Document Writer

---
name: document-writer
description: 为项目生成高质量 README 及子文档（README 作索引枢纽，详细内容拆到子文档）。触发："生成 README"、"写项目文档"、"补文档"、"write docs"、"write readme"。
---

# 项目文档生成器

> 为项目生成高质量 README 及子文档，按项目类型自动选择编写策略，README 作为索引枢纽，详细内容拆分到子文档。

---

## 📑 目录

- 📖 概述
- 📌 适用场景
- 📋 核心原则
- 🔄 工作流总览
- 🔍 阶段 1：项目扫描 + 类型识别
- ⚙️ 阶段 2：策略确认 + 拆分决策
- 📝 阶段 3：并行内容生成
- ✅ 阶段 4：补充交叉引用 + 质量检查
- 📦 阶段 5：输出落盘
- 📚 参考文档

---

## 📖 概述

本 skill 为项目自动生成高质量 README 及子文档，按项目类型自动选择编写策略。README 作为索引枢纽控制在 120 行内，详细信息按主题拆分到子文档。

**核心能力**：

| 能力 | 说明 |
|------|------|
| 类型自动识别 | 扫描项目结构，判定为库 / CLI / Web 应用 / 插件 / 混合型 |
| 策略驱动 | 每种类型有对应的章节模板、示例规则、拆分阈值 |
| 并行生成 | 子文档 ≥ 2 时自动调用 task-dispatch 并行生成 |
| 质量闭环 | 内置 Q-01~Q-06 禁止模式 + P-01~P-06 专业性检查 |

**文档架构**：README（索引枢纽）+ 子文档（API 参考 / 配置指南 / 架构文档 / 部署指南等），按拆分阈值按需生成，简单项目不冗余拆分。

## 📌 适用场景

满足以下任一条件时触发本 skill：

- 用户明确要求为项目生成 README 或完整文档
- 新建项目需要对外发布的文档
- 已有项目缺少文档需要补齐
- 用户说"写个 README"、"生成文档"、"document this"、"补文档" 等

### 排除场景

以下情况**不触发**：

- 用户只是问"README 怎么写" → 直接回答
- 用户只要求写单一章节 → 直接写
- 项目没有代码（纯文档仓库、配置仓库）→ 无法自动识别类型
- 用户明确表示只需要一个简单草稿 → 不走质量检查
- 用户要的是前端 API 调用流程文档 → 使用 `frontend-api-guide`
- 用户要的是 API 接口设计文档（接口契约/错误码）→ 使用 `api-design`
- 用户要的是技术设计文档（方案/架构）→ 使用 `design-craft`
- 用户要的是模块内部技术资产（契约层 + 实现层）→ 使用 `expert-team`

### 快速生成模式

项目同时满足以下**全部条件**时，跳过阶段 2 的用户确认步骤（2.2~2.3），合并阶段 1 + 2，直接进入内容生成（2.1 策略模板加载仍执行，确保套用类型专属章节）：

- 公开 API 或命令数 ≤ 5 个
- 配置项 ≤ 10 个
- 用户未要求子文档拆分
- 项目类型判定明确（非混合型）

快速生成模式只生成单个 README（不拆子文档），但仍遵守全部质量底线。阶段 4.2 检查清单中"子文档间无重复内容"等子文档相关项在单 README 模式下豁免。若快速模式生成的 README 超过 120 行，回退至完整工作流（阶段 2）进行拆分决策。

## 📋 核心原则

1. **类型驱动策略**：先识别项目类型，再套用对应策略
2. **示例即血肉**：每个对外接口（API/命令/配置项）必须有输入→输出完整示例
3. **README 是索引**：README 控制在 120 行内做导航枢纽（快速开始须一屏内读完）；详细信息按主题拆分到子文档。受外部约束（如"技能清单唯一来源""API 参考索引"）无法 ≤120 行时允许豁免，须在文档中标注豁免原因
4. **按需拆分**：有拆分阈值，简单项目不冗余拆分，复杂项目不遗漏文档
5. **并行生成**：子文档 ≥ 2 时自动调用 task-dispatch 并行生成
6. **零空洞容忍**：禁止出现 "TODO"、"Coming soon"、"See source code" 等占位符
7. **语言跟随项目**：文档语言跟随项目现有文档语言；无现有文档时默认中文；用户明确指定风格（语言/徽章/格式约定）时优先遵循用户约定
8. **图表按需选型**：文档图表按「图本质 × 复杂度 × 渲染环境 × 复用需求」四因子选型——结构化关系图（流程/时序/状态/ER）优先 mermaid；**架构图（模块总览）统一用 SVG**；视觉布局类图、需精确样式或需独立复用的图用 SVG。SVG 命名遵循 kebab-case 规范，详见 `references/strategies.md` 通用规则
9. **GitHub 专业呈现**：文档面向 GitHub 仓库的 README 及子文档，必须达到开源项目级专业度——目标读者清晰、术语一致、视觉规范（徽章/代码块/表格）、语言精炼无口语化。详见 `references/quality-rules.md`「专业性检查」

