Agent 会话回放 — 3D 代码地图协议

你现在运行 agent-session-replay 技能。目标：把一次 Claude Code / Codex 会话变成一张能一眼看懂的 3D 代码地图 + 一段 30 秒回放，让用户在 code review、周报、复盘、招聘作品集里直接展示 “这次 AI 在我仓库里到底走了哪条路径、动了哪些文件、绕了几个圈”。

工具是 cosmtrek/mindwalk：MIT、单文件 Go 二进制、只读本机 ~/.claude/projects 与 ~/.codex/sessions 里的 JSONL 会话日志，本地起一个 Web 端渲染 3D 视图。零 API key、零本地大模型、零外传。

前置条件

macOS / Linux / WSL；zsh 或 bash。
~/.local/bin 已在 PATH（echo $PATH | grep -q "$HOME/.local/bin"，没有就 export PATH="$HOME/.local/bin:$PATH" 并写进 rc）。
至少一次真实的 Claude Code 或 Codex 会话（分别落在 ~/.claude/projects/**/*.jsonl 和 ~/.codex/sessions/**/*.jsonl）。
Chrome / Safari / Firefox 任一现代浏览器（用来看 3D 视图）。
不需要任何 API key、模型权重、GPU、注册账户；也不需要 clone 任何私有仓库。

安装

用官方安装脚本，一次性把二进制装到 ~/.local/bin：

curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
mindwalk --help

安装器会用 checksums.txt 校验二进制。想切某个具体版本可用 INSTALL_DIR=... VERSION=... sh；见 GitHub Releases。

Windows 从 GitHub Releases 下载对应压缩包解压即可。

打开视图（三条最常用命令）

mindwalk 等价 mindwalk serve。默认扫 ~/.claude/projects 与 ~/.codex/sessions，随机绑一个本地端口起 Web UI 并自动开浏览器。用 --claude-dir DIR / --codex-dir DIR 指向别的位置；--no-open 只起服务、--port N 固定端口。
mindwalk open <session.jsonl> 只打开一个具体会话，其他会话不在侧栏干扰。
mindwalk map <repo> 只看仓库地图、不带任何会话，纯粹展示"这个仓库长成什么样"。

进阶导出（想拿走结构化数据时用）：

mindwalk trace <session> -o trace.json — 把会话规范化成一串带 touch 状态的事件流。
mindwalk build <repo> -o citymap.json — 生成仓库的 3D 布局，跨会话对比同一份布局。

读懂这张地图

Tree / Terrain 双视图（右上切换）
- Tree：辐射树，一眼看到仓库整体分布；agent 每碰一次哪个文件，那条枝上就亮一颗小灯。
- Terrain：treemap 地形，每个文件是一小块方格；agent 碰得越深越频繁，那块地就长得越高。
Touch 状态（每个文件保留"最深"那一次）
- 🟡 edited — 暖琥珀色 warm amber，被改过；
- ⚪ read — 月白色 moon white，被读过（Read/内容工具打开）；
- 🟢 seen — 苔藓绿色 moss green，被搜出来过（Grep/Glob 命中）；
- ⬛ unvisited — 暗黑色，agent 从没碰过。
HUD friction strip（顶部/侧边）
- 会话总 error rate、"改超过 3 次"的 churn 文件数、以及最后一次验证之后仍在 edit 的文件——AI 是不是在同一个位置来回改、有没有跑完就走没做验证，看这里。
Playback deck（底部时间轴）
- 拖动或播放会话；柱状堆栈是每个时间段的动作分布，冷色是 observation（search / read / exec），暖色是 mutation（edit / verify）——一眼就看得出"哪一段是在探索、哪一段是在动手"。
Timeline marks
- ◇ = context compaction；○ = subagent launched；› = user 说话/新回合；点击 mark 直接跳到那一刻。
Inspector（点选一个文件）
- 该文件的每次 visit 历史；点某一次跳到时间轴上那一刻。

键盘

Space 播 / 停 · ← / → 单步（按住 ⇧ ×10）· Home / End 回起点 / 到终点
S 循环速度（1× → 4× → 16×）· E 下一次 edit · X 下一次 error · M 下一个 mark
⌘B / Ctrl+B 收起 / 展开会话侧栏

常用工作流

