Repowiki Generator

repowiki-generator

为任意项目生成结构与风格参考 popdf repowiki 的仓库知识库，输出到目标项目自身的 wiki/<lang>/ 目录下。

适用场景

• 用户希望为当前项目生成一份完整的、可被 AI Agent 理解的"仓库 Wiki"
• 用户希望以 popdf repowiki 作为参考模板输出结构化文档
• 用户希望文档中包含 mermaid 架构图、<cite> 引用块、章节来源标注
• 用户希望覆盖：项目概述、快速入门、安装指南、命令行使用、核心功能详解、API 参考、开发者指南
• 用户希望产物可直接放入 wiki/zh/content/，并附带 repowiki-metadata.json

不适用场景

• 用户只想要单个 README —— 直接用项目自身 README 即可，不必引入 repowiki
• 用户希望生成博客、公众号文章或其他非 Wiki 形态内容 —— 使用 cover-hero / notion-infographic 等其他 skill
• 目标项目无法访问（远程 GitHub 仓库未克隆到本地）—— 需要先 clone 后再处理

工作流程

阶段 0：读取参考与定位目标

1. 读取参考规范：先打开 references/format-spec.md 与 references/doc-templates.md，确认 repowiki 的目录结构、Markdown 语法、引用格式、mermaid 模式。

2. 确认目标项目根目录：从用户输入中解析目标项目路径。默认参数 project_root = 用户当前工作目录或会话上下文中提到的项目根目录；如果用户未指定，向用户询问一次。

3. 确认语言（必须询问用户一次）：默认只生成中文 zh。在开始撰写前，向用户提问一次，确定生成范围：

   文档语言你想怎么生成？
   1. ⭐ 只生成中文（默认）        → 产出 wiki/zh/
   2. 中文 + 英文都生成（同步双语）  → 产出 wiki/zh/ + wiki/en/
   3. 只生成英文                  → 产出 wiki/en/
   

   用户选择	lang 取值	输出目录
   1（默认 / 未回答）	zh	wiki/zh/
   2（双语）	zh + en	wiki/zh/ 与 wiki/en/
   3（只英文）	en	wiki/en/

   双语模式下，先完整生成中文版，再据此翻译出英文版；英文版的 <cite> 引用路径、行号、mermaid 结构与中文版保持一致，仅正文文案翻译。技术名词、代码标识符、文件名、API 名称在两种语言下都保持原样。

阶段 1：扫描目标项目

按 references/analysis-checklist.md 提供的清单逐项扫描项目。可调用 scripts/analyze_project.py 辅助扫描，但所有内容必须人工核对，不允许脚本结果直接写入最终文档。

扫描维度：

阶段 2：设计文档结构

根据扫描结果，对照 references/output-structure.md 设计本文档的具体产出：

• 顶层文档：项目概述.md、快速入门.md、安装指南.md、命令行使用.md、GUI使用指南.md（如适用）、Web界面使用.md（如适用）、批量处理.md（如适用）
• 核心功能详解/：按功能大类分子目录（如 PDF转换/、用户管理/、订单系统/）
• API参考/：按 API 大类分子目录
• 开发者指南/：分层说明、代码结构、测试策略、贡献指南
• 元数据：meta/repowiki-metadata.json

注意：并非每个项目都需要全部顶层文档——按项目实际功能裁剪。例如纯 CLI 工具不需要 GUI/Web 文档；纯前端项目不需要命令行文档。

阶段 3：按模板撰写文档

每个 .md 文件必须遵循 references/doc-templates.md 中的标准模板：

1. H1 标题：文档名
2. <cite> 块：列出本文引用的所有源文件（带 file:// 路径）
3. 目录：H2 标题 + 有序列表（带锚点链接）
4. 简介：H2 标题，一段或两段说明
5. 章节正文：按模板指定的章节展开
6. 章节末尾：标注 **Section sources** / **章节来源** / **图表来源**，引用相关源文件路径与行号

图表规则：每个 mermaid 图后必须紧跟一段引用块，列出图表对应的源文件路径。

