# 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