| name | init-project-docs |
| description | 当用户要求「初始化项目文档」「生成知识图谱」「分析项目能力」「生成项目文档」时触发。渐进式构建项目知识图谱：Phase 1 核心文档 → Phase 2 映射文档 → Phase 3 流程与术语 → Phase 4 模块深度文档。支持自动模式和人工确认模式。 |
项目知识图谱初始化
触发场景
用户说以下任意一种时，必须调用本 skill：
- 初始化项目文档 / 生成知识图谱
- 分析项目能力 / 分析项目架构
- 生成项目概要 / 架构分析
- 生成开发参考文档
- init project docs / analyze project / knowledge graph
核心理念：渐进式构建
知识图谱不是一次性生成的，而是分 4 个阶段逐步丰富。每个阶段的文档为下一阶段提供上下文。
| 阶段 | 生成内容 | 数据来源 | 默认模式 |
|---|
| Phase 1 | 项目概要 + 架构总览 + 架构约束 | 扫描代码结构 + 构建文件 | 自动 |
| Phase 2 | 模块地图 + 数据模型 + API 总表 + 前后端映射 | 扫描 Controller/Entity/Mapper | 自动 |
| Phase 3 | 业务流程 + 术语表 + 重构计划 + 变更记录 | AI 分析 + 人工确认 | 可选自动/确认 |
| Phase 4 | 模块深度文档 + 技能卡（Flutter/Vue/Spring Cloud） | 逐模块深度扫描 | 可选自动/确认 |
输出根目录（统一到用户目录知识库）
本 skill 生成的全部知识图谱文档默认写入用户目录知识库，不再写入项目 docs/，避免污染源项目仓库。 与 design-doc-required / bug-doc-required / business-logic-orientation 的默认输出根保持一致。
| 项 | 值 |
|---|
输出根 {KG_ROOT} | {USER_DOCUMENTS}/ai-docs/{project}/ |
| 与 design / bug / orientation 的关系 | 同一个 ai-docs/{project}/ 知识库下平级共存（design/、bug/、orientation/、work-log/ 等是兄弟目录） |
项目 docs/ | 不写入。知识图谱不再随项目仓库分发，避免污染源项目 |
下文所有路径中的 {KG_ROOT}/ 一律指 {USER_DOCUMENTS}/ai-docs/{project}/。知识图谱文档之间互相引用一律使用相对文件名（如 01_architecture_overview.md、modules/{module}.md），不写 docs/ 前缀，使整套文档与所在根解耦。
兼容历史项目： 若某项目此前已把知识图谱生成在 docs/，由用户自行迁移到 {KG_ROOT}/；本 skill 默认只读写 {KG_ROOT}/。
执行流程
flowchart TD
A([收到初始化指令]) --> B[探索项目目录结构]
B --> C[识别项目类型和技术栈]
C --> D{用户指定阶段?}
D -->|"指定了 Phase N"| E[执行指定阶段]
D -->|"未指定"| F[询问执行范围]
F --> G{"全量（Phase 1-4）\n还是仅核心（Phase 1-2）?"}
G -->|核心| H[执行 Phase 1 + 2]
G -->|全量| I[执行 Phase 1 → 2 → 3 → 4]
H --> J[输出文档清单]
I --> K{Phase 3-4 模式?}
K -->|自动| L[全自动生成]
K -->|确认| M[逐项展示内容等待确认]
L --> J
M --> J
Phase 1：核心文档（全自动）
扫描内容
- 读取
pom.xml / build.gradle / pubspec.yaml — 获取技术栈和依赖
- 探索项目目录结构 — 识别分层模式
- 读取 Controller 层 — 获取对外 API 清单
- 读取 Service 接口层（
I*.java，不读 impl）— 获取业务能力清单
- 读取 Component 层 — 获取可复用组件
- 读取 Configuration/Interceptor 层 — 获取横切关注点
生成文档
| 文档 | 路径 | 模板 |
|---|
| 项目概要 | {KG_ROOT}/00_project_overview.md | templates/00_project_overview.md |
| 架构总览 | {KG_ROOT}/01_architecture_overview.md | templates/01_architecture_overview.md |
| 架构约束 | {KG_ROOT}/08_constraints_and_rules.md | templates/08_constraints_and_rules.md |
项目概要（00）章节
参考 templates/00_project_overview.md：
- 项目定位 — 一句话描述服务职责
- 技术栈 — 语言、框架、中间件版本
- 主要业务模块 — 按业务域分组
- 关键业务链路 — 主链路概要（2-4 条）
- 全局技术约定 — API 格式、金额单位、时间格式
- 文档导航 — 指向其余 10 份文档的索引
架构总览（01）章节
参考 templates/01_architecture_overview.md：
- 项目分层结构 — 根据实际项目类型选择（Spring Boot / Flutter / Vue）
- 依赖方向 — 层间依赖规则
- 服务清单 — 微服务项目列出所有服务
- 跨端数据流向 — 数据在各层/服务间的流动
- 全局约定 — 统一规则
架构约束（08）章节
参考 templates/08_constraints_and_rules.md：
- 分层红线 — 绝对禁止的行为
- 依赖方向 — 不可反转的规则
- 命名规范 — 各类型的命名约定
- 数据类型约定 — 金额/时间/状态等
- 新增代码 Checklist — 提交前自检
Phase 2：映射文档（全自动）
扫描内容
- 读取 Entity/Model 层 — 获取核心领域模型和表结构
- 读取 Mapper/DAO 层 — 获取数据访问能力
- 读取 Controller 的端点注解 — 获取完整 API 清单
- 读取 Stream/Listener 层 — 获取异步事件处理
- （Flutter）读取 features/ 目录 + pages — 获取页面清单
生成文档
| 文档 | 路径 | 模板 |
|---|
| 模块地图 | {KG_ROOT}/02_module_map.md | templates/02_module_map.md |
| 数据模型 | {KG_ROOT}/04_data_model_map.md | templates/04_data_model_map.md |
| API 总表 | {KG_ROOT}/05_api_map.md | templates/05_api_map.md |
| 前后端映射 | {KG_ROOT}/06_frontend_backend_mapping.md | templates/06_frontend_backend_mapping.md |
开发参考手册
同时生成 {KG_ROOT}/development-reference.md（参考 development-reference-template.md），包含：
- 业务域全景 — 按域列出能力边界
- 新增需求决策指南 — 代码放哪层的决策表
- Controller 端点全表 — 完整端点清单
- Service 能力矩阵 — 核心 Service 依赖和职责
- Component 组件能力 — 可复用组件清单
- 数据模型与 Mapper — 核心表关系和查询规则
- 异步事件与消息流 — 消费者清单和事件场景
- 外部服务依赖 — Feign 客户端清单
- 横切关注点 — 分布式锁、审计、线程池等
- 常见开发场景速查 — 高频场景分步指南
注意：development-reference 需要深度分析，需读取 Service impl、Component 实现、Stream handler、Configuration 类的实际代码。
Phase 3：流程与术语（可选自动/确认）
此阶段的内容无法纯靠代码推断，默认需人工确认。用户可选择自动模式（AI 尽力推断，生成后用户审阅）。
生成文档
| 文档 | 路径 | 模板 | 说明 |
|---|
| 业务流程 | {KG_ROOT}/03_business_flow_map.md | templates/03_business_flow_map.md | 核心业务流程清单和概要 |
| 术语表 | {KG_ROOT}/07_glossary.md | templates/07_glossary.md | 业务术语定义 |
| 重构计划 | {KG_ROOT}/09_refactor_plan.md | templates/09_refactor_plan.md | 重构路线和进度跟踪 |
| 变更记录 | {KG_ROOT}/10_change_log.md | templates/10_change_log.md | ADR 风格变更记录 |
自动模式行为
- AI 从代码中推断业务流程（分析 Controller 调用链、Service 方法间调用）
- AI 从类名/方法名/注释中提取业务术语
- 重构计划基于 Phase 1 的架构约束分析生成建议
- 变更记录初始化为"知识图谱建立"一条
- 生成后提示用户审阅，标注"以下内容需要人工校验"
确认模式行为
- 逐份文档展示 AI 推断的内容
- 等待用户确认、修改或补充
- 用户确认后写入文件
Phase 4：模块深度文档（可选自动/确认）
前置条件
Phase 1-2 已完成（需要 {KG_ROOT}/02_module_map.md 中的模块清单）。
生成文档
模块文档
为 {KG_ROOT}/02_module_map.md 中的每个模块生成深度文档：
路径：{KG_ROOT}/modules/{module}.md
模板：templates/module_template.md
每份模块文档包含 10 节：
- 模块目标
- 用户入口
- 代码结构（关键文件路径和职责）
- 后端结构（服务名、端口、端点列表）
- 数据结构（表结构 + 状态机）
- 核心流程（关键业务流程步骤）
- 关键规则（规则 ID + 描述 + 实现位置）
- 依赖关系（依赖 / 被依赖）
- 常见问题
- 改动建议
技能卡（按项目类型按需生成）
| 项目类型 | 技能卡 | 路径 | 模板 |
|---|
| Flutter | Flutter 技能卡 | {KG_ROOT}/skills/flutter_skill.md | templates/flutter_skill.md |
| Vue | Vue 技能卡 | {KG_ROOT}/skills/vue_skill.md | templates/vue_skill.md |
| Spring Cloud/Boot | Spring Cloud 技能卡 | {KG_ROOT}/skills/springcloud_skill.md | templates/springcloud_skill.md |
技能卡包含：分层职责、命名规范、AI 代码生成规则、当前重构状态。
自动模式行为
- 逐模块扫描代码，自动填充 10 节内容
- 常见问题和改动建议基于 AI 分析生成
- 生成后提示用户审阅
确认模式行为
- 列出所有待生成的模块，用户选择要生成哪些
- 逐模块展示内容，等待确认
文档存储结构
生成完成后，用户目录知识库 {KG_ROOT}/（= {USER_DOCUMENTS}/ai-docs/{project}/）结构如下：
{KG_ROOT}/ ← {USER_DOCUMENTS}/ai-docs/{project}/
├── 00_project_overview.md ← AI 入口（Phase 1）
├── 01_architecture_overview.md ← 系统分层（Phase 1）
├── 02_module_map.md ← 模块一览（Phase 2）
├── 03_business_flow_map.md ← 业务流程（Phase 3）
├── 04_data_model_map.md ← 数据模型（Phase 2）
├── 05_api_map.md ← API 接口（Phase 2）
├── 06_frontend_backend_mapping.md ← 前后端映射（Phase 2）
├── 07_glossary.md ← 术语表（Phase 3）
├── 08_constraints_and_rules.md ← 架构红线（Phase 1）
├── 09_refactor_plan.md ← 重构计划（Phase 3）
├── 10_change_log.md ← 变更记录（Phase 3）
├── development-reference.md ← 开发参考（Phase 2）
│
├── skills/ ← 技能卡（Phase 4）
│ ├── flutter_skill.md
│ ├── vue_skill.md
│ └── springcloud_skill.md
│
└── modules/ ← 模块深度文档（Phase 4）
├── {module_a}.md
├── {module_b}.md
└── ...
Mermaid 语法强制规范
来源：team-standards Mermaid 规范
- 节点/边标签含
=、,、/、<、>、(、)、[、]、: 时必须加引号
< > 改用文字（如：大于、小于、请求体、响应体）- 不使用 emoji
classDiagram 方法名不含中文
文档质量标准
- AI 友好：每份文档开头有"快速索引"，让 AI 读一次就能定位关键信息
- 业务优先：先写业务能力和流程，后写技术细节
- 可维护：文档头部注明"基于代码自动分析生成，如有结构调整请运行 project-docs-update 同步"
- 简洁：表格优先，避免大段叙述；每个 Service 职责用 1-2 句话概括
注意事项
- 探索阶段优先读 service 接口文件（
I*.java），不读 impl，避免无效 token 消耗
- 若项目使用 Kotlin + Java 混合，两个目录都要探索
- Mapper/DAO 层只需列出实体名和关键查询方法，不需要列出所有 CRUD
- 生成完成后，不需要触发
design-doc-required（本 skill 属于分析类，非开发类）
- development-reference 需要深度分析：需读取 Service impl、Component 实现、Stream handler、Configuration 类的实际代码
- development-reference 的"常见开发场景速查"应根据项目实际业务域定制，不要照搬模板示例
- Phase 3-4 生成的文档标注"以下内容基于 AI 推断，请人工校验"
- 已存在的文档不覆盖，提示用户是否更新（可调用
project-docs-update）
- 生成完成后触发
doc-index-required Phase-B 更新索引
与其他 Skill 的关系
| Skill | 关系 |
|---|
project-docs-update | 本 skill 完成初始化后，后续维护由 project-docs-update 负责 |
doc-index-required | 生成文档后自动触发 Phase-B 更新索引 |
business-logic-orientation | Phase 4 模块文档可复用其产出的梳理结果 |
design-doc-required | 不触发——本 skill 属于分析类 |
arch-lint | Phase 1 的架构约束可为 arch-lint 提供检查规则基线 |
