docs-to-book

Docs to Book —— 文档转网站书

把一个项目的文档（散落在 docs/ 里的成堆 Markdown，或缺失文档时直接从代码反推），消化重构为一本结构清晰、重新润色、带阅读路线的离线静态网站。读者顺着读一遍，就能完整理解整个项目。

核心理念：不是搬运文档，而是重新叙述项目——让读者按人的认知逻辑走一遍，而不是按文件目录走。无论输入是文档还是代码，产出都是一本连贯的书。

Quick Start

0. 判定文档完备度 → 决定走哪条路径（详见下方「前置判定」）：
   • 完备：以 docs/ 为主通读，代码仅核实漂移
   • 残缺/过时：文档为线索 + 并行探查代码补全空白，交叉印证
   • 无文档：完全以代码探查为核心，agent 从代码反推全书
1. 梳理：按选定路径产出统一「全局笔记」（跨文档/跨模块整合 + 演进逻辑 + 漂移点）。量大用并行子代理分读
2. 归类：按「七部分分类法」重排内容，设计全书骨架 → 写 book.config.js
3. 搭壳：套 templates/ 的构建脚本 + 设计系统，写 2-4 个标杆页定文风
4. 填内容：并行委派子代理填充其余页，统一文风（见 references/voice-style.md）
5. 验证：跑 verify.js + 真实浏览器渲染 Mermaid + 截图视觉终检

前置判定 · 文档完备度

做完 Step 0 的盘点后，按文档覆盖与新鲜度走三条路径之一。代码永远是事实基线，文档是线索：

残缺/过时与无文档两条路径都需要探查代码库，方法见 codebase-survey.md。

---

渐进式披露（本 skill 的设计原则）

本 skill 按需加载。SKILL.md 是路由入口，只放方法论骨架与路由；具体规范在 references/，按当前步骤读取对应那份即可，不必全读。可复用产物在 templates/，直接复制改用。

当前步骤 → 读哪份 reference

需要的产物 → 用哪个 template

落地拷贝清单（Phase 2 搭壳时照做）：build.js、verify.js、book.config.js 拷到输出目录根；style.css、app.js 拷到 assets/；content-example.html 不进站点，作为写内容片段时的组件用法参考（尤其：卡片内标题用 h4，h2/h3 会被抽进本页目录）。漏拷 app.js 或 style.css 会让页面裸奔——verify.js 会查，但别等它报。

---

核心方法论

七部分分类法

任何项目的文档，都能按「认识 → 演进 → 方法论 → 实现 → 数据 → 运维 → 规范」的认知曲线重新组织。这是本 skill 最重要的洞察——不要沿用 docs/ 的原始目录，要按读者理解项目的自然顺序重排。详见 classification.md。

重叙述，非搬运

• 规划体「将要做 X」→ 改写陈述体「系统是怎样的」
• 每页能独立读懂，不依赖读者读过别处
• 数字/表名/字段/命令/配置值：逐字保留，绝不改写
• 文档与代码不一致处：单列一页「漂移清单」，照应「以代码为准」

文风：沉静陈述体

去口语、去营销、去感叹、去 emoji。详见 voice-style.md。

阅读路线

主线按七部分排，顺着读即可。另给「30 分钟速览」「按角色切入」两条辅线。详见 reading-path.md。

---

站点形态

零依赖、双击即开的静态多页站：

• 左侧目录树 + 右侧本页小目录（TOC 滚动高亮）
• 上一页/下一页 + 全文搜索（⌘K）
• 深浅色切换 + Mermaid 架构/流程图
• 侧栏滚动位置跨页保持（跳转不回顶）

技术约束：纯 HTML/CSS/JS，无需服务器、无需 node_modules。一个 build.js 读 config + content 分页套壳生成，一个 verify.js 校验。

---

工作流（按阶段）

Phase 0 · 盘点与梳理

