章节导航 目录 / 共 23 章
目录 阅读指南

阅读指南

全书结构地图、三种推荐阅读路径、前置知识要求——帮你快速找到自己关心的内容

Claude Code 阅读指南 导读

这本书在讲什么

2026 年 3 月底，Anthropic 的一次构建配置疏忽导致 Claude Code 的完整源码泄露——51 万行 TypeScript，42+ 内置工具，6 种代理，44 个 Feature Flag。这是当前业界最成熟的生产级 AI Agent 系统，泄露让我们有了一次难得的机会从内部理解它。

本书是对这份源码的系统性逆向工程。不是 API 文档的翻译，也不是功能介绍，而是从代码中提取设计意图——为什么这样做，而不是那样做。

全书结构

第一部分：全局视角（Ch1-3）
  └── 事件背景 → 工程结构 → 启动流程
        ▼
第二部分：核心引擎（Ch4-7）
  └── Agent Loop → 工具系统 → System Prompt → 权限安全
        ▼
第三部分：多代理与协作（Ch8-10）
  └── 6 种代理 → Context 管理 → MCP 集成
        ▼
第四部分：工程细节（Ch11-14）
  └── Hooks → Skills/插件 → Feature Flags → 认证/多云
        ▼
第五部分：启示（Ch15）
  └── 可复用的 Agent 设计范式总结
        ▼
第六部分：专题研究（Ch16-23，持续追加）
  └── 中训练启示 / 十个教训 / Prompt Caching / KAIROS
      / 竞品对比 / Buddy 宠物 / 反蒸馏

三种阅读路径

🚀 快速路径（2 小时）

只看核心，跳过细节。适合想快速了解 Claude Code 设计精华的读者。

Ch1 → Ch4 → Ch6 → Ch15 → Ch18

  • Ch1：背景和规模感知
  • Ch4：Agent Loop 是系统心脏
  • Ch6：System Prompt 工程是全书信息密度最高的一章
  • Ch15：设计范式总结
  • Ch18：十个最重要的教训（可直接执行的行动建议）

🔧 Agent 开发者路径（6 小时）

完整阅读系统解剖部分。适合正在构建或计划构建 AI Agent 产品的工程师。

Ch1-15 顺序阅读，重点关注：

  • Ch4（Agent Loop）+ Ch5（工具系统）：核心编排机制
  • Ch6（System Prompt）+ Ch7（权限安全）：Context Engineering + 安全架构
  • Ch8（多代理）：生产级多代理设计

之后按兴趣挑选专题（Ch16-23）。

📊 数据/训练工程师路径（3 小时）

聚焦于”从 Agent 工程反推训练数据设计”。适合做模型训练、数据工程的从业者。

Ch1 → Ch6 → Ch7 → Ch9 → Ch17 → Ch19

  • Ch6：System Prompt 的结构 → 训练数据的结构
  • Ch7：权限层次 → 安全对齐数据的层次
  • Ch9：记忆系统 → 长期知识管理的数据范式
  • Ch17（核心）：推理时工程到训练时数据工程的完整映射
  • Ch19：Prompt Caching → 理解推理成本如何影响架构决策

🏛️ 企业/政府部署路径（4 小时）

聚焦于安全合规、权限审计与多云部署。适合负责 AI 工具合规评审的安全工程师和企业架构师。

Ch1 → Ch2 → Ch7 → Ch14 → Ch10

  • Ch1：规模与影响力认知
  • Ch2：五层架构全景理解
  • Ch7（核心）：六层权限规则 + AI 分类器安全架构 — FedRAMP 合规的技术基础
  • Ch14：认证与多云（Bedrock/Vertex Gov 部署）— 企业环境的实际部署路径
  • Ch10：MCP 集成 — 政府环境中的工具链安全边界（Gov Cloud 中外部工具的限制与审批流程）

补充阅读：Ch00 版本说明中的 Claude Code for Government FedRAMP High public beta（2026-07-07）标注。此路径仍属探索性设计——Gov 部署路径的完整性取决于后续 Gov Cloud 功能的公开披露程度。

前置知识

必须：

  • 基本的 TypeScript / JavaScript 阅读能力（代码块占正文 ~20%）
  • 对 LLM API 调用模式的基础理解（messages、tools、system prompt）

有帮助但不必须：

  • 使用过 Claude Code 或类似的 AI 编程工具
  • 了解 MCP（Model Context Protocol）协议
  • 有 Agent 系统的开发经验
  • 知道 AGENTS.md 是什么——自 v2.1.277 起它是 CLAUDE.md 之外的第二个项目指令入口（见下）

约定

  • 项目指令的入口不止一个：v2.1.277 之前只有 CLAUDE.md；此后项目根没有 CLAUDE.md 时 Claude Code 改读 AGENTS.md，/config 的 “Project instructions” 可在四种取值间切换——claude-md-or-agents-md（默认，无 CLAUDE.md 时读 AGENTS.md）/ claude-md-and-agents-md（两份都读，同目录 CLAUDE.md 在前）/ claude-md（只读 CLAUDE.md）/ managed-only（只读组织托管 CLAUDE.md 与 auto memory）。⚠️ 三条边界值得记：通过该项读入的 AGENTS.md 不触发 InstructionsLoaded hooks（由 CLAUDE.md import 或 symlink 的则照常触发）；--add-dir 加进来的目录，其 AGENTS.md 不加载；v2.1.281 之前，Bedrock 等部分后端与遥测关闭的会话只读 CLAUDE.md（该限制已在 v2.1.281 解除）。AGENTS.md 也是本书讨论的第一个跨工具通用载体——同一份文件 Codex、Gemini CLI、Cursor、Copilot 等都能读，项目指令第一次不再绑定单一厂商

  • 源码引用：关键论断附带源码文件路径或链接，标注为”源码引用”

  • 概念性重构：部分代码块是对原始代码的简化重构（非原始代码），会标注”概念性”

  • 设计启示：多数章节结尾有”设计启示”小节，总结可迁移到你自己产品的模式

  • 延伸阅读：专题章节提供外部参考链接，供深入研究

版本说明与时效性

