Agent on 鬼哥的空间

别让 Fable/Opus 干杂活：Agent 系统的省钱架构

Thu, 09 Jul 2026 00:00:00 +0000

你开发 Agent 的时候，是不是也干过这种事：

不管任务大还是小，先把 Fable/Opus 请出来，一路从查网页、搬数据、整理表格，撸到最后写报告。

鬼哥以前也经常这么干。刚开始是图省事，也确实希望结果尽量好。至于更深层的原因，大概是经验不足，手艺还菜，这句不要外传。

直到后来看到 API 账单，整个人就清醒了。

开法拉利去跑货拉拉，当然快。但快归快，油钱是真的遭不住。

用 Fable/Opus 去读网页、搬资料、整理表格，也有点像拿炮弹打苍蝇。不是打不中，而是太贵、太吵，还容易把桌子一起掀了。

所以我最近翻了几篇 Anthropic 关于 Advisor Tool、Managed Agents 和 multi-agent workflow 的技术文章，发现它们表面上是在讲 Claude 的新能力，底层其实在讲一件更工程化的事：

Agent 系统的成本，不只取决于你用了哪个模型，更取决于你有没有把任务拆对。

这篇文章不做文档复读。我们直接把它抽象成一套可复用的 Agent 省钱架构。

先看一个调研任务：拿 Opus 打苍蝇是怎么发生的

假设你要做一个知识调研：

对比 10 个 AI 编程工具的 Agent 架构、定价、上下文管理、工具调用能力，并给出选型建议。

很多人的第一反应是：直接丢给 Fable/Opus。

1
2


Fable/Opus 单体 Agent：
搜索网页 -> 阅读文档 -> 抽取事实 -> 整理表格 -> 对比分析 -> 写最终报告

这当然能做。

但你仔细看一下任务链条，会发现里面大量步骤其实不需要顶级推理能力：

步骤	需要什么能力	是否值得用 Fable/Opus
搜索官网和文档	覆盖率、耐心、工具调用	不太值
读取定价页	信息抽取	不太值
整理上下文长度、工具能力	结构化归纳	不太值
交叉验证来源	仔细、可重复	通常不需要
判断适合什么团队	产品判断、架构取舍	值
识别长期风险	深度推理、经验迁移	值

也就是说，80% 的 token 可能烧在“搬信息”上，但真正需要 Fable/Opus 的，是最后 20% 的判断。

更合理的拆法应该是这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Sonnet coordinator：
 设计调研维度，拆分任务，规定输出格式，验收结果

Haiku / cheaper workers：
 并行搜索、读取网页、抽取事实、保留来源

Sonnet executor：
 合并结构化结果，发现冲突，要求补查

Fable/Opus advisor：
 在最终选型、风险分析、架构判断时介入

这不是为了“少用好模型”，而是为了把好模型用在刀刃上。

Fable/Opus 应该像会议室里最后拍板的专家，而不是从早到晚跑腿打印材料的人。

Advisor Tool：Sonnet 干活，Fable/Opus 把关

第一种实现手段，是 Advisor Tool。

它的模式很简单：

1
2
3
4


Sonnet executor
 -> 遇到复杂判断
 -> 调用 Fable/Opus advisor
 -> Sonnet 继续执行

这像什么？

像一个靠谱的项目经理在推进日常工作，遇到架构选型、安全边界、产品取舍这种“错了会很贵”的节点，再把资深专家叫进来。

Advisor 不是另一个执行员，也不是全程陪跑的老板。它更像关键决策时被请进会议室的人。

适合它的任务有几类：

Sonnet 能稳定推进，但中间有少数非显然设计决策
任务链很长，全程用 Fable/Opus 成本过高
需要在关键节点做风险审查、策略纠偏、方案选择
coding agent、computer use、多步研究这类“执行量大、判断点少”的任务

反过来，不适合的场景也很明确：

单轮问答
每一步都需要强推理
任务太小，advisor 调用成本超过收益
executor 还没收集上下文，就急着问 advisor

这里最重要的实践不是“能不能调用更强模型”，而是什么时候调用。

我的判断标准是：

如果这个决策错了，后面会产生大量返工，就值得问 Fable/Opus；如果只是搬资料、改格式、补字段，交给 Sonnet 或更便宜的模型就够了。

Advisor Tool 的价值，正在于它把模型能力做了纵向分层：

角色	适合模型	主要职责
Executor	Sonnet	推进任务、调用工具、落地修改
Advisor	Fable/Opus	复杂判断、风险提示、策略纠偏
User	人	目标定义、偏好确认、最终接受

一句话总结：

Sonnet 负责把车开起来，Fable/Opus 负责在岔路口提醒你别开进沟里。

Managed Agents：把一个大任务拆成一支小队

第二种实现手段，是 Managed Agents。

Advisor 是纵向升级，Managed Agents 是横向分工。

它的基本结构是：

1
2
3
4
5
6


Sonnet coordinator
 -> research worker A
 -> research worker B
 -> validation worker C
 -> review worker D
 -> coordinator 综合结果

每个 worker 有自己的上下文、工具和任务边界。它不需要知道全局目标的所有细节，只要把自己那一小块做好。

这件事非常关键。

很多单体 Agent 的失败，不是因为模型笨，而是因为上下文被污染了：

读了太多网页，噪音进入上下文
工具输出太长，关键信息被淹没
前面一个错误判断影响后面所有步骤
权限全开，风险边界变大
最后模型已经分不清哪些是事实，哪些是推测

Managed Agents 的价值，不是“模型数量变多所以更聪明”，而是三件事：

价值	解释
上下文隔离	每个 worker 只看自己需要看的材料
并行吞吐	多个资料源、多份文件、多条事实可以同时处理
权限隔离	调研 worker 不一定需要写文件，代码 worker 不一定需要外网

回到前面的 AI 编程工具调研案例。

你可以让每个 worker 只负责两个工具：

1
2
3
4
5


Worker A：调研 Cursor、Windsurf
Worker B：调研 Claude Code、Codex
Worker C：调研 Devin、OpenHands
Worker D：调研 Replit Agent、Gemini CLI
Worker E：交叉检查定价和上下文窗口

每个 worker 的输出必须结构化，比如：

1
2
3
4
5
6
7
8
9


工具名称：
官方链接：
Agent 架构：
上下文管理：
工具调用能力：
定价：
适合人群：
不确定点：
引用来源：

这样 coordinator 拿到的不是一堆网页碎片，而是一组可比较的事实卡片。

这就是多 Agent 的正确姿势：worker 负责吞吐，coordinator 负责验收，不要让最终答案变成 worker 摘要的简单拼接。

Plan Big, Execute Small：真正值得偷走的范式

第三篇 cookbook 里最值得记住的，不是那个具体案例，而是它背后的范式：

1
2
3
4
5
6
7
8


Plan Big：
 Sonnet / Fable / Opus 制定计划、定义维度、设计验收标准

Execute Small：
 Haiku / cheaper workers 并行搜索、读取、抽取、验证

Review Hard：
 Sonnet 汇总冲突，Fable/Opus 做最终判断或策略建议

翻译成人话就是：

大模型负责问题定义，小模型负责信息吞吐，强模型负责判断和验收。

这套模式特别适合几类任务：

多网页知识调研
多文件代码库扫描
多产品竞品分析
多事实交叉验证
长文档消化和结构化摘要
“先查很多东西，再做少数关键判断”的工作流

它为什么有效？

因为很多复杂任务的成本结构并不均匀。

你以为最难的是“写最终报告”，其实最费 token 的往往是：

把 20 个网页读完
从文档里抠出字段
对齐不同来源的说法
反复检查链接和引用
整理成统一格式

这些事情需要耐心、覆盖率和结构化输出，但不一定需要 Fable/Opus 级别的判断力。

不过，多 Agent 也不是银弹。

最容易踩的坑有四个：

坑	结果
拆得太碎	调度成本超过收益
worker 输出太自由	coordinator 难以比较和验收
coordinator 只拼接	错误会被包装成“综合结论”
关键证据不保留	最终判断无法追溯

所以，Plan Big, Execute Small 不是“把任务随便丢给一堆小模型”，而是要先设计好三件事：

拆分边界：每个 worker 负责什么，不负责什么。
输出格式：worker 必须交付什么字段、证据和不确定性。
验收标准：coordinator 如何发现冲突、追问缺口、决定是否升级给 Fable/Opus。

怎么选架构：别先问模型，先问任务

很多人在设计 Agent 系统时，第一句就是：

我该用 Sonnet，还是直接上 Opus？

这个问题问早了。

更好的顺序是：

这个任务里，哪些步骤只是读取、搜索、抽取？
哪些节点需要真正的判断？
哪些子任务可以并行？
worker 的输出如何验收？
如果判断错了，返工成本高不高？
Fable/Opus 应该在哪些位置介入，才最值？

你可以用这张表快速判断：

任务类型	推荐方案
单轮问答	直接 Sonnet 或 Fable/Opus
普通工具执行 + 少数复杂判断	Sonnet executor + Fable/Opus advisor
大量网页、文件、事实调研	Sonnet coordinator + cheaper workers
高价值研究报告	Sonnet coordinator + workers + Fable/Opus final review
代码库大规模扫描	Coordinator + specialized workers
每一步都需要深推理	直接 Fable/Opus，少拆
小任务	不要多 Agent，调度成本不值

这里的关键不是“多 Agent 一定比单 Agent 好”，而是：

当任务可以拆、证据可以结构化、验收标准可以定义时，多 Agent 才有意义。

如果任务本身是连续推理，比如数学证明、复杂算法设计、哲学论证，你硬拆成一堆 worker，反而可能把思路打碎。

真正的省钱架构：让每个模型做它最值钱的事

回到开头那个比喻。

Fable/Opus 当然可以读网页、搬资料、整理表格。就像炮弹当然可以打苍蝇。

问题是：你为什么要这么打？

好的 Agent 系统，不是把所有事情都交给最强模型，而是把任务拆成三层：

层级	职责	典型模型
吞吐层	搜索、读取、抽取、初步整理	Haiku / cheaper workers
执行层	调度、工具调用、合并、落地	Sonnet
判断层	架构取舍、风险分析、最终审查	Fable/Opus

最后留下一个很实用的判断：

如果一个步骤没有明显的判断成本，就不要默认交给最贵的模型。
如果一个决策会影响后面大量工作，就不要吝啬请 Fable/Opus 把关。

这才是 Agent 系统真正的省钱架构。

不是不用强模型，而是让强模型出现在它最值钱的位置。

参考资料

后端上下文工程：一个开源工具把 Claude Code 的账单砍掉 2/3

Wed, 22 Apr 2026 00:00:00 +0000

最近我一直在观察一件事：模型越来越强，但 Agent 的账单却越来越贵。

这听起来像个悖论。按理说模型更聪明了，应该一步到位，少走弯路，反而更省 token 才对。但现实里，我自己跑 Claude Code 也好，同事跑 Cursor Agent 也罢，同一个任务，换了更强的模型之后 token 账单反而涨了一截。

前两天刷到 Avi Chawla 写的这篇 How to cut Claude Code costs by 3x，一下子把我憋了好久的一个直觉讲清楚了——问题不在模型，在后端。

更具体点：问题在后端是怎么把自己的状态"交代"给 Agent 的。这件事 Karpathy 在讲上下文工程（context engineering）的时候其实提过，但大部分人只把它当成一个"写 prompt 的技巧"，没意识到后端本身就是上下文的一部分。

一个反直觉的数字

先看一张图，这是 MCPMark V2 跑的基准测试，21 个数据库任务，Supabase 的 MCP server 被调用产生的后端 token 消耗：

Sonnet 4.5：11.6M tokens
Sonnet 4.6：17.9M tokens

模型变聪明了，消耗反而多了 50%。

这个结果第一次看到我是懵的，但仔细想一下其实合理：当后端给出的信息不完整时，更聪明的模型不会"跳过空白"，它会花更多 token 去推理那个空白——多跑几次发现式查询，多重试几次，多尝试几种 workaround。

换句话说，“缺失的上下文"不会因为你换了更好的模型就消失，它只会变得更贵。

为什么 Supabase 的 MCP 是个 token 黑洞

Supabase 本身是个好产品，但它不是为 AI Agent 设计的——MCP server 是后来贴上去的，继承了所有面向人类开发者的设计假设。三个机制直接导致 token 爆炸：

1）文档检索：给一勺米，端来一锅饭

当 Claude Code 要在 Supabase 上配 Google OAuth，它会去调用 search_docs 这个 MCP tool。Supabase 的实现是——每次调用都返回整块 GraphQL schema metadata，token 量是 Agent 实际需要的 5-10 倍。

你问 OAuth 怎么配，它把 email/password、magic link、phone auth、SAML、SSO 全给你一遍。

这个模式发生在每一次 search_docs 调用上——查数据库、查 storage 配置、查 edge function 部署……每次都是一整片 domain 的 metadata dump 下来。一个 session 里光这部分的"文档 overhead"就能消耗掉几千 token，而这些 token 里真正被用上的不到两成。

2）后端状态：Agent 看不到仪表盘

当你作为人类开发者用 Supabase 时，你打开 dashboard，一眼扫过去就知道：启用了哪些 auth provider，有哪些表，RLS 策略是什么，storage bucket 怎么配的，edge function 部署到哪一步了……

Agent 看不到 dashboard。

Supabase 的 MCP 确实暴露了一些状态查询接口——list_tables、execute_sql 之类——但没有一个接口能回答"我这个后端整体长什么样”。Agent 只能一个个工具串着调，每次拿回来一小块，部分信息（比如哪些 auth provider 启用了）甚至根本不在 MCP 里。

这个"拼图式"的状态发现过程本身就烧 token，而且经常拼不完整，要回头补查。

3）错误信息：只告诉你 401，不告诉你为什么 401

出错是必然的，因为 Agent 在猜。而 Supabase 返回的错误是原始错误信息：RLS 拒绝了个 403，edge function 配错了给你 500，就这些。

人类开发者看到错误，会去翻 dashboard、交叉比对日志、查 Supabase 的状态面板，最后定位问题。Agent 没有这个路径，它只能根据错误信息的字面意思去猜可能的原因，改一遍代码，再试一次。

猜错了，再来一轮。每一轮重试都会把之前整个对话历史重新发一遍，token 成本像滚雪球一样涨。

这三个机制一叠加，Sonnet 4.6 这种"推理更深入"的模型反而会把 token gap 拉得更大——因为它每一步探索都更细、更花 token。

上下文工程在后端长什么样

修复方案不是换模型，而是给 Agent 一个结构化的后端上下文，让它不用探索、不用猜。

这正是 Karpathy 说的那句话：

Context engineering: the delicate art and science of filling the context window with just the right information for the next step.

Karpathy 明确把工具和状态列入了 context 的一部分。大部分人把这个概念用在 prompt 和 RAG 检索上，但后端也是上下文窗口的一部分——而且是目前几乎没人在优化的那部分。

InsForge（开源，8k star）就是冲这个问题去设计的。

它提供和 Supabase 类似的原语——Postgres + pgvector、auth、storage、edge functions、realtime——但信息层是按"Agent 消费效率"来组织的。

核心架构是三层协作：

Skills 承载静态知识
CLI 负责直接执行后端操作
MCP 只用来做实时状态查询

每一层解决一个具体问题，为不同原因省 token。

1）Skills：静态知识零往返

InsForge 选择用 Agent Skills 作为主要的知识承载方式——在 session 启动时就直接加载进 Agent context，SDK 用法、代码示例、各种边界情况都不用走 tool call 就能拿到。

而且 Skills 用的是渐进式披露：初始只加载元信息（name、description，大概 70-150 token/skill），只有当 Agent 判断当前任务匹配才加载完整内容。这意味着你可以装上百个 Skills 也不会把 context 撑爆——这是 MCP 的"要么全加载要么不加载"做不到的。

四个 Skill 覆盖全栈，每个都有明确的边界：

Skill	职责
`insforge`	前端代码怎么和后端对话
`insforge-cli`	后端基础设施管理
`insforge-debug`	结构化错误诊断（auth 错、慢查询、edge function 失败、RLS 拒绝等）
`insforge-integrations`	第三方 auth provider（Clerk、Auth0、WorkOS、Kinde、Stytch）

一行命令全装：

1

npx skills add insforge/insforge-skills

2）CLI：给 Agent 的"命令行手柄"

真正执行后端操作——建表、跑 SQL、部署 function、管理 secret——InsForge 把 CLI 作为主要入口，而不是 MCP。

每个命令都支持 --json 输出结构化结果，-y 跳过确认，返回语义化的 exit code，让 Agent 能直接通过返回码判断是 auth 失败、项目不存在还是权限问题。

这个设计的好处是 Claude Code 可以把 CLI 输出接到 jq、grep、awk 管道里，这是同样功能要用 MCP 实现时得连续调用好几次的事情。

Scalekit 跑的对比基准显示：CLI+Skills 在单用户 workflow 里的 token 效率比等价 MCP 方案高 10-35 倍，成功率接近 100%。

一些典型的 Agent 实际执行的命令长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 后端状态探查（Agent 第一件事就干这个）
npx @insforge/cli metadata --json

# 数据库操作
npx @insforge/cli db query "CREATE TABLE posts (...)" --json
npx @insforge/cli db policies

# Edge functions
npx @insforge/cli functions deploy my-handler
npx @insforge/cli functions invoke my-handler --data '{"action":"test"}' --json

# Storage
npx @insforge/cli storage create-bucket documents --json
npx @insforge/cli storage upload ./file.pdf --bucket documents

# 诊断
npx @insforge/cli diagnose db --check connections,locks,slow-queries

Agent 直接 parse JSON，然后根据 exit code 处理错误——干净、确定、可脚本化。

3）MCP：只用来看"活的状态"

MCP 这个路径也保留了，但用途变得很窄——只用来查后端当前的实时状态。

InsForge 的 MCP server 只暴露了一个轻量的 get_backend_metadata 工具，一次调用返回整个后端的拓扑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
 "auth": {
 "providers": ["google", "github"],
 "jwt_secret": "configured"
 },
 "tables": [
 {"name": "users", "columns": ["id", "email", "created_at"], "rls": "enabled"},
 {"name": "posts", "columns": ["id", "title", "body", "author_id"], "rls": "enabled"}
 ],
 "storage": { "buckets": ["avatars", "documents"] },
 "ai": { "models": [{"id": "gpt-4o", "capabilities": ["chat", "vision"]}] },
 "hints": ["Use RPC for batch operations", "Storage accepts files up to 50MB"]
}

