haizei-project-wiki-generator

Imported from wuchubuzai2018/expert-skills-hub (skills/haizei-project-wiki-generator/SKILL.md). Install upstream with npx skills add wuchubuzai2018/expert-skills-hub --skill haizei-project-wiki-generator. Copyright stays with the author.

Project Wiki Generator

深度分析项目代码，生成系统性的技术 Wiki 与业务 Wiki，以 VitePress 文档站交付。

技能定位

这是一个代码分析驱动的 wiki 生成技能，核心价值是：

1. 深度阅读项目源码，追踪调用链、识别模块边界、提取业务规则
2. 产出结构化的技术分析文档（01-07 系列）和业务域文档
3. 每篇文档由独立子代理生成，确保分析深度和质量
4. 以 VitePress 文档站作为交付格式，支持本地预览和团队共享

工作原则

• 分析为主线：先深度理解代码，再产出文档。不是先搭站点再填内容。
• 事实为基：严格只写能从代码/配置/已有文档中确认的内容。推断项标为"待确认"。
• 来源可追溯：每个关键结论绑定至少一个代码来源（类、方法、配置、表）。
• 用户确认门控：目录规划必须经用户确认后才开始生成正文。
• 子代理保质量：每篇文档由独立子代理生成，避免上下文稀释导致质量下降。
• 增量优先：已有文档优先局部补写，不默认整篇重写。

参考文件路由表

Phase 1: 范围确定与环境初始化

1.1 识别用户意图

必须先判断用户属于哪种诉求：

1. 首次生成：项目没有 wiki，需要完整流程（分析 → 规划 → 确认 → 生成）
2. 继续生成：已有部分 wiki，用户说"继续生成 wiki / tech wiki / biz wiki"
3. 增量刷新：已有文档需要补章节、修正、刷新导航
4. 质量检查：用户要求检查当前 wiki 质量

1.2 确定分析目标

• 默认分析当前工作目录
• 如果用户指定了路径（如"分析 D:/projects/my-app"），使用指定路径
• 输出始终在当前工作目录的 docs/

1.3 智能初始化 VitePress

检查 docs/ 是否存在：

• 不存在 → 运行 node scripts/init-vitepress.mjs <project-root> 初始化
• 存在但无 .vitepress/config.mts → 补充 VitePress 配置
• 存在且有配置 → 检查是否为本技能管理（含 // project-wiki-generator managed config 注释），准备增量更新

输出提示：[Phase 1 完成] 模式：<首次生成|继续生成|增量刷新>，分析目标：<路径>

Phase 2: 深度项目分析

这是技能的核心 — 由 Claude 自身执行深度代码分析。

2.1 分析动作清单

按以下顺序执行分析（使用 Glob、Grep、Read 等工具）：

1. 技术栈识别：构建工具、框架、语言、依赖管理
2. 入口点识别：启动类、Controller、Job、消息入口、外部回调
3. 模块划分：目录结构、包职责、模块边界
4. 核心类与继承关系：抽象类/接口的关键实现（至少展开 1-3 个）
5. 调用链追踪：主链路方法追踪 3 层深度，标注关键分支和状态变化
6. 数据模型：实体类、数据库表、字段含义、对象关系
7. 外部依赖：第三方服务、中间件、消息队列、缓存
8. 业务规则提取：if/switch 条件分支、状态机、配置开关
9. 业务域识别：从模块职责和业务流程中识别业务域边界

2.2 分析范围控制

• 优先分析用户显式指定的模块/流程
• 优先覆盖主链路方法、状态更新、条件分支、外部调用
• 若项目过大，先产出核心模块分析，标注待补范围
• 对未在代码中直接出现、仅能由命名推断的结论，标为"待确认"

2.3 输出分析结果

将分析结果写入 docs/wiki/.wiki-state/analysis.json：

{
  "projectName": "string",
  "projectRoot": "string",
  "analyzedAt": "ISO timestamp",
  "techStack": ["java", "spring-boot", "mybatis"],
  "entryPoints": [{"type": "controller", "path": "src/...", "description": "..."}],
  "modules": [{"name": "...", "path": "...", "responsibility": "...", "fileCount": 0}],
  "domains": [{"name": "...", "relatedModules": [...], "description": "..."}],
  "stats": {"codeFileCount": 0, "moduleCount": 0, "domainCount": 0}
}

输出提示：[Phase 2 完成] 已识别 N 个模块、M 个业务域，分析结果已写入 analysis.json

Phase 3: Wiki 目录规划与用户确认

这是门控步骤 — 必须经用户确认后才进入生成阶段。

3.1 生成目录规划

基于分析结果，规划完整的 wiki 目录：

新人指南（5 个分类，共 12 篇）：

基础篇（base/）：

