【2026 最新】CI Root-Cause Agent 校準怎麼做？5 個部署閘門＋Python 實作

凌晨兩點，CI 又紅了。你的診斷 Agent 回答：「依賴問題 70%、測試問題 15%、環境問題 10%、基礎設施 5%。」這時真正困難的不是看懂排名，而是判斷：這個 70% 能不能拿來自動改 lockfile？CI Root-Cause Agent 校準，就是把「很像有把握」變成可驗證、可交棒的工程決策。

這篇專為第一次碰機率校準與 Agent 評測的讀者寫。你不必先會統計；我會從分類抽屜、資料切分、五種指標一路做到 temperature scaling、成本門檻與決策收據，並附上一份只用 Python 標準函式庫就能跑的合成資料、程式與 notebook。

CI Root-Cause Agent 校準：先說結論

• 「70%」可以是模型對這一案的預測機率，但單一事件無法獨立驗證它是否校準。可信度要在同版本、同定義且分布相近的一組預測上檢查：所有被報成約 70% 的案例，長期應有約七成命中。
• 猜中第一名與機率可信，是兩件事。top-1 看排序；Brier 與 log loss 看整包機率；confidence calibration curve 看最高信心是否兌現；risk–coverage 才回答自動接手多少案例時會錯多少。
• 模型選擇、校準器擬合與部署門檻選擇需要資料隔離。本文採開發、校準、政策選擇、locked test 四段；也可以用嚴格的巢狀交叉驗證等設計，前提是最終 test 不參與任何選擇。
• 不要把 70% 當成萬用門檻。重跑測試、清 cache、產生 lockfile 修復草稿、合併變更與改 production 設定的誤修成本不同，必須為每個 action 分開決策。

記住這個核心：可行動的 70% ＝ 校準過的機率 × 足夠證據 × 可承受的誤修成本。

為什麼「第一名猜對」還不夠？

近日，一則 r/LLMDevs 的工程討論問得很直接：一個會對 CI 失敗輸出模糊機率分布的 Agent，該怎麼標註、校準，又該在哪裡升級給人？這不是只有模型團隊才會遇到的問題；只要你要讓 Agent 觸發重跑、開 issue、改設定或送修復 PR，機率就已經進入營運決策。

想像兩個 Agent 都有 67% top-1 accuracy。A 每次答錯時只說 45%；B 答錯時仍常說 95%。兩者「第一名猜中幾次」相同，但 B 會更容易越權自動處理。這也是為什麼 AI Evals 不能只留一個 accuracy，而 Agent 可觀測性也不能只存最後一句答案：你需要完整分布、輸入證據、版本與實際結果。

CI Root-Cause Agent 校準前，先回答：你到底在預測什麼？

第一步不是選評測套件，而是固定 root-cause taxonomy（故障原因分類）。本文 toy 把它做成五個 causal labels：產品程式碼、測試本身、依賴、環境與設定、CI 基礎設施，再加一個 flaky／未定 routing bucket。production schema 應另存 determinism={deterministic, flaky, transient, unknown}；flaky 是觀測到的非決定性，不等於已確認根因。每個案例為了單標籤評分，只放一個 operational reference label；若證據不足或多因難分，就進 adjudication queue（人工裁決佇列），不要硬塞。

這六個評分類別只是本文實驗的 taxonomy-v1，不是業界通用真理。Zheng 等人從 260 個 Java 開源專案的 15,355 份有效 logs 中抽樣 375 次失敗執行，整理出 16 類；其 replication package公開人工分類表、job URLs 與 scripts，不等於永久保存全部 raw logs。BugSwarm則蒐集並容器化經 reproducer 驗證的 CI fail–pass artifacts，但部分 artifact 仍會因外部依賴失效而被 deprecated。它們適合當起點，不適合直接變成你公司的 reference labels；尤其「修復後通過」只能提供候選證據，不能單獨證明那個 diff 就是唯一根因。

先固定 diagnosis_timestamp。每筆標籤至少保存：incident_id、run_id、run_attempt、job_id、workflow SHA，以及適用時的 base／head／merge SHA、taxonomy 版本、截至該時間已完成的 log、lockfile 摘要、runner image label／version／release link（實際可得時才存 digest）、reference label、裁決者與證據連結。GitHub 官方說明了如何檢視與下載 workflow run logs；其 retention 文件列出的預設是 90 天，public repository 可設 1–90 天、private repository 可設 1–400 天。較晚的修復 PR、評論、postmortem 與 rerun 只能協助建標籤，不得回流到當次模型輸入。每次 rerun 的 logs 分開保存；raw logs 受控存取，另存 raw／redacted log SHA-256 與 redaction policy version，receipt 不內嵌 secret。

