Mindwalk：在代码库 3D 地图上回放编码代理会话

mindwalk

一个可视化工具，在代码库的 3D 地图上回放编程智能体的会话过程。

mindwalk-demo-en-tree-60s.mp4

问题所在

会话日志记录了智能体做了什么，却没有记录它是如何理解任务的：它把仓库的哪些部分视为相关，在行动之前探索了哪里，它的足迹是否与你心目中的范围相符。逐行阅读原始 JSONL 无法回答其中任何一个问题。

思路

把仓库画成一张夜景地图，将会话回放为在其中移动的光：智能体搜索、读取和编辑过的地方，地图就会亮起——其余部分则保持黑暗。智能体对任务的理解由此变成一眼可见的形状。一个 Go 二进制文件即可读取 Claude Code 和 Codex 的会话日志，完全本地运行；查看不会向任何地方发送数据。唯一的例外是可选的会话评估：当你显式运行它时，该会话的摘要（任务措辞、文件路径、事件摘要）会被发送到你自己的 claude 或 codex CLI 背后的模型——参见会话评估。

快速开始

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>   open one specific session
mindwalk map [--no-open] <repo>             open a repository map, no session needed
mindwalk build <repo> [-o out]              write the repository citymap JSON
mindwalk trace <session> [-o out]           write the normalized trace JSON
mindwalk analyze <session> [--judge claude|codex] [--model name]
                                            evaluate one session (see below)

读懂这张图

树形 / 地形视图 —— 将仓库呈现为放射状树或纯矩形树图；光晕 ∝ 某个文件被触及的深度和频率。
触及状态 —— 每个文件保留其最深的触及状态：见过（苔藓绿）、读过（月光蓝）、编辑过（暖琥珀色）、未访问（深色）。本次会话触及但已不在仓库中的文件，会以线框幽灵的形式留存。HUD 将摩擦信号——错误率、反复改动的文件、最后一次验证之后的编辑——折叠成一条审查条。
回放面板 —— 在按时间分桶的运行直方图上拖动或播放整个会话。柱条落在冷/暖光谱上：观察保持冷色（搜索、读取、执行），变更发出暖色（编辑、验证），因此编辑阶段一眼就能跳出来。重启、速度和视频导出都折叠进面板的 ⋯ 菜单；导出会完全在客户端将回放录制为 .webm。
时间线标记 — ◇ 上下文压缩、○ 子智能体启动、› 用户轮次；每个标记都是可点击跳转的目标。
智能体视角 — 当某个会话启动了子智能体时，HUD 会显示子智能体数量和一个智能体面板：选择一个视角即可在同一张地图上回放任意子智能体的轨迹，然后退回主轨迹。
检查器 — 点击一个文件即可固定其访问历史；点击某一行访问记录即可将播放头跳转到该时刻。
评估 — 让本地智能体 CLI 评判该会话的轨迹；会话行会以一个低调的徽章显示评估状态。参见会话评估。
仓库地图 — mindwalk map <repo>（或会话侧栏中的文件夹图标）可在不附加任何会话的情况下渲染任意仓库的城市地图；高度编码的是代码行数而非注意力。

键盘：Space 播放/暂停 · ←/→ 步进（⇧ ×10）· Home/End 跳至两端 · S 速度 · V 视图 · E 下一处编辑 · X 下一个错误 · M 下一个标记 · ⌘B 会话侧栏。

会话评估

评估面板（以及 mindwalk analyze）会调用本地智能体 CLI 来评判本次会话进行得如何——探索、范围、游移、验证——每一条发现都锚定到可点击跳转的时间线事件上。在面板中选择评判者（任意已安装的 CLI）及其模型；报告会记录实际由谁进行了评判。

什么会离开你的机器，且仅在你主动请求时：评估会运行你自己的 claude 或 codex CLI，它会将该会话的摘要——用户消息的措辞、文件路径以及单行事件摘要——发送到你账户背后的模型。查看会话时不会发送任何内容，也不会包含其他会话。评判子进程以封闭方式运行：无工具、无 MCP 服务器、无用户或项目设置，也不保留会话持久化。

报告缓存在 ~/.mindwalk/reports 中，每个会话一份；当会话内容发生变化时，报告会过期（绝不自动重新运行）。

底层原理

三种产物，刻意保持彼此分离：

一份 trace——将会话日志规范化为有序的文件触碰事件流（internal/adapter，每种智能体格式对应一个适配器）；适配器还会将子智能体会话关联为智能体图，因此每个子智能体的 trace 都可以单独回放；
一份 citymap——仓库的确定性布局（internal/citymap）；同一棵树始终生成相同的地图，因此回放可在不同会话之间进行比较；
一份报告——由 LLM 裁判给出的、针对某一次会话的、以证据为依据的结论（internal/judge）；裁判只负责提供结论，最终判定始终以机械方式汇总，因此报告之间也保持可比性。

一个本地 Go 服务器（internal/server）将它们连接起来，并为 React/Three.js 前端（web）提供服务。schema/ 镜像了导出的 JSON 契约。

贡献

欢迎提交 issue 和 pull request。要搭建一个可用的开发环境：

make setup   # install frontend dependencies
make serve   # dev server on :8765, serving web/dist from the working tree
make test    # go test + frontend build — run before sending a PR
make build   # regenerate embedded assets and bin/mindwalk

基本规则（完整架构说明见 AGENTS.md）：

保持边界清晰：适配器不了解渲染，citymap 生成不依赖回放，裁判只读取规范化后的 trace，服务器只负责把各部分连接起来。
Go 代码保持 gofmt 化；绝不手动编辑 internal/server/static——用 make build 重新生成它。
当 trace、citymap 或 report 的 JSON 结构发生变化时，在同一次变更中更新 schema/ 以及相关测试。

Star 历史

Star History Chart