一次调用、大约 500 token，Agent 就掌握了整个后端拓扑。其中 hints 字段是 Agent 专用的使用提示，能直接减少 API 误用。

关键的设计选择是：MCP 只做"会变化的状态查询"，不做"静态文档检索"——这和业界默认的用法正好反过来，也是 InsForge 比 Supabase 省 token 的根本原因。

实战对比：用 Claude Code 造同一个 RAG 应用

作者选了一个应用叫 DocuRAG：

Google OAuth 登录
上传 PDF
自动 chunk + embed（text-embedding-3-small，1536 维）
向量存进 pgvector
用户问问题，系统 embed 查询、检索相关 chunk、GPT-4o 生成回答
RLS 隔离不同用户的文档

一次覆盖：auth、storage、documents 表、vector embedding、embedding 生成、chat completion、retrieval edge function、RLS——几乎所有后端原语都碰上了。

同一份 prompt，唯一的差别是 Supabase 版本要声明"LLMs/embedding models via the OpenAI API"（两套系统要接），InsForge 版本只需要"also for the model gateway"（一套系统）。

作者把两次完整的 Claude Code session 录下来了：

顺便提一句录像里没捕捉到的细节：Supabase 那次，Google OAuth 需要手动在 Google Cloud Console 里建 OAuth 2.0 Client ID、配 consent screen、加测试用户、复制 Client ID 和 Secret 粘回 Supabase dashboard——这些都不在 Claude Code 的控制范围内。InsForge 则完全不用这一步。

先看最后的账单：

后端	Token	成本	用户消息	错误报告
Supabase	10.4M	$9.21	12 条	10 条
InsForge	3.7M	$2.81	1 条	0 条

3x 的差距。现在我们看看两次 session 具体发生了什么。

Supabase：10.4M token 的大部分都花在调错上

初始构建其实很顺。

Agent 加载了 supabase skill，用 MCP 的 list_tables、list_extensions、execute_sql 把后端状态摸了一遍，scaffold 了 Next.js 项目，建了库表，写了两个 edge function（ingest-document 和 query-document），部署完成，build 通过。

然后开始翻车。

第一个坑：登录直接不工作

问题在于 Next.js 下 OAuth 回调跑在 server 端，但 Agent 给你装的是客户端 Supabase 库，把 session 存在浏览器里——server 端拿不到，登录整个崩了。

Agent 切到 @supabase/ssr，重写了 session 处理，重新构建——算是过了。

第二个坑：上传文档，连续 8 轮失败

登录修好之后试上传，edge function 报错。我报错 → Agent 改 → 失败 → 再报错 → 再改 → 同一个错。这个循环跑了 8 次：

加 auth header → 同样错误
加日志重新部署 → 同样错误
打印真实错误信息 → 变成 CORS 错误
修 CORS → 回到原来的错误
换一种读取用户 token 的方法 → 同样错误
换另一种鉴权方式 → 同样错误

8 轮之后，Agent 终于说了句：

“The 401s may be happening at the platform’s verify_jwt gate before our code even runs.”

翻译一下：Supabase 在平台层有个自动 token 检查，发生在你的 edge function 代码执行之前。前面换 @supabase/ssr 的时候，新库发送的 token 格式平台层不认，所有请求在"门口"就被拒了，function 代码根本没跑起来——所以 8 轮代码级别的修复全都不对。

解法很简单：关掉平台的自动 token 检查，在 function 内部自己做鉴权。

但这 8 轮里 edge function 被重新部署了 8 次（加上最初的 2 次就是 10 次），每一次重新部署、每一次看日志、每一次重试，都会把越来越长的对话历史重新塞进 context——token 就是这么滚起来的。

Supabase 的最终统计：

12 条用户消息（其中 10 条是报错）
135 次 tool call
30+ 次 MCP 调用
10.4M token
$9.21

InsForge：3.7M token，零错误干预

InsForge 这边，全程没有一次需要我介入的错误。

Agent 第一件事是 npx @insforge/cli metadata --json：

一次返回：auth provider、现有表、storage bucket、可用 AI 模型、realtime channel。Agent 在写任何代码之前就已经对这个后端有了完整认知。

对比 Supabase 那次要调多个 MCP tool 才能拼出类似认知，而且还漏掉了 verify_jwt 这种关键细节——差距在这里就已经拉开了。

Schema 建立跑了 6 条 CLI 命令，全部成功：

启用 pgvector、建 documents 和 chunks 表（带 vector(1536) 列）、在两张表上开 RLS、创建访问策略、建 match_chunks 相似度搜索函数。每一条都返回结构化输出确认执行了什么，Agent 逐步验证。

Supabase 那边的 auth 和 edge function 坑——这边一个都没撞上：

insforge skill 自带了 Next.js 下正确的客户端库用法，Agent 一次写对
两个 edge function（embed-chunks 和 query-rag）因为 embedding 和 chat completion 都在同一个 model gateway 里，直接调就行，不用单独接 OpenAI、不用管第二套 API key、不用处理跨服务鉴权
metadata 里已经列出了 text-embedding-3-small 和 gpt-4o，Agent 通过 InsForge SDK 直接调用

最终：

1 条用户消息
77 次 tool call
0 次 MCP 调用
3.7M token
$2.81

作者让 Claude 生成的对照表：

我自己的体感

看完这个对比，我最大的感慨不是"InsForge 比 Supabase 强"——这不是产品优劣的问题，是架构假设的问题。

我过去几个月用 Claude Code 跑全栈任务，有个特别直观的感受：Agent 花在"搞清楚现在是什么状态"上的 token，常常比"写代码"还多。你看它在那里 ls 来 ls 去，grep 来 grep 去，尝试各种命令去探测配置……每一步都是 token。

Supabase 这类后端本来就是给人类开发者设计的：人类可以看 dashboard、可以翻多个 tab 对比、可以凭经验"感觉到"问题大概在哪一层。Agent 一样都做不到——它只能从你返回给它的字节里推理。

如果后端返回的字节里不包含"verify_jwt 把请求在门口挡掉了"这个信号，它就永远不知道问题在上游，只会在代码层打转。

这件事反过来对我写代码也有启发：当你给 Agent 提供接口或工具的时候，得用"Agent 视角"重新设计一遍返回值——错误信息要结构化、状态查询要原子化、成功失败要有明确的语义码、文档要按任务切片而不是按资源切片。

这不是 nice-to-have，是 cost driver。

Takeaway

如果要我用一句话总结这篇文章的价值：

修的不是模型，也不是 context window，是后端怎么把自己交代给 Agent 这件事本身。

几个可以直接拿走的判断：

Token 账单涨了不一定是模型的锅。先去看看 tool call 的 input/output 形状——尤其是那些每次 dump 一大坨 metadata 的"便利接口"。
MCP 不该用来查文档。静态知识走 Skills（进 context 一次就够），MCP 只留给"活的状态"。这和业界默认用法是反的。
CLI 是被低估的 Agent 接口。--json 输出 + 语义化 exit code + 标准 Unix 管道，在大多数场景比 MCP 工具链更省 token、更易验证。
错误信号的结构，比错误信息的文字更重要。如果你的平台只告诉 Agent “401”，它会花 8 轮去猜 401 是谁发的。
设计后端接口的时候，问自己一个问题：一个刚接入的 Agent，看完我的 metadata/docs/error，能不能一次就知道"下一步该干什么"？如果不能，你的 token 账单就在这里。

InsForge 本身只是这个思路的一个落地，但这个思路是通用的——无论你用什么后端、什么 Agent 框架，“把上下文主动喂过去"永远比"让 Agent 探索式发现"便宜一个量级。

Karpathy 说得对：

填满 context window 的"正确信息”，是做 Agent 最核心的技能。

而后端基础设施，是这些"正确信息"最大的一块来源——而这恰恰是大多数人都还没开始做的地方。

参考资料

原推文：Avi Chawla — How to cut Claude Code costs by 3x
InsForge 开源仓库：github.com/InsForge/InsForge
Karpathy 的 Context Engineering 原贴（作者引用的出处）

Claude-Cookbooks 全景导航：被 README 藏起来的另一半

Sat, 18 Apr 2026 00:00:00 +0000

最近 AI 的发展真的是日行千里。

每天打开手机开源社区、翻公众号、过一遍 GitHub Trending——新模型、新工具、新系统、新应用，再加上无数业内高人分享的实践经验，内容浩如烟海，百家争鸣，百家齐放。

说实话，我自己看着都眼花缭乱。有时候晚上躺下想到"今天又没来得及看那几篇论文、那几个新项目"，连睡觉都觉得是在浪费学习时间。

这种状态持续久了，人是会焦虑的。鬼哥每天拼命学习, 拼命实践, 都快忘了自己还是个吉他手, 也得花时间练琴了.

但前阵子我沉下心来，花了一段时间认真翻了一遍 Anthropic 官方的这份 claude-cookbooks——翻完之后我反倒松了一口气。

这份仓库里的内容，积累了 Anthropic 工程师过去三年对 AI 工程化的思考。覆盖面非常全：从 API 最基础的用法，到 Prompt Caching 的成本优化，到 Tool Use 的各种进阶模式，再到 Agent SDK、Managed Agents、Skills 这些最近才成型的产品形态——几乎把"怎么用好 Claude 做一个能上生产的 AI 应用"这件事，从头到尾挨个讲了一遍。

宝藏是真的多，内容也真的多。想用一两篇文章讲清楚根本不现实。

所以我决定先写这一篇——给这份指南做一个大致的梳理，整理出一份索引地图。 后面每个具体话题，再单独开长文展开。

也建议你把这份 cookbook 当作一份可以反复查、反复学的学习地图：不需要一次读完，但值得在接下来几个月里反复回来翻。

你打开 anthropics/claude-cookbooks 的 README，看到的大概是十几条链接——分类、RAG、摘要、几个 tool use 示例、一篇 prompt caching。

如果你只看 README，会以为这就是一份写了两年没人管的老项目。

但你往目录里翻一下就会发现——这份仓库里塞着接近一百篇 notebook，README 里能看到的，大概只占三分之一。

被 README 藏起来的另一半，恰恰是这两年 Anthropic 官方重点推进的东西：Claude Agent SDK 教程、Managed Agents 的 CMA 系列、Skills 技能包、Tool Use 的进阶玩法、Extended Thinking 和 Tool Search 的新模式……这些内容散落在 claude_agent_sdk/、managed_agents/、skills/、patterns/agents/ 这些 README 完全没提的目录下。

这篇文章做的事很简单：把这份 repo 按主题重新整理成一张可以反复查的索引地图。 每个模块一句话定位、列出具体 notebook 文件名、说清楚什么时候该看它——后面想逐篇深入的时候，翻这一页就知道从哪下手。

不做深度拆解，只做导航。真正的"为什么要这么设计"那种长文，留给后面每个主题单开一篇来写。

一、先把这份 repo 的定位搞清楚

在往下看之前，先明确一件事：claude-cookbooks 不是文档的补充，而是可跑的工程示例库。

Anthropic 官方的内容资源现在大致分成三层：

资源	角色	面向
docs.claude.com	权威文档	查 API 参数、模型特性
anthropics/courses	入门课程	第一次接触 API 的开发者
anthropics/claude-cookbooks	工程菜谱	已经会调 API、想把某个具体场景做好的人

Cookbook 是"可执行的最佳实践"：每个 notebook 就是一个最小可跑的场景，装完依赖、填上 API key 就能复现。它的价值不在于"教你 Claude 是什么"，而在于"别人做过这件事，代码给你抄走"。

换句话说，文档告诉你某个 API 参数是什么意思，cookbook 告诉你在真实场景里这个参数应该怎么配、还要和哪几件事配合用。这两者是互补的——文档适合查细节，cookbook 适合找套路。

这也解释了为什么它的更新节奏跟着 Anthropic 的产品线走——每出一个新产品或新能力，这里就会多一个目录。Claude Agent SDK 发布之后有了 claude_agent_sdk/，Managed Agents 发布之后有了 managed_agents/，Skills 功能上线之后有了 skills/。所以它也是观察 Anthropic 官方工程重点转向的一个风向标。

一个小提醒：README 里的链接还是旧的 anthropic-cookbook 仓库路径（目录名对，仓库名已改成 claude-cookbooks）。clone 的时候用新名字，跟着链接点进去会被 GitHub 自动重定向，不影响看内容，但会让你怀疑自己是不是 clone 错了库。

二、一张总览图：20 多个目录怎么归类

仓库里大大小小二十多个目录，我按"使用场景"把它们重新归了一下组：

大类	涉及目录	解决的问题
基础能力	`capabilities/` `multimodal/` `extended_thinking/`	Claude API 开箱即用能做的事
Tool Use	`tool_use/`	让模型调用外部工具
性能与成本	`misc/`（caching/batch 部分） `observability/`	Prompt caching、批处理、用量监控
Agent 三条路径	`patterns/agents/` `claude_agent_sdk/` `managed_agents/`	从模式→SDK→托管运行时的递进
Skills 技能包	`skills/`	打包专业能力给 Claude 调用
第三方集成	`third_party/`	Pinecone / Voyage / Mongo / Wolfram 等八家
评估与微调	`tool_evaluation/` `finetuning/` `misc/building_evals.ipynb`	Prompt eval、工具 eval、Bedrock 微调
工程实践（meta）	整个仓库的组织方式	uv / ruff / registry / slash commands

接下来按这个骨架一层层往里翻。

三、基础能力层：Claude API 开箱即用能做什么

3.1 `capabilities/` — 经典的 NLP 任务

这是整个 cookbook 里最"传统"的一块，也是大部分教程会从这里开始的原因——这些任务不依赖任何高级特性，一个 API key 就能跑：

classification/ — 文本分类。几个 prompt 模式对比，从 zero-shot 到 few-shot 到带 chain-of-thought 的长 prompt。
summarization/ — 摘要。包括长文分块摘要、多文档合并摘要、以及"按角色视角写摘要"这种进阶玩法。
retrieval_augmented_generation/ — RAG。从最基础的"向量检索 + 拼 prompt"到带 rerank、混合检索的几种设计。
contextual-embeddings/ — 这是比较新的一篇，讲 Anthropic 自己提出的"给每个 chunk 加一段上下文描述再 embed"的做法，在某些场景上能显著提升召回。
text_to_sql/ — 自然语言转 SQL，包括 schema 注入、错误恢复、结果校验。
knowledge_graph/ — 用 Claude 从文本抽取三元组、构建图谱。

如果你是刚开始用 Claude API 做项目，这块是"背景知识"——不是每篇都要精读，但至少扫一遍标题，知道什么场景能在这里找到参考实现。

contextual-embeddings/ 这篇值得单独提一下。传统 RAG 的 embedding 过程是直接把 chunk 扔进 embedding 模型，但很多 chunk 脱离上下文后其实没法检索——比如一段"它在第三季度增长了 12%"，没有"哪家公司 / 哪个产品"的上下文，embedding 向量就很泛。Anthropic 的做法是先用 Claude 给每个 chunk 生成一段上下文描述（“这段来自 XXX 公司 2024 Q3 财报的营收章节”），再和原文拼在一起去 embed。实测在有些场景上能把召回率提升 35% 以上，代价是 embedding 阶段的 prompt caching 必须做好，不然成本会飙。

3.2 `multimodal/` — 视觉能力

Claude 的 vision 能力现在已经是基础配置，这个目录把"怎么用好它"讲了一圈：

getting_started_with_vision.ipynb — 入门。base64 编码、URL 传图、多图一起传的几种姿势。
best_practices_for_vision.ipynb — 最佳实践。图片放在 prompt 的哪个位置、多图之间怎么编号、什么时候该先 OCR 再喂文字。
reading_charts_graphs_powerpoints.ipynb — 图表解读。财报柱状图、流程图、PPT 截图的实战。
how_to_transcribe_text.ipynb — 表单/手写稿 OCR。
crop_tool.ipynb — 让 Claude 自己决定"先裁图再看细节"的分步处理。
using_sub_agents.ipynb — 用 Haiku 做前置视觉处理，Opus 做最终决策的 sub-agent 模式。

3.3 `extended_thinking/` — 让模型"想得更久"

Extended Thinking 是 Claude 4 系列引入的能力，让模型在给出答案前先做一段内部推理：

extended_thinking.ipynb — 基础用法。怎么打开、thinking budget 怎么设、拿到的 thinking block 长什么样。
extended_thinking_with_tool_use.ipynb — 和 tool use 结合。这个组合比较微妙——model 在 tool call 之间保留 thinking context 的方式跟普通对话不一样，这一篇讲清楚了边界。

四、Tool Use 专题：整个 cookbook 最密的一块

tool_use/ 目录是更新最频繁、内容也最厚的一块。里面的 notebook 粗粗可以分成"基础用法"和"进阶玩法"两层：

基础几篇，先过一遍：

calculator_tool.ipynb — 第一次接触 tool use 必看，一个最简单的计算器示例。
tool_choice.ipynb — auto / any / tool（强制某个具体工具）三种模式的区别。
parallel_tools.ipynb — 一次响应里并发调多个工具。
extracting_structured_json.ipynb — 用 tool use 强制返回结构化 JSON，比裸 prompt 稳定得多。
tool_use_with_pydantic.ipynb — 直接用 Pydantic 模型定义 tool schema。
customer_service_agent.ipynb — 经典的客服机器人综合示例。

进阶部分，每篇都是一个独立课题：

memory_cookbook.ipynb + memory_tool.py — Claude 的 memory tool，让模型能读写自己的记忆文件。
programmatic_tool_calling_ptc.ipynb — PTC（Programmatic Tool Calling）。让 Claude 生成一段小代码来决定怎么调用一组工具，而不是一个个手动编排。
automatic-context-compaction.ipynb — 自动上下文压缩。长对话里如何在触发上限前让模型自己"总结前面然后丢掉"。这一篇和我之前写过的 Session 管理文章其实是同一套思路的底层实现。
tool_search_with_embeddings.ipynb + tool_search_alternate_approaches.ipynb — 工具太多塞不进 prompt 的时候怎么办。用 embedding 召回最相关的工具再喂给模型。
vision_with_tools.ipynb — 把 vision 输入和 tool use 混在一起用的注意事项。
threat_intel_enrichment_agent.ipynb — 威胁情报富化 Agent，一个比较完整的垂直场景实战。
context_engineering/ 子目录 — 专门讲上下文工程的一组 notebook，是相对独立的小专题。

