基准测试

落地页上的数字来自一项脚本化 agent 基准。本页记录测量协议、结果，以及这些数据能——和不能——支撑的结论。

协议

• 驱动器： pi 编程代理，端到端运行每个脚本化任务，token 经 OpenRouter 计费。
• 任务： 面向真实仓库的四个真实任务——三个 51–96 KB 的源码文件，加一份 1,914 行的构建日志。
• 实验组：
  • base — agent 内置的 read + bash 工具。
  • cliskill — 通过 agent skill 驱动的 ctxctl（CLI 调用）。
  • mcp — 作为五个原生 MCP 工具暴露的 ctxctl（ctxctl_outline、ctxctl_symbol、 ctxctl_read、ctxctl_deps、ctxctl_exec）。
• 模型： deepseek-v4-flash，经 OpenRouter，每组单次运行。

结果

指标	结果
原生 ctxctl mcp 工具对比内置 read/bash —— 会话成本	−33%
同一基准 —— 未缓存（全额计费）输入 token	−31%
通过 ctxctl exec 分析构建日志	成本 −84%
通过 outline/symbol 切片探索 96 KB 文件	未缓存输入 −86%
文件 outline 对比整文件读取	小 91–95%

基线本身就很重要：节省是在一个已经相当激进的 provider 前缀缓存之上测得的，所以 −33% 的 会话成本降幅其实低估了 ctxctl 砍掉的新计费输入量。

工具调用可靠性

成本节省只是故事的一半。出错的 MCP 调用曾一度不可见（最初的桥接层丢弃了服务端错误标志）， 因此我们为驱动器加入了错误计数与分类，并随着 ctxctl 的演进在相同的三个源码理解场景上反复重跑：

运行	二进制	调用数	出错调用	错误率
8 月 23 日基线	0.3.1	111	9	8.11%（被低估）
插桩重跑	0.3.2	134	25	18.66%
自愈重跑	0.3.3	130	21	16.15%

占主导的失败类别是 symbol-not-found——agent 向符号查询请求一个文件里不存在的名字。 在自愈符号错误之后，该类别从 ×20（v0.3.2） 降到 ×9（v0.3.3）：miss 现在返回排序后的相似符号列表和内嵌的文件迷你 outline，agent 可以在 一次往返内重新瞄准。v0.3.3 运行中每一次 miss 都携带迷你 outline，两次跟随建议的重试全部 成功恢复——而 v0.3.2 下是零比二，当时的建议甚至会指向刚刚试过的那个名字。

测量诚实性：8 月 23 日的数字来自一个隐藏错误的桥接层——某个场景里六次 symbol-not-found 失败以纯文本返回，任何指标都无法看到，所以 8.11% 低估了真实基线。另外每组都是单次运行且 agent 轨迹不固定，逐场景波动（如 graphology：v0.3.2 为 21 次调用，v0.3.3 为 10 次）属于方差， 不是回归或改进。确定无疑的是错误负载本身，以及建议重试能否解析成功。

逐场景表格、方法与有效性威胁：完整报告见 v0.3.2 插桩运行 与 v0.3.3 自愈运行。

发现

• 原生工具解决采用门槛。 把 ctxctl 暴露为原生 MCP 工具，消除了 skill 驱动 CLI 用法的摩擦，并带来最大的会话成本降幅。
• exec 压缩是最不受条件影响的收益（所有模型均 ~80%+）。构建日志任务落在 −84% 成本。
• 文件探索随文件体积放大。 在 96 KB 夹具上，outline/symbol 切片把未缓存输入最多削减 −86%。
• 节省幅度与 provider 前缀缓存质量成反比。 provider 缓存激进的模型仍能削减未缓存输入；弱缓存模型（solar-pro4）节省了 47% 会话成本。
• exec 里没有 shell。 exec 按 shell 分词方式拆分命令而不经过交互式 shell，因此管道和重定向需要显式的 sh -c 包裹——v0.3.1 起未加引号的 shell 元字符会直接快速报错并给出该提示。

注意事项

请谨慎解读这些百分比：

• 各实验组均为单次运行。把这些数字当作方向性证据，而不是精确值。
• 节省取决于 provider 的前缀缓存质量；缓存很强的实验组即使未缓存输入仍然下降，相对成本收益也会缩水。
• token 计数使用 cl100k_base BPE 分词器作为跨 provider 的近似。
• 基准脚本尚未发布；我们计划发布它们以保证可复现性。