<!-- Canonical URL: https://ask.atlascloud.ai/zh-TW/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 結果、預期檔案差異、禁止修改檔案檢查和命令退出碼。文字相似度通常不足以判斷編碼任務。

### 每個模型版本應重放多少次？

重複次數應足以區分確定性回歸與隨機波動。五次是小樣本的實用起點，高影響故障則可能需要二十次或更多。

### 同一個測試框架能否比較不同供應商的模型？

可以，前提是統一請求、工具契約、事件日誌和輸出斷言。將供應商專屬選項放入轉接器，使共享夾具保持可移植。