docs-generator

文档生成器

重组并整理项目文档，使其更清晰、更易于访问。

前置条件

此技能要求满足以下条件（开始前逐项验证；若任何一项检查失败，请停止并询问用户）：

• Git 工作树：干净或可暂存。先运行 git status；如果工作树不干净，在任何可能变基或覆盖本地更改的同步操作之前，使用 git stash push -u -m "pre-docs-sync" 进行备份。
• 所需工具：git >= 2.30、支持 Markdown 的编辑器，以及仅在需要导出图表时使用的 mermaid-cli（或其他渲染器）。使用 git --version 和 command -v mmdc 确认是否可用。
• 仓库权限：分析需要读取权限；只有在用户明确批准提交后才需要写入权限。对于只读仓库，应改为提供差异或内联摘要，而不是写入文件。
• 分支状态：存在可访问的 origin 远程仓库（git remote get-url origin）；若不存在，请勿尝试变基或拉取，而应询问用户。
• 备份：在任何会删除或移动文档文件的重组操作之前，确认仓库已推送或以其他方式备份。每次执行破坏性的 rm/git mv 之前，都要先检查 git status 并获得用户明确确认；未经试运行预览和用户批准，绝不运行 git reset --hard、git push --force 或 rm -rf。
• 安全默认设置：优先使用试运行预览（git mv -n、rm -i），并在执行任何不可逆操作前征得用户确认。

如果任何前置条件不满足，请停止并向用户说明阻碍，不要继续操作。

编辑前同步仓库（必需）

在现有仓库中创建、更新或删除文件之前，先将当前分支与远程同步：

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作树不干净，先暂存，再同步，之后恢复更改：

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

如果缺少 origin、无法拉取，或变基/暂存时发生冲突，请停止并在继续之前询问用户。

工作流

0. 创建功能分支

进行任何更改之前：

1. 检查当前分支；如果已经位于此任务对应的功能分支上，则跳过
2. 运行 git branch -r | head -20 检查仓库的分支命名惯例（例如 feat/、feature/ 等）
3. 按照仓库惯例创建并切换到新分支；如果没有惯例，则使用：feat/docs-generator

1. 分析项目

阅读代码库，确定：

• 项目类型：库、API、Web 应用、CLI、微服务
• 架构：Monorepo、多包、单模块
• 用户角色：终端用户、开发者、运维人员
• 现有文档：查找 README 文件、docs/ 文件夹、内联注释和文档字符串
• 缺口：列出已有文档及缺失内容

2. 重组文档

根目录 README.md——精简为入口文档：

• 项目概述和用途
• 快速入门（安装 + 首次使用）
• 模块/组件摘要及链接
• 许可证和联系方式

组件 README——为每个模块/软件包/服务添加文档：

• 用途和职责
• 设置说明
• 测试命令

集中整理到 docs/——按类别组织（选择适用项）：

docs/
├── architecture.md      # System design, diagrams
├── api-reference.md     # Endpoints, authentication
├── database.md          # Schema, migrations
├── deployment.md        # Production setup
├── development.md       # Local setup, contribution
├── troubleshooting.md   # Common issues
└── user-guide.md        # End-user documentation

3. 创建图表

所有可视化文档均使用 Mermaid：

• 架构图
• 数据流图
• 数据库架构图

4. 审查与验证

1. 验证所有内部链接均可正确跳转
2. 检查文档中的代码示例在语法上是否有效
3. 确认没有孤立文档（没有任何地方链接到的文件）
4. 提交前向用户说明更改摘要

向用户展示更改并征求批准。除非用户明确要求，否则不要提交。

预期输出

在中型 Node.js API 项目上运行此技能后，你应看到：

• 一份简洁的根目录 README.md，包含项目概述、快速入门、模块链接和许可证
• 每个服务或库各有一份 README.md
• 一个 docs/ 文件夹，其中包含相关文件，例如 architecture.md、api-reference.md、deployment.md 和 development.md
• 架构和数据流文档中嵌入的 Mermaid 图表
• 一份验证摘要，列出所有已检查的内部链接和发现的缺漏

验收标准

满足以下所有条件时，运行才算通过：

• 根目录 README.md 包含概述、快速入门（安装 + 首次使用），以及指向组件或 docs/ 文件的链接。
• 存在 docs/ 目录，其中至少包含以下文件之一：architecture.md、api-reference.md、deployment.md、development.md，且只包含与项目类型相关的文件。
• 每个内部 Markdown 链接都指向现有文件（没有失效的 [text](path) 引用）。
• 没有孤立文件：每个 docs/*.md 都能在一步之内从 README.md 或其他 docs/ 页面访问。
• 架构或数据流文档中的 Mermaid 图表均可正常渲染，没有语法错误（如可用，使用 mmdc 验证）。
• 不在 main/master 上提交；所有变更都在遵循仓库命名约定的功能分支上。

边缘情况

• 没有现有文档：技能通过分析代码从头生成文档。先创建 README.md，再根据项目复杂度添加 docs/ 文件。
• 文档冲突或过时：将冲突标记给用户。优先采用从代码得出的信息，而非过时文档；将过时部分标记为待审核。
• 包含许多包的单体仓库：仅为具有实际公共 API 或面向用户功能的包创建独立的 README.md；跳过自动生成或构建输出包。
• 私密内容或可能涉及机密的内容：除代码注释中已有的内容外，绝不记录凭据、令牌或仅供内部使用的端点。
• 只读仓库：如果无法写入 Git，则以差异或内联摘要的形式输出文档，而不是提交文件。

步骤完成报告

完成每个主要步骤后，按以下格式输出状态报告：

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

根据步骤实际验证的内容调整检查项名称。通过使用 √，失败使用 ×，并使用 — 添加简短说明。“Criteria” 行概述已满足的验收标准数量。“Result” 行给出总体判定。

各阶段的技能专属检查项

阶段：分支设置 — 检查项：Branch creation、Repo sync

阶段：项目分析 — 检查项：Project analysis、Gap identification

阶段：文档重组 — 检查项：Doc restructure、Diagram creation

阶段：验证 — 检查项：Validation pass、Link verification

指南

• 文档应简洁易读，便于快速浏览
• 根据项目类型调整结构（并非所有类别都适用）
• 保持相关文档之间的交叉引用
• 删除冗余或过时内容
• 保留仍然准确的现有文档