核验方法（建议读者照做）：本书所有版本号以 npm dist-tags.latest（registry.npmjs.org/@anthropic-ai/claude-code）与 Anthropic 官方 changelog 为准，不要用搜索引擎的二手转述——本轮实测第三方 changelog 聚合站最新只写到 v2.1.282，而 npm 与官方 changelog 已是 v2.1.283，二手源滞后整整一个版本。需要逐条核对变更内容时，取 https://code.claude.com/docs/en/changelog.md（该页面由 GitHub 上的 CHANGELOG.md 生成，纯文本、可按 <Update label="..."> 锚点解析）比渲染后的 HTML 页可靠。双通道也会彼此错位（2026-11-04 实测到两种形态）：其一，npm 短暂领先 changelog——2.1.318 于 2026-11-03 晚发布上 npm，changelog 次日（11-04）才登记，滞后约一天属正常；其二，npm 有而 changelog 持续缺席——2.1.315（2026-10-30 发布）至今未在 changelog 登记。读法：锚点版本号以 npm 为准，变更内容以 changelog 为准；反序（changelog 有而 npm 无）才是异常信号。

补两条本轮新确认的核验要点：

  1. 🔴 “最新版”现在有两个答案：latest 与 stable 已经分离。 本轮实测（2026-11-04）：dist-tags 为 latest=2.1.318（2026-11-03） 而 stable=2.1.311（2026-10-26），两者相差 7 个版本（上一轮记录为 9 个，差距在收窄）。生产环境装 @anthropic-ai/claude-code 默认走的是 latest，但许多组织会 pin stable——如果你装的是 stable，你跑的版本比本书说的”最新”还要再落后 7 个版本。所以最终判据不是任何一个 tag，而是你自己机器上的那个数：

    claude --version        # 你自己的锚点
npm view @anthropic-ai/claude-code dist-tags   # 看 latest / stable / next 三个 tag 各停在哪

  2. 📌 版本号跨度 ≠ 已发布版本数，且这个偏差是常态不是偶发。 五次独立观察：

    区间版本号跨度changelog 实际登记空号
    2.1.88 → 2.1.263175137—
    2.1.263 → 2.1.2832018264、279
    2.1.283 → 2.1.3011816297、298
    2.1.301 → 2.1.3181715（npm 实发 16）313

凡引用”自 vX 以来发布了 N 个版本”，一律按官方 changelog 的 <Update label> 条目计数，绝不写跨度。 空号已连续五轮出现（264/279 → 297/298 → 313），npm 版本列表与官方 changelog 双双查不到。⚠️ 另有一类新型错位（2026-11-04 首次观察到）：2.1.315 在 npm 已发布（2026-10-30）但 changelog 从未登记——它不是空号（npm 确实发了），而是”npm 有、changelog 无”的登记缺席。因此空号表要配一条规则：判定一个号段是否”从未发布”，必须双通道都查不到；npm 能查到而 changelog 查不到的，是登记缺席，不是空号。

本书基于 2026 年 3 月 31 日泄露的 Claude Code v2.1.88 源码进行分析。当前最新版本 v2.1.318（2026-11-03，npm dist-tags.latest 确认）——从 v2.1.88 到 v2.1.318 官方 changelog 实际登记 186 个版本（版本号跨度 230，中间号段未全部发布；五轮累计发现的空号为 264、279、297、298、313；另 2.1.315 为 npm 已发布而 changelog 未登记，见上文空号表的分类规则）与 5 大里程碑（Dynamic Workflows / Claude Sonnet 5 / Claude in Chrome GA / Claude Opus 5 / Claude Fable 5.1 与受限模式、组织托管 MCP（2026-08~09））。以下为阅读时需要注意的时效性事项：

源码版本：@anthropic-ai/claude-code v2.1.88，包含 cli.js（13 MB）和 cli.js.map（59.8 MB）。后续版本的实现可能已经变化。

确定性较高的内容（预期长期有效）：

  • 整体架构设计（五层架构、QueryEngine 核心、多代理框架）
  • 设计哲学（Fail-Closed、Context Engineering、分层权限）
  • 工具系统的接口契约（Tool Schema、行为标记）
  • System Prompt 的动态构建机制

可能已变化的内容：

  • 具体的 Feature Flag 名称和启用状态（Anthropic 持续迭代）
  • 工具数量（v2.1.88 为 42+，后续版本可能增减）
  • 模型代号（Capybara、Tengu、Numbat 等可能已启用或更名）
  • Buddy 宠物系统、KAIROS 等实验性功能的发布状态
  • 反蒸馏机制的具体实现（这是攻防对抗，双方都在持续演进）

已知的后续变化：

  • 2026 年 4 月，Anthropic 将 Claude Code 的分发从 npm 转向原生安装程序（curl 安装）
  • Claude Code 开始支持 claude-opus-4-6 模型（源码中的 migrateFennecToOpus 迁移函数已生效）
  • MCP 协议持续演进，新增传输方式和认证模式

重大交互范式变更（2026-05-12，v2.1.139）：

  • /goal 命令：设定完成条件，Agent 多轮自主工作直到达成目标——从”逐轮指令”到”目标驱动自主执行”的范式转变
  • Agent View：多任务全景调度界面，解决多 Agent 多开的分屏焦虑（研究预览版，Ctrl+O 切换视图）
  • 背景：OpenAI Codex 先于 Claude Code 3 天发布 /goal 功能（2026-05-08），Anthropic 随即跟进，说明 AI Coding Agent 的交互范式正在行业层面收敛

版本迭代加速：从 v2.1.88（2026-03-31 泄露）到 v2.1.139（2026-05-12），50天内超过 50 个版本迭代。新增功能包括：/powerup 教学系统、延迟权限处理、MCP 结果存储限制提升至 500K、Plugin bin/ 目录、Focus View（Ctrl+O）、Mantle 接入路径、/goal 自主任务模式、Agent View。这意味着本书分析的 v2.1.88 是一个快照，核心架构设计稳定，但功能细节持续快速迭代。

v2.1.139 → v2.1.142 更新（2026-05 下旬）：

  • Hook 增强：args[] exec form 支持（不再局限于字符串拼接）、continueOnBlock 选项（Hook 阻塞时是否继续执行）、terminalSequence 配置
  • Supervisor 架构：/goal 命令背后的验证架构细节——supervisor agent 负责目标分解和完成度验证，与主 agent 形成双 agent 协作模式
  • Fast mode 升级：切换至 Opus 4.7，编码任务延迟显著降低

阅读路径更新提示：Agent 开发者路径应额外关注 Hook exec form 和 supervisor 架构——这两个变更直接影响多步任务编排的设计模式。