5 個部署閘門：從標籤到可升級的決策

① 固定 taxonomy 與標註契約

痛點：如果「環境問題」今天包含 runner 掛掉，明天又不包含，70% 沒有共同分母。做法：版本化每一類的定義、包含／排除規則與 ambiguous policy；先由兩位標註者獨立標記一批具代表性的案例，記錄每類 agreement，再裁決分歧並更新 guidelines。驗證：抽查同一案例在相同 taxonomy 版本下能否得到一致 reference label。

② 切成四段資料，最後一段上鎖

1. development：選 prompt、模型、工具與特徵。
2. calibration：只擬合機率校準器。
3. policy：依誤修成本選 action-specific 門檻。
4. locked test：凍結模型、校準器與政策後，只驗收一次。

切分方式要跟部署問題一致：若目標是同一 repository 的未來事故，就在各 repo 內按時間切；若目標是未見 repository，才做 repo-group holdout，兩種結果分開報告。同一 incident、rerun、fault template 與近重複 log 在任何設計下都不得跨段。scikit-learn 的 常見陷阱文件也強調，任何會從資料學到參數的步驟都只能在訓練側擬合。白話說：不能一邊看期末考答案，一邊調及格線。

③ 同時看 5 面鏡子

• Top-1／Top-3 accuracy：真因是否排在第一名或前三名，回答「嫌疑清單有沒有命中」。
• Multiclass Brier score：(1/N) × Σ事件 Σ類別 (p − y)²。它檢查所有類別機率與 one-hot 答案的平方距離；依 scikit-learn 1.9.0 的預設 scale_by_half="auto"，multiclass 保留原始 0–2 範圍；若設為 True 才縮放至 0–1，本文 lab 使用前者。越低越好。
• Log loss：−(1/N) × Σ log(p真因)。對「非常有自信卻答錯」特別嚴格，越低越好。
• Calibration curve：把預測信心分桶，比較每桶的平均信心與實際命中率；說 70% 的桶應靠近 70%。
• Risk–coverage：coverage 是自動接受的案例占比；selective risk 是被接受案例中的錯誤率。把門檻從低拉高，沿途畫出「接多少、錯多少」。

scikit-learn 的校準指南提醒，Brier 與 log loss 同時混合了 calibration、resolution 與資料本身的不確定性，因此 Brier 下降不能單獨證明「校準一定更好」。ECE（Expected Calibration Error，預期校準誤差）的研究分析也顯示結果會受分桶與類別處理方式影響；本文小實驗只畫 predicted-class confidence reliability 與 10 個等寬 bins 的輔助 ECE，不把它冒充完整的 multiclass classwise calibration，更不能只靠它批准 expected-cost action。

④ 用 temperature scaling 只校準機率

如果 Agent 能輸出每類 logits（softmax 前的分數），可以先試只有一個參數的 temperature scaling：p = softmax(logits / T)。在獨立 calibration split 上選一個讓 log loss 最小的正數 T；T > 1 會把過度尖銳的分布放柔，T < 1則變尖。因為每個 logit 都除以同一個正數，類別排序與 top-1 不變。Guo 等人於 2017 年系統性評估了它的神經網路校準效果；截至 2026 年 8 月，scikit-learn 1.9.0 的 multiclass calibrator也列出這個方法。

它不是魔法：單一 temperature 不會修正錯的 taxonomy、證據缺漏或錯誤排序，也不能直接補救資料漂移、保證漂移後仍校準；你必須重新評估，必要時重校準。若要使用本文的 multiclass temperature scaling，需要 logits 或完整類別機率；只有一個 scalar confidence 仍可用其他方法另行校準，但不能直接套這個 multiclass 做法。

⑤ 用成本選門檻，不用感覺選 70%

對每個 action 建一張成本矩陣，計算 EC(action | x) = Σ原因 p(原因 | x) × C(action, 原因)。只有當自動 action 的預期成本低於請人處理的成本，而且證據與政策硬閘門都通過，才允許自動化。這是決策規則，不是某篇論文替所有團隊訂好的數字；成本要由你的事故等級、回復難度與工程時間估計。predicted-class ECE 不足以證明每個 p(原因 | x) 都能直接進成本公式，部署前還要檢查 classwise calibration、稀有高成本類與真實 action outcome。

