# Mindwalk：在代码库 3D 地图上回放编码代理会话 - 来源：Hacker News 热门（buzzing.cc 中文翻译） - 作者：cosmtrek - 发布时间：2026-07-12 21:51 - AIHOT 分数：74 - AIHOT 标记：精选 - AIHOT 链接：https://aihot.virxact.com/items/cmrhvwe6k00y7biidjabepmem - 原文链接：https://github.com/cosmtrek/mindwalk ## 精选理由 这个工具把编码代理的会话回放做成 3D 代码地图，一眼就能看出代理探索了哪些文件、在哪里改动最多。如果你是 Claude Code 或 Codex 用户，这是目前最直观地理解代理「脑子里在想什么」的方式。 ## AI 摘要 Mindwalk 是一款可视化工具，可将 Claude Code 和 Codex 的会话日志在代码库的 3D 地图上回放。它将仓库绘制成夜间地图，代理搜索、读取和编辑过的文件会发光，未触及区域保持黑暗，让用户一眼看清代理对任务的理解范围。单个 Go 二进制文件即可运行，所有会话数据完全本地处理，不会离开机器。支持树状图/地形图两种视图，文件触达状态分为未访问、已查看、已读取、已编辑四种颜色标记。播放界面包含错误率、文件修改量等摩擦信号面板，以及上下文压缩、子代理启动、用户交互等时间轴标记。支持键盘快捷键控制播放速度、跳转编辑点或错误点。 ## 正文 mindwalk 一款可视化工具，能在代码库的 3D 地图上回放编码智能体的会话过程。 30 秒演示——请开启声音。 问题所在 会话日志记录了智能体做了什么，但并未体现它如何理解任务：它认为代码库的哪些部分与任务相关，在行动之前探索了哪些区域，它的活动范围是否与你设想的目标范围一致。逐行阅读原始的 JSONL 文件无法回答这些问题。 核心理念 将代码仓库绘制成一幅夜间地图，然后将会话过程以光的形式在地图中回放：智能体搜索、读取和编辑过的地方，地图便会发光——其余部分则保持黑暗。智能体对任务的理解由此变成一种你一眼就能看清的形态。一个 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] open one specific session mindwalk build [-o out] write the repository citymap JSON mindwalk trace [-o out] write the normalized trace JSON 解读画面 树状 / 地形视图——将代码仓库呈现为径向树状图或简单的矩形树状图；发光程度 ∝ 文件被触及的深度和频率。 触及状态——每个文件保留其最深层的触及状态：已查看（苔藓绿）、已读取（月光白）、已编辑（暖琥珀色）、未访问（暗色）。HUD 将摩擦信号——错误率、反复修改的文件、最后一次验证后的编辑——整合到一条审查条中。 回放控制台——可在会话运行的分桶直方图上拖拽或播放。条形图位于冷/暖色光谱上：观察行为保持冷色调（搜索、读取、执行），修改行为呈现暖色调（编辑、验证），因此编辑阶段一目了然。 时间线标记——◇ 上下文压缩、○ 子智能体启动、› 用户交互；每个标记都是可点击跳转的目标。 检查器——点击文件可固定其访问历史；点击某次访问行可将播放头跳转到该时刻。 键盘快捷键：Space 播放/暂停 · ←/→ 单步（⇧ 为 10 倍步进）· Home/End 跳转至首尾 · S 调整速度 · E 跳至下一处编辑 · X 跳至下一个错误 · M 跳至下一个标记 · ⌘B 打开会话侧栏。 底层架构 两个工件，刻意保持分离： 一条轨迹——将会话日志归一化为按序排列的文件触碰事件流（位于 internal/adapter，每种智能体格式对应一个适配器）； 一张城市地图——仓库的确定性布局（位于 internal/citymap）；相同的代码树始终生成相同的地图，因此不同会话间的回放具有可比性。 一个本地 Go 服务器（位于 internal/server）将两者结合，并为 React/Three.js 前端（web 目录）提供服务。schema/ 目录镜像了导出的 JSON 合约。 贡献指南 欢迎提交 Issue 和拉取请求。要搭建可用的开发环境，请按以下步骤操作： 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）： 保持边界清晰：适配器不关心渲染逻辑，城市地图生成不依赖回放功能，服务器仅负责连接两者。 保持 Go 代码符合 gofmt 格式规范；切勿手动编辑 internal/server/static 目录——请使用 make build 命令重新生成。 当轨迹或城市地图的 JSON 结构发生变化时，需在同一变更中同步更新 schema/ 目录及相关的测试文件。