本篇代碼示例：code/ 實戰練習：Project 06. 搭建一套完整的 agent 工作環境

第十一講. 讓 agent 的運行過程可觀測

你讓 agent 做一個功能，它跑了 20 分鐘，改了一堆檔案，然後告訴你"做完了但有兩個測試失敗"。你問它為什麼失敗，它說"不太確定，可能是時序問題"。你問它改了哪些關鍵路徑，它說"讓我看看代碼……"。

這不是 agent 能力不夠，是你的 harness 沒有給它裝儀表盤。想象你在開一輛沒有儀表盤的車——沒有速度表、沒有油量表、沒有發動機故障燈。你能開，但你不知道開多快、還剩多少油、發動機是不是快爆了。技術再好的司機，蒙著眼也得出事。

沒有可觀測性，agent 在不確定狀態中做決策，評估變成主觀判斷，重試變成盲目摸索。 OpenAI 和 Anthropic 都將可靠性定義為證據問題——harness 必須以可指導下一步決策的形式暴露運行時行為和評估信號。

可觀測性缺失的真實代價

當 harness 缺乏可觀測性時，四類問題系統性出現：

無法區分"正確"和"看似正確"：一個函數在代碼審查時看起來完全正確——語法對、邏輯通。但運行時因為邊界條件處理錯誤，在特定輸入下產生了不正確結果。只有運行時追蹤能揭示實際執行路徑偏離了預期。就像一個演員排練時臺詞全對了，但上臺演出時燈光一打，表情和走位全都變了——你不看現場是發現不了的。

評估變成玄學：沒有評分標準和驗收條件時，評估者（人或 agent）依賴隱式假設。同一個輸出，不同評估者可能給出截然不同的評價。質量評估不可復現。就像體操比賽沒有評分標準——這個裁判覺得你的動作優雅，那個裁判覺得你落地不穩，誰說了算？

重試變成盲猜：agent 不知道為什麼失敗時，重試方向是隨機的。它可能在錯誤的方向上反覆嘗試——修復了不相關的代碼路徑而忽略真正的故障根源。就像你開車發現車跑偏了，但你沒有儀表盤——你猜是輪胎的問題換了輪胎，實際是方向盤的 alignment 出了問題。每次盲重試都消耗 token 和時間。

會話交接信息斷崖：當未完成的工作移交給下一個會話時，缺乏可觀測性意味著新會話必須從零診斷系統狀態。Anthropic 的長期運行 agent 觀察表明，這種重複診斷可能佔會話總時間的 30-50%。就像換班司機上車發現沒有交接記錄——他得花半小時檢查油量、胎壓、發動機狀態才能出發。

Claude Code 的真實場景

想象一個使用"計劃者-生成者-評估者"三角色工作流的 harness，執行"為應用添加暗色模式"任務。

沒有儀表盤：計劃者輸出模糊描述。生成者根據模糊描述實現暗色模式，但和計劃者的隱式預期不一致。評估者基於自己的隱式標準拒絕，但說不出具體哪裡不對——"感覺不太對"。生成者基於模糊拒絕理由盲重試。循環 3-4 次，總耗時約 45 分鐘，最終勉強產出。

有完整儀表盤：計劃者輸出衝刺合同——列明要改哪些組件、每個組件的驗證標準、排除項（不處理打印樣式）。生成者按合同實現。運行時可觀測性記錄每個組件的樣式加載和應用過程。評估者用評分標準逐維度評估，附具體證據引用——"按鈕顏色對比度不足（WCAG AA 標準 4.5:1，實測 2.1:1）"。一次迭代出高質量結果，總耗時約 15 分鐘。

效率差 3 倍。區別只在可觀測性——給車裝上了儀表盤。

雙層可觀測性

可觀測性不是"多打點日誌"那麼簡單。它分兩層，缺一不可：

運行時可觀測性：系統層的信號——日誌、追蹤、進程事件、健康檢查。回答"系統做了什麼"。這是你車上的儀表盤——速度、油量、發動機溫度。

過程可觀測性：harness 決策工件的可見性——計劃、評分標準、驗收條件。回答"為什麼這個變更應該被接受"。這是你的導航系統——不光知道現在在哪，還知道為什麼走這條路。

