章节导航 第 1 章 / 共 23 章
第 1 章 第一部分：全局视角

为什么要研究 Claude Code

一次构建工具的默认配置失误，意外打开了一扇窗——让我们得以窥见当前业界最成熟的 AI Agent 系统的完整内部构造

Claude Code 源码泄露 Agent 逆向工程

1.1 一个默认配置引发的意外

2026 年 3 月 31 日，安全研究员 Chaofan Shou（@shoucccc）在例行审查 npm 包时发现了一件不寻常的事：Anthropic 官方发布的 @anthropic-ai/claude-code v2.1.88 包中，附带了一个 59.8 MB 的 JavaScript source map 文件 cli.js.map。

这个文件不应该出现在生产包中。

Source map 的作用是将混淆打包后的代码映射回原始源码。也就是说，通过 13 MB 的 cli.js（混淆后的主程序）和这个 59.8 MB 的 .map 文件，任何人都可以完整还原出 Claude Code 的全部 TypeScript 源代码——跨越 1,906 个源文件，总计 512,000 行代码，302 个目录，最大目录深度 6 层。

技术根因：Claude Code 的构建管道使用 Bun 打包工具。Bun 默认生成 source map，除非在构建配置中明确设置 sourcemap: "none"。Anthropic 团队没有关闭这个默认选项。

—— 参考：Claw Code 事件时间线

这是一个典型的 CI/CD 配置疏忽。讽刺的是，泄露的代码中恰好包含一个精心设计的”隐身模式”（Undercover Mode）系统，专门用于防止 Claude Code 的内部架构细节泄露给终端用户。

泄露后数小时内，源代码被镜像到多个 GitHub 仓库。数千名开发者开始分析架构。在随后的混乱窗口期（3 月 31 日 00:21-03:29 UTC），甚至有攻击者趁机发起供应链攻击——发布了 axios 的恶意版本（1.14.1 和 0.30.4），内含远程访问木马。

Anthropic 的应对措施包括：将 Claude Code 的分发方式从 npm 转向原生安装程序（curl -fsSL https://claude.ai/install.sh | bash）。这不仅是安全应对，也标志着 Claude Code 从”npm 包”到”系统级应用”的定位升级。

后续影响仍在发酵：Anthropic 对多个 GitHub 镜像仓库发起了 DMCA 删除请求，但社区镜像已广泛传播。围绕泄露代码形成的分析生态（ClaudeCode-Leak 仓库、claude-harness.dev 交互式分析网站、多个技术博客系列）客观上加速了 AI Agent 工程实践的知识传播——这是一个意外的知识外溢效应。

1.2 这不是一个 CLI 工具

在泄露之前，大多数人对 Claude Code 的认知停留在”Anthropic 出的一个命令行 AI 编程助手”。源码公开后，业界才意识到这个判断严重低估了它的复杂度和野心。

先看几个数据：

指标数值
目录数302
文件数1,903
总代码行数513,237
最大目录深度6
主体语言TypeScript + React TSX
TypeScript 文件1,332（379,997 行）
React TSX 文件552（133,219 行）
内置工具42+
内置命令70+
服务模块18+
内置代理6 种（+ Dynamic Workflows 动态子Agent + 5 层嵌套 sub-agent）；Workflow 并发默认 16（v2.1.269 起 1–256 可调）
Feature Flags50+ 个（32 编译时 + 22+ GrowthBook 运行时门控）
默认模型（Sonnet）Claude Sonnet 5.5（claude-sonnet-5-5，v2.1.284+ / 2026-09-28，官方 changelog 逐字记为 1M context, $2/$10 per Mtok with $0.20/Mtok cache reads）；v2.1.296 起 /cost、状态行、--max-budget-usd、SDK 四处把它的 cache reads 按 $0.10/Mtok 计价（公告后 11 天被改）。上一代 Claude Sonnet 5（v2.1.197+ ~ v2.1.284，1M-token 原生上下文，$2/$10 per Mtok）降为历史标注
默认模型（Opus）Claude Opus 5.5（claude-opus-5-5，v2.1.280+，1M 上下文，官方 changelog 逐字记为 1M context, $4/$20 per Mtok with $0.20/Mtok cache reads）；上一代 Claude Opus 5（v2.1.219+ ~ v2.1.280，SWE-bench Verified 96.0%，5/5/25 per Mtok）
默认模型（Fable）Claude Fable 5.1（v2.1.257+，1M 上下文，官方 changelog 逐字记为 $10/$50 per Mtok with $0.25/Mtok cache reads）
默认模型（Haiku）Claude Haiku 5.5（claude-haiku-5-5，v2.1.293+ / 2026-10-07，1M 上下文，官方 changelog 逐字记为 $0.10/$0.50 per Mtok ($0.50/$2.50 for prompts over 100K)）——全书第一个按提示长度分段计价的默认模型线
默认权限模式Manual（v2.1.200+，原 Default/Auto）
编排范式单 agent 串行 / Dynamic Workflows 脚本驱动多 agent（v2.1.154+）/ 5 层嵌套 sub-agent（v2.1.172+）
自动化等级后台 agent 自动 commit / push / 开 draft PR（v2.1.198+）
无障碍屏幕阅读器全适配（v2.1.200+）
合规认证FedRAMP High（Public Beta, 2026-07-07）—— Gov Cloud 部署，hash-chained 审计日志，两人审批敏感操作

数据来源：内网 claude-code 源码分析知识库，基于 src/ 目录的完整扫描统计。

51 万行代码、42 个工具、6 种代理（+ Dynamic Workflows 动态子Agent层 + 5 层嵌套）、50+ 个功能开关。这不是一个 CLI 工具。这是一个完整的 Agent 操作系统。