v2.1.154 → v2.1.198 关键变更（2026-05 下旬至 2026-07 初）：

  • v2.1.154 (2026-05-28) — Dynamic Workflows 首发（research preview）：JavaScript 脚本运行时编排 subagents（硬上限 1000 个 Agent，并发 16 个），从”6 种固定代理”扩展为”按需动态编排”。Workflow 脚本本身不直接读写文件——脚本像调度器，subagent 才是 worker。适合”超过 10 个文件或超过 3 个独立子任务”场景。
  • v2.1.160 (2026-06-02) — 触发关键字重命名：Dynamic Workflows 的触发关键字从 workflow 重命名为 ultracode，并组合 xhigh reasoning 推出 /effort ultracode 命令。/deep-research 是内置 workflow 范例。
  • v2.1.172 (2026-06-11) — Sub-agent 嵌套 5 层深：sub-agent 现在可以自己生成 sub-agent（最多 5 层深），解决了”深层 delegation chains 上下文爆炸”问题。配合 Dynamic Workflows 形成”嵌套 = 深度 / workflows = 广度”双维度编排能力。
  • v2.1.197 (2026-06-30) — Claude Sonnet 5 集成：
    • 1M-token 原生上下文（默认开启，无需手动切换）
    • $2 / $10 per Mtok 促销定价（至 2026-08-31）
    • 1M context 自动降级机制（避免会话卡死）
    • Hooks matchers 严格匹配：连字符标识符（code-reviewer、mcp__brave-search）从子串匹配改为完全匹配——可用 mcp__brave-search__.* 匹配整个 MCP server（Ch11 Hooks 章节需补此变更）
    • Streaming idle watchdog 默认开启（5 分钟无事件自动重试）
    • 错误恢复系列修复：后台任务唤醒不再误删对话、多并行请求不再过度计数 rate-limit、remote session 中断后下次 worker 自动恢复
  • v2.1.198 (2026-07-01) — Claude in Chrome GA + 后台 Agent 自动 PR：
    • Claude in Chrome 正式 GA：从限量内测开放给所有用户，浏览器集成作为 first-party 能力
    • 后台 agent 自动 commit / push / 开 draft PR（不再停下来询问）
    • /dataviz skill 上线：图表/仪表盘设计指引 + 颜色调色板校验工具
    • AWS 网关接入 Anthropic 上游（anthropicAws 故障转移链）
    • Explore agent 继承主会话模型（capped at opus）
    • Sub-agents 和 context compaction 继承 extended thinking 配置
    • /agents 向导移除（改为对话式创建/管理 sub-agents）
    • Highlight.js 11 升级（语法高亮精度）
    • Bundle +573.6 kB（+1.9%），prompt token 涨 +22.6%

三条阅读路径更新提示：

  • 快速路径 → 仍可走 Ch1 → Ch4 → Ch6 → Ch15 → Ch18，但应额外注意 Ch15 设计模式章节新增”ultracode 关键字自动编排”（v2.1.160+）与 Ch18 已升级的”半自主开发”教训；若你的使用场景涉及无人值守运行，先读 Ch07 的 --restricted 与 --permission-prompts none；另有一条可以立刻自助执行的：v2.1.283 起 /doctor prompt-audit（亦 /checkup prompt-audit）会审计你的 CLAUDE.md、skills、agents、commands 里”为旧模型写的提示模式”（v2.1.283 还把陈旧路径、陈旧命令与相互矛盾的指令文件排到报告最前）。这是 Anthropic 官方把 Ch18”少写指令”这条反直觉原则做成了命令——也是本书所有建议里唯一一条读者不用读源码就能立刻跑的
  • Agent 开发者路径 → 重点补：
    • Ch8（多代理）+ Dynamic Workflows 动态编排（v2.1.154+）
    • Ch08（多代理）补”sub-agent 嵌套 5 层深”（v2.1.172）
    • Ch11（Hooks）前置阅读 v2.1.197+ 严格匹配变更 + v2.1.251 的 PreModelSwitch/PostModelSwitch 模型切换钩子
    • Ch08（多代理）补”子代理中断自动续跑”（受 CLAUDE_CODE_SUBAGENT_MODEL_FORCE 与传输大小限制影响）
    • Ch15（设计模式）补 ultracode 关键字 + 1M context + extended thinking 协同
  • 数据/训练工程师路径 → 关注 Ch9（记忆系统）补 1M context 长程会话的”上下文压缩”训练数据需求（Sonnet 5 自动压缩窗口已改为完整 1M，约 967K 触发，“上下文压缩”部分的阈值需按新值理解）；Ch19（提示缓存）的提示从”理解推理成本”升级为：prompt cache 已是三件套——可配置 TTL、可诊断失效原因（likely_cause）、子代理有独立 TTL，建议结合 /cost 阅读。2026-09-27 补第四条：effort 档位本身也成了可治理变量——v2.1.267 的 maxEffortLevel 可设在顶层或按模型设在 modelSettings 下，且覆盖 Bedrock / Vertex / Foundry（用户仍可自选更低档）。对成本核算的意义是：effort 从”用户每次手选”变成”可被配置层钉死的上限”，团队预算从此多了一个服务端可控的旋钮

新命令清单：/workflows（v2.1.154+）、/effort ultracode（v2.1.160+）、/dataviz（v2.1.198+）、/goal（v2.1.139+，已升级为 supervisor 架构）

v2.1.202 → v2.1.207 关键变更（2026-07-01 ~ 07-10）：

  • 沙箱内建浏览器 GA（v2.1.202-206, Week 28）：Claude Code 桌面端可从聊天中打开任意网页，安全分类器审查外部站点操作，支持 Google OAuth 登录。与 Artifacts（v2.1.198, 2026-06-18）形成”终端→网页”双输出通道。
  • /doctor 交互式修复（v2.1.205）：从只读报告升级为交互式修复，自动识别无用 skills/MCP servers/plugins、去重 CLAUDE.md、裁剪冗余内容。
  • Per-agent 成本预算 + checkpointing（v2.1.204+）：长时 agent 任务可设美元预算上限，checkpoint 机制支持中断恢复。
  • Bedrock/Vertex/Foundry Auto 模式默认开启（v2.1.207）：无需 CLAUDE_CODE_ENABLE_AUTO_MODE 环境变量，这三后端的默认模型切换为 Claude Opus 4.8。
  • 安全加固：plugin ${user_config.*} shell-injection 修复、non-interactive 执行中静默 consent 安全修复。

