TokenEconomizer开发者指南:三步接入新AI Agent,trace、DomainAdapter与Stage接口全讲
TokenEconomizer开发者指南:三步接入新AI Agent,trace、DomainAdapter与Stage接口全讲
TokenEconomizer 是一款面向编码 AI Agent(Claude Code、Codex、Copilot CLI、Pi 等)的黑盒成本控制插件,通过微技能、工具裁剪与失败循环干预三大机制,在不修改 Agent 本体的前提下持续降低会话成本。如果你需要为 TokenEconomizer 接入一个新的 AI Agent,只需围绕 trace、DomainAdapter 和 Stage 三个接口分三步完成,全程只需纯 Python 标准库。
先读懂架构:为什么接入一个新 Agent 这么轻
TokenEconomizer 的核心包 tokeneconomizer 有一条铁律:三大机制(microskills、toolprune、loopguard)不认识任何 Agent、任何任务域。所有"特定于某个环境"的知识,只从四个小接口进入:
| 接口 | 位置 | 职责 |
|---|---|---|
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 有两种接法:
- 格式转换(推荐,最省事):写一个转换函数,把新 Agent 的会话文件改写成已有格式。先例是 Codex 的 rollout 经
codex_rollout_to_exec改写为 exec 流、Pi 与 opencode 的会话经pi_session_to_claude/opencode_session_to_claude改写为 Claude transcript,之后所有机制"无感"处理; - 新增解析分支:为新格式写一个
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)绝不 importtokeneconomizer.plugin; tokeneconomizer/下绝不 importexperiments/(实验侧 harness 是兄弟包,且被排除出分发包)。
只要新 Agent 的代码落在 trace 读取器 + Host 登记 + 可选 adapter 这三处,边界天然成立。运行 python -m pytest tests 即可全量回归。
为什么值得:接入后的实测收益
接入的价值可以用论文数据说话:在 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)——而机制本身一行不用改。


