Codemode(用代码调工具,而不是逐个 tool call)调研笔记

By 陈成 · Published October 29, 2026 · Updated November 3, 2026

Codemode 是什么、省在哪里、对 harness 设计意味着什么?

2026-10-28 · 来源:X 书签 + X 搜索 + Reddit + HN + 相关博客 · 目标:给 qodercli 的 harness 设计做决策参考 2026-10-30 更新:加入 Manoj Mahalingam 的三家对比、小实验和崩溃测试(第 7 节) 2026-11-03 更新:加入 Phil Schmid《Why Agents Are Soon Only Going to Have 1 Tool》、Factory Droid 的数据和推上关于"脚本跑到一半失败"的讨论

TL;DR


1. 演进脉络

timeline
    title Codemode 时间线
    2025-09 : Cloudflare "Code Mode - the better way to use MCP"(Kenton Varda, Sunil Pai): MCP 工具转成 TS API,在 Worker isolate 里执行
    2025-11 : Anthropic "Code execution with MCP":150k → 2k token(-98.7%)
    2026-02 : Cloudflare 全量 API MCP:只有 search()+execute() 两个工具,约 1k token 覆盖约 2500 个端点
    2026-05 : michaellivs "Ergonomic coding surfaces";pi-dynamic-workflows(subagent 的 code mode)
    2026-07/08 : Codex 原生 exec(codemode);opencode2 内置 tool search + codemode;pi-subagents code mode
    2026-09 : geoqiao 实验 -75% token;Pi v0.99 内置 codemode(QuickJS)+ MCP;Earendil "You Said No MCP!"
    2026-10 : Pi 1.0 codemode prompt -40%;mitsuhiko "What is Codemode";Manoj 崩溃测试 Pi Durable 的脚本重放;Factory Droid 1.0 默认 Script mode
    2026-11 : Phil Schmid "Why Agents Are Soon Only Going to Have 1 Tool":预测 MCP 借 outputSchema 在 2027 回潮

有人吐槽(@LanLance24):最近 Pi 和 OpenCode 写的 codemode 内容,Cloudflare 去年基本都讲过,现在才火起来,大概是因为模型能力跟上了,而且实验室开始专门训练这个格式。

2. 机制:省在哪里

