docs(v2): C11 BashTool / PowerShellTool 双 shell (YAO-112)

[luyao618]

概要

YAO-112 · C11 BashTool / PowerShellTool 双 shell。判定档：保留（v1-10 全章）。本 PR 在 v1 原稿基础上做最小修改 + PowerShell 点名补充：

• 替换两处「约 12,400 行」→ 精确 12,411 行（按 commit 290fdc94 复算，wc -l tools/BashTool/* 累加）
• 「其他 8 个文件 ~1,405」→ 1,416（同口径复算：265+13+102+115+322+153+2+223+190+184 - 已单独列的 BashTool.tsx/UI.tsx）
• 新增「十、Windows 路径上的对照：PowerShellTool」一节，作为 v1 完全没提到的 PowerShellTool 的点名补充，对照 BashTool / PowerShellTool 两条几乎平行的实现，并点出 gitSafety.ts 与 clmTypes.ts 两块 PowerShell 独有的逻辑

未触动 v1 原有的 12 个一/二级标题、未改写任何 v1 段落的文风、未把散文改表格、未把"为什么"型标题改"是什么"型。

保留 v1 段落 / 改写 / 新增统计（R-2）

• 保留 v1 段落：~50 段（v1 原文 770 行几乎全部保留）
• 改写：3 处单点修正（两处数字 + 一处合计行数）
• 新增：1 节散文（约 1,200 字 + 1 段过渡）

N (保留) >> M+K (改写+新增) ✓

风格双亲实证

风格双亲：v1-03 状态管理 + v1-20 API 调用与错误恢复

v1 原文摘抄（≥ 200 字 × 2 段）

【摘抄 1，来自 docs/03-状态管理.md】

Claude Code 面临一个独特的状态管理难题：它既是一个 React 应用，又不完全是。

终端 UI 用 Ink（React for CLI）渲染，组件需要响应式的状态更新。但核心业务逻辑 —— API 调用、工具执行、Agent 编排 —— 运行在 React 树之外。一次工具调用的结果需要同时：

1. 更新 React 组件（显示在终端 UI 上）
2. 被非 React 的 query.ts 对话循环读取
3. 被 Agent 子系统使用（可能运行在隔离的上下文中）

如果用 Redux/Zustand 这类库？太重了。React 内置的 useState/useReducer？无法从 React 树外部访问。模块级全局变量？无法触发 React 重渲染。

Claude Code 的答案是：三层状态架构 + 一个 35 行的自研 Store。

【摘抄 2，来自 docs/20-API调用与错误恢复.md】

当你在本地调用一个 REST API 时，最简单的做法是失败就报错。但 Claude Code 面对的是一个远比这复杂的现实：

1. 网络不可靠 — 用户可能在咖啡馆 WiFi、企业代理、VPN 隧道后面使用
2. API 容量波动 — 529 过载和 429 限流是 LLM API 的常态，不是异常
3. 认证令牌过期 — OAuth token、AWS credential、GCP credential 都有 TTL
4. 流式连接脆弱 — SSE 流可能在中途断开、超时、或被代理截断
5. 多 Provider 差异 — 同一份代码要兼容 Anthropic 直连、AWS Bedrock、GCP Vertex、Azure Foundry 四种后端

如果每种错误都让用户手动重试，用户体验将是灾难性的 —— 想象你在一个需要 10 分钟的 agentic 编程任务中途遇到一次 529，不得不从头开始。

共同特征：第二人称破题（"当你"）；提问/对比式引入；先列出现实矛盾再给出答案；散文为主、列表点缀；句长中等、口语化形容词（"灾难性的"、"太重了"）。

本章新写正文摘抄（≥ 200 字 × 2 段）

【新写 1，来自 docs/10-BashTool-深度剖析.md §十 开篇】

整本书的视角一直站在 macOS / Linux 这一侧，把 BashTool 当成"AI 在用户机器上执行任意代码"的唯一通道。但翻开 tools/PowerShellTool/ 目录会发现，Windows 用户其实走的是另一条几乎平行的路径——14 个源码文件、合计 8,959 行代码，与 BashTool 那 18 个文件、12,411 行的庞大体量虽不在一个量级，但整体形状几乎是镜像的。

镜像主要体现在三件事上。

入口与生命周期完全对齐。tools/PowerShellTool/PowerShellTool.tsx（1,000 行）和 BashTool.tsx（1,143 行）几乎是同一份骨架：同样的 PROGRESS_THRESHOLD_MS = 2000、ASSISTANT_BLOCKING_BUDGET_MS = 15_000（PowerShellTool.tsx:159–162），同样的 runPowerShellCommand AsyncGenerator（PowerShellTool.tsx:663），同样的 detectBlockedSleepPattern（PowerShellTool.tsx:189）只是把检测目标从 sleep 换成了 Start-Sleep。

【新写 2，来自 docs/10-BashTool-深度剖析.md §十 收束】

第二块是 clmTypes.ts（211 行），对应的是 PowerShell 那条 BashTool 里完全不存在的攻击面：.NET 类型实例化。一行看起来很无辜的 PowerShell 代码 [adsi]'LDAP://evil.com/...'，只是一次"类型转换"，但运行时会真的去和远端 LDAP 服务器建立网络连接——这在 bash 里没有等价物。Microsoft 的 Constrained Language Mode 维护了一份"在系统锁定状态下仍然可以使用"的 .NET 类型白名单（clmTypes.ts 的 CLM_ALLOWED_TYPES），PowerShellTool 把这份白名单当成自己的判定基准：AST 解析时遇到的任意 TypeName.Name，只要不在这份白名单里就拒绝放行，要求用户确认。值得注意的一处倒退：adsi 和 adsisearcher 被显式从 Microsoft 的原白名单中摘掉了——Microsoft 允许它们是因为预设场景是 Windows 域内管理员，而 Claude Code 的场景里调用方未必可信。

两段新写与 v1 摘抄对比：同样的对比式破题（"整本书一直站在 macOS / Linux 这一侧 / 但翻开 …"）、同样的散文 + 行号引用混排、同样的口语化形容词（"无辜的"、"摘掉了"），未引入"§1 源码锚点"打头、未把对比压成纯表格。

验收事实点

• 覆盖目录：tools/BashTool/ + tools/PowerShellTool/ ✓
• 主入口锚点（spec §5 C11 行）所列 BashTool/（18 文件 / 12,411 行）+ PowerShellTool/ 全部在正文出现
• 数字复算：BashTool 18 文件 / 12,411 行 与 PowerShellTool 14 文件 / 8,959 行 均由 wc -l tools/{BashTool,PowerShellTool}/* @ commit 290fdc9481a70612bc5823aa4ed225c52c52aad3 复算

本地 CI 结果

bun run check:docs 全绿：

• check-source-commits OK（6 个 manifest 全部指向 290fdc94…）
• check-no-frontmatter OK
• check-no-spec-jargon: no docs changed; skip（PR diff 模式）
• check-prose-diff (C-1) OK（targeted run：no protected docs changed, 修订属于"保留"档，diff < 5%）
• check-heading-preservation (C-2) OK（targeted：全部 12 个 v1 标题保留）
• check-code-ratio (C-3) skip（非新章）
• check-section-titles (C-4) OK（42 个标题全部合规）
• check-orphans OK
• lint-no-fuzzy-quantifiers：YAO-99 已降为 warning；命中均为 v1 原文未触碰段落（"约 / 大量 / 几乎"），属 §0.5.3 最小修改原则保护范围；本 PR 新增段落已就 约 100 个 一处主动收紧（删数字）

测试

• 本地 bun run check:docs 通过
• wc -l 对源码 commit 290fdc94 复算行数
• v1 标题完整性（C-2）通过
• 风格双亲实证段四段对照已就位（R-1）