注意 v2.1.257 起 Claude Code 的默认模型线在三条之间并列，v2.1.280/284/293 三次换代之后，当前是 Opus 5.5（$4 / $20，cache reads $0.20）、Sonnet 5.5（$2 / $10，cache reads 公告 $0.20、v2.1.296 起四处计价改 $0.10）、Fable 5.1（$10/$50，cache reads $0.25） 与 Haiku 5.5（$0.10/$0.50，提示超过 100K 时跳到 $0.50/$2.50） 四条并列。选型不再是”哪个更强”，而是缓存命中率与 effort 档位哪个主导你的账单——但这条轴的代价关系已经反转：Opus 5.5 的输入价只有 Fable 5.1 的 40%，cache reads（0.20）比Fable5.1的0.20）比 Fable 5.1 的 0.25 更低，长会话场景下”选便宜模型”与”省缓存费”第一次指向同一个模型。

两个新变量把这条轴从二维推成三维。

其一，Haiku 5.5 引入了全书第一个按提示长度分段的定价结构（$0.10/$0.50；prompts over 100K 为 $0.50/$2.50）。它直接推翻”Haiku 线最便宜”的直觉：在长 prompt 场景下，Haiku 5.5 的输入价与 Sonnet 5.5 同为 $0.50，只有输出价（$2.50）仍是 Sonnet 5.5（$10）的四分之一。单价不再是一个数，而是一个关于输入长度的函数——凡写”某模型的单价”，必须先声明落在哪一段。

其二，单价低不等于总价低。 tbench.ai 官方榜（一手，页面内嵌 JSON）在同一 harness（Claude Code）、同一 effort（max）、同一 n_trials=330 下给出了一组反例：

模型准确率总成本总 token平均单轮耗时
Opus 5.5（rank 1）64.85% ± 3.11$4,718.658.0B4,790.4 s
Sonnet 5.5（rank 2）61.82% ± 2.94$7,333.6419.4B7,431.6 s

Sonnet 5.5 的输入单价只有 Opus 5.5 的一半，实际却低 3.03pp 而贵 $2,615（约 55%）：它用了 2.4 倍的 token、1.55 倍的单轮时长，才拿到更低的分数。所以选型轴的第三个维度不是价格，而是达成同一结果需要多少 token——这与 Ch11 记录的”低分可能比高分更贵”是同一现象的两个样本。⚠️ 该对比不做归因：单价、缓存命中率、步数三个因素未拆分，只能读作”总量反例”，不能读作”Sonnet 5.5 效率低”。⚠️ Claude apps gateway 会话中 fable / best 别名仍可能解析为 Fable 5（网关未配置 5.1 会拒绝），需手动在 /model 选择。另需留意：SWE-bench Verified 96.0% 是 Opus 5 的数字，Anthropic 未在 Fable 5.1 系统卡对比表中列出该项；第三方对 Fable 5.1 给出 95.0% 的报道（快照 2026-09-08），引用时须标注来源，不取单源定论。

📌 同一条规则在 Terminal-Bench 4.0 上更值得记（2026-09-27 核实，2026-10-17 重写）：Anthropic 在 Opus 5.5 官方发布页自报 Terminal-Bench 4.0 为 66.4%（xhigh，标准误 ±2.6）；tbench.ai 官方榜截至今 2026-09-27 那天的榜首是 GPT-6 Astra（max）+ Codex 的 58.18% ±2.79（条目日期 2026-09-03，$3,267.18），当时 Opus 5.5 确实不在榜上。

2026-10-17 回源一手数据后的更新：tbench.ai 官方榜（页面内嵌 JSON 直接读取，非二手转述）显示——

排名模型 / harness准确率effort总成本总 token条目日期条目创建时间
1Opus 5.5 / Claude Code64.85% ± 3.11max$4,718.658.0B2026-09-222026-10-06
2Sonnet 5.5 / Claude Code61.82% ± 2.94max$7,333.6419.4B2026-09-282026-10-06

两点必须分开说：

  1. 本章”Opus 5.5 尚未进入官方榜”在 2026-09-27 是对的，只是现在过期了。 榜单条目自带的 created_at 是 2026-10-06（晚于本章快照日 9 天），而 date 字段（2026-09-22）是评测提交日。这正好解释了为什么”条目日期早于快照日却当时不在榜”——date 与 created_at 是两个字段。 凡引榜单，快照日期必须与 created_at 对齐，不能与 date 对齐。
  2. “差 8.2pp”这个数是比错了对象。 原来的 8.2pp 是拿 Anthropic 自报的 Opus 5.5 去比榜单上当时排名第一的 GPT-6 Astra——两个不同模型。Opus 5.5 现在在榜，正确的同模型对照是自报 66.4%（xhigh）对榜单 64.85%（max），差 1.55pp，且两者 effort 档不同。这不是谁造假，而是口径不同：厂商自报用自己的 harness 与 effort，官方榜统一 Claude Code harness。

教学结论因此改向。 本章原结论是”自报与榜单差得多是因为 harness 不同”；现在两条都在 Claude Code harness + 官方榜上，说明 harness 统一之后，仍会造成可观分差的主要变量是 effort。

⚠️ 但 effort 的方向本身不可预测，这一条比”effort 会造成分差”更重要。同一份榜单里：GPT-6 Astra 随 effort 单调上升（low 50.61 → medium 54.24 → high 57.88 → xhigh 57.88 → max 58.18）；Fable 5.1 的 max 与 xhigh 同为 57.88；而 Opus 5 是反的——xhigh 53.94% ±3.17 高于 max 51.82% ±3.39。所以”自报取高档、榜单取低档”或反过来，差值的符号都不能预先假定。

凡引榜单，必须带四个要素：快照日期（对齐 created_at）+ 口径（harness / n_trials）+ 成本 + effort。 第四项是本轮新增的，理由就是上面这张表——effort 是唯一一个在 harness 统一之后仍能造成可观分差的变量。

⚠️ 还有一处极易误读：Anthropic 页脚注称公开榜上 Opus 5 为 51.8%，而榜单页面上另有 53.9%——这不是快照漂移，是两个不同 effort 档位。榜单里 2026-07-24 那次提交挂了两条：max effort 51.8% ±3.4与 xhigh effort 53.9% ±3.2，至今都在榜上。Anthropic 用的正是前者作对照（“our setup reproduces it at 52.3%, within noise”）。同一模型名下的多个 effort 条目会被不同来源各取一个，写作时必须连 effort 一起引。

