Mindwalk：3D地图回放AI编码智能体会话

背景

编码代理（coding agent）在执行任务时会生成 session log，记录每一步操作，但日志无法反映代理对任务的理解：哪些代码文件被它视为相关？它在行动前探索了哪些区域？其行为足迹是否与你预期的范围一致？逐行阅读原始的 JSONL 文件显然无法回答这些问题。现有的日志分析方式缺乏直观的可视化手段，难以让开发者快速把握代理的思维过程和行为模式。

核心内容

Mindwalk 是一个可视化工具，它能在代码库的3D地图上重放编码代理的会话，让代理的理解过程变得可见。其核心思路是将仓库绘制成一幅夜间地图（night map），会话回放时，代理搜索、读取和编辑过的区域会发光，其余区域保持黑暗，从而在一瞥之间看出代理对任务的认知形状。

工具由单个 Go 二进制文件构成，解析 Claude Code 和 Codex 的会话日志，完全本地运行，会话数据不会离开你的机器。安装与使用非常简洁：

curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
mindwalk

安装器会通过 checksums.txt 验证二进制文件，默认安装到 ~/.local/bin（可通过 INSTALL_DIR 覆盖安装目录，通过 VERSION 指定版本）。Windows 的归档文件可从 GitHub Releases 获取。从源码构建的方式为 make setup && make build，生成 bin/mindwalk。

无参数运行时，mindwalk 会扫描 ~/.claude/projects 和 ~/.codex/sessions，在随机本地端口启动 UI 并打开浏览器。支持以下子命令：

• mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR]：启动服务。
• mindwalk open [--no-open] <session.jsonl>：打开特定会话。
• mindwalk build <repo> [-o out]：生成仓库的城市地图 JSON。
• mindwalk trace <session> [-o out]：生成归一化的轨迹 JSON。

Mindwalk 提供了多种视图和交互功能：

• 树/地形视图（Tree / Terrain views）：仓库呈现为径向树（radial tree）或简洁的树地图（treemap），文件发光强度与访问深度和频率成正比。
• 触摸状态（Touch states）：每个文件保留其最深的接触状态：看到（苔绿色）、读取（月光白）、编辑（暖琥珀色）、未访问（暗色）。HUD 将摩擦信号——错误率、被反复修改的文件、最后一次验证后的编辑——整合成一条审查条（review strip）。
• 播放控制（Playback deck）：可通过滑块或播放按钮控制会话重放，时间轴采用桶状直方图显示运行时间。直方图的色条从冷色到暖色：观察行为（搜索、读取、执行）保持冷色，突变行为（编辑、验证）变为暖色，编辑阶段一目了然。
• 时间线标记（Timeline marks）：◊ 表示上下文压缩，○ 表示子代理启动，› 表示用户转向。每个标记都可点击跳转。
• 检查器（Inspector）：点击文件可固定其访问历史，点击访问行可将播放头跳转到对应时刻。
• 键盘快捷键：空格（播放/暂停）、←/→（步进，Shift+×10）、Home/End（首尾）、S（速度）、E（下一编辑）、X（下一错误）、M（下一标记）、Cmd+B（会话轨道）。

Mindwalk 内部保持两个独立构件：

• 轨迹（trace）——将会话日志归一化为有序的文件触摸事件流（internal/adapter 中每种代理格式对应一个适配器）。
• 城市地图（citymap）——仓库的确定性布局（internal/citymap）；同一棵树总是生成相同的地图，因此不同会话的回放具有可比性。

本地 Go 服务器（internal/server）将二者连接并服务于 React/Three.js 前端（web）。schema/ 目录镜像了导出的 JSON 契约。项目欢迎 Issue 和 PR，开发环境搭建：make setup（安装前端依赖）、make serve（开发服务器在 :8765）、make test（Go 测试 + 前端构建，提 PR 前运行）、make build（重新生成嵌入资源和二进制文件）。项目的基本规则包括：保持边界清晰（适配器不感知渲染，城市地图生成不依赖回放，服务器仅连接二者）；Go 代码通过 gofmt 格式化；不手动编辑 internal/server/static，而是通过 make build 重新生成；当 trace 或 citymap JSON 结构变更时，需同步更新 schema/ 及相关测试。

关键要点

• 可视化方式：将代码仓库转化为3D夜间地图，代理的搜索、读取、编辑行为以光点移动呈现，直观反映代理的重点区域。
• 完全本地运行：单个 Go 二进制文件，会话数据不离开用户机器，保护隐私。
• 支持两种热门代理：兼容 Claude Code 和 Codex 的会话日志格式。
• 双视图：径向树视图（Tree View）和树地图视图（Terrain View），发光强度关联文件被访问的深度与频率。
• 触摸状态颜色编码：苔绿色（看到）、月光白（读取）、暖琥珀色（编辑）、暗色（未访问），HUD 整合错误率等摩擦信号为审查条。
• 回放与时间轴：支持播放/暂停、步进、跳转，直方图使用冷暖色区分观察行为和突变行为，编辑阶段高亮。
• 时间线标记：上下文压缩、子代理启动、用户转向均可点击跳转，方便快速导航。
• 检查器与键盘快捷键：可查看单个文件的访问历史，并使用键盘快捷键高效控制回放。
• 确定性城市地图：相同树结构生成相同布局，保证不同会话间的回放可比性。
• 架构清晰：轨迹（trace）和城市地图（citymap）分离，适配器、服务器、前端职责独立，便于扩展和贡献。

意义与影响

Mindwalk 填补了编码代理行为理解工具的空缺。传统的 session log 是线性的文本记录，面对复杂探路和编辑任务时，开发者难以直观判断代理是否合理利用代码库。Mindwalk 将抽象的操作序列转化为空间和光的语言，让“代理如何理解任务”这一隐式信息变得可观察、可比较。这有助于调试代理行为、优化提示词或任务拆分，并让团队成员在审查代理输出时拥有共同的视觉参考。同时，工具完全本地运行且开源，降低了隐私顾虑和集成门槛。随着编码代理在开发工作流中的普及，类似 Mindwalk 的可视化调试工具将成为提升代理透明度和可信赖度的重要基础设施。