用途
Agent Run Forensics 旨在解决智能体对自身历史“自信但错误”的问题：当被问及“为什么改了某个文件”时，智能体往往基于不完整的记忆作答，而底层运行框架其实记录了完整的执行轨迹。该技能强制先读取轨迹再回答，适用于事后审计智能体行为、核查改动范围、验证测试结果和校验会话总结真实性等场景。
主要能力
- 运行查找：
trace_finder.py可按仓库、时间窗口、触碰文件或文本筛选已记录的会话。 - 轨迹时间线：
trace_timeline.py以编号步骤展示执行顺序，支持--files表格展示改动文件（SILENT 表示文件被改动但智能体从未提及）、--grep、--errors、--file PATH、--around N过滤，--why STEP可回溯某一步骤的因果链。 - 声明校验：
claim_checker.py将总结中的句子转化为类型化声明（ran、not-run、passed、failed、edited、not-edited、read），并与实际记录比对。STALE 表示测试通过后又有文件改动；PARTIAL 表示退出码 0 来自管道或链式命令的最后一条；退出码 4 表示记录与声明矛盾，需先纠正描述。 - 钩子提示：
hooks/forensics_hint.py在用户提示涉及历史工作时，输出一行指向当前会话轨迹的提示，可通过AGENT_RUN_FORENSICS_HOOK=0禁用。
使用方式
典型工作流为四步：先用 trace_finder.py 定位运行（若问题涉及当前会话，钩子已提供路径）；再用 trace_timeline.py --files 查看事件顺序及文件变更；然后用 --why 从问题步骤回溯；最后在采纳任何总结前，用 claim_checker.py 校验每个声明。所有脚本均支持 --help、--sample 和 --output json。
硬性规则
- 无轨迹不回答：若查找器返回空（退出码 2），应说明该运行未被记录，不得凭空重建。
- 引用步骤号：关于运行的每个事实性句子都需指向具体步骤。
- 区分记录与推断：“recorded”为运行框架当时写入的内容；“inferred”为按命名规则（如 prior-write、retry-after-failure）现时推导的内容。只能对记录边使用“轨迹显示”的措辞，推断边需明确标注规则。
- Shell 效果除非经 bashEditDiff 确认，否则视为推断。
- 复合命令的退出码 0 仅代表最后一条命令。
- 不得引用原始敏感信息，所有输出已脱敏。
适用场景与限制
适用于需要忠实还原智能体运行历史的审计、复盘与总结校验场景。工具为只读、无网络、无模型调用，仅依赖 Python 标准库。限制包括：只能处理已被运行框架记录的会话；无法回答未被记录的内容；推断边需明确标注，不可与记录混为一谈。