值得注意的是，本书分析基于 v2.1.88，但 Claude Code 仍在快速演进。泄露后的版本迭代远超预期——从 v2.1.88（2026-03-31）到 v2.1.198（2026-07-01），90 天内经历 110+ minor patch 与 3 大架构特性：

  1. Dynamic Workflows 脚本驱动多 agent 大规模编排（v2.1.154+, 2026-05-28）：JavaScript 脚本运行时编排 subagents（总上限 1000 / 并发默认 16；v2.1.269 起 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS 可在 1–256 区间上调，官方定位为 inference-bound fan-outs），从”单 agent 串行”演进到”按需动态编排”。/deep-research 是内置 workflow 范例。
  2. Sub-agent 嵌套 5 层深（v2.1.172, 2026-06-11）：sub-agent 现在可以自己生成 sub-agent，深度上限 5 层——对 agent 层级研究是重大能力扩展。配合 Dynamic Workflows 形成”嵌套 = 深度 / workflows = 广度”双维度编排。
  3. Claude Sonnet 5 + 1M context 集成（v2.1.197, 2026-06-30）：1M-token 原生上下文、$2/$10 per Mtok 促销定价（至 8/31）——研究价值从”工程实战代理”升级为”百万 token 长程任务代理”。
  4. Claude in Chrome GA + 后台 agent 自动 PR（v2.1.198, 2026-07-01）：浏览器集成作为 first-party 能力，后台 agent 完成代码工作后自动 commit / push / 开 draft PR（不再询问）——Claude Code 已从”辅助开发工具”演进为”半自主开发代理”。
  5. /dataviz skill（v2.1.198, 2026-07-01）：图表/仪表盘设计指引 + 可运行颜色调色板校验工具——标志 Skills 系统从”prompt 模板”向”特定领域方法论沉淀”演进。
  6. Artifacts 实时页面（Beta，2026-06-18）：会话产出可发布为交互式 HTML 网页（私有 claude.ai URL），实时更新，支持 PR 走查/仪表盘/架构展示/时间线。标志 Claude Code 从”终端工具”走向”团队协作平台”。
  7. Manual 权限默认 + daemon 锁自愈（v2.1.200/201，2026-07-03）：默认权限模式回归 Manual，daemon.lock 僵尸进程死锁修复，休眠唤醒后台任务断流自愈，屏幕阅读器无障碍重构。v2.1.201 移除 Sonnet 5 的 mid-conversation harness 提醒。
  8. Claude Opus 5 默认化（v2.1.219，2026-07-24）：Opus 5 以同等定价上线，SWE-bench Verified 96.0%、Frontier-Bench 2× Opus 4.8。子Agent嵌套恢复深度 3（经 v2.1.217 禁用实验后）。Fast mode 内模型调整为 Opus 5+Opus 4.8，Opus 4.7 退出 Fast mode。
  9. v2.1.207v2.1.220 实验期（2026-07-1107-25）：Auto mode 无需 opt-in（v2.1.207）、子Agent嵌套安全实验：禁用→恢复深度 3（v2.1.217→219）、verify 技能改为显式调用、MCP 连接状态可见化（v2.1.218）——反映 Anthropic 在子Agent安全边界和可靠性上的持续实验。v2.1.220 为稳定性修复。
  10. v2.1.220 ~ v2.1.263：安全边界与缓存经济学（2026-07-25 ~ 09-06）：6 周 35 个版本集中在两条主线。安全侧——--restricted 受限模式（2.1.248，移除命令执行类工具与 WebFetch、拒绝 bypassPermissions、忽略用户/项目/本地设置）、--permission-prompts none（2.1.259，无头主机 fail-closed 自动拒绝）、auto mode Containment Escape 规则（2.1.257，云元数据凭证获取/出口规避/跨租户访问不再自动批准）、Bash Read() 拒绝规则收紧（2.1.259）与因误伤 npm run build 而回滚（2.1.260）。缓存侧——promptCacheTtl / subagentPromptCacheTtl（2.1.243，主对话 1 小时 / 子代理 5 分钟）、experimental.cacheTtl 代理 frontmatter（2.1.248）、/cost 与状态行 prompt_cache.likely_cause 失效诊断（2.1.260）、Fable 5.1 的 prompt cache 未覆盖”工具结果之后的上下文”的修复（2.1.260）。最后一条值得单独记：Fable 5.1 发布时宣布 cache reads 大幅降价，三天后 changelog 才承认该折扣未覆盖”工具结果之后的上下文”——而这恰是 Agent 会话累积最多的部分。定价公告与实现代码路径不在同一个版本落地，是评估任何”降价”发布时的默认假设。
  11. v2.1.264 → v2.1.283：模型治理与编排解绑（2026-09-08 ~ 09-25，18 个版本）：⚠️ 264–283 的跨度是 20，实际只发布 18 个版本——264 与 279 两个号段从未发布（npm 版本列表与官方 changelog 双通道均查不到）。这是本书第三次踩同一个坑（另两次：ch00「约 175 个版本」实为 137、本章第 10 条「44 个版本」实为 35），凡写”N 个版本”一律按 changelog 条目计数，绝不写跨度。三条主线：
    • 默认模型再换（v2.1.280）：Opus 5.5 成为默认 Opus 模型，$4/$20 + $0.20 cache reads，官方称典型任务成本比 Opus 5 降约 40%。
    • 编排上限解绑（v2.1.269）：CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS（1–256）可上调 Workflow 单次运行的并发 agent 数——“并发 16”降为默认值。
    • 安全与治理：v2.1.271 per-command allowed_domains（域名只对本条命令开放）；v2.1.277 AGENTS.md 原生支持（无 CLAUDE.md 时改读）；v2.1.278 auto mode 分类器默认走服务端且不计费 classifier 开销（/status 新增 “Auto mode server” 行）；v2.1.283 availableModelsMatch: "exact" + deniedModels（新模型发布默认被阻断，直到被显式列出）；v2.1.283 /doctor prompt-audit 审计”为旧模型写的提示模式”。
  1. v2.1.284 → v2.1.302：模型线扩容与扩展层重做（2026-09-28 ~ 10-16，17 个版本）：⚠️ 284–302 跨度 19，实际只发布 17 个版本——297 与 298 两个号段从未发布（npm versions 列表与官方 changelog <Update label> 双通道均查不到，296 直接跳到 299）。这是本书第五次踩同一个坑（前四次：ch00「约 175 个版本」实为 137、本章第 10 条「44 个版本」实为 35、264/279 空号、297/298），凡写”N 个版本”一律按 changelog 条目计数，绝不写跨度。四条主线：
    • 默认模型线从三条变四条：Sonnet 5.5（v2.1.284，逐字 1M context, $2/$10 per Mtok with $0.20/Mtok cache reads）、Haiku 5.5（v2.1.293，逐字 $0.10/$0.50 per Mtok ($0.50/$2.50 for prompts over 100K)）各自成为默认；v2.1.296 把 /cost、状态行、--max-budget-usd、SDK 四处的 Sonnet 5.5 cache reads 从 $0.20 改为 $0.10。
    • 扩展层重做（v2.1.287 Claude Mods）：官方 changelog 逐字为 “Added Claude Mods: plugins may now modify deeper behavior”。官方公告《Customize Claude Code with mods》（2026-10-01）把 mod 定义为挂在事件上的 TypeScript 函数，可改写 prompt、拦截/改写/重试工具调用、批准或拒绝权限请求、在工具输出进入模型前脱敏、编辑界面，并替换内置功能（内置 /diff 现已是 mod）。同篇逐字写 “Mods run with the same access to your machine as Claude Code itself. They aren’t sandboxed”；Team/Enterprise 及任何有托管设置的机器上，内置 sec-default mod 首个加载，阻止用户安装的 mod 覆盖 permission deny 规则。多个 mod 挂同一事件时按加载顺序执行，先加载的先见事件、后见结果。
    • MCP 描述配额四轨化：v2.1.295 起 tool search 加载路径截断从 2,048 改为 16,384；v2.1.296 起 sent up front 的描述与 server instructions 默认改为 4,096；v2.1.299 起 Anthropic 第一方 MCP server 不再受截断；v2.1.280 的 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH 是会话级总开关。同一件事在 11 天内被拆成四条互不相同的轨道——凡记”某个上限被改成 N”，必须写明是哪一条轨道的上限（详见 Ch02、Ch05）。
    • 运行与编排默认值变动：claude -p 与 Agent SDK 的默认权限模式（v2.1.302）、fork subagent 默认开启（v2.1.302）、后台命令时限（v2.1.285/288）。

