AI 原生开放教材

外观

驾驭工程：从 Claude Code 源码到 AI 编码最佳实践工程手册·中文原文 ↗原件 ↓仓库 ↗

书籍影响分析: v2.1.88 → v2.1.91 ​

生成时间: 2026-04-03

基于 v2.1.88 完整源码 + v2.1.91 bundle 字符串信号 + sdk-tools.d.ts 精确对比

概览 ​

指标v2.1.88v2.1.91
cli.js12.4MB12.5MB (+115KB)
Source Map有已移除
Tengu 事件827860 (+39 / -6)
环境变量178183 (+8 / -3)
GrowthBook 配置1718 (+1)
sdk-tools.d.ts基线+1 字段, +1 mode 值

需要更新的章节 ​

章节影响级别变化摘要建议操作
ch16-18 权限系统高sdk-tools.d.ts 新增 "auto" 权限模式将 auto mode 作为正式权限策略文档化；补充 TRANSCRIPT_CLASSIFIER 分类器自动审批机制
ch16 Bash 安全高移除 tree-sitter WASM AST 解析器（3 个事件 + 1 个环境变量移除）更新 bash 安全管道描述：从 AST 分析退回到 JS regex/shell-quote 方案；记录 CC-643 性能问题（REPL freeze）作为决策原因
ch11 自动压缩高新增 cold_compact + rapid_refill_breaker + autocompact_command + autocompact_dialog_opened新增"冷压缩"策略说明（区别于热压缩）；补充压缩对话框 UX（用户确认机制）；记录快速回填熔断器
ch09-10 上下文管理中sdk-tools.d.ts 新增 staleReadFileStateHint 字段补充文件状态跟踪：工具执行期间 mtime 变化检测 → 模型收到陈旧读取提示
ch20 计划模式中新增 ultraplan_* 5 个事件（config/keyword/prompt_identifier/stopped/timeout_seconds）补充 Ultraplan 远程多代理规划模式：Opus 4.6 模型、30 分钟超时、CCR 远程会话、关键字触发
ch21 多代理中新增 forked_agent_default_turns_exceeded + subagent_lean_schema_applied + subagent_md_report_blocked + mcp_subagent_prompt补充代理回合限制、精简 schema 模式、子代理 CLAUDE.md 报告阻断机制
ch04 工具系统中sdk-tools.d.ts 工具结果元数据扩展更新工具输出结构文档，增加 hint 字段说明
ch19 钩子系统低新增 hook_output_persisted + pre_tool_hook_deferred补充钩子输出持久化和前置钩子延迟执行
ch12 记忆系统低新增 memory_toggled + extract_memories_skipped_no_prose补充记忆开关事件和无散文跳过逻辑
ch06 API/流式低新增 rate_limit_lever_hint补充限速杠杆提示信号
ch22 IDE/桥接低新增 bridge_client_presence_enabled补充客户端存在检测
附录 B 环境变量低+8 新增 / -3 移除更新环境变量索引表

高影响变化详细分析 ​

1. Tree-Sitter 安全基础设施移除 ​

移除的信号：

  • tengu_tree_sitter_load — WASM 模块加载事件
  • tengu_tree_sitter_security_divergence — AST vs regex 解析分歧检测
  • tengu_tree_sitter_shadow — 影子模式测试
  • tengu_bash_security_check_triggered — 23 种安全检查类型
  • CLAUDE_CODE_DISABLE_COMMAND_INJECTION_CHECK — 注入检查禁用开关

v2.1.88 源码证据：

  • restored-src/src/utils/bash/treeSitterAnalysis.ts（507 行）— AST 级 bash 安全分析
  • restored-src/src/utils/bash/parser.ts（136 行）— WASM 模块加载
  • restored-src/src/tools/BashTool/bashPermissions.ts:1700-1738 — 影子模式测试逻辑
  • restored-src/src/tools/BashTool/bashSecurity.ts:76-101 — 23 种检查类型 ID

移除原因推断（基于源码注释 CC-643）：

复杂复合命令触发 splitCommand 产生指数级子命令数组，每个子命令执行 tree-sitter 解析 + 约 20 个验证器 + logEvent，导致微任务链饿死事件循环 — REPL 100% CPU 冻结。

对书的影响：ch16 需要将 bash 安全分析从"AST 级分析"修改为"regex/shell-quote 方案"，并记录 tree-sitter 被移除的工程权衡。