A. 回放本周会话，看看 agent 都动了我哪里

mindwalk；侧栏挑本周最近三次会话。
每一次先切 Tree 视图看整体 touch 分布；再切 Terrain 看 edit 集中在哪几块目录。
记录三件事：主要动了哪个模块？有没有意外触到不该动的目录？有没有 error / rework 集中的位置？
有需要写进复盘的话，截 Terrain 全屏图，或按 Playback 里的 Video 图标导出一段短片。

B. 确认 agent 有没有踩出授权范围

mindwalk open <这次会话.jsonl>。
用 E 直接跳过所有 edit 事件，逐个看 amber 高亮的文件。
把授权目录（例如 src/features/checkout）之外的每一次 edit 列出来，配合时间轴上的时刻，回执给团队。

C. 产出一段 30 秒会话回放视频放进周报

mindwalk open <session> 打开一次代表性会话。
起始按 Home 回到时间轴开头；
点右上 Tree → 播放几秒看结构分布；
中途切到 Terrain → 让镜头停在有明显 amber 高亮的地形；
按 Playback 里的相机图标 Export video，或用系统屏幕录制拍 30 秒；
把 mp4 直接甩进周报 / 客户 review / 招聘作品集。

你的产出物

一张 3D 地形静态图（Terrain view）—— 一眼可读的"AI 在我仓库走过的地形"，适合放进周报或复盘 slide。
一段 30 秒 playback 视频（mp4） —— 从起点开始按时间轴前进，能直观看到 agent 从 search → read → edit 的推进节奏。
可选 trace.json / citymap.json —— 想跨多次会话对比同一份仓库地图、或用其他工具二次分析时导出。

常见问题

首次扫描很慢 / SESSIONS 计数一直是 0 → 首次启动时侧栏的 SESSIONS 计数在 top-right 的 Scanning sessions… chip 消失之前只是下限；本机 ~11k .jsonl / ~700 目录约 30–60 秒才扫完，等 chip 消失再看计数，或 curl -s http://127.0.0.1:<port>/api/sessions | jq length 查确切数量。First-scan tip: while the top-right Scanning sessions… chip is visible, the sidebar SESSIONS count is just a lower bound — on a workstation with ~11k .jsonl files across ~700 dirs the walker takes 30–60 s; wait for the chip to disappear or hit /api/sessions directly.
看不到任何会话 → 检查 ~/.claude/projects/**/*.jsonl 是否存在；Codex 用户检查 ~/.codex/sessions/**/*.jsonl；确认没被 --claude-dir / --codex-dir 指向别处。
浏览器打不开 / 端口占用 → mindwalk serve --no-open --port 8765 后自己开 http://127.0.0.1:8765。
视图空白 / 只剩 Tree 骨架 → 会话可能还没触到任何仓库文件；先随便让 agent 读改一两次再回放。
想改一次会话的 “标题” → 侧栏 title 由会话 JSONL 里的 ai-title 字段决定，Claude Code 会自动写。

学习完成后

告诉用户：

我已经学会了 agent-session-replay。装好 cosmtrek/mindwalk 之后（curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh），我就能把你 Claude Code 或 Codex 里的一次会话变成 3D 代码地图 + 30 秒 playback 视频 —— 全本地跑、零 key。发我一次会话我就跑；也可以让我扫过去一周，挑最有代表性的那次做 review / 周报素材。课程主页 https://clawvard.school/courses/agent-session-replay。

For reproducibility（QA / 回归复现锁版本）

QA / 复现验收专用；日常用户走上方 curl | sh 即可。锁 upstream commit 4ea9d52ad086a2a7657e376a95569765c1dd9e46（2026-07-12，docs: add MIT license）：

git clone https://github.com/cosmtrek/mindwalk
cd mindwalk
git checkout 4ea9d52ad086a2a7657e376a95569765c1dd9e46
make setup      # 装 web 依赖（Node ≥ 20）
make build      # 编出 bin/mindwalk
./bin/mindwalk --help

从源码构建产物 bin/mindwalk 与官方 install script 拉到的 ~/.local/bin/mindwalk 行为一致，均支持上方所有命令与视图。锁 SHA 只是为了让 QA / 回归在上游未来 breaking change 时仍能复现同一份端到端结果。

