TokenEconomizer：给编码 Agent 装上"成本记性"的开源插件

一、先说一个真实痛点

如果你每天在同一个仓库里用 Claude Code 或 Codex 敲代码，你多半经历过这种场景：agent 每次开工都要重新摸索——"这个项目的测试到底怎么跑？""环境变量怎么设？""生成的文件放哪？"然后它把二十多个工具定义塞进每一次请求里，其中一半你这辈子都不会用。更糟的是，当它卡住时，会用同一种错误方式反复撞墙几十次，直到你自己按 Esc。

这些重复消耗的 token，本质上是每个会话都在重新交一次学费。微软研究院与加州大学伯克利分校的团队把这笔"重复学费"量化了出来：在 277 个 SWE-Bench 任务上，一个普通开发者反复使用的 agent，单会话成本中有相当一部分是纯粹的浪费。

TokenEconomizer（microsoft/TokenEconomizer）给出的答案很直接：既然 agent 是黑盒，就从外面学。 它不碰模型权重、不改 agent 代码、不要求你换工作流，只是一个插件——挂在你的编码代理上，读取历史会话日志，把学到的经验回灌给后续会话。

图：TokenEconomizer 的三种机制与五种宿主 Agent，来源官方仓库 docs/assets

二、它到底怎么省下钱

官方论文（arXiv:2610.22732）把省下来的钱拆成三堆，对应三种机制：

微技能（Micro-skills）——记住这个仓库怎么跑。 它从两个来源采集事实：跨会话重复出现的失败，以及一个每 k=3 个会话复盘一次的模型提议器。事实需要三个会话确认后才在会话开头注入，被后续会话证伪就丢弃。典型产物就是一行"测试用 python -m pytest 而不是 pytest"。

工具裁剪（Tool pruning）——别再加载用不上的工具。 工具定义的 schema 每次请求都要重发一遍。一个工具若在跨 m=2 个会话的 p=10 次提示中从未被调用（或连续 s=5 个会话完全没用），就写进该 Agent 的拒绝清单，下次会话直接不加载。一条命令就能还回去。

失败循环干预（Loop guard）——卡住时拉一把。 一个裁判模型判断当前回合是否卡死，置信度超过 c=0.7 才插话，每回合最多 r=1 次 redirect。它从不主动停止回合，只告诉你"这回合看着还卡着（judge-stuck@0.82, 46 tool calls），按 Esc 中断"。

图：插件保持对仓库的认知，在不改动 agent 的前提下应用三种机制；每个会话结束后回写全部三项

三、类比：给 agent 配一个"老员工"

把它想象成一个新来的实习生。你不换人，也不改他的工作方法，但你给他一份"这个项目交接手册"：测试怎么跑、哪些目录是自动生成的、哪些工具这个仓库根本用不上。前两次他还会犯错，第三次你就在他开工前把要点递过去了。这就是微技能。而工具裁剪相当于你告诉他"这个仓库没有前端，你不用每次都打开浏览器工具"。失败循环干预则是有人坐在旁边看，发现他同一个坑掉三次就提醒一句"换个思路"——但最终拍板还是你。

四、实测数据与对比

图：SWE-Bench 上五种 agent-模型组合的成本与 Pass@1 变化

在 277 个 SWE-Bench 任务、6 个仓库、5 种 agent-模型组合下：

组合	平均成本变化	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

30 个"仓库 × 组合"单元格里成本全部下降，5 个组合中 4 个 Pass@1 不降反升。Web-Bench 上省 16–21%，两个每次都是全新仓库的安全审计基准上省 6–20%。

横向对比更值得看：官方给出的对照表里，RTK 平均成本变化在 -8.9% 到 +4.5% 之间，aider RepoMap 在 -6.1% 到 +6.5% 之间——也就是说，这两者的收益不稳定，甚至可能是负的。TokenEconomizer 的 30/30 全绿是它最大的差异化。另有媒体提到，把推理强度调低同样能省钱，但那会让 Pass@1 掉 1.8 到 10.3 个点——这是拿成功率换成本，与本项目"守任务成功率"的第四原则相悖。

五、上手门槛：比想象的低，但不是零

不需要 API Key。 插件的模型调用（事实提议器、裁判及其 redirect）全部走你自己的 agent，用你原本的套餐或登录，费用也计入它的报表。它从不接触凭据。