这个目录是我个人会反复回来查的。基本上做任何一个需要"让模型调用外部能力"的项目，都能在这里找到至少一个相近的参考实现。

特别想点名 PTC 和 Tool Search 这两篇。 PTC（Programmatic Tool Calling）解决的是"工具编排逻辑比工具本身还复杂"的场景——比如你有 10 个工具需要按特定顺序调用并做中间结果处理，与其让模型一轮一轮 tool call，不如让它一次性生成一段编排代码，由你在沙箱里执行。这种做法在复杂工作流里能把 round-trip 次数从十几轮压到两三轮，延迟和成本都是数量级的改善。

Tool Search 解决的是另一类问题：工具数量多到塞不进 prompt。一个大型 Agent 系统可能挂了几百个 MCP 工具，全部塞进去既超 token 又污染模型判断。用 embedding 预先对工具做语义索引，按用户 query 召回 top-K 工具再喂给模型，是目前比较成熟的解法。这一篇讲清楚了实现细节和几种 trade-off。

五、性能与成本优化

做 Demo 的时候钱和速度都不敏感，但一旦到线上，成本和延迟立刻就会成为第一优先级问题。 这块内容散落在几个目录里，我挑出来单独放一节：

misc/prompt_caching.ipynb — Prompt caching 的基础用法。配合我之前那篇 Prompt Caching 深度拆解一起看效果最好：那篇讲"为什么要这么做"和底层 KV cache 原理，这篇告诉你"具体几行代码怎么写"。
misc/speculative_prompt_caching.ipynb — 推测式缓存。不等用户发消息，提前把可能的下一轮 prompt 预热进缓存。在某些低延迟场景下能把首 token 延迟打下去很多。
misc/batch_processing.ipynb — Message Batches API。离线批处理的价格是实时请求的 50%，跑评测、做回填数据时能省很多。
misc/session_memory_compaction.ipynb — 会话记忆压缩。和 tool use 里的 automatic-context-compaction 是配套关系，一个讲工具侧，一个讲消息侧。
observability/usage_cost_api.ipynb — Usage & Cost API。用来做团队用量看板、成本归因报表。
misc/using_citations.ipynb — Citations 功能。让 Claude 在回答里标注"这句话来自文档的哪一段"，做 RAG 产品时非常有用。
misc/sampling_past_max_tokens.ipynb — 当输出被 max_tokens 截断时怎么优雅续写。

这几篇单独看每一个都不长，但组合起来基本就是一个"线上项目优化清单"。上线前对着这张清单过一遍，能省下不少成本和踩坑时间。

有一个非常容易被忽略的组合用法：prompt caching + batch processing。Batch API 本身就打 5 折，再加上 caching 命中的部分又打 1 折左右，叠加下来做离线大规模推理时的成本可以比天真实现低 85% 以上。如果你在做评估、数据标注、回填历史数据这类离线任务，这个组合的经济性优势非常大，但大多数人做 MVP 时根本不会想到要用它。

六、Agent 的三条进阶路径

这是整个 cookbook 里我认为最值得花时间的一块，也是 README 最没讲清楚的一块。

Anthropic 把"怎么构建 Agent"拆成了三个层次递进的目录：

1
2
3


patterns/agents/ ← 模式层：概念和套路（轻量）
claude_agent_sdk/ ← SDK 层：用 Agent SDK 自己组装（中等）
managed_agents/ ← 托管层：用 Managed Agents 托管运行时（重型）

从左到右是"自由度递减、工程量递减"的关系。 哪一层适合你，取决于你要做的系统规模和运行需求。

6.1 模式层 `patterns/agents/` — 先把套路搞清楚

这个目录对应的是 Anthropic 那篇著名博客 Building Effective Agents 里提的几种基础模式的可运行版本：

basic_workflows.ipynb — Prompt chaining / Routing / Parallelization 三种基础工作流模式。
evaluator_optimizer.ipynb — 评估者-优化者模式。一个 Agent 输出、另一个 Agent 打分并反馈，循环到满足条件为止。
orchestrator_workers.ipynb — 编排者-工人模式。主 Agent 拆任务，子 Agent 并发执行。

这三篇是"概念打底"。哪怕你最后不用 Agent SDK，看一遍这三个模式，再去评估任何第三方 Agent 框架的设计，心里都会有一把尺子。

6.2 SDK 层 `claude_agent_sdk/` — 官方的 Agent 教程

这是 Anthropic 最近重点推进的一块，基于 claude-agent-sdk-python，六篇 notebook 是一条渐进式的教学路径：

#	文件	学到什么
00	`00_The_one_liner_research_agent.ipynb`	一行 `query()` 起一个研究 Agent，理解异步迭代和基础概念
01	`01_The_chief_of_staff_agent.ipynb`	CEO 助理 Agent——Memory、Output Styles、Plan Mode、Slash Commands、Hooks、子 Agent 编排全家桶
02	`02_The_observability_agent.ipynb`	可观测性 Agent，需要 GitHub Token + Docker
03	`03_The_site_reliability_agent.ipynb`	SRE Agent，处理告警和事故
04	`04_migrating_from_openai_agents_sdk.ipynb`	从 OpenAI Agents SDK 迁移过来的映射指南——有存量代码的团队重点看这篇
05	`05_Building_a_session_browser.ipynb`	Session 浏览器 demo，可视化 Agent 会话

这一条路径的隐含逻辑是：“你如果已经在用 Claude Code，那 Claude Code 背后的 Agent 内核就是 Agent SDK，你可以用同样的工具链做任何 Agent 应用，而不只是软件开发”。

01 这篇 Chief of Staff 我单独推荐——它是整个教程里最接近"生产级 Agent 到底长什么样"的那篇。里面把持久化记忆（CLAUDE.md 机制）、输出风格切换（给 CEO 发邮件 vs 给团队发内部备忘是两种语气）、Plan Mode（复杂任务先产出方案再执行）、Slash Commands（把高频操作做成可复用快捷方式）、Hooks（每次工具调用都自动写审计日志）、Subagent 编排（法务/财务/战略三个专项 Agent 分工协作）这一整套都串起来了。看完之后你会意识到，“Agent” 这个概念背后其实是一组工程约束的组合，单独拎出任何一个都不够，组合起来才是真正可以上生产的东西。

6.3 托管层 `managed_agents/` — Claude Managed Agents (CMA)

Managed Agents 是 Anthropic 相对较新的一个产品形态：服务端托管的 Agent 运行时，带沙箱、会话持久化、文件状态保留，你只要定义 Agent 和环境，剩下的交给托管服务。

这个目录分成两组：

三个应用型示例（适合先看，建立直觉）：

data_analyst_agent.ipynb — CSV 进、HTML 分析报告出的数据分析 Agent。
slack_data_bot.ipynb — 把上面那个分析 Agent 包成 Slack Bot。
sre_incident_responder.ipynb — 告警→调查→PR→人审→合并的完整 SRE 流程。

六个教程型 notebook（以 CMA_ 开头，建议按顺序读）：

Notebook	主题
`CMA_iterate_fix_failing_tests.ipynb`	入门。引入 agent / environment / session、文件挂载、流式事件循环
`CMA_orchestrate_issue_to_pr.ipynb`	issue → 修复 → PR → CI → 人审 → 合并的完整编排
`CMA_explore_unfamiliar_codebase.ipynb`	在陌生代码库里探索，含"过期文档陷阱"演示
`CMA_gate_human_in_the_loop.ipynb`	人类审批关卡，用自定义工具的 `decide()` / `escalate()` 模式
`CMA_prompt_versioning_and_rollback.ipynb`	提示词版本化与回滚——生产 Agent 的脆弱环节，中文圈讲得很少
`CMA_operate_in_production.ipynb`	生产部署：MCP 工具集、vault 存 per-user 凭证、webhook idle 模式

这一组是目前 cookbook 里最贴近"企业级 Agent 运营"的内容。如果你在做 B 端 Agent 产品，哪怕不用 Managed Agents，也强烈建议看一遍 prompt versioning 和 operate in production 这两篇——它们把"Agent 上线之后你还要做哪些事"讲得最清楚。

稍微展开一下 CMA_prompt_versioning_and_rollback.ipynb 为什么特别值得看：传统软件工程里代码改动有 Git、有 CI、有灰度发布，但 prompt 的改动目前很多团队还靠 Excel 或 Notion 维护。Prompt 不是代码但比代码更脆弱——同一个字改一下，模型行为可能完全变样。这篇 notebook 给出的答案是把 prompt 也纳入版本化体系：服务端存版本、每个 session 可以绑定到特定版本、用标注过的测试集做版本对比、发现回归可以按 session ID 批量回滚。这套工作流不依赖 Managed Agents 本身也能借鉴——核心思路是把 prompt 当成一等公民的配置来治理。

七、Skills 技能包

skills/ 目录对应的是 Claude 的 Skills 功能——打包好的"专业能力"，Claude 在需要的时候自动发现并加载。

核心理念是 Progressive Disclosure：技能定义不在每轮对话里都加载，只在模型判断"这个任务需要 Excel 能力"时才把 Excel skill 拉进来，从而节省 token。

这个目录下有三篇 notebook：

notebooks/01_skills_introduction.ipynb — 基础：加 beta header、创建第一个 Excel/PPT/PDF。
notebooks/02_skills_financial_applications.ipynb — 金融场景：投资组合报告、多格式工作流（CSV → Excel → PPT → PDF）。
notebooks/03_skills_custom_development.ipynb — 自定义 skill 开发：金融比率计算器、品牌指南 skill。

Skills 这个功能对应的是你在 Claude.ai 里看到的"Claude 帮你直接生成 Excel/PPT"那个能力。如果你想做类似的"让 Claude 产出真正可用的办公文档"的产品，这是唯一的官方路径。

Progressive Disclosure 这个机制值得单独理解一下。传统做法里，你要给模型扩展能力，通常是把所有工具定义、system prompt、知识都塞进每一轮对话——结果是你挂的能力越多，token 成本越高，而且大部分 token 根本用不上。Skills 的思路是把能力拆成有元数据的"技能包"，只在模型判断当前任务需要时才动态加载对应的代码和指令，本质上是一种 lazy loading + capability routing。这个设计思路在做大型 Agent 平台时非常关键，哪怕你不用 Skills 产品本身，理解它的机制对你设计自己的能力注入系统也有参考价值。

八、第三方集成一览

third_party/ 下有八家集成，都是最小可跑的对接示例：

目录	角色	典型场景
`Pinecone/`	向量数据库	RAG 召回
`VoyageAI/`	Embedding 模型	RAG、语义搜索
`MongoDB/`	文档数据库 + 向量搜索	一体化 RAG 后端
`LlamaIndex/`	RAG 框架	和 Claude 一起用的完整 pipeline
`Wikipedia/`	知识源	实时查询百科做事实补充
`WolframAlpha/`	计算/数学	精确数值计算、公式求解
`Deepgram/`	语音转文字	音频输入场景
`ElevenLabs/`	文字转语音	语音输出场景

这块适合按需查阅——你项目里用到哪家就去看哪篇，不需要通读。

九、评估与微调

这两块相对偏"工程化"，但一旦你开始做严肃点的 AI 产品就绕不过去：

misc/building_evals.ipynb — 自动化评估。用 Claude 当 judge 给自己的 prompt 打分。
misc/generate_test_cases.ipynb — 用 Claude 生成测试用例来做对抗性评估。
tool_evaluation/tool_evaluation.ipynb — 工具级评估。Agent 系统里每个 tool 调用是否正确、参数是否合理的专项评估。
misc/metaprompt.ipynb — Metaprompt：让 Claude 帮你写/优化 prompt。
misc/building_moderation_filter.ipynb — 用 Claude 搭内容审核过滤器。
finetuning/finetuning_on_bedrock.ipynb — 在 AWS Bedrock 上微调 Claude，附 datasets/ 示例数据。

微调这块目前官方只出了 Bedrock 路径的教程，直接从 Anthropic API 做 fine-tuning 目前还不是公开能力。

十、仓库工程实践：这本身就是一份"怎么管理 Notebook 项目"的样板

这一节是给另一类读者的——那些在自己团队里也要维护大量 notebook / 示例代码的工程师。

claude-cookbooks 这个 repo 本身的组织方式，其实是一份挺成熟的范本：

用 uv 做包管理。有 uv.lock 和 uv.toml，uv sync --all-extras 一键把所有依赖装齐。相比 pip install -r requirements.txt，速度快一个数量级，也更容易复现。
ruff 做 lint 和 format。行长 100、双引号。Notebook 里放宽了 E402（中间 import）、F811（重定义）、N803/N806（变量命名），这几条放宽对 notebook 写作很实用——Jupyter 里本来就会有大量这种"不优雅但可读"的写法。
pre-commit + Makefile + tox。make check / make fix / make test 三条命令覆盖日常。
registry.yaml + authors.yaml。每篇 notebook 在 registry.yaml 里登记标题、路径、作者、分类，方便后续站点化检索。这是一个很聪明的做法——内容和元数据分离，让 notebook 集合可以被当成一个可查询的数据库来对待。
.claude/ 目录 + 自定义 slash commands。/notebook-review（检查 notebook 质量）、/model-check（校验模型 ID 是不是用了非推荐的日期版本）、/link-review（检查死链）。这几个 slash command 既给人用，也给 CI 用。
lychee.toml。专门的死链检查配置，比自己手写正则靠谱。
CLAUDE.md 里写死模型 ID 规范。明确规定永远用非日期别名（如 claude-sonnet-4-6）而不是 claude-sonnet-4-6-20250514。这种小约定写在 CLAUDE.md 里，让 Claude Code 或其他 Agent 在写示例代码时不会跑偏。

这些细节如果你自己维护过一个 notebook 集合，应该能立刻 get 到它们的价值。我之前维护过几套内部示例代码，最大的痛点就是时间一长没人管，示例里的 API 调用方式和模型名全都过时了。claude-cookbooks 用 CI + slash command + 自动化校验把这件事从"靠人自觉"变成"靠流程保证"，是很值得抄的做法。

另一个细节是 registry.yaml 里每篇 notebook 都登记了分类标签和作者。这看起来只是一个 meta 索引文件，但它背后其实是一个内容运营思路：让示例集合既能被人读，也能被机器查询。未来如果要做一个"按类目筛选的交互式站点"或者"根据用户目标推荐 notebook 的 Agent"，registry.yaml 就是现成的数据源。把内容和元数据分开，永远比把元数据硬编码进 README 要更灵活。

十一、我接下来会按什么顺序往里钻

最后给自己留一份阅读路线图，也供参考：

如果你是第一次用 Claude API：

misc/prompt_caching.ipynb — 先把成本大头的底子打好
tool_use/calculator_tool.ipynb + tool_choice.ipynb — Tool use 基础
capabilities/retrieval_augmented_generation/ — 如果你要做 RAG
multimodal/getting_started_with_vision.ipynb — 如果涉及图像

如果你已经在用 Claude Code，想扩展到自定义 Agent：

patterns/agents/ 三篇 — 先把概念过一遍
claude_agent_sdk/00 → 01 → 04 — 沿着教程走
tool_use/memory_cookbook.ipynb + automatic-context-compaction.ipynb — 长会话 Agent 必备
managed_agents/CMA_operate_in_production.ipynb — 想上线再看这篇

如果你在做 B 端 Agent 产品：

managed_agents/ 全套六篇 CMA 教程
tool_evaluation/tool_evaluation.ipynb + misc/building_evals.ipynb — 评估不能缺
observability/usage_cost_api.ipynb — 成本监控
managed_agents/CMA_prompt_versioning_and_rollback.ipynb — 运营侧

结尾：这只是起点

写到这里回头看，这份 cookbook 里随便挑一个模块展开，都够单独写一篇长文：

Agent SDK 的六篇 notebook 值得一篇一篇拆，特别是 Chief of Staff 那篇里塞了一整套生产级 Agent 该有的能力
Managed Agents 这个新产品形态本身就值得一篇"它和 Agent SDK 到底什么区别"的分析
Tool Use 里的 PTC、Tool Search with Embeddings、Memory Tool 每一个单拿出来都能写一篇技术拆解
Skills 的 Progressive Disclosure 机制和它对 token 经济的影响，是个完整的专题
patterns/agents/ 对应的那三种设计模式，配合实际项目经验聊一聊会很有意思

这些我都打算一篇一篇写。这份导航文章就当是书签——以后每完成一篇深度拆解，就回来把对应的链接加上，让这里慢慢长成一张真正可用的学习路线图。

如果你也在看这份 cookbook，欢迎告诉我你最关心哪个模块，我排序的时候可以参考一下。

参考资料

anthropics/claude-cookbooks — 本文索引的主体
anthropics/claude-agent-sdk-python — Agent SDK 本体
anthropics/courses — 如果你还在更早的阶段，先看这个
Building Effective Agents — Anthropic 官方 Agent 设计方法论
Equipping agents for the real world with Skills — Skills 的设计理念

Gemma 4 深度解析：从「不可用」到「生产级」的 Agent 质变

Sun, 05 Apr 2026 00:00:00 +0000

tau2-bench 从 6.6% 到 86.4%。一个数字，一代模型，从"玩具"到"生产级"。

Google 这次终于想通了，把 Gemma 4 换成了 Apache 2.0 协议——翻译成人话就是：随便用，商用也行，不用给 Google 交保护费。

鬼哥看完技术文档后，脑子里瞬间蹦出了五六个"这个能搞"的想法，手指已经开始不自觉地敲桌子了。本着"先吹牛再干活"的优良传统，我决定先把分析文章写了，然后用业余时间（就是那些本该用来睡觉的时间）挨个撸几个 demo 出来。

至于能不能撸完……关注我就知道了。反正 flag 先立在这里，倒了再说。

一个数字说明一切

2026 年 4 月 2 日，Google 发布了 Gemma 4。

如果你只看一个数字，看这个：tau2-bench（衡量模型自主完成多步骤任务的能力）从上一代的 6.6% 飙升到 86.4%，单代提升超过 13 倍。

