codemap

name	codemap
description	代码流程分析与可视化工具，将复杂代码执行流转化为清晰的可视化图谱。支持本地文件分析、历史版本管理、导入导出等功能。

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：历史版本管理

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/