这意味着本书拆解的架构是一个快照而非终态——核心架构设计稳定，但功能细节与编排范式持续快速迭代。⚠️ 版本锚点：截至 2026-10-17，npm dist-tags 为 latest = 2.1.302（2026-10-16）、stable = 2.1.292（2026-10-06），两者相差 10 个版本（上一轮记录为 9 个，又拉开一格）。latest 与 stable 是两条不同的线，引用版本号时必须说明取的是哪一条。

为了理解这个规模，可以做几个对比：

  • VS Code 的核心代码大约 50 万行（不含扩展）
  • Webpack 5 大约 10 万行
  • Next.js 大约 15 万行

Claude Code 的代码量与 VS Code 核心相当。但 VS Code 是一个拥有十年历史、数百名贡献者的成熟 IDE。Claude Code 是一个不到两年历史的 AI 工具。

1.3 代码都花在了什么地方

51 万行代码的分布揭示了一个反直觉的事实：工具层只占 10%，基础设施占了 35%。真正的复杂度不在模型调用，而在包裹模型的工程系统——权限引擎、配置管理、Git 集成、遥测、终端 UI。第 2 章会用完整的五层架构图展开这个分布。

剧透一个数字：src/utils 目录有 564 个文件、180,487 行代码，比很多独立项目的全部代码还多。

1.4 为什么值得逆向研究

把大量时间投入到一个商业闭源产品的逆向研究，是否值得？我认为答案是明确的肯定，原因有五：

理由一：当前最完整的生产级 Agent Harness 参考实现

“Harness”这个词在 AI Agent 语境中指的是包裹在模型外面的工程系统——提示词构建、工具调度、权限控制、上下文管理、错误恢复。Sebastian Raschka 在一篇被广泛讨论的文章中提出了一个判断：Harness 比 Model 更重要（The harness matters more than the model）。

Claude Code 是这个判断的最佳佐证。它的 System Prompt 不是一个静态文本文件，而是一个动态构建系统——根据运行模式、Feature Flag、用户配置、环境信息实时组装。它的权限模型不是简单的 allow/deny，而是六层规则来源加 AI 分类器的混合决策。它的工具系统不是简单的函数注册，而是包含 Schema 验证、权限上下文、执行上下文、错误恢复的完整协议。

目前没有任何一个开源项目达到这个工程成熟度。Cursor、Windsurf、Aider、OpenDevin——它们各有优势，但在架构完整性和工程精细度上，Claude Code 是标杆。

泄露事件后的行业反应为这个判断提供了最佳验证。“Harness Engineering”从 Anthropic 内部术语在两周内变为全行业讨论话题——多个独立分析项目（claude-harness.dev 交互式源码分析、多篇万字级深度拆解）围绕泄露代码迅速形成了完整的学习生态。这种规模的社区响应本身就证明了 Agent Harness 工程知识的稀缺性和 Claude Code 作为参考实现的独特价值。