本文 toy 在 policy split 指定「未加權分類 selective risk 不超過 5%，且至少接受 30 筆」，再以 point estimate 選覆蓋率最高的門檻；這只是示範程式，不是 production safety constraint。真實系統應在獨立 policy set 上，連同 weighted accepted risk 的 confidence upper bound、人工 queue 容量與成本敏感度選門檻，再到 locked test 驗收。風險與覆蓋率的定義來自 selective classification／reject option 的研究脈絡，但樣本上的 5% 不是未來事故的保證。低樣本、分布漂移或高影響 action，都應直接要求更多證據或交給人。

完整追一次：從「依賴 78%」到要求補證據

另做一筆不混入 900 筆評測資料的示意事件 demo-lockfile-001：raw distribution 是依賴 0.78、產品程式碼 0.06、環境 0.06、測試 0.04、基礎設施 0.03、flaky 0.03。套用 toy lab 的 T = 1.50 後，分布約為：依賴 0.579、產品程式碼 0.105、環境 0.105、測試 0.080、基礎設施 0.066、flaky 0.066。這不代表依賴被「判錯」；共享 T > 1 只表示 raw scores 在 calibration cohort 整體偏尖，不能由單一事件斷言它本身過度自信。

1. 系統先檢查 taxonomy 是否在支援範圍，並確認 log、commit SHA、runner image label／version 與 lockfile SHA 的可得狀態都有記錄。
2. 在這個示意 policy 中，「產生但不合併 lockfile 修復草稿」的門檻是 0.91；校準後約 0.579 未過，而且 evidence 中缺少 lockfile diff。
3. Agent 不修改檔案，改回傳 request_more_evidence，請上游補 lockfile diff 與可重跑 seed。
4. 補證據後重新評分；若仍未過 action-specific gate，就升級給人。原 decision-time receipt 保持 immutable，稍後的人工裁決、override 與 remediation result 以 parent_receipt_id 串接新的 outcome receipt；另隨機抽查部分已自動接受的案例。

decision-time receipt（決策收據）保存 Agent／prompt／taxonomy／calibrator／policy 版本、可得的輸入快照 hash、完整機率、缺漏與已有證據、門檻及 action；outcome receipt 再串接人工結果。它是本文提出的可追溯 schema，只記錄當時宣稱使用的輸入與決策，不是「根因已被證明」或「資料不可竄改」的證書。若你正搭建執行層，可把它接進 AI Agent Harness，並參考 從零實作 Agent Harness把權限、重試與人工升級做成硬閘門。

實作、部署與上線

CI Root-Cause Agent 校準實作：下載 toy dataset 與 notebook

AlphaLab 保留了一份可下載的 CI 校準小實驗 ZIP。它含 900 筆模擬六類標籤與 Agent 機率輸出的 synthetic classification rows，以及 lab.py、CSV、notebook、taxonomy、預期輸出與 decision receipt 範例；固定 seed 為 20260820，不含真實 logs 或實際注入故障。它只驗證管線能重現，不代表任何生產 Agent 的效能。

echo "1863c63843f5fb578555eade5861c274436f29e913443efbe3336241bab4b3a1  ci-root-cause-agent-calibration-lab-fde591c7.zip" | shasum -a 256 -c - &&
unzip ci-root-cause-agent-calibration-lab-fde591c7.zip &&
cd ci-root-cause-agent-calibration-lab-fde591c7 &&
python3 lab.py

程式只用 Python 標準函式庫。因為這裡模擬的是一個已固定但過度自信的 Agent，所以資料切成 calibration、policy、locked test 各 300 筆；若你還要選 prompt 或模型，請另隔離 development 用途，不能拿這三段反覆試模型。這份合成資料的 repo_group 只是示意欄位；生成器沒有加入 repository-specific 訊號，15 個 group 會跨三段，所以它沒有示範 production 的 group holdout。

這次本機程式在 T = 0.50–3.00、步長 0.01 的網格中選到 T = 1.50。locked test 的 top-1 維持 67.0%，top-3 維持 92.7%；Brier 從 0.452 降至 0.446，log loss 從 0.923 降至 0.888，10-bin confidence ECE 從 8.5% 降至 5.9%。policy split 以 point estimate 為 5% 目標選出 0.909 門檻（2/41 錯誤），locked test 則接受 45/300，coverage 15.0%、risk 3/45＝6.7%；3/45 的 Wilson 95% interval 約為 2.3%–17.9%，不能把 6.7% 與 5% 的差當成顯著差異。它只示範：小樣本門檻有很大不確定性，不能把 policy 上的漂亮數字當未來保證。

這裡的 locked 只表示「本次開發流程沒有使用」；公開 GitHub logs 或 PR 可能進過模型預訓練，不能宣稱模型從未看過。production 評測可用新生成、private 或模型知識截止日之後的案例降低污染風險。

