最近两个新词在 Agent 工程圈同时冒头:Code Mode 和 Context Mode。听上去像一对,但解决的问题几乎不重叠。
一句话先放这里:它们都在让 Agent 的 context 窗口瘦下来,但按住的是两根不同管子——一根是进去的工具定义,一根是出来的工具返回。
| 新词 | 按住哪根管子 | 典型做法 | 代表来源 |
|---|---|---|---|
| Code Mode | 输入侧:工具编排与中间数据 | 模型写一段代码,在沙箱里一次性调用若干工具 | Cloudflare、Anthropic |
| Context Mode | 输出侧:工具返回体 | 在模型和工具之间加 gateway,把原始返回折叠成摘要 | context-mode.com |
这篇把两者的机理、目的、组合用法和开放问题讲清楚,并用一次可复现的字节数实验证明两根管子都值得按。
名词速查
读下文先用五个词接住:
| 词 | 一句话解释 |
|---|---|
| MCP | 模型连接外部工具的开放协议;详见这篇旧文 |
| Tool schema | 工具的参数定义,一般写成 JSON Schema,交给模型读 |
| Harness | 包裹模型的运行程序,管理 context、工具和循环;见什么是好的 Agent Harness |
| Progressive disclosure | 按需加载:先给目录,用到哪个工具再读该工具的详细定义 |
| Response folding | 把工具原始返回在进入模型前折叠成摘要;原始内容另存可按 ID 取回 |
还有两个背景结论可以直接拿来用:
- 在企业环境里把 20 个 MCP server × 20 个工具装进 context,一上来就是 400 份 JSON Schema,前置成本很重。这是 Code Mode 讨论里反复用的场景。
- Anthropic 的 “Code execution with MCP” 给了一个代表性数字:从 150,000 token 降到 2,000 token,降幅 98.7%。这是官方页面给的单一场景例子,不是通用基准。
Context 窗口的两类浪费:进去的和出来的
传统的 MCP tool-use 回合长这样:
flowchart LR
A["客户端启动<br/>加载全部 400 份工具 schema"] --> B[模型选工具]
B --> C[调用工具]
C --> D[返回体整段回到 context]
D --> E[模型读完<br/>选下一个工具]
E --> C
两处浪费一眼可见:
- 进去的:工具定义一开始就全量灌进 context,用不用都算在 token 账单上。
- 出来的:每次工具返回原封不动流回 context;接下来每一轮推理都要重读一遍。
一段 Claude Code / Codex 的长会话里,这两类浪费会叠加放大。Context Mode 文档里给的一次优化前后对比是单会话成本从 2.49,降幅 65.5%——这是 gateway 自己披露的数字,不是独立评测,但方向可信。
两根管子分开按,两个新词正好各治一根。
Code Mode:让模型写代码,而不是循环调用工具
Code Mode 的核心是把”选工具 → 调工具 → 读返回 → 再选工具”这一串循环,塞进模型写的一段代码,交给沙箱执行;只有最终输出回到 context。
flowchart LR
A["模型看到的是<br/>TS/JS API 签名"] --> B["写一段代码:<br/>get → filter → sort → return"]
B --> C["沙箱<br/>V8 isolate / QuickJS"]
C -->|调用| D[MCP 工具 1]
C -->|调用| E[MCP 工具 2]
D --> C
E --> C
C --> F["只回 console.log 结果"]
F --> A
机制有三块:
- 工具改成代码接口。Cloudflare 的 Agents SDK 把 MCP schema 翻译成 TypeScript 函数签名;Anthropic 的做法更进一步,把每个工具挂成文件系统里的一个
.ts文件,Agentls ./servers/发现,cat读某一个文件时才付定义成本。这就是前面说的 progressive disclosure。 - 代码在沙箱里跑。Cloudflare 用 V8 isolate,Pi 用 QuickJS/WASM。沙箱只能通过注入的接口调用 MCP 工具,不能直通外网。
- 只有最终结果回到模型。中间 10 次工具调用的原始返回全部留在沙箱里,模型看到的只是最后一行
console.log。
训练数据给了这件事一个客观依据:模型见过的 TypeScript 比它见过的”合成 tool-use JSON”多几个数量级。Cloudflare 原文的说法是 “LLMs have seen a lot of code. They have not seen a lot of ‘tool calls’“。能写代码就少走一条冷门的生成路径。
用字节数估一下输入侧省了多少
我把 20 个 MCP 工具同时写成 JSON Schema 和 TypeScript 签名量一下。保存为 schema_bloat_probe.py,运行 python3 schema_bloat_probe.py,无需额外依赖:
import json
def make_tool(i):
return {
"name": f"tool_{i}",
"description": f"Perform operation {i} on the target resource with optional modifiers.",
"inputSchema": {
"type": "object",
"properties": {
"resource_id": {"type": "string", "description": "Target resource identifier."},
"mode": {"type": "string", "enum": ["read","write","append"], "description": "Operation mode."},
"timeout_ms": {"type": "integer", "description": "Timeout in milliseconds.", "default": 5000},
"metadata": {"type": "object", "description": "Optional metadata key-value pairs.", "additionalProperties": True},
"dry_run": {"type": "boolean", "description": "If true, do not persist changes.", "default": False},
},
"required": ["resource_id","mode"],
},
}
def make_ts_sig(i):
return (
f"// Perform operation {i} on the target resource with optional modifiers.\n"
f"export declare function tool_{i}(args: {{\n"
f" resource_id: string;\n"
f" mode: 'read' | 'write' | 'append';\n"
f" timeout_ms?: number;\n"
f" metadata?: Record<string, unknown>;\n"
f" dry_run?: boolean;\n"
f"}}): Promise<unknown>;\n"
)
N = 20
tools = [make_tool(i) for i in range(N)]
ts = [make_ts_sig(i) for i in range(N)]
listing = "\n".join(f"./servers/demo/tool_{i}.ts" for i in range(N))
size = lambda s: len(s.encode() if isinstance(s, str) else json.dumps(s, separators=(',',':')).encode())
all_schema = size(tools)
all_ts = sum(size(s) for s in ts)
file_listing = size(listing)
two_ts = size(ts[0]) + size(ts[1])
print("traditional_all_schemas_bytes =", all_schema)
print("code_mode_all_signatures_bytes =", all_ts)
print("code_mode_listing_only_bytes =", file_listing)
print("code_mode_listing_plus_two_tools_bytes =", file_listing + two_ts)
print("ratio_schema_vs_full_ts =", round(all_schema/all_ts, 2))
print("ratio_schema_vs_lazy_two =", round(all_schema/(file_listing + two_ts), 1))
本次实测输出:
traditional_all_schemas_bytes = 12801
code_mode_all_signatures_bytes = 5500
code_mode_listing_only_bytes = 509
code_mode_listing_plus_two_tools_bytes = 1057
ratio_schema_vs_full_ts = 2.33
ratio_schema_vs_lazy_two = 12.1
三行值得挑出来:
| 做法 | 字节数 | 相对基线 |
|---|---|---|
| 全量 JSON Schema(传统 MCP) | 12,801 | 1x |
| 全量 TS 签名 | 5,500 | 节省 57% |
| 只放文件目录 + 两个真用到的 TS 定义 | 1,057 | 节省 92% |
这不是 token 数、也不是账单;只是 UTF-8 字节数,不同模型 tokenizer 比例还会不同。但方向明确:把 schema 换成签名能省一截,再叠一层”用到才读”又能省一截。Anthropic 页面那个 150k→2k 的 98.7%,极大一部分就来自第二层。
Code Mode 没解决的事
沙箱约束的是脚本自己的直接能力,不是注入工具的权限。如果把一个”直接改生产库”的工具暴露给沙箱里的脚本,脚本仍可以把生产库改花。Armin 的 Code Mode 原文把这一点写得很清楚:Bash 和 Code Mode 的沙箱位置不同,但都不能替工具本身设置权限。
脚本不是事务。把十个操作塞进一个 main() 不等于给它们包了原子性。前面 7 步已经真实发送消息,第 8 步解析失败再重跑,前 7 步仍会重放。关于这件事上一篇 Pi Durable + Code Mode 的实验写过——持久执行、幂等键、独立 Oracle,这里不展开。
Context Mode:在模型和工具中间加一层 gateway,折叠返回
如果说 Code Mode 按住的是”进去”那根管子,Context Mode 按住的就是”出来”那根。它是一个 gateway,坐在 Agent 和模型 provider 之间,拦截工具调用的返回体。
flowchart LR
A[Agent 调用工具] --> B[Gateway]
B --> C[工具真实执行]
C --> D[原始返回<br/>比如 60 KB 的 HTML snapshot]
D --> B
B --> E["原始返回另存<br/>(可按 ID 取回)"]
B --> F["压缩成摘要<br/>只送摘要进 context"]
F --> G[模型继续推理]
context-mode.com 文档把它拆成三件事:
- Response folding。工具原始返回第一次经过 gateway 时,被折叠成一个”小结 + 可引用 ID”的摘要塞进 context;原始内容另存。后续轮次直接读折叠版,不再把 60 KB 的 Playwright snapshot 重新塞一遍。
- Subprocess isolation。用户脚本在 Cloudflare Worker isolate 里跑,只有 stdout 回到模型——这其实就是 Code Mode 的做法内嵌进了 gateway,统一提供给 Claude Code / Codex 两家。
- Policy enforcement。工具调用先过规则:22 种能力、98 个修饰词、
sudo/sh -c/xargs/ssh这些 carrier 都会被拦;被拦的命令永远不执行,只回一个拒绝信息。
它和 Code Mode 的分工,对号入座看最清楚:
| 关注点 | Code Mode | Context Mode |
|---|---|---|
| 省的是什么 | 工具 schema 和中间数据 | 工具返回体 |
| 代码改哪里 | 要改 Agent/Harness:给它一个代码接口 | 不改 Agent,拦在模型请求路径上 |
| 典型载体 | Cloudflare Agents SDK、Pi、Anthropic Skills | context-mode.com 的 gateway |
| 适用对象 | 自己造 Agent 的工程团队 | 已经在用 Claude Code / Codex 的用户 |
| 失败模式 | 脚本漏项或不幂等 | 折叠太狠丢证据、gateway 自身成瓶颈 |
用一次返回体实验直观感受
输出侧的省法可以用之前 Pi + Code Mode 篇跑过的 filter_probe.py 直接看。它造 200 条模拟记录,每条 1KB 正文,每 40 条标一条 urgent,只问”哪些紧急”:
rows= 200 kept= 5 raw_bytes= 207086 selected_bytes= 122
reduction_percent= 99.9411
207,086 字节压到 122 字节,99.94%。这是最乐观的构造场景(正文全是重复字符),但方向说得清:只问”哪些紧急”却把 200 条正文全送回模型,纯属浪费。 Context Mode 把这类压缩从”写代码的人要记得做”变成”gateway 默认帮你做”。
但有一个条件:折叠逻辑必须保留”源 ID + 丢弃计数 + 可取回入口”。 否则下一轮模型想追查某条记录为何未入选,证据已经不在手边。这正是 Context Mode 的默认设计——折叠后原始内容仍可按 ID 取回,不是直接扔掉。
Context Mode 没解决的事
- 折叠本身有判断成本。如何折叠依赖规则或小模型;规则不当会误压重要字段。
- Gateway 要承担所有 traffic。单点故障和延迟都归它负责;要上生产得规划 HA 与可观测。
- 不改 Agent 的好处也是坏处:没法像 Code Mode 那样让 Agent 一次编排多个工具,省中间轮次。
本质:这两件事都是数据库谓词下推的再次演出
两个新词的本质可以用一句老话概括:把能机械完成的数据搬运,推到执行层去做,不要塞进推理层。
- 数据库早就有同一招:谓词下推(predicate pushdown)。能在存储层过滤的记录,不要先搬到计算层。
- Code Mode 推下去的是编排:筛选、排序、循环这些机械步骤,交给代码执行层。
- Context Mode 推下去的是裁剪:原始返回里哪些字段进不去模型,由 gateway 决定。
一个反事实能把这件事验证一下:如果 Agent 的 context 不花钱、也不会漏信息、还永远精准召回,这两个新词都不必存在。只要有一个条件不满足——而 LLM 现状是三条都不满足——就有理由把机械工作搬离推理层。
这和站内早前讨论的 “推理转程序:卸载机械工作” 是同一条脉络。Code Mode 卸载编排,Context Mode 卸载返回体裁剪,形态不同,底层逻辑一致。
怎么选:三张边界卡
瓶颈在”工具太多,schema 装不下” → 先上 Code Mode,核心是 progressive disclosure:工具改成文件/模块,用到才读。前面实测的 92% 节省来自这里。
瓶颈在”工具返回太大,context 滚雪球” → 先上 Context Mode 这类 gateway,或者在自己的 Agent 里实现一个 response-folding 层。关键是折叠时留下源 ID 和取回入口,别让模型失明。
两件事都痛,但只能先做一件 → 看 Agent 是不是自家在造。自己造,Code Mode 的改造成本可控、长期收益最大。用的是别人的 Agent(Claude Code / Codex 这种),Context Mode 这种拦在模型请求路径上的方案更现实——不需要动 Agent 本身。
最后两件事做了也救不了的 → 持久恢复(崩溃后外部副作用去哪儿找)、独立 Oracle(Agent 能不能自己判定做完了)。这两件事和 context 大小正交,省 token 省不出来;要靠幂等键、业务规则、独立测试这些”框架能帮你证明的东西”。
通俗总结
把 Agent 想成一个会议室:模型是开会的人,context 窗口是桌子,MCP 工具是外面的办事窗口。
- 传统做法:400 份办事指南堆满桌子,每次办事回来还把完整文件糊脸读一遍。
- Code Mode:改成”用到才拿这一本指南,顺手把一串事交代给秘书去办,秘书只回一句话”。
- Context Mode:在办事窗口和会议室之间加一个前台,所有回执都先精简成”要点 + 存档编号”再送进会议室。
两件事可以同时做,但解决的痛点不一样——先搞清楚自己的桌子是被指南撑爆的,还是被回执撑爆的,再对号入座。
参考来源
- Cloudflare — Code Mode: the better way to use MCP。Code Mode 命名出处与 V8 isolate 做法。
- Anthropic — Code execution with MCP: Building more efficient agents。文件系统 progressive disclosure 和 150k→2k 的例子。
- context-mode.com 文档。Context Mode 的 response folding / subprocess / policy 机制,及 65.5% 成本降幅出处。
- Armin Ronacher — What is Codemode。设计原文,含 Bash 与 Code Mode 的位置差异、持久性开放问题。
- 站内延伸:Pi Durable 与 Code Mode 的恢复实验、MCP 的状态在哪、推理转程序:卸载机械工作、什么是好的 Agent Harness。