2026 年 6 月，UIUC / Meta / Stanford 联合发布了 102 页综述《Code as Agent Harness》（arXiv:2605.18747），将 Claude Code 和 Codex 作为核心案例，系统性论证了”代码是 Agent Harness 的通用操作载体”这一命题。综述提出的三层分析框架（接口层 / 机制层 / 多 Agent 扩展层）与本书的五层架构拆解形成互补——本书从工程实现角度逆向，综述从学术视角归纳设计空间。同期，独立研究者的 Harness Engineering 综述将 2026 上半年的 Agent 工程实践形式化为六大组件学科（loop engine / compaction / separation / memory / permission / orchestration），其中 Claude Code 在五个组件上被列为标杆参考实现。

项目指令层也正在被标准化，而且标准化它的不是 Anthropic。 2025-12-09，Linux Foundation 宣布成立 Agentic AI Foundation（AAIF），首批三个捐赠项目是 Anthropic 的 MCP、Block 的 goose、以及 OpenAI 的 AGENTS.md——三个里有两个是”指令 / 配置格式”层面的标准。AGENTS.md 由 OpenAI 于 2025 年 8 月发布，官方新闻稿称其已被 60,000+ 开源项目与 Agent 框架采用（Amp、Codex、Cursor、Devin、Factory、Gemini CLI、GitHub Copilot、Jules、VS Code 等）；AAIF 的铂金成员包括 AWS、Anthropic、Block、Bloomberg、Cloudflare、Google、Microsoft、OpenAI。这解释了 Claude Code v2.1.277 为什么会原生支持 AGENTS.md（无 CLAUDE.md 时改读）：不是在做一个兼容性功能，而是接受一个由竞争对手发起、已被 6 万个项目采用的事实标准。对逆向研究者来说这条因果链值得单独记一笔——连”喂给 Agent 的指令文件”都不再由单一厂商定义，而 Harness 的入口恰恰就是这个指令文件。

逆向研究不仅是为了学习架构——更是为了理解攻击面。OWASP 于 2026 年发布的 Agentic AI Top 10（ASI01-ASI10）和 Agentic Skills Top 10（AST01-AST10）揭示了 Agent 系统的系统性安全风险：ClawHavoc 供应链攻击影响了 1,184 个恶意技能，Georgia Tech 数据显示 AI 编码工具相关 CVE 从 1 月的 6 个增至 3 月的 35 个。Claude Code 作为最完整的 Harness 实现，其安全架构（六层权限规则 + AI 分类器 + 沙箱隔离）也最具代表性——理解它的防御设计，就是理解 AI Agent 安全的前沿实践。

理由二：Context Engineering 的教科书

“Context Engineering”是 2025 年下半年出现的一个概念，指的是精确控制送入模型上下文窗口的内容这门工程学科。Claude Code 的 prompts.ts 是我见过的最精巧的 Context Engineering 实现：

  • 静态内容和动态内容有明确的边界分离（用 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记），这允许利用 Anthropic API 的 Prompt Caching 功能——静态部分只需计费一次
  • 50+ 个 Feature Flag（32 编译时 + 22+ GrowthBook 运行时门控）决定哪些提示片段被加载
  • 环境信息（操作系统、Shell、工作目录、Git 状态）被动态注入
  • 不同运行模式（CLI / MCP / SDK）有不同的提示词组装策略

如果你在构建任何 AI 产品，这个模块的设计思想值得反复研读。

值得补充的是，Claude Code 的工具系统通过 MCP（Model Context Protocol） 暴露 42+ 内置工具。MCP SDK 月下载量近 5 亿次（2026-07），已成为 AI Agent 与外部工具交互的行业标准协议。MCP 2026-07-28 规范正式发布，核心变更为无状态架构——废除 initialize 握手和 Mcp-Session-Id，MCP Server 可部署在 Serverless/Edge 平台；同时 MCP Apps 和 Tasks 毕业为正式扩展、OAuth 2.0/OIDC 硬化（iss 校验、CIMD 替代 DCR）。Google Cloud、Cloudflare、Netlify 宣布 Day Zero 支持。这意味着 Context Engineering 不仅包括”给模型的上下文”，还包括”工具调用的标准化接口”——现在不仅是接口标准化，连部署都是标准 HTTP 工作负载。理解 MCP 协议的 Schema 设计（工具名、描述、参数、结果格式）是理解 Claude Code 工具系统的关键。

⚠️ 按本书思路去读 MCP 的 Schema 之前，有三条已生效的硬约束（2026-09-08 核实）：

  1. Roots、Sampling、Logging 三项能力已被弃用（SEP-2577，自 2026-07-28 版本起；最早移除时间为 2027-07-28 及之后发布的第一个修订版）。迁移路径分别为：用工具参数 / resource URI / server 配置传递目录与文件；直接对接 LLM 提供商 API；stdio 传输写 stderr、可观测性用 OpenTelemetry。这是 MCP 新弃用策略（最短 12 个月窗口）的首次使用。
  2. Dynamic Client Registration 也已弃用，迁移到 Client ID Metadata Documents（CIMD）。
  3. 兼容性边界：官方兼容性矩阵把”现代客户端 + 旧服务端”标记为 failing。旧服务端之所以仍能工作，是因为官方 SDK 对两个时代的协议都提供支持，而非协议本身保证兼容。五个 Tier-1 SDK（TypeScript / Python / Go / C# / Rust）在 2026-07-28 发布当日即提供稳定支持，v2 为默认安装、v1 冻结为仅安全修复。

规模口径另需并列标注：官方 registry 收录数已达 25,000+ server（2026-08-26 核实）。📌 这与前文的”月下载量近 5 亿次”是不同口径（registry 收录计数 vs SDK 下载量 / 全生态可用），不可互相替换，引用时须标明口径与快照日期。

2026-09-27 复核：registry 收录数已升至约 30,000–32,000 server（第三方对官方 registry API 的两次独立全量统计：30,375 / 31,309，快照分别为 2026-09-10 与 2026-09-14，彼此相差约 3%）。⚠️ 该数字未找到官方公告口径，属中置信度，写入时请连同快照日期一起引用。

