diegosouzapw CodeMap
高级代码架构分析和可视化工具，将用户的查询和代码库上下文转化为结构化的 CodeMap JSON，并提供多种可视化表达（文本图、Mermaid 图、Markdown 指南）。
执行环境
| 路径类型 | 路径 | 基准目录 |
|---|---|---|
| 技能目录 | ~/.pi/agent/skills/codemap/ |
固定位置 |
| SKILL 文件 | ~/.pi/agent/skills/codemap/SKILL.md |
技能目录 |
| 客户端目录 | ~/.pi/agent/skills/codemap/client/ |
技能目录 |
功能特性
核心功能
- 代码流程分析：自动识别 Controller、Service、Mapper 等关键代码节点
- 可视化输出：生成三种可视化形式（文本调用图、Mermaid 流程图、Markdown 指南）
- 本地处理：所有代码分析在本地完成，保护隐私
高级功能
- 历史版本管理：保存和管理多个 CodeMap 版本，支持版本对比
- 目录树浏览：交互式文件目录树，支持多文件/文件夹选择
- 导入导出：支持 JSON、Markdown、自包含 HTML 格式
- 分享功能：导出独立 HTML 文件，包含所有可视化和数据
客户端架构
技术栈
- 后端：Rust + Tauri
- 前端：Web（HTML + CSS + JavaScript）
- 存储：基于文件系统（JSON 格式，存储在
docs/.codemap/目录） - 可视化库：mermaid.js、marked.js
目录结构
~/.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
使用方式
方式 1：通过 Tauri 客户端（推荐）
# 启动客户端（开发模式）
cd ~/.pi/agent/skills/codemap/client
npm run tauri dev
# 构建生产版本
npm run tauri build
方式 2：集成到 AI 工作流
在 AI 对话中调用 codemap 技能：
用户：请分析"用户登录全流程"的代码执行路径
AI（调用 codemap）：
1. 读取代码库上下文
2. 识别关键节点（Controller、Service、Mapper）
3. 生成 CodeMap JSON
4. 返回可视化结果
CodeMap JSON Schema
{
"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 格式的详细指南"
}
]
}
Tauri 命令 API
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] [分享] │
└──────────────┴──────────────────────────────────────┘
组件说明
1. 目录树组件（DirectoryTree）
- 显示项目目录结构
- 支持多文件选择（复选框）
- 支持文件夹全选
- 显示文件类型图标
2. 查询输入组件（QueryInput）
- 文本输入框
- 支持历史查询记录
- 提供示例查询提示
3. 可视化展示区（VisualizationPanel）
- 三个 Tab：Mermaid 图、文本调用图、Markdown 指南
- 支持缩放和全屏
- 支持节点点击查看代码
4. 历史版本列表（HistorySidebar）
- 显示所有保存的 CodeMap
- 支持搜索和过滤
- 显示创建时间和标签
- 支持删除和重命名
5. 导出组件（ExportDialog）
- 格式选择：JSON、Markdown、HTML
- 文件路径选择
- 导出进度显示
数据存储
文件系统结构
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/ # 源代码
index.json 结构
{
"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 文件结构
每个 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 层
- 特征：类名包含
Controller、Api、Endpoint - 关键方法：
@RequestMapping、@GetMapping、@PostMapping等
Service 层
- 特征：类名包含
Service、Manager、Handler - 关键逻辑：业务判断、数据处理
Mapper/DAO 层
- 特征：类名包含
Mapper、Dao、Repository - 关键操作：数据库查询、插入、更新
分支判断
- 特征：
if、switch、try-catch、三元运算符 - 记录条件表达式
文本调用图生成
流程名称
├── Phase 1: 前端提交
│ ├── LoginController.login() < -- 1a
│ │ └── 调用 UserService.validateUser() < -- 1b
│ └── 返回登录结果 < -- 1c
└── Phase 2: 后端处理
├── UserService.validateUser() < -- 2a
│ ├── 检查用户存在性 < -- 2b
│ ├── 验证密码 < -- 2c
│ └── 生成 Token < -- 2d
└── UserMapper.selectById() < -- 2e
示例使用
示例 1：分析登录流程
输入：
- 查询：
用户登录全流程 - 文件：
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": [...]
}
示例 2：历史版本管理
- 生成多个 CodeMap 版本
- 在历史版本列表中查看
- 点击版本加载到可视化区域
- 对比不同版本的差异
示例 3：分享功能
- 选择要分享的 CodeMap
- 点击"分享"按钮
- 选择"导出 HTML"
- 生成独立的 HTML 文件，包含所有可视化
- 发送给同事，直接在浏览器中打开查看
最佳实践
代码选择
- 选择完整的业务流程相关文件
- 包含 Controller、Service、Mapper 层
- 避免选择过多无关文件
查询编写
- 使用清晰的业务术语：
用户登录流程、订单创建流程 - 可以包含特定关注点：
支付流程 - 异常处理 - 中英文均可，系统会自动识别
版本管理
- 为重要的 CodeMap 添加标签：
v1.0、生产环境 - 添加备注说明版本变更点
- 定期清理过期的历史版本
导出格式
- JSON：用于程序化处理和二次开发
- Markdown：用于文档归档和版本控制
- HTML：用于分享和演示
扩展计划
- 支持更多编程语言（Python、Go、TypeScript）
- 添加代码复杂度分析
- 集成 AI 智能建议
- 支持团队协作（云端同步）
- 添加插件系统
故障排查
常见问题
Q：Mermaid 图表不显示？ A：检查网络连接，mermaid.js 需要从 CDN 加载。可配置本地离线版本。
Q：代码分析不准确？ A：确保选择的文件包含完整的业务流程，代码需要符合常见的命名规范。
Q：历史版本丢失？ A：检查 SQLite 数据库文件权限，确保应用有读写权限。
技术支持
- 技能目录：
~/.pi/agent/skills/codemap/ - 客户端目录：
~/.pi/agent/skills/codemap/client/ - 数据存储：
项目根目录/docs/.codemap/