Code Map 技能

基于 Grep/Read 文本分析 + LLM 语义理解，为代码仓库生成可追溯的 YAML 知识图谱

权威定义见 SKILL.md（含触发条件、分析等级、执行流程）。 执行指引见 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）。

/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 预览，或用 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 可选扩展

核心原则

事实优先 - 结构信息必须来自代码（Grep/Read），不能捏造
可追溯 - 每个信息都有源码位置引用
语义增强 - 在事实基础上，用 LLM 补充业务含义
按需加载 - 索引与详情分层存储，按分析等级生成

文件大小管理

读取任何文件前先 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

4.3 KiB Raw Blame History Unescape Escape