238 lines
8.9 KiB
Markdown
238 lines
8.9 KiB
Markdown
---
|
||
name: sn-domainmap
|
||
description: 从业务文档（手册/流程/PRD/数据字典）提取结构化领域知识图谱（实体、流程、规则、术语表，D4 含页面流程、配置影响、运行态采集与 CodeMap 深度交叉引用）。当用户要求"分析业务文档"、"提取业务流程"、"创建 domainmap/业务知识图谱"或输入 /sn-domainmap、/domainmap 时使用。
|
||
---
|
||
|
||
# Domain Map 业务领域知识图谱生成 (sn-domainmap)
|
||
|
||
## 功能概述
|
||
|
||
从业务文档中提取结构化的领域知识：
|
||
|
||
**基础能力（D1–D3，executor 已实现）**：
|
||
- 业务实体：核心业务对象及其状态机定义
|
||
- 业务流程：工作流、阶段、角色、Mermaid 图
|
||
- 业务规则：校验规则、计算规则、流转规则
|
||
- 术语表：业务专有名词定义和口径
|
||
- 交叉引用：与 CodeMap 的基础关联（实体→代码、流程→API、术语→符号）
|
||
|
||
**可选扩展（D4，见下文）**：
|
||
- 页面流程：页面→API→方法→表的完整链路
|
||
- 配置影响：配置项对功能的影响映射
|
||
- 运行态事实：系统截图、菜单树、表单字段
|
||
- CodeMap 深度引用：与 formulas、decisions、errors、thresholds 关联
|
||
|
||
---
|
||
|
||
## 核心理念
|
||
|
||
```
|
||
CodeMap 回答 "系统能做什么"（Capability）
|
||
DomainMap 回答 "系统应该怎么做"（Intent & Contract）
|
||
两者结合形成完整的语义网络
|
||
```
|
||
|
||
---
|
||
|
||
## 分析等级
|
||
|
||
### D1–D3（executor 覆盖）
|
||
|
||
| 等级 | 名称 | 内容 | 适用场景 |
|
||
|------|------|------|----------|
|
||
| **D1** | 快速扫描 | 实体 + 术语，不提取流程/规则 | 快速了解业务概念 |
|
||
| **D2** | 标准分析 | 实体 + 流程 + 规则 + 术语 | 日常参考（默认） |
|
||
| **D3** | 完整生成 | D2 全量 + CodeMap 基础交叉引用 | 完整文档 |
|
||
|
||
### D4 可选扩展
|
||
|
||
executor 的执行流程覆盖 D1–D3。以下内容为**按需扩展**，模板已备在 `templates/`（config_impact / runtime / screen_flow），schemas 中有对应校验定义，但 executor 未内置生成步骤——需要时由执行代理参照模板手动生成：
|
||
|
||
- `screen_flows/`：页面→API→方法→表链路（模板 `screen_flow.template.yaml`）
|
||
- `config_impact/`：配置项对功能的影响（模板 `config_impact.template.yaml`）
|
||
- `runtime/`：运行态采集（模板 `runtime.template.yaml`）。**仅当 chrome-devtools MCP 可用时才采集**；不可用时直接跳过，不阻塞 D1–D3 产出。
|
||
- 深度交叉引用：`rule-to-code`、`screen-to-api`、`screen-to-formula`、`screen-to-decision`、`config-to-formula`（依赖 CodeMap 的 formulas/decisions 等 L4 产物存在）
|
||
|
||
---
|
||
|
||
## 执行流程（Phase）
|
||
|
||
执行时**先加载 `executor.yaml`** 作为执行指引；`templates/` 与 `schemas/` 在各 Phase 的生成/校验步骤中按需查阅。
|
||
|
||
| Phase | 名称 | 说明 |
|
||
|-------|------|------|
|
||
| -1 | 交互式初始化 | 询问分析等级（D1/D2/D3）、文档目录、输出目录、CodeMap 关联 |
|
||
| 0 | 文档扫描与分类 | 扫描文档目录，按类型分类（手册/流程/PRD/数据字典） |
|
||
| 1 | 业务实体提取 | 生成 `entities/*.yaml` + 索引 |
|
||
| 2 | 业务流程提取 | 生成 `processes/*.yaml` + 索引（D1 跳过） |
|
||
| 3 | 业务规则提取 | 生成 `rules/**/*.yaml` + 索引（D1 跳过） |
|
||
| 4 | 术语表构建 | 生成 `glossary/terms/*.yaml` + 索引 |
|
||
| 5 | CodeMap 交叉引用 | 生成 `xrefs/` 3 个基础映射（提供 codemap 路径时） |
|
||
| 6 | 索引生成与完整性检查 | 生成 `_index.yaml`、`state.yaml`，对照 schemas 校验关键产物 |
|
||
|
||
---
|
||
|
||
## 输出目录结构
|
||
|
||
输出根目录统一为 `domainmap/`（即 `{{output_dir}}/domainmap`）：
|
||
|
||
```
|
||
domainmap/
|
||
├── _index.yaml # 项目主索引
|
||
├── .domainmap/state.yaml # 分析状态（断点续跑）
|
||
│
|
||
├── entities/ # 业务实体
|
||
│ ├── _entities_index.yaml
|
||
│ └── {entity-name}.yaml
|
||
│
|
||
├── processes/ # 业务流程
|
||
│ ├── _processes_index.yaml
|
||
│ └── {process-name}.yaml
|
||
│
|
||
├── rules/ # 业务规则（rule_set 包装结构）
|
||
│ ├── _rules_index.yaml
|
||
│ ├── validation/
|
||
│ │ └── {rule-name}.yaml
|
||
│ ├── calculation/
|
||
│ │ └── {rule-name}.yaml
|
||
│ └── transition/
|
||
│ └── {rule-name}.yaml
|
||
│
|
||
├── glossary/ # 术语表
|
||
│ ├── _glossary_index.yaml
|
||
│ └── terms/
|
||
│ └── {domain}-terms.yaml
|
||
│
|
||
├── xrefs/ # 基础交叉引用（D3，提供 codemap 时）
|
||
│ ├── _xrefs_index.yaml
|
||
│ ├── entity-to-code.yaml # 实体→代码符号
|
||
│ ├── process-to-api.yaml # 流程→API
|
||
│ └── term-to-symbol.yaml # 术语→符号
|
||
│
|
||
├── screen_flows/ # 页面流程（可选扩展 D4）
|
||
│ └── {flow-name}.yaml
|
||
│
|
||
├── config_impact/ # 配置影响（可选扩展 D4）
|
||
│ ├── by_table/
|
||
│ └── by_function/
|
||
│
|
||
└── runtime/ # 运行态事实（可选扩展 D4，需 chrome-devtools MCP）
|
||
├── system_access.yaml
|
||
├── menu_tree.yaml
|
||
├── pages/
|
||
└── screenshots/
|
||
```
|
||
|
||
D4 深度交叉引用文件（`rule-to-code.yaml`、`screen-to-api.yaml`、`screen-to-formula.yaml`、`screen-to-decision.yaml`、`config-to-formula.yaml`）属于可选扩展，生成时放入 `xrefs/` 并在 `_xrefs_index.yaml` 中登记。
|
||
|
||
---
|
||
|
||
## 完整性检查（Phase 6）
|
||
|
||
```
|
||
业务实体：entities/*.yaml 文件数 >= _entities_index.yaml 声明总数
|
||
业务流程：processes/*.yaml 文件数 >= _processes_index.yaml 声明总数
|
||
业务规则：rules/**/*.yaml 文件数 >= _rules_index.yaml 声明规则集总数
|
||
术语表：glossary/terms/*.yaml 条目数 >= _glossary_index.yaml 声明总数
|
||
Schema 校验：关键产物（索引、实体、流程、规则、术语、xref）对照 schemas/ 校验，
|
||
校验失败项列入完整性报告
|
||
```
|
||
|
||
---
|
||
|
||
## 上下文管理
|
||
|
||
### 分批执行（大型项目）
|
||
|
||
| 内容类型 | 批次大小 |
|
||
|----------|----------|
|
||
| 文档分析 | 5 个/批 |
|
||
| 实体生成 | 10 个/批 |
|
||
| 流程生成 | 5 个/批 |
|
||
| 规则提取 | 20 条/批 |
|
||
|
||
### 断点续跑
|
||
|
||
```bash
|
||
/sn-domainmap --resume
|
||
```
|
||
|
||
状态保存在 `domainmap/.domainmap/state.yaml`，支持中断后继续。
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
- 用户说"分析业务文档"、"提取业务流程"
|
||
- 用户说"创建 domainmap"、"业务知识图谱"
|
||
- 用户想要理解业务规则和流程
|
||
- 用户想要将业务知识与代码关联
|
||
- 直接输入 `/sn-domainmap` 或 `/domainmap`
|
||
|
||
## 命令格式
|
||
|
||
```
|
||
/sn-domainmap [<docs_path>] [options]
|
||
|
||
选项：
|
||
--output, -o 输出目录（产物写入 {output}/domainmap/）
|
||
--link-codemap, -l 关联的 CodeMap 目录
|
||
--focus, -f 聚焦特定业务域
|
||
--level 分析等级 (D1/D2/D3)
|
||
--resume 从上次中断处继续
|
||
```
|
||
|
||
---
|
||
|
||
## 支持的文档类型
|
||
|
||
| 类型 | 格式 | 提取内容 |
|
||
|------|------|----------|
|
||
| 使用手册 | .md, .docx | 功能入口、字段规则、操作流程 |
|
||
| 流程手册 | .md, .docx | 业务流程、角色职责、状态流转 |
|
||
| 需求文档 | .md, .docx | 功能定义、验收标准、业务规则 |
|
||
| 数据字典 | .xlsx | 字段口径、枚举定义、取值范围 |
|
||
|
||
---
|
||
|
||
## 与 CodeMap 的关系
|
||
|
||
### 基础交叉引用（D3，executor 已实现）
|
||
|
||
| 类型 | DomainMap | CodeMap | 说明 |
|
||
|------|-----------|---------|------|
|
||
| entity-to-code | entities/*.yaml | dataobjects/{lang}/、symbols/{lang}/ | 业务实体→代码实体 |
|
||
| process-to-api | processes/*.yaml | api/{lang}/_api_catalog.yaml、callchains/{lang}/ | 业务流程→API/调用链 |
|
||
| term-to-symbol | glossary/terms/*.yaml | symbols/{lang}/ | 术语→枚举/常量 |
|
||
|
||
### 深度交叉引用（可选扩展 D4）
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| rule-to-code | 业务规则→Service 方法 |
|
||
| screen-to-api | 页面→API |
|
||
| screen-to-formula | 页面→计算公式（需 CodeMap formulas/） |
|
||
| screen-to-decision | 页面→决策点（需 CodeMap decisions/） |
|
||
| config-to-formula | 配置→公式（需 CodeMap formulas/） |
|
||
|
||
### 推荐组合
|
||
|
||
```
|
||
CodeMap（代码知识图谱）+ DomainMap（业务知识图谱）
|
||
= 完整的业务-代码语义网络
|
||
```
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 更新内容 |
|
||
|------|----------|
|
||
| v3.0 | 统一等级体系为 D1/D2/D3（消除 standard/brief/deep 双轨）；D4 转为可选扩展并删除自相矛盾的强制框；修复 process-to-api 的 CodeMap 数据源断链（补加载 api/ 与 callchains/）；统一输出路径为 domainmap/；补齐 rule 与索引模板；Phase 6 增加 schema 校验 |
|
||
| v2.1 | 曾声称新增 D4 等级，但 executor 未实现对应 Phase（已纠正） |
|
||
| v2.0 | 添加生成等级定义（D1/D2/D3） |
|
||
| v1.1 | 新增页面流程、配置影响、运行态采集 |
|
||
| v1.0 | 初始版本 |
|
||
|
||
当前版本：v3.0
|