“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. 委派质量标准：约束向子系统传递任务时的描述完整性和具体性。 本章小结：优秀的工具提示词不是简单的功能文档，而是行为契约。它通过精准的约束和引导，确保模型在安全、高效、成本可控的轨道上运行。

本章深入解析了 Claude Code 如何针对不同世代的模型（如内部代号为 Capybara v8 的 Claude 4.5/4.6 系列）进行精细的行为校准，以及如何通过一套复杂的门控和实验系统管理内部验证与全球发布。 以下是该章节核心内容的总结： 1. @[MODEL LAUNCH] 分布式检查清单 为了应对模型升级时需要更新多处代码（如模型 ID、知识截止日期、行为指令等）的挑战，Claude Code 引入了 @[MODEL LAUNCH] 注解系统。 * 工程意义：它将发布流程的知识嵌入代码本身，构成一个分布式检查清单。工程师只需全局搜索该注解，即可找到所有需要更新、评估或解除门控的位置。 2. 针对特定模型的“个性缺陷”缓解 每个模型世代都有独特的行为倾向，源码记录了针对 Capybara v8 的四种行为缓解指令： * 过度注释（Over-commenting）：建立精细的评论哲学，只在“为什么”不明显时添加注释，避免解释显而易见的代码。 * 虚假声明（False Claims）：针对该模型较高的虚假声明率（29-30%），要求模型提供准确报告而非防御性报告，既不虚报成功也不过度自我怀疑。 * 主动性不足：纠正模型倾向于盲从指令而不提出判断的问题，将其定位为“协作者”而非单纯的“执行者”。 * 彻底性不足：要求模型在无法验证结果时显式承认，而非假装任务已完成。 3. USER_TYPE === 'ant' 编译时门控 这是系统实现内部 A/B 测试和安全保护的核心机制。 * 死代码消除（DCE）：通过打包工具在编译时将 process.env.USER_TYPE 替换为常量，外部构建中物理上不存在任何内部代码（如内部代号或未公开的缓解措施）。 * 渐进式管道：新功能先在内部（ant）用户中验证，收集数据后再通过 A/B 测试推广至外部。 4. Undercover 模式：公开仓库的隐身术 为了防止 Anthropic 内部工程师在向开源仓库贡献代码时泄露内部信息，系统设计了 Undercover 模式。 * 多层压制：自动检测远程仓库地址，一旦非内部仓库，立即压制系统提示词中的模型 ID、名称以及可能暴露身份的 commit message 示例。 * 安全哲学：采取**“安全默认开启且无法强制关闭”**的设计，宁可在内部仓库误报，也不冒泄露风险。 5. GrowthBook 与 tengu_* Feature Flag 体系 Claude Code 使用 GrowthBook 作为其远程控制平面。 * 缓存感知读取：为了不阻塞启动 UI，特性值优先从磁盘或内存缓存读取（_CACHED_MAY_BE_STALE），实现性能与功能的平衡。 * 模型热切换：通过 tengu_ant_model_override Flag，工程师可以在不发布新版本的情况下，远程配置内部模型列表、调整默认模型或追加系统提示词后缀。 6. 工程启示：从软件到平台 本章提炼了几个关键的 AI Agent 构建原则： * 编译时安全优于运行时检查：物理消除内部代码比逻辑隐藏更安全。 * 默认安全哲学：在安全与便利冲突时，始终选择安全（如 Undercover 模式的设计）。 * 控制平面与数据平面分离：通过 Feature Flag 体系将 Agent 转变为一个可远程调控、可快速实验的平台。 总结而言：第7章展示了如何通过分布式注解、编译时死代码消除、自动化隐私保护和远程实验平台，构建一个能够安全、快速迭代且对不同模型能力具有高度适应性的生产级 AI Agent。

