Opensource Doc Generator

开源文档生成器 (Open Source Documentation Generator)

概述

本 Skill 帮助 Agent 根据项目的实际文件和结构，为开源平台（如 GitHub、GitLab、Gitee 等）生成全套规范的说明文档。核心思路是：先分析项目，再智能推荐分级方案，经用户确认后逐一生成。

开源项目的文档质量直接影响项目的采纳率、贡献者增长和社区健康度。一份好的 README 可以让用户在 30 秒内理解项目价值；一份清晰的 CONTRIBUTING 可以降低 50% 的贡献者入门成本；而缺少 LICENSE 的项目在法律意义上根本不算开源。

工作流程

第一步：项目分析

深入扫描项目，收集以下信息：

1. 项目基本信息

   • 项目名称（从 package.json、pyproject.toml、Cargo.toml、go.mod、pom.xml、*.csproj 等配置文件中提取）
   • 项目描述和用途
   • 版本号
   • 作者/维护者信息

2. 技术栈识别

   • 编程语言（通过文件扩展名和配置文件判断）
   • 框架和库（从依赖文件中提取：package.json、requirements.txt、Pipfile、go.sum、Cargo.lock 等）
   • 构建工具（Webpack、Vite、CMake、Makefile、Gradle 等）
   • 测试框架（Jest、Pytest、Go test 等）
   • CI/CD 配置（是否已有 .github/workflows/、.gitlab-ci.yml 等）

3. 项目结构分析

   • 目录结构（源码、文档、测试、配置等目录的分布）
   • 入口文件（main.py、index.js、src/main.rs、cmd/main.go 等）
   • 文档目录（docs/、wiki/ 等）
   • 示例代码（examples/、demo/ 等）

4. 现有文档检查

   • 检查项目根目录和 .github/ 目录下已存在哪些文档文件
   • 检查 .gitignore、.editorconfig 等配置文件是否已存在
   • 检查是否已有 LICENSE 文件

5. 项目特征判断

   • 是否是库/框架（供其他项目依赖）
   • 是否是独立应用/工具
   • 是否是学术/科研项目
   • 是否有 Docker 支持
   • 是否有多语言支持
   • 项目规模（小型/中型/大型）

第二步：智能推荐分级

根据第一步的分析结果，结合下文的文档类型目录和决策矩阵，在内部生成一套分级推荐方案。这一步不需要向用户输出完整内容，而是为第三步的用户交互做好准备。

推荐分级的逻辑是：不同项目、不同用户对文档完整度有不同需求。有人想要面面俱到的全套文档，有人只想要最基本的几个文件。通过分级让用户自己选择，既尊重用户意图，又避免了"一刀切"的问题。

第三步：用户确认与选择

这是最关键的交互步骤。 在真正开始生成文件之前，必须先向用户展示分析结果和分级推荐方案，让用户做出选择。绝不能跳过这一步直接生成文件。

3.1 展示项目分析摘要

先简明扼要地向用户展示项目分析结果，让用户确认 AI 的理解是否正确：

## 项目分析摘要

- 项目名称：XXX
- 技术栈：Node.js / React / TypeScript
- 项目类型：独立应用
- 项目规模：小型
- 现有文档：已有 .gitignore，无其他文档
- 推测特征：接受外部贡献、有版本发布、跨平台

3.2 展示分级推荐方案

根据项目特征，向用户展示 3-4 个不同完整度的推荐方案。每个方案应包含：文件清单、简要说明、适用场景。

推荐的展示格式如下（以一个 Node.js 项目为例）：

## 推荐方案

根据你的项目特征，我准备了以下几套方案供你选择：

### 方案一：全套文档（最推荐）
适合希望长期维护、吸引社区贡献的正式开源项目。

包含文件：
- README.md — 项目说明，第一入口
- LICENSE — 开源许可证（需选择类型，见下方问题）
- .gitignore — Git 忽略规则
- CONTRIBUTING.md — 贡献指南
- CODE_OF_CONDUCT.md — 行为准则
- CHANGELOG.md — 变更日志
- .editorconfig — 编辑器风格统一
- .gitattributes — Git 文件属性
- .github/ISSUE_TEMPLATE/ — Issue 模板（Bug 报告 + 功能请求）
- .github/PULL_REQUEST_TEMPLATE.md — PR 模板