sequenceDiagram
    autonumber
    participant M as 模型
    participant H as Harness
    participant T as 工具/MCP
    rect rgb(255,235,235)
    note over M,T: 传统 tool call:每一步都回模型(每次都带全量历史)
    M->>H: tool_call list_issues
    H->>T: 执行
    T-->>H: 250 条 issue(大结果)
    H-->>M: 全部塞进上下文
    M->>H: tool_call list_comments(#1)
    H-->>M: 结果
    note over M: ……重复 N 次,每次都重读历史
    end
    rect rgb(230,245,230)
    note over M,T: Codemode:一段脚本,一次往返
    M->>H: codemode { JS: 循环 / Promise.all / filter }
    loop 在沙箱内
        H->>T: tools.mcp__linear__list_comments(...)
        T-->>H: 结构化结果(不进上下文)
    end
    H-->>M: 只返回汇总结果(可 store() 存进 transcript)
    end

几个关键点:

点 说明
省的是往返 geoqiao:40% 是请求次数,每次请求带全量历史,所以和总 token 口径接近;因为多数命中缓存,费用降幅略低
中间结果不进上下文 大输出在 JS 里过滤/聚合,模型只看结论。Pi 里普通 bash 只把末尾 2000 行塞给模型,走 codemode 时拿到的是完整结构化输出
并发 Promise.all 自然表达并行;Pi 限制总并发 4,其余排队
状态 store() 把数据写进 session transcript,下一次 codemode 用 load() 读回,不用重新拉。脚本成功才会保存,脚本中途死掉,已完成的调用结果不会留下
常见用法 先探 5-10 条看数据形状,再写脚本批处理剩下 n 条(mitsuhiko 观察到的模型行为)

3. mitsuhiko 的核心论点:brain vs hands

flowchart LR
    subgraph Brain["Harness(brain,可信)"]
        LLM[模型] --> CM["codemode 沙箱<br/>QuickJS/WASM<br/>无网络/无FS/无timer/限内存"]
        CM -->|tools.*| HT[harness 工具: read / view_image / subagent]
        CM -->|tools.mcp__*| MCP[MCP servers]
        CM -->|models.*| AI[classify / generateImages]
        CM -->|store| TR[(session transcript)]
    end
    subgraph Hands["执行环境(hands,不可信/沙箱)"]
        B[bash / 文件系统]
    end
    HT --> B
    CM -->|tools.bash| B

MCP 的问题(mitsuhiko 列的"MCP Desires"):

  1. 需要 structured content / outputSchema,很多 server 只回文本
  2. 结果要一致:有的 server 按结果条数做 token 优化,导致探 5 条时成功、拿满批次时失败
  3. 不支持大二进制
  4. 没有跨多个 server 的 tool search 机制
  5. "Codemode 套 Codemode":Cloudflare 的 MCP 自己就是 codemode,在 Pi 里用就成了 JS 里套 JS 字符串,双重转义,内层也调不到外层工具

4. 证据与数据

来源 场景 结果 注意
geoqiao 文章 Pi + GPT 6 Astra,长流程前端主题任务,exec+wait 两个工具(pi-codex-conversion) 累计 token −75%,费用 −64% 单次实验。原生 Pi 129 次响应,Codex 40 次;差额约 99% 是 cache read
geoqiao 后续 日常 Claude Max 使用 请求数 −40%+,成本 −30%+("5X 秒变 10X") Codex 原生就是 codemode,再开收益不明显
Pi 1.0 changelog codemode 提示本身 GPT-5.6 默认工具请求 ~5300 → ~3300 token(−40%) models API 改为按需加载
Reddit r/PiCodingAgent(96 runs) 6 个一行 bug +21% token 工具描述约 3k token 每轮都带,小任务里用不上
同上 60 次只能经由工具查的大数据 lookup −40% token、费用减半、7 vs 64 次往返 作者 149 个会话里这种场景只出现过 1 次
Reddit 另一帖 一天日常使用 总 token 和上下文 −15~20% 小样本
Cloudflare 全量 Cloudflare API 1.17M → ~1k token(−99.9%) 省的是 schema,不是往返
Anthropic MCP code execution 150k → 2k token(−98.7%) 同上
Angie Jones(goose) 大量真实任务 token、消息、LLM 调用都减半 —
Databricks / Maka TB2.1(geoqiao 文章引用) harness 横评 Pi 更便宜;但 Codex 多过 7 题 geoqiao 推测短任务里还要多写一次 JS,codemode 没优势
Factory Droid 1.0(Phil Schmid 文章引用,Factory 自报) Terminal-Bench 4,同模型跨 harness 对比,Factory 叫 Script mode 准确率 +3.5 分,模型花费 −15% 只公布差值,没有绝对分数,未见独立复现
Manoj,Pi coding agent 1.4.0 gpt-6.1-sol,本地 MCP(2 个工具)按标签汇总 vite issue,中位数 总输入 21,524 → 17,756(−17.5%),回给模型的工具输出 26,820 → 4,374 字节(−84%),Pi 记录的费用 $0.037 → $0.021 一个任务、几次运行,作者自己说不算 benchmark。耗时基本不变(23.3s → 22.8s),首个 prompt 从 1,483 涨到 1,996 token
Manoj,OpenCode v2.1.4 同上 未缓存输入 −28%,输出 −42%,但总输入 30,436 → 35,755(+17.5%) 每次都把完整列表返回给模型,多数运行还手抄 id 进下一个脚本;工具定义更大,每步都从缓存重读。首个 prompt 从 3,305 涨到 4,650 token

结论:收益和"任务中往返次数 × 每次结果大小"成正比。长流程、工具密集、大结果的任务收益明显;小修小改是净亏损(多出来的工具描述每轮都要付钱)。Manoj 的对比还多说明一点:同一个任务、同一个模型,Pi 省了,OpenCode 反而多花,差别在中间数据有没有回到模型。开了 codemode 不等于省。

5. 社区争论

支持方

反对 / 质疑

michaellivs 的折中框架(我认为最有用的一条):

能力少 能力多
高频 直接 tool 热路径用 tool,长尾用 codemode
低频 都行,默认 tool codemode(唯一可行)

tool 的成本是 O(工具数 × 轮数),codemode 的成本是 O(推理次数 × 新命名空间数)。tool 第一次就调对的概率高,codemode 要先发现再调用。

6. 各家实现对比

Pi 1.0 Codex opencode2 Cloudflare qodercli(现状)
入口工具 codemode exec(freeform 自定义工具)+ wait execute MCP server 端 search + execute 无通用入口;workflows 只编排 agent
运行时 QuickJS/WASM V8 自研解释器,只支持部分 JS 语法,其余报 UnsupportedSyntax Dynamic Worker isolate node:vm(workflow-sandbox.ts)
工具暴露模式 direct / model-only / codemode / deferred / hidden codemode-only 是 GPT-6 的 MCP 默认 MCP 默认进 codemode — MCP 有 lazy 模式(mcp_list/get/call)
发现 tool_search 按需声明;脚本内 searchTools() 按模型能力判断是否开启 tool search 内置;脚本内 search(...) search() 跑 JS 查 OpenAPI mcp_list / mcp_get
额外能力 models.classify/generateImages、store()/load()、image()、嵌套调用记录在 nestedCalls — 脚本里按 tools.<server>.<tool>() 调用;OpenCode 额外注入 fetch,脚本可直接请求网址 — agent()/parallel()/pipeline()/phase()/log()、journal、script cache
默认开启 配置了 MCP 时,或 defaultTools: ["+codemode"] 模型声明支持时(不支持的 provider 报 "does not advertise Code Mode support") 是(MCP 工具;codemode: false 可改回直接暴露) — —
崩溃重启后 脚本丢失,模型从头重跑,所有调用再跑一遍(用 @earendil-works/pi-durable/codemode 扩展可恢复,见第 7 节) — 同 Pi,脚本丢失后全部重跑 — Workflow 有前缀缓存,需显式 resumeFromRunId

Factory Droid 1.0 也默认走 codemode(叫 Script mode);Pydantic AI、LangChain、Cloudflare Agents SDK 有类似支持。Phil Schmid 文章里的两个设计值得参考:工具 schema 编译成 declare namespace tools { ... } 的 TS 声明,比 JSON Schema 紧凑;工具太多时在沙箱里放一个全局 ALL_TOOLS,让模型用代码筛,相当于把 tool search 搬进脚本。返回模型的内容只经 text()/image()/audio(),和 Pi 的 image()、store()/load() 是同一套思路。

Reddit 上有人说 Pi 的 MCP/codemode 实现几乎照搬 Codex(模式名称都一样)。Codex 的 exec 是 freeform 自定义工具,DeepSeek 这类只支持 function calling 的 provider 用不了(openai/codex#37825 提议加一个 function-backed 的 exec { code: string })。

7. 脚本跑到一半进程死了

Manoj Mahalingam 在 Pi coding agent 和 OpenCode 里各 kill 掉一个跑到一半的脚本:两边都把中断的调用标成失败,模型从头重跑,已经拿到结果的查询也再查一遍。Pi Durable(实验状态)能接着跑。它的整体设计见 Pi Durable 调研,这里只记脚本这部分。

Pi Durable 不保存脚本的栈,重启后从头运行同一段脚本,靠下面几条保证走同一条路:

崩溃测试用 pi-durable 1.4.0,模型是每次返回相同脚本的假模型,中间加一层代理保证 kill 时服务端已经处理完在途调用,然后 SIGKILL,换新进程打开同一个 SQLite 文件恢复:

场景 replay 已完成调用被重发 服务端重复调用 结果
崩溃(3 次) safe 0 / 18 1 正确
默认策略 unsafe 0 / 18 0 报错:在途调用被中断
并行(Promise.all) safe 0 / 18 19 正确
改了脚本 safe 0 / 18 1 报错:路径分叉
改了沙箱配置 safe 0 / 18 1 报错:沙箱已变
改了外部数据 safe 0 / 18 1 总数错误,没有报错

我从这张表读出三点:

另外两个细节:timeout_ms 在停机期间用完,恢复时会直接报错;关闭进程不算脚本结束,应用要取消脚本必须显式记录,否则重启后脚本会继续跑。

作者的使用边界是:有界的读取和计算放进脚本,长时间运行的工具、等人审批、有副作用的操作留在外面。副作用工具保持 unsafe,崩溃后由重试方带幂等 key 判断第一次有没有生效。他也承认还没想清楚 codemode 什么时候完全不值得用。

他还认为 durable codemode 让 Pi Durable 走完了通往 Claude Code dynamic workflows 的大半程:模型自己写工作流脚本,崩溃后能恢复。这和第 8 节"把 workflows 和 codemode 合起来"是同一个方向。

8. 对 qodercli 的具体建议

flowchart TD
    A[新增 codemode 工具] --> B{当前模型是否在白名单?}
    B -- GPT 系列 / 已评测通过 --> C[默认开启]
    B -- 其他 --> D[默认关闭,可通过配置开启]
    C --> E[工具分级暴露]
    D --> E
    E --> E1["direct: Read/Edit/Bash/Grep 等热路径"]
    E --> E2["codemode-only: MCP 工具、长尾工具"]
    E --> E3["deferred: 通过 tool search 按需声明"]
    E --> E4["codemode 专属 API: classify / imageGen / store"]
    E2 --> F[复用 mcp-lazy 的发现逻辑]
    A --> G[复用 workflow-sandbox 的 VM 与 journal]
    G --> H["VM 内的嵌套调用仍然走权限系统 + hooks"]
  1. 不另起炉灶:packages/core/src/workflows/ 已经是"subagent 的 code mode"(和 pi-dynamic-workflows、Claude Code dynamic workflows 同一类),tools/mcp-lazy/ 已经做了 MCP 的延迟发现。codemode 就是在同一个 VM 里再注入 tools.*(包括 MCP),并把 lazy 的 list/get 变成 VM 内的 tools.search()/describe()。
  2. 按模型开关:GPT 系列默认开(Codex 已经训练过这个格式);Claude 先 opt-in,跑 bench/evals 再决定;开源模型默认关。参考 Codex 的"模型声明支持"机制,而不是全局开关。
  3. 工具描述要小:Reddit 实测 3k token 的描述是小任务亏钱的根源。参考 Pi 1.0:API 文档按需加载(prompt 从 ~5.3k 降到 ~3.3k)。目标是 1k 以内。工具签名用 TS 声明而不是 JSON Schema 塞进描述(Phil Schmid 的做法),会更省。
  4. 热路径保持 direct:Read/Edit/Bash/Grep 不要只放进 codemode(Pi 默认也把 read 等工具留在顶层,codemode.mode: only 才全收进去)。MCP 和低频工具走 codemode-only 或 deferred。
  5. 安全边界:node:vm 不是安全边界(Node 官方文档明确说明)。workflow 场景下可以接受,因为脚本由可信流程生成;codemode 执行的是模型随手写的代码,考虑换 QuickJS-WASM(Pi 和 runline 都这么做:约 210KB,毫秒级冷启动,可以限制内存和 CPU)。更关键的是:每个嵌套的 tools.* 调用都要走现有的权限检查和 PreToolUse hooks,沙箱本身拦不住一个权限过大的工具。需要人工确认的嵌套调用会让脚本停在中间,所以默认只把只读工具放进脚本,写操作和需要审批的工具留在顶层,这也和第 7 节的使用边界一致。如果以后放开写操作,确认粒度定在单次调用而不是整个脚本,一个 Promise.all 批量归档不能只问一次。
  6. 结果契约:嵌套调用返回结构化对象,isError、非零 exit_code 要显式暴露,不能只靠 Promise 状态判断;能拿到 outputSchema 的 MCP 优先使用。
  7. 可观测性:TUI 里展示嵌套调用(Pi 记为 nestedCalls),设置并发上限(Pi 是 4),返回值默认截断,超出部分落盘。
  8. 评测口径:在 bench/ 里按任务长度分组,记录往返次数、cache read token、首次调用错误率。短任务(<5 次调用)的净 token 必须不劣化,否则默认关闭。再加一项"回给模型的工具输出字节数":Manoj 的实验里这个数最能解释 Pi 和 OpenCode 的差别。
  9. 让中间数据留在脚本里:提供跨脚本的 store()/load(),并在工具描述里明确要求脚本只返回结论。Manoj 的 Pi 运行每次都用了 store()/load(),OpenCode 运行每次都把完整列表回传。样本很小,不能确定差别全来自这两个 API,但这条改动成本低,先做。
  10. 第一版不做重放,但别把路堵死:Starlark 等替代语言也不做。重放现在有了可参考的实现(Pi Durable),不过它还是实验状态,而且要给每个工具标 replay。现在只需守住三条,以后补重放时不用返工:沙箱不暴露真实时钟和随机数;嵌套调用结果先写 journal 再交给脚本,这可以从现有 WorkflowJournal 下沉到工具调用粒度;嵌套调用默认按 unsafe 处理。脚本失败时,返回值里要列清楚哪些调用完成了、哪些失败了、哪些没跑,模型才能只重试剩下的部分;有副作用的调用带幂等 key(@johnroodepic 的做法),这比重放便宜得多,可以先做。

参考链接

X 书签

X 搜索

博客 / 文章

Reddit

Read this report as Markdown · Cite it (BibTeX)