政府部署（Claude Code for Government FedRAMP High Public Beta，2026-07-07）：Claude Code 进入 FedRAMP High 授权的 Gov Cloud 公开测试——hash-chained 审计日志、两人审批敏感操作、渗透测试报告。企业部署路径从”商业 SaaS”扩展到”政府合规环境”。

新命令清单（v2.1.202+）：浏览器 Cmd+Shift+B（桌面端快捷键，非 slash command）。

MCP 2026-07-28 SDK Beta 里程碑（2026-06-29）：Python v2 / TypeScript v2 / Go / C# 四个 Tier 1 SDK beta 已发布，支持 stateless core 测试——这是 MCP 2026-07-28 正式发布（7 月 28 日）前的最后一个重大里程碑。

v2.1.212 → v2.1.219 关键变更（2026-07-16 ~ 07-24）：

  • v2.1.212 (2026-07-16) — /fork 命令重构：/fork 拆分为两个独立命令——/fork（创建当前会话的分支副本用于探索替代方案）和 /subtask（在当前会话中启动子任务）。这一变更使子 Agent 启动从隐式变为显式，直接影响 Ch08（多 Agent）和 Ch04（Agent Loop）中与子任务管理相关的讨论。
  • v2.1.216 (2026-07-20) — sandbox.filesystem.disabled 设置：允许完全禁用沙箱文件系统访问。对 Ch07（权限与安全）和 Ch16（潜行模式）的权限模型讨论有直接影响。
  • *v2.1.219 (2026-07-24) — Claude Opus 5 默认模型：本书自写作以来最重大的上游变更。
    • Claude Opus 5 成为默认模型：1M 上下文、128K 最大输出、thinking 默认开启（Opus 4.8 默认关闭）、effort 五档（low/medium/high/xhigh/max）。
    • 定价不变：5/5/25 per Mtok（与 Opus 4.8 完全相同），Fast mode 10/10/50（2.5× 速度）。
    • SWE-bench Pro 从 69.2%→79.2%（+10pp，与 Fable 5 的 80.0% 仅差 0.8pp），ARC-AGI-3 30.2%（4× GPT-5.6 Sol，20× Opus 4.8）。
    • 子 Agent 嵌套深度从 1→3（默认），支持 Agent→Sub-agent→Sub-sub-agent 三级委托链。
    • Thinking 行为变更：thinking: {"type": "disabled"} 仅当 effort ≤ high 时有效（Breaking API change）。
    • Sandbox 安全：sandbox.network.strictAllowlist 拒绝非白名单主机无需提示。
    • Opus 5 自验证行为：模型默认会主动验证自己的输出（写完代码后自动检查、重新运行推理、在返回前捕获错误）。Opus 4.8 仅在显式要求时才执行此类验证——这意味着许多 CLAUDE.md 中的显式验证指令可能变成冗余（Ch06/Ch18 需注意此反直觉设计原则）。

受 v2.1.212-v2.1.219 影响的章节：Ch04（Agent Loop，受子 Agent 嵌套深度 3 影响）、Ch06（系统提示工程，受 Opus 5 自验证行为影响）、Ch07（权限与安全，受 sandbox.filesystem.disabled/strictAllowlist 影响）、Ch08（多 Agent，受 /fork→/fork+/subtask 拆分影响）、Ch18（十条经验，受”少写指令”反直觉原则影响）。

v2.1.220 → v2.1.263 关键变更（2026-07-25 ~ 09-06，44 个版本）：

这六周的迭代集中在两条主线——把权限从”规则配置”扩展成”运行模式选择”，以及把 prompt cache 从”成本背景”变成”可配置、可诊断的一等公民”。

  • 默认模型（v2.1.251 / v2.1.257）：v2.1.251 起 seat-based Enterprise 订阅的默认模型改为 Opus 5，与其他 premium 计划一致；v2.1.257 起新增 Claude Fable 5.1（claude-fable-5-1）并成为默认 Fable 模型——1M 上下文、官方 changelog 逐字记为 1M context, $10/$50 per Mtok with $0.25/Mtok cache reads。⚠️ 坑：Claude apps gateway 会话中 fable / best 别名仍可能解析为 Fable 5，需手动在 /model 选择（v2.1.260 修复了 /model 选择器不显示 5.1 的问题）。
  • 权限与安全（v2.1.248 ~ v2.1.260）：--restricted（或 CLAUDE_CODE_RESTRICTED=1，2.1.248）移除执行命令或代码的内置工具与 WebFetch（除非在 --tools 中显式命名），文件工具保留在工作目录内，拒绝 bypassPermissions，并忽略用户/项目/本地设置文件；--permission-prompts none（2.1.259）面向无人值守的无头主机——任何会触发权限提示的操作自动拒绝，属 fail-closed，与 --dangerously-skip-permissions 的 blanket bypass 是两回事；auto mode 新增 Containment Escape 规则（2.1.257），云元数据凭证获取、出口规避、跨租户访问不再自动批准。
  • “收紧 → 误伤 → 回滚”完整案例（v2.1.259 → v2.1.260）：2.1.259 把 Bash 的 Read() 拒绝规则扩展到选项值文件与 cd DIR && cat FILE 复合命令；2.1.260 因该改动误伤 npm run build 等正常构建命令而回滚。这是权限工程里极难得的一次公开迭代记录，Ch07 值得单独引用。
  • 缓存经济学（v2.1.243 ~ v2.1.260）：promptCacheTtl / subagentPromptCacheTtl（2.1.243，主对话可保持 1 小时缓存、子代理 5 分钟）；experimental.cacheTtl 代理 frontmatter（2.1.248）；/cost 与状态行 prompt_cache 字段新增 likely_cause 诊断（2.1.260，如工具定义变更 / 系统提示被编辑 / 空闲超过 TTL）；修复 Fable 5.1 的 prompt cache 未覆盖”工具结果之后的上下文”的问题（2.1.260）；/effort 中途切换不再使缓存失效（2.1.260）。⚠️ 最后一条值得单独记：Fable 5.1 发布时宣布 cache reads 大幅降价，三天后 changelog 才承认折扣未覆盖”工具结果之后的上下文”——而那恰是 Agent 会话累积最多的部分。定价公告与实现代码路径不在同一个版本落地，是评估任何”降价”发布时的默认假设。
  • MCP 组织化（v2.1.259 / v2.1.261）：managedMcpServers 托管设置允许组织向所有用户推送 HTTP/SSE MCP server（条目形状同 .mcp.json，命名 command 的条目被跳过）；allowedMcpServers 语义随之收窄为”只管用户添加的 server”——升级后原本被过滤的 managed-mcp.json 条目会加载，需要用 deniedMcpServers 关闭，这是一个会真实踩到的迁移风险。
  • Hooks 与子代理（v2.1.251 ~ v2.1.261）：新增 PreModelSwitch / PostModelSwitch 钩子事件（2.1.251，可阻止/确认/注解模型切换）；CLAUDE_CODE_SUBAGENT_MODEL_FORCE（2.1.257）；子代理响应被睡眠/断连/服务器错误中断时自动续跑（2.1.257）；转录超 5MB 的恢复修复（2.1.257）；/skill-doctor 显示未使用技能及其上下文成本（2.1.261）。
  • 上下文（v2.1.247）：Sonnet 5 的默认自动压缩窗口改为完整 1M 上下文，在 1M 窗口上的会话约 967K tokens 触发自动压缩（此前约 934K）。⚠️ 前提限定：967K 这个触发点只有在 1M 窗口上才有意义；在 200K 窗口上不存在这个数字。v2.1.287 起 1M 已成为四大后端的默认（见 §阅读提醒 第 8 条），但 CLAUDE_CODE_DISABLE_1M_CONTEXT=1 或 gateway 只到 200K 时仍会落回 200K——读到这个阈值先确认窗口档位。
  • 其他：/diff 全屏差异面板（2.1.260）；/permissions Auto mode 标签页（2.1.246）；bashOutputMaxChars / taskOutputMaxChars 提高到 128K（2.1.261）；修复 glibc 2.44 Linux 与 macOS 12 的启动崩溃（2.1.245 / 2.1.258）。