---

## 🔄 工作流总览

```
阶段 1：项目扫描 + 类型识别   → 分析项目结构，自动判定类型
阶段 2：策略确认 + 拆分决策   → 确定文档集，阈值判断是否需要子文档
阶段 3：并行内容生成          → 子文档 ≥ 2 时 task-dispatch 并行生成
阶段 4：补充交叉引用 + 质量检查 → 主 agent 统一补充 README 中的子文档链接
阶段 5：输出落盘              → 写入文件，给出文档导航概览
```

## 🔍 阶段 1：项目扫描 + 类型识别

### 1.1 扫描项目结构

分析以下内容（扫描结果不足以判断时再询问用户）：

- 根目录文件：`package.json`、`setup.py`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Makefile` 等
- 目录结构：`src/`、`lib/`、`commands/`、`routes/`、`controllers/` 等
- 入口文件：`index.js`、`main.go`、`app.py`、`cli.js` 等
- 依赖框架：从依赖列表中识别 Express、Flask、React、Commander 等
- 现有文档：是否已有 README、CONTRIBUTING、CHANGELOG 等

### 1.2 类型判定规则

| 项目类型 | 核心判定特征 |
|----------|-------------|
| **库 / SDK** | `package.json` 含 `main`/`exports`/`module`；`setup.py`；Go module；主要导出函数/类 |
| **CLI 工具** | `package.json` 含 `bin`；使用 commander/yargs/cobra/click/argparse 等；入口以解析命令行参数为主 |
| **Web 应用/服务** | 依赖 express/koa/next/flask/django/gin 等；含路由/控制器定义；包含 HTTP 服务启动逻辑 |
| **插件/扩展** | 依赖宿主框架（VS Code/Webpack/Babel/ESLint 等）；`package.json` 含 `engines`/`contributes` |

**混合类型**：若同时满足多种特征，合并对应策略，输出判定结果让用户确认。

### 1.3 逆向生成模式

若项目**完全没有 README**，进入逆向模式：从代码入口反推用途、从导出接口反推 API 列表、从 CLI 入口反推命令列表，推断的输出标注 `<!-- 从代码推断，输出需验证 -->`（HTML 注释格式，与 quality-rules.md Q-02 标注统一，不会被 Q-01 误判为占位符）。用户未确认时默认继续生成，保留 `<!-- 输出需验证 -->` 标注。

### 1.4 已有 README 更新模式

若项目**已有 README 但质量不达标**：保留项目描述/徽章/用户确认的信息；补充缺失的示例/空白章节；新增该类型策略应触发的子文档；重写信息密度低的章节。标注「保留/新增/重写」让用户确认。用户未确认时默认按标注方案继续，保留「待确认」标注。

### 1.5 输出判定结果

```markdown
## 项目类型判定

- **项目名称**：[从 package.json/setup.py 等提取]
- **判定类型**：[库 / CLI / Web 应用 / 插件 / 混合型]
- **判定依据**：[列出匹配到的关键特征]
- **文档语言**：[跟随项目现有文档语言；无现有文档时默认中文；用户指定风格时以用户约定为准]（核心原则 7，传递给子 agent）
- **推荐文档集**：[列出将生成的文档列表]

