docs(v2): C32 命令系统全景 (YAO-103)

[luyao618]

概要

本 PR 是 v1 第 11 章「命令系统」的 v2 迭代重写交付。按 spec §0.5.3「最小修改原则」，diff 集中在补一段缺失的源码事实——v1 通篇没给出 commands/ 目录的真实文件分布，本次在「二、命令聚合：六大来源的统一注册」一节的开篇之前补一段散文，落地 spec §1 主入口锚点声明的 commands.ts:1-754, commands/（86 一级目录 + 15 一级文件 = 101 一级条目，总 207 文件）。

v1 已发布章节那种叙事博客的风格、骨架、段落都不动；不重排、不表格化、不换皮小标题。

风格双亲实证

风格双亲：v1-09 工具系统设计 + v1-03 状态管理

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

【摘抄 1，来自 docs/09-工具系统设计.md】
本篇是《深入 Claude Code 源码》系列的第 9 篇。我们将深入工具系统的核心设计：从 Tool 接口的核心方法，到 buildTool() 的 builder 模式，到 tools.ts 的注册表架构，再到 ToolSearch 的延迟加载机制，揭示一个生产级 AI Agent 如何管理 40+ 个内置工具和无限数量的 MCP 工具。一个 AI Agent 与普通 chatbot 的本质区别在于：Agent 能执行动作。当模型决定读取一个文件、运行一条 Shell 命令、或搜索代码时，它依赖的就是工具系统。Claude Code 拥有 40+ 个内置工具和通过 MCP 协议接入的无限数量外部工具。管理这样规模的工具集面临几个核心挑战：接口一致性、安全默认、条件注册、规模可扩展。当工具数量超过模型上下文窗口的承载能力时，需要动态发现机制。本篇将回答这些问题。

【摘抄 2，来自 docs/03-状态管理.md】
本篇是《深入 Claude Code 源码》系列的第 3 篇。我们将深入分析 Claude Code 如何用一个 35 行的极简 Store 实现，桥接 React UI 与非 React 业务逻辑之间的状态管理。Claude Code 面临一个独特的状态管理难题：它既是一个 React 应用，又不完全是。终端 UI 用 Ink（React for CLI）渲染，组件需要响应式的状态更新。但核心业务逻辑——API 调用、工具执行、Agent 编排——运行在 React 树之外。一次工具调用的结果需要同时更新 React 组件、被非 React 的 query.ts 对话循环读取、被 Agent 子系统使用。如果用 Redux/Zustand 这类库？太重了。React 内置的 useState/useReducer？无法从 React 树外部访问。模块级全局变量？无法触发 React 重渲染。

本章新写正文摘抄（≥ 200 字 × 2 段，覆盖典型叙事段）

【新写 1，来自 docs/11-命令系统.md 二节开篇】
commands.ts 是整个命令系统的聚合枢纽。它将来自六个不同来源的命令合并为一个统一的列表。聚合枢纽本身有多大？commands.ts 当前 754 行，向上挂接了 commands/ 目录——这个目录在 commit 290fdc9 上是 86 个一级子目录 + 15 个一级 .ts/.tsx 文件 = 101 个一级条目，合计 207 个源码文件。这 101 个一级条目基本是一对一地各自承载一个内建命令（少数文件只是辅助模块，如 createMovedToPluginCommand.ts）。换句话说，下面这套加载机制要把这 200 来个文件、连同来自磁盘 Skill / Plugin / Bundled / MCP / Workflow 的命令，统一收编进同一份 Command[] 列表里。

【新写 2，本 PR 未对 v1 散文段做改写，第二段摘抄取自 v1 保留段（diff=0）以示文风一致】
当你在 Claude Code REPL 里输入 /commit、/compact、/review 时，你用的是斜杠命令。这些命令看起来只是快捷操作，但在 Claude Code 中，它们承载着远比表面复杂的职责：有的命令本地执行，有的命令生成 Prompt 发给模型，有的命令需要渲染交互式 UI，有的命令来自用户自定义 Skill，有的命令来自第三方 Plugin，有的命令来自 MCP 服务器，有的命令只对内部用户可见。关键问题是：如何用一套统一的类型体系将这些来源完全不同、执行方式各异的命令聚合在一起？如何让 70+ 个内建命令的加载不拖慢启动速度？

段落统计

• 保留 v1 段落：~全部（中文留存率 99.8%，C-1 报告）
• 改写 v1 段落：0
• 新增段落：1（嵌入二节开篇，散文，约 230 字，含主入口锚点 commands.ts:1-754 与 commands/ 目录三个计数）

N (=≈全章 v1 段落) 显著大于 M+K (=0+1)，符合 R-2。

验收事实点

• 主入口锚点 commands.ts:1-754 已出现 ✓
• commands/ 目录 86 一级目录 + 15 一级文件 = 101 一级条目 / 207 文件 已出现 ✓
• 数字来源：find commands -maxdepth 1 -type d \| wc -l (87 含 commands 本身) → 86 子目录；find commands -maxdepth 1 -type f \| wc -l → 15；find commands -type f \| wc -l → 207；commit 290fdc9481a70612bc5823aa4ed225c52c52aad3 复算
• 标题保留：全部 11 个 v1 标题保留（C-2 OK）
• 中文段落留存率：99.8%（C-1 OK，远高于 50% 门限）
• 工程化小标题禁词：38 个标题全部合规（C-4 OK）
• 程度副词禁词：本次 diff 行无命中（no-fuzzy OK）
• squad 内部术语：本次 diff 行无命中（no-spec-jargon OK）
• frontmatter：本章无 frontmatter（C-5 OK）
• 孤儿目录：无（F OK）

CI 验收

bun run check:docs 全部 10 项 pass：

• check-source-commits OK
• lint-no-fuzzy-quantifiers OK
• lint-no-revision-codenames OK
• check-no-frontmatter-in-chapters OK
• lint-no-spec-jargon-in-prose OK
• check-prose-diff-ratio: 99.8% 留存
• check-heading-preservation: 11/11
• check-code-ratio: skip（v1 已发布章节）
• lint-section-titles: 38/38
• gen-module-matrix --check-orphans: covered=31

manifest diff 摘要

本 PR 不动 docs/appendix/*.manifest.json，无 manifest 变化。

备注

• 按 issue 流程，本 PR 不 merge，等 OC-R review + 尧哥手动合。
• v1 原文中存在的「约 / 大概 / 不少 / 大量」等程度副词位于 v1 已发布段落，按 spec §0.5.3 最小修改原则保留，未触碰。CI 已确认 diff 行不含禁词。

🤖 Generated with Claude Code