v2.1.264 → v2.1.283 关键变更（2026-09-08 ~ 09-25，18 个已发布版本）：

这三周的迭代让 8-9 月那两条主线各自走出了下一步，并且出现了第三条线：权限与模型的”决策位置”开始从本地配置迁往服务端托管。

  • 默认模型第三次变动（v2.1.280, 2026-09-22）：新增 Claude Opus 5.5（claude-opus-5-5）并成为默认 Opus 模型——官方 changelog 逐字记为 1M context, $4/$20 per Mtok with $0.20/Mtok cache reads。Anthropic 官方发布页补充：2026-09-22 发布，Claude 5.5 家族首款，1M 上下文，Fast mode 8/8/40（2.5×），官方称典型任务成本比 Opus 5 降约 40%、输出提速 30%+。⚠️ 选型含义变了：Opus 线输入价从 $5 降到 $4，只有 Fable 5.1（$10）的 40%，而 cache reads（$0.20）比 Fable 5.1 的 $0.25 更低——长会话场景下”便宜的模型”与”便宜的缓存”第一次指向同一个模型，“省钱选 Opus”不再需要拿能力去换。
  • 编排上限解绑（v2.1.269, 2026-09-11）：新增 CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS（1–256），用于抬高 Workflow 工具单次运行的并发 agent 上限（官方限定语是”for inference-bound fan-outs”，即推理受限的扇出场景）。“并发 16”从此是默认值而不是硬上限——这个数字在 Ch01 与 Ch03 各出现多处，一律需加限定语。
  • 安全与治理（本轮最密，v2.1.271 / 275 / 277 / 278 / 283）：
    • v2.1.271 per-command allowed_domains：auto mode + sandbox 下，Bash / PowerShell / Monitor 命令需要的主机与该命令一起被审阅，只对该条命令开放，其余一律拒绝。此前域名一经放行就在整个会话内持续有效。
    • v2.1.275 claude.ai 账号同步：已登录终端会话会同步 claude.ai 账号上启用的 skills 与 plugins（syncClaudeAiSkills: false / syncClaudeAiPlugins: false 可分别退出）。
    • v2.1.277 AGENTS.md 支持：项目根没有 CLAUDE.md 时改读 AGENTS.md，可在 /config 的 “Project instructions” 切换。
    • v2.1.278 auto mode 分类器搬到服务端：Claude API / Enterprise / Bedrock / Vertex / Foundry / gateway 用户的 auto mode 默认改用服务端分类器，不计费 classifier 开销（CLAUDE_CODE_AUTO_MODE_SERVER=0 退出）；/status 新增 “Auto mode server” 行显示本会话分类器跑在哪。⚠️ 官方措辞是 “warns on billed fallback”——回退到本地分类器时仍可能计费，退出前先看 /status。
    • v2.1.283 availableModelsMatch: "exact" + deniedModels：托管设置里 availableModels 的条目在 exact 模式下只允许它点名的那一个模型版本，新模型发布后在被明确列出之前一律保持阻断；deniedModels 则在 availableModels 放行时也能单独拉黑。新模型从”默认可用”变成”默认被阻断”，这是组织治理侧最需要提前知道的一条。
  • 缓存与 effort 成为可治理项（v2.1.267 / 2.1.274 / 2.1.280）：maxEffortLevel 设置（顶层或按模型设在 modelSettings 下）给 effort 加了天花板，覆盖 Bedrock / Vertex / Foundry，用户仍可自选更低档；--system-prompt-snapshot off 让系统提示每次请求重渲染而不复用会话记录的提示（用于迭代提示文本）；CLAUDE_CODE_MCP_STARTUP_WAIT_MS 限定首个非交互轮次等待 MCP server 连接的时间（0 = 不等）；CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH 可改 MCP 工具描述与 server 指令的 2,048 字符上限。
  • 插件生态出现第一个质量闸门（v2.1.269）：claude plugin eval 对插件跑评测套件并给出可复现的打分结果（JSON + HTML 报告）。⚠️ 版本号曾被第三方写成 v2.1.271（09-14），官方实为 v2.1.269（09-11）——二手版本号即使是最新的那条也可能是错号，滞后的旧值还能靠”取最新”修正，错号不能。
  • AGENTS.md 的后端覆盖（v2.1.281, 2026-09-23）：AGENTS.md 支持扩展到 Amazon Bedrock / Google Vertex AI / Microsoft Foundry / LLM gateway 以及遥测关闭的会话。⚠️ 这一点与不少第三方转述冲突——它们称 “Bedrock / Vertex / Foundry 暂未上线”，那是 v2.1.277~2.1.280 期间的真实状态，v2.1.281 已改变。官方文档的表述是”Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, read CLAUDE.md files only. On those versions, update Claude Code”。