核心概念

運行時可觀測性：系統層的信號——日誌、追蹤、進程事件、健康檢查。回答"系統做了什麼"。
過程可觀測性：harness 決策工件的可見性——計劃、評分標準、驗收條件。回答"為什麼這個變更應該被接受"。
任務軌跡：一個任務從開始到完成的完整決策路徑記錄，類似分佈式系統中的請求追蹤。agent 的每一步操作及其上下文都被記錄。就像黑匣子——出了問題可以回放完整過程。
衝刺合同：編碼開始前協商的短期協議——明確任務範圍、驗證標準、排除項。是過程可觀測性的核心工具。
評估評分標準：把質量評估從主觀判斷變成基於證據的結構化評分。使不同評估者對同一輸出產生相似結論。就像體操比賽的評分標準——有了它，十個裁判的分才不會差太遠。
雙層可觀測性：系統層和過程層同時設計、相互增強。運行時信號解釋行為，過程工件解釋意圖。

為什麼 agent 自己解決不了這個問題

你可能在想："agent 不能自己打日誌嗎？" 問題在於：

agent 不知道它不知道什麼——它不會主動記錄自己沒意識到需要的信號。就像你不知道油箱快漏了的時候，你不會去看油量表——因為你壓根不知道該看。
日誌格式不統一——不同會話用不同的日誌格式，無法做系統化分析。就像十個司機各寫各的交接記錄，格式都不一樣，下一個司機看不懂。
過程可觀測性不是日誌能解決的——衝刺合同和評分標準是結構化的工件，需要 harness 層面的支持。不是多 print 幾行就能搞定的。

怎麼裝儀表盤

1. 在 harness 裡內置運行時信號採集

不要依賴 agent 自己打日誌。harness 應該自動採集以下信號：

應用生命週期：啟動、就緒、運行、關閉各階段狀態
功能路徑執行：關鍵路徑的執行記錄，包括入口、檢查點和出口
數據流：數據在組件間的流轉記錄
資源利用：異常的資源使用模式（如內存持續增長）
錯誤和異常：完整的錯誤上下文，不只是錯誤消息

2. 實施衝刺合同

在每個任務開始前，生成者和評估者（可能是同一個 agent 的不同調用）協商一份合同——就像施工隊開工前籤的施工協議：

markdown

# 冲刺合同: 暗色模式支持

## 範圍
- 修改主题切換组件
- 更新全局 CSS 變量
- 添加暗色模式測試

## 驗證標準
- 每個组件的视觉回歸測試通過
- 主流程端到端測試通過
- 无样式闪烁 (FOUC)

## 排除项
- 不處理打印样式
- 不處理第三方组件暗色模式

3. 建立評估評分標準

把"好不好"變成可量化的評分——就像給體操比賽定評分標準：

markdown

# 評分標準

| 维度 | A | B | C | D |
|------|---|---|---|---|
| 程式碼正确性 | 所有測試通過 | 主流程通過 | 部分通過 | 编译失敗 |
| 架构合规 | 完全合规 | 轻微偏离 | 明顯偏离 | 严重违反 |
| 測試覆盖 | 主流程+邊缘 | 仅主流程 | 仅有骨架 | 无測試 |

4. 用 OpenTelemetry 標準化

為每個 harness 會話創建一個 trace，每個任務創建一個 span，每個驗證步驟創建子 span。使用標準屬性標註關鍵信息。這樣可觀測性數據可以和標準工具鏈（Jaeger、Zipkin）集成。

Anthropic 的三 agent 架構實驗

Anthropic 在 2026 年 3 月發佈了一項系統性的 harness 實驗。他們用三種架構跑同一個任務（"用 Web Audio API 做一個瀏覽器端 DAW"），記錄了詳細的階段數據：

Agent 和階段	時長	成本
Planner（規劃者）	4.7 分鐘	$0.46
Build 第 1 輪	2 小時 7 分鐘	$71.08
QA 第 1 輪	8.8 分鐘	$3.24
Build 第 2 輪	1 小時 2 分鐘	$36.89
QA 第 2 輪	6.8 分鐘	$3.09
Build 第 3 輪	10.9 分鐘	$5.88
QA 第 3 輪	9.6 分鐘	$4.06
總計	3 小時 50 分鐘	$124.70