这一章深入解析了 Claude Code 如何在不稳定的网络和 API 过载环境下，通过一套精密、具备韧性的通信子系统来保证 Agent 的可靠性。 以下是该章节的核心内容总结： 1. 核心哲学：通信失败是常态 该系统将 API 通信层视为 Agent 的控制平面（Control Plane），而非简单的 SDK 封装。其核心理念是：通信失败是常态而非异常，系统必须在每一层都有预案。所有的降级、重试和缓存保护策略都在这一层完成决策。 2. 多级重试策略与模型降级 系统通过 withRetry.ts 实现了一套高度可调优的重试机制： * 指数退避与随机抖动：默认提供 10 次重试预算，采用 500ms 基数的指数退避，并叠加 0-25% 的随机抖动（Jitter）以避免“雷群效应”。 * 差异化重试决策：shouldRetry() 函数会根据错误类型做决策。例如，对于按量计费用户的 429（限流）会重试，但对于 ClaudeAI 订阅用户的 429 则不重试，因为后者的限制窗口通常长达数小时，重试无意义。 * 529 过载特殊处理：这是系统级的减载（Load Shedding）策略。连续 3 次 529 错误会触发模型降级（例如从 Opus 降级到 Sonnet），且只有前台请求才会重试 529，后台任务会立即放弃以减轻后端压力。 3. 流式通信的双重“看门狗” 为了应对流式连接静默挂起的问题，系统设计了两层检测机制： * Idle Timeout 看门狗（中断型）：如果 90 秒完全没有收到任何流式事件，判定流已死，强制中断并触发非流式回退。 * Stall 检测（日志型）：如果两个事件之间的间隔超过 30 秒，系统会记录遥测事件但不会中断连接。这种机制主要用于识别“服务端响应慢”而非“连接已死”。 * 非流式回退：当流式失败时，系统会尝试回退到非流式模式，并确保重试计数在切换过程中不会重置。 4. Fast Mode 与缓存感知重试 在加速模式（Fast Mode）下，重试决策会优先考虑 Prompt Cache（提示词缓存） 的保护： * 20 秒阈值：如果 Retry-After 头部指示等待时间 小于 20 秒，系统会原地等待以保留缓存；如果大于等于 20 秒，则认为缓存可能已失效，转而切换到标准模式并进入冷却期。 5. 持久重试模式与“心跳保活” 针对 CI/CD 等无人值守场景，系统提供了持久重试模式： * 无限重试：对 429/529 错误进行无限重试，退避时间最高可增长至 5 分钟。 * 心跳机制：为了防止远程容器因长时间无输出而被回收，系统将长达 5 分钟的等待切片为多个 30 秒片段，每个片段后通过 yield 产生一条心跳消息，从而保持流活跃并允许用户随时中断等待。 6. 三事件遥测模型 系统的可观测性基于三个核心事件构建：tengu_api_query（请求发出）、tengu_api_success（成功响应）和 tengu_api_error（失败响应）。 * 精细化诊断：错误分类多达 25 种，能够精确区分是 SSL 证书问题、模型访问受限还是 API 密钥无效。 * 网关指纹检测：系统能识别请求是否经过了 LiteLLM、Cloudflare 等第三方 AI 网关，以便诊断特定代理环境下的错误模式。 7. 模式提炼 * 有限重试预算 + 独立降级阈值：全局 10 次，529 错误 3 次。 * 双重看门狗：区分“死连接”与“慢连接”。 * 缓存感知的重试：在等待时间与缓存重建成本之间寻找平衡。 * 心跳保活：将同步等待转为异步协作，解决容器回收与中断响应问题。 总结而言， Claude Code 如何将 API 调用从一个简单的网络请求升华为一个高度可观测、具备自愈能力且成本感知的工业级控制系统。

