237 lines
10 KiB
Markdown
237 lines
10 KiB
Markdown
---
|
||
name: sn-codemap
|
||
description: 将代码仓库转化为结构化 YAML 知识图谱（符号索引、API 详情、调用链、数据对象、交叉引用，L4 含公式/决策点/错误/阈值等业务知识）。当用户要求"分析项目"、"生成 codemap"、"提取符号/调用链"、"生成完整代码文档"或输入 /sn-codemap、/codemap 时使用。
|
||
---
|
||
|
||
# Code Map 代码知识图谱生成 (sn-codemap)
|
||
|
||
## 功能概述
|
||
|
||
将代码仓库转化为结构化的 YAML 知识图谱：
|
||
|
||
**代码结构**：
|
||
- 符号信息：类、方法、字段的定义和位置
|
||
- API 详情：请求参数、响应字段、错误码
|
||
- 调用链：以 API 入口为根的调用图
|
||
- 交叉引用：callers/callees、继承关系、前后端映射
|
||
- 数据对象：Entity/DTO/VO 的字段和关系
|
||
|
||
**业务知识（L4 可选扩展）**：
|
||
- 公式提取：计算逻辑的伪代码和配置依赖
|
||
- 决策点：if-else 分支和业务判断条件
|
||
- 错误信息：异常消息和触发条件清单
|
||
- 阈值常量：业务相关的常量值
|
||
|
||
---
|
||
|
||
## 加载链路（执行时如何读取本技能）
|
||
|
||
1. 触发本技能后，**先加载 `executor.yaml`**，按其中 Phase 0 → Phase 12 的顺序执行。
|
||
2. `templates/`、`schemas/` 在各 Phase 生成产物时按 executor 中的引用查阅。
|
||
3. `workflows/` 的 5 个子工作流在 executor 对应 Phase 中被引用时加载。
|
||
4. `guides/`（lsp-*.md）仅在需要 LSP/Serena 具体操作指引且对应工具可用时查阅，否则忽略。
|
||
|
||
---
|
||
|
||
## 分析等级（开始时与用户确认）
|
||
|
||
| 等级 | 名称 | 产出范围 | 适用场景 |
|
||
|------|------|----------|----------|
|
||
| **L1** | 快速扫描 | 技术栈 + 各平台符号索引 + 主索引 | 快速了解项目 |
|
||
| **L2** | 标准分析 | L1 + API 目录 + 核心数据对象/调用链/前后端映射 | 日常开发 |
|
||
| **L3** | 完整生成 | L2 全量化 + 交叉引用 + 跨端映射 + Mermaid 图 + 域模型 | 完整文档 |
|
||
|
||
等级通过 `--level` 参数或 Phase 0 交互确认，默认 L2。
|
||
|
||
### L4 可选扩展（业务知识提取）
|
||
|
||
executor.yaml 的执行流程覆盖 L1–L3。L4（formulas / decisions / errors / thresholds
|
||
业务知识提取）为**按需扩展**：在 L3 完成后，用户可要求提取业务知识，Agent 使用
|
||
`templates/formula|decision|error|threshold.template.yaml` 模板与
|
||
`schemas/codemap.formula|decision|error|threshold.schema.json` 进行提取，
|
||
产出写入 `formulas/`、`decisions/`、`errors/`、`thresholds/` 目录（各含 `_index.yaml`），
|
||
按 15 个/批 分批处理。
|
||
|
||
---
|
||
|
||
## 多语言支持（检测到什么平台分析什么）
|
||
|
||
技术栈检测（Phase 2）决定分析范围，只分析实际检测到的平台。
|
||
|
||
已验证路径：
|
||
|
||
| 平台 | 语言 | 分析内容 | 产出目录 |
|
||
|------|------|----------|----------|
|
||
| 后端 | Java | Controller, Service, Mapper, Entity | symbols/java/, api/java/, dataobjects/java/, callchains/java/ |
|
||
| Web 前端 | Vue | 页面组件, API 调用层 | symbols/vue/ |
|
||
| 小程序 | uni-app | 页面, 组件, API 调用 | symbols/miniapp/ |
|
||
|
||
备用路径（仅在检测到对应代码时启用，使用备用模板）：
|
||
|
||
| 平台 | 备用模板 |
|
||
|------|----------|
|
||
| Android (Kotlin) | `templates/kotlin-symbol.template.yaml` |
|
||
| iOS (Swift) | `templates/swift-symbol.template.yaml` |
|
||
|
||
符号分析主路径为 Grep/Glob/Read/Bash；若环境提供 Serena MCP（mcp__serena__*）
|
||
可用于加速，否则用 Grep/Read 完成，不得因此中断。
|
||
|
||
---
|
||
|
||
## 输出目录结构（L3 全量示例，按实际检测平台生成）
|
||
|
||
```
|
||
codemap/
|
||
├── _index.yaml # 项目主索引
|
||
├── _summary.yaml # 分析摘要
|
||
├── .codemap/state.yaml # 分析状态（支持增量/断点续跑）
|
||
│
|
||
├── context/ # 项目背景
|
||
│ ├── _project_context.yaml
|
||
│ └── _tech_stack.yaml
|
||
│
|
||
├── symbols/ # 符号索引（按检测到的平台）
|
||
│ ├── java/_symbols_index.yaml
|
||
│ ├── vue/_symbols_index.yaml
|
||
│ └── miniapp/_symbols_index.yaml
|
||
│
|
||
├── api/ # API 目录与详情（L2 核心、L3 全量）
|
||
│ └── java/
|
||
│ ├── _api_catalog.yaml
|
||
│ └── {endpoint-name}.yaml
|
||
│
|
||
├── dataobjects/ # 数据对象详情（L2 核心、L3 全量）
|
||
│ └── java/
|
||
│ ├── _dataobjects_index.yaml
|
||
│ └── {entity-name}.yaml
|
||
│
|
||
├── callchains/ # 调用链（L2 核心流程、L3 全量）
|
||
│ └── java/
|
||
│ ├── _callchains_index.yaml
|
||
│ └── {chain-name}.yaml
|
||
│
|
||
├── mapping/ # 前后端/跨端映射
|
||
│ ├── _frontend_backend_mapping.yaml
|
||
│ ├── _cross_platform_api_mapping.yaml # L3 多端项目
|
||
│ └── _api_consumer_matrix.yaml # L3 多端项目
|
||
│
|
||
├── xrefs/ # 交叉引用（L3）
|
||
│ ├── _xrefs_index.yaml
|
||
│ ├── callers-callees.yaml
|
||
│ └── inheritance.yaml
|
||
│
|
||
├── graphs/ # Mermaid 图（L3）
|
||
│ ├── _index.yaml
|
||
│ ├── state-machines/
|
||
│ └── callchains/
|
||
│
|
||
├── domain-entities/ # 统一业务域模型（L3 多平台）
|
||
│
|
||
├── formulas/ # 业务公式（L4 可选扩展）
|
||
├── decisions/ # 决策点（L4 可选扩展）
|
||
├── errors/ # 错误信息（L4 可选扩展）
|
||
└── thresholds/ # 阈值常量（L4 可选扩展）
|
||
```
|
||
|
||
---
|
||
|
||
## 执行流程（与 executor.yaml 的 Phase 一一对应）
|
||
|
||
| Phase | 名称 | 说明 | 主要产出 |
|
||
|-------|------|------|----------|
|
||
| 0 | 交互式初始化与参数确认 | 收集代码目录、输出目录、等级 | 分析计划 |
|
||
| 1 | Git 检测与增量分析判断 | Git 状态、历史状态、增量/全量决策 | 变更清单 |
|
||
| 2 | 技术栈检测 | 平台与框架检测，决定分析范围 | context/_tech_stack.yaml |
|
||
| 3 | 辅助文档分析（可选） | SQL、对接文档 | schema/、external/、context/ |
|
||
| 4 | Java 后端分析 | 符号/API/数据对象/调用链 | symbols/java/、api/java/、dataobjects/java/、callchains/java/ |
|
||
| 5 | 前端分析 | Vue/小程序页面与 API 调用层 | symbols/vue/、symbols/miniapp/ |
|
||
| 6 | 前后端映射与跨端 API 分析 | 路径匹配、跨端追踪 | mapping/ |
|
||
| 7 | 交叉引用生成（L3） | callers/callees、继承 | xrefs/ |
|
||
| 8 | Mermaid 图生成（L3） | 可视化图 | graphs/ |
|
||
| 9 | 统一业务域模型（L3 可选） | 跨端实体映射 | domain-entities/ |
|
||
| 10 | 索引生成 | 主索引与摘要 | _index.yaml、_summary.yaml |
|
||
| 11 | 状态更新与缓存 | checksum、状态文件 | .codemap/state.yaml |
|
||
| 12 | 完整性检查与完成报告 | 验证产出、补缺、报告 | 检查报告 |
|
||
|
||
---
|
||
|
||
## 完整性检查（Phase 12，只检查可兑现项）
|
||
|
||
- 核心文件存在：`_index.yaml`、`.codemap/state.yaml`、`context/_tech_stack.yaml`
|
||
- 符号索引与技术栈检测一致：检测到哪个平台就存在对应的 `symbols/{platform}/_symbols_index.yaml`
|
||
- 按等级生成的索引文件存在：L2 起 `api/java/_api_catalog.yaml`、`dataobjects/java/_dataobjects_index.yaml`、`callchains/java/_callchains_index.yaml`；L3 增 `xrefs/_xrefs_index.yaml`
|
||
- API/dataobject 详情文件按等级生成（L2 核心、L3 全量），以索引文件存在为准，不做数量硬指标
|
||
|
||
---
|
||
|
||
## 上下文管理
|
||
|
||
### 文件大小管理
|
||
|
||
读取任何文件前先 `wc -l` 检查：≤500 行直接读；500–2000 行分批读；
|
||
>2000 行或 >100KB 先用 Grep 定位结构再定点读。详细规则见 executor.yaml
|
||
`file_size_management` 节。
|
||
|
||
### 分批执行（大型项目）
|
||
|
||
| 内容类型 | 批次大小 |
|
||
|----------|----------|
|
||
| 数据对象 | 20 个/批 |
|
||
| 调用链 | 10 个/批 |
|
||
| API 详情 | 30 个/批 |
|
||
| L4 业务知识 | 15 个/批 |
|
||
|
||
### 断点续跑
|
||
|
||
状态保存在 `.codemap/state.yaml`（增量变更保存在 `.codemap/pending_changes.json`），
|
||
中断后重新执行 `/sn-codemap --resume` 可继续。
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
- 用户说"分析项目"、"生成 codemap"
|
||
- 用户说"提取符号"、"分析调用链"
|
||
- 用户说"生成完整代码文档"
|
||
- 直接输入 `/sn-codemap` 或 `/codemap`
|
||
|
||
## 命令格式
|
||
|
||
```
|
||
/sn-codemap <project_path> [options]
|
||
|
||
选项：
|
||
--output, -o 输出目录
|
||
--auxiliary, -a 辅助文档目录
|
||
--level 分析等级 (L1/L2/L3)
|
||
--incremental 强制增量分析
|
||
--full-rebuild 强制全量重建
|
||
--resume 从上次中断处继续
|
||
```
|
||
|
||
---
|
||
|
||
## 资源清单
|
||
|
||
- `executor.yaml` — 执行指引（Agent 按 Phase 0–12 执行，**执行时首先加载**）
|
||
- `workflows/` — 子工作流（被 executor 对应 Phase 引用时加载）：
|
||
- `incremental-analysis.yaml` — 增量分析：Git diff / checksum 变更检测、影响分析、增量合并（Phase 1/11）
|
||
- `cache-management.yaml` — 分析结果缓存：checksum 验证、级联失效、淘汰策略（Phase 1/11）
|
||
- `cross-platform-api-mapping.yaml` — 跨端 API 识别的**唯一定义**：各端调用模式、路径匹配、一致性检查（Phase 6）
|
||
- `mermaid-generation.yaml` — Mermaid 图生成步骤（Phase 8）
|
||
- `unified-domain-model.yaml` — 统一业务域模型生成步骤（Phase 9）
|
||
- `templates/` — 产物 YAML 模板（生成对应产物时查阅；`kotlin-symbol` / `swift-symbol` / `miniapp-page` 为备用模板，仅在检测到对应平台时使用）与 `templates/mermaid/` 图模板
|
||
- `schemas/` — 产物 JSON Schema（验证产物结构时查阅）
|
||
- `guides/`（lsp-*.md）— LSP/Serena 工具使用指南；需对应 LSP server 或 Serena MCP 可用，否则忽略
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 更新内容 |
|
||
|------|----------|
|
||
| v4.0 | 彻底重构：对齐执行链路（SKILL.md → executor.yaml → workflows/templates/schemas），Phase 重排为连续整数，符号分析主路径改为 Grep/Read/Bash，L4 转可选扩展，多语言收敛为按检测分析，删除无人消费的配置与孤儿文件 |
|
||
| v3.x 及更早 | 历史版本（LSP/Serena 中心架构、L1–L4 等级、缓存/增量机制引入等），已被 v4.0 取代 |
|
||
|
||
当前版本：v4.0
|