这不是某项指标的例行提升。6.6% 意味着模型在 Agentic 任务中几乎不可用——每 15 次尝试只能成功 1 次。86.4% 意味着它可以可靠地自主执行复杂工作流。这是从"实验室玩具"到"生产级工具"的质变。

Gemma 4 基于 Gemini 3 的研究成果构建，在许可证上做了一个重大决定：从自定义许可证切换到 Apache 2.0。这意味着任何企业、任何开发者都可以直接商用，无需和 Google 谈判。在 Meta 的 Llama 系列仍使用限制性许可证的背景下，这是一步有力的棋。

模型家族全景：四种规格，一套架构

Gemma 4 不是一个模型，而是一个家族。四种规格覆盖从手机到服务器的全部场景：

模型	参数量	上下文窗口	目标部署环境	Arena AI 排名
31B Dense	31B	256K	服务器/云端	开源第 3
26B MoE	26B (激活 ~4B)	256K	工作站/高端笔记本	开源第 6
E4B	~4B	128K	笔记本/T4 GPU	-
E2B	~2B	128K	手机/IoT/Raspberry Pi	-

几个值得注意的设计选择：

“E” 代表 Effective。E4B 不是"4B 参数模型"，而是"等效 4B 性能的模型"。Google 在命名上刻意淡化参数量，强调实际效能——这反映了一个行业趋势：参数量不再是核心卖点，效率才是。

26B MoE 是最有意思的一个。它有 128 个小型专家网络，每个 token 只激活 8 个专家加 1 个共享的"always-on"专家。结果是：26B 的知识容量，4B 的推理速度，接近 31B Dense 的质量。这是"用架构换效率"的教科书级实现。

E2B 支持音频输入。在 2B 级别的模型上原生支持语音识别和跨语言翻译，这在之前是不可想象的。这让完全离线的手机端语音助手成为可能。

架构革新：三个关键设计决策

Gemma 4 的性能跃迁不是靠简单堆参数，而是来自三个精巧的架构设计。

1. 混合注意力：局部与全局的交替舞步

传统 Transformer 的注意力机制让每个 token 都"看到"所有其他 token。这在长上下文场景下计算成本爆炸。Gemma 4 的解法很优雅：

局部滑动窗口注意力层：每个 token 只关注周围 512-1024 个 token，处理局部语义
全局全上下文注意力层：每个 token 关注完整上下文，捕获长距离依赖
两种层交替堆叠，最后一层强制为全局层

效果：轻量模型的速度 + 长上下文任务的深度理解。你不需要在"快"和"聪明"之间选一个。

2. 双 RoPE 位置编码策略

位置编码决定了模型"理解位置关系"的能力。Gemma 4 根据注意力层类型使用不同的 RoPE 变体：

滑动窗口层：标准 RoPE（局部位置信息已经足够精确）
全局层：Proportional RoPE（在超长距离上仍能保持位置感知质量）

这个看似微小的区分，是 256K 上下文窗口不"退化"的关键。很多模型声称支持长上下文，但实际上在超过 32K 之后质量急剧下降。Gemma 4 通过分层设计绕过了这个问题。

3. MoE 的"以小搏大"哲学

26B MoE 模型的专家设计值得细看：

128 个小型专家（不是传统的 8-16 个大专家）
每个 token 激活 8 个，外加 1 个共享的 always-on 专家
共享专家处理通用语义，激活专家处理特定领域知识

为什么选择"多而小"而不是"少而大"？更多专家意味着更细的专业化粒度。想象一下：8 个全科医生 vs 128 个专科医生中挑 8 个——后者在特定问题上的精度会高得多。而共享专家则确保基础能力不会因为过度专业化而丢失。

基准对决：Gemma 3 vs Gemma 4

数字不说谎。以下是 Gemma 4 在核心基准上的表现：

31B Dense 模型

基准	测量内容	Gemma 4 得分
MMLU Pro	通用知识与推理	85.2%
AIME 2026	数学竞赛题	89.2%
tau2-bench	Agentic 任务自主完成	86.4% (上代 6.6%)

26B MoE 模型（以 ~4B 的速度运行）

基准	得分
AIME 2026	88.3%
LiveCodeBench	77.1%
GPQA Diamond (研究生级科学推理)	82.3%

小模型也不弱

基准	E4B	E2B
AIME 2026	42.5%	37.5%
LiveCodeBench	52.0%	44.0%

几个值得玩味的对比：

26B MoE vs 31B Dense：在 AIME 2026 上，MoE 拿到 88.3%，仅比 Dense 的 89.2% 低不到 1 个百分点。但 MoE 的推理速度是 Dense 的好几倍。对于绝大多数应用场景，MoE 都是更优选择。

E4B 的性价比：一个能在 T4 GPU（约 $0.35/小时）上运行的模型，在 LiveCodeBench 上拿到 52%——这已经超过了一年前很多云端大模型的水平。

tau2-bench 的代际飞跃：从 6.6% 到 86.4%，这不是渐进提升，是质变。之前开源模型在 Agent 场景中几乎是装饰品，现在它们可以真正干活了。

五个有趣的实际应用

架构和基准只是开始。真正让人兴奋的是 Gemma 4 打开的应用可能性。

应用一：离线法律合同分析师

场景：律师事务所需要 AI 辅助审查合同，但客户数据绝对不能上传到任何云端。

方案：在事务所内网服务器上部署 Gemma 4 26B MoE 模型。律师拍摄或扫描合同 → Gemma 4 的视觉能力直接解析文档图片 → 提取关键条款（违约金、竞业限制、知识产权归属）→ 用 Function Calling 调用内部案例数据库比对历史判例 → 生成结构化风险评估报告。

为什么现在可行：

视觉能力原生支持文档 OCR、表格解析
Function Calling 从训练阶段内置，不是指令微调的"权宜之计"
26B MoE 以 4B 速度推理，单卡就能跑
Apache 2.0 许可证，商用零障碍

有趣之处：一年前，这种应用需要 GPT-4 级别的云端模型 + 一套复杂的数据脱敏管道。现在，一台配 RTX 4090 的工作站就能完成全部工作，数据始终不出内网。

应用二：手机端实时语音翻译器

场景：出国旅行，对方说日语/阿拉伯语/泰语，你需要即时理解。

方案：Gemma 4 E2B 运行在手机本地。打开 App → 对方说话 → E2B 的原生音频输入能力直接处理语音 → 跨语言翻译 → 屏幕显示中文翻译文本。全程离线，无需网络。

性能数据：

Qualcomm Dragonwing IQ8 NPU 上：3,700 prefill / 31 decode tokens/s
支持 140+ 语言

有趣之处：Google Translate 也能做这件事，但它需要网络。在地铁里、在信号差的乡村、在出国时没买当地流量的情况下，一个完全离线且支持 140+ 语言的翻译器，才是真正的"随身翻译"。而这个模型只有 2B 参数。

应用三：产线边缘质检 Agent

场景：电子元器件工厂需要对 PCB 板进行实时视觉质检。

方案：NVIDIA Jetson Orin Nano 部署 Gemma 4 E4B。高速相机拍摄 PCB 板 → E4B 视觉模型实时检测焊点虚焊、元件偏移、短路等缺陷 → 检测到问题时通过 Function Calling 触发分拣机械臂 → 异常数据本地存储用于质量追溯。

为什么比传统方案更好：

传统视觉质检依赖预设规则，遇到新型缺陷需要重新编程
Gemma 4 可以用自然语言描述缺陷：“焊点面积不足”、“电容倾斜超过 15 度”
支持多步推理：不只是"检测"，还能"判断严重程度"和"建议处理方式"

有趣之处：这本质上是给每条产线配了一个"有经验的质检工程师"。传统 CV 方案只能说"这里有异常"，Gemma 4 能说"U23 芯片第 4 脚虚焊，建议回流焊复检，严重度 Medium"。

应用四：个人代码审查 Agent

场景：独立开发者或小团队没有专职 reviewer，需要 AI 辅助代码审查。

方案：本地运行 Gemma 4 26B MoE。git hook 在 commit 时触发 → Agent 读取 diff → 调用 linter/type checker 等工具 → 检查安全漏洞（SQL 注入、XSS 等）→ 查阅项目的 CONTRIBUTING.md 了解编码规范 → 生成结构化审查意见（JSON 格式），包含文件路径、行号、问题描述、修复建议和严重等级。

Agentic 工作流示意：

1
2
3


[读取 diff] → [思考：这段代码在做什么？] → [调用 eslint]
→ [思考：eslint 报了 3 个问题，但其中 1 个是 false positive]
→ [调用 grep 检查是否有类似模式] → [生成结构化审查报告]

有趣之处：tau2-bench 86.4% 的意义在这里体现——Agent 需要自主决定"接下来调用什么工具"，而不是按预设脚本执行。一个能可靠完成 5-6 步决策链的 Agent，才是真正有用的 reviewer，而不只是一个高级 linter。

应用五：会议手写笔记 → 结构化文档

场景：开会时习惯手写笔记，但事后需要整理成电子文档分享给团队。

方案：用手机拍摄手写笔记（可以是多页、混合图表和文字）→ Gemma 4 E4B 在本地处理 → 识别手写文字（支持中英混排）→ 理解笔记的逻辑结构（标题、要点、子项、箭头表示的关系）→ 输出结构化 Markdown 文档，包含层级标题、待办清单、关键决策高亮。

为什么不是普通 OCR：

普通 OCR 只做字符识别，不理解结构
Gemma 4 理解"箭头"表示因果关系、“圈起来的"表示重点、“问号"表示待确认
128K 上下文窗口支持一次性处理十几页笔记
支持手写中文识别（Gemma 4 原生支持 140+ 语言）

有趣之处：这个应用看起来简单，但它戳中了一个真实痛点。很多人（尤其是高管和研究者）仍然偏好手写笔记——但手写笔记的最大问题是"写完就忘”。一个能在手机上 3 秒内把手写草稿变成可搜索、可分享的结构化文档的工具，真的会改变记笔记这件事的体验。

开源 AI 的分水岭时刻

Gemma 4 的发布不只是"又一个开源模型”。它标志着几个趋势的交汇：

Apache 2.0 改变了游戏规则。 Meta 的 Llama 系列使用自定义许可证，对月活超过 7 亿的应用有限制。Google 选择 Apache 2.0 等于说：不管你是初创公司还是大厂，拿去用，不收钱，不设限。这会加速企业采用开源模型的步伐。

边缘 AI 从愿景变成现实。 一年前，“在手机上运行大模型"还是一个需要大量妥协的概念验证。现在，Gemma 4 E2B 在手机上做语音识别、图像理解、多语言翻译，且性能数据令人信服。AI 应用的成本结构和隐私模型正在被重写。

Agent 从"能跑"变成"能用”。 tau2-bench 13 倍的提升意味着：开源模型在 Agentic 场景首次具备生产级可靠性。之前你只能把 Agent 当辅助工具（最终还是人拍板），现在你可以开始设计"Agent 自主完成，人做最终审核"的工作流了。

生态闭环正在形成。 Google 明确表示：为 Gemma 4 写的代码将自动适配后续的 Gemini Nano 4 设备。这意味着今天基于 Gemma 4 开发的应用，未来可以无缝迁移到 Google 的系统级 AI 芯片上。开发者投入不会浪费。

回到开头那个数字：6.6% → 86.4%。

这不只是一个基准分数的提升。它代表了一种可能性的转变：开源 AI 模型不再只是云端闭源模型的低配替代品，而是在特定场景（边缘部署、数据隐私、离线运行、商业自由度）下的更优选择。

当最好的开源模型在关键指标上接近甚至追平闭源模型，同时在部署灵活性和商业许可上全面领先——这才是真正的分水岭。

解剖 Claude Code（三）：Prompt 缓存分割与四级上下文压缩

Sat, 04 Apr 2026 00:00:00 +0000

一个 AI Agent 的核心竞争力不在于它调用了多好的模型，而在于它的主循环有多健壮。Claude Code 的心脏是 query.ts 中一个 1,700 行的 while(true) 循环——本篇逐阶段拆解它。

本文为「解剖 Claude Code」系列第三篇。前篇：解剖 Claude Code（二）：ReAct 循环

问题

一个典型的 Claude Code 会话可能持续几十轮。每一轮都要把完整的系统提示、对话历史、工具定义发给 API。如果不做优化：

系统提示：~10K Token，每轮都重复发送
工具定义：50 个工具的 Schema，~15K Token
对话历史：逐轮增长，最终撑爆上下文窗口（200K Token）

不做缓存 = 每轮重复支付这些 Token 的输入费用。不做压缩 = 对话最终无法继续。

Claude Code 的解法是两套机制联合工作：

Prompt 缓存分割：把不变的部分标记为全局可缓存，只为变化的部分付费
四级上下文压缩：当对话增长时，逐级压缩保留核心信息

在整体架构中的位置

1
2
3


ReAct 循环的每一轮：
 Phase 1: 上下文准备 ← 四级压缩在这里运行
 Phase 2: 模型调用 ← 缓存分割在这里生效

Part 1：Prompt 缓存分割

核心思想：静态 vs 动态

Claude Code 将系统提示在物理上分为两部分，用一个边界标记隔开：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


┌─────────────────────────────────────────────────┐
│ STATIC（全局缓存，scope: 'global'） │
│ │
│ · 身份声明（"You are an interactive agent..."） │
│ · 系统指南（工具使用、权限、压缩规则） │
│ · 任务执行指南 │
│ · 操作安全指南（可逆性、爆炸半径） │
│ · 工具使用规范（Bash vs 专用工具） │
│ · 语气风格（无 emoji、简洁） │
│ · 输出效率指南 │
│ │
├──── SYSTEM_PROMPT_DYNAMIC_BOUNDARY ──────────────┤
│ │
│ DYNAMIC（不缓存，每轮重新计算） │
│ │
│ · 会话引导（Agent 类型相关指令） │
│ · 记忆内容（loadMemoryPrompt()） │
│ · 环境信息（模型 ID、平台、Shell、OS） │
│ · MCP 服务器指令（服务器随时连接/断开） │
│ · Scratchpad 目录 │
│ · 语言偏好 │
│ · 输出风格 │
│ │
└─────────────────────────────────────────────────┘

边界标记是一个常量字符串：

1

export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'

三种缓存范围

系统提示被分割成最多 4 个 TextBlockParam，每个有不同的 cache_control：

块	内容	cache_control.scope	含义
1	归属头（Attribution）	`null`	不缓存，每请求元数据
2	CLI 前缀	`null`	不缓存
3	静态内容（边界前）	`'global'`	跨组织缓存，所有用户共享
4	动态内容（边界后）	`null`	不缓存，用户/会话特定

为什么分 global 和 org？

global 缓存：所有 Anthropic 1P 用户共享。当你发送和另一个用户完全相同的静态系统提示时，直接命中缓存——零写入成本
org 缓存：组织内共享（Bedrock/Vertex 3P 用户的默认）
无 scope（ephemeral）：仅当前请求链，5 分钟 TTL

cache_control 的返回结构：

1
2
3
4
5


{
 type: 'ephemeral',
 ttl?: '1h', // 符合条件时升级到 1 小时
 scope?: 'global', // 1P 用户的静态内容
}

TTL 升级：从 5 分钟到 1 小时

默认 TTL 是 5 分钟（ephemeral）。对于付费订阅用户，可以升级到 1 小时：

升级条件（三项都要满足）：

内部用户或 Claude AI 订阅者（非超额使用）
查询来源在 GrowthBook 白名单内（repl_main_thread*, agent:* 等）
Bedrock 3P 用户需显式 opt-in

为什么 TTL 决策要"锁存"（latch）？ 如果用户在会话中途切换了订阅状态（如用量超额），TTL 可能从 1h 变回 5m，导致 ~20K Token 的缓存前缀失效。锁存确保 TTL 在整个会话中保持稳定。

Section 缓存机制

动态部分内部也有缓存优化。每个 prompt section 分为两类：

1
2
3
4
5
6
7
8
9


// 缓存 section：会话级别复用，/clear 或 /compact 时失效
systemPromptSection('env_info', async () => {
 return `Model: ${modelId}, Platform: ${platform}...`
})

// 非缓存 section（危险！每轮重算）
DANGEROUS_uncachedSystemPromptSection('mcp_instructions', async () => {
 return buildMcpInstructions(mcpClients)
}, 'MCP servers connect/disconnect mid-session')

为什么 MCP 指令不能缓存？ 因为 MCP 服务器可能在会话中途连接或断开。如果缓存了旧的服务器列表，模型会尝试调用不存在的工具。

DANGEROUS_ 前缀是刻意的命名——它强制开发者思考"为什么这个 section 不能缓存"，并通过第二个参数写下原因。

工具 Schema 的缓存稳定性

第 02 篇提到，工具注册表按名称排序以保护 Prompt Cache。这里看看具体怎么做的：

工具 Schema 通过 getToolSchemaCache() 会话级缓存
缓存 key 是 ${tool.name}:${jsonStringify(schema)}
每次请求只叠加 defer_loading、cache_control、eager_input_streaming 等运行时属性
如果工具列表稳定（名称和 Schema 不变），缓存前缀不受影响

缓存断裂检测：系统还有一个 promptCacheBreakDetection.ts 模块，监控 cache_read_input_tokens 的变化。如果缓存读取 Token 骤降 > 2,000 且 < 上次的 95%，说明缓存被打破了——系统会记录事件用于诊断。

Part 2：四级上下文压缩

当对话持续增长，四级压缩体系逐级介入：

触发阈值

1
2
3
4


上下文窗口 = 200,000 Token（默认）
摘要预留 = 20,000 Token（给压缩模型留空间）
有效窗口 = 200,000 - 20,000 = 180,000 Token
自动压缩阈值 = 180,000 - 13,000 = 167,000 Token

阈值	值	含义
`AUTOCOMPACT_BUFFER_TOKENS`	13,000	自动压缩的缓冲区
`WARNING_THRESHOLD_BUFFER_TOKENS`	20,000	UI 警告阈值
`ERROR_THRESHOLD_BUFFER_TOKENS`	20,000	UI 错误阈值
`MANUAL_COMPACT_BUFFER_TOKENS`	3,000	手动压缩的阻塞阈值
`MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES`	3	熔断器上限