引用规则：所有引用文件必须使用 [name](file://path/to/file) 或 [name](file://path/to/file#L1-L100) 格式，行号仅在确知时使用。

阶段 4：生成元数据

调用 scripts/generate_metadata.py，或在文档撰写完毕后手工编写 meta/repowiki-metadata.json，格式参考 references/format-spec.md 第 5 节。

阶段 5：写入与校验

1. 在目标项目的 wiki/<lang>/ 下创建完整目录结构
2. 写入所有 .md 文档与 meta/repowiki-metadata.json
3. 校验清单：
   • 每个文档都有 <cite> 引用块
   • 每个文档都有目录
   • 每个 mermaid 图都有 **图表来源** 块
   • 每个章节末尾都有 **章节来源** 或等价块
   • 所有 file:// 路径真实存在
   • 行号范围（如有）与文件实际行数一致
   • repowiki-metadata.json 是合法 JSON 且 code_snippets 数组非空
   • 中英文标点、空格符合中文排版习惯

关键参考

• 格式规范详解：references/format-spec.md
• 文档结构模板：references/doc-templates.md
• mermaid 图表模式：references/mermaid-patterns.md
• 项目扫描清单：references/analysis-checklist.md
• 输出目录结构：references/output-structure.md
• 辅助脚本：
  • scripts/analyze_project.py —— 扫描项目结构
  • scripts/generate_metadata.py —— 生成元数据 JSON

风格与质量要求

• 语言：默认中文（与 popdf 一致）。技术名词、代码标识符、文件名、API 名称保持原样不翻译。
• 图表：每个核心概念必须有至少一个 mermaid 图。<mermaid> 块使用 graph TB / graph LR / classDiagram / sequenceDiagram / flowchart TD / stateDiagram-v2 等常用类型，按内容选择。
• 不省略细节：模块名、类名、方法名必须精确写出，与代码保持一致；行号引用必须可验证。
• 不杜撰：没有的源码文件不要写进 <cite>；没有的功能不要写入文档。
• 中英文混排：中文文案中夹英文文件名/类名/方法名时，前后保留一个空格。

输入参数

调用此 skill 时，Agent 应从用户消息中识别以下参数：

如果用户没有明确 modules / api_groups，按扫描结果智能分组，并在最终回复中列出推断结果，请用户确认或修正。

输出示例

调用完成后，应当在目标项目根目录下生成如下结构（以 Python 库项目为例）：

<project_root>/wiki/zh/
├── meta/
│   └── repowiki-metadata.json
└── content/
    ├── 项目概述.md
    ├── 快速入门.md
    ├── 安装指南.md
    ├── 命令行使用.md
    ├── 批量处理.md
    ├── 核心功能详解/
    │   ├── 核心功能详解.md
    │   └── <模块A>/<功能1>.md ...
    ├── API参考/
    │   ├── API参考.md
    │   └── <API组A>/...md ...
    └── 开发者指南/
        ├── 开发者指南.md
        ├── 代码结构说明.md
        ├── 测试策略与实践.md
        └── 贡献代码指南.md

完成后，回复用户：

1. 生成的文档清单
2. repowiki-metadata.json 中包含的代码片段数量
3. 待用户确认的关键假设（如模块划分、API 分组）
4. 已知信息缺口（用户可补全的细节）

注意事项

• 行号必须真实存在：使用 L1-L100 格式时，确保目标文件至少有 100 行；否则改为 L1-L<实际行数> 或省略行号。
• 不要复制 popdf 内容：模板与格式可以复用，但所有内容必须基于目标项目实际代码生成，不允许复读 popdf 的具体业务描述。
• 不创建冗余文档：项目没有 GUI 就不要写 GUI使用指南.md；项目没有 Web 前端就不要写 Web界面使用.md；项目没有 CLI 入口就不要写 命令行使用.md。
• 不修改项目源代码：本 skill 只在 wiki/ 目录下创建文件，绝不允许触碰源代码。
• 保持中立语气：客观描述架构与功能，不写营销文案或主观评价。