请确认或手动指定类型。确认后进入阶段 2 核定文档集；若最终文档集与推荐一致，无需再次确认。
```

## ⚙️ 阶段 2：策略确认 + 拆分决策

### 2.1 获取策略模板

根据确认的类型，从 `references/strategies.md` 加载对应策略模板。

### 2.2 拆分阈值判断

**库/SDK**：公开 API > 5 → `api-reference.md`；配置项 > 10 → `configuration.md`；有高级用法 → `advanced-usage.md`

**CLI**：命令数 > 5 → `command-reference.md`；配置项 > 10 → `configuration.md`；支持 CI/CD 集成 → `integration.md`

**Web 应用**：部署步骤 > 3 或多环境 → `deployment.md`；模块/服务 > 3 → `architecture.md`；有本地开发特殊配置 → `development.md`

**插件**：配置项 > 10 → `configuration.md`；API/Hooks > 5 → `api-reference.md`；有多场景示例 → `examples.md`

### 2.3 核定文档集

按 2.2 阈值核对阶段 1.5 的推荐文档集，输出最终文档集。**无论是否与推荐集一致，均输出文档生成计划（含每个子文档的触发原因）供用户知情**；仅当与推荐集一致时免去等待用户确认，直接进入阶段 3：

```markdown
## 文档生成计划

### 主文档
- `README.md` — 索引枢纽，包含概述、快速开始、子文档导航

### 子文档（共 N 个）
- `api-reference.md` — [触发原因：API 数量 12 > 阈值 5]
- `configuration.md` — [触发原因：配置项 15 > 阈值 10]

[若子文档 ≥ 2]
  → 将使用 task-dispatch 并行生成，预计加速 {N} 倍。
```

若最终文档集与阶段 1.5 推荐集一致，直接进入阶段 3 内容生成（无需再次确认）；若不一致，输出差异项请用户确认。

---

## 📝 阶段 3：并行内容生成

### 3.1 执行策略

| 子文档数 | 策略 |
|----------|------|
| 0-1 个 | 主 agent 直接生成 README + 子文档 |
| ≥ 2 个 | 调用 `task-dispatch` skill 并行生成 |

### 3.2 task-dispatch 调度要点

**task-name**：`docs-{项目名称}`（如 `docs-my-lib`），命名遵循 task-dispatch 的规则（英文小写 + 短横线）；中文项目名须转写为英文短横线形式。

**子任务编号**：遵循 task-dispatch 的子任务编号规范 `S-{NN}`（与 task-dispatch 的 `subtasks/S-{NN}/` 目录结构一致，勿自造编号格式）。

**产出路径**：以 task-dispatch 的调度约定为准（当前为 `.codebuddy/task-dispatch/{task-name}/subtasks/S-{NN}/code/`，若约定变更无需修改本 skill）。

**子任务拆分**：README + 每个子文档各为一个子任务：

```text
| 编号 | 子任务 | 产出文件 | 类型 |
|------|--------|----------|------|
| S-01 | README 生成 | README.md | 索引枢纽 |
| S-02 | API 参考生成 | api-reference.md | 子文档 |
| S-03 | 配置文档生成 | configuration.md | 子文档 |
```

独立性校验：各文档内容独立（无接口依赖），但 README 作为索引需要引用其他文档，标记为弱依赖（先定子文档文件名，README 按文件名写链接）。

**子 agent prompt 要点**（`{references/strategies.md}` 等占位符由主 agent 在派发时替换为项目内相对路径；若子 agent 环境无法访问 references 文件，主 agent 须将对应规则直接内联到 prompt，保证子 agent 自包含）：

```
你是子 agent，负责生成文档 S-{NN}：{文档名称}

## 任务目标
生成 {文档名称}，内容要求：
- 文档语言：{从阶段 1.5 获取}
- 章节结构：从 {references/strategies.md} 中对应类型的策略模板提取章节要求、示例规则（混合型项目须合并相关策略模板章节，见 strategies.md 策略 5 合并规则）
- 图表：按 {references/strategies.md}「图表选型规则」决策 mermaid vs SVG，勿误用
- 同类参照：参考 {references/examples/} 下对应类型的示例文件（如 example-1-library.md、example-2-cli.md）了解完整文档结构；若无对应类型示例，以 strategies.md 策略模板为准
- 其余遵循下方"内容质量底线"与"示例获取优先级"

## 输出目录
产出：{task-dispatch 约定的 S-{NN} 输出目录}
  - 产出文件：{文件名}.md
报告：{task-dispatch 约定的 report.md 路径}