三個 agent 各司其職，每個都有明確的可觀測性角色：

Planner（規劃者）：接收一段 1-4 句話的用戶需求，擴展成完整產品規格。被要求"大膽設定範圍"並且"專注於產品上下文和高層技術設計，而不是詳細的技術實現"。原因是：如果 planner 過早指定了粒度技術細節且搞錯了，錯誤會級聯到下游實現。更好的做法是約束交付物，讓 agent 在執行中自己找到路徑。就像建築設計師只畫效果圖和結構圖，不規定每塊磚怎麼砌。

Generator（生成者）：按 sprint 逐個功能實現。每個 sprint 前和 evaluator 協商一份 sprint 合同——約定這個功能塊"做完"的標準。然後按合同實現，自評後交給 QA。按合同施工，不按感覺施工。

Evaluator（評估者）：用 Playwright MCP 像用戶一樣點擊運行中的應用，測試 UI 功能、API 端點和數據庫狀態。對每個 sprint 按四個維度評分——產品深度、功能性、視覺設計和代碼質量。每個維度有硬性閾值，任一不達標則 sprint 失敗，generator 收到詳細反饋後修復。就像驗收工程師拿著驗收標準逐項檢查——不達標就打回去重做。

QA 第 1 輪反饋的示例——"這是一個視覺上令人印象深刻的應用，AI 集成工作良好，但核心 DAW 功能有幾個是展示性的，沒有交互深度：剪輯不能拖拽/移動，沒有樂器 UI 面板（合成器旋鈕、鼓墊），沒有視覺效果編輯器（EQ 曲線、壓縮器儀表）"。這些不是邊緣情況——它們是讓 DAW 可用的核心交互。具體的、有證據的反饋，不是"感覺不對"。

Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題，然後說服自己這些問題不嚴重，最終批準工作。調校方式是：讀 evaluator 的日誌，找到它的判斷和人類判斷分叉的地方，更新 QA 的 prompt 解決那些問題。經過幾輪這種開發循環，evaluator 的評分才變得合理。就像訓練一個新驗收工程師——一開始他太寬容，出了幾次事故後學會了嚴格。

來源：Anthropic: Harness design for long-running application development

關鍵要點

可觀測性是 harness 的架構屬性——不是事後添加的功能，而是設計時必須考慮的核心能力。儀表盤不是可選配件，是出廠標配。
雙層可觀測性缺一不可——運行時信號解釋"發生了什麼"，過程工件解釋"為什麼這樣做"。速度表和導航系統各有各的用處。
衝刺合同前置對齊工作——防止"生成者做了評估者因可預見原因立即拒絕的東西"。施工協議要在開工前籤，不是完工後補。
評分標準讓評估可復現——不同評估者對同一輸出產生相似評分。有了評分標準，十個裁判的分才不會差太遠。
可觀測性缺失導致 30-50% 的會話時間浪費在重複診斷上。

練習

可觀測性差距分析：審查你當前的 harness，評估系統層和過程層可觀測性。找出無法從現有信號區分的系統狀態，提出補充方案。
衝刺合同實踐：為一個真實任務寫衝刺合同。讓 agent 按合同執行，對比沒有合同時的效率和質量差異。
任務軌跡構建：記錄一個完整編碼任務中 agent 的每一步操作。用 OpenTelemetry 語義約定標註。分析軌跡中的信息瓶頸——哪些步驟的決策缺乏足夠的信號支持。

第十一講. 讓 agent 的運行過程可觀測 ​

可觀測性缺失的真實代價 ​

Claude Code 的真實場景 ​

雙層可觀測性 ​

核心概念 ​

為什麼 agent 自己解決不了這個問題 ​

怎麼裝儀表盤 ​

1. 在 harness 裡內置運行時信號採集 ​

2. 實施衝刺合同 ​

3. 建立評估評分標準 ​

4. 用 OpenTelemetry 標準化 ​

Anthropic 的三 agent 架構實驗 ​

關鍵要點 ​

延伸閱讀 ​

練習 ​