OPEN SOURCE DEEP DIVE
TokenEconomizer:编码智能体的跨会话成本控制插件
通过跨会话微技能、工具裁剪和失败循环干预,在不更换模型的前提下降低编码智能体重复成本。
项目定位:把跨会话复用变成可计量的成本控制器
TokenEconomizer 是面向编码智能体的开源成本控制插件。它不替换模型,不修改权重,也不要求智能体采用新的工作接口,而是在 Claude Code、Codex、GitHub Copilot CLI、Pi 等工具已有的会话生命周期中读取日志、写入少量上下文,并通过各智能体自己的设置文件调整工具暴露范围。它要解决的不是单次回答是否足够聪明,而是同一个开发者反复在同一个仓库工作时,为什么会持续为相同事实、相同工具定义和相似失败回路重复付费。
项目采用黑盒思路:模型与智能体代码保持不变,学习状态保存在本机 ~/.tokeneconomizer 中。插件需要调用模型时,使用用户已经登录的智能体及其套餐,不要求额外的 API Key,也不接触用户凭据。它把优化目标放在仓库的长期使用上,而不是要求一次会话立刻回收成本。
成本从哪里产生
编码智能体的请求会反复携带系统指令、工具定义和已有对话。随着会话推进,大量上下文会从缓存中再次读取;如果只看原始 token 总数,就会把廉价缓存命中与昂贵输出 token 按同一价格比较,得出失真的结论。TokenEconomizer 从三类常见浪费入手:在后续会话中重新发现仓库命令与环境事实,持续加载从未被使用的工具,以及在失败信号已经重复后继续沿着同一条路径尝试。
| 机制 | 学习信号 | 执行方式 | 安全边界 |
|---|---|---|---|
| 微技能 | 跨会话重复出现的失败与仓库事实 | 会话开始时注入短事实 | 多个会话确认,矛盾后撤回;插件默认关闭 |
| 工具裁剪 | 工具已加载但长期未使用 | 通过智能体设置文件写入门禁清单 | 受保护工具和曾经用过的工具不会被删除 |
| 循环干预 | 重复失败、错误累积和异常拉长的回合 | 向上下文加入改道提示,并通知用户 | 不主动终止回合,最终停止权留给用户 |
微技能:用证据把仓库经验带到下一次会话
微技能保存的是短小、可执行、与当前仓库有关的事实,例如测试必须先运行某个构建步骤,或者这里必须使用 python -m pytest 而不是直接运行 pytest。事实有两个来源:一是跨会话重复出现的失败,二是可选的模型提案器定期审阅近期会话。提案器默认每隔三次会话运行一次,但整个微技能机制默认关闭,因为提案会产生真实模型调用,而且注入内容来自仓库命令输出,用户需要自行判断是否信任该仓库。
一条事实只有在三个会话确认后才进入注入层。后续会话如果给出反证,该事实会被撤回。由此,微技能不是把某次偶然命令写死成规则,而是把“这个仓库里反复成立的环境知识”变成可审计、可撤销的短期记忆。对于只希望零模型调用地学习环境失败的用户,可以使用只依赖重复失败的自由层。
工具裁剪:让工具定义也有证据门槛
工具裁剪关注的是另一类固定开销:每次请求都会发送当前加载工具的定义。一个工具从未在当前仓库被调用,并不意味着可以立刻删除;单次任务可能恰好不需要它。项目因此设置了两个并列门槛:工具至少在两次会话中的十个提示内持续未使用,或者在连续五个会话中始终未使用。只有达到门槛后,它才进入裁剪候选。
裁剪不会碰受保护的工作面工具,也不会删除曾经成功使用过的工具。写入动作还要等待仓库会话空闲约六十分钟,最迟在候选形成一天后执行。这个延迟不是保守过头的装饰,而是避免在提示缓存仍热时改变工具前缀,导致恢复会话不得不重新写入整段历史缓存。不同宿主能表达的裁剪粒度也不同:Claude Code 删除单个工具,Codex 调整能力包,Copilot CLI 处理整个 MCP 服务器;Pi、Cursor、Grok、opencode、Hermes、Antigravity 和 Droid 目前没有同等的持久裁剪入口。
所有修改只添加插件自己的条目,不覆盖用户已经写好的拒绝规则。插件创建或修改的设置文件会避开版本控制,并在不安全的情况下保留为待执行的提案。用户随时可以恢复工具;被人工恢复的工具不会再次被自动删除。
循环干预:识别失败回路,但把停止权留给用户
循环干预以单个提示回合为单位观察智能体行为。它先等待当前仓库至少五个正常结束、最后一次编辑后没有失败检查的回合,用这些回合建立“通常需要多长、编辑与错误如何变化”的包络。之后,如果相同的失败反复出现或错误持续累积,系统才把轨迹交给判断模型。判断模型至少有 0.7 的置信度认为回合已经卡住时,智能体会收到一次简短改道提示,默认每个回合最多一次。
还有一个不依赖判断模型的后备规则:当回合运行到通常长度的 2.5 倍,同时仍在重复编辑和失败时,可以直接触发改道。即使改道后仍然卡住,插件也只会显示一行提示,告诉用户当前智能体应该怎样停止回合。它不会替用户中止进程,因为交互环境里的“看起来停滞”仍可能包含尚未显现的有效进展。
成本账本:缓存命中与插件开销进入同一个分母
项目的账本把会话执行成本与插件自身调用成本相加,再折算成“新鲜输入 token 等价量”。缓存读取、缓存写入和输出 token 按具体计费模型的价格比例加权,而不是把每类 token 都当作全价输入。实验路径遇到未知模型价格时直接失败,避免静默产生错误比较;实际插件路径则记录一条带标记的回退价格,保证用户会话仍能被记账。
这一点决定了它如何判断“节省”:工具裁剪减少了缓存上下文,但如果报告仍按原始 token 总数计算,就会夸大收益;微技能或循环判断增加了输出与新鲜输入,也必须计入同一账本。只有优化后的执行成本减去新增机制成本仍然更低,方案才算真正有效。
架构边界:机制不依赖具体智能体或任务域
核心包只使用 Python 标准库,并把变化点压缩成几个窄接口。轨迹读取层负责把各智能体的日志规范为统一会话;领域适配器描述当前任务需要保护或排除哪些工具、如何识别循环信号、使用什么微技能词表;阶段接口把机制挂到任务前、构建工具、运行参数和任务后等生命周期。账本与定价模块同时服务于线上插件和实验框架,避免两套统计口径漂移。
因此,新增智能体主要是在轨迹读取和宿主适配层补支持,而不是复制三个机制。新增任务领域也只需实现领域适配器。这个边界使插件能够同时覆盖交互式编码会话和基准测试流,同时让核心机制继续与 Claude、Codex 或 Copilot 的具体事件格式解耦。
实验证据:五组组合、三十个仓库单元全部降本
论文在六个仓库的同一批 277 个 SWE-Bench 任务上测试了五组智能体与模型组合。每个任务作为独立会话运行,同一仓库的任务按顺序执行,并从零学习开始。成本包含 TokenEconomizer 产生的全部模型调用。在每组仓库与组合构成的三十个单元中,优化后的平均成本都低于默认配置,组合层面的平均降幅为 18.4% 至 30.9%。
| 智能体与模型 | 平均成本变化 | Pass@1 变化 |
|---|---|---|
| Claude Code / Sonnet 5 | 降低 23.6% | 提高 1.3 个百分点 |
| Claude Code / Opus 4.8 | 降低 30.9% | 下降 1.0 个百分点 |
| Codex / GPT-5.6 Terra | 降低 24.7% | 提高 0.9 个百分点 |
| Codex / GPT-5.6 Sol | 降低 26.1% | 提高 1.6 个百分点 |
| Copilot CLI / Sonnet 5 | 降低 18.4% | 提高 2.6 个百分点 |
五组组合中有四组同时提高 Pass@1,Opus 4.8 组则出现成本大幅下降但正确率下降 1.0 个百分点的权衡。Web-Bench 上成本降低 16% 至 21%;两个安全审计基准的每个任务都在新仓库中运行,仍取得 6% 至 20% 的降低,说明收益不只来自单一仓库内的事实复用。论文还报告了每个仓库内 5% 至 40% 的成本变化范围。这些是受控基准结果,不应直接外推为任意生产仓库的固定节省比例。
安装、支持范围与运行方式
运行要求是 Python 3.10 或更新版本,以及一个已经登录的受支持智能体。主要支持范围包括 Claude Code、Codex、GitHub Copilot CLI 和 Pi。opencode、Cursor Agent、Grok Build、Hermes Agent、Antigravity CLI 与 Factory Droid 属于实验性支持,可用机制各不相同。安装后,用户可以在智能体内查看状态、列出已学习事实、检查工具裁剪证据、恢复工具和修改配置;在终端中运行这些命令不需要额外模型回合。
项目把权限和可逆性放在默认路径里。工具裁剪和循环干预默认开启,微技能默认关闭。插件自身调用失败时采用失败开放策略,会话继续运行,不会因为成本控制器本身出错而阻断主要工作。会话折叠和循环判断等工作也会尽量移出关键路径。
适用边界
TokenEconomizer 最适合反复使用同一仓库、工作流相对稳定且会话成本可观测的编码团队。收益需要跨会话积累,单次任务或频繁更换工作目录的使用方式很难体现仓库级学习。对于不可信仓库,应保持微技能关闭,或只使用不调用模型的自由层,因为注入事实来自仓库控制的命令输出。对希望统一管理所有智能体工具的企业,它也不能替代宿主本身缺失的持久权限接口。
项目真正的工程价值不只在于三个降本技巧,而在于把它们放进同一套可审计账本、可逆操作和跨宿主边界中。它让“智能体是否从过去工作中学到了有用经验”成为可以观察、计量和回滚的工程问题,而不是依赖一次会话内的即兴优化。