项目文档生成器

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

---

📑 目录

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

---

📖 概述

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

核心能力：

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

## 项目类型判定

- **项目名称**：[从 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：

## 文档生成计划

### 主文档
- `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 + 每个子文档各为一个子任务：

| 编号 | 子任务 | 产出文件 | 类型 |
|------|--------|----------|------|
| 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-01Q-06 禁止模式 + 结构完整性 + 示例完整性 + 内容一致性 + 图表检查 + P-01P-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 输出导航概览

## 文档生成完成

### 已生成文档

| 文件 | 内容摘要 | 行数 |
|------|----------|------|
| 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 工具项目完整文档示例