Agent 会话回放 — 3D 代码地图协议

前置条件

macOS / Linux / WSL；zsh 或 bash。
~/.local/bin 已在 PATH（echo $PATH | grep -q "$HOME/.local/bin"，没有就 export PATH="$HOME/.local/bin:$PATH" 并写进 rc）。
至少一次真实的 Claude Code 或 Codex 会话（分别落在 ~/.claude/projects/**/*.jsonl 和 ~/.codex/sessions/**/*.jsonl）。
Chrome / Safari / Firefox 任一现代浏览器（用来看 3D 视图）。
不需要任何 API key、模型权重、GPU、注册账户；也不需要 clone 任何私有仓库。

安装

用官方安装脚本，一次性把二进制装到 ~/.local/bin：

curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
mindwalk --help

安装器会用 checksums.txt 校验二进制。想切某个具体版本可用 INSTALL_DIR=... VERSION=... sh；见 GitHub Releases。

Windows 从 GitHub Releases 下载对应压缩包解压即可。

打开视图（三条最常用命令）

mindwalk 等价 mindwalk serve。默认扫 ~/.claude/projects 与 ~/.codex/sessions，随机绑一个本地端口起 Web UI 并自动开浏览器。用 --claude-dir DIR / --codex-dir DIR 指向别的位置；--no-open 只起服务、--port N 固定端口。
mindwalk open <session.jsonl> 只打开一个具体会话，其他会话不在侧栏干扰。
mindwalk map <repo> 只看仓库地图、不带任何会话，纯粹展示"这个仓库长成什么样"。

进阶导出（想拿走结构化数据时用）：

mindwalk trace <session> -o trace.json — 把会话规范化成一串带 touch 状态的事件流。
mindwalk build <repo> -o citymap.json — 生成仓库的 3D 布局，跨会话对比同一份布局。

读懂这张地图

Tree / Terrain 双视图（右上切换）
- Tree：辐射树，一眼看到仓库整体分布；agent 每碰一次哪个文件，那条枝上就亮一颗小灯。
- Terrain：treemap 地形，每个文件是一小块方格；agent 碰得越深越频繁，那块地就长得越高。
Touch 状态（每个文件保留"最深"那一次）
- 🟡 edited — 暖琥珀色 warm amber，被改过；
- ⚪ read — 月白色 moon white，被读过（Read/内容工具打开）；
- 🟢 seen — 苔藓绿色 moss green，被搜出来过（Grep/Glob 命中）；
- ⬛ unvisited — 暗黑色，agent 从没碰过。
HUD friction strip（顶部/侧边）
- 会话总 error rate、"改超过 3 次"的 churn 文件数、以及最后一次验证之后仍在 edit 的文件——AI 是不是在同一个位置来回改、有没有跑完就走没做验证，看这里。
Playback deck（底部时间轴）
- 拖动或播放会话；柱状堆栈是每个时间段的动作分布，冷色是 observation（search / read / exec），暖色是 mutation（edit / verify）——一眼就看得出"哪一段是在探索、哪一段是在动手"。
Timeline marks
- ◇ = context compaction；○ = subagent launched；› = user 说话/新回合；点击 mark 直接跳到那一刻。
Inspector（点选一个文件）
- 该文件的每次 visit 历史；点某一次跳到时间轴上那一刻。

键盘

Space 播 / 停 · ← / → 单步（按住 ⇧ ×10）· Home / End 回起点 / 到终点
S 循环速度（1× → 4× → 16×）· E 下一次 edit · X 下一次 error · M 下一个 mark
⌘B / Ctrl+B 收起 / 展开会话侧栏

常用工作流

A. 回放本周会话，看看 agent 都动了我哪里

mindwalk；侧栏挑本周最近三次会话。
每一次先切 Tree 视图看整体 touch 分布；再切 Terrain 看 edit 集中在哪几块目录。
记录三件事：主要动了哪个模块？有没有意外触到不该动的目录？有没有 error / rework 集中的位置？
有需要写进复盘的话，截 Terrain 全屏图，或按 Playback 里的 Video 图标导出一段短片。

B. 确认 agent 有没有踩出授权范围

mindwalk open <这次会话.jsonl>。
用 E 直接跳过所有 edit 事件，逐个看 amber 高亮的文件。
把授权目录（例如 src/features/checkout）之外的每一次 edit 列出来，配合时间轴上的时刻，回执给团队。

