---
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