agentplay：把编码 Agent 的会话画成地图回放

编码 Agent 的 transcript 里其实记着一切：改这个文件之前读过哪些文件、哪条命令重试了几次、MCP 服务器在哪里挂掉、上下文窗口什么时候塞满、哪个子智能体空手而归。这些数据就躺在 ~/.claude、~/.codex、~/.cursor 之类的目录里，几乎没人翻。agentplay 是 Entelligence 开源（Apache-2.0）的 Python 工具，把每次会话变成一张径向地图加一条可播放的时间轴，让你看得见 Agent 到底做了什么。仓库 2026 年 10 月 14 日建库，目前 316 Star，今天仍在推送。

核心功能

• 径向会话地图：把仓库、目录、文件（分「看过 / 读过 / 改过」）、shell 动词、MCP 服务器与工具、技能、子智能体、web 主机、错误类别、模型，以及产出（commit、PR、ticket）摊成一张树状地图。
• 可播放的时间轴：支持 1x / 4x / 16x 回放，可在「步骤」与「墙钟时间」两种轴之间切换；泳道分别标出 prompt、错误、延迟、产出、编辑、探索、MCP、技能、工具、模型、成本、token、子智能体与上下文大小，上下文压缩点也有标记。
• 任务与 Agent 视角：一次会话按你给的 prompt 切成若干任务；可以只选某个任务、某个模型或某个子智能体，整个浏览器随之重新聚焦。
• 错误排行：Errors 标签按类别分组，并按「同一条命令连续失败最多次」排序，点一行就把回放跳到那一刻。
• 九个 Agent 的开箱支持：Claude Code、Codex（CLI 与 IDE）、Cursor、GitHub Copilot CLI、VS Code 里的 Copilot、OpenCode、Kiro、Gemini CLI、Antigravity CLI；其中 Claude Code 保真度最高，直接读 JSONL，含 hooks、压缩、停止原因与延迟。
• 零依赖零上传：除标准库外没有运行时依赖，uvx agentplay@latest 一条命令即可；会话数据不离开本机，地图里也不含 prompt 文本、工具输入输出、文件内容或命令参数——shell 命令只记动词（git log，不记 --author=…）。

典型使用场景

• 复盘一次失败的会话：想知道 Agent 为什么改错文件，看地图上它读过的文件列表，比翻几千行 JSONL 快得多。
• 排查工具与 MCP 问题：哪个 MCP 服务器反复失败、哪条命令重试了十几次，Errors 面板直接给出排名。
• 看懂成本花在哪：时间轴上的 token、成本与上下文大小泳道，配合压缩点标记，能看出上下文是在哪一步被撑爆的。
• 把会话分享出去：agentplay export 导出单会话地图，再配合 --path-mode dirs_only 只保留目录级路径，可以安全贴给同事。
• 与既有工作流衔接：看会话之外，还想审查代码产出，可以配 PR-Agent；想直接上 Claude Code 的成套工程配置，可以看 ECC。

快速上手

1. 需要 Python 3.11 或更新版本，然后运行 uvx agentplay@latest（也可 pipx run agentplay 或 pip install agentplay）。
2. 它会扫描本机已有的 Agent 会话，增量构建脱敏地图，并在 127.0.0.1:7317 打开本地浏览器。第二次运行只重建 transcript 有变化的会话。
3. 常用子命令：agentplay build 只建图、agentplay list 列出已建会话、agentplay export <session> 导出、agentplay import 导入同事的地图、agentplay agents 查看本机装了哪些 Agent。
4. 不想联网可以在启动前设置 AGENTPLAY_NO_NETWORK=1，关掉查看器里的邮箱订阅入口。

小结

agentplay 的价值在于把「Agent 做过什么」从日志变成可读的图形：地图回答它碰过什么，时间轴回答它是怎么走到那一步的，错误排行回答它在哪里卡住。Apache-2.0 开源、零运行时依赖、数据不出本机，这三点让它比多数可观测性产品更容易上手。局限也写得很实在：除 Claude Code 外，其余 Agent 的子智能体不会单独成泳道；Cursor 不记录 token；导出的地图在公开分享前需要确认路径模式。