feat: 根目录文档、脚本、gitignore

2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
@@ -0,0 +1,92 @@
+# DomainMap Skill
+
+业务领域知识图谱生成技能 - 从业务文档提取结构化领域知识。
+
+> **权威定义见 [SKILL.md](./SKILL.md)**（等级体系、输出结构、Phase 流程、CodeMap 交叉引用均以 SKILL.md 为准）。本文档仅提供快速上手说明。
+
+**核心精神**: 于细微处发大隙 - 流程必须标注所有"分支点"，状态机必须列举所有状态及其可执行操作
+
+**验证纲领**: 实践才能检验真理 - 运行态采集（D4 可选扩展）须有截图等证据，无证据的转换标记为"推测"
+
+## 概述
+
+DomainMap 与 CodeMap 形成互补：CodeMap 回答"系统能做什么"（来自代码仓库），DomainMap 回答"系统应该怎么做"（来自业务文档）。
+
+## 使用方法
+
+```bash
+# 交互式初始化（推荐）
+/sn-domainmap
+
+# 指定文档目录
+/sn-domainmap /path/to/docs
+
+# 指定输出目录（产物写入 {output}/domainmap/）
+/sn-domainmap /path/to/docs --output /path/to/output
+
+# 指定分析等级（D1 快速扫描 / D2 标准分析 / D3 完整生成）
+/sn-domainmap /path/to/docs --level D3
+
+# 与 CodeMap 建立交叉引用
+/sn-domainmap /path/to/docs --link-codemap /path/to/codemap
+```
+
+支持的文档类型、输出结构、等级定义与 CodeMap 交叉引用矩阵见 SKILL.md。
+
+## 核心概念
+
+### 业务实体 (Entity)
+
+核心业务对象的定义，包含业务定义、状态机（状态与流转）、关键字段、与代码 Entity/DTO/VO 的对应关系。
+
+### 业务流程 (Process)
+
+工作流程的阶段定义（角色、动作、输入输出）与 Mermaid 流程图。
+
+### 业务规则 (Rule)
+
+分三类：validation（校验）、calculation（计算）、transition（流转）。产物采用 rule_set 包装结构（见 `templates/rule.template.yaml` 与 `schemas/domainmap.rule.schema.json`）。
+
+### 术语表 (Glossary)
+
+业务专有名词定义，按业务域分文件存放于 `glossary/terms/{domain}-terms.yaml`，含别名、使用上下文、与代码枚举的对应。
+
+## D4 可选扩展
+
+`screen_flows/`（页面流程）、`config_impact/`（配置影响）、`runtime/`（运行态事实）与深度交叉引用为按需扩展：模板备于 `templates/`，executor 不内置生成步骤。其中 `runtime/` 采集依赖 chrome-devtools MCP，不可用时跳过。
+
+## 应用场景
+
+1. **需求影响分析**：从 DomainMap 定位受影响业务对象，经交叉引用进入 CodeMap 展开调用链
+2. **智能 PRD 生成**：业务流程/规则 + CodeMap 接口定义，自动填充技术实现参考
+3. **Bug 追踪定位**：堆栈 → CodeMap 符号 → 交叉引用 → 业务流程与规则约束
+
+## 文件说明
+
+```
+domainmap/
+├── SKILL.md                               # Skill 入口定义（权威）
+├── executor.yaml                          # 执行引擎（v3.0）
+├── README.md                              # 本文档
+├── schemas/                               # JSON Schema 校验定义（9 个）
+│   ├── domainmap.index.schema.json
+│   ├── domainmap.entity.schema.json
+│   ├── domainmap.process.schema.json
+│   ├── domainmap.rule.schema.json
+│   ├── domainmap.glossary.schema.json
+│   ├── domainmap.xref.schema.json
+│   ├── domainmap.screen_flow.schema.json  # D4 可选扩展
+│   ├── domainmap.config_impact.schema.json# D4 可选扩展
+│   └── domainmap.runtime.schema.json      # D4 可选扩展
+└── templates/                             # YAML 模板（16 个）
+    ├── _index / _entities_index / _processes_index / _rules_index / _glossary_index / _xrefs_index .template.yaml
+    ├── entity / process / rule / glossary .template.yaml
+    ├── xref-entity-to-code / xref-process-to-api / xref-term-to-symbol .template.yaml
+    └── screen_flow / config_impact / runtime .template.yaml    # D4 可选扩展
+```
+
+## 相关文档
+
+- [CodeMap Skill](../codemap/README.md)
+
+当前版本：v3.0
@@ -0,0 +1,237 @@
+---
+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