第一级：Snip（轻量裁剪）

特性门控：HISTORY_SNIP

最轻量的压缩——直接移除旧消息。不做摘要，不做总结，就是删除。

保留最近的消息不动
释放的 Token 数（snipTokensFreed）传给后续阶段，影响 Autocompact 的触发判断
如果 Snip 已经释放了足够空间，Autocompact 就不需要触发

为什么最先运行？ 因为它最快（零 API 调用），且对缓存无影响。

第二级：Microcompact（缓存感知压缩）

核心创新：在不打破 Prompt Cache 的前提下压缩工具结果。

可压缩的工具：FileRead、FileWrite、FileEdit、Bash、Grep、Glob、WebSearch、WebFetch

两种模式：

时间触发压缩：如果距离上次 API 调用超过缓存 TTL，服务器缓存已过期。此时全量重写前缀不会有额外成本——因此可以直接清理旧工具结果。

缓存编辑压缩（Cache Editing，仅内部用户）：利用 API 的 cache_edits 功能，在不失效缓存的情况下删除工具结果：

1
2
3
4
5
6
7
8


// 不是替换缓存内容，而是发送编辑指令
{
 type: 'cache_edits',
 edits: [{
 type: 'delete',
 cache_reference: 'tool_use_abc123' // 要删除的工具结果 ID
 }]
}

这意味着：缓存前缀完全保持不变，只通过 cache_reference 标记哪些工具结果已经不需要了。API 服务器会在应用缓存时跳过被删除的部分。

为什么这很重要？ 传统做法是修改消息内容来"清空"工具结果——但这会改变消息的 hash，导致整个缓存失效。Cache Editing 绕过了这个问题。

第三级：Autocompact（AI 全量摘要）

当 Token 超过阈值（默认 ~167K），触发 AI 全量摘要。

触发条件：

1
2
3


tokenCount > getAutoCompactThreshold(model)
// 其中 threshold = effectiveWindow - AUTOCOMPACT_BUFFER_TOKENS
// = (contextWindow - 20K) - 13K

排除场景：

当前查询本身就是压缩查询（防止递归）
Session memory 查询
Context agent（marble_origami）查询

摘要模板（9 个分区）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<analysis>
[模型的思考过程——最终会被剥离]
</analysis>

<summary>
1. Primary Request and Intent — 用户的所有显式请求
2. Key Technical Concepts — 讨论过的技术和框架
3. Files and Code Sections — 查看/修改的文件（含代码片段）
4. Errors and Fixes — 遇到的错误及修复方式
5. Problem Solving — 已解决和进行中的问题
6. All User Messages — 所有非工具结果的用户消息
7. Pending Tasks — 明确的待办任务
8. Current Work — 压缩前正在做什么
9. Optional Next Step — 下一步建议（仅当与最近请求一致时）
</summary>

强制文本输出：摘要 Prompt 开头有一段"反工具声明"：

1
2


CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
Tool calls will be REJECTED and will waste your only turn — you will fail the task.

末尾还有 REMINDER 重复一次——双重保险。因为压缩调用本身也消耗 Token 和时间，如果模型在这里"开小差"调工具，代价极高。

摘要后的智能恢复：

压缩完成后，系统不是简单地用摘要替换历史。它会恢复最重要的信息：

恢复项	上限
最近读取的文件	最多 5 个文件
文件恢复总预算	50,000 Token
单文件预算	5,000 Token
Skill 恢复预算	25,000 Token
单 Skill 预算	5,000 Token

熔断器：如果 Autocompact 连续失败 3 次（MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES），停止尝试。防止"压缩失败 → 重试 → 又失败"的无限循环。

第四级：Reactive Compact（紧急 413 压缩）

当 API 返回 413 Prompt Too Long 错误后触发——这是最后手段。

与 Autocompact 的区别：

	Autocompact	Reactive Compact
触发时机	API 调用前（预防性）	API 返回 413 后（响应性）
触发条件	Token > 阈值	API 报错
可用次数	多次	每轮一次（`hasAttemptedReactiveCompact`）
图片处理	不处理	可剥离图片/PDF
Token 差距计算	不需要	从 413 错误信息解析

Token 差距计算：

1
2
3


getPromptTooLongTokenGap(errorMessage)
// 从 "prompt is too long: 137500 tokens > 135000 maximum"
// 提取出 gap = 137500 - 135000 = 2500

利用这个 gap，系统可以精确计算需要删除多少消息组，而不是盲目地一组一组删除。如果 gap 无法解析（Bedrock/Vertex 的错误格式不同），回退到"删除 20% 的消息组"策略。

图片/PDF 剥离：对于 Media Size Error，直接将图片块替换为 [image]、文档块替换为 [document] 文本标记。这不是压缩——是放弃媒体内容以换取请求可以通过。

Token 成本的数学

来算一笔账。以 Sonnet 4.6 为例：

Token 类型	价格（$/百万）	相对比
输入	$3.00	基准
输出	$15.00	5×
缓存写入	$3.75	1.25×
缓存读取	$0.30	0.1×
Web 搜索	$0.01/次	—

缓存回本点：写入成本 $3.75 / 读取成本 $0.30 ≈ 12.5 次读取回本。

对于一个持续 30 轮的会话，系统提示（~10K Token）的成本对比：

1
2
3
4


无缓存：30 轮 × 10K Token × $3/Mtok = $0.90
有缓存：1 次写入 $0.0375 + 29 次读取 × $0.003 = $0.12

节省：$0.90 - $0.12 = $0.78（节省 87%）

如果是全局缓存命中（scope: 'global'），连写入费用都省了——第一个用户写入后，所有用户都只付读取费用。

输出 Token 的优化：8K 默认 + 按需升级

第 02 篇提到的 Token 上限升级机制，也是一个成本优化：

1
2


默认 max_tokens = 8,000 (CAPPED_DEFAULT_MAX_TOKENS)
按需升级到 = 64,000 (ESCALATED_MAX_TOKENS)

为什么默认只给 8K？ 数据显示 p99 的输出 Token 才 4,911——绝大多数请求在 8K 以内就能完成。默认 64K 意味着 API 需要为每个请求预留 8 倍的计算资源，但 99% 的时候这些资源是浪费的。

8K 默认 + 按需升级 = 资源利用率大幅提升，< 1% 的请求需要重试。

6 级 Prompt 优先级

系统提示不是一个简单的字符串——它有 6 级优先级，决定最终发给 API 的内容：

1
2
3
4
5
6


优先级 0: Override（覆盖一切）
优先级 1: Coordinator 模式
优先级 2: Agent 系统提示
优先级 3: 自定义提示（--system-prompt）
优先级 4: 默认提示
优先级 5: Appendive（总是追加）

关键设计：Agent 在 Proactive 模式下是追加到默认提示（不是替换）。因为 Proactive 模式的默认提示已经很精简（自主 Agent 身份 + 记忆 + 环境），Agent 在此基础上添加领域指令，就像队友在共享基础上各自添加专长。

而在非 Proactive 模式下，Agent 是替换默认提示——因为默认提示太长，全部保留会浪费缓存前缀空间。

Appendive 级别的提示总是追加（除非 Override 激活）——用于注入临时上下文，如用户的 --append-system-prompt 参数。

可借鉴的模式

1. 静态/动态分割是缓存优化的第一步

任何 LLM 应用都可以做这个优化：把系统提示中不会变化的部分放前面，标记为可缓存。改动频繁的部分（用户上下文、环境信息）放后面，不缓存。

关键洞察：顺序很重要。Prompt Cache 是前缀匹配——只要前缀相同就命中。动态内容放后面意味着它的变化不影响前缀的缓存命中。

2. 分级压缩优于一刀切

不要在上下文快满时直接"砍掉一半历史"。分级压缩的好处是：

轻量操作（Snip）先跑，可能就够了
避免不必要的 API 调用（AI 摘要很贵）
每一级都保留尽可能多的信息

3. 缓存编辑是一个值得关注的 API 特性

Cache Editing（通过 cache_reference + cache_edits 修改缓存内容而不失效）是一个强大的优化手段。虽然目前只有 Anthropic API 支持，但它展示了一个方向：缓存不需要是全有全无的——可以细粒度地增删。

下一篇预告

缓存分割和压缩保证了"对话能继续"。但 Agent 的能力边界取决于工具——50 个工具如何做到自包含又统一？Tool<Input, Output, Progress> 类型契约是怎么设计的？buildTool() 的 fail-closed 默认值意味着什么？下一篇，我们拆解 Tool System。

篇	标题	状态
01	512K 行代码，一个终端里的 Agent Runtime	✅
02	ReAct 循环：`while(true)` 里的五个阶段与七层恢复	✅
03	Prompt 缓存分割与四级上下文压缩（本篇）	✅
04	50 个工具的统一契约：Tool System 设计	🔄 下一篇
05	五层记忆体系：从短期到持久化	⬚
06	纵深防御：23 项安全检查与"不信任任何输入"	⬚
07	投机执行与自研状态管理：隐藏延迟的两个利器	⬚
08	多 Agent 编排：三种执行模型与 Coordinator 模式	⬚
09	在终端里造一个浏览器：自定义 Ink 渲染引擎	⬚
10	Bridge 与协议层：让 VS Code、Web、Mobile 共享一个 Claude	⬚
11	Skill、Plugin、Hook：三层扩展的设计谱系	⬚
12	回顾：从 Claude Code 中提炼的 10 个 Agent 工程模式	⬚

解剖 Claude Code（二）：ReAct 循环 — while(true) 里的五个阶段与七层恢复

Fri, 03 Apr 2026 00:00:00 +0000

一个 AI Agent 的核心竞争力不在于它调用了多好的模型，而在于它的主循环有多健壮。Claude Code 的心脏是 query.ts 中一个 1,700 行的 while(true) 循环——本篇逐阶段拆解它。

问题

当你在 Claude Code 里输入"帮我重构这个函数"，系统不是简单地调一次 API 然后返回结果。它可能需要：

先搜索代码找到函数位置
读取相关文件理解上下文
生成修改方案
执行文件编辑
运行测试确认没有 break

每一步都是一次"模型思考 → 工具执行"的循环。如果中途上下文溢出了怎么办？输出被截断了怎么办？API 过载了怎么办？网络断了怎么办？

Claude Code 的回答是：一个能自我修复的 ReAct 循环。

在整体架构中的位置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


用户输入 → QueryEngine.submitMessage()
 ↓
 ┌──────────────────┐
 │ query.ts │ ← 本篇聚焦
 │ while(true) { │
 │ ...1,700 行... │
 │ } │
 └──────────────────┘
 ↓
 Ink 渲染引擎 → 终端

QueryEngine 是入口，但真正的循环逻辑在 query.ts 的 queryLoop() 函数中。QueryEngine.submitMessage() 做的是消息规范化、系统提示组装，然后把控制权交给 query() 异步生成器。

循环状态：一个 Agent 需要记住什么

在进入循环之前，先看循环维护的状态。这个状态对象定义了一个 ReAct Agent 需要跨轮次追踪的所有信息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


type State = {
 messages: Message[] // 对话历史（持续增长）
 toolUseContext: ToolUseContext // 工具执行上下文
 autoCompactTracking: AutoCompactTrackingState // 压缩状态追踪
 maxOutputTokensRecoveryCount: number // 输出截断恢复次数（上限 3）
 hasAttemptedReactiveCompact: boolean // 是否已尝试紧急压缩
 maxOutputTokensOverride: number | undefined // Token 上限覆盖（8K→64K）
 pendingToolUseSummary: Promise<...> // 上一轮的工具摘要（异步）
 stopHookActive: boolean // Stop Hook 是否激活
 turnCount: number // 当前轮次
 transition: Continue | undefined // 上一次继续的原因
}

两个关键设计：

恢复计数器在每轮重置：maxOutputTokensRecoveryCount 在正常轮次结束时归零——每轮都有 3 次恢复机会，而不是全局 3 次。这意味着一个跨 20 轮的长任务，每轮都能独立恢复。
Transition 追踪：transition.reason 记录上一次循环为什么继续，而不是结束。这不是给用户看的——是给调试和测试用的。可能的值包括 'next_turn'（正常）、'reactive_compact_retry'（紧急压缩后重试）、'max_output_tokens_escalate'（Token 升级）等。

五个阶段

阶段一：上下文准备 — 在调 API 之前先"瘦身"

每轮 API 调用之前，系统会运行一条压缩管线，确保消息历史不会超出上下文窗口：

1
2
3
4
5
6
7
8
9


Tool Result Budget (单消息上限)
 ↓
 Snip (历史裁剪)
 ↓
 Microcompact (工具结果压缩)
 ↓
 Context Collapse (选择性归档)
 ↓
 Autocompact (AI 全量摘要)

每级压缩逐层递进，前一级减少不够才进下一级：

Tool Result Budget：给单条工具结果设置上限。过长的搜索结果、文件内容会被截断。这一步在 Microcompact 之前运行，因为它的截断对缓存是不可见的。

Snip：轻量裁剪，直接移除旧消息。保留最近的上下文不动。释放的 Token 数 snipTokensFreed 会传给后续阶段，影响 Autocompact 的触发阈值。

Microcompact：按 tool_use_id 压缩工具结果。关键技术：它操作的是缓存索引而非消息内容本身，对 API 的 Prompt Cache 不可见。这意味着压缩不会打破缓存。支持的工具包括 FileRead、Shell、Grep、Glob、WebSearch、WebFetch、FileEdit、FileWrite。

Context Collapse：选择性归档。不是摘要所有内容，而是保留细粒度上下文、只归档确定不再需要的部分。

Autocompact：AI 全量摘要。当 Token 数超过 上下文窗口 - 13,000 时触发。使用专门的 Prompt 让模型生成 9 个分区的结构化摘要（请求意图、技术概念、文件代码、错误修复、问题解决、用户消息、待办任务、当前工作、下一步建议）。

有一个熔断器：如果 Autocompact 连续失败 3 次（MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3），就停止尝试，避免无限循环。

阶段二：模型流式调用

准备好上下文后，调用 Anthropic API：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


for await (const message of deps.callModel({
 messages: prependUserContext(messagesForQuery, userContext),
 systemPrompt: fullSystemPrompt,
 tools: toolUseContext.options.tools,
 signal: toolUseContext.abortController.signal,
 options: {
 model: currentModel,
 fallbackModel,
 maxOutputTokensOverride, // 可能已从 8K 升至 64K
 fastMode: appState.fastMode,
 taskBudget: { total, remaining },
 queryTracking: { chainId, depth },
 // ...
 }
})) {
 // 流式处理每个消息块
}

流式处理的核心：模型的输出不是一次性返回的，而是逐块到达——文本块、工具调用块、思考块。系统在流式接收过程中做了三件关键的事：

1. 错误拦截与暂扣

并非所有错误都立即暴露给调用方。三类错误会被暂扣（withheld），等待后续恢复：

错误类型	暂扣条件	恢复手段
413 Prompt Too Long	Context Collapse 或 Reactive Compact 可用	压缩后重试
Max Output Tokens	总是暂扣	Token 升级或多轮恢复
Media Size Error	Reactive Compact 可用	剥离图片/PDF 后重试

暂扣的消息仍然会推入 assistantMessages，但不会 yield 给调用方。只有恢复失败后才会浮出。

2. 工具调用块收集

1
2
3
4


if (msgToolUseBlocks.length > 0) {
 toolUseBlocks.push(...msgToolUseBlocks)
 needsFollowUp = true // 标记：本轮需要继续循环
}

3. 流式工具执行（如果启用）

这是最精巧的部分——下一节详述。

阶段三：工具执行 — 流水线并行

Claude Code 有两种工具执行模式：

模式 A：流式执行器（StreamingToolExecutor）

当特性门控 tengu_streaming_tool_execution2 开启时，工具在模型还在输出时就开始执行。

工作原理：

模型流式输出 tool_use 块 → streamingToolExecutor.addTool(block) 立即入队
执行器检查并发安全性 → 满足条件立即开始执行
模型继续输出 → 新工具继续入队和执行
模型输出完毕 → getRemainingResults() 等待剩余工具完成

并发安全规则：

1
2
3
4
5
6
7


canExecuteTool(isConcurrencySafe: boolean): boolean {
 const executing = this.tools.filter(t => t.status === 'executing')
 return (
 executing.length === 0 ||
 (isConcurrencySafe && executing.every(t => t.isConcurrencySafe))
 )
}

翻译成人话：

如果没有工具在执行 → 直接执行
如果当前工具和所有正在执行的工具都是并发安全的 → 并行执行
否则 → 等待

哪些工具是并发安全的？ 读操作通常是安全的（FileRead、Grep、Glob）。写操作通常不安全（Bash、FileEdit）。但 Bash 工具有特殊逻辑：某些只读命令（git status、ls）也可以并发。

Bash 错误的传播：如果一个 Bash 工具报错，它会通过 siblingAbortController.abort('sibling_error') 取消所有兄弟工具。这是因为 Bash 错误通常意味着环境出了问题，继续执行其他工具没有意义。

工具状态机：

1

queued → executing → completed → yielded

模式 B：批量执行器（toolOrchestration.ts）

如果流式执行未启用，工具在模型输出完毕后批量执行：

1
2
3


partitionToolCalls(toolUseBlocks)
 → 并发安全工具分到同一批（并行，最多 10 个）
 → 非安全工具各自一批（串行）

两种模式的接口是统一的——都产出 { message, newContext } 的异步迭代器——循环体不需要知道用的是哪种模式。

阶段四：附件收集

工具执行完成后，系统收集一系列"附件"为下一轮做准备：

排队命令：用户在工具执行期间输入的命令
Skill 发现：后台预取的新 Skill
记忆预取：后台发现的相关长期记忆
工具摘要：用 Haiku 模型异步生成的工具使用摘要（fire-and-forget，不阻塞下一轮）

1
2
3
4
5


// 工具摘要是异步的——这一轮生成，下一轮才消费
nextPendingToolUseSummary = generateToolUseSummary({
 tools: toolInfoForSummary,
 signal: toolUseContext.abortController.signal,
}).catch(() => null) // 失败也不阻塞

阶段五：终止或继续？

这是每轮的最终决策点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


模型调用了工具？
 ├─ 是 → needsFollowUp = true → 继续循环
 └─ 否 → 进入终止检查

