TokenEconomizer开发者指南:三步接入新AI Agent,trace、DomainAdapter与Stage接口全讲

原创2026-11-01 17:49:011,620 阅读

TokenEconomizer开发者指南:三步接入新AI Agent,trace、DomainAdapter与Stage接口全讲

TokenEconomizer 是一款面向编码 AI Agent(Claude Code、Codex、Copilot CLI、Pi 等)的黑盒成本控制插件,通过微技能、工具裁剪与失败循环干预三大机制,在不修改 Agent 本体的前提下持续降低会话成本。如果你需要为 TokenEconomizer 接入一个新的 AI Agent,只需围绕 trace、DomainAdapter 和 Stage 三个接口分三步完成,全程只需纯 Python 标准库。

TokenEconomizer 三大成本优化机制与新 Agent 接入示意

先读懂架构:为什么接入一个新 Agent 这么轻

TokenEconomizer 的核心包 tokeneconomizer 有一条铁律:三大机制(microskills、toolprune、loopguard)不认识任何 Agent、任何任务域。所有"特定于某个环境"的知识,只从四个小接口进入:

TokenEconomizer 框架总览:插件读取会话日志并应用三大机制

接口 位置 职责
trace tokeneconomizer/trace/ 唯一读取各 Agent 会话日志的地方
DomainAdapter tokeneconomizer/domain.py 描述任务域:日志怎么读、哪些工具受保护
Stage tokeneconomizer/stage.py 每个机制暴露给调用方的生命周期钩子
ledger / pricing tokeneconomizer/ledger.py 全局统一的成本定义

架构文档 docs/ARCHITECTURE.md 给出了一句关键承诺:"A new agent needs a reader here and nothing else"——新 Agent 只需要一个日志读取器,其余什么都不用改。下面逐步拆解。

第一步:接入会话日志 —— trace 读取器接口

trace 是什么

tokeneconomizer/trace 是唯一"认识"各 Agent 文件格式的模块。每个机制都通过它把一个完成的会话读成统一的有序调用列表,每条形如:

(tool_name, args_dict, result_text, success_bool)
模块 说明
calls.py 核心入口 load_trajectory、tool_usage、call_cwds,按文件格式自动嗅探分发
claude.py Claude Code transcript:调用、用量、子代理、延迟工具
codex.py Codex exec --json 流与 rollout 文件互转、用量解析
copilot.py Copilot CLI 事件日志:调用、用量、MCP 服务器
catalog.py 解析"会话加载了哪些工具",兼容多种日志形态

新 Agent 的两条接入路径

观察 load_trajectory 的实现,load_trajectory 先嗅探文件内容:包含 "type":"item.completed" 走 Codex 解析器,包含 "tool_use" 或 assistant 消息信封走 Claude 解析器,否则按 Copilot 事件读取。据此新 Agent 有两种接法:

  1. 格式转换(推荐,最省事):写一个转换函数,把新 Agent 的会话文件改写成已有格式。先例是 Codex 的 rollout 经 codex_rollout_to_exec 改写为 exec 流、Pi 与 opencode 的会话经 pi_session_to_claude / opencode_session_to_claude 改写为 Claude transcript,之后所有机制"无感"处理;
  2. 新增解析分支:为新格式写一个 xxx_calls(lines) 解析函数返回统一四元组,并在 load_trajectory 的嗅探链里加一个判定分支。

无论哪种路径,还需要补齐 session_usage(用量统计)等函数,让成本账本 ledger 能读到 token 明细。

第二步:声明领域 —— DomainAdapter 接口

DomainAdapter 是一个 @runtime_checkable Protocol(见 domain.py),机制通过它回答"运行环境长什么样"。方法分四组,新手可按组理解:

分组 方法 回答的问题
读会话 load_trajectory / tool_usage / parse_catalog 这个域里的日志怎么读?工具目录从哪来?
工具裁剪 protected_tools / inapplicable_tools / hardcoded_exclusions 哪些工具绝不能裁?哪些按构造就不适用?
循环守卫 spiral_snapshot 一个已完成轨迹的"打转信号"是什么?
微技能 problem_statements / env_vocabulary 判官能看到什么任务文本?用什么词汇表识别解释器与测试命令?

