这一章深入分析了 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 的自主性。 状态转换防抖：通过单次消费标志处理快速切换模式产生的冲突。 总结： 展示了如何通过物理约束（权限）、持久化媒介（文件）和精细的状态转换逻辑，构建一个既高效又安全的人机对齐机制。

第4章的主题是 “工具执行编排 —— 权限、并发、流式与中断”。这一章深入解析了 Claude Code 如何在保证安全和一致性的前提下，高效地执行模型请求的多个工具调用。展示了 Claude Code 如何通过分区调度、纵深防御的权限链以及确定性的结果管理，在追求极致并发性能的同时，构建起一套不容突破的安全红线 1. 核心任务：解决三个关键问题 工具编排层（Tool Orchestration）主要负责处理以下三个核心挑战： * 安全并发：区分只读工具（可并行）与写入工具（须串行），防止竞态条件。 * 权限门控：确保危险操作在执行前经过权限决策链的审查。 * 结果管理：对海量输出进行智能裁剪和持久化，防止挤爆上下文窗口。 2. 工具调用分区 (partitionToolCalls) 当模型一次性发出多个工具请求时，编排层首先进行“贪心合并”分区： * 并发安全批次：连续的只读工具（如 FileRead, Grep）被合并，最大化吞吐量。 * 串行批次：修改状态的工具（如 FileWrite, Bash 中的写入命令）独占一批，确保顺序执行。 * 失败即关闭 (Fail-closed)：如果模型输入无效或并发安全判定出错，系统默认回退到最安全的串行模式。 3. 单工具执行的九阶段生命周期 每个工具调用都会经历一套严密的执行流水线： * 阶段 1-2：工具查找、Schema 验证及推测性分类器启动（提前开始 Bash 权限检查以减少延迟）。 * 阶段 3-4：执行 PreToolUse Hooks 并进入权限决策链。遵循纵深防御原则：Hook 的“允许”决策不能绕过用户在配置文件中显式设定的“拒绝”规则。 * 阶段 5-6：工具执行并产出进度事件，随后进行结果映射。 * 阶段 7-9：大结果持久化、执行 PostToolUse Hooks 以及必要时的中断判定（Stop Hooks）。 4. 流式并发执行器 (StreamingToolExecutor) 为了实现极致的流式体验，系统支持“工具到达即执行”，无需等待 API 响应结束： * 状态机驱动：为每个工具维护 queued 到 yielded 的状态转换。 * 选择性级联中断：这是一个精妙的设计——当一个 Bash 命令失败时，系统会取消所有同级并行的 Bash 工具（因为它们通常存在逻辑依赖），但不会影响独立的只读工具（如 Read）。 5. 结果管理与缓存优化 * 两级预算控制：单工具结果上限为 50,000 字符，单回合聚合预算为 200,000 字符。超出部分将被持久化到磁盘，模型仅看到带路径的摘要。 * 提示缓存稳定性：通过 ContentReplacementState 确保一旦结果被持久化，后续迭代中该结果的摘要内容保持绝对一致，防止“缓存抖动”导致 API 成本激增。 * 空结果占位：为防止模型将空输出误判为回合结束，系统会自动注入占位文本（如 (Bash completed with no output)）。 6. 版本演化与新趋势 * AdvisorTool：引入了第一个“非执行类”工具，它不改变环境而是提供建议，标志着 Agent 从“只做事”向“先对齐意图再做事”演进。 * 工具结果去重：新增第三道上下文防线（前两道为输入去重和压缩），通过对输出端去重进一步维护上下文卫生。

Claude Code 的 Agent Loop (queryLoop()) 被定义为一个自修改状态机（Self-modifying State Machine）。它的拓扑结构并非简单的线性循环，而是一个包含多级预处理管线、错误恢复路径和复杂终止判定的闭环系统. 下面的流程图展示了状态机的完整拓扑： 这一拓扑的设计哲学是“扣留-释放” (Withhold-Release) 模式——可恢复的错误被内部消化（扣留），只有当所有预设的恢复路径都失败时，才会向用户释放错误并终止循环

第2章展示了 Claude Code 的工具系统不仅仅是一个 API 列表，而是一个集成了安全防御（失败关闭）、性能优化（死代码消除）、上下文管控（两级预算）和极致 UX（渐进渲染）的工程化闭环。

第1章主要介绍了 AI 编码 Agent（以 Claude Code v2.1.88 为例）的完整技术栈与架构设计。其核心思想是 AI Agent 不仅仅是传统的 CLI 工具，而是一个“在分发状态下（on distribution）运行”的系统，模型在其中扮演着一等公民的角色