我把「晚枫知识库」Skill 发布到 SkillHub 了：让 AI 读懂项目，生成整套 Wiki

一个项目只有 README，新成员往往还是不知道从哪里开始看：怎么安装、入口在哪里、核心模块如何协作、二次开发应该改哪个文件。
我把「晚枫知识库」Skill 发布到 SkillHub 了。它会扫描并阅读本地代码项目，按项目的真实功能生成一整套结构化 Wiki，并附上 Mermaid 图、源码引用和元数据。

SkillHub 发布页：晚枫知识库

GitHub 源码：repowiki-generator

大家好，我是程序员晚枫。

维护项目的时间越长，我越能体会到一件事：代码写完后，文档才是真正长期使用它的入口。

但很多项目的文档现状是：README 里只有一段简介和几条安装命令，配置说明散落在源码里，模块关系要靠猜，核心流程要翻很多文件才能看明白。

新人接手项目时，常问的不是某个函数怎么写，而是：

这个项目到底能解决什么问题？
我应该先安装什么、运行哪条命令？
CLI、GUI 或 Web 入口分别在哪里？
核心模块之间是什么关系？
想修改一个功能，应该去看哪个文件？

这些问题，单靠一份 README 很难完整回答。

所以我做了一个「晚枫知识库」Skill：让 AI 阅读本地项目，把分散在代码、配置和入口文件里的信息，整理成一套能阅读、能追溯来源的仓库 Wiki。

一、它不是再写一份 README，而是生成一整套 Wiki

这个 Skill 的默认输出目录位于目标项目内部：

<project_root>/.wanfeng-wiki/<lang>/
├── meta/
│   └── repowiki-metadata.json
└── content/
    ├── 项目概述.md
    ├── 快速入门.md
    ├── 安装指南.md
    └── 其他按项目实际情况生成的文档

其中，content/ 保存可以直接阅读的 Markdown 文档，meta/ 保存从文档引用中提取出来的代码片段元数据。

根据项目的实际能力，文档可以覆盖：

文档方向	主要回答的问题
项目概述	项目做什么，适合谁，整体结构是什么
快速入门	第一次运行项目，最短路径是什么
安装指南	依赖、环境、配置和安装步骤是什么
命令行使用	有哪些命令、参数和典型用法
GUI / Web 使用	图形界面或 Web 页面怎么操作
批量处理	是否支持批量任务，输入输出如何组织
核心功能详解	关键模块如何协作，主要流程怎么走
API 参考	对外接口、类、方法和参数是什么
开发者指南	如何理解目录、修改代码、运行测试和参与开发

这里很重要的一点是：它不是把固定模板机械地复制到每个项目里。

纯命令行项目，不会凭空多出 GUI 和 Web 使用文档；纯前端项目，也不会为了凑目录硬写一套命令行说明。文档页面应该跟着项目的真实能力走，而不是让代码迁就模板。

二、从项目扫描到文档校验，完整流程是什么？

这个 Skill 的工作可以分成 6 步。

第 1 步：确认项目根目录和文档语言

它先弄清楚要为哪个本地项目生成文档，以及你需要中文、英文，还是中英双语。

项目必须已经克隆或保存在本地，AI 能访问到源码，才能继续后面的阅读和核对。

第 2 步：扫描项目结构和关键线索

Skill 会查看目录、依赖配置、入口文件、测试、部署文件和主要源码，辅助判断项目类型、技术栈和已有能力。

仓库里还提供了一个 analyze_project.py 脚本，可以输出 JSON 扫描报告，帮助整理项目名、候选模块、入口、源码数量和 API 分组等线索。

但请注意：扫描报告只是线索，不是最终文档。

第 3 步：由 Agent 阅读源码并核对事实

真正写文档之前，Agent 还要继续阅读相关代码，核对模块名、类名、方法名、API、配置项和调用关系。

也就是说，这个 Skill 不是运行一个脚本，就把扫描结果改写成几十篇看似完整的文章。扫描负责减少遗漏，阅读源码负责弄清楚事实，两者不能相互替代。

第 4 步：按项目实际功能规划页面

确认项目具备哪些能力后，再决定生成哪些文档。

如果项目根目录已经存在 .wanfeng-wiki/wiki_plan.yaml，Skill 还会遵循其中的扫描范围和页面计划：scope.include、scope.exclude 用来控制范围，repowiki.notes 提供需要优先核对的说明，repowiki.documents 则限定允许规划的页面。

这样既可以使用默认流程，也给有明确文档计划的团队留下了控制入口。

第 5 步：撰写 Markdown、Mermaid 和源码引用

文档不是只有大段文字。对于项目结构、核心流程和模块关系，可以使用 Mermaid 图辅助理解；对于关键结论，则通过引用块标明对应的源码位置。

写完后，读者不仅能看到“这个项目是这样工作的”，还能继续回到源代码，确认这个结论从哪里来。

第 6 步：生成元数据并检查结果

最后，Skill 会检查输出目录、引用路径、行号、Mermaid 排版和元数据。

generate_metadata.py 会扫描文档中的 <cite> 引用块，提取 file:// 路径及行号范围，去重后生成 code_snippets。正常情况下，这些片段应来自文章中的真实引用，而不是另外编造一份代码清单。

三、为什么我特别强调“源码出处”？

AI 写项目文档，最容易出现的问题不是语句不通顺，而是看起来很完整，实际上混入了项目中不存在的东西。

比如，多写一个并不存在的命令，给模块起一个源码里没有的名字，或者把候选能力误写成已经实现的功能。

所以我在这个 Skill 里加了几条明确约束：

文件路径必须真实存在。
模块、类、方法和 API 名称以代码为准。
只有确知行号时才填写，并应与源文件保持一致。
Mermaid 图后需要注明图表来源。
章节中的关键内容需要有对应出处。
不存在的文件、接口和功能，不能为了让文档好看而补上。

这些要求不会让文档变得花哨，但会让它更可靠。

好的项目 Wiki，不只是“读起来像真的”，而是能够回到代码里验证。

四、支持中文、英文和中英双语

默认情况下，可以为项目生成中文文档，输出到 .wanfeng-wiki/zh/；需要英文时，可以使用 en；如果项目同时面向中英文读者，也可以生成两套内容。

开始撰写前，Skill 会先确认一次语言，避免写完后才发现方向不对。

双语模式下，两套文档会保持一致的源码引用路径、行号和 Mermaid 结构，主要翻译正文说明。这样后续核对时，不需要在两套完全不同的文档结构之间来回切换。

五、怎么安装和使用？

方式一：从 SkillHub 安装

打开发布页：

https://skillhub.cn/skills/user_bf8c5b73/wanfeng-repowiki-generator

在支持 Skill 安装的 AI 工具里，可以发送：

1	请根据 https://skillhub.cn/install/skillhub.md，安装 @user_bf8c5b73/wanfeng-repowiki-generator。

安装完成后，可以直接这样调用：

使用晚枫知识库 Skill，为当前本地项目生成中文 Wiki。
项目根目录是 /path/to/your/project。
请先扫描并阅读源码，再根据项目的真实功能规划文档。
我需要项目概述、快速入门、安装指南、核心功能详解和开发者指南。
如果项目只有命令行功能，不要生成 GUI 或 Web 文档。
输出到项目根目录下的 .wanfeng-wiki/zh/。
完成后请检查源码引用、行号、Mermaid 图和元数据。

把 /path/to/your/project 换成你自己的项目路径即可。

如果你暂时不确定需要哪些页面，也可以只说“为这个本地项目生成中文 Wiki”，让 Skill 先根据实际代码规划，再由你确认。