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

2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
@@ -0,0 +1,102 @@
+# 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