企业官网建设流程全解析

mindwalk 是一个开源的 AI 编程会话可视化工具：它能把 Claude Code、Codex 等 coding agent 的会话日志，回放到一张由你的仓库生成的3D 代码地图上。Agent 搜索过哪里、读过哪些文件、改动了什么，地图会随之发光——其余部分保持黑暗。一眼就能看清 Agent 对任务的理解是否跑偏，AI 编程过程不再是黑盒 🌃

AI编程的黑盒问题：Agent会话日志为什么难读

用 Claude Code、Codex 这类 AI 编程助手时，你常会遇到这样的困惑：

• Agent 说"已完成修复"，但它到底看了哪些文件？
• 它的探索范围是否符合你的预期，还是满仓库乱逛？
• 报错几次？改了又改的文件（churned files）有多少？

会话日志（JSONL）只记录了 Agent做了什么，却无法回答它如何理解任务：把原始日志逐行读一遍，这些疑问一个也回答不了。

mindwalk 的思路很巧妙：把仓库画成一张夜景地图，把会话回放成光在地图上移动——Agent 搜索、读取、编辑过的地方亮起来，其他区域保持黑暗。Agent 对任务的理解，变成了一个你一眼就能看出的形状。

mindwalk快速安装：3步本地跑起3D代码地图

mindwalk 是一个纯 Go 编写的单二进制程序，完全本地运行，浏览会话不会向任何地方发送数据。

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/mi/mindwalk cd mindwalk # 2. 构建（安装前端依赖并生成 bin/mindwalk） make setup make build # 3. 启动 ./bin/mindwalk

不带任何参数直接运行mindwalk时，它会自动扫描~/.claude/projects和~/.codex/sessions下的会话记录，在本地随机端口启动 UI 并打开浏览器。

常用命令一览：

更完整的说明见 README.md，官方安装脚本为 scripts/install.sh。

读懂3D代码地图：颜色、高度与播放台

打开回放界面后，地图提供Tree（径向树）和Terrain（方块城市）两种视图，方块越高、越亮，代表该文件被触碰得越深、频率越高。

文件触碰状态：一眼看懂Agent行为

每个文件保留它在整个会话中最深的一次触碰状态：

播放台与时间轴

底部的**播放台（Playback Deck）**支持拖动进度条、变速、回放，甚至把整个回放导出为.webm视频（纯客户端完成）。直方图柱体按冷/暖色谱着色：观测类事件（search、read、exec）保持冷色，变更类事件（edit、verify）呈现暖色——编辑阶段会直接"跳"出来。

时间轴上的标记也都可以点击跳转：◇上下文压缩、○子 Agent 启动、›用户发言轮次。

回放Agent会话：像导演一样审视每一次文件触碰

几个高价值操作，帮你快速定位问题：

• 点击文件：固定它的访问历史（Inspector 面板），再点击某条访问记录，播放头会直接跳到那一刻；
• 快捷键：Space播放/暂停、←/→单步（⇧×10 步）、E跳到下一个编辑、X跳到下一个错误、M跳到下一个标记；
• REVIEW 条：HUD 会把摩擦信号——错误率、被反复修改的文件数、最后一次验证之后的改动——折叠成一条"审查条"，例如"~27 errors · 7 files edited 3+ times"，提示你重点复核。

当会话启动了多个子 Agent 时，HUD 会显示子 Agent 数量，并打开Agents 面板：选择一个"镜头（lens）"，即可在同一张地图上回放任意一个子 Agent 的完整轨迹，再切回主轨迹。这对排查"多 Agent 协作到底谁干了什么"极其有用。

Session evaluation：让本地Agent给你的会话当裁判

除了"看"，mindwalk 还能"评"。在 UI 的 Evaluate 面板执行mindwalk analyze，它会调用你本机的claude或codexCLI 作为裁判，评估这次会话的探索质量、范围控制、是否乱逛、是否做了验证——每一条结论都锚定在可点击跳转的时间轴事件上。

隐私边界很清晰：

• 仅在你明确发起评估时，才会把该会话的摘要（任务措辞、文件路径、单行事件摘要）发给你自己账号背后的模型；
• 裁判子进程是"密封"的：无工具、无 MCP、无用户配置、无会话持久化；
• 评估报告缓存在~/.mindwalk/reports，会话内容变化后报告标记为过期，但绝不自动重跑。

mindwalk工作原理：trace、citymap与report三大构件

mindwalk 有意把三种产物保持独立，这也是它跨会话可比的前提：

1. trace（会话轨迹）——把 Agent 日志归一化为有序的文件触碰事件流，并关联子 Agent 会话形成 Agent 图，实现位于 internal/adapter/，Claude Code 与 Codex 各有独立适配器；
2. citymap（城市地图）——仓库的确定性布局，同一棵树永远生成同一张地图，实现位于 internal/citymap/；
3. report（评估报告）——LLM 裁判基于证据的发现，结论始终由严重程度机械汇总，实现位于 internal/judge/。

本地 Go 服务（internal/server/）把三者拼接后，交给 React + Three.js 前端（web/src/scene/CityScene.tsx）渲染。三类 JSON 契约的 schema 文件在 schema/ 下，想深入原理可以配合 AGENTS.md 阅读。

常见问题FAQ

会泄露我的代码吗？浏览和回放完全本地进行，不发送任何数据；唯一例外是你主动发起的会话评估，且只发送单次会话摘要。

支持哪些Agent？Claude Code 与 Codex 的会话日志，后续新格式会通过 adapter 边界接入。

可以只看不回放吗？可以，mindwalk map <repo>直接渲染任意仓库的 citymap，此时高度编码的是代码行数而非关注度。

💡小结：AI 编程的瓶颈往往不在"Agent 能不能干活"，而在"你敢不敢信它怎么干的"。mindwalk 用一张发光的 3D 代码地图，把 Agent 的每一步探索变成可见的光影轨迹——从黑盒到透明，只差一次make build。