v2.1.284 → v2.1.301 关键变更（2026-09-28 ~ 10-15，16 个已发布版本；297 与 298 未发布）：

  • 默认模型线的另外两条也换代了——本章此前只跟了 Opus 线（4.8 → 5 → 5.5）与 Fable 线（5 → 5.1），本轮补齐：

    • v2.1.284（2026-09-28）：新增 Claude Sonnet 5.5（claude-sonnet-5-5），成为 Anthropic API 上的默认 Sonnet 模型——changelog 逐字记为 1M context, $2/$10 per Mtok with $0.20/Mtok cache reads。
    • v2.1.293（2026-10-07）：新增 Claude Haiku 5.5（claude-haiku-5-5），成为默认 Haiku 模型——changelog 逐字记为 1M context, $0.10/$0.50 per Mtok ($0.50/$2.50 for prompts over 100K)。
    • ⚠️ Haiku 5.5 带来一种本章此前从未写过的新定价结构：按提示长度分段计价——超过 100K 的输入/输出单价都跳到 5×。这直接影响”用 /cost 估算成本”的建议：长 prompt 场景下 Haiku 不再是”便宜的小模型”，选 Haiku 前先看你的 prompt 长度落在哪一段。

  • 🔴 定价公告会被后续版本改——这次是公告本身被改。 v2.1.296（2026-10-09） 把 /cost、状态行、--max-budget-usd 与 SDK 四处成本计算统一改为：Sonnet 5.5 的 cache reads 按 $0.10/Mtok 计价（原 $0.20）——而 $0.20 是 11 天前（v2.1.284） 刚公告的。详见 §缓存提示 处的独立警示。

  • Ultracode 不再是 effort 档，而是与 effort 正交的开关（v2.1.284）：VSCode 下 Effort 滑块下方新增独立的 Ultracode on/off 开关，取代了滑块上的 Ultracode 档位；模型胶囊在任何 effort 档都显示 ”· Ultracode”；配套三个可绑定 action（effortSlider:decreaseEffort / increaseEffort / toggleUltracode）。⚠️ 这是概念位置变了，凡本书提到 ultracode 的地方都要重新定位——尤其 Ch15 设计模式里”ultracode 关键字自动编排”（v2.1.160 那条仍成立，但它现在不是 effort 轴上的点）。

  • 1M 上下文从”某些模型的能力”变成跨后端的默认行为：

    • v2.1.287（2026-10-01）：Opus 4.7+ 与 Fable 在 Bedrock / Vertex / Foundry / Claude apps gateway 上默认使用 1M 窗口，且不再需要 [1m] 后缀（CLAUDE_CODE_DISABLE_1M_CONTEXT=1 可保持 200K）。
    • v2.1.285（2026-09-29）：自定义 ANTHROPIC_BASE_URL 之后的会话同样用上模型 1M 窗口（Opus 4.7+ / Sonnet 5+ / Fable）；若 gateway 只到 200K，需 /autocompact 200k。
    • v2.1.299：新增 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 改变空闲压缩的 200K token 最小门槛；settings.json 里 "idleCompaction": false 可关闭（两者均需 v2.1.290+）。

  • 🔴 同一个常量在 4 天内被改了三次，且三个上限并存——MCP 描述长度：

    版本改了什么上限
    v2.1.295经 tool search 加载的 MCP 工具描述2,048 → 16,384
    v2.1.296提前发送的 MCP 工具描述 + MCP server 指令2,048 → 4,096
    v2.1.299Anthropic 第一方 MCP server（api.anthropic.com）的工具描述与指令不再截断（原 4,096）

    上一轮（v2.1.280）刚把”2,048”记录为可调上限，11 天后默认值本身就变了，而且不是一个值，是三个。

  • /advisor——本章编排叙事里没有一格放得下它：v2.1.300 把 /advisor 带到 Claude Platform on AWS（该能力此前已存在：v2.1.287 修配对检查——Sonnet 5.5 现可为 Opus 4.7/4.8 提供建议，API 会拒绝的组合提前标出而非静默丢弃；v2.1.295 修对话框对已失效 advisor 仍打勾）。规则是：不主动运行任何 advisor，须经 /advisor、advisorModel 或 --advisor 显式选择，CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 关闭。v2.1.290 起 mod 的 turn.step hook 增加 serverTurnUses，能看到 API 自己跑的工具调用（即 advisor） 的 id / 名称 / 输入 / 起止时间。

    📌 定性建议：advisor 不是子代理（不是干活的 worker），而是给主模型提供建议的另一个模型。本书 Ch04/Ch08 的代理分类里没有它的位置，建议按”第五类参与者”单列，不要硬塞进代理体系。

  • MCP 协议版本 2026-07-28 分三批铺开（不是一次性）：v2.1.292 本地（stdio）server 连接默认协商（含 Bedrock / Vertex / Foundry）→ v2.1.295 claude.ai connectors → v2.1.299 cloud session 与 Remote Control connectors；MCP_PROTOCOL_NEGOTIATION=legacy 可退出。

  • 治理线再补一环：v2.1.285 新增 allowedProviders 托管设置，限定一台机器可用的 API provider 白名单（Anthropic API / 自定义端点 / Bedrock / Mantle / Vertex AI / Foundry / Claude Platform on AWS / Cloud gateway）。与上一轮的 availableModelsMatch / deniedModels 构成一条完整的线——先管”能用哪些模型”，再管”能用哪些 provider”。

  • effort 现在是四个方向可控的量（补两条本章未写的）：① 用户手选 /effort——⚠️ v2.1.295 修了一个误导：Max effort 只对当前会话生效，/model 曾误报为”已存为新会话默认值”；② maxEffortLevel 封顶（v2.1.267，本章已写）；③ v2.1.292 给 Agent 工具加 effort 参数，可让子代理跑在指定档；④ 与 Ultracode 正交叠加（v2.1.284）。另：v2.1.287 起被 flagged 消息后的自动模型切换保留当前 effort 档；v2.1.299 起 /usage 会对 max effort / workflows / always-on context / 大工具结果 告警。