部署前容易踩的 7 個坑

1. 同一批資料選模型、校準又挑門檻：每個數字都被調得很漂亮，卻沒有真正未見資料。
2. 把修復後資訊塞回輸入：Agent 看見答案才會有的 diff，評測就失去意義。
3. 把多因事故硬壓成單因：保留一個 scoring primary cause，但另存 secondary causes 與人工裁決狀態。
4. 只報一個 ECE：一定同看 reliability 圖、每桶樣本量、Brier、log loss 與 classwise 行為。
5. 預設所有 action 共用 70%：低風險重跑與高風險改設定應依各自成本、證據與風險約束獨立選門檻；結果可能碰巧相同，但不能先假定共用。
6. 只標註被升級的案例：系統會看不見自動接受後的錯誤；保留隨機 audit sampling，避免 selective-label bias。
7. 把收據當真相：receipt 記錄當時宣稱使用的資訊與決策、提供可追溯性；未簽署 JSON 不防竄改，也不證明 Agent 的根因正確。

部署後，把校準漂移當成正常營運訊號。按 repository、workflow、runner image、語言生態與 incident severity 分層看曲線；每次 taxonomy、模型、prompt 或工具變更，都產生新版本並先走 shadow mode（影子模式：只記錄建議，不執行 action）。Prompt Injection 回歸測試與 Agent Skill Routing A/B Test只是其中兩項；寫入型 action 還要有 least privilege、read-only default、dry run、idempotency、rate／impact cap、rollback、獨立 audit log 與高影響人工批准。

三種上線模式：你該選哪一種？

• 先選「只觀察」：taxonomy 還在變、真實標籤少、locked test 不穩，Agent 只排行與蒐證，不觸發 action。
• 再選「低風險自動」：只允許可逆的重跑、補抓 artifacts 或開 issue；門檻按 action 分開，保留隨機人工抽查。
• 高影響預設「人批准」：改權限、動 production 設定或合併修復 PR，先把校準分數當排序證據，不當執行命令。lockfile 是否能自動改，則按 repository、可回滾性、證據完整度與 action-specific gate 逐項決定。

FAQ：CI 診斷機率的 8 個實作問題

1. Agent 說 70%，代表這一案有精確七成機率嗎？

它是模型對此案的預測機率，不是已知的精確客觀機率。單一事件無法獨立驗證是否校準；你能驗的是同版本、同定義且分布相近的一群預測，長期是否接近承諾頻率。

2. Top-1 accuracy 高，就能自動修嗎？

不能。它只看第一名是否命中，沒有衡量自信答錯的嚴重度，也沒有放進 action 成本與證據完整度。

3. 評測用的 reference label 從哪裡來？

從可追溯、受證據支持的 operational reference label 來。已修復 PR、CI logs、issue 與 fault injection 都只是證據來源；可行時以重現失敗加最小修復或回退確認，否則標成 probable 或 ambiguous，並記錄 taxonomy 版本、裁決者與理由，不宣稱它是客觀真相。

4. 需要多少案例才夠？

沒有脫離情境的固定數字。至少公開每個機率桶與每個 action 接受區的樣本量與不確定性；若高信心區只剩少數案例，就不要批准自動化。

5. Temperature scaling 會提高 top-1 accuracy 嗎？

通常不是它的工作。單一正 temperature 會保留 logits 排序，所以重點是讓機率尺度更貼近經驗頻率；本文 toy run 的 top-1 就維持 67.0%。

6. 所有 root cause 可以共用一條門檻嗎？

不建議。更重要的是按 action 與事故影響分門檻；相同 root cause 也可能對應「只重跑」或「修改 production」兩種完全不同成本。

7. 這份 synthetic dataset 能直接決定 production gate 嗎？

不能。它只讓你驗證程式、欄位與切分方法；真正門檻必須由你的真實 failures、成本與 locked test 決定。

8. 上線後只要監控平均 accuracy 嗎？

不夠。同時監控分層 calibration、risk–coverage、coverage、人工推翻率、未支援類別比例與 action 後果，並定期抽查已自動接受案例。

給新手的 5 個重點

1. 先固定 taxonomy 與標註契約，再收數字。
2. 隔離開發、校準、政策與 locked test 四種用途，不讓最終 test 參與選擇。
3. 一起看 top-k、Brier、log loss、calibration 與 risk–coverage。
4. 用獨立資料校準；temperature 不修錯誤排序，分布漂移後要重新評估或重校準。
5. 把機率、證據與 action 成本綁在版本化 receipt，保留人工升級與隨機抽查。