## 内容质量底线
- 每个对外接口必须有输入→输出完整示例（规则详见 {references/quality-rules.md}）
- 每个命令必须附带预期终端输出
- 禁止任何形式的占位符（TODO、Coming soon、See source code 等）
- 章节要么写满实质内容，要么从导航中移除

## 示例获取优先级
1. 从测试文件提取（最可靠） → 2. 从示例目录提取 → 3. 从代码逻辑推断 → 4. 标注不可得

[若为 README 子任务，追加]
## README 结构
- 标题 + 一行描述 + 徽章
- 目录（TOC）：标题/徽章后、正文前，列出全部 H2 章节并与之一一对应（章节 ≥ 5 时必加；规范见 references/quality-rules.md「目录索引（TOC）检查」）
- 概述：做什么 + 解决什么问题
- 快速开始：最简安装 + 最简示例（输入+输出），30 秒内理解项目价值
- 子文档导航：各子文档链接 + 一句话说明
  （子文档文件名列表：{从阶段2获取}）
- 类型专属章节（根据策略模板追加）

完成后写 report.md，列出生成的章节和关键示例。
```

### 3.3 合并

主 agent 收集所有子 agent 产出，补充 README 中的子文档交叉引用链接（若子 agent 按指定的文件名生成则链接已正确），进入阶段 4 质量检查。

---

## ✅ 阶段 4：补充交叉引用 + 质量检查

### 4.1 补充交叉引用

主 agent 读取 README.md，执行以下交叉引用修复：
1. 确认子文档导航中的链接均指向已生成的子文档文件
2. **验证每个子文档链接的"一句话说明"与子文档实际内容一致**（并行生成时 README 子 agent 无法预知子文档内容，描述可能不准确）
3. 若描述不准确，用子文档实际内容修正

### 4.2 自动检查清单

- [ ] 全文符合 `references/quality-rules.md` 全部检查项（Q-01~Q-06 禁止模式 + 结构完整性 + 示例完整性 + 内容一致性 + 图表检查 + P-01~P-06 专业性检查）
- [ ] 每个对外接口有完整示例（输入+输出）
- [ ] 所有子文档链接可对应到实际生成的文件
- [ ] README 行数 ≤ 120（受外部约束时可豁免，见核心原则 3）
- [ ] 章节数 ≥ 5 时 README 含目录索引，目录项与 H2 一一对应（见 `references/quality-rules.md`「目录索引（TOC）检查」）
- [ ] 子文档间无重复内容（抽查相邻文档）（单 README 模式豁免）
- [ ] 概述章包含三要素（做什么 + 解决什么问题 + 与方案对比），见 `references/quality-rules.md` 结构完整性检查

### 4.3 修正缺陷

发现缺陷立即修正后重新检查，直到全部通过。

---

## 📦 阶段 5：输出落盘

### 5.1 写入文件

将生成的文档写入项目根目录。若用户指定了输出目录，写入指定路径。

SVG 资产随文档落盘：独立 SVG 文件写入各文档所在目录的 `assets/` 子目录（如 `docs/assets/architecture-overview.svg`），命名遵循 kebab-case 规范，README 中引用路径与其实际位置一致。落盘后校验：所有 `![...](...)` 引用的 SVG 文件真实存在。

### 5.2 输出导航概览

```markdown
## 文档生成完成

### 已生成文档

| 文件 | 内容摘要 | 行数 |
|------|----------|------|
| README.md | 项目概述 + 快速开始 + 导航 | 85 |
| api-reference.md | 12 个 API 的完整参考 | 340 |
| configuration.md | 15 个配置项详解 | 120 |

### SVG 资产

| 文件 | 用途 |
|------|------|
| assets/architecture-overview.svg | 模块总览图（architecture.md 引用） |

### 快速验证

- 打开 `README.md` → 快速开始 → 复制示例命令 → 应可直接跑通
- 打开 `api-reference.md` → 任意 API → 有明确的输入输出示例
- 子文档间链接 → 全部可达，无死链
```

## 📚 参考文档

- 类型策略定义：`references/strategies.md`
- 质量检查规则：`references/quality-rules.md`
- 对比例子：`references/examples/`
  - `example-1-library.md` — 库/SDK 项目完整文档示例
  - `example-2-cli.md` — CLI 工具项目完整文档示例