更重要的是这里藏着第三个口径：registry API 按 (name, version) 逐条返回，同一 server 的每个历史版本各占一条，条目数天然远大于 server 数。实测（2026-09-27 分页抽样，按名字字典序前段）22,967 条条目只对应 8,820 个不同 name（约 2.6 倍）；第三方全量统计给出的倍数约为 3.2 倍（99,114 ~ 101,219 条目 → 30,375 ~ 31,309 server）。所以看到”MCP 生态有 10 万个 server”这类说法时，先问一句：数的是条目还是 server？

📌 自核方法：curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100" 沿 metadata.nextCursor 翻页（limit 超过 500 会返回 422），把 server.name 去重后计数即为 server 数，不去重即为条目数。

⚠️ 自核方法的偏差（2026-10-17 修正）：2026-09-27 那次实测是按名字字典序前段抽样，得约 2.6 倍；2026-10-17 把覆盖推到前 60,100 条条目 → 19,363 个不同 name，倍数 3.10。两者之差不是漂移，而是偏差：样本越集中在字典序前段，倍数被低估得越多（前段的 server 版本数少）。抽样必须跨越多个字典序区段（或按 name 首字母分桶并行，见下）。⚠️ 3.10 仍不是全量——本次分页在 601 页 / 60,100 条处被上限截断（nextCursor 仍有值），只能当倍数用，不能当总数用。

🔴 跨书口径警告（2026-10-17）：本书另一部《大模型完整教程》（llm-complete）Ch16 记录了第三方统计 42,753（2026-10-13） 与 40,965（2026-10-09） 两个”registry server”数，并给出 2026-10-16 的官方 API 实测下界 68,190 条条目 / 20,300 个不同 name。⚠️ 这两个第三方数都远高于官方 API 实测到的去重 name 数（20,300），说明第三方统计的”server”很可能不是”去重 name”这一个口径（可能含非 active 状态、或按版本 / 仓库计数）。因此：本章的”约 30,000–32,000（去重 name 口径）“与 llm-complete Ch16 的”42,753”不是同一个量，不可互相替换，也不应把本章数字直接改写成 42,753。 这正是”口径”这件事的现场演示——连官方 API 都能给出与媒体统计差一倍的数。

📌 引用规则因此补到第四项：统计者。 引用任何会自己增长的数字，必须标 ① 口径（全生态 / 收录 server / 收录条目）② 快照日期（精确到日）③ 统计者（谁数的）④ 是否为全量。本章现有两个数字来自不同第三方、Ch16 的又来自第三个，同口径内彼此差 3%–4.4%，跨口径差一倍。

此外 2026-08-22 MCP 官方路线图把渐进式发现（progressive discovery）列为五大优先方向之一——“一次性把所有工具塞进上下文”不再只是不经济，而是即将被协议层淘汰。

理由三：多代理编排的生产实践

Claude Code 内置了 6 种代理（Explore、Plan、General Purpose、Verification、Guide、Statusline Setup），每种有不同的工具权限和模型选择策略。

2026 年 5 月与 Opus 4.8 同日上线的 Dynamic Workflows 将代理谱系从”6种固定角色”扩展为分层架构——底层仍为 6 种内置代理，但新增了动态子Agent层：Claude 根据提示词动态生成 JavaScript 编排脚本，将任务拆解为数十至数百个并行子Agent，每个子Agent独立执行，另有对抗性Agent负责反驳验证，直至结果收敛。编排逻辑运行在对话上下文之外，中间结果存储在脚本变量中。默认 16 个并发 Agent、1000 个总 Agent——16 自 v2.1.269 起是默认值而非硬上限，可用 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS 在 1–256 区间上调（官方限定语：inference-bound fan-outs）。这改变了”多代理编排”从”固定角色协作”到”按需动态编排”的范式。2026-07-02，Dynamic Workflows 正式 GA 并下放至 Pro 计划（$20/月）。GA 版本公开了 pipeline()、parallel()、agent() 三个核心原语，标杆案例为 Bun 从 Zig 到 Rust 的 96 万行代码移植（6 天，99.8% 测试通过率）。GA 标志着 Dynamic Workflows 从”实验性研究预览”升级为”面向全体付费用户的产品化多 agent 编排能力”。

2026 年 6 月 11 日发布的 v2.1.172 进一步扩展了 sub-agent 能力——sub-agent 现在可以自己生成 sub-agent（最多 5 层深），解决了”深层 delegation chains 上下文爆炸”问题。配合 Dynamic Workflows 形成”嵌套 = 深度 / workflows = 广度”双维度编排能力。Ch08 多代理章节需要补 5 层嵌套子Agent作为研究新前沿。

⚡ 子Agent嵌套策略在 7 月经历了快速实验：v2.1.217（7/22）因安全考虑默认禁用嵌套子Agent（需 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 环境变量开启），但仅两天后 v2.1.219（7/24）随 Opus 5 发布恢复深度 3 默认。这一”禁用→恢复”的快速迭代本身就值得研究——它表明生产环境中多Agent嵌套的安全边界仍在探索中，尚未收敛到稳定方案。

2026 年 6 月 30 日发布的 v2.1.197 Claude Sonnet 5 集成，引入 1M-token 原生上下文——研究价值从”工程实战代理”升级为”百万 token 长程任务代理”。sub-agents 和 context compaction 继承 extended thinking 配置，1M context + thinking 预算充足时，复杂多步任务可单会话完成。

2026 年 7 月 1 日发布的 v2.1.198 Claude in Chrome GA + 后台 agent 自动 PR：浏览器集成作为 first-party 能力（不是 MCP 工具），后台 agent 完成代码工作后自动 commit / push / 开 draft PR（不再询问）——Claude Code 已从”辅助开发工具”演进为”半自主开发代理”。研究 Claude Code 工具系统时，浏览器集成是新增 first-party 维度。

其中最有创新性的是 Verification Agent——它被明确要求”假设代码有 bug”，并识别两种认知偏差：验证避免（找理由跳过检查）和被表面完善迷惑（前 80% 看起来没问题就通过）。这种对抗性验证策略在 CrewAI、AutoGen、LangGraph 等框架中几乎看不到，因为它来自大规模生产实践而非学术实验。

