---
title: "Codemode"
author: "陈成"
author_url: "https://research.sorrycc.dev/@sorrycc"
question: "Codemode 是什么、省在哪里、对 harness 设计意味着什么？"
url: "https://research.sorrycc.dev/@sorrycc/codemode"
emoji: "🧩"
published: 2026-10-29T12:56:15Z
updated: 2026-11-03T03:50:29Z
version: 7
cite: "https://research.sorrycc.dev/@sorrycc/codemode.bib"
---

# Codemode（用代码调工具，而不是逐个 tool call）调研笔记

By [陈成](https://research.sorrycc.dev/@sorrycc) · 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

- **是什么**：harness 给模型一个"执行 JS 的工具"（Pi 叫 `codemode`，Codex 叫 `exec`），JS 里通过 `tools.*` 调用 harness 自己的工具和 MCP。模型写一段脚本完成"多次调用 + 过滤 + 汇总"，只把最终结果回给模型。
- **省在哪**：省的是**模型往返次数**。每次 tool call 返回后都要带着全部历史再请求一次模型，往返少了，累计输入（主要是 cache read）就少了。不是省在"代码比 JSON 短"。前提是中间数据留在脚本里：Manoj 的小实验中，Pi 的总输入 −17.5%，而 OpenCode 把整个列表返回给模型，总输入 +17.5%。
- **75% 这个数**：来自 @geoqiao 的单次实验：Pi + GPT 6 Astra 跑一个长流程前端任务，Code Mode 对比原生工具，累计 token −75%，估算费用 −64%。差额里 98.46% 是 cache read 减少。只有一次实验，短任务上可能反而更贵。
- **"GPT 是被训练过的"**：Mario（Pi 作者）原话 "gpt family of models is now trained on it"；mitsuhiko 在 HN 说 Codex 在 Responses Lite 下**必须**走 codemode 才能并行调用工具；Reddit 有人指出 GPT-6 系列在 Codex 里 MCP 默认是 codemode-only。Claude 在 Pi 里也用得不错，DeepSeek 等开源模型报错多一些。
- **反对声音**：Reddit 实测，小修 bug 场景 token 反而 **+21%**（codemode 工具描述约 3k token，每轮都带着），模型首次用错、来回试错，和其他工具混淆。作者扫描自己 149 个会话，真正适合 codemode 的场景只出现过一次。
- **崩溃恢复**：Pi coding agent 和 OpenCode 里，进程崩了脚本就丢了，模型从头再跑一遍。Pi Durable 靠确定性重放接着跑，SIGKILL 测试中已完成的调用没有重跑过，但崩溃时在途的调用可能跑两次，外部数据变了也不报错。副作用仍然不适合放进脚本。
- **"只剩 1 个工具"**：Phil Schmid（Google DeepMind）11/1 的文章把 codemode 当成工具调用的下一阶段：几个工具 → tool search → 一个 `exec`。新增的信息主要是：工具 schema 编成 TS 声明、工具多时暴露 `ALL_TOOLS` 让模型自己筛；Pi、Factory Droid、Codex 已默认开启；Factory 自报 Droid 1.0 切过去后 Terminal-Bench 4 +3.5 分、花费 −15%。他判断 `outputSchema` 普及后 MCP 会在 2027 年回潮。文章没讲失败恢复，推上回复问得最多的就是这个。
- **对 qodercli 的建议**：做，但按模型开关、按工具分级暴露。qodercli 已经有两块现成的地基：`workflows/`（node:vm 跑 JS 编排 subagent）和 `tools/mcp-lazy/`（mcp_list/get/call 延迟加载）。codemode 基本就是把这两者合起来：VM 里除了 `agent()` 再暴露 `tools.*` 和 MCP。

---

## 1. 演进脉络

```mermaid
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. 机制：省在哪里

```mermaid
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

```mermaid
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
```

- bash 只能组合"能跑的程序"。`read` 图片、spawn subagent、调用分类模型这类 harness 原生能力，bash 组合不了。
- codemode 跑在 **harness 侧**，用来编排 harness 级别的工具；bash 跑在**执行环境侧**。两边的文件系统和信任级别都不同。
- 所以 codemode 不是 bash 的替代，而是 bash 管不到的那一层（HN 上 mitsuhiko 原话："codemode solves a different problem than bash"）。
- 他自己列出的未解决问题：durability（可能要借鉴 durable workflow 做快照，或者换用 Starlark 这种确定性语言）、二进制/图片、小模型用不好。其中 durability 现在有了一个实现，见第 7 节。

**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. 社区争论

**支持方**
- dax（opencode）："pretty much a non-negotiable thing at this point"；opencode2 里所有 MCP 默认进 codemode，自定义工具可以选择加入
- Mario：省钱来自减少轮次，和当年 parallel tool calls 一样
- magnio（HN）：codemode 可以理解为"可以类型检查的 bash"：错误提前暴露、并发编排更顺手、输出可控、不依赖宿主环境、天然沙箱
- Mehdi：从不确定性（skill/prompt）转向确定性（codemode + 少量 jev 智能）
- Phil Schmid 列的"为什么不用 bash"：有类型的函数和 `Promise.all`/`try/catch`，不用处理字符串转义；类型声明一开始就交代接口，省掉模型跑 `--help`、读源码的轮次；能把图片、音频带回下一轮；宿主桥接层可以注入 OAuth token、校验 schema、对破坏性调用要求确认；KV 存状态。和 mitsuhiko 的 brain/hands 是同一个结论，角度更偏工程
- @slaser79：手机这类没有完整 CLI 的沙箱 agent，更依赖 codemode 做组合

**反对 / 质疑**
- "模型会 bash 就够了"（HN 多人、Reddit）。反驳：bash 调不到 MCP、harness 内部 API、subagent
- 模型用不好：每个 session 一半概率第一次用错，要试错两轮；会误用 codemode 去起 subagent 或 read（Reddit 14 赞）
- 开源模型普遍不擅长（Mario 自己也承认）；Claude 在部分 harness 里用得不好（@AnerCohen），但在 Pi 里表现不错（geoqiao、@su_shengka46416）
- Pi 一向以极简著称，把 codemode/MCP 放进核心而不是做成扩展，有人不满
- 安全：QuickJS 隔离挡不住一个权限过大的工具调用（@sebuzdugan）；MCP 返回 `isError` 时 Promise 照样 resolve，bash 非零退出码也是 resolve，"一批 fulfilled 的 Promise 里也可能有失败的操作"（@hexablob）
- 输出默认应该截断（@hyknerf）
- 半成品：直接调用时模型下一步就能纠错，脚本只能按写脚本时的假设跑到底。模型探几条成功、跑全量时撞上服务端条数上限，就会停在一部分调用完成、一部分没完成的状态（Manoj）。和 mitsuhiko 列的"结果要一致"是同一个坑
- 逐次审批：一个脚本可以调很多工具，需要人工确认的调用会让脚本停在中间，脚本还得活到人回复（Manoj）
- 半途失败（Phil Schmid 推文下回复最集中的问题）：@johnroodepic 说一个脚本 12 个副作用、死在第 7 个，重试会把 1–6 再做一遍，他们的做法是每个有副作用的调用先写一行带 key 的记录、执行前检查，重试就能从第 7 个接着跑；@alishohadaee 指出普通 tool call 每次失败只回一个结果，脚本挂了 agent 要先弄清哪些已经执行；@AIQuanting 问 `Promise.all` 批量归档时，确认是按调用还是按脚本
- 生态不匹配：很多工具、CLI 和 Agent Skills 是按 bash + 人读文本写的，不一定能接进有类型的执行环境（Phil Schmid 自己的保留意见）
- "去年的技术"：@Shashikant86 认为 codemode 押注 tool search，主要是 Cloudflare 这类沙箱厂商在推
- "the dangerous savings are the unobserved ones"：一次改多个文件时，怎么确认停在了正确的边界（@AgentEtna）
- Mistral 有 CodeAct 专利（US 12,670,045 B1），有人提到，影响未知

**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 调研](https://research.sorrycc.dev/@sorrycc/pi-durable)，这里只记脚本这部分。

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

- **脚本看不到会变的东西**。虚拟时钟、固定种子的随机数、固定 UTC 时区。
- **结果先提交，再交给脚本**。每个嵌套调用是 codemode 调用名下的一个工具任务，journal 记下结果到达的顺序。
- **按位置匹配**。重跑时第 N 次调用必须是同一个工具、同样的参数，匹配上就直接返回存好的结果，走到断点后才发起新调用。
- **在途调用看工具声明**。`replay: "safe"` 的重跑；默认的 unsafe 不重跑，脚本收到 `was interrupted and may have partially run` 错误。

崩溃测试用 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 | **总数错误，没有报错** |

我从这张表读出三点：

- 它保证已完成的调用不重跑，不保证每个调用只跑一次。作者的原话是 "It does not promise that every call runs once"。
- 并发的代价是崩溃后要重做的更多。并行那一行重复了 19 次，顺序执行只重复 1 次。模型爱写 `Promise.all`，这个代价躲不掉。
- 最危险的是最后一行。重放只检查调用和参数，不检查数据有没有变，旧结果和新结果混在一起算出错误总数，没有任何提示。长时间停机后恢复时要留意。

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

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

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

## 8. 对 qodercli 的具体建议

```mermaid
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 书签**
- @geoqiao 日常使用效果：https://x.com/geoqiao/status/2105686410946908389
- @geoqiao 文章《Is Code Mode the Future? 64% Lower Cost on a Long-Running Task》：https://x.com/geoqiao/article/2098084791191310694
- @badlogicgames（Mario）"gpt family of models is now trained on it"：https://x.com/badlogicgames/status/2105957444287430989
- @PiChangelog v0.99.0（codemode 内置）：https://x.com/PiChangelog/status/2104986274730029265
- @PiChangelog v1.0.0（prompt −40%）：https://x.com/PiChangelog/status/2105741334728634552
- @dillon_mulroy codemode + jev 演示：https://x.com/dillon_mulroy/status/2105453668266873091
- @thdxr "non-negotiable"：https://x.com/thdxr/status/2092368916563542299
- @joelhooks：https://x.com/joelhooks/status/2105450590914695502
- @justsisyphus OmO v5 "10x faster tool calls using codemode"：https://x.com/justsisyphus/status/2103923201055289369
- @verysmallwoods 视频《Pi Agent 1.0 Code Mode：用 JavaScript 编排工具调用》：https://x.com/verysmallwoods/status/2110502104557048205
- @micLivs pi-dynamic-workflows：https://x.com/micLivs/status/2060115468531499224
- @nicopreme pi-subagents code mode：https://x.com/nicopreme/status/2085436528952827981
- @alex_frantic 画图 → codemode 脚本：https://x.com/alex_frantic/status/2080776965070496115
- @guyingjie129 基于 code mode 的 coding agent：https://x.com/guyingjie129/status/2083126617426280890
- @manojlds《Code mode that survives a crash》：https://x.com/manojlds/status/2115868615333327059
- @_philschmid 发文《Why Agents Are Soon Only Going to Have 1 Tool》及回复：https://x.com/_philschmid/status/2117278154918092817

**X 搜索**
- @mitsuhiko 发文：https://x.com/mitsuhiko/status/2107464890180927782
- @LanLance24 Cloudflare 才是源头：https://x.com/LanLance24/status/2107480347667796253
- @yifanxu_ephai apply_patch 名存实亡：https://x.com/yifanxu_ephai/status/2106960305490387390
- @Stephan_Talk 批量读文件场景：https://x.com/Stephan_Talk/status/2113773156314030398
- @techgirl1908 goose 中 token 减半：https://x.com/techgirl1908/status/2013644130362982606
- @Jilles Cloudflare MCP 约 1k token：https://x.com/Jilles/status/2094833926879560031

**博客 / 文章**
- Phil Schmid《Why Agents Are Soon Only Going to Have 1 Tool》：https://www.philschmid.de/code-mode
- Factory Droid 1.0 评测（二手，Factory 自报数据）：https://aireiter.com/blog/factory-droid-1-0-review
- mitsuhiko《What is Codemode》：https://lucumr.pocoo.org/2026/10/6/codemode/
- Earendil《"You Said No MCP!"》：https://earendil.com/posts/you-said-no-mcp/
- HN 讨论（687 points）：https://news.ycombinator.com/item?id=49906637
- Cloudflare《Code Mode: the better way to use MCP》：https://blog.cloudflare.com/code-mode
- Cloudflare《Code Mode: give agents an entire API in 1,000 tokens》：https://blog.cloudflare.com/code-mode-mcp
- Anthropic《Code execution with MCP》：https://www.anthropic.com/research/code-execution-with-mcp
- Anthropic《Introducing advanced tool use》（Programmatic Tool Calling）：https://www.anthropic.com/research/advanced-tool-use
- michaellivs《Ergonomic coding surfaces for agents (a.k.a Code Mode)》：https://michaellivs.com/blog/ergonomic-coding-surfaces-for-agents/
- openai/codex#37825 function-backed exec：https://github.com/openai/codex/issues/37825
- pi-codemode 扩展（ian-pascoe）：https://github.com/ian-pascoe/pi-extensions/tree/main/packages/pi-codemode
- pi-subagents：https://github.com/nicobailon/pi-subagents
- pi-dynamic-workflows：https://github.com/Michaelliv/pi-dynamic-workflows
- pydantic/monty（Rust 写的 Python 沙箱）：https://github.com/pydantic/monty
- Manoj Mahalingam 博客（X 长文的完整版）：https://stacktoheap.com/blog/2026/10/26/durable-code-mode-in-pi/
- Manoj Mahalingam 上一篇 Pi Durable：https://stacktoheap.com/blog/2026/10/05/pi-durable/
- Pi Durable README（replay）：https://github.com/earendil-works/pi/blob/main/packages/durable/README.md
- OpenCode codemode 包：https://github.com/anomalyco/opencode/blob/dev/packages/codemode/README.md
- 本库 Pi Durable 调研：https://research.sorrycc.dev/@sorrycc/pi-durable

**Reddit**
- "Codemode won its designed-for test by 40%. I still turned it off."：https://www.reddit.com/r/PiCodingAgent/comments/1wulbg8/codemode_won_its_designedfor_test_by_40_token/
- "What does everyone think about codemode?"：https://www.reddit.com/r/PiCodingAgent/comments/1wtxc1d/what_does_everyone_think_about_codemode/
- "Stop Exposing Thousands of Tools to Agents. Use Code Mode Instead"：https://www.reddit.com/r/AI_Agents/comments/1v4yba9/stop_exposing_thousands_of_tools_to_agents_use/
- "Built-in MCP and code mode are amazing"：https://www.reddit.com/r/PiCodingAgent/comments/1wudg9b/builtin_mcp_and_code_mode_are_amazing/
