Context Mode 与 Code Mode:都在给 Agent 瘦身,按住的是不同管子

一边压缩工具编排,一边折叠工具返回。用一次自跑的字节数实验讲清两个新词的机理、目的、组合方式和边界。

最近两个新词在 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 文档里给的一次优化前后对比是单会话成本从 7.20降到7.20 降到 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

机制有三块:

  1. 工具改成代码接口。Cloudflare 的 Agents SDK 把 MCP schema 翻译成 TypeScript 函数签名;Anthropic 的做法更进一步,把每个工具挂成文件系统里的一个 .ts 文件,Agent ls ./servers/ 发现,cat 读某一个文件时才付定义成本。这就是前面说的 progressive disclosure。
  2. 代码在沙箱里跑。Cloudflare 用 V8 isolate,Pi 用 QuickJS/WASM。沙箱只能通过注入的接口调用 MCP 工具,不能直通外网。
  3. 只有最终结果回到模型。中间 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,8011x
全量 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 文档把它拆成三件事:

  1. Response folding。工具原始返回第一次经过 gateway 时,被折叠成一个”小结 + 可引用 ID”的摘要塞进 context;原始内容另存。后续轮次直接读折叠版,不再把 60 KB 的 Playwright snapshot 重新塞一遍。
  2. Subprocess isolation。用户脚本在 Cloudflare Worker isolate 里跑,只有 stdout 回到模型——这其实就是 Code Mode 的做法内嵌进了 gateway,统一提供给 Claude Code / Codex 两家。
  3. Policy enforcement。工具调用先过规则:22 种能力、98 个修饰词、sudo / sh -c / xargs / ssh 这些 carrier 都会被拦;被拦的命令永远不执行,只回一个拒绝信息。

它和 Code Mode 的分工,对号入座看最清楚:

关注点Code ModeContext Mode
省的是什么工具 schema 和中间数据工具返回体
代码改哪里要改 Agent/Harness:给它一个代码接口不改 Agent,拦在模型请求路径上
典型载体Cloudflare Agents SDK、Pi、Anthropic Skillscontext-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:在办事窗口和会议室之间加一个前台,所有回执都先精简成”要点 + 存档编号”再送进会议室。

两件事可以同时做,但解决的痛点不一样——先搞清楚自己的桌子是被指南撑爆的,还是被回执撑爆的,再对号入座。

参考来源