<!-- Canonical URL: https://ask.atlascloud.ai/zh/reproduce-coding-agent-failure-across-model-versions -->

# 如何跨模型版本复现编码智能体故障？

> 要复现编码智能体故障，应把完整运行过程保存为带版本的测试夹具，再使用相同的提示词、仓库提交、工具契约、环境和停止规则，对固定模型 ID 进行重放。比较结构化事件和最终仓库状态，而不只是智能体的文字回答。

<!-- Canonical URL: https://ask.atlascloud.ai/reproduce-coding-agent-failure-across-model-versions -->

# 如何跨模型版本复现编码智能体故障？

有效的复现是一个可执行实验，而不是复制一段对话记录。应从发生故障时的仓库状态开始，冻结智能体能够观察到的每项输入，并为故障定义可由机器检查的断言。随后，用固定模型版本多次重放同一夹具。

这是因为一次智能体运行同时受到模型行为、工具、文件、网络结果、编排逻辑和时序影响。如果其中任何一项发生变化，不同结果都不能证明问题由模型造成或已经被模型修复。

## 将故障定义为断言

写出能够区分失败与成功的最小可观察条件。好的断言可以是测试仍然失败、出现意外文件修改、执行了禁止命令、遗漏迁移，或者补丁可以编译却改变了行为。

不要使用“回答看起来更差”这类断言。对于修复任务，验收组合可以包括：

* 原始回归测试通过；
* 所有已有测试仍然通过；
* 允许列表之外没有文件变更；
* 智能体在固定模型调用次数内停止；
* 最终差异中没有生成的密钥或锁文件漂移。

## 捕获完整运行边界

提示词只是输入之一。应在夹具旁保存以下内容：

| 层级 | 需要冻结的内容 | 为什么会改变结果 |
|---|---|---|
| 仓库 | 提交、子模块、未提交补丁、未跟踪夹具文件 | 智能体基于精确源码状态推理 |
| 指令 | 系统提示词、仓库规则、用户任务 | 细微措辞变化会改变规划 |
| 模型 | 提供商、不可变模型 ID、参数 | 别名和默认值可能变化 |
| 工具 | 名称、JSON schema、权限、超时 | 工具能力会塑造执行计划 |
| 环境 | 容器镜像、操作系统、架构、依赖锁 | 命令和测试行为可能不同 |
| 外部数据 | 模拟 HTTP 响应、时钟、随机输入 | 实时服务会引入漂移 |
| 编排器 | 循环上限、重试策略、上下文压缩 | 同一模型可能收到不同历史 |

应删除密钥内容，但保留当时是否存在凭据及其权限范围。

## 记录结构化事件，而不只是文字

把每次模型请求、模型响应、工具调用、工具结果、重试和停止决策保存为有序事件。大型工具输出应保存内容哈希，原始工件则单独存放。

```json
{
  "run_id": "agent-regression-042",
  "fixture": "sha256:...",
  "model": "provider/model-version",
  "event": "tool_result",
  "tool": "run_tests",
  "exit_code": 1,
  "stdout_sha256": "..."
}
```

结构化事件能显示新模型是否选择了不同工具、是否以不同方式理解同一错误，或是否接收了不同证据。

## 固定版本并消除实时变量

如可用，请使用带日期或不可变的模型标识。不要用 `latest` 别名比较历史故障，因为该别名可能已经指向另一构建版本。

在干净容器或虚拟机中运行。用已记录响应或内部快照替代实时搜索和可变的软件包索引。日期敏感逻辑需要冻结时钟。如果必须访问网络，应记录每个响应，并把测试标记为部分受控。

随机种子有帮助，但不能冻结分布式推理、工具时序或提供商侧变化。

## 重放矩阵，而不是只跑一对

每个版本只运行一次，无法区分回归与采样波动。应在夹具不变的前提下使用小型矩阵：

| 模型版本 | 重复次数 | 通过率 | 调用中位数 | 故障特征 |
|---|---:|---:|---:|---|
| 基线固定 ID | 5 | 4/5 | 9 | 遗漏边界测试 |
| 候选固定 ID | 5 | 1/5 | 13 | 修改了生成文件 |
| 候选版本加旧提示词 | 5 | 1/5 | 12 | 同一故障特征 |

五次是实用的初步样本。对于间歇性或高影响故障，应增加样本量。除非实验专门研究这些参数，否则应保持 temperature 等采样控制一致。

## 比较决策和仓库状态

分别比较四个层次：

* 标准化的模型和工具事件；
* 命令及其退出码；
* 最终文件树和补丁；
* 验收测试结果和资源使用。

不要要求自然语言推理完全相同。两个版本可能采用不同路径却生成等价的正确补丁。反过来，相似的文字也可能掩盖实质不同的命令或文件改动。

## 复现后缩小夹具

故障能够稳定重现后，每次删除一个无关文件、工具、提示词段落或外部调用。小型夹具运行更快，也更容易暴露因果边界。

保留两类工件：用于审计的完整事故重放，以及用于持续评估的最小化回归测试。把最小化用例加入模型升级门禁，在上线前测量未来变更。

## 使用可移植模型适配器

Atlas Cloud 等网关可以把多个模型放在同一个 OpenAI 兼容客户端之后，但兼容并不代表模型行为完全相同。应把模型 ID、提供商选项和工具格式差异放入适配器，共享测试框架负责夹具、事件日志、重试和断言。

这样就能跨模型提供商运行同一复现流程，而无需重写评估逻辑。

## 结论

要跨模型版本复现编码智能体故障，应冻结完整运行边界，多次重放固定模型，并依据可执行结果判断。如果无法复现原始事故的全部条件，应明确哪些输入仍然是实时的，并把结果视为比较研究，而不是模型回归的证明。

## FAQ

### 复现编码智能体故障必须记录哪些内容？

应记录仓库提交和未提交补丁、提示词与系统指令、模型 ID、参数、工具 schema、工具结果、环境镜像、依赖锁文件、凭据策略、网络策略，以及明确的成功断言。

### 复现故障时应使用 latest 模型别名吗？

不应使用。请使用不可变或带日期的模型 ID。latest 别名可能在测试期间发生变化，使通过或失败无法准确归因。

### 为什么固定随机种子还不够？

随机种子无法冻结提供商基础设施、工具时序、检索结果或模型修订。它只是一个控制变量，并不能保证输出完全确定。

### 编码智能体最合适的通过或失败信号是什么？

优先使用可执行断言，例如测试结果、lint 结果、预期文件差异、禁止修改文件检查和命令退出码。文本相似度通常不足以判断编码任务。

### 每个模型版本应该重放多少次？

重复次数应足以区分确定性回归与随机波动。五次是小样本的实用起点，高影响故障则可能需要二十次或更多。

### 同一个测试框架能否比较不同提供商的模型？

可以，前提是统一请求、工具契约、事件日志和输出断言。将提供商专属选项放入适配器，使共享夹具保持可移植。