双人漫谈：ClaudeCode

“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章提到的模式）的基石。没有精确的检测，就无法量化优化的效果，也无法发现新的优化机会。 总结而言：本章展示了如何构建一个数据驱动的“黑盒”监控系统。它将静默的缓存失效转化为透明的诊断报告，为后续的性能压榨和成本控制提供了科学依据。