codemap

# 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 客户端（推荐） ```bash # 启动客户端（开发模式） 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 ```json { "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。 ```rust #[tauri::command] async fn analyze_code( files: Vec<String>, // 文件路径列表 query: String, // 用户查询 project_root: String, // 项目根目录 ) -> Result<CodeMap, String> ``` ### `save_codemap` 保存 CodeMap 到数据库。 ```rust #[tauri::command] async fn save_codemap( codemap: CodeMap, // CodeMap 数据 tags: Vec<String>, // 标签 notes: String, // 备注 ) -> Result<u64, String> // 返回 ID ``` ### `list_codemaps` 列出所有保存的 CodeMap。 ```rust #[tauri::command] async fn list_codemaps() -> Result<Vec<CodeMapMeta>, String> ``` ### `load_codemap` 加载指定 ID 的 CodeMap。 ```rust #[tauri::command] async fn load_codemap(id: u64) -> Result<CodeMap, String> ``` ### `delete_codemap` 删除指定 ID 的 CodeMap。 ```rust #[tauri::command] async fn delete_codemap(id: u64) -> Result<(), String> ``` ### `export_codemap` 导出 CodeMap 为指定格式。 ```rust #[tauri::command] async fn export_codemap( id: u64, format: String, // "json" | "markdown" | "html" output_path: String, ) -> Result<(), String> ``` ### `import_codemap` 导入 CodeMap 从文件。 ```rust #[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 结构 ```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 文件： ```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` **输出**： ```json { "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：历史版本管理 1. 生成多个 CodeMap 版本 2. 在历史版本列表中查看 3. 点击版本加载到可视化区域 4. 对比不同版本的差异 ### 示例 3：分享功能 1. 选择要分享的 CodeMap 2. 点击"分享"按钮 3. 选择"导出 HTML" 4. 生成独立的 HTML 文件，包含所有可视化 5. 发送给同事，直接在浏览器中打开查看 ## 最佳实践 ### 代码选择 - 选择完整的业务流程相关文件 - 包含 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/`