说明：这是最全面的方案，覆盖了开源项目所需的全部核心文档。
社区成员可以从 README 快速了解项目，通过 CONTRIBUTING 参与贡献，
通过 Issue/PR 模板高效沟通。适合面向公众、希望吸引贡献者的项目。

### 方案二：标准文档（推荐）
适合个人项目或小型团队，想要规范但不需要太多社区治理文件。

包含文件：
- README.md — 项目说明
- LICENSE — 开源许可证（需选择类型）
- .gitignore — Git 忽略规则
- CONTRIBUTING.md — 贡献指南
- CHANGELOG.md — 变更日志
- .editorconfig — 编辑器风格统一

说明：在必要文件基础上增加了贡献指南和变更日志，
适合有一定用户量但不强调社区治理的项目。

### 方案三：基础文档（精简）
适合快速开源、个人工具项目或原型阶段。

包含文件：
- README.md — 项目说明
- LICENSE — 开源许可证（需选择类型）
- .gitignore — Git 忽略规则

说明：只包含开源项目最基本的三件套。
能让别人看懂项目、合法使用代码、正确克隆仓库。
适合刚起步或仅供个人使用的项目。

### 方案四：仅 README（最小）
适合快速分享代码片段或实验性项目。

包含文件：
- README.md — 项目说明

说明：只有一个 README 文件，让别人能看懂项目做什么。
注意：没有 LICENSE 意味着他人在法律上无权使用你的代码。
仅适合实验性代码或内部演示。

以上只是示例。实际推荐时应根据项目特征调整每个方案的具体文件清单。例如：

• 如果项目有 Docker 部署需求，方案一/二应包含 Dockerfile
• 如果项目是学术/科研项目，方案一/二应包含 CITATION.cff
• 如果项目使用环境变量，方案一/二应包含 .env.example
• 如果项目处理敏感数据，方案一应包含 SECURITY.md

3.3 询问需要用户决定的事项

除了让用户选择方案外，还有一些文件的具体内容需要用户确认。这些必须在生成前问清楚，而不是事后猜测。

必须询问的事项：

1. 许可证类型（如果方案中包含 LICENSE 且项目尚未指定许可证）：

   LICENSE 文件需要选择许可证类型：
   - MIT：最宽松，几乎无限制，适合希望被广泛集成的项目（推荐）
   - Apache-2.0：明确专利授权，适合企业级项目
   - GPL-3.0：要求衍生作品也开源，保护自由
   - BSD-3-Clause：类似 MIT，适合学术/科研项目
   - 其他（请说明）
   
   你的项目使用哪种许可证？
   

2. 文档语言（如果项目代码注释和现有文档无法明确判断）：

   文档使用什么语言？
   - 中文
   - 英文
   - 中英双语
   

3. 作者/版权持有人信息（如果无法从配置文件中提取）：

   LICENSE 和 README 中需要填入作者/版权持有人名称，请提供：
   - 姓名/组织名：
   - 邮箱（可选）：
   - GitHub 用户名：
   

根据项目特征可能需要询问的事项：

• 如果项目有 Docker 需求：是否需要生成 Dockerfile 和 docker-compose.yml？
• 如果项目是学术/科研：是否需要生成 CITATION.cff？如需要，DOI 是什么？
• 如果项目接受赞助：是否需要生成 FUNDING.yml？赞助平台是什么？
• 如果项目有 CI/CD：是否需要生成 GitHub Actions workflow？

3.4 等待用户回复

将上述内容展示给用户后，停下来等待用户回复。不要自行假设用户的选择。

用户可能的回复方式：

• 选择某个方案（如"我选方案二"）
• 在方案基础上增减文件（如"方案一，但不要 CODE_OF_CONDUCT"）
• 回答许可证、语言等问题
• 提出额外需求

收到用户回复后，最终确认要创建的文件清单，然后进入第四步。

第四步：文档生成

对用户确认的每个文件类型：

1. 阅读 references/file-types-guide.md 中对应章节，了解该文件的详细内容要求和模板
2. 结合第一步收集的项目信息和第三步用户确认的信息，填充具体内容
3. 生成文件到正确路径（根目录或 .github/ 目录）
4. 对生成的内容进行质量检查

生成原则：

• 内容要具体且准确，基于项目的实际代码和配置，不要使用空洞的模板化语言
• 使用项目实际的命令、路径、依赖名称
• 保持文档语言与用户在第三步确认的语言一致
• 文件之间的交叉引用要保持一致（如 README 中引用 LICENSE、CONTRIBUTING 等）
• 如果用户已有部分文件，不要覆盖，而是提示用户可以参考生成的版本进行改进