1. 评估文档完备度：docs/ 是否存在、覆盖度、新鲜度（是否与代码明显不符）
2. 按完备度选路径，三条路径的子代理策略不同：
   - 完备：项目有 CLAUDE.md / README.md 等高质量总览文件 → 主 agent 直接读这些关键文件
     即可建立全局认知，不必等 Explore 代理（代理扫描 100+ 文档产出的摘要往往你读完
     关键文件后就用不上了）。如需核实具体细节，按需点读。
   - 残缺/过时：文档为线索 + 代码探查补全（见 codebase-survey.md 的 6 个角度）
   - 无文档：完全以代码探查为核心
3. 探查类代理只在「残缺/过时」和「无文档」两条路径派发，且只读扫描用轻量/只读型代理。
   完备路径下：量大的 docs/ 如需批量扫描 → 只在你有明确问题需要回答时才派，不要在
   「先读一遍」阶段无目标地全量扫描。
4. 主线汇总统一"全局笔记"：跨文档/跨模块整合、演进逻辑、文档-代码漂移点
   （文档与代码探查的笔记合并成一份，不区分来源）

无文档或残缺时，代码探查的 6 个切入角度：入口与启动 / 模块边界与依赖 / 数据流与状态 / 持久化与数据层 / 配置部署运维 / 外部集成与职责边界。详见 codebase-survey.md。

Phase 1 · 骨架

1. 按七部分分类法把内容归入各部分
2. 每部分拆成若干页(slug)，定标题与阅读顺序
3. 估算总页数：7 个固定页（封面/阅读指南/漂移清单/术语表/API参考/项目规范/快速开始）
   + 每部分至少 1 个总览页 + 每个核心模块/工作流约 1 页。
   小项目 ~15 页，中型项目 ~25 页，大型项目 ~35 页。心里有数再动笔。
4. 写 book.config.js：parts[] / pages[]{slug,title,part}，next-prev 自动算

Phase 2 · 外壳

1. 写 style.css 设计系统(令牌→基础→排版→组件→响应式)
2. 写 build.js：读 config + content/{slug}.html，套统一外壳输出 pages/{slug}.html
   自动抽 TOC(h2/h3)、算上下页、生成搜索索引、注入侧栏滚动保持脚本
3. 跑一次测试构建，确认引擎通(页面占位无妨)
   - 若项目 `package.json` 设了 `"type": "module"`，`.js` 文件会被当成 ESM 导致
     `require()` 报错。此时将 `build.js`、`verify.js`、`book.config.js` 改扩展名为
     `.cjs`，并更新 `require` 路径。注意：`node --check` 只做语法检查、不会触发
     `require` 解析，**探测请直接跑** `node build.js`（或先 `node -e "require('./build.js')"`）。

Phase 3 · 内容

