Agent Lens 轨迹捕获与回放调试

问题：会话一结束，现场就没了

调试 Claude Code 时最难受的并不是「报错了」，而是报错发生时你只能看到最终文本。一段看似正确的回复背后，可能经历过三轮自我纠正、两次文件重写和一次方向切换；一旦会话结束，这些中间过程全部消失。

• 你不知道代理是在哪一回合改主意的，只知道最终结果
• 文件被反复编辑，但中间态从未被保存，出错的那一步无法还原
• 跨会话调试时，你无法把上一轮的决策和下一轮的行为连成一条时间线

靠事后看日志、手动复现，属于临时转录审查：能猜个大概，但拿不出证据链。当代理行为出现 bug，你需要的是法医级调试——逐回合地看它当时看到了什么、改了什么、为什么改。

它如何工作

这个技能把 Agent Lens 的轨迹能力接到 Claude Code 上，核心做三件事：

1. 捕获结构化轨迹：记录的是代理的执行步骤（工具调用、观察、决策），而不是把输出文本抄一遍。这意味着你可以按回合回放，而不是重播一段录屏似的文本
2. 影子 git diff：代理每次编辑文件都会生成一份差异快照。即使它把文件改回去再改回来，你也能逐次对比，定位是哪一步引入了破坏
3. 分支回放：把代理行为当作分支来重放。选一个分叉点，从那里重新走，看不同决策会导向什么结果

关键步骤串起来就是：记录轨迹 → 生成影子 diff → 在分支上回放。调试时先看 diff 确认改动范围，再在可疑回合上回放，验证你的假设。

适用边界

• 目前只支持 Claude Code：通过 Claude Agent SDK 接入，其他代理和框架还在路线图上，不要指望现在拿来调试其他框架的代理
• 回合级回放是实验性的：关键验证路径可能不稳定，拿它做决定前最好用稳定功能交叉确认
• 环境要求不轻：需要 Python 3.12+、uv 和 Agent Lens，凭证走订阅（Claude Pro/Max）或 API key。你的环境里这两样不一定都具备
• 不适合日常小修：如果你只是想改个变量名，这套法医级流程是杀鸡用牛刀；它的价值在「代理行为异常且难以复现」的场景

换句话说，这是给排查疑难杂症准备的手术刀，不是日常开发的瑞士军刀。