第五步：生成总结报告

生成所有文件后，向用户输出一份总结报告，包括：

• 创建了哪些文件及其路径
• 每个文件的简要说明
• 建议后续手动补充的内容（如需要用户提供的特定信息）
• 未创建但可能需要的文件及原因

文档类型目录

以下按优先级分类列出所有可能需要的文档文件。详细的内容指南请阅读 references/file-types-guide.md。

第一类：必需文件 (Required)

第二类：强烈推荐 (Strongly Recommended)

第三类：GitHub 社区健康文件 (Recommended)

第四类：配置类文件 (Configuration)

第五类：特定场景文件 (Special Scenarios)

决策矩阵

以下矩阵帮助 Agent 在第二步生成分级推荐方案。注意：这只是内部参考，最终创建哪些文件由用户在第三步决定。

分级推荐方案设计指南

在为用户准备推荐方案时，遵循以下分级原则：

方案一（全套文档） 应包含：

• 所有必需文件 + 所有强烈推荐文件 + 所有适用的社区健康文件 + 所有适用的配置文件 + 项目特征匹配的场景文件

方案二（标准文档） 应包含：

• 所有必需文件 + 强烈推荐文件中的 2-3 个 + 1-2 个最相关的配置文件

方案三（基础文档） 应包含：

• 所有必需文件（README + LICENSE + .gitignore）

方案四（最小文档） 应包含：

• 仅 README.md

设计方案时的注意事项：

• 每个方案都应包含 README.md，这是不可省略的
• 如果项目已有某些文件，在方案中标注"已有"
• 场景文件（如 CITATION.cff、Dockerfile）只在项目特征匹配时才加入方案一
• 不要在方案三/四中放入场景文件，保持精简

项目特征 → 推荐文档

技术栈 → .gitignore 模板

许可证选择指南

当用户未指定许可证时，在第三步向用户展示上述选项并询问。默认推荐 MIT（通用）或 Apache-2.0（企业级）。

内容生成要点

生成文档时，遵循以下原则确保质量：

README.md 生成要点

README 是最重要的文档。一个优秀的 README 应该让用户在 30 秒内理解"这是什么、能做什么、怎么用"。

必须包含的章节：

1. 项目标题 + 一句话描述 — 可选配 Badge（CI 状态、版本号、许可证）
2. 项目简介 — 解决什么问题，核心价值
3. 功能特性 — 列出关键功能点
4. 安装方式 — 具体命令（npm install、pip install、go get 等）
5. 快速开始 — 最小可用示例代码
6. 使用文档 — 或链接到详细文档
7. 配置说明 — 环境变量、配置文件等（如有）
8. 开发指南 — 链接到 CONTRIBUTING.md
9. 许可证 — 声明许可证并链接到 LICENSE 文件

可选章节（根据项目情况添加）：

• 项目截图/GIF 演示
• 架构图
• 常见问题（或链接到 FAQ.md）
• 贡献者列表
• 致谢
• 更新日志链接

其他文件生成要点

详细的每种文件内容指南，请阅读 references/file-types-guide.md。该文件包含：

• 每种文件的完整内容结构
• 模板和示例
• 最佳实践建议
• 常见错误避免

质量检查清单

生成文档后，逐项检查：

• README 是否能在 30 秒内让读者理解项目用途
• LICENSE 文件是否包含完整的许可证文本（不是仅有名称）
• LICENSE 文件的类型是否与用户在第三步确认的一致
• .gitignore 是否覆盖了项目技术栈的常见忽略项
• 所有文档中的命令和路径是否与项目实际一致
• 文档之间的交叉链接是否正确
• 是否有占位符未填充（如 TODO: 补充描述）
• 代码示例是否可运行
• 文档语言是否与用户在第三步确认的一致
• Markdown 格式是否正确（标题层级、代码块语言标注等）
• 用户已有的文件是否未被覆盖

输出格式

最终向用户呈现：

1. 项目分析摘要（第三步）：简明的项目特征总结
2. 分级推荐方案（第三步）：3-4 个方案供用户选择
3. 需要确认的问题（第三步）：许可证类型、文档语言等
4. 生成的文件（第四步）：每个文件的实际内容
5. 总结报告（第五步）：创建了哪些文件、建议补充的内容、未创建的文件及原因