• 01_快速上手 — 30 分钟建立项目第一印象
• 02_阅读指南与接手路线图 — 按角色/目标的阅读路径
• 03_接手维护关键入口清单 — 按问题类型定位入口

环境篇（setup/）：

• 01_本地环境搭建 — 从零把项目跑起来
• 02_联调与测试环境 — 环境清单、Mock、测试命令

代码篇（codebase/）：

• 01_代码导航地图 — 按功能/页面/数据流定位代码
• 02_核心链路速查 — 用户操作 → 完整调用路径
• 03_调试排查技巧 — 日志、断点、SQL 排查

实战篇（practice/）：

• 01_第一个改动怎么做 — 从接需求到提交的完整步骤
• 02_常见修改场景指南 — 新增接口/字段/规则等场景
• 03_提测与上线注意事项 — checklist 和回滚方案

FAQ（faq/）：

• index — 从其他文档聚合的常见问题

技术 Wiki（固定 01-07 系列）：

• 每篇文档标注将覆盖哪些模块、分析哪些内容
• 给出 2-3 句话的内容摘要

业务 Wiki（按域组织）：

• 列出识别到的业务域
• 每个域下规划 01-05 系列文档
• 标注每个域关联的模块

3.2 向用户展示规划

必须以清晰的格式向用户展示：

## Wiki 目录规划

### 新人指南（12 篇）

#### 入门概览（base/）
1. 01_快速上手 — 项目做什么、技术栈、主业务主线、第一小时阅读顺序
2. 02_阅读指南与接手路线图 — 按角色/目标推荐不同阅读路径
3. 03_接手维护关键入口清单 — 按问题类型定位代码入口

#### 环境搭建（setup/）
4. 01_本地环境搭建 — 前置依赖、启动命令、配置说明、常见报错
5. 02_联调与测试环境 — 环境清单、Mock 方式、测试命令

#### 代码导航（codebase/）
6. 01_代码导航地图 — 按功能/页面/数据流找代码
7. 02_核心链路速查 — 用户操作 → 完整调用路径（卡片式）
8. 03_调试排查技巧 — 日志、断点、SQL 排查路径

#### 实战上手（practice/）
9. 01_第一个改动怎么做 — 典型改动示例、修改 checklist、自测方法
10. 02_常见修改场景指南 — 新增接口/字段/规则/定时任务等场景
11. 03_提测与上线注意事项 — 提测 checklist、SQL 规范、回滚方案

#### 常见问题（faq/）
12. FAQ — 从其他文档聚合的非显而易见知识点

### 技术知识（7 篇）
1. 01_系统架构分析 — 覆盖模块 A、B、C，分析系统分层与调用链
2. 02_专业术语词汇表 — 提取项目中的领域术语与代码命名规范
...

### 业务知识
#### 用户管理域（5 篇）
- 关联模块：user-service, auth-module
- 01_业务目标与范围 — 用户注册、认证、权限的业务边界
...

#### 订单域（5 篇）
...

### 本轮生成范围
建议按阶段分批生成：
- 第一批：base/ 全部 + tech-01 + tech-06（新人第一天需要的基本认知）
- 第二批：setup/ 全部 + codebase/01（有了环境才能看代码）
- 第三批：codebase/02-03 + practice/01（能调试后开始实战）
- 第四批：practice/02-03 + faq/（前面文档都有了才能写好场景指南）

请确认：
1. 域划分是否合理？
2. 命名是否需要调整？
3. 本轮先生成哪些？

3.3 等待用户确认

• 用户确认后，将最终规划写入 docs/wiki/.wiki-state/plan.json
• 如果用户要求调整，修改规划后重新展示
• 禁止跳过确认直接生成

输出提示：[Phase 3 完成] 目录规划已确认，准备生成 N 篇文档

Phase 4: 子代理批量生成文档

4.1 子代理调度策略

对 plan 中每篇确认的文档，启动独立子代理（Agent 工具）：

构造子代理 prompt 的规则：

1. 读取 references/agent-prompts.md 中的"通用前缀"全文
2. 将 {通用前缀} 占位符完整展开为通用前缀的实际内容（不是引用，是内联展开）
3. 替换所有变量：{projectName}、{projectRoot}、{targetPath}、{relatedModules}、{scope}、{audience}、{date}
4. 拼接对应文档类型的模板（tech-01 到 tech-07，guide-base-01 到 guide-base-03，guide-setup/codebase/practice/faq 模板，或 biz 域模板）
5. 在 prompt 末尾附加 references/known-gotchas.md 的完整内容（已知陷阱清单）
6. 最终发送给子代理的 prompt 必须是一个完整的、自包含的指令，不含任何未展开的占位符

禁止只传递 {通用前缀} 文本给子代理 — 子代理看不到 references 文件，必须把完整约束内联到 prompt 中。