第7章的主题是 “通过提示词引导行为”。如果说前两章是 Claude Code 的“骨骼”，那么本章探讨的精心措辞的行为指令就是附着在骨骼上的“肌肉”，它们让模型表现得像一个经验丰富的工程师。 以下是该章节提炼出的 6 种核心行为引导模式及其底层设计原则： 1. 六大行为引导模式 * 极简主义指令 (Minimalism Directive)：核心：通过禁止过度工程，将模型的“乐于助人”倾向限制在任务实际需要的范围内。 金句：“三行相似的代码优于过早的抽象”。这种具体数量锚定（数字“3”）打破了模型默认的 DRY（不重复自己）启发式倾向。 * 渐进式升级 (Progressive Escalation)：核心：在“直接放弃”和“无限死循环”之间定义中间路径，引导模型遵循 “诊断 → 调整 → 最后求助” 的三阶段协议。 约束：同时禁止盲目重试和过早放弃，迫使模型在失败后进行有信息量的推理。 * 可逆性意识 (Reversibility Awareness)：核心：引入 “可逆性” 和 “影响范围” 两个维度构建 2x2 决策矩阵，教会模型“三思而后行”。 实践：使用 “NEVER + 除非明确要求” 的强力约束（如禁止 amend 已发布的 commit），并附带因果解释以促进模型在未知场景中的泛化。 * 工具偏好引导 (Tool Preference Steering)：核心：通过工具描述中的 “前置拦截”，将模型的默认工具选择从通用 Bash 命令（如 grep, find）重定向到专用工具（如 Grep, Glob）。 技巧：采用 “Use X (NOT Y)” 的二选一对照格式，并在系统提示词和工具描述中进行冗余强化。 * Agent 委托指引 (Agent Delegation Protocol)：核心：为多 Agent 协作定义精准规则，防止递归派生和上下文污染。 拟人化禁令：使用 “Don't peek（不要偷看子 Agent 的中间输出）” 和 “Don't race（不要在结果返回前捏造结果）” 等词汇，将技术约束转化为社交直觉。 * 数值锚定 (Numeric Anchoring)：核心：用精确数字（如“≤25 词”）替代模糊的定性描述（如“简洁一些”）。 量化收益：实验证明，仅将“保持简洁”替换为“≤25 词”，就实现了 1.2% 的输出 Token 削减。 2. 跨模式的底层设计原则 本章归纳了 5 条通用的提示工程设计准则： 1. 反面定义优于正面描述：“不要做 X”的边界比“做 Y”更清晰。 2. 具体例子是抽象规则的校准器：通过具体的反面案例（如 bug 修复不需要清理周围代码）来校准模型的执行力度。 3. 因果解释促进泛化：解释规则背后的“为什么”（如为何不能 amend），能让模型在未见过的场景中推导出正确行为。 4. 冗余是刻意的：在不同位置（如系统提示词和工具描述）重复关键约束，以对抗模型的注意力衰减。 5. 灰度部署提示词：如 ant-only 实验所示，提示词的修改也需要 A/B 测试和数据验证。 3. 实操建议 对于开发者，本章建议在构建自己的 Agent 时： * 用数字替代形容词（如“1-2 句”）。 * 为失败场景建立明确的升级路径。 * 利用“可逆性”维度构建安全防御框架。 总结而言，第7章展示了提示工程如何从“文学创作”转向**“精确控制”**。通过在生成概率空间中设置明确的“围栏”，Claude Code 成功地将一个通用的 AI 模型驯化成了一个克制、高效且具备风险意识的专业编码助手。

本章深入解析了 Claude Code 如何通过一套分段式组合架构（Sectioned Composition Architecture），在维持海量指令集的同时，实现极致的成本优化和缓存效率 1. 核心挑战：成本与灵活性的权衡 Claude Code 的系统提示词包含身份、规范、工具指南、环境信息等十余个段落，总量达数万 token。其架构设计必须解决三大工程挑战： * 体积与成本：避免每次 API 调用都重传数万 token 导致的缓存成本。 * 变化频率不一：身份介绍是静态的，而环境信息和 MCP 指令是动态的。 * 多来源覆盖：需要处理用户自定义、Agent 模式、循环模式等多种提示词来源的优先级。 2.：分段记忆化 (Sectioned Memoization) 系统提示词被拆分为独立的段落（Section），通过 systemPromptSections.ts 进行生命周期管理： * 记忆化段落 (systemPromptSection)：计算结果会被缓存到全局状态中，后续轮次直接复用，仅在 /clear 或 /compact 时重置,。 * 易变段落 (DANGEROUS_uncachedSystemPromptSection)：标记为“危险”，因为它们每轮都会重新计算并破坏缓存。这种设计通过 API 摩擦（要求必填 reason 参数）强制开发者权衡内容新鲜度与缓存效率,。 3. 静态与动态边界：缓存分治策略 系统提示词中存在一条显式的 SYSTEM_PROMPT_DYNAMIC_BOUNDARY（动态边界）： * 静态区（边界前）：包含在所有用户、所有会话中完全相同的内容。系统利用 scope: 'global' 实现跨组织缓存共享，极大降低了 Anthropic API 后端的计算压力。 * 动态区（边界后）：包含所有依赖运行时状态的内容（如工具引导、内存文件、环境信息）。 * 设计约束：静态区严禁包含任何因会话而异的条件分支，否则会导致全局缓存哈希变体呈指数级增长（2^N），使命中率归零,。 4. splitSysPromptPrefix 的三条缓存路径 系统会根据运行时条件选择最优的 API 请求块构建路径： * 路径 1：MCP 降级路径。当存在活跃的 MCP 工具时，由于工具 Schema 是用户级的，系统会自动降级到组织级（org）缓存。 * 路径 2：全局缓存+边界路径。这是最优路径，将提示词拆分为不可缓存的归因头、全局缓存的静态块以及不缓存的动态块。 * 路径 3：默认组织缓存路径。用于第三方提供者或未定义边界的情况。 5. 优先级合成链 (Priority Chain) buildEffectiveSystemPrompt 负责按严格的优先级合成最终发送给模型的指令集： * 优先级顺序：Override (覆盖) > Coordinator (协调器) > Agent (代理) > Custom (自定义参数) > Default (默认值)，最后再加上可选的 Append (追加) 段落,。 * 这种设计确保了在不同运行模式下，系统行为是可预测且线性可读的。 本章提炼了三项可复用的工程模式,： 1. 分段记忆化：通过工厂函数区分静态与易变内容。 2. 缓存边界分治：将会话变量赶到边界之后，保护全局缓存前缀。 3. 优先级链合成：使用清晰的三元链处理多来源提示词冲突。 总结而言：系统提示词架构的价值不在于功能实现，而在于成本效率。它通过精密的缓存层级设计，在每天数百万次 API 调用中节省了大量的处理开销，是生产级 AI Agent 的关键基础设施。