只需要 Python 3.10+ 和一个编码 Agent。 安装就是 git clone 加一行插件安装命令，Claude Code / Codex / Copilot CLI / Pi 各有各的语法：

git clone https://github.com/microsoft/TokenEconomizer.git
claude plugin marketplace add "$PWD/TokenEconomizer"
claude plugin install tokeneconomizer@tokeneconomizer

然后在仓库里跑 /tokeneconomizer:status 看状态。日常命令各家统一：status（学到了什么、花了多少）、microskills（注入了哪些事实）、toolprune（裁掉了哪些工具）、config set microskills=on（开关机制）。

学到的数据全在本机 ~/.tokeneconomizer，不上传。

版本窗口偏窄，这是真实门槛：Claude Code 需 2.1.300–2.1.310，Codex 需 0.153.1–0.164.0，Copilot CLI 需 1.0.83–1.0.102，Pi 需 1.2.0–1.3.0。Cursor Agent 与 opencode 属于实验性支持，Cursor 还在 macOS/Linux 限定（Windows 下 hook 走 PowerShell，而启动器是 POSIX shell 脚本）。

默认配置有个反直觉点：工具裁剪和 loop guard 默认开启，微技能默认关闭——因为提议器要额外花模型调用，收益取决于仓库和你的工作方式。想省最多就 /tokeneconomizer:config set microskills=on；只想观察不动手就用 toolprune=propose 模式。

六、争议与局限

最值得警惕的一点：省下来的钱是从失败任务里挤出来的。 有分析指出，总开销中约 32% 花在了 17% 的失败任务上。也就是说，TokenEconomizer 的收益有相当部分来自"让失败的尝试少烧点 token"，而非"让成功的任务更高效"。如果你的工作负载里失败任务占比很高，这个数字会好看得失真。

仓库之间收益极不均衡。 在 Django 上三种机制都降本，在 SymPy 上反而全部升高。原因是工具裁剪的前提是"这个仓库真的不用某些工具"，而像 SymPy 这种工具密集型项目恰恰相反，裁掉就出事。

Opus 4.8 组合出现了 -1.0 的 Pass@1 回落，说明在最强模型上减少工具和上下文会影响任务成功率。五个组合里只有这一个是负的，样本还不足以判定是噪声还是系统性现象。

版本兼容是持续负担。 插件依赖各家 hook 事件的私有行为（Cursor 的 transcript 格式与 per-session token 用量就不是公开接口，导致 Cursor 下会话成本直接显示为 unavailable）。Agent 一升级就得等插件跟进。

没有 Dockerfile、没有 docker-compose、没有 Web UI。 它不是一个能独立启动的服务，而是必须依附宿主 agent 生命周期的插件层——这决定了它的部署形态只能是"装到你的机器上"。

七、行业意义

TokenEconomizer 指向一个正在成形的方向：编码 agent 的下一个竞争维度不是"更聪明"，而是"更省"。 当各家模型能力趋同、上下文窗口越来越大、价格战持续压低单 token 成本时，真正的差异化开始转移到"如何让同一份能力在重复使用中不被浪费"。

它的方法论也很值得借鉴——黑盒 + 跨会话记忆。不改被控系统，而是从外部观测其行为、积累环境特定的经验、在下一次交互时回灌。这个范式完全可以迁移到 agent 评测、CI 自动化、数据清洗流水线等任何"同一工具被反复调用"的场景。arXiv 论文把它定义为"Experience-Driven Black-Box Cost Control"，经验驱动的黑盒成本控制，这个框架比代码本身更值钱。

值得一提的是项目本身的工程纪律：主包 tokeneconomizer/ 只用标准库，零安装依赖，import tokeneconomizer 在任何 Python 3.10+ 上都能跑；27 个测试文件、约 98 次提交、16 位贡献者，Apache-2.0 协议，代码与论文同步开源。微软研究院 + 微软安全 + 伯克利三方联合署名，学术界与工业界在同一份代码上对齐，这在 agent 工具链里并不常见。

如果你每天在同一个仓库里跟 agent 打交道，值得花十分钟装上试试——先开 toolprune 和 loopguard（默认就有），跑几个会话后用 status 看看账单，再决定要不要打开微技能。