4.2 并行策略

• 无依赖关系的文档可并行生成（同一消息中发送多个 Agent 调用）
• 建议每批 2-3 个子代理并行
• tech-wiki 的 01（架构）建议最先生成，因为后续文档可能引用它

4.3 子代理质量要求

不要向子代理强加统一的固定章节骨架，文档结构应由对应文档类型、代码材料密度和读者目标决定。

4.4 文档开头格式

每篇文档开头必须声明：

> **分析范围**：<所属域/文档类型> | **适用对象**：<目标读者> | **生成日期**：<YYYY-MM-DD>

4.5 信息状态标签

技术 Wiki 必须区分：

• 代码事实 — 可从代码/配置直接验证
• 文档口径 — 现有文档中的描述（可能与代码不一致）
• 待确认 — 无法确认的内容
• 风险提示 — 已知风险或潜在问题

业务 Wiki 必须区分：

• 业务目标 — 系统或功能的业务目的
• 主流程 — 核心业务链路
• 参与角色 — 涉及的用户/系统角色
• 规则 — 业务规则或决策条件
• 异常 — 失败路径、补偿逻辑、边界情况
• 待确认 — 无法确认的内容

输出提示：[Phase 4 进行中] 正在生成第 N 批文档（共 M 篇）...

Phase 5: 组装与质量检查

5.1 更新 VitePress 配置

运行：

node scripts/build-vitepress-config.mjs <docs-root>

自动扫描 docs/wiki/ 下所有 md 文件，生成侧边栏和导航配置。

5.2 更新首页

根据实际生成的文档，更新 docs/index.md 的 features 区块，确保链接指向真实存在的页面。

5.3 质量检查与自纠正

运行：

node scripts/check-wiki-quality.mjs <docs-root>

检查每篇文档的：行数、章节数、图表数、来源索引、交叉链接。

自纠正逻辑：

1. 对评级为 "weak" 的文档，识别具体缺失项（缺来源索引？缺图表？行数不足？缺分析范围声明？）
2. 启动修补子代理，只补缺失区块（不重写全文），prompt 中明确指出缺什么
3. 修补后重新检查，最多重试 1 次
4. 仍为 "weak" 的文档标记为"需人工审查"，在报告中告知用户

5.4 更新进度

运行：

node scripts/progress-manager.mjs complete <docs-root> <doc-id>

5.5 向用户报告

必须使用结构化格式报告：

## 本批完成

| 文档 | 质量 | 行数 | 图表 | 来源索引 |
|------|------|------|------|----------|
| 01_系统架构分析 | ✅ strong | 156 | 3 | 8 条 |
| 06_模块结构分析 | ⚠️ acceptable | 67 | 1 | 3 条 |

## 剩余待生成

- tech: 02-05, 07
- biz: 域"订单管理"全部
- guide: 02, 03（依赖前面文档完成后再生成）

## 下一步

说"继续生成 wiki"生成下一批，或指定"生成 tech 02"单独生成某篇。

输出提示：[Phase 5 完成] 本批 N 篇文档已生成，质量评级：X strong / Y acceptable / Z weak

增量维护规则

• 若目标文件已存在，必须优先增量修订，不重写无关章节
• 修改前必须参考 references/edit-checklist.md
• 保留现有编号体系与标题风格
• 不因补充某一模块文档而重排其他模块结构
• 新增章节必须与现有目录层级兼容
• 若现有页面主体结构合理，只补缺失区块

常见用户表达与响应方式

"生成项目 wiki" / "分析这个项目生成文档"

执行完整流程：Phase 1 → 2 → 3（等待确认）→ 4 → 5

"继续生成 wiki" / "继续生成 tech wiki" / "继续生成 biz wiki"

1. 读取 progress.json，找到下一批待生成文档
2. 执行 Phase 4 → 5
3. 禁止重复生成已完成的文档

"分析 <路径> 生成 wiki"

将 <路径> 作为分析目标，输出仍在当前目录 docs/

"检查 wiki 质量"

直接运行质量检查脚本，报告结果

"刷新 VitePress 配置" / "更新侧边栏"

直接运行 build-vitepress-config.mjs

"补充 <文档名> 的 <章节>"

进入增量修订模式，参考 edit-checklist.md

禁止行为

• ❌ 跳过 Phase 3 用户确认直接生成文档
• ❌ 在未读代码的情况下编造系统行为或业务规则
• ❌ 把推断当作确认事实，未验证项必须标为"待确认"
• ❌ 生成空骨架页或只有标题没有正文的文档
• ❌ 篡改类名、方法名、字段名等固定标识符
• ❌ 在增量修订时重写无关章节
• ❌ 生成的文档缺少来源索引区块