v2.1.303 → v2.1.318 关键变更（2026-10-18 ~ 11-03，15 个已发布版本；313 未发布，315 见登记缺席说明）：

  • 🔴 模型功能弃用的第一个带硬移除日期的样本（v2.1.316，changelog 逐字）：“Deprecated fast mode for Opus 4.8 as of October 30, 2026; it will be removed on November 30, 2026. After removal, fast mode requests on Opus 4.8 return an error and do not fall back to standard Opus 4.8. Migrate to Opus 5.5 to keep the speedup.”——弃用（10-30）→ 移除（11-30）→ 无回退三段式，且官方指定迁移目标为 Opus 5.5（Opus 5.5 成为 fast mode 唯一承载体，见 Ch01 定价警示框的方向三）。
  • effort 治理扩到第五个控制点（v2.1.316，逐字）：CLAUDE_CODE_SUBAGENT_EFFORT “to set the effort level subagents run at when nothing else names one, instead of inheriting the session’s”——子代理的缺省 effort 档不再继承会话档。同版新增 CLAUDE_CODE_DISABLE_ULTRATHINK 可关闭 ultrathink 关键词。
  • 权限线的新地板（v2.1.314，逐字）：permissions.blockWritesOutsideWorkingDirectories——“Write, Edit and NotebookEdit refuse paths outside the working directories in every permission mode”。与此前 fail-closed 样本的差别：不再是”默认更保守”，而是跨权限模式的硬边界（详见 Ch02）。
  • 治理执行点可观测化（v2.1.307，逐字）：新增 claude_code.safety_event OTel 事件——“for each tool call a permission rule, auto mode, a safety check, a hook or the sandbox stopped, prompted or sent back”——权限/安全体系每次实际出手都进遥测，“决策 → 遥测”闭环首次出现在执行层。
  • Monitor 工具多云扩展（v2.1.310）：Monitor 工具与 plugin monitors 扩展到 Bedrock / Vertex / Foundry 及遥测关闭会话，长前台 sleep 在该环境同步封禁。
  • 空闲压缩跨界面统一（v2.1.314）：idle compaction（200K+ token 会话空闲后摘要、缓存过期后使用摘要）从终端扩展到 VS Code 与 Claude Desktop 的 Code tab——Ch09 的”967K 触发阈值”提示现在要加”空闲压缩已跨界面统一”这一前提。
  • hook 失败闭环补第三段（v2.1.317，逐字）：onFailure: "block" 扩展到 Agent SDK hook 回调（“a callback that fails blocks the action instead of letting it run”）——与 v2.1.290（validate 可检查 gating hooks 有无 .catch）、v2.1.295（command/HTTP hooks 可声明 onFailure: “block”）构成”可检查 → 可声明 → 声明面全覆盖”三段式（详见 Ch02 Mods 小节）。

受 v2.1.284-v2.1.301 影响的章节：Ch01（默认模型线从只跟 Opus 扩到 Sonnet 5.5 / Haiku 5.5 两线；规模表与”默认模型”相关段落需同步）；Ch03（1M 上下文跨后端默认化 + 空闲压缩 200K 门槛，改变了”窗口多大”这个启动前提）；Ch08（多 Agent：Agent 工具新增 effort 参数；/advisor 属于”第五类参与者”而非代理）；Ch10（MCP 集成：本地 stdio 默认协商 2026-07-28 协议版本；MCP 描述三个并存上限）；Ch14（认证与多云：allowedProviders provider 白名单）；Ch15（设计模式：Ultracode 从 effort 档改为正交开关，“ultracode 关键字自动编排”需重新定位）。

受 v2.1.303-v2.1.318 影响的章节：Ch01（默认模型线补 fast mode 弃用时间线：Opus 4.8 fast mode 2026-11-30 移除且无回退，迁移目标 Opus 5.5；effort 叙事从四方向扩为五方向）；Ch03（idle compaction 跨界面统一、Monitor 多云扩展）；Ch07（blockWritesOutsideWorkingDirectories 全权限模式硬边界、claude_code.safety_event 治理遥测）；Ch09（空闲压缩跨界面统一，967K 阈值的界面前提）；Ch11（Agent SDK hook 回调 onFailure: "block"）；Ch12（Mods 的 settings.read 组织设置天花板、decider: "person" 与 skill hooks 配额，详见 Ch02 提案执行）。

受 v2.1.264-v2.1.283 影响的章节：Ch01（规模表与版本演进的默认模型线，Opus 5 → Opus 5.5；“并发 16”四处需加限定语）；Ch02（工程结构：v2.1.277 AGENTS.md 改变”配置层读什么文件”；v2.1.265 --plugin-dir 可指向插件文件夹且运行时热拾取、工具结果落盘新增 1 GB 上限；v2.1.280 MCP 描述 2,048 字符上限可调）；Ch03（启动与运行模式：v2.1.274 的 MCP 启动等待改变了”MCP 连接是否阻塞首轮”这一启动假设；v2.1.269 并发上限解绑直接影响 Dynamic Workflows 段；v2.1.278 分类器上移改变了权限决策发生的位置；v2.1.283 让模型可用性成为后端选择之外的第四个维度）；Ch06（系统提示工程：v2.1.267 --system-prompt-snapshot off 是”系统提示文本迭代”的官方工具）；Ch07（权限与安全：per-command allowed_domains、服务端分类器、availableModelsMatch）；Ch12（插件：v2.1.269 claude plugin eval）。

受 v2.1.220-v2.1.263 影响的章节：Ch07（权限与安全，受影响最大——--restricted、--permission-prompts none、auto mode Containment Escape 规则、Bash Read() 规则的收紧与回滚）；Ch19（提示缓存，新增受影响章节——TTL 可配置、likely_cause 失效诊断、Fable 5.1 缓存覆盖修复、/effort 切换不失效）；Ch10（MCP 集成，managedMcpServers 组织托管与 allowedMcpServers 语义收窄的迁移风险）；Ch11（Hooks，新增 PreModelSwitch/PostModelSwitch——此前只需关注 v2.1.197+ 的 matcher 严格匹配）；Ch09（上下文与记忆，Sonnet 5 自动压缩窗口改为 967K 触发）；Ch08（多代理，子代理中断自动续跑、跨会话消息 Windows/同机支持、--append-subagent-system-prompt-file）；Ch12（Skills 与插件，/skill-doctor）；Ch18（十条经验，与 Opus 5 自验证叠加后”少写指令”原则需再校准）。

