CodeMap Trace

English

CodeMap Trace is a VS Code extension for turning code investigation notes into visual documents. It opens .codemap JSON files as sequence diagrams or spatial trace canvases, so you can review service calls, source evidence, and hand-curated relationships without leaving the editor.

Use it when you need to:

• Understand how a request moves across services, RPC calls, queues, and handlers.
• Keep a readable map of important source files, functions, and call relationships.
• Review and refine diagrams generated by external AI tools.
• Store architecture and debugging notes as version-controlled project files.

Trace Canvases

Trace files show source cards on a draggable canvas. Cards can point to real source evidence, connect to other cards, and include annotations for important decisions or missing context.

Trace files live under:

.codemap/traces/**/*.json

Sequence Diagrams

Sequence files show service or RPC flows as lanes and ordered links. They are useful for request lifecycle reviews, cross-service communication, async events, and focused business-process documentation.

Sequence files live under:

.codemap/sequences/**/*.json

Main Features

• Browse Sequence and Trace files from the Code Map side bar.
• Open diagrams in full editor tabs.
• Create new Sequence or Trace template files.
• Edit titles, lanes, links, notes, evidence, and visual annotations.
• Organize files in subfolders by topic or module.
• Jump from diagram evidence back to source code.
• Export the current JSON format guide for external AI tools.

Quick Start

1. Open a trusted workspace in VS Code.
2. Open the Code Map view from the Activity Bar.
3. Create a file with New File, or place an existing JSON file under .codemap/sequences or .codemap/traces.
4. Click a file in the side bar to open the diagram.
5. Use Docs in the side bar to export the current format guides when you want an external AI tool to generate files for this extension.

AI Workflow

CodeMap Trace does not require a built-in AI provider. External AI tools can read the exported format guides and write JSON files directly into your workspace. A practical workflow is:

1. Export sequence-format.md or trace-format.md from the side bar.
2. Give the relevant format guide and your analysis request to an AI tool.
3. Ask it to generate one focused JSON file.
4. Save the file under .codemap/sequences or .codemap/traces.
5. Open it in CodeMap Trace and refine the result with source evidence.

File Format

The repository includes the current JSON references:

• Sequence format
• Trace format

For installed extensions, prefer the side bar Docs button because it exports the format guide that matches the installed version.

中文

CodeMap Trace 是一个 VS Code 扩展，用来把代码阅读、链路梳理和调试分析沉淀成可视化文档。它读取项目中的 .codemap JSON 文件，并展示为服务时序图或源码 Trace 画布，帮助你在编辑器内查看调用关系、源码证据和人工整理的业务链路。

适合用于：

• 理解一个请求如何经过服务、RPC、队列和处理函数。
• 保存关键源码路径、函数关系和排查结论。
• 检查并调整外部 AI 生成的链路图。
• 把架构分析、调试笔记和业务流程图纳入项目版本管理。

Trace 画布

Trace 文件用可拖动的源码卡片展示代码阅读路径。卡片可以关联真实源码证据、连接到其它卡片，也可以加入注释说明关键判断或缺失上下文。

Trace 文件放在：

.codemap/traces/**/*.json

Sequence 时序图

Sequence 文件用泳道和有序连线展示服务或 RPC 调用流程，适合描述请求生命周期、跨服务通信、异步事件和业务流程。

Sequence 文件放在：

.codemap/sequences/**/*.json

主要能力

• 在 Code Map 侧边栏浏览 Sequence 和 Trace 文件。
• 在完整编辑器标签页中打开图表。
• 创建新的 Sequence 或 Trace 模板文件。
• 编辑标题、泳道、连线、备注、源码证据和视觉注释。
• 按主题或模块把文件整理到子目录。
• 从图表中的源码证据跳转回真实代码位置。
• 导出当前 JSON 格式说明，方便外部 AI 生成图表文件。

快速开始

1. 在 VS Code 中打开一个已信任的项目。
2. 点击左侧 Activity Bar 中的 Code Map 视图。
3. 使用 New File 创建文件，或者把已有 JSON 放到 .codemap/sequences 或 .codemap/traces。
4. 在侧边栏点击文件即可打开图表。
5. 如果希望外部 AI 生成图表，可以点击侧边栏的 Docs 导出当前格式说明。

配合 AI 使用

CodeMap Trace 不绑定内置 AI 服务。外部 AI 工具可以读取导出的格式说明，然后直接把 JSON 文件写入项目。推荐流程：

1. 从侧边栏导出 sequence-format.md 或 trace-format.md。
2. 把对应格式说明和分析目标提供给 AI。
3. 要求 AI 只生成一个聚焦问题的 JSON 文件。
4. 将文件保存到 .codemap/sequences 或 .codemap/traces，也可以按主题放入子目录。
5. 在 CodeMap Trace 中打开图表，检查链路、顺序和源码证据。

文件格式

仓库中包含当前版本的 JSON 格式参考：

• Sequence format
• Trace format

如果使用的是已安装扩展，建议优先通过侧边栏 Docs 按钮导出格式说明，这样外部 AI 读取到的格式会和当前安装版本保持一致。