103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
# Code Map 技能
|
||
|
||
> 基于 Grep/Read 文本分析 + LLM 语义理解，为代码仓库生成可追溯的 YAML 知识图谱
|
||
|
||
**权威定义见 [SKILL.md](SKILL.md)**（含触发条件、分析等级、执行流程）。
|
||
**执行指引见 [executor.yaml](executor.yaml)**（Agent 按 Phase 0–12 执行）。
|
||
本文件仅为概览与使用说明。
|
||
|
||
## 概述
|
||
|
||
Code Map 技能将源代码转化为结构化的 YAML 知识图谱，包含：
|
||
|
||
- **符号信息**：类、方法、字段的精确定义和位置
|
||
- **API 详情**：请求参数、响应字段、错误码
|
||
- **调用链**：以 API 入口为根的调用图
|
||
- **交叉引用**：callers/callees、继承、前后端映射
|
||
- **Mermaid 可视化**：状态机图、调用链图、API 矩阵图等
|
||
|
||
分析等级：**L1 快速扫描 / L2 标准分析（默认）/ L3 完整生成**；
|
||
L4 业务知识提取（公式/决策点/错误/阈值）为可选扩展，详见 SKILL.md。
|
||
|
||
平台支持：检测到什么平台分析什么。已验证路径为 Java / Vue / 小程序；
|
||
Kotlin、Swift 有备用模板（`templates/kotlin-symbol.template.yaml`、
|
||
`templates/swift-symbol.template.yaml`），仅在检测到对应代码时启用。
|
||
|
||
## 使用方式
|
||
|
||
```
|
||
/sn-codemap [<project_path>] [--output <dir>] [--auxiliary <dir>]
|
||
[--level L1|L2|L3] [--incremental] [--full-rebuild] [--resume]
|
||
```
|
||
|
||
不带参数执行时进入交互式初始化（executor Phase 0）。
|
||
|
||
```bash
|
||
/sn-codemap /path/to/project # 基本用法
|
||
/sn-codemap /path/to/project --level L3 # 完整生成
|
||
/sn-codemap /path/to/project --incremental # 强制增量分析
|
||
/sn-codemap /path/to/project --resume # 断点续跑
|
||
```
|
||
|
||
生成的 `.mmd` 图可在 [Mermaid Live Editor](https://mermaid.live) 预览，
|
||
或用 `mmdc -i input.mmd -o output.svg` 导出。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
codemap/
|
||
├── SKILL.md # 技能权威定义（入口）
|
||
├── executor.yaml # 执行指引（Agent 按 Phase 0–12 执行）
|
||
├── README.md # 本文件
|
||
├── workflows/ # 子工作流（被 executor 引用时加载）
|
||
│ ├── incremental-analysis.yaml # 增量分析（Phase 1/11）
|
||
│ ├── cache-management.yaml # 结果缓存（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 模板 + mermaid/ 图模板
|
||
├── schemas/ # 产物 JSON Schema
|
||
└── guides/ # LSP/Serena 使用指南（需对应工具可用，否则忽略）
|
||
```
|
||
|
||
## 输出结构
|
||
|
||
```
|
||
codemap/
|
||
├── _index.yaml # 项目主索引
|
||
├── _summary.yaml # 分析摘要
|
||
├── .codemap/state.yaml # 分析状态（增量/断点续跑）
|
||
├── context/ # 项目背景与技术栈
|
||
├── symbols/ # 符号索引（按检测到的平台）
|
||
├── api/ # API 目录与详情（L2 核心、L3 全量）
|
||
├── dataobjects/ # 数据对象详情
|
||
├── callchains/ # 调用链
|
||
├── mapping/ # 前后端/跨端映射
|
||
├── xrefs/ # 交叉引用（L3）
|
||
├── graphs/ # Mermaid 图（L3）
|
||
├── domain-entities/ # 统一业务域模型（L3 多平台）
|
||
└── formulas/ decisions/ errors/ thresholds/ # L4 可选扩展
|
||
```
|
||
|
||
## 核心原则
|
||
|
||
1. **事实优先** - 结构信息必须来自代码（Grep/Read），不能捏造
|
||
2. **可追溯** - 每个信息都有源码位置引用
|
||
3. **语义增强** - 在事实基础上，用 LLM 补充业务含义
|
||
4. **按需加载** - 索引与详情分层存储，按分析等级生成
|
||
|
||
## 文件大小管理
|
||
|
||
读取任何文件前先 `wc -l` 检查大小：≤500 行直接读，500–2000 行分批读，
|
||
>2000 行或 >100KB 先用 Grep 定位结构再定点读。详见 executor.yaml
|
||
`file_size_management` 节。
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 更新内容 |
|
||
|------|----------|
|
||
| v4.0 | 彻底重构：对齐执行链路，Phase 连续编号，Grep/Read 主路径，L4 转可选扩展，删除死文件 |
|
||
| v3.x 及更早 | 历史版本，已被 v4.0 取代 |
|
||
|
||
当前版本：v4.0
|