# Haizei Project Wiki Generator

> 生成项目 Wiki技能、技术 Wiki、业务 Wiki生成技能。用户提到"生成 wiki"、继续生成 wiki""刷新 wiki""补齐 docs 文档结构"时务必使用。适用于深度分析用户指定的项目或模块，先规划系统性 wiki 目录、经用户确认后再通过子代理逐篇生成高质量技术与业务文档。不适用于：纯 API 文档生成（用 TypeDoc/Swagger）、README 编写、代码注释生成、非代码项目的文档、已有完善文档只需格式转换的场景。

- Skill: `wuchubuzai2018/haizei-project-wiki-generator` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add wuchubuzai2018/haizei-project-wiki-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wuchubuzai2018/haizei-project-wiki-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: wuchubuzai2018 (https://skillmd.com/u/wuchubuzai2018)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/wuchubuzai2018/haizei-project-wiki-generator

---


# Project Wiki Generator

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

## 技能定位

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

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

## 工作原则

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

## 参考文件路由表

| 文件 | 作用 | 调用时机 |
|------|------|----------|
| `references/tech-prompts.md` | 技术 Wiki 01-07 每篇的写作规则与必含区块 | Phase 4 生成技术文档时**必须**参考 |
| `references/biz-prompts.md` | 业务 Wiki 域文档的写作规则 | Phase 4 生成业务文档时**必须**参考 |
| `references/agent-prompts.md` | 子代理 prompt 模板（含通用前缀） | Phase 4 构造子代理指令时**必须**参考 |
| `references/vitepress-template.md` | VitePress 首页、config.mts 模板 | Phase 1 初始化时**必须**参考 |
| `references/output-structure.md` | 输出目录结构规范 | Phase 3 规划目录时**必须**参考 |
| `references/edit-checklist.md` | 增量修订检查清单 | 修改已有文档时**必须**参考 |
| `references/known-gotchas.md` | 已知陷阱与规避（❌/✅ 对比） | Phase 4 子代理 prompt 中**必须**附带 |

---

## 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`：

```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 文档开头格式

每篇文档开头**必须**声明：

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

### 4.5 信息状态标签

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

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

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

---

## Phase 5: 组装与质量检查

### 5.1 更新 VitePress 配置

运行：
```bash
node scripts/build-vitepress-config.mjs <docs-root>
```

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

### 5.2 更新首页

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

### 5.3 质量检查与自纠正

运行：
```bash
node scripts/check-wiki-quality.mjs <docs-root>
```

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

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

### 5.4 更新进度

运行：
```bash
node scripts/progress-manager.mjs complete <docs-root> <doc-id>
```

### 5.5 向用户报告

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

```markdown
## 本批完成

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