docs(C34): v2 勘误保留 + 补 4 个 v2 模式 (YAO-132)

[luyao618]

概要

YAO-132 / C34《架构模式总结》v1→v2 勘误保留档。

• 篇数勘误：24/25 → 33/34；7 个模式 → 11 个模式
• 新增 4 个 v2 模式（每个含问题/解法/迁移要点，文件:行 锚点）：
  • 模式 8: Bridge IPC — crash-recovery pointer + mtime 心跳 + worktree fanout
  • 模式 9: Coordinator-Agent — 同源码双角色，env 切换，工具白名单做减法
  • 模式 10: Migration-as-Code — 11 个独立幂等迁移文件，不抽 version 链
  • 模式 11: Output-Style-as-Plugin — markdown + frontmatter，Skills/Commands/Memory 共享
• 重写"## 7 个模式的全景关系"内的 mermaid 图，补 4 新模式与既有模式的连边
• 扩展"## 写在最后" trade-off 列表为 8 条

来源 commit

290fdc9481a70612bc5823aa4ed225c52c52aad3（Claude Code 源仓库），所有引用均含 file:line 锚点。

风格双亲实证

风格双亲：v1-03《状态管理 — React 与非 React 世界的状态桥接》+ v1-20《API 调用与错误恢复 — 面向不可靠网络的鲁棒设计》

两章都是"先把问题的真实复杂度铺开 → 给一段源码 → 解释为什么这么写 → 给迁移启示"的散文体，正是本章模式 8（Bridge IPC）/ 模式 9（Coordinator）需要复刻的叙事节奏。

v1 原文摘抄（真实摘自 docs/，未删改）

v1-03 节选 · docs/03-状态管理.md L7–L16（"为什么状态管理值得单独一篇？"小节）

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。

（中文计数 ≈ 250 字，超过 200 字闸）

v1-20 节选 · docs/20-API调用与错误恢复.md L7–L17（"为什么需要如此复杂的错误恢复？"小节）

当你在本地调用一个 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，不得不从头开始。

Claude Code 的解决方案是一套三层防御架构：withRetry 通用重试层 → 流式/非流式双模式 → 错误分类与用户友好提示。

（中文计数 ≈ 280 字，超过 200 字闸）

本 PR 新写正文摘抄（真实摘自 docs/25-架构模式总结.md 本次新增段落）

新写段落 1 · 模式 8 Bridge IPC 开篇 + 解法 + 哲学解释（L592–L626）

当一个长时间运行的本地 CLI 进程需要被另一端（手机、Web、桌面端）远程驱动时，你会撞上一个看似简单、其实很恶心的问题：这两端的生命周期不对齐。CLI 进程可能崩溃、被 kill -9、被终端关闭；远端不知道。下次用户想"接着上次那个会话继续"时，怎么找回正确的 session？

bridge/bridgePointer.ts 用一个极轻量的 JSON 文件 + 文件 mtime 当心跳，把这个问题压成了 200 行代码。

bridge session 一启动就把 {sessionId, environmentId, source} 写到 .../bridge-pointer.json，之后周期性"刷新"——但不改内容，只是 writeFile 一次让 mtime 推到当前时间。clean shutdown 时把它 unlink 掉。

这个设计的精妙之处在于用文件系统的两个原生原语（内容 + mtime）分别承载两件不同的事：内容承载身份（sessionId / environmentId）——回答"我要恢复哪个 session"；mtime 承载活跃度——回答"这个 pointer 还有效吗"。

（中文计数 ≈ 290 字，超过 200 字闸；叙事性段落，非纯代码过渡段，刻意复刻 v1-20 "先把真实复杂度铺出来再剖析源码"的破题节奏）

新写段落 2 · 模式 9 Coordinator-Agent 开篇 + 解法 + 减法白名单（L650–L684）

当系统从"单 Agent 串行做事"演化到"多 Agent 并行做事"时，最容易掉进的坑是给协调者写一份独立的代码。两套 Prompt、两套工具白名单、两套上下文构造——很快就会出现"协调者不知道工人能用什么工具"、"工人能调用协调者专属的 SendMessage"这类 bug。

coordinator/coordinatorMode.ts 一共 369 行，整章只做一件事：把同一份 Claude Code 二进制，按一个环境变量切成 coordinator 或 worker。外层用 feature('COORDINATOR_MODE') 做编译期门控（模式 1 的 DCE），里层用环境变量做运行期切换。这意味着非 coordinator 构建里这段代码会被 bundler 直接 DCE 掉——零运行时成本。

注意这里的减法：INTERNAL_WORKER_TOOLS（TeamCreate / TeamDelete / SendMessage / SyntheticOutput）是 coordinator 自己用的、不应该被 worker 调用的工具。同一个工具池，根据角色减去不应该暴露的部分，而不是为两个角色各维护一份白名单。

（中文计数 ≈ 280 字，超过 200 字闸；叙事性段落，复刻 v1-03 "先讲为什么这个方案不行 → 给最终选择"的对照节奏）

段落统计

• 保留 v1 段落：原 643 行结构全部保留（11 个 H2 全部保留，C-2 OK）
• 改写段落：仅 intro 2 句（"24 篇"→"33 篇"，"7 个"→"11 个"）+ closing trade-off 列表追加 4 条
• 新增段落：4 个新模式（模式 8-11），mermaid 图补连边
• C-1 中文段落留存率：98.0%（远高于 50% 闸门）
• N（保留）≫ M（改写）+ K（新增）：保留段落数 ≫ 改写 2 句 + 新增 4 模式段落，满足 R-2

CI 验证

[C-1] OK   docs/25-架构模式总结.md: 中文段落留存率 98.0%
[C-2] OK   docs/25-架构模式总结.md: 全部 11 个 v1 标题保留
[C-3] skip  docs/25-架构模式总结.md: 非 v2 新增章节
[no-frontmatter] OK
[no-revision-codenames] OK

⚠️ 注意

按 YAO-132 issue 显式要求：「只提 PR，不要 merge」——Yao 手动合并。