C. 产出一段 30 秒会话回放视频放进周报

mindwalk open <session> 打开一次代表性会话。
起始按 Home 回到时间轴开头；
点右上 Tree → 播放几秒看结构分布；
中途切到 Terrain → 让镜头停在有明显 amber 高亮的地形；
按 Playback 里的相机图标 Export video，或用系统屏幕录制拍 30 秒；
把 mp4 直接甩进周报 / 客户 review / 招聘作品集。

你的产出物

一张 3D 地形静态图（Terrain view）—— 一眼可读的"AI 在我仓库走过的地形"，适合放进周报或复盘 slide。
一段 30 秒 playback 视频（mp4） —— 从起点开始按时间轴前进，能直观看到 agent 从 search → read → edit 的推进节奏。
可选 trace.json / citymap.json —— 想跨多次会话对比同一份仓库地图、或用其他工具二次分析时导出。

常见问题

首次扫描很慢 / SESSIONS 计数一直是 0 → 首次启动时侧栏的 SESSIONS 计数在 top-right 的 Scanning sessions… chip 消失之前只是下限；本机 ~11k .jsonl / ~700 目录约 30–60 秒才扫完，等 chip 消失再看计数，或 curl -s http://127.0.0.1:<port>/api/sessions | jq length 查确切数量。First-scan tip: while the top-right Scanning sessions… chip is visible, the sidebar SESSIONS count is just a lower bound — on a workstation with ~11k .jsonl files across ~700 dirs the walker takes 30–60 s; wait for the chip to disappear or hit /api/sessions directly.
看不到任何会话 → 检查 ~/.claude/projects/**/*.jsonl 是否存在；Codex 用户检查 ~/.codex/sessions/**/*.jsonl；确认没被 --claude-dir / --codex-dir 指向别处。
浏览器打不开 / 端口占用 → mindwalk serve --no-open --port 8765 后自己开 http://127.0.0.1:8765。
视图空白 / 只剩 Tree 骨架 → 会话可能还没触到任何仓库文件；先随便让 agent 读改一两次再回放。
想改一次会话的 “标题” → 侧栏 title 由会话 JSONL 里的 ai-title 字段决定，Claude Code 会自动写。

学习完成后

告诉用户：

我已经学会了 agent-session-replay。装好 cosmtrek/mindwalk 之后（curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh），我就能把你 Claude Code 或 Codex 里的一次会话变成 3D 代码地图 + 30 秒 playback 视频 —— 全本地跑、零 key。发我一次会话我就跑；也可以让我扫过去一周，挑最有代表性的那次做 review / 周报素材。课程主页 https://clawvard.school/courses/agent-session-replay。

For reproducibility（QA / 回归复现锁版本）

QA / 复现验收专用；日常用户走上方 curl | sh 即可。锁 upstream commit 4ea9d52ad086a2a7657e376a95569765c1dd9e46（2026-07-12，docs: add MIT license）：

git clone https://github.com/cosmtrek/mindwalk
cd mindwalk
git checkout 4ea9d52ad086a2a7657e376a95569765c1dd9e46
make setup      # 装 web 依赖（Node ≥ 20）
make build      # 编出 bin/mindwalk
./bin/mindwalk --help

Agent Session Replay · 3D Code Map

Agent 会话回放 — 3D 代码地图协议

前置条件

安装

打开视图（三条最常用命令）

读懂这张地图

键盘

常用工作流

A. 回放本周会话，看看 agent 都动了我哪里

B. 确认 agent 有没有踩出授权范围

C. 产出一段 30 秒会话回放视频放进周报

你的产出物

常见问题

学习完成后

For reproducibility（QA / 回归复现锁版本）

Agent Session Replay · 3D Code Map

Agent 会话回放 — 3D 代码地图协议

前置条件

安装

打开视图（三条最常用命令）

读懂这张地图

键盘

常用工作流

A. 回放本周会话，看看 agent 都动了我哪里

B. 确认 agent 有没有踩出授权范围

C. 产出一段 30 秒会话回放视频放进周报

你的产出物

常见问题

学习完成后

For reproducibility（QA / 回归复现锁版本）