2. 冷压缩（Cold Compact） ​

新增信号：

  • tengu_cold_compact — 冷压缩触发
  • tengu_auto_compact_rapid_refill_breaker — 快速回填熔断器
  • tengu_autocompact_command — 用户手动触发的 /compact
  • tengu_autocompact_dialog_opened — 压缩确认对话框

v2.1.88 架构参考：

  • restored-src/src/services/compact/autoCompact.ts:72-91 — 阈值计算
    • AUTOCOMPACT_BUFFER_TOKENS = 13,000
    • MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3
  • restored-src/src/services/compact/compact.ts:650 — 核心压缩事件

推断：

  • v2.1.88 只有"热压缩"（紧急、上下文将满时自动触发）
  • v2.1.91 新增"冷压缩"（延迟、上下文接近满但未到阻塞点时触发）
  • 新增对话框 UI 提升透明度：用户可看到压缩即将发生
  • 快速回填熔断器解决：压缩后上下文迅速回满导致循环压缩的边缘情况

3. Auto 权限模式正式化 ​

sdk-tools.d.ts 变化：

diff
- mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";
+ mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";

v2.1.88 源码证据：

  • restored-src/src/migrations/resetAutoModeOptInForDefaultOffer.ts — 迁移逻辑
  • restored-src/src/tools/shared/spawnMultiAgent.ts:227-230 — 子代理继承 auto 模式
  • restored-src/src/tools/BashTool/bashPermissions.ts:1467 — 分类器行为

含义：auto 模式在 v2.1.88 中已存在于内部代码但未公开到 SDK 接口。v2.1.91 将其正式化为公开 API 的一部分，允许 SDK 用户使用 ML 分类器自动审批安全工具调用。

4. Ultraplan 远程多代理规划 ​

新增信号（v2.1.91 新增 5 个，v2.1.88 源码中已有 6 个）：

  • 新：tengu_ultraplan_config/keyword/prompt_identifier/stopped/timeout_seconds
  • 已有：tengu_ultraplan_launched/approved/failed/awaiting_input/create_failed

v2.1.88 源码证据：

  • restored-src/src/commands/ultraplan.tsx（470 行）— 主编排
  • restored-src/src/utils/ultraplan/ccrSession.ts — 轮询状态机
  • restored-src/src/utils/ultraplan/keyword.ts — 关键字触发检测

架构特征：

  • 运行在 CCR（Claude Code on the web）远程会话中
  • 使用 Opus 4.6 模型（无论用户当前配置什么模型）
  • 30 分钟超时（ULTRAPLAN_TIMEOUT_MS = 30 * 60 * 1000）
  • 轮询间隔 3 秒（POLL_INTERVAL_MS = 3000）
  • 最大连续失败 5 次后硬停止
  • 用户终端在规划期间保持可用

可能需要新章节/新节的功能 ​

功能事件数建议处理
Powerup Lessons（学习教程系统）2 个新事件v2.1.88 源码中不存在，是全新 UX 功能。建议放入 ch25-29 经验教训篇或附录，非核心架构变化
Ultraplan 远程规划11 个事件（6 旧 + 5 新）v2.1.88 源码中已有完整实现。建议在 ch20（计划模式）中新增专门小节
Plugin/Marketplace 系统新增 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE已有 plugin 事件体系。可在 ch23（技能系统）中补充

无需更新的章节 ​

以下章节的核心架构在 v2.1.91 中无对应信号变化：

  • ch01-03（架构基础、启动流程、Agent Loop 主循环）
  • ch05（认证流程核心）
  • ch07-08（提示工程、系统提示词构造）
  • ch13-15（提示词缓存核心机制）
  • ch24（后台任务/Kairos — 无新信号）

实验代码名事件（影响级别：低） ​

以下是带随机代码名的新事件，属于 A/B 测试：

事件推测用途
tengu_garnet_plover未知实验
tengu_gleaming_fair未知实验
tengu_gypsum_kite未知实验
tengu_slate_finch未知实验
tengu_slate_reef未知实验
tengu_willow_prism未知实验
tengu_maple_forge_w未知实验
tengu_lean_sub_pf可能与子代理精简 schema 相关
tengu_sub_nomdrep_q可能与子代理行为相关
tengu_noreread_q可能与文件重读跳过相关

由 version-track 工作流生成