本章的主题是 “Teams 与多进程协作”。这一章深入剖析了 Claude Code 的 Swarm 团队协作机制 —— 一种基于平面结构的多 Agent 协作模型。与第20章介绍的“父子层级”派生模型不同，Teams 系统通过构建一个平面的团队，利用消息传递、共享状态和分布式调度来完成复杂任务。 以下是该章节的核心内容总结： 1. 核心定位：平面 Swarm 协作模型 * 平面结构约束：系统通过 TeamCreateTool 创建团队，团队名册（TeamFile）是一个扁平数组。为了防止协调逻辑混乱，系统设定了强硬的架构约束：队友不能派生其他队友，且进程内队友不能派生后台 Agent。 * 身份标识：队友使用 TeammateAgentContext 上下文，其 ID 格式统一为 name@team-name（如 researcher@my-team），在 UI 中会被自动分配不同的终端颜色，便于一眼识别身份和归属。 2. 调度内核：共享任务图（TaskList & DAG） Teams 的核心价值不在于“聊天”，而在于共享任务图（Shared Task Graph）： * Team = TaskList：团队与任务列表是一对一绑定的，创建团队的同时就会初始化对应的任务目录。 * DAG 任务依赖：任务不仅有状态，还包含 blocks 和 blockedBy 字段，将其从普通的 Todo 清单提升为显式的有向无环图（DAG）依赖节点。任务只有在所有前置依赖（Blockers）都完成后才变为可执行状态。 * 自动抢占（Auto Claim）：运行时通过 useTaskListWatcher.ts 监听任务目录。当 Agent 空闲或目录变化时，系统会自动筛选并抢占（claim）一个满足条件（pending、无 owner、无 blocker）的任务并分发给 Agent 执行。这实现了调度与推理的分离，Agent 之间不需要复杂的自然语言协商，冲突直接由运行时的状态机原子锁解决。 * 事件驱动收尾：任务完成后，会触发 TaskCompleted 和 TeammateIdle 专用事件钩子，用于通知 Leader 或驱动后续自动化流程。 3. Mailbox 通信协议与结果回传 * SendMessageTool 寻址：支持多种寻址方式，包括具体队友名称、广播（*）、本地 IPC 套接字（uds:<socket-path>）以及远程控制节点。 * 文件系统邮箱：消息异步写入本地目录 ~/.claude/teams/{teamName}/inboxes/{agentName}.json。并发控制通过 async lockfile 和指数退避重试来保证安全。 * 控制消息：邮箱不仅传递文本，还承载结构化的 JSON 控制命令，如 idle 通知、shutdown_request/response（优雅关闭）和 plan_approval_response（计划审批）。 * Worker 结果回传：在协调者模式下，Worker 的工作结果会格式化为 <task-notification> XML 块作为用户角色消息注入协调者的上下文，防止协调者将其误判为用户指令。 4. 三种物理后端与进程隔离 系统支持三种物理后端，通过统一的接口管理，由运行时自动选择最优方案： 1. Tmux：独立 CLI 进程，在 tmux 中分屏显示，是 Linux/macOS 的默认后端。 2. iTerm2：独立 CLI 进程，在 iTerm2 中分屏显示。 3. In-Process（进程内回退）：无 tmux/iTerm2 环境时，在同一进程内运行，通过 AsyncLocalStorage 隔离上下文，消息通信改用内存队列。 5. 权限同步与 Leader 代理审批 为了确保安全，运行在独立进程或分屏中的队友无权自行审批危险工具调用： * 当 Worker 触发权限检查时，会创建审批请求写入 permissions/pending/ 并发送到 Leader 的邮箱。 * Leader 轮询并检测到请求后，在其终端向用户展示并等待审批。 * 审批通过后，结果写入 permissions/resolved/，Worker 轮询获取结果后继续执行，确保人类对危险操作拥有绝对控制权。 6. 共享团队记忆（Team Memory） * 团队成员共享位于 ~/.claude/projects/{project}/memory/team/MEMORY.md 的团队记忆，与个人记忆相互独立。 * 为了防止恶意项目代码通过路径逃逸攻击团队记忆，系统建立了极其严密的路径安全验证，能强力拦截空字符（Null byte）注入、URL 编码遍历、Unicode 正规化攻击以及符号链接循环（ELOOP）等漏洞。 7. 工程设计模式：基于文件系统的状态外化 Teams 做出了一个务实且反直觉的设计选择：用本地文件系统邮箱代替传统的 IPC/RPC。这种“共享状态”而非“共享内存”的设计，在 Agent 协作场景下带来了显著的优势：进程崩溃后消息不丢失（高持久性）、可以直接使用 cat 命令调试（高可观测性），且天然支持锁机制。

本次的主题是**“Agent 派生与编排”**。这一章深入解析了 Claude Code 如何通过多智能体协作来解决单 Agent 上下文窗口有限且无法并行处理复杂任务的问题。 以下是该章节的核心内容总结： 1. 核心动力：从“单兵”到“分治” 单智能体循环（Agent Loop）在面对如“调查 Bug、修复、运行测试、写 PR”等大规模任务时，容易因上下文填满而丢失细节 。多智能体系统的引入是为了实现并行化和分治策略。 2. 三种 Agent 模式（通过 AgentTool 派生） 系统通过统一的入口工具 AgentTool 提供三种递进的协作模式： 标准子 Agent (Subagent)：启动一个全新的、上下文隔离的对话。它像是一个“刚进房间的聪明同事”，只负责独立的小任务，完成后返回摘要。 Fork 模式（实验性）：继承父 Agent 的完整对话上下文和系统提示词。它通过极其精密的指令结构实现提示词缓存（Prompt Cache）共享，最大化执行效率。 协调者模式 (Coordinator Mode)：主 Agent 转型为不直接编码的“指挥官”，指挥 Research、Synthesis、Implementation 和 Verification 四类 Worker 进行阶段化协作。 3. 验证 Agent (Verification Agent) 这是内置 Agent 中设计最精良的一个，专门用于质量把关： 严格只读：被明确禁止修改项目文件，但可以在临时目录运行测试脚本。 对抗性探测：提示词要求它必须执行边界值或幂等性等对抗性检查，不能被简单的“测试通过”报告迷惑。 强制判定格式：必须以 VERDICT: PASS/FAIL/PARTIAL 结尾，提供明确结论。 4. 协作与编排机制 Agent 间通信：通过 SendMessageTool 实现消息路由，支持名称寻址、广播以及跨机器寻址。 异步生命周期管理：后台 Agent 拥有独立的生命周期，不随父 Agent 的取消而停止，必须显式通过命令终结。 Worktree 隔离：支持在临时 Git Worktree 中执行修改，确保实验性变更不会污染主分支。 5. 远程执行：Bridge 架构 这一机制将 Agent 的能力延伸到网络之外： 客户端-服务器-工作者模式：允许用户从 claude.ai 网页端触发本地机器上的 Agent 会话。 权限远程代理：本地子进程发出的权限请求会跨网络转发给网页端用户实时审批。 6. 核心设计洞察 不要委托理解 (Never delegate understanding)：协调者模式强调指挥官必须亲自阅读并理解 Worker 的结果，而不是盲目相信摘要，这是保证任务质量的关键。 分层信任模型：队友系统采用扁平化结构，禁止队友再次派生队友，以防止形成不可控的深层递归链。 总结而言，Claude Code 如何通过隔离、继承与协调三种维度的巧妙平衡，将 AI 编码能力从“单人对话”升级为“工业级多 Agent 生产线”。