终止检查链：
 1. API 错误？→ 执行失败 Hook，返回 'completed'
 2. Stop Hook 阻止？→ 返回 'stop_hook_prevented'
 3. Stop Hook 报错？→ 注入错误消息，继续循环（reason: 'stop_hook_blocking'）
 4. Token Budget 未用完？→ 注入 nudge 消息，继续循环
 5. 超过 maxTurns？→ 返回 'max_turns'
 6. 以上都不是 → 返回 'completed'

Stop Hook 是一个有趣的机制：用户可以在设置中定义 Shell 命令，在模型每次完成回复后执行。Hook 可以检查模型的输出，决定是否允许继续。如果 Hook 返回错误，错误会被注入到消息历史中，模型会在下一轮看到这些错误并尝试修正。

Token Budget 是另一个控制点：当启用时，系统会检查本轮已消耗的 Token 是否达到预算的 90%。如果没有，注入一条 nudge 消息（“已用 X%，继续工作，不要总结”）让模型继续工作。还有衰减检测：如果连续 3+ 轮且每轮新增 < 500 Token，判定为"衰减"并停止——模型可能在兜圈子。

七层恢复机制

恢复机制是这个循环最精妙的部分。不是简单的 try-catch 重试，而是分层的、有针对性的自我修复。

前三层：预防性（在 API 调用前）

层	名称	触发	做什么
L1	Autocompact	Token > 上下文窗口 - 13K	AI 生成 9 段结构化摘要
L2	Snip	历史消息过长	裁剪旧消息
L3	Microcompact	工具结果冗余	按 tool_use_id 压缩

这三层在 API 调用前运行，目的是把上下文控制在安全范围内，避免触发 413 错误。

第四层：Context Collapse（413 第一道防线）

当 API 返回 413 错误后，系统首先尝试 Context Collapse——选择性归档消息。

1
2
3
4
5
6
7


if (state.transition?.reason !== 'collapse_drain_retry') {
 // 只尝试一次，避免双重 drain
 const drained = contextCollapse.recoverFromOverflow(messagesForQuery)
 if (drained.committed > 0) {
 continue // reason: 'collapse_drain_retry'
 }
}

关键细节：通过 transition.reason 检查避免重复 drain——如果上一轮已经是 collapse_drain_retry，就不再尝试，直接进入下一层。

第五层：Reactive Compact（413 最后手段）

如果 Context Collapse 也不够，触发紧急全量压缩：

1
2
3
4
5
6


if (!hasAttemptedReactiveCompact) {
 const result = reactiveCompact.tryReactiveCompact({...})
 if (result) {
 continue // reason: 'reactive_compact_retry'
 }
}

Reactive Compact 会：

计算需要清理的 Token 差距（actualTokens - limitTokens）
对整个对话生成紧凑摘要
智能恢复：压缩后自动恢复最重要的信息（最近读取的文件、当前 PR 文件等，最多 5 个文件，预算 50K Token）
对于 Media Size Error，可以剥离图片/PDF 后重试

死亡螺旋防护：413 恢复路径显式跳过 Stop Hook——因为模型从未产生有效输出，Hook 没有东西可评估。如果在这里运行 Hook，会产生"错误 → Hook 阻塞 → 重试 → 错误"的死亡螺旋。

1
2
3
4


// 代码注释原文：
// Do NOT fall through to stop hooks: the model never produced a valid response,
// so hooks have nothing meaningful to evaluate. Running stop hooks on
// prompt-too-long creates a death spiral: error → hook blocking → retry → error → …

第六层：Token 上限升级（8K → 64K）

当模型输出被截断（max_output_tokens 错误），系统的第一反应不是重试，而是升级限制：

1
2
3
4
5


if (capEnabled && maxOutputTokensOverride === undefined) {
 // 从默认的 8K 升级到 64K——单次升级，同一请求内立即重试
 maxOutputTokensOverride = 64_000 // ESCALATED_MAX_TOKENS
 continue // reason: 'max_output_tokens_escalate'
}

为什么默认只给 8K？ 这是一个成本优化。大多数回复在 8K 以内就能完成。只在真正需要时才升级到 64K，避免不必要的 Token 消耗。

第七层：多轮恢复（最多 3 次）

如果 64K 也不够，系统会注入恢复指令让模型从断点继续：

1
2
3
4
5
6
7
8


if (maxOutputTokensRecoveryCount < 3) { // MAX_OUTPUT_TOKENS_RECOVERY_LIMIT
 const recoveryMessage = createUserMessage({
 content: 'Output token limit hit. Resume directly — no apology, no recap...',
 isMeta: true, // 对 UI 不可见
 })
 maxOutputTokensRecoveryCount++
 continue // reason: 'max_output_tokens_recovery'
}

注意恢复指令的措辞：“Resume directly — no apology, no recap”——告诉模型直接从断点继续，不要浪费 Token 道歉或重复已输出的内容。

3 次恢复后如果仍然被截断，才浮出错误给用户。

循环的 10 种终止方式

终止原因	含义
`completed`	正常完成：模型没有调用工具
`aborted_streaming`	用户中断（Ctrl+C），模型还在输出
`aborted_tools`	用户中断，工具还在执行
`hook_stopped`	Hook 发出了停止信号
`stop_hook_prevented`	Stop Hook 显式阻止继续
`prompt_too_long`	413 错误，所有恢复手段用尽
`image_error`	图片处理错误
`blocking_limit`	Token 超过手动压缩阈值
`model_error`	未处理的模型调用异常
`max_turns`	超过最大轮次限制

6 种继续循环的原因：

Transition Reason	含义
`next_turn`	正常：模型调用了工具，需要继续
`collapse_drain_retry`	Context Collapse 释放了空间，重试
`reactive_compact_retry`	紧急压缩成功，重试
`max_output_tokens_escalate`	Token 上限从 8K 升到 64K
`max_output_tokens_recovery`	注入恢复指令，继续输出
`stop_hook_blocking`	Hook 报错，注入错误让模型修正
`token_budget_continuation`	Token 预算未用完，注入 nudge

一个完整的循环实例

把所有部分串起来，看一个"重构函数"任务的完整循环轨迹：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


Turn 1: 用户输入 "帮我重构 parseConfig 函数"
 Phase 1: 无需压缩（对话刚开始）
 Phase 2: 模型调用 GrepTool 搜索 "parseConfig"
 Phase 3: GrepTool 并发执行（read-only，并发安全）
 Phase 4: 收集搜索结果
 Phase 5: needsFollowUp=true → continue (reason: 'next_turn')

Turn 2:
 Phase 1: 无需压缩
 Phase 2: 模型调用 FileReadTool 读取文件 + GlobTool 查找相关文件
 Phase 3: 两个工具并行执行（都是只读）
 Phase 4: 收集文件内容
 Phase 5: needsFollowUp=true → continue

Turn 3:
 Phase 1: 无需压缩
 Phase 2: 模型调用 FileEditTool 修改代码
 Phase 3: FileEditTool 串行执行（写操作，非并发安全）
 Phase 4: 记录文件变更
 Phase 5: needsFollowUp=true → continue

Turn 4:
 Phase 1: 无需压缩
 Phase 2: 模型调用 BashTool 运行测试
 Phase 3: BashTool 串行执行
 Phase 4: 收集测试结果
 Phase 5: needsFollowUp=true → continue

Turn 5:
 Phase 1: 无需压缩
 Phase 2: 模型输出最终回复（无工具调用）
 Phase 3: 跳过
 Phase 4: 后台生成工具摘要、提取记忆
 Phase 5: needsFollowUp=false → Stop Hook 通过 → 返回 'completed'

5 轮循环，4 次工具调用，零错误——最简单的路径。

但如果 Turn 3 的编辑触发了上下文溢出：

1
2
3
4
5
6
7
8


Turn 3 (异常路径):
 Phase 2: API 返回 413 → 暂扣错误
 Recovery L4: Context Collapse → 释放了 20K Token → continue (reason: 'collapse_drain_retry')
 
Turn 3 (重试):
 Phase 1: 上下文已缩小
 Phase 2: API 调用成功，模型继续编辑
 → 恢复正常流程

用户完全无感——系统自动压缩、重试，编辑继续。

可借鉴的模式

从这个循环中可以提取三个通用模式：

1. 分层恢复，而非统一重试

不同类型的错误需要不同的恢复策略。413 和 max_output_tokens 是完全不同的问题——前者需要压缩输入，后者需要扩展输出。用一个通用的 retry(n) 处理所有错误是不够的。

2. 暂扣错误，给恢复留窗口

不是"收到错误 → 立即报告"，而是"收到错误 → 先暂扣 → 尝试恢复 → 恢复失败才报告"。这个模式适用于所有有恢复能力的系统。

3. 状态重置的粒度

maxOutputTokensRecoveryCount 每轮重置，hasAttemptedReactiveCompact 每轮重置（除非是 Stop Hook 阻塞的重试）。恢复预算是按轮次而非全局分配的——长任务不会因为早期的错误耗尽后期的恢复能力。

下一篇预告

ReAct 循环的阶段一（上下文准备）提到了四级压缩和 Prompt Cache 分割——这是控制 Token 成本的核心。下一篇，我们将深入拆解：静态/动态 Prompt 分割如何最大化缓存命中率，以及四级压缩体系如何在保留关键信息的同时将 Token 消耗降到最低。

系列导航

篇	标题	核心问题
01	512K 行代码，一个终端里的 Agent Runtime	全景认知
02	ReAct 循环：while(true) 里的五个阶段与七层恢复（本篇）	系统心脏怎么跳
03	Prompt 缓存分割与四级上下文压缩	长对话怎么省钱
04	50 个工具的统一契约：Tool System 设计	Agent 能力怎么扩展
05	五层记忆体系：从短期到持久化	Agent 怎么记住事情
06	纵深防御：23 项安全检查与"不信任任何输入"	怎么让 Agent 安全
07	投机执行与自研状态管理：隐藏延迟的两个利器	怎么让用户感觉快
08	多 Agent 编排：三种执行模型与 Coordinator 模式	多个 Agent 怎么协作
09	在终端里造一个浏览器：自定义 Ink 渲染引擎	终端 UI 怎么做到 60fps
10	Bridge 与协议层：让 VS Code、Web、Mobile 共享一个 Claude	CLI 怎么变成平台
11	Skill、Plugin、Hook：三层扩展的设计谱系	怎么不改源码就扩展
12	回顾：从 Claude Code 中提炼的 10 个 Agent 工程模式	带走什么

解剖 Claude Code（一）：512K 行代码，一个终端里的 Agent Runtime

Thu, 02 Apr 2026 00:00:00 +0000

2026 年 3 月 31 日，Anthropic 的 Claude Code CLI 完整源码因 npm 包中的 .map 文件泄露。512,000 行 TypeScript，1,900 个文件——这不是一个 CLI 工具，这是一个藏在终端里的 AI Agent 运行时。

为什么要读这份源码？

市面上的 AI 编程工具不少：Cursor、Windsurf、Aider、Copilot CLI……但 Claude Code 是第一个被完整泄露源码的生产级 Agent Runtime。它不是一个简单的"调 API → 输出结果"的 wrapper——它有自己的渲染引擎、权限系统、多 Agent 协调器、五层记忆体系、四级上下文压缩，甚至还有投机执行机制。

读懂它，不只是在看 Anthropic 的内部工程，而是在看一个完整的 Agent 架构范本。

本系列共 12 篇，本篇是全景导读。

技术栈：一个看似奇怪的组合

层级	选型	为什么？
运行时	Bun	启动速度是 CLI 体验的生命线。Bun 比 Node.js 快 3-5 倍。`bun:bundle` 的 `feature()` API 实现编译期死代码消除——未启用的功能从构建产物中彻底消失
语言	TypeScript (strict)	50 万行代码没有类型系统是不可想象的
终端 UI	React + 自定义 Ink	声明式 UI + Yoga flexbox 布局，在终端里实现接近 IDE 的交互体验
CLI 解析	Commander.js	成熟稳定，类型安全
Schema	Zod v4	一套 Schema 同时用于运行时验证和 API JSON Schema 生成
搜索	ripgrep	代码搜索的事实标准
协议	MCP + LSP	标准协议集成外部工具和语言服务
遥测	OpenTelemetry	标准化可观测性
特性门控	GrowthBook	灰度发布、A/B 测试

这套组合的底层逻辑是：启动要快（Bun）、交互要好（React+Ink）、扩展要广（MCP/LSP）、安全要硬（TypeScript strict + Zod）。

值得注意的是，Claude Code 完全不依赖传统的代码索引——没有 Embedding 向量检索，没有 AST 分析，没有代码图谱。它纯靠大模型的推理能力配合 Grep/Glob 全局搜索来理解代码库。这是一个大胆的哲学选择：赌模型能力的增长速度会超过代码库的增长速度。

核心数据流：一次对话背后发生了什么

当你在 Claude Code 中输入一条消息，数据会经过以下管线：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


用户输入
 │
 ▼
┌─────────────────────────────────────────────────┐
│ QueryEngine.submitMessage() │
│ ┌─────────────────────────────────────────┐ │
│ │ query.ts: while(true) — ReAct 循环 │ │
│ │ │ │
│ │ Phase 1: 上下文准备 │ │
│ │ → Snip / Microcompact / Autocompact │ │
│ │ │ │
│ │ Phase 2: 模型流式调用 │ │
│ │ → Anthropic API (streaming) │ │
│ │ │ │
│ │ Phase 3: 工具执行 │ │
│ │ → StreamingToolExecutor (并行) │ │
│ │ → 权限检查 → 沙箱执行 │ │
│ │ │ │
│ │ Phase 4: 附件收集 │ │
│ │ → 任务通知 / 记忆 / 文件变更 │ │
│ │ │ │
│ │ Phase 5: 终止或继续？ │ │
│ │ → 有工具调用？继续循环 │ │
│ │ → 无工具调用？结束 │ │
│ │ → 出错？七层恢复 │ │
│ └─────────────────────────────────────────┘ │
│ │
│ 错误恢复层: │
│ L1 Autocompact (80% 预警) │
│ L2 Snip (历史裁剪) │
│ L3 Microcompact (工具结果压缩) │
│ L4 Context Collapse (选择性归档) │
│ L5 Reactive Compact (413 紧急压缩) │
│ L6 Token 升级 (8K→64K) │
│ L7 多轮恢复 (最多 3 次) │
└─────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────┐
│ Ink 渲染引擎 │
│ React Reconciler → Yoga 布局 → Screen Buffer │
│ → 增量 Diff → ANSI 输出 → 终端 │
└─────────────────────────────────────────────────┘

这个流程最值得注意的是：

模型调用和工具执行是并行的 —— StreamingToolExecutor 在模型还在输出时就已经开始执行已完成解析的工具调用。这不是等模型说完再跑工具，而是流水线式并行。
七层恢复不是简单重试 —— 每一层处理不同类型的故障。413 上下文溢出会触发压缩后重试；输出被截断会自动将 Token 上限从 8K 升至 64K；API 过载会指数退避。系统在各种异常下自我修复，而不是直接崩溃。
上下文压缩是分级的 —— 不是简单地"砍掉旧消息"，而是四级递进：轻量裁剪 → 缓存感知压缩 → AI 全量摘要 → 紧急压缩。每一级都尽可能保留更多有用信息。

五个维度看系统成熟度

维度一：ReAct 循环 — 系统心脏

query.ts 中的 while(true) 循环是整个系统的心脏，实现了经典的 ReAct（推理-行动）模式。

五个阶段，每轮都走一遍：

阶段	做什么	关键技术
上下文准备	裁剪旧消息、压缩工具结果	Snip + Microcompact + Autocompact 三级组合
模型流式调用	发送对话历史 + 系统提示 + 工具列表	流式输出、Prompt Cache 分割
工具执行	并行执行工具调用	StreamingToolExecutor 流水线并行
附件收集	任务通知、记忆提取、文件变更	后台 Agent 异步提取记忆
终止决策	根据模型行为决定循环或结束	七层恢复、Stop Hook

最精巧的设计在于流式工具执行器：模型还在生成第二个工具调用时，第一个工具已经在并行执行了。如果第一个工具是并发安全的（isConcurrencySafe: true），它甚至可以和其他并发安全工具同时运行。

七层恢复机制则是韧性设计的典范：

层	触发条件	恢复策略
L1	对话达到上下文窗口 80%	预警式自动摘要
L2	历史消息过长	轻量裁剪（Snip）
L3	工具结果冗余	缓存感知压缩（Microcompact）
L4	API 返回 413	选择性消息归档（Context Collapse）
L5	L4 失败	紧急全量压缩（Reactive Compact）
L6	输出被截断	Token 上限 8K→64K 单次升级
L7	L6 仍被截断	注入恢复指令，最多重试 3 次

系列第 2 篇将深入拆解这个循环的每个阶段和恢复机制。

维度二：五层记忆体系 — 超越上下文窗口

大多数 Agent 工具的"记忆"就是对话历史。Claude Code 构建了五层记忆体系，覆盖从毫秒到永久的全时间尺度：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


┌─────────────────────────────────────────────────┐
│ 第 5 层：Checkpoint（会话持久化） │
│ 关闭终端，下次打开完整恢复 │
│ JSONL 转录文件 + 元数据快照 │
├─────────────────────────────────────────────────┤
│ 第 4 层：摘要记忆 │
│ AI 生成的结构化对话摘要（9 个分区） │
│ 区别于简单截断，保留语义 │
├─────────────────────────────────────────────────┤
│ 第 3 层：长期记忆 │
│ ~/.claude/projects/<path>/memory/ │
│ 4 种类型：用户偏好 / 纠正反馈 / 工作约束 / 外部引用 │
│ 检索时用 LLM 做相关性判断，提取 Top-5 │
├─────────────────────────────────────────────────┤
│ 第 2 层：工作记忆 │
│ 7 种任务状态 / 投机执行状态 / 权限追踪 │
├─────────────────────────────────────────────────┤
│ 第 1 层：短期记忆 │
│ 当前会话消息列表（内存中） │
└─────────────────────────────────────────────────┘

长期记忆的设计尤其精巧：它不是一个笨重的向量数据库，而是本地目录下的 markdown 文件，按主题组织。检索时不是做 embedding 相似度搜索，而是把所有记忆的文件名和描述发给模型，让模型选出最相关的 5 个再读取全文。