第 8 章会完整拆解每种代理的角色设计、工具权限矩阵和协作机制。

理由四：2026 上半年五大新研究价值（v2.1.154 ~ v2.1.198）

除上述三个核心研究价值外，2026-05 ~ 2026-07 期间 Claude Code 新增 5 项研究价值：

  1. Dynamic Workflows 脚本驱动多 agent 大规模编排（v2.1.154, 2026-05-28）——从”6 种固定代理”扩展到”按需动态生成上百个 sub-agent”的范式转移。研究价值：脚本运行时 + 调度器/worker 分离架构 + 上限（1000 总数 / 默认 16 并发）的工程取舍。2026-09-27 追加一条研究价值：v2.1.269 把并发数从常量变成了 1–256 的可调参数——这件事本身说明 Anthropic 认为并发度是一个应由调用方按负载类型决定的量，而不是架构常数。判断”哪些值应该写死、哪些应该开放”是 Harness 设计中最难的一类决策，这里有一次公开的态度转变可供观察
  2. Sub-agent 5 层嵌套的 agent 层级研究（v2.1.172, 2026-06-11）——研究 sub-agent 自己生成 sub-agent 的能力边界、attribution headers、上下文压缩策略
  3. 1M context + extended thinking 协同（v2.1.197, 2026-06-30）——研究”何时用 Dynamic Workflows vs 单 agent 1M context”是新决策维度
  4. 后台 agent 自动 PR 模式（半自主开发）（v2.1.198, 2026-07-01）——研究”无人值守长时任务”的工程挑战、错误恢复、自动 commit/push/PR 的安全边界
  5. Skills 系统演进（领域方法论沉淀）（v2.1.198 /dataviz, 2026-07-01）——Skills 不再是 prompt 模板，而是含可执行验证的领域方法论。Hooks 系统的严格匹配演进（v2.1.197+）也属于此范畴

这些新增研究价值都直接呼应 AI Agent 工程前沿——单 agent → 多 agent → 动态编排 → 5 层嵌套 → 半自主，是 2026 年 Agent 系统的演进主线。

这条主线在 2026-10 长出了第六个环节，而且性质与前五个都不同：可扩展性的归属方变了。 前五个环节都是 Anthropic 自己加能力（多 agent、嵌套、1M、auto-PR、Skills）；Claude Mods（v2.1.287，2026-10-01）第一次把”Claude Code 内部怎么处理一件事”交给第三方改写——改写 prompt、拦截/改写/重试工具调用、批准或拒绝权限请求、在工具输出进入模型前脱敏、编辑界面，并替换内置功能（官方公告逐字：内置 /diff 现已是一个 mod，官方还称”We plan to move more built-in features to mods over time”）。对照 Hooks 的边界最清楚：官方原话是 hooks “can’t rewrite events, draw new UI, or replace features”，mods 可以。扩展机制因此从三种（Skills / MCP / Hooks）变成四种（+ Mods）。

研究价值要连反面一起写。 官方公告逐字：“Mods run with the same access to your machine as Claude Code itself. They aren’t sandboxed”——mods 不在沙箱内、与 Claude Code 同权限。企业侧的约束手段是一个加载顺序约定：Team/Enterprise 及任何有托管设置的机器上，内置 sec-default mod 首个加载，阻止用户安装的 mod 覆盖 permission deny 规则；管理员可改为先加载自己的 mod（官方提示此时要把 sec-default 一并加回列表）。多个 mod 挂同一事件时按加载顺序执行，先加载的先见事件、后见结果。

这把本书第 5 章”工具供应链安全”的讨论从”工具本身是不是坏的”推进到”扩展层本身是不是可信的”——前者的信任边界在工具调用的参数上，后者的信任边界在处理流被谁改写过上。

理由五：Claude Code 已是自举系统

Claude Code 负责人 Boris Cherny 自 2024-11 起零手写代码，100% 代码由 Claude Code 生成，单日最高 150 个 PR。Anthropic 工程师整体产出提升 250%。Claude Code 自身代码已 100% 由自己编写。这不仅是”Harness 比 Model 更重要”的实证——它意味着我们研究的不是一个静态的 agent 框架，而是一个已经能自我演化的 agent 系统。

一个必要的反面：自主度不是越高越好（2026-09）

上面”自主度越高越好”的叙事需要一个平衡。（据 Anthropic 的 Fable 5.1 / Mythos 5.1 System Card，经两家第三方转述一致）Anthropic 在自家系统卡中主动披露了两个失败模式：

  1. 更高的 effort 反而掉分。在 FrontierCode 1.1（Cognition 基于真实开源 PR 构建的 150 任务 agentic coding 基准）上，Fable 5.1 在 medium effort 得 63.6%（Extended）/ 50.9%（Main），均略低于 Fable 5 在 xhigh effort 的 64.9% / 53.5%。Anthropic 的解释是：FrontierCode 拒绝任何超出任务声明范围的文件改动，“即使改动是正确或有帮助的”，而更高 effort 下模型更常做出这类未被要求的额外改动。

  2. 更严谨的实现可能被判失败。在 DeepSWE v1.1（113 个长程软件工程任务）上，Fable 5.1 五次试验平均 67.4%，而 Anthropic 复盘失败转录时发现模型产出了”等价甚至更严谨的实现”仍被判失败——因为隐藏测试针对单一参考解编写。

  3. 厂商自曝”我们的分数被自己的安全策略压低了”（2026-09-22，Anthropic 官方 Opus 5.5 发布页，一手）。这是三条证据里最硬的一条，因为它是厂商主动披露而非第三方复盘。官方原文逐字：

    Claude Opus 5.5 was evaluated with its production safeguards enabled. When they intervened, cybersecurity tasks were completed by Claude Opus 4.8, and biology and frontier LLM development tasks were completed by Claude Opus 5. This likely reduces Claude Opus 5.5’s performance on these benchmarks.

    也就是说，Opus 5.5 的公开基准分数里，有一部分是另一个模型代它考的，而 Anthropic 明确承认这会拉低自家分数。同一页面还有一句更值得记住的判断：

    at these levels of capability we’ve found that benchmark margins have become a less reliable guide to real-world differences. In our own use, the gap between Opus 5.5 and Claude Fable 5.1 is narrower than these scores suggest.

