| name | haizei-project-wiki-generator |
| description | 生成项目 Wiki技能、技术 Wiki、业务 Wiki生成技能。用户提到"生成 wiki"、继续生成 wiki""刷新 wiki""补齐 docs 文档结构"时务必使用。适用于深度分析用户指定的项目或模块，先规划系统性 wiki 目录、经用户确认后再通过子代理逐篇生成高质量技术与业务文档。不适用于：纯 API 文档生成（用 TypeDoc/Swagger）、README 编写、代码注释生成、非代码项目的文档、已有完善文档只需格式转换的场景。 |
Project Wiki Generator
深度分析项目代码，生成系统性的技术 Wiki 与业务 Wiki，以 VitePress 文档站交付。
技能定位
这是一个代码分析驱动的 wiki 生成技能，核心价值是：
- 深度阅读项目源码，追踪调用链、识别模块边界、提取业务规则
- 产出结构化的技术分析文档（01-07 系列）和业务域文档
- 每篇文档由独立子代理生成，确保分析深度和质量
- 以 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 识别用户意图
必须先判断用户属于哪种诉求：
- 首次生成：项目没有 wiki，需要完整流程（分析 → 规划 → 确认 → 生成）
- 继续生成：已有部分 wiki，用户说"继续生成 wiki / tech wiki / biz wiki"
- 增量刷新：已有文档需要补章节、修正、刷新导航
- 质量检查：用户要求检查当前 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 等工具）：
- 技术栈识别：构建工具、框架、语言、依赖管理
- 入口点识别：启动类、Controller、Job、消息入口、外部回调
- 模块划分：目录结构、包职责、模块边界
- 核心类与继承关系：抽象类/接口的关键实现（至少展开 1-3 个）
- 调用链追踪：主链路方法追踪 3 层深度，标注关键分支和状态变化
- 数据模型：实体类、数据库表、字段含义、对象关系
- 外部依赖：第三方服务、中间件、消息队列、缓存
- 业务规则提取：if/switch 条件分支、状态机、配置开关
- 业务域识别：从模块职责和业务流程中识别业务域边界
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":
...
输出提示：[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/）：
技术 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 的规则：
- 读取
references/agent-prompts.md 中的"通用前缀"全文
- 将
{通用前缀} 占位符完整展开为通用前缀的实际内容（不是引用，是内联展开）
- 替换所有变量：
{projectName}、{projectRoot}、{targetPath}、{relatedModules}、{scope}、{audience}、{date}
- 拼接对应文档类型的模板（tech-01 到 tech-07，guide-base-01 到 guide-base-03，guide-setup/codebase/practice/faq 模板，或 biz 域模板）
- 在 prompt 末尾附加
references/known-gotchas.md 的完整内容（已知陷阱清单）
- 最终发送给子代理的 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>
检查每篇文档的：行数、章节数、图表数、来源索引、交叉链接。
自纠正逻辑：
- 对评级为 "weak" 的文档，识别具体缺失项（缺来源索引？缺图表？行数不足？缺分析范围声明？）
- 启动修补子代理，只补缺失区块（不重写全文），prompt 中明确指出缺什么
- 修补后重新检查，最多重试 1 次
- 仍为 "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"
- 读取
progress.json，找到下一批待生成文档
- 执行 Phase 4 → 5
- 禁止重复生成已完成的文档
"分析 <路径> 生成 wiki"
将 <路径> 作为分析目标，输出仍在当前目录 docs/
"检查 wiki 质量"
直接运行质量检查脚本，报告结果
"刷新 VitePress 配置" / "更新侧边栏"
直接运行 build-vitepress-config.mjs
"补充 <文档名> 的 <章节>"
进入增量修订模式，参考 edit-checklist.md
禁止行为
- ❌ 跳过 Phase 3 用户确认直接生成文档
- ❌ 在未读代码的情况下编造系统行为或业务规则
- ❌ 把推断当作确认事实，未验证项必须标为"待确认"
- ❌ 生成空骨架页或只有标题没有正文的文档
- ❌ 篡改类名、方法名、字段名等固定标识符
- ❌ 在增量修订时重写无关章节
- ❌ 生成的文档缺少来源索引区块
