Mindwalk - 代码库会话回放可视化
将编码代理的会话回放为代码库的3D地图，直观展示代理对任务的理解与探索过程。
证据显示：工具默认本地运行，仅当用户明确运行评估时才发送会话摘要到本地CLI；安装脚本校验checksums；无网络请求。扣分：依赖仅一个jsonschema库，但未提供依赖漏洞扫描或锁定文件细节；回滚机制未明确；发布者身份未验证。
证据显示：README描述与代码结构一致，有CI测试和前端构建验证；依赖为Go标准库和少量第三方，可用性高。扣分：失败消息未在文档中详细说明，错误处理细节未展示。
证据显示：面向开发者，支持多种agent格式和平台（Linux、macOS、Windows、Nix）；能力边界清晰（只读会话日志，评估需显式调用）；触发条件明确（命令行参数）。扣分：环境适配细节（如特定shell、权限）未完全说明。
证据显示：README结构清晰，安装说明详细，命名稳定（命令和参数一致），有示例和FAQ（通过文档和截图），MIT许可证明确。扣分：已知限制未明确列出，版本变更日志未提供，维护责任未明确（发布者未验证）。
证据显示：输出为可视化界面和JSON文件，可直接使用；边际价值高（解决会话理解问题）；成本低（本地运行，免费）。扣分：无成本效益分析，但整体合理。
证据显示：README中的声明与代码结构一致，有测试和CI；文档区分事实和推断（如评估报告）。扣分：跨来源验证不足（仅单一仓库证据）。
- 发布者身份未验证，安装脚本从远程获取，建议检查校验和。
- 评估功能会发送会话摘要到本地CLI，确保理解数据流向。
- 依赖较少，但未提供依赖漏洞扫描，建议定期检查。
这个 Agent 能做什么，适合哪些场景？
Mindwalk 是一个可视化工具，以代码库的 3D「夜景地图」形式回放编码代理的会话日志，让用户直观看到代理在执行任务时搜索、阅读和编辑的轨迹。它读取 Claude Code、Codex 和 pi 的会话日志（本地处理，不发送任何数据），将仓库渲染为树状或矩形树状图，并通过发光强度表示文件被触碰的深度和频率。工具提供播放控制、时间轴标记（上下文压缩、子代理启动、用户回合）、子代理镜头、文件历史检查器以及本地 LLM 评估功能。所有处理均在本地完成，唯一的例外是用户明确运行时才会发送会话摘要给本机 CLI 背后的模型。项目包含一个 Go 服务器和 React/Three.js 前端，通过命令行和浏览器交互。
Mindwalk 将会话日志（如 ~/.claude/projects 下的 JSONL）通过内部适配器（internal/adapter）归一化为有序的文件触碰事件流（trace），并同时关联子代理会话构建代理图。它通过 internal/citymap 为代码库生成确定性的 3D 布局（citymap），将深度和频率编码为发光强度。用户可通过 mindwalk serve 启动本地服务器并自动打开浏览器界面，或使用 mindwalk open <session.jsonl> 打开特定会话、mindwalk map <repo> 渲染仓库地图、mindwalk build 和 mindwalk trace 分别导出 citymap 和 trace 的 JSON。界面支持播放/暂停、速度调整、时间轴跳转、子代理镜头切换、文件点击查看访问历史，并可将回放导出为 .webm 视频。评估功能通过调用本机 claude 或 codex CLI，对会话进行四个固定维度和动态任务评分卡的评估，结果缓存在 ~/.mindwalk/reports。
- 开发者希望快速了解一个大型代码库中，编码代理是如何理解任务、在哪些文件上花费时间，从而评估其工作范围是否符合预期。
- 团队在审查代理生成的代码时，需要可视化代理的执行轨迹，以发现代理是否在无关文件上浪费了时间或忽略了关键部分。
- 在调试代理行为异常时，用户可以通过回放子代理的独立轨迹（agent lenses）来深入分析其决策过程。
- 技术经理或资深开发者需要对多个代理会话进行对比评估，利用一致的评分维度（探索、范围、漫游、验证）和任务特定标准来挑选最佳方案。
- 用户想要在没有会话数据的情况下浏览任意代码库的结构，通过
mindwalk map命令生成仓库的 3D 地图，利用高度表示代码行数。
这个 Agent 有哪些优点和局限？
- 完全本地处理：会话数据不离开机器，除了明确触发的评估（此时发送摘要给本机 CLI 背后的模型），隐私保护强。
- 直观的可视化：3D地图结合发光强度、触摸状态和播放控制，比阅读原始JSONL高效得多，能一眼看出代理的行为模式。
- 多代理支持：原生支持 Claude Code、Codex 和 pi 的会话日志，并可通过子代理镜头单独回放子代理轨迹。
- 可复现的比较：citymap 生成是确定性的，同一仓库始终生成相同地图，使得跨会话比较成为可能。
- 依赖外部代理工具：仅支持已记录的日志格式，对其他代理（如 Gemini、Cursor 等）需要额外适配。
- 安装要求：需要 Go 和 Node.js 环境，且安装脚本需要从网络下载二进制，可能受网络限制。
- 评估功能依赖本地安装的 claude 或 codex CLI，并且评估会消耗模型 API 额度。
- 学习曲线：可视化界面和命令较多，新用户需要一定时间熟悉。
如何安装或部署这个 Agent？
通过脚本安装：运行 curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh，然后设置 export PATH="$HOME/.local/bin:$PATH" 并启动 mindwalk。安装程序会验证校验和并安装到 ~/.local/bin（可通过 INSTALL_DIR 覆盖，VERSION 固定版本）。Windows 用户可从 GitHub Releases 下载。要求 Go 和 Node.js 环境。
如何使用这个 Agent？
直接运行 mindwalk 即可扫描默认目录（~/.claude/projects、~/.codex/sessions、~/.pi/agent/sessions），启动随机端口的 UI 并打开浏览器。常用命令：mindwalk serve --port N --no-open 指定端口；mindwalk open <session.jsonl> 打开特定会话；mindwalk map <repo> 打开仓库地图；mindwalk analyze <session> --judge claude|codex --model name 进行评估。在 UI 中，使用空格播放/暂停、方向键步进、S 调整速度、V 切换视图、E 跳转到下一个编辑、X 下一个错误、M 下一个标记、⌘B 显示会话栏。评估功能会在明确触发时调用本地 CLI，发送会话摘要给模型，并缓存报告。