Files

T

guoqibing e98660ce4e feat: 根目录文档、脚本、gitignore

2026-10-08 16:15:33 +08:00

10 KiB

Raw Blame History

name, description

name	description
sn-codemap	将代码仓库转化为结构化 YAML 知识图谱（符号索引、API 详情、调用链、数据对象、交叉引用，L4 含公式/决策点/错误/阈值等业务知识）。当用户要求"分析项目"、"生成 codemap"、"提取符号/调用链"、"生成完整代码文档"或输入 /sn-codemap、/codemap 时使用。

Code Map 代码知识图谱生成 (sn-codemap)

功能概述

将代码仓库转化为结构化的 YAML 知识图谱：

代码结构：

符号信息：类、方法、字段的定义和位置
API 详情：请求参数、响应字段、错误码
调用链：以 API 入口为根的调用图
交叉引用：callers/callees、继承关系、前后端映射
数据对象：Entity/DTO/VO 的字段和关系

业务知识（L4 可选扩展）：

公式提取：计算逻辑的伪代码和配置依赖
决策点：if-else 分支和业务判断条件
错误信息：异常消息和触发条件清单
阈值常量：业务相关的常量值

加载链路（执行时如何读取本技能）

触发本技能后，先加载 executor.yaml，按其中 Phase 0 → Phase 12 的顺序执行。
templates/、schemas/ 在各 Phase 生成产物时按 executor 中的引用查阅。
workflows/ 的 5 个子工作流在 executor 对应 Phase 中被引用时加载。
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

10 KiB Raw Blame History Unescape Escape