引用建议：引用本书内容时，建议标注”基于 v2.1.88 分析”。对于具体的代码行号、Feature Flag 值等细节，以最新版本（v2.1.318，2026-11-03）为准。架构级别的分析和设计哲学的讨论则具有较长的有效期。以上 8-11 月变更的一手来源为 Anthropic 官方 changelog。

阅读提醒：本书写作于 Claude Code v2.1.88-v2.1.207 时期，默认模型为 Opus 4.8。自 v2.1.219（2026-07-24）起默认模型为 Claude Opus 5；自 v2.1.280（2026-09-22）起默认 Opus 模型再变为 Claude Opus 5.5——默认模型线在五个月内变了三次，读本书任何涉及”默认模型”的段落都要先确认它指的是哪一代。读者在使用本书代码示例和性能分析时，需注意以下行为差异：(1) thinking 开销——Opus 5 默认开启 thinking，同一 prompt 的 token 消耗可能高于本书假设；(2) 子 Agent 嵌套——本书假设深度=1，v2.1.219 起默认深度=3；(3) 自验证行为——Opus 5 会主动验证输出，可能使部分 Ch06/Ch18 中的 CLAUDE.md 指令冗余。本书将在后续版本中更新这些变更的影响分析。(4) Fable 模型线已与 Opus 线分叉——自 v2.1.257 起默认 Fable 模型为 Claude Fable 5.1（官方 changelog 逐字记为 $10/$50 per Mtok with $0.25/Mtok cache reads），与 Opus 5（5/5/25，另据 Anthropic 官方定价页，不出自 changelog）是两条不同的价格/能力线；gateway 会话中 fable 别名可能仍解析到 Fable 5，需用 /model 手动选择。(5) 自 v2.1.280 起 Opus 线再换代——默认 Opus 模型为 Opus 5.5（claude-opus-5-5，1M 上下文），官方 changelog 逐字记为 1M context, $4/$20 per Mtok with $0.20/Mtok cache reads，官方称典型任务成本比 Opus 5 降约 40%。代价关系反转：Opus 5.5 输入价（\$4）是 Fable 5.1（\$10）的 40%，cache reads（\$0.20）也比 Fable 5.1 的 \$0.25 更低，长会话下”选便宜模型”与”省缓存费”第一次不再冲突。(6) Sonnet 线也换代了（）——自 v2.1.284（2026-09-28） 起 Anthropic API 上的默认 Sonnet 模型为 Sonnet 5.5（claude-sonnet-5-5），官方 changelog 逐字记为 1M context, $2/$10 per Mtok with $0.20/Mtok cache reads；⚠️ 但见 §缓存提示：该 cache reads 单价在 11 天后（v2.1.296）被改为 $0.10。(7) Haiku 线也换代了，并带来一种新定价结构——自 v2.1.293（2026-10-07） 起默认 Haiku 模型为 Haiku 5.5（claude-haiku-5-5），官方 changelog 逐字记为 1M context, $0.10/$0.50 per Mtok ($0.50/$2.50 for prompts over 100K)。⚠️ 括号里那半句是本章此前从未出现过的结构：按提示长度分段计价，超过 100K 后输入输出单价都跳到 5×——长 prompt 场景下 Haiku 不再是”便宜的小模型”，选 Haiku 前先看你的 prompt 长度落在哪一段。(8) 上下文窗口不再是隐含前提，而是一个需要显式确认的变量——本书写作时默认是 200K；v2.1.287（2026-10-01）起，Opus 4.7+ 与 Fable 在 Bedrock / Vertex / Foundry / Claude apps gateway 上默认使用 1M 窗口，且不再需要 [1m] 后缀（CLAUDE_CODE_DISABLE_1M_CONTEXT=1 可保持 200K），v2.1.285 起自定义 ANTHROPIC_BASE_URL 的会话同样用上 1M。

📌 这一条对本书所有”约 N K tokens 触发自动压缩”类数字都是前提：例如 §上下文（v2.1.247）那条 967K 触发点，只有在 1M 窗口上才存在；在 200K 窗口上这个数字根本不存在。读到任何上下文阈值时，先确认你的窗口是 200K 还是 1M。 同族观察：[1m] 后缀被取消，与 Ultracode 从 effort 档变开关是同一类迁移——本来靠命名约定 / 档位表达的东西，变成了默认行为或独立的正交开关。

⚠️ 定价类事实的半衰期比功能类更短，而且两个方向都出过事。

  • 方向一：实现没跟上公告。 Fable 5.1 发布时宣布 cache reads 大幅降价，三天后 changelog 才承认折扣未覆盖”工具结果之后的上下文”——而那恰是 Agent 会话累积最多的部分（本章已记录）。
  • 方向二：公告本身被改。 v2.1.296（2026-10-09）把 /cost、状态行、--max-budget-usd 与 SDK 四处成本计算统一改为：Sonnet 5.5 的 cache reads 按 $0.10/Mtok 计价（原 $0.20，11 天前 v2.1.284 刚公告）。

实践含义：“降价”类公告在落地后的两周内应该再核一次，而且要用 /cost 实测，不只看公告页。

⚠️ “常量 → 可调参数”不是演进的终点：默认值也会变，而且刚被参数化的常量恰恰是最可能再被改的那个。

现场证据就是 MCP 工具描述长度：上一轮（v2.1.280）刚把它记录为可调参数（默认 2,048），11 天后（v2.1.295/296/299）三个不同的默认值先后被改，上限分别变成 16,384 / 4,096 / 不截断。

因此本章记录”可调参数”的三要素（当前默认值 + 可调区间 + 调整所需版本）应当补第四要素：这个默认值上次被改是什么时候。 一个刚被参数化的常量，是最不稳定的那个。

缓存提示：v2.1.243 起 promptCacheTtl（主对话，最长 1 小时）与 subagentPromptCacheTtl（子代理，5 分钟）可配置。若长会话的实际成本与书中假设不符，先看 /cost 与状态行的 prompt_cache.likely_cause（工具定义变更 / 系统提示被编辑 / 空闲超过 TTL），再调 TTL——不要直接归因于”模型变贵了”。