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

生成时间: 2026-04-03

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

---

## 概览

| 指标 | v2.1.88 | v2.1.91 |
|------|---------|---------|
| cli.js | 12.4MB | 12.5MB (+115KB) |
| Source Map | 有 | **已移除** |
| Tengu 事件 | 827 | 860 (+39 / -6) |
| 环境变量 | 178 | 183 (+8 / -3) |
| GrowthBook 配置 | 17 | 18 (+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 工作流生成*