结论：Agent 的自主度与评分器/验收标准的范围约束直接耦合，不是单调递增的。这与 Ch18”十条经验”中的”少写指令”原则构成一组张力——给 Agent 更多自由度之前，先确认验收边界是否容忍范围外的正确改动。第三条证据把这条结论再推一层：评测口径本身也是一种范围约束——当厂商的安全策略会把任务转交给另一个模型时，榜单上的”模型 A 得分”里可能混着模型 B 的产出；而当能力差距小到某个量级后，连厂商自己都说分差不再可靠。读 2026 年下半年的任何 Agent 榜单，都要先问两个问题：这个分数是谁跑出来的（哪个模型、哪个 effort、哪个 harness），以及它是不是我们要比较的那个量。

顺带一条与 Ch23 反蒸馏的呼应：Opus 5.5 随附 preserved thinking 防蒸馏机制——官方原文是它”stops API users from editing Claude’s prior context in an attempt to extract Claude’s reasoning”，即阻止 API 用户通过编辑历史上下文来套取推理轨迹；该机制自 Fable 5.1 引入，适用于 2026-08-31 及之后创建的 API 账户的 Fable 5.1 与 Opus 5.5。

1.5 本书拆解的章节地图（v2.1.263 升级建议）

基于 v2.1.198 的新架构特性，并结合 v2.1.220~v2.1.263 的变更，原章节大纲建议升级：

章节主题升级建议
Ch04 Agent Loop主循环补 Dynamic Workflows 脚本运行时解析 + Artifacts 发布作为新的循环终止/产出路径
Ch05 工具系统工具调度补 Claude in Chrome first-party 集成
Ch07 权限与安全权限补 v2.1.200 Manual 默认 + daemon 锁自愈架构；新增 --restricted 受限模式、--permission-prompts none 无头 fail-closed、auto mode Containment Escape 规则、Bash deny 规则收紧与回滚（v2.1.259→2.1.260）
Ch08 多代理代理谱系补 sub-agent 5 层嵌套 + Dynamic Workflows 脚本调度层；新增子代理中断自动续跑、CLAUDE_CODE_SUBAGENT_MODEL_FORCE、跨会话消息 Windows/同机支持
Ch09 Context 记忆上下文补 1M context 自动降级 + extended thinking 协同；Sonnet 5 自动压缩窗口改为完整 1M（约 967K 触发，此前约 934K）
Ch10 MCP 集成工具链边界新增：managedMcpServers 组织托管、allowedMcpServers 语义收窄的迁移风险、Roots/Sampling/Logging 弃用
Ch11 Hooks钩子补 v2.1.197+ matchers 严格匹配（连字符标识符从子串→完全匹配）；新增 v2.1.251 PreModelSwitch/PostModelSwitch 模型切换钩子
Ch12 Skills 与插件技能补 /dataviz 风格方法论沉淀（含可执行验证）；新增 /skill-doctor（显示未使用技能及其上下文成本）；2026-10-17 追加：扩展机制从三种变四种（Skills / MCP / Hooks / Mods），需补 Claude Mods（v2.1.287）的事件模型、isDeferred 与 tool search 的关系（v2.1.293）、以及 sec-default 首个加载的顺序语义
Ch15 设计模式范式补 ultracode 关键字自动编排 + 1M context 单会话决策树
Ch19 提示缓存推理成本新增：promptCacheTtl / subagentPromptCacheTtl、likely_cause 失效诊断、Fable 5.1 缓存覆盖修复、/effort 中途切换不再失效
Ch20 Kairos 之梦未来愿景补 Claude Sonnet 5 + 1M 上下文的百万 token 长程任务愿景
Ch23 反蒸馏攻防补 2026-07 后台 agent auto-PR 的供应链攻击新攻击面

表格按 v2.1.263（2026-09-06） 整理。Claude Code 平均每 1-2 天发布一个版本，读者应以官方 changelog 为准核对最新状态。

1.5 这本书的方法论

本书采用逆向工程的方法论。我们不是在读 Anthropic 的官方文档（它只覆盖了用户可见的功能），也不是在做 API 级别的黑盒测试。我们直接读源码，从代码中提取设计意图。

具体来说：

  1. 分层递进：从全局架构到核心引擎，从多代理到工程细节，按依赖关系从外到内
  2. 代码为证：关键论断附带源码引用，不做无根据的推测
  3. 设计意图优先：不只是”它做了什么”，更关注”为什么这样设计”和”你能从中学到什么”
  4. 持续扩展：第二部分（专题研究）随社区新发现和深入分析不断追加

信息来源

来源优先级用途
泄露的源码（v2.1.88）⭐⭐⭐⭐⭐一手证据
内网源码分析知识库⭐⭐⭐⭐系统性分析的基础
claude-harness.dev⭐⭐⭐⭐交互式源码分析，引导式代码漫步
ClaudeCode-Leak GitHub 仓库⭐⭐⭐高保真泄露档案和技术调查
ClawDecode.net / Claw Code⭐⭐⭐社区分析聚合，交叉验证
Engineer’s Codex 等技术博客⭐⭐⭐高质量社区深入分析
Anthropic 官方文档⭐⭐官方视角补充
HN / X 讨论⭐⭐发现研究点和社区关注方向

泄露事件后，社区分析生态快速形成，已产出数十篇深度分析文章。本书的信息来源会随社区发现持续更新。

适合什么人读

  • 正在构建或计划构建 AI Coding Agent 产品的工程师和技术负责人
  • 对大模型应用架构感兴趣的研究者
  • 想深入理解 “AI + 工程” 如何在生产环境中融合的从业者

不需要你用过 Claude Code。但假设你具备基本的 TypeScript 阅读能力和对 LLM API 调用模式的基础理解。