本章深入剖析了 Claude Code 如何通过自然语言指令集，在不修改源码的情况下精准控制 AI Agent 的行为逻辑。 以下是该章节核心内容的总结： 1. 核心哲学：用户指令覆盖默认行为 CLAUDE.md 系统不仅是一个配置文件，而是一套指令注入系统。其设计的最高准则被字面注入到系统提示词中：“用户指令覆盖（OVERRIDE）任何默认行为，模型必须严格遵守”。这使得用户的个性化规范在冲突时具有比内置指令更高的优先级。 2. 四级优先级层叠模型 系统按照从低到高的优先级顺序加载指令，最后加载的层级拥有最高效力（利用了大模型的“近因偏差”）： * Managed Memory (L1)：最低优先级，用于企业 IT 部门推送全局策略（如 /etc/claude-code/CLAUDE.md）。 * User Memory (L2)：用户私有的全局指令，适用于所有项目。 * Project Memory (L3)：团队共享的项目规范（如 CLAUDE.md 或 .claude/rules/*.md）。 * Local Memory (L4)：最高优先级，仅本地生效的覆盖（如 CLAUDE.local.md），通常被放入 .gitignore。 3. 精密的加载与处理机制 * 路径遍历与 Git 意识：加载逻辑会从当前目录向上遍历至文件系统根目录。系统还能智能处理 git worktree 场景，防止主从仓库指令重复加载。 * 模块化 @include：支持通过 @path 语法引用外部文件，实现指令重用。为保证安全，系统限制了最大 5 层嵌套，并具备循环引用防护和外部路径安全审查机制。 * HTML 注释剥离：在注入上下文前，系统会自动移除 <!-- --> 注释，允许用户在指令文件中保留内部笔记而不消耗 Token 空间。 4. 条件规则与 Token 预算管理 为了在 200K Token 的“竞技场”中节省开销，系统引入了按需加载模式： * Frontmatter Paths：规则文件可以通过 YAML 头部声明 paths 范围。只有当模型操作的文件路径匹配这些 glob 模式时，该规则才会被注入上下文。 * 大小警告：单个文件的推荐上限为 40,000 字符。超大文件会触发警告，以防挤压工作空间 Token。 5. 三大工程模式提炼 * 分层覆盖配置模式：仿效 CSS 的层叠机制，解决不同层级用户（企业 vs 个人）的控制权冲突。 * 显式覆盖声明模式：通过强硬的元指令（"MUST follow...OVERRIDE"）引导模型遵从度。 * 按需条件加载模式：利用文件路径匹配实现规则的“懒加载”，极大优化了有限的上下文预算。 总结而言，展示了 Claude Code 如何通过一套层叠、模块化且具备路径感知能力的指令系统，赋予用户对 AI 行为的最终裁决权。这不仅是配置管理，更是生产级 AI Agent 实现“全局默认”与“局部定制”平衡的关键基础设施。

主题是 “Hooks —— 用户自定义拦截点”。本章深入剖析了 Claude Code 如何通过一套精密的 Hooks 系统，允许用户在 AI Agent 生命周期的 26 个关键事件点插入自定义逻辑，实现从格式检查到自动部署的任意工作流定制。 以下是该章节的核心内容总结： 1. 核心定位：可扩展的工作流引擎 Hooks 系统填补了内置安全防线（权限系统与 YOLO 分类器）的空白。它不只是简单的“回调函数”，而是解决了信任边界、超时控制、语义转换和配置隔离四个核心难题的工程方案。 2. 四种 Hook 类型 系统支持四种可持久化的 Hook 类型，满足不同复杂度的需求： * command（Shell 命令）：最基础类型，支持 Bash 和 PowerShell，可利用 $ARGUMENTS 获取工具输入，并通过退出码与模型通信。 * prompt（LLM 评估）：将输入发送给轻量级模型进行评估，用于快速判断。 * agent（Agent 验证器）：最强大类型，启动一个完整的 Agent 循环来验证复杂条件（如“验证单元测试是否全部通过”）。 * http（Webhook）：将数据 POST 到指定 URL，具备显式的环境变量白名单保护机制。 3. 五大类生命周期事件 Hooks 覆盖了 Agent 运行的全过程，共 26 种事件： * 工具执行：PreToolUse（可拦截或重写命令参数）、PostToolUse 等。 * 会话阶段：SessionStart（环境初始化）、Stop（响应结束前拦截）、UserPromptSubmit（提交前清洗）等。 * 多 Agent 协作：SubagentStart、TaskCompleted 等。 * 文件与配置：文件变更、目录切换及规则文件加载。 * 压缩与 MCP：对话压缩前后及 MCP 服务器的交互点。 4. 执行模型与退出码协议 * 异步生成器架构：采用 async function* 设计，支持流式处理 Hook 结果，每个 Hook 独立 yield 进度和最终状态。 * 超时策略：默认超时为 10 分钟以适应构建任务；但 SessionEnd 事件被严格限制在 1.5 秒内，以确保用户退出的流畅性。 * 退出码语义：这是 Hook 与宿主间的核心协议。0 表示成功；2 表示阻塞错误（stderr 会发送给模型进行修正）；其他值视为非阻塞错误。 * 后台执行：通过 async: true 支持后台运行，asyncRewake 模式能在后台任务失败（退出码 2）时唤醒模型继续处理。 5. 信任门控与安全设计 * 强制信任检查：在交互模式下，所有 Hook 执行前必须经过信任对话框确认，遵循纵深防御原则。 * 配置快照隔离：Hook 配置在启动时捕获快照，运行时不再重复读取磁盘，确保了会话期间行为的一致性。 * 路径安全：在 Windows 上自动进行 Git Bash 路径转换，并在执行前验证工作目录的真实存在性。 6. 高级应用案例：LangSmith 运行时追踪 本章通过 LangSmith 插件展示了 Hooks 的强大价值：该插件无需修改源码，仅通过 9 个 Hook 事件采集信号，配合事实日志（Transcript）本地状态机，就能在外部重建出一棵包含子 Agent 和工具调用的完整 Trace 树。 总结而言：展示了 Hooks 系统如何将 Claude Code 从一个封闭工具转变为一个开放的集成平台。它通过标准化的退出码协议和丰富的生命周期钩子，让开发者能够以“非侵入”的方式深度定制 AI Agent 的行为。

这一章深入解析了 Claude Code 如何应对 AI Agent 特有的安全威胁 —— 提示注入（Prompt Injection）。由于 Agent 具备读写文件和执行命令的能力，这类攻击可能导致 Agent 被劫持为攻击者的代理，从而执行任意恶意代码。 以下是该章节核心内容的总结： 1. 纵深防御体系（Defense in Depth） Claude Code 并不依赖单一技术，而是构建了一套七层纵深防御体系。其核心哲学是：没有任何一层是完美的，但七层叠加后，攻击者必须同时绕过所有层级才能成功。这七层涵盖了从字符级到行为级的全方位防护。 2. 第一道防线：Unicode 迭代清洗 针对真实的隐形字符攻击漏洞（如 HackerOne #3086545），系统实现了极其严格的清洗机制： * 三重防御：结合 NFKC 规范化、Unicode 属性类移除和显式字符范围过滤，剔除所有肉眼不可见但模型能“看到”的格式控制、私用区和隐形指令字符。 * 迭代清洗：由于规范化可能产生新的危险字符，系统会进行最多 10 轮迭代直到字符串完全稳定。 * 递归处理：系统不仅清洗 JSON 数据的值，还会清洗其键名，防止攻击者在键名中嵌入注入向量。 3. 结构与语义防御：XML 转义与来源标签 为了防止外部输入伪造系统指令，系统建立了严密的结构化防线： * XML 转义：所有进入上下文的外部字符串都会经过 escapeXml 处理，防止其包含伪造的标签（如 <system-reminder>）。 * 来源认证机制：定义了 29 个 XML 标签常量（如 bash-stdout, channel-message）。模型通过这些标签明确知晓内容来源，从而对不同来源的数据赋予不同的信任级别。例如，包裹在 <channel-message> 中的内容被视为不可信的外部推送，而非用户直接指令。 4. 模型即防线（Model as Defender） 该系统的一个独特之处在于让受保护的模型本身参与防御： * 注入检测训练：在系统提示词中明确要求模型：如果怀疑工具结果中包含注入尝试，必须主动向用户发出警告。 * 信任模型建立：通过提示词告诉模型，哪些标签是系统自动生成的，且它们与周围的工具结果无直接关联，从而识破伪造的系统提醒。 5. 架构级硬阻断与威胁面分级 系统根据操作的潜在损害范围实施威胁面分级（Threat Surface Tiering）： * 本机操作：如读写文件，由权限规则和 ML 分类器判定。 * 跨机器消息：对于跨机器发送的消息，系统实施最严格的硬阻断 —— 将 classifierApprovable 设为 false。这意味着即使 AI 分类器认为安全，也必须由人类手动确认。 6. 行为边界：CYBER_RISK_INSTRUCTION 系统通过内嵌在系统提示词中的 CYBER_RISK_INSTRUCTION 为模型设定了认知边界： * 明确允许清单：列出合法的安全研究场景（如 CTF、渗透测试教育）。 * 灰色地带处理：对双用途安全工具（如 C2 框架）要求必须具备明确的授权上下文。 * 元防御：在指令文件中加入注释，禁止模型在未经用户许可下修改自身的安全规范文件。 7. 核心工程模式提炼 * 信任边界清洗（Sanitize at Trust Boundaries）：只在外部数据进入内部系统的入口点（如 MCP 工具加载、Deep Link 解析）进行清洗，不在业务逻辑中散布清洗代码，以平衡性能与安全。 * 来源标记分级：对不同来源（代码内嵌、用户编写、Hook 输出、MCP 结果）赋予阶梯式的信任权重，其中 MCP 工具结果被视为最低信任级别，需经过完整的七层防御链。 总结而言，本章展示了 Claude Code 如何通过字符级清洗、结构化隔离、模型认知强化以及架构级硬阻断，在开放的工具生态（如 MCP）中为 AI Agent 筑起了一道坚实的防御长城。

“YOLO 分类器 —— AI 审核 AI 的安全决策系统”。这一章深入解析了 Claude Code 在 auto 权限模式下，如何通过引入第二个 AI 实例作为“安全裁判”，在无人值守的情况下平衡执行效率与系统安全。 以下是该章节核心内容的总结： 1. 核心定位：AI 审核 AI 当权限模式设为 auto 时，系统不再弹出用户确认对话框，而是发起一次独立的侧查询（Side Query），由另一个 AI 模型来裁决当前操作是否安全。 * 设计目标：让 Agent 在保持自主性的同时，能区分“正常的构建清理”与“灾难性的删库操作”。 * 物理隔离：分类器拥有独立的系统提示词、消息序列和 Token 预算，确保主循环中潜在的恶意注入不会通过 API 状态影响安全裁决。 2. 分层短路过滤机制 为了降低延迟和成本，系统设计了两层零成本过滤： * 安全白名单：所有只读操作（文件读取、搜索、LSP 查询）天然放行，不触发 API 调用。 * 字段级过滤 (toAutoClassifierInput)：工具开发者可以精确控制哪些参数需要送审，如果该方法返回空，则直接放行。 3. 二阶段 XML 分类器 系统在速度与准确性之间通过两阶段架构取得平衡： * 阶段 1：快速判定（Fast）：使用极小的 Token 预算（64 tokens）和简洁的 XML 格式（<block>yes/no</block>）。如果是明显的安全操作，亚秒级放行，主循环几乎感知不到延迟。 * 阶段 2：深度推理（Thinking）：如果阶段 1 判定为阻止或模糊，则升级到阶段 2。使用大预算（4096 tokens）并强制模型先输出 <thinking> 推理块。这种**链式思考（CoT）**能显著纠正阶段 1 的误判。 4. 防御性对话转录 分类器看到的不是原始对话，而是经过**投影（Projection）**后的压缩转录： * 屏蔽助手文本：只保留 tool_use 块，完全过滤掉助手的自由文本输出。这是关键的安全设计，防止恶意注入通过 Agent 的回复来欺骗分类器。 * 配置注入：分类器能看到用户的 CLAUDE.md，从而理解项目特定的意图（如“使用 make clean 是正常的”）。 5. 拒绝追踪（Denial Tracking）与熔断 为了防止 Agent 陷入“被拒 -> 换个说法再试 -> 又被拒”的死循环，系统引入了计数器： * 回退门槛：连续 3 次被拒或总计 20 次被拒时，系统会强制从 auto 模式回退到人工确认模式。 * 非对称重置：成功的操作会重置“连续计数”，但不会重置“总计数”，确保频繁触碰安全边界的 Agent 无法通过穿插简单操作来“洗白”信用记录。 6. 安全哲学：失败即阻止（Fail-Closed） 分类器遵循最保守的安全原则：任何不确定性都等同于阻止。 * 无论是因为 Schema 解析失败、API 超时、Token 过长还是分类器模型不可用，系统一律返回 shouldBlock: true，并将裁决权交还给人类。 在最新版本中，YOLO 分类器已从内部实验功能转变为 SDK 公开 API，标志着其准确度已达到生产级应用水平。 总结而言：本章展示了如何构建一个纵深防御的自动化安全体系。通过分层短路、二阶段验证和严格的转录投影，Claude Code 成功地将 AI 的自主权力锁在了安全栅栏之内。

详细解析了 Claude Code 如何在“允许 AI 执行任意命令”和“保护用户系统安全”之间通过分级管控实现平衡。该系统旨在防止恶意指令注入造成的破坏，同时避免频繁的确认对话框干扰用户体验。 以下是该章节的核心内容总结： 1. 六种权限模式 权限模式是系统的最高层控制开关，决定了 Agent 的自主程度： * default：所有工具调用均需用户确认，适用于高安全要求场景。 * acceptEdits：工作目录内的文件编辑自动通过，Shell 命令仍需确认。 * plan：只读模式，AI 只能读取和搜索，不执行写操作。 * bypassPermissions：跳过常规权限检查，但安全检查（如修改 .git 或 .bashrc）除外。 * dontAsk：自动化模式，将所有“询问”决策转为“拒绝”，适用于 CI/CD 环境。 * auto：AI 分类器自动裁决，仅供内部开发验证使用。 2. 权限规则与匹配机制 系统支持细粒度的规则控制，规则由操作（Allow/Deny/Ask）和目标内容（工具名及参数）组成。 * 八级来源优先级：规则可来自企业策略、项目设置（.claude/settings.json）、本地设置或会话临时规则等。 * 三种匹配模式：支持精确匹配、前缀匹配（git:*）和通配符匹配（git add *）。 3. 三阶段验证管线 当模型发起工具调用时，需经过以下决策流水线： * 阶段一：规则验证：这是最坚固的防御。工具级 deny 会立即拦截；用户显式配置的 ask 规则和对核心配置文件（如 .zshrc）的写操作具有 bypass 免疫性，必须由用户确认。 * 阶段二：模式裁决：根据当前的权限模式（如 acceptEdits）判断是否放行。 * 阶段三：模式后处理：在 auto 模式下启动 YOLO 分类器，由另一个 AI 模型对当前操作的风险进行两阶段裁决（快速判断或深度推理）。 4. 深度防御与路径安全 系统在路径验证上建立了严密的防线以抵御特定攻击： * UNC 路径防护：在 Windows 上检测并拒绝非法 UNC 路径，防止攻击者通过 Prompt 注入窃取用户的 NTLM 哈希。 * TOCTOU 防护：拒绝包含 $、%、= 等可能在验证和执行时产生语义差异的路径，防御 Shell 变量展开攻击。 * 危险删除保护：禁止删除根目录、主目录及系统关键子目录。 核心设计洞察：Claude Code 遵循纵深防御和失败关闭（Fail-closed）原则。它将分类器视为安全网而非替代品，并始终坚持“安全意图不可覆盖”——即使用户启用了最高权限的 bypass 模式，系统依然会守住核心敏感文件的最后底线。

本章立足于前两章建立的缓存架构与检测能力，从“进攻”的角度展示了 Claude Code 如何通过 7 个以上的命名优化模式，从源头消除或减少缓存中断（Cache Break），从而实现极致的成本节约。 以下是该章节的核心内容总结： 1. 七大核心缓存优化模式 这些模式遵循共同的框架：识别变化源 → 理解变化本质 → 将动态变为静态。 * 模式一：日期记忆化 (getSessionStartDate) * 问题：系统提示词包含当前日期，午夜跨天时一个字符的变化会击穿约 11,000 tokens 的缓存。 * 优化：在会话首次调用时捕获日期并进行记忆化（Memoize），此后无论实际日期如何变化，该会话内日期始终保持一致。 * 模式二：月度粒度 (getLocalMonthYear) * 优化：在工具提示词中，将时间精度从“日”降低到“月”（如 "April 2026"），将缓存失效频率从每日降低到每月。 * 模式三：Agent 列表附件化 * 问题：动态的 Agent 列表嵌入在工具描述中，其变化会导致整个工具 Schema 缓存失效，贡献了 10.2% 的全量缓存创建成本。 * 优化：将动态列表移至消息附件（Attachment）。由于附件位于消息尾部，其变化不会影响前缀缓存。 * 模式四：技能列表预算 (1% Context Window) * 优化：将技能列表体积硬性限制在上下文窗口的 1%。通过预算裁剪减少列表抖动，实现“预算即稳定”。 * 模式五：$TMPDIR 占位符 * 问题：不同用户的临时目录路径包含唯一的 UID，阻碍了跨用户的全局缓存命中。 * 优化：将绝对路径替换为 $TMPDIR 占位符，使提示词在所有用户之间逐字节一致。 * 模式六：条件段落省略 * 原则：“宁可不说，不要说了又删”。确保系统提示词前缀在会话生命周期内保持“单调稳定”，避免因功能开关翻转导致内容抖动。 * 模式七：工具 Schema 缓存 (getToolSchemaCache) * 优化：使用会话级 Map 缓存序列化后的 Schema。一旦首次渲染，后续请求直接复用，有效隔离了远程配置（GrowthBook）翻转和动态内容的影响。 2. 优化模式的四个共性原则 本章提炼了构建缓存友好型 Agent 的通用哲学： 1. 将动态内容推向请求尾部：越靠前的内容变化破坏性越大。 2. 降低变化频率：当必须出现在前缀时，用更粗的粒度（如月度）代替细粒度。 3. 消除用户维度的差异：利用占位符实现跨用户的全局缓存共享。 4. 先测量，再优化：所有模式都源自对遥测数据的归因分析。 3. 给开发者的实操建议 * 审计提示词：识别并处理其中的动态变量（日期、用户名等）。 * 锁定工具 Schema：确保工具定义在会话内保持不变。 * 监控关键指标：cache_read_input_tokens 是判断缓存是否正常的唯一指标。 * 理解前缀顺序：在构建请求时，始终将最稳定的内容放在最前面。 总结而言：强调缓存稳定性是一等公民。它展示了如何通过精细的工程设计（甚至是一个路径占位符或日期格式的改变），在复杂的分布式环境中维持字节级的匹配一致性，从而最大限度地压榨缓存的经济价值。

核心发现 通过对 PR #19823 之后的生产数据进行分析，团队发现： 当客户端快照显示所有标志位均为“未变化”，且两次请求的时间间隔在缓存 TTL（5 分钟或 1 小时）范围之内时，约 90% 的缓存中断归因于服务端原因，而非客户端代码 Bug。 以下是该章节核心内容的详细总结： 1. 核心架构：两阶段检测逻辑 由于缓存中断的触发（请求前状态变化）与确认（响应后 Token 数下降）在时间上是分离的，Claude Code 采用了两阶段检测架构： * 阶段 1：recordPromptState() (请求前)：在构建 API 请求时，捕获当前所有可能影响缓存键的客户端状态（如系统提示词哈希、工具定义、Beta Header 等），并与前次状态对比，记录变化清单（PendingChanges）,,。 * 阶段 2：checkResponseForCacheBreak() (响应后)：在收到 API 响应后，检查 cache_read_input_tokens。如果发现显著下降，则利用阶段 1 收集的信息来解释中断原因,。 2. 精密的“状态快照” (PreviousState) 系统通过 PreviousState 对象捕获了 15+ 个关键字段，确保不遗漏任何导致缓存失效的变量。 * 哈希分离设计：系统将 systemHash（提示词内容）与 cacheControlHash（缓存标记/TTL）分开计算。这样即使提示词内容没变，仅因缓存范围从 global 翻转为 org 导致的中断也能被捕获。 * 逐工具归因：当工具哈希变化时，系统会按需计算 perToolHashes。根据大数据分析，77% 的工具变化源于单个工具的描述改变（如 Agent 列表更新），这种设计能精确定位具体受影响的工具,。 * 隔离策略：使用 Map 存储不同查询源的状态，并通过 agentId 隔离并发的子代理，防止不同任务间的状态对比产生误报,。 3. 中断判定的“双重门槛” 为了过滤掉正常的 Token 波动，系统设定了严苛的中断判定标准： * 相对阈值：缓存读取 Token 数下降超过 5%。 * 绝对阈值：下降总量超过 2,000 tokens。 * 只有两个条件同时满足，系统才会触发中断告警，从而避免因基数过小或细微波动导致的误报,。 4. 强大的中断解释引擎 一旦确认中断，系统会尝试进行人类可读的归因分析： * 客户端归因：列举模型切换、系统提示词增减字符、工具集变动等具体信息。 * TTL 过期检测：如果没有客户端变化，系统会检查时间间隔。若超过 5 分钟或 1 小时，则判定为 TTL 自然过期,。 * “90% 服务端”发现：这是一个重大的工程洞察——数据分析显示，当客户端无变化且未超 TTL 时，约 90% 的中断源于服务端路由、缓存驱逐或计费不一致,。这一发现让开发团队避免了在客户端盲目排查不可控的 Bug,。 5. 调试与分析工具 * 自动化 Diff：检测到客户端中断时，系统会自动生成一个包含前后状态差异的 Diff 文件，供开发者在临时目录中查看具体的提示词变动,。 * 安全去敏：在发送 tengu_prompt_cache_break 遥测事件时，系统会自动将 MCP 工具名称安全化（统一标记为 mcp），防止泄露用户隐私信息,。 6. 工程设计洞察 * 时序决定架构：两阶段架构是处理此类异步问题的唯一正确方案，因为原始状态只存在于请求前，而确认只能在响应后。 * 可观测性先于优化：本系统本身并不优化缓存，但它是所有优化（如第15章提到的模式）的基石。没有精确的检测，就无法量化优化的效果，也无法发现新的优化机会。 总结而言：本章展示了如何构建一个数据驱动的“黑盒”监控系统。它将静默的缓存失效转化为透明的诊断报告，为后续的性能压榨和成本控制提供了科学依据。

这一章深入解析了 Claude Code 如何围绕 Anthropic API 的提示词缓存（Prompt Caching）机制，构建一套精密的防御体系，旨在通过极致的前缀稳定性来降低 API 成本（最高可节省 90%）并减少响应延迟。 以下是该章节的核心内容总结： 1. 核心挑战：逐字节匹配的严苛要求 Anthropic 的缓存机制基于前缀匹配：API 请求被视为序列化的字节流，只有当前缀与之前的请求逐字节完全一致时，缓存才能命中。这意味着任何微小的变动（如系统提示词中日期跨天、工具列表顺序变化、甚至是 Beta Header 的增减）都会导致“缓存中断”（Cache Break），迫使系统重新支付昂贵的缓存创建费用。 2. 三级缓存范围 (Cache Scopes) 系统通过 splitSysPromptPrefix() 函数将提示词划分为三个层级，以平衡共享粒度与命中率： * 全局缓存 (global)：最激进的优化。用于存放所有用户、所有会话都完全相同的静态内容（如身份介绍、通用编码规范）。通过 SYSTEM_PROMPT_DYNAMIC_BOUNDARY（动态边界标记）将其与动态内容隔开，实现跨组织的缓存共享。 * 组织缓存 (org)：用于存放组织特定但用户无关的内容。当全局缓存不可用（如配置了 MCP 工具）时，系统会回退到此级别。 * 无缓存 (null)：用于高度动态的内容（如会话特定的引导、内存文件）。这些内容不标记缓存断点，以避免增加请求复杂度。 3. 核心设计模式：锁存 (Latching) 为了应对会话中途状态变化带来的缓存中断，Claude Code 广泛采用了**“首次评估 → 锁存 → 会话稳定”**的模式： * TTL 锁存：缓存默认 TTL 为 5 分钟，合格用户（如订阅者或员工）可提升至 1 小时。系统在会话开始时锁存用户的 TTL 资格，防止中途因配额状态翻转导致缓存键变化。 * Beta Header 锁存：这是最极端的案例。AFK 模式、Fast Mode 等功能的 Beta Header 一旦在会话中发送过，就会保持 “sticky-on” 状态。即使该功能随后被关闭，Header 仍会继续发送，以保持请求签名的一致性，防止击穿 50K-70K token 的缓存前缀。 4. 缓存的“敌人”与退化路径 * MCP 工具：由于 MCP 服务器可能随时连接或断开，其定义的工具 Schema 极不稳定。当检测到活跃的 MCP 工具时，全局缓存会自动降级为组织级缓存，以确保命中率的稳定性。 * 模型切换：不同模型的系统提示词不同，切换模型会导致缓存前缀完全失效。 5. 智能清理与优化 * Thinking Clear 锁存：如果距离上次调用超过 1 小时，系统判定缓存已过期，会自动触发思维块（Thinking Blocks）的清理，以节省 token 消耗。 * 日期记忆化：系统在会话开始时捕获日期并记忆化，防止午夜跨天时日期的变更击穿 11,000 tokens 的缓存前缀。 总结而言：展示了 Claude Code 如何通过静态/动态边界分离、多级作用域划分以及强制性的锁存机制，在变幻莫测的运行时环境中，为模型构建了一个极其稳定的“数字化工作记忆”环境

在内容进入上下文窗口之前，如何通过三层防御体系精准控制其大小，以防止窗口溢出或不必要的压缩。 以下是该章节核心内容的总结： 1. 三级入口闸门体系 为了应对工具输出过大（如海量日志或并行搜索）带来的挑战，系统在三个维度实施预算控制： * 单工具结果级别（50K 字符限制）： * 当单个工具输出超过 50,000 字符时，系统会触发持久化机制：完整内容写入磁盘，模型仅接收到一个包含文件路径和前 2,000 字节预览的替代消息。 * 特殊例外：Read 工具被设定为“永不持久化”，因为它通过自身的 maxTokens 参数控制大小，且避免了“模型读取持久化文件”的死循环。 * 单消息聚合级别（200K 字符限制）： * 针对并行工具调用场景（例如同时发起 10 个 Grep），系统限制单轮对话中所有工具结果的总量不超过 200,000 字符。 * 状态冻结机制：为保护提示词缓存（Prompt Cache），系统采用“三态分区”管理（必须应用、已冻结、新增）。一旦模型看到了某个结果，该状态就会被冻结，确保后续调用中字节级一致，防止缓存失效。 * Token 计数级别： * 系统结合“API 规范计数”与“运行时粗略估算”来实时追踪上下文占用情况。 2. 精细化的 Token 估算模型 在两次 API 调用之间，系统使用字符长度除以经验系数进行估算： * 普通文本/代码：采用 4 字节/token 的保守系数。 * JSON 文件：由于包含大量单字符 token（如 {, ", :），其密度是普通代码的两倍，系数被设为 2 字节/token，以防止严重低估导致的溢出。 * 多媒体文件：图片和 PDF 文档统一按 2,000 token 固定值估算，避免将其 Base64 编码计入 JSON 序列化路径而导致的灾难性高估。 3. 处理并行调用的“计数陷阱” 并行工具调用会导致消息数组出现交错结构，多个 assistant 记录共享同一个 message.id 和 usage。 * 回溯修正（Backtracking）：tokenCountWithEstimation 函数在计算时会向前回溯到共享同一 ID 的第一个分片，确保所有交错的工具结果都被纳入统计。 * 原则：宁可高估触发提前压缩，也不要低估导致 API 报错。 4. 辅助计数与回退方案 * countTokens API：在需要极高精确度时（如评估工具定义的开销），系统会调用专用的计数端点，虽然会有额外的网络延迟。 * Haiku 回退：当专用计数 API 不可用时，系统会利用 Haiku（小模型）通过 max_tokens: 1 的请求来“白嫖”精确的输入 token 使用量，这是一种极具工程巧思的低成本替代方案。 5. 核心设计洞察 * 安全优于优化：Token 预算被视为一种安全机制。系统在所有环节都倾向于保守策略（如 JSON 密度的处理和并行回溯），因为低估的代价是 API 调用失败。 * 架构耦合：为了追求性能优化（Prompt Cache），系统被迫引入了复杂的**有状态状态机（ContentReplacementState）**来管理预算，展示了底层优化如何反向约束高层功能设计。 总结而言：第14章揭示了 Claude Code 如何通过持久化闸门、聚合预算、多系数估算和回溯修正，在 200K Token 的竞技场内建立了一套纵深防御体系，确保了系统的稳定性和成本的可预测性。

这一章深入分析了 Claude Code 如何在不调用大语言模型（LLM）生成摘要的情况下，通过轻量级的策略精准移除“过时”的上下文内容（如旧的工具执行结果），以释放宝贵的 Token 空间。 以下是该章节的核心内容总结： 1. 微压缩的核心哲学 与之前提到的全量“自动压缩”不同，微压缩遵循 “最便宜的 Token 是你从未发送的那个”。它不生成摘要，而是直接清除或删除旧的工具调用结果（如几小时前的搜索输出或日志），因为这些信息对于当前的推理任务往往已经过时。 2. 三种微压缩机制对比 源码中实现了三种互补的机制，它们在触发条件和执行方式上各有侧重： * 基于时间的微压缩（Time-based Microcompact）： * 触发场景：当用户长时间离开（如超过 60 分钟）后恢复会话时触发。 * 原理：既然服务端的提示词缓存（Prompt Cache）已经过期，系统会直接修改本地消息内容，将旧工具结果替换为占位文本，从而在重写缓存时减小体积。 * 缓存微压缩（Cached Microcompact）： * 触发场景：实时会话中，当可压缩工具数量超过阈值时触发。 * 原理：利用 Anthropic API 的 cache_edits 特性，向服务端发送删除指令。它不修改本地消息，因此能保持缓存前缀的完整性，避免产生昂贵的缓存创建费用。 * API 上下文管理（API Context Management）： * 原理：一种声明式策略。客户端描述规则（如“超过 X tokens 时保留最近 Z 个”），由 API 服务端自动执行清理工作。它还支持清理大模型产生的思考过程（Thinking Blocks）。 3. 工具清除的优先级与分类 并非所有工具结果都会被一视同仁地清除。系统定义了不同的可压缩工具集： * 高频清理类：输出量大但可丢弃的工具，如 Shell (Bash)、Grep、Glob、FileRead 和 WebSearch。 * 写入保护类：如 FileEdit 和 FileWrite，在 API 模式下会采取更激进的 exclude_tools 策略来管理。 4. 复杂的工程协调机制 微压缩并非孤立操作，它需要与系统的其他子系统紧密配合： * 缓存中断检测协调：由于微压缩故意减少了缓存内容，系统通过 notifyCacheDeletion() 通知检测器，防止其将正常的微压缩误报为“缓存中断” Bug。 * 子代理（Sub-agent）隔离：为了防止全局状态污染，缓存微压缩仅对主线程执行，子代理被完全排除在外。 * 幂等性保证：在修改消息时，系统会检查占位文本，防止对已清除的内容重复统计节省的 Token 数。 5. 版本演化 (v2.1.91) 在较新版本中，微压缩系统引入了更多人性化和防御性特性： * 冷压缩（Cold Compact）：一种非紧急的、可延迟到下一回合的压缩策略。 * 压缩确认 UI：在执行压缩前通过对话框通知用户，提升了操作透明度。 * 快速回填熔断器：如果压缩后上下文被迅速填满（如连续读大文件），系统会中断压缩循环，防止无意义的 API 开销。 6. 给开发者的设计模式启示 * 分层降级：从 API 声明式基线到精准手术般的缓存微压缩，再到缓存失效后的时间触发清理，形成了完备的退化路径。 * 单次消费语义：通过 consumePendingCacheEdits() 确保指令在 API 重试等场景下不会被重复消费。 * 不可变修改：在处理消息数组时使用展开运算符创建新数组，保护原始数据不被污染。 总结而言：本章展示了 Claude Code 如何通过时间感知、缓存感知和声明式策略的组合，在不牺牲模型“智力”的前提下，极致地榨取每一分上下文空间的价值。

探讨了在前一章提到的“自动压缩”完成后，Claude Code 如何通过附件（Attachments）机制**有选择地恢复关键上下文，以防止模型出现“失忆”现象。 以下是该章节的核心内容总结： 1. 核心哲学：恢复比压缩更重要 作者指出，“没有恢复的压缩只是多了一步数据丢失”。压缩会清空原始对话历史，如果模型不记得刚刚读过哪些文件或正在执行什么计划，就会导致模型重复操作或工作流中断。 2. 快照-清空模式 (Snapshot-Clear) 在执行压缩前，系统会先启动快照逻辑： * 先存：将内存中的 FileStateCache（文件状态缓存）序列化保存，记录模型读过的每一个文件、内容及时间戳。 * 再清：随后显式清空缓存。这样做是为了确保系统进入一个干净的状态，避免因旧缓存导致后续的文件去重逻辑出错。 3. 专项恢复通道 除了文件和技能，系统还通过特定附件恢复以下内容： * 计划与计划模式：Plan 附件恢复计划内容，PlanMode 附件确保模型继续以“计划模式”运行，防止其回退到执行模式。 * Delta 增量重播：通过传入空的消息历史，触发延迟工具、Agent 列表和 MCP 指令的完整重新宣告。 * 异步 Agent：恢复正在后台运行或已完成但未检索的 Agent 任务状态，防止重复启动相同任务。 4. 刻意的工程权衡 为了节省成本，系统故意不恢复 sentSkillNames（已发送的技能名称列表）。虽然这会节省约 4K Token 的缓存创建成本，但模型仍能通过工具定义的 Schema 感知到技能的存在，这是一个收益大于损失的工程决策。 5. 给用户的实操建议 * 刷新时间戳：由于只恢复最近的 5 个文件，在预感要压缩时，可以让模型重新读取一次核心文件以确保其在压缩后不丢失。 * 结构优化：将关键的技能指令放在文件开头，以应对 5K Token 的截断逻辑。 * 利用计划模式：对于超长任务，使用 /plan 可以确保计划跨越压缩边界被完整保留。 6. 版本演进 * v2.1.91：新增了 staleReadFileStateHint，增强了单轮对话内对陈旧文件状态的追踪能力。 * v2.1.100：引入了**工具结果去重（Tool Result Dedup）**机制，通过哈希引用替换重复的巨量输出，从源头上减少了触发压缩的频率。 总结而言，本章展示了 Claude Code 如何通过分层过滤、预算控制和多通道重播，在极致节约 Token 的同时，维持了复杂长会话的连贯性。

这一章深入解析了 Claude Code 在面对 200K Token 上下文窗口限制时，如何通过精密的阈值判定、摘要生成和失败恢复机制来管理长会话的记忆。 以下是该章节的核心内容概括： 1. 自动压缩的触发阈值（何时压缩） 自动压缩并非在窗口完全填满时触发，而是留有三层防线： * 核心公式：自动压缩阈值 = (原始窗口 - 20,000 预留) - 13,000 缓冲区。 * 触发比例：以 Claude 3.5 Sonnet (200K) 为例，实际阈值约为 167,000 tokens。这意味着当对话消耗约 83.5% 的空间时，压缩就会启动。 * 环境变量覆盖：用户可以通过 CLAUDE_CODE_AUTO_COMPACT_WINDOW 缩小窗口值或通过百分比覆盖来强制更早触发压缩。 2. 压缩提示词的 9 段式模板（如何压缩） 为了保证压缩后的摘要不丢失关键信息，系统使用了包含 9 个结构化段落的提示词模板： * 涵盖内容：包括显式请求、技术概念、代码片段（要求全量保留而非摘要）、调试历史、所有用户消息、待办任务及当前工作状态。 * <analysis> 草稿块：利用“思维链”技术，要求模型在生成正式摘要前先按时间顺序进行分析，该草稿块在完成后会被剥离以节省 token。 * 严禁工具调用：提示词首尾都有强硬指令禁止模型在压缩过程中调用工具，以防止因模型尝试工具调用而导致输出为空（该错误率在 Sonnet 4.6 上曾达 2.79%）。 3. 熔断器机制（失败保护） 为了防止系统陷入“压缩失败 → 下一轮继续压缩”的死循环（源码记录曾有会话因此连续失败 3,272 次，造成巨大资源浪费），系统设计了 10 行代码的熔断器： * 如果连续 3 次 自动压缩失败，系统会停止尝试。 * 哲学原则：宁可让用户手动执行 /compact，也不要用注定失败的重试浪费 API 预算。 4. 极致的 PTL（Prompt Too Long）重试 当对话过长导致“压缩请求本身”都超过 API 限制时，系统会启动 truncateHeadForPTLRetry 机制： 1. 按轮次分组：确保不会拆散工具调用与其结果。 2. 头部截断：精确丢弃最旧的内容（通常是 20% 的消息组）以腾出空间。 3. 修复序列：确保截断后的消息仍以 user 角色开头（通过插入 PTL_RETRY_MARKER）。 5. 压缩后的状态恢复 * 先忘后记：压缩完成后会清空旧的文件状态缓存，但会立即触发 createPostCompactFileAttachments，重新读取最重要的 5 个文件（约 50,000 tokens）注入上下文。这确保了模型虽然丢失了对话细节，但依然拥有最新的生产文件上下文。 6. v2.1.100 的版本演进 * 冷压缩 (Cold Compact)：引入了 Feature Flag 驱动的延迟压缩策略，允许在更合适的断点执行压缩。 * 快速回填熔断器：如果压缩后 3 回合内上下文又迅速填满，系统会触发熔断以防止“压缩-回填”的系统震荡。 * 主动权下放：新增了用户可手动触发的 /compact 命令和确认对话框。 总结原则：自动压缩的设计体现了 “多层缓冲、渐进降级、可观测性与用户可控” 的工程哲学，旨在实现一种“用户永远察觉不到”的无缝上下文管理体验。

如果说系统提示词是“顶层战略”，那么注入到每一个工具 description 字段中的提示词就是微型驾驭器 (micro-harness)，它们在微观层面直接塑造模型对特定工具的使用行为,。 以下是该章节的核心内容总结： 1. 工具提示词的本质：行为约束协议 在 Claude Code 中，工具的描述字段不仅是功能说明，而是一套完整的行为约束协议，包含功能描述、正面引导、负面禁令（NEVER）、条件分支和格式模板。这种设计与系统提示词共同构成了**“双层驾驭架构”**：系统提示词设定全局人格，工具提示词塑造局部行为。 2. 六大核心工具的微型驾驭策略 * BashTool (最复杂的驾驭器)： * 流量导向：建立“工具偏好矩阵”，明确禁止用 Bash 执行文件编辑或搜索，强制导流至专用工具以保证权限受控。 * Git 六层防线：严禁 push --force、修改 git config 或未经许可的 commit，防御数据丢失场景。 * 策略透明化：将沙箱配置以 JSON 格式内联，让模型“理解”自己的路径和网络权限，从而自检合规性,。 * 反模式抑制：明确禁止使用 sleep 进行轮询，并提供后台执行等替代方案。 * FileEditTool (接口契约)： * 前置读取强制：在提示词和运行时双重强制“编辑前必须先读取”，防止模型因“幻觉”导致错误的编辑操作,。 * Token 经济学：引导模型使用 2-4 行的“最小唯一 old_string”，在确保匹配准确性的同时节省 Token。 * FileReadTool (资源感知)： * 渐进式限制：设定 2000 行默认限制；对 PDF 采取分页读取策略，且仅在运行时支持 PDF 解析时才声明该能力，确保“能力与运行时对齐”,。 * GrepTool (安全默认值)： * 排他性声明：强调搜索必须使用 GrepTool 而非 Bash grep，因为前者经过了权限和忽略模式的优化。 * 逃生舱口：默认限制 250 条输出（上下文保护），但保留 head_limit=0 作为无限制的逃生舱口,。 * AgentTool (缓存保护与委派质量)： * 动态内容外移：为保护提示词缓存，将频繁变化的 Agent 列表移至附件消息，使工具描述保持静态,。 * 元认知约束：提出“Never delegate understanding”（永不委派理解），防止模型将核心思考工作甩给子代理。 * SkillTool (预算管理)： * 1% 预算约束：将技能列表体积硬性限制在上下文窗口的 1%，防止其侵蚀工作空间,。 * 三级截断策略：按照“内置技能 > 非内置描述 > 仅保留名称”的优先级动态裁剪，确保在任何规模下都成本受控。 3. 设计工具提示词的通用原则 本章总结了七条核心原则，帮助开发者构建生产级 Agent： 1. 双向闭环：在工具 A 中禁做 X 并导向 B，在 B 中声明做 X 必须用我。 2. 理由先于禁令：每一条 “NEVER” 禁令后都应跟随一个 “because” 解释。 3. 能力与运行时对齐：仅在环境支持时声明某项功能。 4. 安全默认值 + 逃生舱口：保守的默认输出限制配合显式的解除方式。 5. 预算意识：通过归一化和截断策略控制工具描述本身的 Token 成本。 6. 前置条件声明：在提示词中声明依赖（如先读后写），并在运行时强制执行。 7. 委派质量标准：约束向子系统传递任务时的描述完整性和具体性。 本章小结：优秀的工具提示词不是简单的功能文档，而是行为契约。它通过精准的约束和引导，确保模型在安全、高效、成本可控的轨道上运行。