188 lines
6.6 KiB
Markdown
188 lines
6.6 KiB
Markdown
---
|
||
name: docmap
|
||
description: |
|
||
项目文档架构生成技能。从代码、SQL、接口定义、文档中提炼产品视角的架构文档。
|
||
输出：《产品整体架构文档》+ 各模块《功能模块拆解文档》+ 系统能力模型。
|
||
适用场景：新项目入手、产品知识基座构建、PRD 生成前的背景探索。
|
||
触发关键词：分析项目架构、生成产品文档、生成架构文档、理解系统、/docmap
|
||
---
|
||
|
||
# docmap — 项目文档架构生成
|
||
|
||
## 触发条件
|
||
- 用户说"分析项目架构"、"生成产品文档"、"生成架构文档"
|
||
- 用户说"帮我理解这个系统"、"先了解项目再写 PRD"
|
||
- 直接输入 `/docmap [项目路径]`
|
||
|
||
---
|
||
|
||
## 角色定位
|
||
资深产品架构师 + 系统架构师 + 技术产品经理。从代码和文档中提炼产品层逻辑，而非重复代码结构。
|
||
|
||
---
|
||
|
||
## Phase 0：资源发现与确认
|
||
|
||
扫描以下资源路径（以项目根为准，默认路径为本项目实际结构）：
|
||
|
||
| 资源 ID | 默认路径 | 内容 | 优先级 |
|
||
|---------|---------------------------------------|------|--------|
|
||
| SRC-KNOWLEDGE | `assets/codemap/`、`assets/domainmap/` | 已有结构化知识（YAML 知识图谱），存在时优先消费 | P0 |
|
||
| SRC-FEAT | `prds/` | 功能需求文档 | P0 |
|
||
| SRC-CODE | `codes/`（源码子仓库） | 代码结构 | P0 |
|
||
| SRC-SQL | `docs/sql/` 或各仓库内 SQL | 数据库设计 | P1 |
|
||
| SRC-API | `docs/open-api/` | 接口定义 | P1 |
|
||
| SRC-REVIEW | `docs/` 下评审类目录 | 评审报告 | P2 |
|
||
|
||
**路径发现策略：**
|
||
1. 检查默认路径是否存在
|
||
2. 不存在时扫描项目根目录寻找对应内容
|
||
3. 向用户确认发现的路径，确认后把最终路径映射写入 `materials_index.md`
|
||
|
||
**输出：** `materials_index.md`（资料索引）
|
||
|
||
---
|
||
|
||
## 输入来源与技能边界
|
||
|
||
- codemap / domainmap 产出**结构化事实**（YAML 知识图谱：符号、API、调用链、数据对象、实体、流程、规则等）；docmap **消费其产出**，撰写叙事性产品文档，不重复生成结构化事实。
|
||
- 当 `assets/codemap/`、`assets/domainmap/` 存在时，模块边界、数据流、业务流程等分析应**优先引用**其中的结构化事实，而非从原始代码重新挖掘；原始代码仅用于补充知识图谱未覆盖的细节。
|
||
- 引用结构化知识时按 `[SRC-KNOWLEDGE]` 标注证据（见"证据标注"节）。
|
||
|
||
---
|
||
|
||
## Phase 1：项目深度理解
|
||
|
||
6 个维度分析（每个维度必须有输出）：
|
||
|
||
| 维度 | 分析问题 | 主要资源 |
|
||
|------|---------|---------|
|
||
| 系统目标 | 产品要解决什么问题？核心价值是什么？ | SRC-FEAT |
|
||
| 核心业务流程 | 主流程是什么？关键节点有哪些？ | SRC-FEAT + SRC-CODE |
|
||
| 系统角色 | 有哪些用户角色？各自的操作边界？ | SRC-FEAT |
|
||
| 模块边界 | 系统拆分为哪些模块？边界如何划定？ | SRC-CODE |
|
||
| 数据流 | 数据从哪里来、流向哪里？生命周期？ | SRC-SQL + SRC-API |
|
||
| 系统依赖 | 内外部依赖有哪些？集成点在哪？ | SRC-API + SRC-CODE |
|
||
|
||
**输出：** `phase1_analysis.md`
|
||
|
||
---
|
||
|
||
## Phase 2：输出文档生成
|
||
|
||
### 2.1 产品整体架构文档
|
||
|
||
**文件：** `outputs/01-产品整体架构.md`
|
||
|
||
必须包含：
|
||
1. 产品定位（目标、价值、用户、场景）
|
||
2. 系统整体架构（分层、技术概览、依赖关系）
|
||
3. 业务架构图（Mermaid）
|
||
4. 核心业务流程说明（Mermaid 流程图）
|
||
5. 数据架构（实体、关系、生命周期）
|
||
6. 权限与角色体系（角色定义、权限分层）
|
||
7. 系统扩展点分析
|
||
|
||
### 2.2 功能模块拆解文档
|
||
|
||
**目录：** `outputs/02-功能模块/`
|
||
**命名：** `{序号}-{模块名}.md`
|
||
|
||
每个模块包含：
|
||
1. 模块定位
|
||
2. 功能清单（表格）
|
||
3. 核心逻辑（规则、校验、状态流转 Mermaid）
|
||
4. 数据结构（表、字段、关联）
|
||
5. 对外接口（API、事件、回调）
|
||
6. 异常与边界处理
|
||
|
||
---
|
||
|
||
## Phase 3：系统能力模型
|
||
|
||
**文件：** `outputs/03-系统能力模型.md`
|
||
|
||
包含：
|
||
1. 核心能力清单（不超过 10 项）
|
||
2. 能力依赖关系图（Mermaid）
|
||
3. 可复用能力清单（表格）
|
||
4. 平台级能力
|
||
5. 业务定制能力
|
||
|
||
---
|
||
|
||
## Phase 4：质量检查
|
||
|
||
执行验证脚本检查输出完整性：
|
||
|
||
```bash
|
||
python3 scripts/validate_output.py {workdir}/outputs
|
||
```
|
||
|
||
- **参数：** `outputs` 子目录路径（脚本位于本技能 `scripts/` 下，参数可写相对项目根路径或绝对路径）
|
||
- **报告输出：** `{workdir}/validation_report.md`（即 outputs 的父目录）
|
||
- **退出码：** 存在失败项时为非零；仅有警告项时为零
|
||
|
||
检查项（与脚本口径一致）：
|
||
- 目录结构完整（`01-产品整体架构.md`、`02-功能模块/`、`03-系统能力模型.md`）
|
||
- 架构文档 7 个章节完整
|
||
- 架构文档至少 2 个 Mermaid 图
|
||
- 模块文档都有功能清单表格
|
||
- 能力模型包含能力依赖关系图（Mermaid）及平台级/业务定制能力区分
|
||
- 模块文档 stateDiagram 状态流转图（警告项，不阻断：无状态机的模块可豁免）
|
||
- 模糊表述（"等"、"等情况"、"等多种"等；警告项，不阻断）
|
||
|
||
**输出：** `validation_report.md`
|
||
|
||
---
|
||
|
||
## 写作原则
|
||
|
||
- **产品视角**，不重复代码结构
|
||
- **逻辑严谨**，不泛泛而谈
|
||
- **可长期维护**
|
||
- 禁止模糊表达："等情况"、"等多种"、"其他相关"
|
||
|
||
### 证据标注
|
||
- `[SRC-KNOWLEDGE]` - 已有结构化知识库（codemap / domainmap）
|
||
- `[SRC-FEAT]` - 功能文档
|
||
- `[SRC-CODE]` - 代码结构
|
||
- `[SRC-SQL]` - 数据库设计
|
||
- `[SRC-API]` - 接口定义
|
||
- `[ASSUMPTION]` - 无证据推断
|
||
|
||
---
|
||
|
||
## 工作目录结构
|
||
|
||
```
|
||
{workdir}/
|
||
├── materials_index.md
|
||
├── phase1_analysis.md
|
||
├── outputs/
|
||
│ ├── 01-产品整体架构.md
|
||
│ ├── 02-功能模块/
|
||
│ │ └── {序号}-{模块名}.md
|
||
│ └── 03-系统能力模型.md
|
||
└── validation_report.md
|
||
```
|
||
|
||
---
|
||
|
||
## 使用 bundled resources
|
||
|
||
### 参考模板
|
||
- `references/architecture_template.md` - 架构文档模板
|
||
- `references/module_template.md` - 模块文档模板
|
||
- `references/capability_template.md` - 能力模型模板
|
||
|
||
### 验证脚本
|
||
- `scripts/validate_output.py` - 输出质量检查脚本
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
- **v1.1**（2026-08）输入源对齐项目实际结构（`codes/`、`prds/`、`docs/` 子目录）；新增"输入来源与技能边界"，消费 codemap/domainmap 已有产出；Phase 4 补验证脚本调用示例，检查项口径与脚本实现对齐
|
||
- **v1.0** 初始版本
|