本章主题是 “计划模式（Plan Mode） — 从‘先做后看’到‘先看后做’”。本章深入分析了 Claude Code 如何通过一套完整的**“先规划、后执行”状态机**，解决 AI Agent 最大的风险——“写对了错误的东西”。 以下是该章节的核心内容总结： 1. 核心定位：意图对齐（Intent Alignment） Plan Mode 的核心价值在于意图对齐：在 Agent 动手修改代码前，先让其探索代码库、制定计划并获得用户审批。这不仅是简单的提问，而是一套涉及权限切换、计划持久化和工作流管理的复杂系统。 2. 三个关键设计决策 权限作为行为约束：进入计划模式后，工具集被限制为只读。这并非仅靠提示词，而是通过权限系统在工具调用前进行拦截。 计划文件作为对齐载体：计划被写入磁盘（Markdown 文件），而非仅停留在对话中。这使得计划在上下文压缩后不会丢失，且支持用户在外部编辑器中直接修改。 状态机而非布尔开关：它包含进入、探索、审批、退出、恢复的完整转换链，并具备保存/恢复权限模式的能力。 3. 5阶段工作流与提示词注入 系统通过“附件消息”向模型注入行动指南，并采用 Full/Sparse 节流模式 优化 Token 成本： Full 附件：包含完整的 5 阶段工作流指令（约 2000+ 字符），每 N 轮人类消息注入一次。 Sparse 附件：在非注入轮次仅提供一行提醒，节省空间。 不同工作流：外部用户通常使用标准的 5 阶段模式（先探索完再提交），而内部用户（Anthropic 员工）则使用 Interview 模式（边探索边提问，迭代完善）。 4. 计划文件的工程细节 命名机制：使用人类可读的词组 Slug（如 brave-fox.md）而非 UUID，并存放在全局目录中以防污染项目仓库。 路径防御：具备路径穿越防御，防止配置路径逃逸到项目根目录之外。 子 Agent 隔离：每个子 Agent 拥有独立的计划文件，避免相互覆盖。 5. 审批与安全防护 权限模式恢复：退出 Plan Mode 时会恢复进入前的权限（如 Auto 或 Default）。如果 Plan 期间触发了熔断器（如连续拒绝次数超限），系统会降级到安全默认值而非恢复 Auto 模式。 内外有别的行为校准：系统对内部和外部用户有不同的触发阈值。外部版本更倾向于“如果不确定就先计划”，而内部版则鼓励直接执行并针对性提问。 6. 核心设计模式提炼 本章总结了 5 种可复用的模式： 保存/恢复权限模式：确保受限操作结束后能精确回归原态。 计划文件作为载体：提升计划的持久性与外部协作性。 Full/Sparse 节流：在指令引导与 Token 成本之间取得平衡。 内外差异的行为校准：根据用户成熟度调整 Agent 的自主性。 状态转换防抖：通过单次消费标志处理快速切换模式产生的冲突。 总结： 展示了如何通过物理约束（权限）、持久化媒介（文件）和精细的状态转换逻辑，构建一个既高效又安全的人机对齐机制。