1. 划分页面归属（防冲突，关键步骤）：
   - 主 agent 负责的页：封面、阅读指南、总览页（项目总览/架构总览）、漂移清单、
     术语表、API 参考——这些需要跨文档交叉引用、全局一致性要求高
   - 子代理负责的页：独立性强的模块/工作流描述页（如「CPI 工作流」「Fed 四件套」）、
     各 part 之下的独立主题页——页内闭环、不依赖其他页的内容
   - 文件落盘规则：由主 agent 统一 Write 所有 content/*.html。
     子代理不直接写文件，而是返回「slug + HTML 正文」文本，由主 agent 落盘。
     这能杜绝主 agent 和子代理同时写同一个文件导致的冲突。
2. 亲手写 2-4 个标杆页(封面/阅读指南/总览/漂移清单)，定组件用法与文风
3. 写一份 AUTHORING.md 内容撰写规范(共享给子代理)
4. 子代理规范（并行委派时）：
   - 只读探查用轻量/只读型代理；写内容用通用代理
   - 委派 prompt 里写死：子代理只返回「slug + HTML 正文」文本，不自己落盘文件
   - prompt 硬约束：只改散文措辞，绝不动数字/表名/字段/命令/mermaid/HTML 结构
5. 主 agent 收到子代理返回的内容后，抽查几页确认无事实错误，再统一 Write 落盘
6. 逐组验收，早退或超时的代理补做
7. **事实验证（关键，不可跳过）**：全部内容写完后、进入 Phase 4 前，主 agent 必须
   逐项核对以下高频遗漏模式（实测踩坑总结）：
   - **数字类事实**（端点数、阈值、计数）：grep 源码确认，不信任文档
   - **否定结论**（「无 X」「不存在 X」）：grep 源码搜索验证，常见反例：文档说
     「无通知」但代码有 webhook
   - **配置项**：在 config.py / Settings 类中确认存在，环境变量名 ≠ 有效配置
   - **代码片段**：逐行与源文件对齐，不从文档中抄过时版本
   - **执行路径描述**（如「支持 A/B 两种模式」）：检查 orchestrator / runner
     确认模式是否仍在运行时路径上
   详见 quality-checks.md「代码核对 checklist」。
8. **清理检查**：全部子代理完成后，确认输出目录外没有遗留的临时产物（如代理工具
   自动落盘的中间文件、未归入 `content/` 的 HTML 片段等）。`git status` 或 `ls`
   快速扫一遍项目根目录，发现多余文件立即清理。

Phase 4 · 验证

1. 内容准确性抽查（重点）：verify.js 只查语法不查事实。对子代理写的页做抽查——
   至少抽 3-5 页，对照原始文档/CLAUDE.md，确认表名/端口/workflow名/命令/配置值
   未被代理在润色时误改。关键事实项见 quality-checks.md
2. **代码核对 checklist**（Phase 3 事实验证的二次确认）：
   - 每个数字（端点数、阈值、计数）→ grep 源码确认
   - 每个否定结论（「无 X」）→ grep 源码搜索验证
   - 每个配置项 → 在 config.py / Settings 类中确认存在
   - 每个代码片段 → 逐行与源文件对齐
   - 每个执行路径描述 → 检查 orchestrator / runner 确认
3. node verify.js：内部链接全有效、mermaid 语法、HTML 结构
4. 真实浏览器 headless 渲染所有 mermaid 图，确认 0 报错(光看源码不够)
5. 截图视觉终检：封面、最复杂页(含多图)、暗色模式
6. 重新构建确认齐全

详见 quality-checks.md。

---

关键约束（硬规则）

• emoji：装饰性 emoji 一律移除；callout 改 CSS 文字标签；几何/功能字符（✓ ★ ◐ ⌘）可留
• 标点：CJK 相邻的半角 ,; 转全角 ，；，但保护 code/pre/mermaid 块不动
• 事实保真：数字、阈值、表名、字段、workflow 名、命令、配置 = 逐字保留
• 漂移透明：文档说一套代码做一套的，单列漂移清单页，提示「以代码为准」
• 离线可用：Mermaid 等三方库落到 assets/ 本地，不依赖 CDN。获取顺序： ① 项目 node_modules/mermaid/dist/mermaid.min.js 直接拷；② 有网时 npm pack mermaid 或从 jsdelivr/unpkg 下载一次；③ 完全离线且拿不到 → 站点照常构建（build.js 会告警）， 在 README 与交付说明里明确"图需补库后可见"，不要沉默交付
• 子代理委派：遵循所在环境的委派机制与命名规范；核心不变——子代理只返回结构化摘要与散文改写，不得改动事实

---

输出位置

站点写到项目内指定目录（如 文档可视化/ 或 docs-site/）：

文档可视化/
├── index.html              ← 双击即开
├── pages/                  ← 生成的各页
├── assets/                 ← mermaid.min.js 等(离线)
├── build.js  verify.js     ← 可重新生成/校验
├── book.config.js          ← 全书结构(单一事实来源)
├── content/                ← 内容源(按 slug)
└── README.md               ← 维护说明

---

常见坑