场景：AI Agent 同一任务为何忽好忽坏？AgentLens 用可回放证据找出 Codex 分叉
AI 编码 Agent 最难排查的问题，往往不是“它有没有运行”，而是同一个提示词今天成功、明天失败：一次修改了正确文件，另一次却走了另一条路径；一次测试通过，另一次在相同命令上得到不同结果。只看最终 diff，很难回答中间到底发生了什么。
AgentLens 是一个 MIT 许可的 JavaScript 工具，专门记录 Codex CLI 运行过程，并把命令、输出、文件变化、工具调用和错误组织成离线时间线。它的重点不是再运行一个模型，而是给 Agent 的执行过程增加“回放按钮”。
先把一次运行录下来
项目 README 要求 Node.js 20+、Git，以及已经安装并完成认证的 Codex CLI。AgentLens 目前直接从 GitHub 安装：
npm install -g github:fang520huang-lgtm/AgentLens agentlens run codex "Find and fix the failing test"
第二条命令应在 Git 项目中执行。运行结束后，记录保存在项目的 .agentlens/runs/ 目录中。也可以显式指定工作目录和沙箱：
agentlens run codex --cwd /path/to/project --sandbox read-only -- "Explain the architecture"
这个设计很适合复现问题：先在相同分支上运行任务，再保留运行目录和 Git 状态，之后不用重新消耗模型调用，就能查看当时捕获的证据。
回放不是普通日志
拿到运行目录后，可以打开交互式时间线：
agentlens replay .agentlens/runs/
时间线会展示捕获到的命令、消息、文件变化、工具调用和错误；检查器则可以进一步查看命令输出、状态、相关文件和工作区补丁。工具还会根据读取和搜索命令推断 Agent 看过哪些文件，但 README 明确提醒：这不是完整的文件访问审计日志。
这一区分很重要。AgentLens 的价值是帮助开发者重建“可观察到的执行过程”，而不是声称能证明 Agent 的全部内部原因。比如两个运行执行了同一条命令，却得到不同退出码或输出时，回放可以标出分叉，但“分叉”本身仍需要开发者结合环境继续判断。
用 compare 找到首次可观察分叉
当你有两次运行时，最有用的命令是：
agentlens compare .agentlens/runs/run-a .agentlens/runs/run-b
它会生成左右并排的比较页，突出显示首次捕获到的分叉、首次失败命令、各自独有的命令和可能读取的文件、补丁差异，以及模型、提示词、Git 状态、沙箱和 token 使用量的变化。需要自动化处理时，可以输出文本或 JSON：
agentlens compare .agentlens/runs/run-a .agentlens/runs/run-b --text agentlens compare .agentlens/runs/run-a .agentlens/runs/run-b --json
比较结果的正确用法，是把它当作排查入口，而不是最终结论。先看首次分叉发生在哪条命令，再检查两次运行的输入、工作区和沙箱是否一致；最后回到失败命令的原始输出，确认问题来自环境、上下文、工具调用还是代码本身。
分享前先处理敏感信息
AgentLens 默认生成脱敏的单文件 HTML：
agentlens export .agentlens/runs/--out pr-replay.html
也可以显式选择脱敏或原始模式：
agentlens export .agentlens/runs/--redact --out pr-replay.html agentlens export .agentlens/runs/ --raw --out private-replay.html
README 列出的脱敏范围包括常见 API token、Authorization header、私钥、秘密赋值、.env 补丁、主目录路径和用户名。不过它同时强调这是基于模式的处理，不能保证捕获所有秘密。导出后仍应人工检查，并把 .agentlens/runs/ 加入项目的 .gitignore。
什么时候值得使用
如果团队只关心最终代码，Agent 的偶发失败往往会被归咎为“模型不稳定”。AgentLens 提供了更工程化的路径：保存运行、回放过程、比较两次执行，再把可复现的 HTML 附在 PR 或问题单中。它尤其适合调试提示词变更、Codex 沙箱差异、测试偶发失败和“同样任务结果不一致”等问题。
它也有明确边界：当前 README 说明 AgentLens 只记录 Codex，不运行自己的模型；文件快照有每个文件 1 MB、总计 40 MB、最多 4,000 个文件的限制；二进制文件会被跳过。对大仓库或包含敏感数据的项目，应该先评估快照范围和分享策略。
最后，如果运行中断但留下了 events.jsonl，还可以尝试恢复：
agentlens recover .agentlens/runs/
对于经常使用 AI 编码 Agent 的团队，真正值得保存的不是一句“它这次又错了”，而是能让别人复盘的证据链。AgentLens 的定位很克制：不替你解释 Agent 为什么犯错，而是先把它读了什么、运行了什么、改了什么，整理成可以重新检查的记录。