cosmtrek/mindwalk

# mindwalk 一款可视化工具，能在代码库的 3D 地图上重现 coding-agent 的会话过程。 https://github.com/user-attachments/assets/6490cd77-0374-4f36-a6e7-24267d5c61f3 *30 秒演示 —— 请打开声音。* ## 问题所在 会话日志记录了 agent 做了什么，却没记录它是如何理解任务的： 它将代码库的哪些部分视为相关，在采取行动前它在哪里进行了探索， 以及它留下的痕迹是否与你预期的范围一致。逐行阅读原始的 JSONL 文件 根本无法回答这些问题。 ## 核心理念 将代码库绘制成一幅夜景地图，并以光线在其中移动的形式重放会话过程： 在 agent 搜索、读取和编辑过的地方，地图会亮起 —— 其他地方则保持黑暗。 agent 对任务的理解程度变成了一眼即可看穿的轮廓。一个 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](https://github.com/cosmtrek/mindwalk/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 ``` ## 读懂图表 - **Tree / Terrain 视图** —— 代码库呈现为径向树状图或矩形树状图平原； 发光程度 ∝ 文件被触及的深度和频次。 - **触碰状态** —— 每个文件保留其最深度的触碰状态：seen（苔藓绿）、 read（月光白）、edited（暖琥珀色）、unvisited（暗色）。HUD 会将摩擦信号 —— 错误率、频繁变动的文件、最后一次 verify 之后的 edits —— 整合到审查条中。 - **回放面板** —— 在按运行时间分桶的直方图上拖拽或播放会话。 柱状图采用冷/暖色调：观察类操作保持冷色调（search、read、exec）， 修改类操作则呈暖色调发光（edit、verify），让编辑阶段一目了然。 - **时间轴标记** —— `◇` 表示 context 压缩，`○` 表示 subagent 启动， `›` 表示用户交互回合；每个标记都可以点击跳转。 - **Inspector（检查器）** —— 点击文件以固定其访问历史；点击访问记录行可将 播放指针跳转到对应时刻。  快捷键：`Space` 播放/暂停 · `←`/`→` 单步（`⇧` 按住快进 10 倍） · `Home`/`End` 跳转首尾 · `S` 速度 · `E` 下一个 edit · `X` 下一个错误 · `M` 下一个标记 · `⌘B` 会话栏。 ## 底层原理 由两个刻意分离的构件组成： 1. **trace** —— 会话日志被规范化为有序的 文件触碰事件流（`internal/adapter`，每种 agent 格式对应一个 adapter）； 2. **citymap** —— 代码库的确定性布局 （`internal/citymap`）；相同的树状结构始终生成相同的地图， 因此不同会话的重放结果具有可比性。 一个本地 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](AGENTS.md)）： - 保持边界清晰：adapter 不涉及渲染逻辑，citymap 生成 不依赖于回放机制，服务器仅负责连接两者。 - 保持 Go 代码经过 `gofmt` 格式化；切勿手动修改 `internal/server/static` —— 请使用 `make build` 重新生成。 - 当 trace 或 citymap 的 JSON 结构发生改变时，请同步更新 `schema/` 及相关的 测试。

标签：AI编程助手, EVTX分析, Go语言, Mutation, SOC Prime, 可视化, 开发工具, 日志审计, 程序破解