这种"用 LLM 做检索"的方式看似低效，但在记忆数量可控（几十到几百个文件）的场景下非常实用——它避免了 embedding 模型的维护成本，同时利用了大模型的语义理解能力。

系列第 5 篇将深入拆解五层记忆体系。

维度三：安全纵深 — 六层防御，不信任任何输入

一个能执行 Shell 命令的 AI Agent，安全不是可选项，是生存条件。Claude Code 构建了六层纵深防御：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


┌─────────────────────────────────────────────────┐
│ 第 6 层：内容检测 │
│ 秘密/PII 检测，遥测隐私保护 │
├─────────────────────────────────────────────────┤
│ 第 5 层：路径校验 │
│ 路径遍历防护、符号链接检查 │
├─────────────────────────────────────────────────┤
│ 第 4 层：命令级验证 │
│ 纯 TS Bash 解析器，23 项安全检查 │
│ 50ms 超时 + 50K 节点预算防 DoS │
├─────────────────────────────────────────────────┤
│ 第 3 层：规则匹配 │
│ 8 来源权限规则：policy > managed > project > user │
├─────────────────────────────────────────────────┤
│ 第 2 层：权限模式 │
│ default / plan / auto / bypass │
│ Auto 模式：二阶段分类器决策 │
├─────────────────────────────────────────────────┤
│ 第 1 层：沙箱 │
│ 文件系统/网络级隔离 │
└─────────────────────────────────────────────────┘

几个硬核细节：

纯 TypeScript 写的 Bash 解析器（130KB）：生成 tree-sitter-bash 兼容的 AST，在执行前静态分析命令安全性。设置了 50ms 超时和 50K 节点预算，防止恶意构造的命令消耗解析资源。
23 项 Bash 安全检查：覆盖命令替换、注入攻击、Unicode 同形攻击、IFS 注入、brace 展开、heredoc 注入等攻击面。
解释器黑名单：Python、Node 等只允许 --version 检查，禁止在自动模式下执行任意脚本。
ZSH 危险命令黑名单：16 个可绕过安全检查的 Zsh 内建命令（zmodload、emulate、sysopen、zpty 等）被显式禁止。

这套体系的设计哲学是每一层都不信任上一层——即使沙箱被绕过，权限系统仍然在拦截；即使权限被绕过，Bash 解析器仍然在检查命令安全性。

系列第 6 篇将深入拆解完整的安全体系。

维度四：多 Agent 编排

Claude Code 不是单 Agent 工具。它支持三种 Agent 执行模型和一个编排层：

三种执行模型：

模型	实现	隔离方式	适用场景
子 Agent	`AgentTool` 生成	Git Worktree	独立的文件修改任务
同进程队友	`InProcessTeammateTask`	`AsyncLocalStorage`	需要共享内存的协作
远程队友	`RemoteAgentTask`	独立进程/远程会话	PR 审查、后台任务

Coordinator 模式：

当启用后，系统切换为"指挥者-执行者"架构：

Coordinator 只负责任务分解和结果汇聚
Worker 拥有完整工具集，独立执行
内置角色：General Purpose（通用）、Explore（只读探索）、Plan（只读规划）、Verification（破坏性验证）
Worker 间通过 SendMessageTool 通信，通过 Scratchpad 目录共享持久知识
任务完成后以 <task-notification> XML 标签的 user-role 消息通知 Coordinator

Git Worktree 隔离是一个精巧的设计：每个子 Agent 在独立的 Git Worktree 中工作，可以自由修改文件而不影响主工作区。用户确认后才合并变更；拒绝则直接删除 worktree。

系列第 8 篇将深入拆解多 Agent 架构。

维度五：可观测性与隐私

遥测栈：OpenTelemetry（Trace + Metrics + Logs）→ OTLP/Prometheus/BigQuery

三级隐私类型系统——这是最值得学习的设计之一：

1
2
3
4
5
6
7
8


// 第 1 级：安全元数据（工具名、计数、状态码）
AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS

// 第 2 级：PII 标记数据（文件路径、仓库 URL）
// 用 _PROTO_* 前缀路由到特权列
AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED

// 第 3 级：通用元数据（已净化的值）

类型名本身就是安全检查：当你写 AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS 时，这个冗长的类型名逼迫你在写代码时思考：“我确认这个值不包含代码或文件路径吗？” 这是把安全审查嵌入类型系统的优雅做法。

MCP 工具名默认脱敏为 'mcp_tool'，只有官方注册的 MCP 服务器才保留原始名称。工具输入截断到 512 字符/4KB，防止业务代码意外被遥测上传。

六大惊艳的工程设计（速览）

#	设计	核心思路	详见
1	Prompt 缓存分割	系统提示拆为静态（全局缓存）+ 动态（不缓存），极大提高 API 缓存命中率	第 3 篇
2	四级上下文压缩	Snip → Microcompact → Autocompact → Reactive Compact，压缩后智能恢复关键信息	第 3 篇
3	投机执行	在用户确认前，在 Overlay 文件系统中预执行。确认写入，拒绝丢弃	第 7 篇
4	23 项 Bash 安全检查	覆盖注入、替换、同形攻击等。解释器黑名单防止自动执行脚本	第 6 篇
5	自研状态管理	Zustand 风格轻量 Store，精准订阅防止 React Ink 级联重渲染	第 7 篇
6	工具延迟加载	超过 20 个工具时，不直接写入 system prompt，让模型自己搜索发现	第 4 篇

模块地图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


src/
├── query.ts ★ ReAct 循环（系统心脏）
├── QueryEngine.ts ★ 对话引擎入口
├── Tool.ts ★ 工具类型契约
├── tools.ts ★ 工具注册表
├── commands.ts 命令注册表
├── main.tsx 入口（Commander.js + React/Ink）
├── context.ts 上下文收集
├── cost-tracker.ts 费用追踪
│
├── tools/ ~50 个工具实现
│ ├── BashTool/ Shell 执行（最复杂，含 23 项安全检查）
│ ├── AgentTool/ 子 Agent 生成
│ ├── FileEditTool/ 文件编辑
│ ├── GrepTool/ 代码搜索
│ ├── MCPTool/ MCP 协议桥接
│ ├── SkillTool/ Skill 执行
│ └── ToolSearchTool/ 工具延迟加载
│
├── services/ 服务层
│ ├── api/ Anthropic API 客户端（多提供商）
│ ├── compact/ 四级上下文压缩
│ ├── mcp/ MCP 集成（5 种传输）
│ ├── extractMemories/ 后台记忆提取
│ └── analytics/ 遥测与隐私（三级类型系统）
│
├── coordinator/ 多 Agent 协调器
├── tasks/ 7 种任务类型
├── memdir/ 长期记忆目录
├── state/ 自研状态管理
│
├── ink/ 自定义 Ink 渲染引擎
│ ├── reconciler.ts React Reconciler
│ ├── layout/ Yoga 布局引擎
│ ├── events/ W3C 事件模型
│ ├── screen.ts Screen Buffer（Intern 池化）
│ └── termio/ 终端 I/O 解析
│
├── bridge/ IDE 集成（VS Code / JetBrains）
├── skills/ Skill 系统（6 种来源）
├── plugins/ Plugin 系统
├── hooks/ Hook 系统（6 类 × 24 种事件）
├── vim/ Vim 模式（状态机实现）
├── voice/ 语音输入
├── utils/
│ ├── permissions/ 权限引擎（8 来源规则）
│ ├── sandbox/ 沙箱适配器
│ ├── bash/ 纯 TS Bash 解析器
│ └── telemetry/ OpenTelemetry 集成
│
└── constants/
 └── prompts.ts 系统提示（6 级优先级）

一个关键哲学选择

最后值得讨论一个贯穿整个架构的哲学选择：Claude Code 完全不做代码索引。

没有 Embedding 向量数据库，没有 AST 解析，没有代码图谱，没有符号表。当模型需要理解一个代码库时，它就用 GrepTool 和 GlobTool 全局搜索。

这意味着：

冷启动零成本——不需要先索引再使用
永远是最新的——每次搜索都读实际文件
简单到不可能出错——没有索引就没有索引过期

但也意味着：

大型代码库可能效率低——每次搜索都是全局扫描
依赖模型的推理能力——需要模型知道搜什么、怎么缩小范围
Token 消耗更高——搜索结果直接进入上下文

这个选择在当前模型变强的趋势下是说得通的。模型越强，越擅长用最少的搜索找到目标。但在百万行级代码库中，这个策略是否还能 hold 住，是一个开放问题。

系列导航

篇	标题	核心问题
01	512K 行代码，一个终端里的 Agent Runtime（本篇）	全景认知
02	ReAct 循环：`while(true)` 里的五个阶段与七层恢复	系统心脏怎么跳
03	Prompt 缓存分割与四级上下文压缩	长对话怎么省钱
04	50 个工具的统一契约：Tool System 设计	Agent 能力怎么扩展
05	五层记忆体系：从短期到持久化	Agent 怎么记住事情
06	纵深防御：23 项安全检查与"不信任任何输入"	怎么让 Agent 安全
07	投机执行与自研状态管理：隐藏延迟的两个利器	怎么让用户感觉快
08	多 Agent 编排：三种执行模型与 Coordinator 模式	多个 Agent 怎么协作
09	在终端里造一个浏览器：自定义 Ink 渲染引擎	终端 UI 怎么做到 60fps
10	Bridge 与协议层：让 VS Code、Web、Mobile 共享一个 Claude	CLI 怎么变成平台
11	Skill、Plugin、Hook：三层扩展的设计谱系	怎么不改源码就扩展
12	回顾：从 Claude Code 中提炼的 10 个 Agent 工程模式	带走什么

下一篇，我们将深入 query.ts 中的 while(true) 循环，看看这个 Agent Runtime 的心脏是如何一拍一拍跳动的。

Harness Engineering：当模型够强，系统设计成为胜负手

Wed, 01 Apr 2026 00:00:00 +0000

2026 年上半年，AI 工程领域出现了一个升温极快的概念：Harness Engineering。

如果你现在还停留在"怎么写一条更好的 prompt"这个层面去构建 Agent，那你可能正在用 2024 年的方法论解决 2026 年的问题。Anthropic、OpenAI、Google DeepMind、Stripe 这些公司几乎同时开始公开传达一个信号——决定 Agent 能否上线的，不是你给模型喂了什么 prompt，甚至不是你选了什么模型，而是你给模型搭了一套什么样的运行系统。

这套运行系统，就是他们说的 harness。

一匹不知道往哪跑的马

先聊词源。Harness 的原始含义是马具——缰绳、马鞍、胸带，一整套控制马匹的装备。这个隐喻是刻意选择的：马（模型）强大且快速，但自己不知道该往哪跑；骑手（人类工程师）提供方向；而马具（harness）则是将这匹马的原始力量导向有用工作的那层工程结构。

翻译成技术语言：Harness Engineering 不是在教模型怎么回答，而是在设计模型怎么工作。

它处理的是模型外部的那一整层东西：任务怎么拆解、上下文怎么管理、工具怎么编排、权限怎么设定、状态怎么在会话间交接、做完了怎么验证、失败了怎么恢复、什么时候该把控制权交回给人类。这不是一条 prompt 能搞定的事情，这是一个完整的运行时系统设计问题。

三代范式：从 Prompt 到 Harness

要理解 Harness Engineering 的位置，需要把它放进一条更长的演进链里看。

第一代：Prompt Engineering（2022–2024）

核心问题：怎么问？

这是大语言模型进入公众视野后的第一个工程范式。工程师们发现，同一个模型面对不同措辞的提问，输出质量天差地别。于是 few-shot prompting、chain-of-thought、role-playing、self-consistency 等技巧快速涌现。

Prompt Engineering 的本质是单轮、文本层面的优化。你精心措辞一段指令，模型给你一个回复，交互结束。它在问答、文本生成、简单推理等场景下效果显著，但天花板也很明显——当任务复杂到需要多步执行、外部信息检索、跨会话状态维持时，单条 prompt 无论写得多精巧，都无能为力。

第二代：Context Engineering（2025）

核心问题：给模型看什么？

2025 年年中，Shopify CEO Tobi Lütke 在公开场合表示"context engineering 比 prompt engineering 重要得多"。几乎同一时期，Anthropic 工程团队提出了一个精彩的类比：把大语言模型看作 CPU，上下文窗口看作 RAM，那么 Context Engineering 就是操作系统层面管理工作内存的技术。

Context Engineering 涵盖了 RAG（检索增强生成）、记忆注入、工具定义、对话历史管理、动态上下文组装等一系列技术。它的核心贡献是认识到：模型的输出质量不仅取决于你怎么问，更取决于你让它看到了什么。

这是一个重要的认知跃迁——从优化"提问方式"到优化"信息供给"。但 Context Engineering 仍然主要关注模型的输入侧，对模型执行过程中的行为约束、状态管理、失败恢复等问题触及有限。

第三代：Harness Engineering（2026）

核心问题：模型在什么系统里干活，如何确保它真的把活干成？

Harness Engineering 不仅管模型看到什么，还管模型能用什么工具、拥有什么权限、怎么保持跨会话状态、必须通过什么验证、产生什么日志、失败了怎么重试、什么时候该暂停等人介入。

三者之间是清晰的包含关系：

1

Harness Engineering ⊃ Context Engineering ⊃ Prompt Engineering

用一个驾驶类比来说：Prompt 是一句"右转"的语音指令；Context 是给驾驶员一张地图，让它理解右转意味着什么；而 Harness 是整辆车——方向盘、刹车、车道边界、仪表盘、安全气囊、维护计划，以及确保车辆不会在高速公路上失控的所有工程设计。

Anthropic 在 2026 年 3 月的工程博客中直接挑明了一个判断：Prompt 和 Context 层面的优化都能显著提升效果，但都会碰到天花板。前沿的性能差异越来越落在 harness design 上。

为什么偏偏是 2026 年？

Harness Engineering 作为一个显式概念在 2026 年初集中爆发，并非偶然，背后至少有四个结构性因素在同时发力。

第一，模型能力越过了"够用"的临界点，系统设计成为主要瓶颈。

2025 年到 2026 年初，Claude Opus 4.5、GPT-5、Gemini 2.5 等模型相继发布。单论推理能力，这些模型在大多数孤立任务上已经表现优秀。但当你试图让它们完成一个需要数十步、跨多个会话、涉及外部工具调用的真实生产任务时，失败率仍然惊人。Anthropic 给出了一个具体的描述：即使是 Opus 4.5，在收到"构建一个完整的 Web 应用"这样的高层级指令时，如果不配备系统化的 harness，它要么试图一口气完成所有事情导致上下文耗尽，要么在下一个 session 中看到一部分进展就提前宣布完成而跳过验证。这类问题换一个更强的模型并不会自动消失——它们是系统层面的问题，需要系统层面的解决方案。

第二，串联衰减让"每一步都还行"变成了"整体不可用"。

这里有一个被广泛引用的数学直觉：假设一个多步 Agent 流水线中每一步的成功率是 95%——听起来很高。但如果串联 20 步，端到端的任务完成率只剩下 0.95²⁰ ≈ 36%。

这就是为什么团队经常报告"Agent 95% 的时间都在正常工作"，但真实任务的失败率却接近三分之一。这个问题不是靠更聪明的模型能解决的，必须靠系统层面的验证、重试、检查点机制来应对——而这些恰恰是 harness 的核心职责。

第三，模型正在商品化，harness 成为新的差异化因素。

GPT 系列、Claude 系列、Gemini 系列在核心能力上的差距正在缩小。当模型本身不再是竞争壁垒时，围绕模型的系统设计——也就是 harness——就成了新的护城河。这个趋势类似于云计算早期：当计算资源本身变成商品，AWS 之所以领先不是因为它的服务器更快，而是因为它构建了更好的编排、监控和管理系统。

第四，Agent 从 demo 走向生产，工程实践倒逼方法论。

2025 年的 Agent 大多停留在演示阶段——跑一个令人印象深刻的 demo，然后在真实场景中悄悄失败。到了 2026 年初，越来越多的团队开始认真地把 Agent 推向生产环境。生产环境对可靠性、可观测性、失败恢复的要求远高于 demo，这些需求天然指向了 harness 层面的工程投入。Devin（Cognition 的自主编程 Agent）在 harness 达到生产就绪之前，经历了六个月、五次完整的架构重写——没有人是一次就做对的。

关键时间线

这个概念的浮现并非一蹴而就，而是实践先行、命名随后、推广跟进：

2025 年 11 月，Anthropic 发布工程博客 Effective Harnesses for Long-Running Agents，将 Claude Agent SDK 定义为通用型 Agent Harness。这是"harness"一词在 Agent 工程语境中最早的正式使用之一。
2026 年 2 月 5 日，Anthropic 联合创始人在博客中写了一句被广泛引用的话：“每当你发现 Agent 犯了一个错误，就花时间工程化一个解决方案，让它永远不再犯同样的错。”
2026 年 2 月中旬，OpenAI 在官方博客发布了标题直接叫 Harness Engineering 的文章，正式把这个术语推到台前。
2026 年 3 月，Anthropic 发布了更新的工程博客，系统阐述了 harness design 的方法论演进。

所以本质上：Anthropic 是实践者，命名者，OpenAI 是推广者。

头部公司怎么做的？

概念层面讲清楚了，接下来看最硬核的部分：这些公司到底是怎么构建 harness 的？

Anthropic：从双 Agent 到三 Agent 架构

Anthropic 的实践集中体现在两篇工程博客中（2025 年 11 月和 2026 年 3 月），两篇文章之间能看到方法论的明显演进。

第一版：双 Agent 架构。 他们将长任务拆成两种角色——初始化 Agent 和编码 Agent。初始化 Agent 只在第一个 session 运行，负责搭建环境、创建脚手架、写入进度追踪文件，并且——这是关键——将用户的高层级指令扩展成数百条具体的、可测试的功能需求清单（JSON 格式）。编码 Agent 在后续 session 中逐个推进功能，每次启动先读取进度文件、审查功能清单、运行已有测试。

这里有一个重要的设计思想：外部制品成为 Agent 的记忆。 进度文件、Git 历史、结构化需求清单，这些都是跨 session 持久化的。每个 Agent session 在动手之前先从这些制品重建上下文。这本质上是用文件系统解决了 LLM 无状态的核心问题。

