القائمة
代码流程分析与可视化工具，将复杂代码执行流转化为清晰的可视化图谱。支持本地文件分析、历史版本管理、导入导出等功能。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | codemap |
| description | 代码流程分析与可视化工具，将复杂代码执行流转化为清晰的可视化图谱。支持本地文件分析、历史版本管理、导入导出等功能。 |
高级代码架构分析和可视化工具，将用户的查询和代码库上下文转化为结构化的 CodeMap JSON，并提供多种可视化表达（文本图、Mermaid 图、Markdown 指南）。
| 路径类型 | 路径 | 基准目录 |
|---|---|---|
| 技能目录 | ~/.pi/agent/skills/codemap/ | 固定位置 |
| SKILL 文件 | ~/.pi/agent/skills/codemap/SKILL.md | 技能目录 |
| 客户端目录 | ~/.pi/agent/skills/codemap/client/ | 技能目录 |
docs/.codemap/ 目录）~/.pi/agent/skills/codemap/
├── SKILL.md # 技能文档
├── client/ # Tauri 客户端
│ ├── src-tauri/ # Rust 后端
│ │ ├── src/
│ │ │ ├── main.rs # Tauri 入口
│ │ │ ├── commands.rs # Tauri 命令
│ │ │ ├── analyzer.rs # 代码分析逻辑
│ │ │ ├── codemap.rs # CodeMap 生成
│ │ │ └── storage.rs # 文件系统存储
│ │ └── Cargo.toml
│ ├── src/ # Web 前端
│ │ ├── components/ # 组件
│ │ ├── styles/ # 样式
│ │ ├── app.js # 主应用
│ │ └── index.html
│ └── package.json
└── README.md
# 启动客户端（开发模式）
cd ~/.pi/agent/skills/codemap/client
npm run tauri dev
# 构建生产版本
npm run tauri build
在 AI 对话中调用 codemap 技能：
用户：请分析"用户登录全流程"的代码执行路径
AI（调用 codemap）：
1. 读取代码库上下文
2. 识别关键节点（Controller、Service、Mapper）
3. 生成 CodeMap JSON
4. 返回可视化结果
{
"schemaVersion": 1,
"title": "流程标题",
"description": "流程的简要概述",
"mermaidDiagram": "全局视角的 Mermaid graph TB 流程图代码",
"traces": [
{
"id": "序号 (e.g., 1, 2)",
"title": "步骤标题",
"description": "步骤简述",
"locations": [
{
"id": "节点ID (e.g., 1a, 1b)",
"path": "文件绝对路径",
"lineNumber": 整数行号,
"lineContent": "关键代码行内容",
"title": "节点行为标题",
"description": "在该行发生了什么"
}
],
"traceTextDiagram": "基于文本的树状调用图",
"traceGuide": "Markdown 格式的详细指南"
}
]
}
analyze_code分析代码并生成 CodeMap。
#[tauri::command]
async fn analyze_code(
files: Vec<String>, // 文件路径列表
query: String, // 用户查询
project_root: String, // 项目根目录
) -> Result<CodeMap, String>
save_codemap保存 CodeMap 到数据库。
#[tauri::command]
async fn save_codemap(
codemap: CodeMap, // CodeMap 数据
tags: Vec<String>, // 标签
notes: String, // 备注
) -> Result<u64, String> // 返回 ID
list_codemaps列出所有保存的 CodeMap。
#[tauri::command]
async fn list_codemaps() -> Result<Vec<CodeMapMeta>, String>
load_codemap加载指定 ID 的 CodeMap。
#[tauri::command]
async fn load_codemap(id: u64) -> Result<CodeMap, String>
delete_codemap删除指定 ID 的 CodeMap。
#[tauri::command]
async fn delete_codemap(id: u64) -> Result<(), String>
export_codemap导出 CodeMap 为指定格式。
#[tauri::command]
async fn export_codemap(
id: u64,
format: String, // "json" | "markdown" | "html"
output_path: String,
) -> Result<(), String>
import_codemap导入 CodeMap 从文件。
#[tauri::command]
async fn import_codemap(
file_path: String, // JSON 或 Markdown 文件路径
) -> Result<CodeMap, String>
┌─────────────────────────────────────────────────────┐
│ CodeMap - 代码流程可视化工具 [设置] [帮助] │
├──────────────┬──────────────────────────────────────┤
│ │ │
│ 📁 目录树 │ 查询输入 │
│ │ ┌────────────────────────────────┐ │
│ ├─ src/ │ │ 请输入要分析的流程... │ │
│ │ ├─ ctrl/ │ └────────────────────────────────┘ │
│ │ ├─ svc/ │ │
│ │ └─ dao/ │ [分析] [清除选择] │
│ └─ tests/ │ │
│ │ ┌────────────────────────────────┐ │
│ 历史版本 │ │ │ │
│ 📋 版本列表 │ │ │ │
│ ├─ 登录流程 │ │ 可视化展示区 │ │
│ ├─ 订单流程 │ │ (Mermaid / 文本图 / 指南) │ │
│ └─ 支付流程 │ │ │ │
│ │ │ │ │
│ │ └────────────────────────────────┘ │
│ │ │
│ │ [导出 JSON] [导出 Markdown] [分享] │
└──────────────┴──────────────────────────────────────┘
CodeMap 使用基于文件系统的存储方式，所有数据存储在项目的 docs/.codemap/ 目录中。
项目根目录/
├── docs/
│ ├── .codemap/ # CodeMap 数据目录
│ │ ├── index.json # CodeMap 索引（元数据）
│ │ ├── codemaps/ # CodeMap 数据文件
│ │ │ ├── 20250106-001-login-flow.json
│ │ │ ├── 20250106-002-order-process.json
│ │ │ └── ...
│ │ ├── exports/ # 导出文件
│ │ │ ├── login-flow.html
│ │ │ ├── order-process.md
│ │ │ └── ...
│ │ └── cache/ # 缓存目录（可选）
│ ├── issues/ # Workhub Issues
│ └── pr/ # Workhub PRs
└── src/ # 源代码
{
"version": 1,
"projectRoot": "/path/to/project",
"codemaps": [
{
"id": "20250106-001",
"filename": "20250106-001-login-flow.json",
"title": "用户登录流程",
"description": "从前端登录请求到后端验证的完整流程",
"query": "用户登录全流程",
"createdAt": "2025-01-06T10:30:00Z",
"updatedAt": "2025-01-06T15:20:00Z",
"tags": ["v1.0", "生产环境"],
"note": "包含异常处理逻辑"
}
]
}
每个 CodeMap 保存为独立的 JSON 文件：
{
"schemaVersion": 1,
"metadata": {
"id": "20250106-001",
"title": "用户登录流程",
"description": "从前端登录请求到后端验证的完整流程",
"query": "用户登录全流程",
"projectRoot": "/path/to/project",
"createdAt": "2025-01-06T10:30:00Z",
"updatedAt": "2025-01-06T15:20:00Z",
"tags": ["v1.0", "生产环境"],
"note": "包含异常处理逻辑"
},
"title": "用户登录流程",
"description": "从前端登录请求到后端验证的完整流程",
"mermaidDiagram": "graph TB\n A[前端提交] --> B[Controller.login]\n B --> C[Service.validateUser]",
"traces": [...]
}
Controller、Api、Endpoint@RequestMapping、@GetMapping、@PostMapping 等Service、Manager、HandlerMapper、Dao、Repositoryif、switch、try-catch、三元运算符流程名称
├── Phase 1: 前端提交
│ ├── LoginController.login() < -- 1a
│ │ └── 调用 UserService.validateUser() < -- 1b
│ └── 返回登录结果 < -- 1c
└── Phase 2: 后端处理
├── UserService.validateUser() < -- 2a
│ ├── 检查用户存在性 < -- 2b
│ ├── 验证密码 < -- 2c
│ └── 生成 Token < -- 2d
└── UserMapper.selectById() < -- 2e
输入：
用户登录全流程src/controller/LoginController.java, src/service/UserService.java, src/mapper/UserMapper.java输出：
{
"schemaVersion": 1,
"title": "用户登录全流程",
"description": "从前端登录请求到后端验证和Token生成的完整流程",
"mermaidDiagram": "graph TB\n A[前端提交] --> B[Controller.login]\n B --> C[Service.validateUser]\n C --> D[Mapper.selectById]\n D --> C\n C --> E[生成Token]\n E --> B\n B --> A",
"traces": [...]
}
用户登录流程、订单创建流程支付流程 - 异常处理v1.0、生产环境Q：Mermaid 图表不显示？ A：检查网络连接，mermaid.js 需要从 CDN 加载。可配置本地离线版本。
Q：代码分析不准确？ A：确保选择的文件包含完整的业务流程，代码需要符合常见的命名规范。
Q：历史版本丢失？ A：检查 SQLite 数据库文件权限，确保应用有读写权限。
~/.pi/agent/skills/codemap/~/.pi/agent/skills/codemap/client/项目根目录/docs/.codemap/