章节导航 目录 / 共 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 页可靠。

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

  1. 🔴 “最新版”现在有两个答案：latest 与 stable 已经分离。 本轮实测（2026-10-16）：dist-tags 为 latest=2.1.301（2026-10-15） 而 stable=2.1.292（2026-10-06），两者相差 9 个版本。生产环境装 @anthropic-ai/claude-code 默认走的是 latest，但许多组织会 pin stable——如果你装的是 stable，你跑的版本比本书说的”最新”还要再落后 9 个版本。所以最终判据不是任何一个 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

    凡引用”自 vX 以来发布了 N 个版本”，一律按官方 changelog 的 <Update label> 条目计数，绝不写跨度。 空号已连续四轮出现（264/279 → 297/298），npm 版本列表与官方 changelog 双双查不到。

本书基于 2026 年 3 月 31 日泄露的 Claude Code v2.1.88 源码进行分析。当前最新版本 v2.1.301（2026-10-15，npm dist-tags.latest 确认）——从 v2.1.88 到 v2.1.301 官方 changelog 实际登记 171 个版本（版本号跨度 213，中间号段未全部发布；四轮累计发现的空号为 264、279、297、298）与 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.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.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.301，2026-10-15）为准。架构级别的分析和设计哲学的讨论则具有较长的有效期。以上 8-10 月变更的一手来源为 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——不要直接归因于”模型变贵了”。