一个值得注意的技术细节：Anthropic 自己透露，这两个 Agent 其实共享相同的系统提示和工具集，区别仅在于初始用户提示不同。换句话说，仅通过 prompt 差异就能在同一个 harness 内创造专门化行为。

第二版：三 Agent 架构（Planner-Generator-Evaluator）。 Planner 负责需求扩展和任务规划，Generator 负责代码实现，Evaluator 负责用 Playwright 等工具做交互式验证和打分。

这个演进中最关键的发现是评估器分离。Anthropic 发现，当你让模型评估自己的工作时，它会倾向于自信地表扬自己——即使在人类看来质量明显平庸。这不是某个特定模型的问题，而是自评估的系统性缺陷。他们的结论是：工程化一个独立的、严格的评估器 Agent，远比教会生成器 Agent 自我批评要容易得多。

另一个重要发现与模型迭代有关：早期 harness 基于 Sonnet 4.5 设计，该模型有明显的"上下文焦虑"倾向——随着上下文增长，模型行为会变得不稳定。因此 harness 设计了上下文重置机制。但换成 Opus 4.5 后，模型自行消除了这一行为，上下文重置机制反而变成了多余的复杂度。

这说明一个重要原则：Harness 不是越复杂越好，它必须与模型当前的能力边界相匹配。模型变强了，某些 harness 模块反而应该撤掉。

OpenAI：Codex 团队的百万行实验

OpenAI 的案例更具传播力，因为他们给出了非常具体的数字。

一个起初只有三人、后来扩展到七人的工程团队，用 GPT-5 驱动的 Codex Agent，在大约五个月里生成了约一百万行代码，合并了约 1500 个 PR，构建了一个有内部日活用户的生产级产品。团队人均日吞吐量约 3.5 个 PR，而且随着团队扩大，吞吐量反而上升了。

他们甚至给自己加了一个极端约束：零手写代码。 所有应用逻辑、测试、CI、文档、可观测性、内部工具全部由 Codex 生成。他们坦诚构建速度大约是手写的十分之一，但认为这是一种可接受的权衡——目的是验证 Agent 驱动开发的极限在哪里。

Martin Fowler 网站上的技术分析将 OpenAI 的 harness 方法论归纳为三大支柱：

Context Engineering：持续增强代码库中的知识文档（如 AGENTS.md），加上 Agent 对可观测性数据和浏览器的动态访问。
架构约束：不靠 Agent 自觉遵守，而是用确定性的自定义 linter 和结构测试来强制执行——这是硬性规则，不依赖 LLM 的判断。
垃圾回收：定期运行后台 Agent 扫描不一致和架构违规，对抗系统的熵增。

OpenAI 团队还发现了一个值得铭记的核心模式：当 Agent 遇到困难时，不要让它更努力地尝试，而是评估它缺少什么能力，把这个能力以可读、可执行的形式提供给它，然后让 Agent 自己编写修复代码。 这形成了一个 harness 自我改进的闭环。

不过，必须加一个诚实度提醒。OpenAI 在呈现这个案例时存在明显的利益关联——他们希望说服市场相信 AI 可以承担大规模代码维护。而且有分析者指出，这篇文章标题虽然叫 Harness Engineering，但正文中 “harness” 一词只出现了一次，标题很可能是后来受到 Anthropic 概念的启发才加上去的。

Google DeepMind：独立收敛到同一模式

Google DeepMind 没有像前两家那样发布专门的 harness 方法论文章，但他们用产品说话。

2026 年 2 月发布的 Elythia 是一个面向数学研究的自主 Agent，核心架构是三组件的 Agent harness：Generator 负责提出候选解法和证明策略，Verifier 用自然语言检查逻辑缺陷和幻觉，Revisor 负责修正验证器发现的错误。三个组件循环迭代，直到输出通过验证。

注意这里的结构：Generator → Verifier → Revisor，与 Anthropic 的 Planner → Generator → Evaluator 高度对应。两家公司独立走到了同一个设计模式——这不是巧合，这说明生成-评估分离正在成为 Agent harness 设计的行业共识。这个模式的灵感可以追溯到 GAN（生成对抗网络）的对抗训练思想，但在 Agent 系统中被重新发现并赋予了新的工程意义。

Google 在工具层面也有布局：Agent Development Kit（ADK）作为开源框架，内置了 evaluation harness 做场景驱动测试。2026 年 3 月发布的 ADK Python 2.0 Alpha 还加入了基于图的工作流编排能力。

另一个值得关注的技术细节：Gemini 2.5 引入了一个叫 thinking signatures 的机制——模型在调用工具之前生成一个加密的推理状态表示，传回对话历史后可以恢复精确的推理链路。这本质上是在模型层面解决跨步骤的状态持久性问题。Anthropic 用 harness 层面的外部制品（进度文件、Git 历史）保持记忆，Google 则尝试在模型内部解决同样的问题——两条技术路线的有效性值得持续观察。

一个反直觉的案例：Voxel 的"工具减法"

除了三大巨头，Voxel 提供了一个完全反直觉的经验。

他们最初给 Agent 配备了一个非常全面的工具库——搜索、文件操作、API 调用、代码分析，应有尽有。结果效果很差：Agent 变得困惑，进行冗余调用，执行不必要的步骤。然后 Voxel 做了一件看似倒退的事：移除了 80% 的工具。

结果反而获得了全面提升——更少的步骤、更少的 token 消耗、更快的响应、更高的成功率。

这个案例揭示了一个深层原则：约束 Agent 的解决空间反而能提升它的表现。 这与传统软件工程中"给工程师更多工具和自由度"的理念完全相反。对于概率性推理系统来说，更多选择意味着更大的决策空间，而更大的决策空间意味着更高的出错概率。精心策划的工具集（curated toolset）比大而全的工具库更有效。

Stripe 的实践也佐证了这一点：他们的 Agent 运行在隔离的、预热好的沙箱环境里，通过 MCP 协议访问超过 400 个内部工具——但这些工具经过了严格的权限分级和场景适配，而非全部平铺给 Agent。

一个成熟 Harness 的六大模块

综合以上公司的实践，一个生产级的 Agent harness 通常包含六个核心模块：

1. 上下文工程与知识管理

这是 harness 的基础层，负责确保 Agent 在每个执行步骤中都能访问到正确的信息。

包括：项目指令文件（如 CLAUDE.md、AGENTS.md，Agent 启动时自动读取）、动态上下文注入（从日志、监控指标中获取实时信息）、上下文隔离（用子 Agent 作为"上下文防火墙"，让不同子任务在各自的上下文窗口中运行）、上下文压缩（随着窗口被填满，自动摘要或丢弃无关信息）。

OpenAI 有一个精辟的观察：从 Agent 的视角看，它在运行时无法访问的任何东西都等同于不存在。 所以越来越多的知识需要被显式地推送到代码库内部，成为版本化的、Agent 可读的制品。

2. 工具编排与权限设计

Voxel 的经验已经说明，工具不是越多越好。成熟的 harness 需要精心策划工具集、移除冗余选项、设计清晰的权限边界。

具体包括：MCP（Model Context Protocol）协议集成实现工具标准化、文件系统的读写权限分级、网络访问的白名单控制、沙箱隔离确保 Agent 不会意外影响生产环境。一个好的工具编排层应该让 Agent 只看到它当前任务需要的工具，而非所有可用工具。

3. 验证机制与约束执行

这是 harness 区别于简单 scaffold（脚手架）的核心特征。

两种约束类型需要协同工作：确定性约束——自定义 linter、结构测试、pre-commit hooks，这些不依赖 LLM 判断，Agent 无法绕过；评估性约束——独立的评估器 Agent，用 Playwright 等工具做交互式验证和打分。

Anthropic 已经用实验证明了为什么需要这两层：确定性约束兜底确保"不可接受的事情绝对不会发生"，评估性约束则处理那些无法用硬规则覆盖的质量判断。

4. 状态管理与记忆持久性

大语言模型是无状态的——每个新 session 从零开始。这是长任务场景中最核心的工程挑战。

解决方案是外部化记忆：进度追踪文件记录"做到哪了"、结构化功能清单定义"还剩什么要做"、增量 Git 提交提供"做了什么"的完整审计链、检查点机制支持失败后从最近的成功状态恢复。

这里有一个有趣的类比：这套机制本质上就是操作系统中进程管理的变体——上下文保存与恢复、持久化存储、崩溃恢复。只不过被管理的"进程"是一个概率性的推理系统，而非确定性的程序。

5. 可观测性与反馈闭环

包括：执行追踪（每一步做了什么、用了什么工具、消耗了多少 token）、质量分级（输出结果的自动评分）、异常检测（识别 Agent 进入循环、产生幻觉等异常模式）。

最关键的是反馈归因：把 Agent 在生产中的失败模式追溯到 harness 的具体缺陷，驱动持续改进。OpenAI 的"垃圾回收"机制（定期用后台 Agent 扫描不一致和架构违规）就是这个模块的一种实现。

6. 人类接管与生命周期管理

在关键决策点暂停执行——要删数据库？要扣费？要发客户邮件？必须让人类确认。

还包括：升级路径（Agent 无法解决时如何优雅地交还控制权）、失败重试策略、完整的生命周期钩子（启动前检查、执行中监控、完成后清理）。这个模块的设计原则是：Agent 的自主性应该与任务的可逆性成正比。 可逆操作（如编辑代码）可以高度自主；不可逆操作（如部署到生产、发送外部通知）必须有人类审批环节。

新瓶装旧酒？一个诚实的定位

讲到这里，可能有人想问：这不就是换了个名字的软件工程吗？

坦率地说，Harness Engineering 里确实有很大一部分不是新发明。Test harness 在软件工程中已有几十年历史；CI/CD 流水线、linter、pre-commit hooks 是成熟的 DevOps 实践；任务分解与编排在分布式系统中早就被充分研究；沙箱隔离是安全工程的基础概念；可观测性在 SRE 领域已经高度成熟。

如果有人说 Harness Engineering 全是新东西，那是在夸大。但如果有人说它纯粹是旧酒，那也不准确。

它在几个维度上确实产生了新的方法论贡献：

约束对象发生了根本变化。 传统软件工程约束的是确定性代码执行——给定相同输入，程序总是产生相同输出。而 Harness Engineering 约束的是概率性推理系统——相同的 prompt 可能产生不同的输出，模型可能产生幻觉，可能在多步推理中逐渐偏离。这要求在验证、重试、恢复等方面采用根本不同的设计策略。

“约束即提升"的反直觉原则。 Voxel 的案例证明，约束 Agent 的解决空间——减少工具、限定模式、强制架构边界——反而提升了它的生产力和可靠性。传统工程思维倾向于给工程师更多工具和自由度，但对概率性推理系统，逻辑恰好相反。

代码库本身成为 harness 的一部分。 代码结构、命名约定、模块边界，不仅服务于人类可读性，更服务于 Agent 的"可推理性”。OpenAI 的 Codex 代码库甚至首先为 Agent 的可读性优化，而非人类的阅读偏好。这是一个全新的代码设计维度。

我个人认为最准确的定位是：Harness Engineering 类似于 DevOps。 DevOps 也不是发明了全新的技术，而是在持续交付的压力下，将开发、测试、运维等多个成熟领域的实践重新组合，形成了统一的方法论。Harness Engineering 正在做类似的事——在 Agent 生产化的压力下，将系统设计、测试工程、可观测性等成熟实践重新组合，并补充针对概率性推理系统的新模式。这种重组本身就是有价值的创新。

风险与清醒认知

最后聊聊风险。任何新概念在上升期都容易被过度包装，Harness Engineering 也不例外。

概念膨胀。 当一个术语从一个 agent.md 文件到完整的生产运维系统都能涵盖时，它的精确性就会被稀释。“Harness Engineering"正在变成一个什么都能往里装的筐，这对概念的长期生命力是危险的。

过度工程化。 Anthropic 自己的经验已经证明了这一点：Opus 4.5 自行消除了 Sonnet 4.5 的上下文焦虑行为，harness 中的上下文重置机制随之变成了多余的复杂度。随着模型快速进步，今天精心设计的 harness 模块明天可能就成了不必要的包袱。OpenAI 也强调 harness 必须是"可撕裂的”（tearable）——能够随时移除不再需要的模块。

证据基础偏弱。 这是我认为最需要警惕的问题。目前支持 Harness Engineering 价值的大多数证据来自 AI 工具厂商自身——OpenAI 报告 Codex 有多厉害、Anthropic 报告 Claude Agent SDK 改进了多少。这些来源都存在利益冲突。独立的、定量的、可复现的 benchmark 验证目前仍然缺乏。Anthropic 自己都在文章中承认，他们的案例缺少"显著的定量成功指标"。

可复现性存疑。 OpenAI 的百万行代码案例是在极其特定的条件下完成的：从空仓库开始、用自家的 Codex 工具、团队本身就是 AI 系统专家。这个经验对普通工程团队的可复现性完全没有被验证过。

Harness 也是风险放大器。 Anthropic 在 biosafety 评测中发现了一个令人警醒的数据：单 Agent 配置下非预期解法的发生率是 0.24%，多 Agent 配置下上升到 0.87%。更强的 harness 并不一定改变模型想走捷径的倾向，但因为更高的 token 使用量和更多并行搜索路径，反而提高了意外行为的概率。Harness 不只是性能放大器，也可能是风险放大器。

给 Agent 开发者的行动路径

与其纠结于概念定义，不如从务实的角度看看现在能做什么。

立即能做： 在项目根目录创建一个 AGENTS.md（或 CLAUDE.md），把 Agent 的工作约束写进去。每次 Agent 犯重复性错误，就在文件中加一条规则。这是最小化的 harness，成本几乎为零，效果立竿见影。

中期投入： 构建确定性验证层。自定义 linter 检查 Agent 输出的代码结构、pre-commit hooks 拦截明显的质量问题、结构测试验证架构约束没有被破坏。再加上基本的可观测性——至少记录每次 Agent 执行的步骤数、token 消耗和成功/失败状态。

长期方向： 设计模块化的、可替换的 harness 架构。每个模块应该能独立启用或禁用，支持模型升级时平滑迁移。记住 Anthropic 的教训：今天为弱模型设计的补偿机制，明天可能因为模型变强而需要拆除。

引用 OpenAI Codex 团队工程师的一句话来结尾：

Agent 不难，harness 才难。

当模型能力不再是瓶颈，你为模型搭建的运行系统，就是你真正的竞争力。

Agent on 鬼哥的空间

别让 Fable/Opus 干杂活：Agent 系统的省钱架构

先看一个调研任务：拿 Opus 打苍蝇是怎么发生的

Advisor Tool：Sonnet 干活，Fable/Opus 把关

Managed Agents：把一个大任务拆成一支小队

Plan Big, Execute Small：真正值得偷走的范式

怎么选架构：别先问模型，先问任务

真正的省钱架构：让每个模型做它最值钱的事

参考资料

后端上下文工程：一个开源工具把 Claude Code 的账单砍掉 2/3

一个反直觉的数字

为什么 Supabase 的 MCP 是个 token 黑洞

1）文档检索：给一勺米，端来一锅饭

2）后端状态：Agent 看不到仪表盘

3）错误信息：只告诉你 401，不告诉你为什么 401

上下文工程在后端长什么样

1）Skills：静态知识零往返

2）CLI：给 Agent 的"命令行手柄"

3）MCP：只用来看"活的状态"

实战对比：用 Claude Code 造同一个 RAG 应用

Supabase：10.4M token 的大部分都花在调错上

第一个坑：登录直接不工作

第二个坑：上传文档，连续 8 轮失败

InsForge：3.7M token，零错误干预

我自己的体感

Takeaway

参考资料

Claude-Cookbooks 全景导航：被 README 藏起来的另一半

一、先把这份 repo 的定位搞清楚

二、一张总览图：20 多个目录怎么归类

三、基础能力层：Claude API 开箱即用能做什么

3.1 capabilities/ — 经典的 NLP 任务

3.2 multimodal/ — 视觉能力

3.3 extended_thinking/ — 让模型"想得更久"

四、Tool Use 专题：整个 cookbook 最密的一块

五、性能与成本优化

六、Agent 的三条进阶路径

6.1 模式层 patterns/agents/ — 先把套路搞清楚

6.2 SDK 层 claude_agent_sdk/ — 官方的 Agent 教程

6.3 托管层 managed_agents/ — Claude Managed Agents (CMA)

七、Skills 技能包

八、第三方集成一览

九、评估与微调

十、仓库工程实践：这本身就是一份"怎么管理 Notebook 项目"的样板

十一、我接下来会按什么顺序往里钻

结尾：这只是起点

参考资料

Gemma 4 深度解析：从「不可用」到「生产级」的 Agent 质变

一个数字说明一切

模型家族全景：四种规格，一套架构

架构革新：三个关键设计决策

1. 混合注意力：局部与全局的交替舞步

2. 双 RoPE 位置编码策略

3. MoE 的"以小搏大"哲学

基准对决：Gemma 3 vs Gemma 4

31B Dense 模型

26B MoE 模型（以 ~4B 的速度运行）

小模型也不弱

五个有趣的实际应用

应用一：离线法律合同分析师

应用二：手机端实时语音翻译器

应用三：产线边缘质检 Agent

应用四：个人代码审查 Agent

应用五：会议手写笔记 → 结构化文档

开源 AI 的分水岭时刻

解剖 Claude Code（三）：Prompt 缓存分割与四级上下文压缩

问题

在整体架构中的位置

Part 1：Prompt 缓存分割

核心思想：静态 vs 动态

三种缓存范围

TTL 升级：从 5 分钟到 1 小时

Section 缓存机制

工具 Schema 的缓存稳定性

Part 2：四级上下文压缩

触发阈值

第一级：Snip（轻量裁剪）

第二级：Microcompact（缓存感知压缩）

第三级：Autocompact（AI 全量摘要）

第四级：Reactive Compact（紧急 413 压缩）

3.1 `capabilities/` — 经典的 NLP 任务

3.2 `multimodal/` — 视觉能力

3.3 `extended_thinking/` — 让模型"想得更久"

6.1 模式层 `patterns/agents/` — 先把套路搞清楚

6.2 SDK 层 `claude_agent_sdk/` — 官方的 Agent 教程

6.3 托管层 `managed_agents/` — Claude Managed Agents (CMA)