编程 Agent 调试复现证据包：从失败现场到冷启动重演

Agent 收到堆栈后直接改代码，常会把唯一现场一起改掉：未提交配置被覆盖、依赖重新解析、测试数据过期，最后只剩“本机似乎好了”。AI 辅助调试说明如何提供有效上下文；生产流程还需要一份独立证据，证明另一台干净机器能在旧代码上观察同一失败，并在候选代码上看见失败判据消失。

这不是保存 Agent 的完整思考轨迹。Agent 回放评测关注工具选择和多步控制流，复现包关注被调试程序的代码、环境、输入与 oracle。它也不负责证明 shell 命令确实执行过；这里只保存不可变入口及外部 command receipt 引用，避免把调试现场和命令审计混成一个不可复用的大日志。

定义 reproBundle.v1

首次稳定观察到失败、任何修复写入之前，采集器生成 coding.debug.reproBundle.v1。manifest 使用规范化序列化并内容寻址，至少冻结：仓库和 baseCommit、submodule OID、已跟踪 binary patch、未跟踪文件清单、lockfile、构建脚本、工具链、容器 image digest、允许影响行为的环境键、fixture、时钟/时区/locale/随机种子、外部服务替身、失败 oracle、trace 引用和采集策略。

schema: coding.debug.reproBundle.v1
baseCommit: 73a1d9c...
workspaceDelta: sha256:18c4...
runtimeImage: registry.example/debug@sha256:91aa...
fixtures: cas://sha256/44e2...
entrypointDigest: sha256:6fa0...
commandReceiptRefs: [receipt:01J...]
oracle:
  type: structured-event
  fingerprint: NullInvoice/resolveTax/v2
  mustObserve: 1
  forbiddenAfterFix: true

Git bundle 可以携带复现所需、可达的 refs 与对象，但不会包含工作区修改；因此 dirty diff、untracked fixture 和文件 mode 要作为独立 blob 枚举并求摘要。OCI image 由 manifest、config 和 layer digest 固定，不能只写可变 tag。W3C PROV 的 entity/activity 关系连接现场、采集动作、runner 和候选修复；OpenTelemetry trace 只保存相关 span ID 与必要属性，不把整套遥测仓库复制进包。

v1 合同必须写清必填字段、摘要算法、压缩格式、缺失 fixture 的处理和 oracle 解释。reader 不认识 oracle 类型时返回 UNSUPPORTED_SCHEMA；不能退化成“进程非零即复现”。格式升级新增 v2 manifest，旧包保持不可变，并提供离线迁移报告，禁止原地改摘要。

先保存现场，再最小化输入

采集顺序决定证据是否可信。先冻结 Git 与工作区，再复制输入和失败产物，随后才允许 Agent 增加日志或缩小样本。最小复现是原包的派生物，必须记录删除了哪些文件、使用什么 reducer，以及原始与最小包是否产生同一 fingerprint；不能用人工重写的“类似示例”替换真实现场。

密钥、个人数据和内部地址在写入共享 CAS 前按字段类型脱敏，稳定占位符只在确有比较需求时使用；高基数字段不能简单保留明文哈希。清单保存 sanitizer 版本、被删字段计数和脱敏后 blob 摘要。若脱敏会改变 Bug，原始包只能进入受限密钥域，并生成最小授权、到期时间和销毁回执。编程 Agent 沙箱权限还应禁止复现 runner 默认访问生产网络。

冷启动执行双向判定

独立 runner 从空缓存开始，验证每个摘要，检出准确 commit，应用 workspace delta，按 digest 装载镜像和 fixture，再调用冻结入口。网络默认关闭；确需外部协议时使用版本化录制替身，并把未匹配请求视为失败。oracle 优先匹配结构化错误码、状态转换、数据库不变量或崩溃指纹，日志文本只能作为辅证。复现结果记录 bundle digest、runner image、开始/结束时间、oracle 版本及 artifact digest。

修复验证必须是同一个 bundle 的 A/B：旧候选满足 failure oracle，新候选满足 success oracle，并运行编程 Agent 改动验证门要求的相关回归。只在新分支“测试通过”却没有旧失败证据，状态应是 UNPROVEN_FIX。若问题本质是不稳定测试，则转入编程 Agent Flaky Test 治理，但仍保留这个现场作为触发证据，不能靠重试抹掉。

故障注入与量化门禁

故障演练要主动替换 base commit、漏传 untracked fixture、篡改一个 CAS blob、把 image digest 换成 tag、改变 locale/时钟、截断上传、让外部替身多返回一字段，以及让 sanitizer 删除决定性错误码。系统必须分别报告 STATE_MISMATCH、MISSING_INPUT、DIGEST_FAILURE、UNPINNED_RUNTIME、ORACLE_UNSTABLE 或 REDACTION_DAMAGE，不能统一显示“无法复现”。还要在上传完成前杀死采集器，确认没有半成品 manifest 获得 READY 状态。

确定性问题的合并门可规定：必填字段与 blob 摘要覆盖率 100%，两种受支持 runner 各冷启动 10 次，旧版本 10/10 命中同一 fingerprint，候选 10/10 不命中且 success oracle 10/10 成立；未声明网络请求为 0；篡改注入检出率 100%；P95 重建时间不超过团队声明的 15 分钟。概率性竞态必须在 manifest 声明触发轮数、种子和最低命中率，报告置信区间，不得伪装成确定性 10/10。

可逆启用和事故处置

上线先 shadow 采集，只比较人工复现结果；随后对 P0/P1 修复要求证据包，再逐步扩展。每阶段追踪采集成功率、冷启动复现率、脱敏拒绝数、缺失输入率和重建耗时，连续两周达标才提高强制范围。bundle alias 用 generation CAS 指向已验证 digest；回滚 runner 时只切回上一兼容 reader，绝不重写旧包。

若采集器疑似泄密，立即停止新上传、撤销原始包解密授权并保留脱敏 manifest 的事件证据；若新 runner 误判，则降回 shadow，修正 reader 后重放相同 digest。代码修复需要撤销时，也用原包验证 revert 是否重新触发旧 oracle。这样复现证据既能支持交接和审查，也不会因为工具升级或一次错误发布失去可解释性。