仓库里现成两个对照样本,非常适合作为模板:

  • 插件侧 LiveAdapter:面向"真实仓库 + 真人会话",把 AskUserQuestion、Web 工具等加入保护集(交互场景下人确实会用),env_vocabulary 返回通用的 GENERIC 词汇表并自动探测 package.json / pyproject.toml 标记;
  • 实验侧 SwebenchAdapter:几乎所有读取方法直接委托给 trace(如 return trace.load_trajectory(path)),真正的领域代码只有 problem_statements()——从任务 JSON 读 issue 文本并屏蔽指向 gold 补丁的链接。其他域(Web-Bench、CredData、ReposVul)同样在 experiments/te_bench/adapters/ 中各占一个文件。

💡 经验法则:新 adapter 尽量薄,凡是 trace 已经会的都直接委托,只保留本域独有的 I/O。

第三步:驱动机制 —— Stage 生命周期钩子

Stage 定义了机制围绕一个任务(插件里即一个会话)提供的四个钩子,按固定顺序执行:

顺序 钩子 返回值 用途
1 before_task(task, injected) str 任务前:可扩展注入前缀(微技能说明书)
2 build_tools(task) list / None 启动时:要排除的工具集
3 run_kwargs(task) dict 启动时:传给 Agent 运行器的参数
4 after_task(task, row, run_dir_path, srow) opt_tokens 任务后:更新状态、上报该机制的模型开销

每个机制只实现自己需要的钩子,其余保持无操作默认值。仓库中的三个实现分别是微技能的 PrefixStage、工具裁剪的 ToolingStage 和实验侧的 SpiralStage(循环守卫)。

实验/基准场景下,Economizer 门面 把三个 Stage 和 adapter 组装到一起,每个任务只需按序调用:

injected      = econ.injection_prefix(task)   # 学到的仓库说明书
exclude_tools = econ.build_tools(task, i)     # 工具排除集
run_kwargs    = econ.run_kwargs(task)         # 循环守卫参数
... 用 AgentRunner 执行任务 ...
opt_tokens    = econ.after_task(task, row, run_dir_path, srow)

注意门面只向 AgentRunner 协议要两样能力:一次"优化器"小模型调用(optimizer_call)和(可选的)任务执行器(run_task)。它从不自己启动 Docker 或调用 LLM API——这正是"黑盒"的含义:经济器对执行 harness 完全无知。

插件(真人会话)场景下,Stage 由 hooks 驱动:会话结束时在 plugin/fold.py 中以 LiveAdapter 运行 PrefixStage 与 ToolingStage,循环守卫则逐工具调用地运行;各 Agent 的钩子 payload 差异(prompt_id vs turn_id、日志位置、消息展示方式)集中在 plugin/hosts.py 的 Host 子类里,新 Agent 通常只需在此登记一个 Host 并加入 HOSTS 字典。若目标 Agent 没有 hook 协议(如 Pi、opencode),可参照 plugin/pi/tokeneconomizer.ts 用 TS 扩展代为转述 Claude 形状的 payload。

验证与边界:两个"绝不"必须守住

接入完成后,用离线测试验证包边界——tests/test_plugin_package.py 固化了两条单向依赖规则:

  • 机制包(microskills / toolprune / loopguard / trace)绝不 import tokeneconomizer.plugin;
  • tokeneconomizer/ 下绝不 import experiments/(实验侧 harness 是兄弟包,且被排除出分发包)。

只要新 Agent 的代码落在 trace 读取器 + Host 登记 + 可选 adapter 这三处,边界天然成立。运行 python -m pytest tests 即可全量回归。

TokenEconomizer 在 SWE-Bench 等基准上的实测成本与成功率结果

为什么值得:接入后的实测收益

接入的价值可以用论文数据说话:在 277 个 SWE-Bench 任务上,五种 Agent–模型组合的平均成本下降 18.4%–30.9%,全部 30 个"仓库×组合"格子均更便宜,Pass@1 在 4/5 组合中不降反升;节省在 Web-Bench(16–21%)和两个安全审计基准(6–20%)上同样成立。也就是说,你接的每一个新 Agent,都能直接摊到这套已验证的收益曲线上。

关键文件速查

想做什么 看哪里
新增 Agent 日志读取器 tokeneconomizer/trace/(对照 pi.py 的转换先例)
登记新 Agent 的钩子差异 tokeneconomizer/plugin/hosts.py
编写新任务域 adapter experiments/te_bench/adapters/swebench.py 模板
组装三大 Stage experiments/te_bench/facade.py
理解整体装配关系 docs/ARCHITECTURE.md、docs/PLUGIN.md

三步走完后,新的 AI Agent 就与 TokenEconomizer 的三大机制无缝打通:日志进得来(trace)、领域说得清(DomainAdapter)、生命周期钩得上(Stage)——而机制本身一行不用改。

登录后查看全文
TokenEconomizer