這一課會完成什麼
- 建立能重建控制流程、又不保存敏感 payload 或 hidden reasoning 的 correlated events
- 在 dispatch 前執行 turn、time、tool、output、change、retry 與 spend budgets
- 用 state 與 normalized observations 偵測 non-progress 和 unknown effect
- 在 crash、tool outage 與 approval wait 後重新授權並安全 resume
開始前先準備
- • 模組 04 到 07 的 state machine、tool union、mechanical rules 與 eval suite
- • 能在 dispatch、effect、observation 與 checkpoint 前後注入 crash 的 fixture runner
先把定義說清楚
Observability 與復原
Operational harness 讓 agent run 可重建、有邊界且能復原。Controller 為 state transition、tool dispatch、observation、check、effect、budget 與 terminal reason 寫 correlated event;工作前先 reserve budget,達停止條件就保存 authoritative checkpoint。Resume 時重新驗 identity、policy、environment、Git、state、approval 與 effect,不能因舊 session 曾有權限便直接繼承。
Coding session 可能一直重跑同一失敗 test、搜尋相同 route、產生新說法,卻沒有增加 evidence 或改變 state。若 progress 由模型自行宣告,系統會在很久以後才讓人知道卡住,時間、token 與 reviewer attention 都已經消耗。
Recovery 同樣是 control boundary。Crash 可能發生在 write 完成但 observation 尚未存、branch 已改變、或 approval 已過期。從聊天摘要 resume 可能重複 effect 或套用 stale authority。Checkpoint、budget ledger 與 reconciliation 把中斷變成可測 transition。
現場情境
跑了六小時,證據卻沒有前進
Event volume、budget、crash boundary 與 recovery result 都是合成 fixture。
- 負責人
- 你是準備將 Release Desk task 放到 background 的 operator。
- 要做的決策
- Controller 如何偵測沒有進展,又如何在 interrupted write 後避免第二筆 effect?
- 目前狀態
- Session 在同一個 browser failure 與 route inspection 間來回。每輪 prose 不同,文字差異 heuristic 仍報 progress。另一個 run 在 audit insert 後、tool observation 寫入前 crash。
- 預期成果
- 第一個 run 以 non_progress 結束;fresh authorized session 查到既有 audit effect,從最後 safe checkpoint 接回。
限制條件
- • 最多 14 turns、24 tool calls、150 秒、三次 unchanged cycle、一筆 write 只可在 reconcile 後重試、USD 2.50 fixture budget
- • Budget 在模型外執行並記 reserved、used、released、remaining
- • Kill control 要擋 dispatch、取消 owned lease、禁止 resume 並保存 evidence
實作範例
Normalized evidence 看出 prose 掩蓋的 loop
證據類型: 具名模擬情境連續三輪雖有不同解釋,validated action、target file hash、browser failure code、missing evidence 與 state version 全部相同。另一個 controlled run 在 audit effect commit 後 crash。
Controller 比較 normalized action、observation code、evidence coverage、diff hash 與 state。第三次無變化就以 non_progress 停止。Crash resume 以 idempotency key 查 effect ledger,找到既有 audit,補存 observation 並釋放 reservation,不再 dispatch write。
Receipt 顯示一個 logical effect、一次 physical write、零 duplicate retry 與 checkpoint。Kill drill 只取消 Release Desk lease,另一套 fixture environment 仍存活;restore 需要 named operator event。
主張限制
Budget 與 threshold 依 task shape、tool latency 和價值而變。教材數字只示範控制位置,不能直接搬到 production。
做法
照著做,每一步都有檢查點
現場情境
Controller 如何偵測沒有進展,又如何在 interrupted write 後避免第二筆 effect?
- 01定義 event 與 budget contract
- 02偵測 meaningful progress
- 03在 persistence boundary 注入 failure
驗收條件
Background run 在 evidence 與 state 不再前進時停止;每個 interruption 都有 deterministic recovery,budget 可對帳,operator 不看 transcript 也能介入。
- 01
定義 event 與 budget contract
建立 state、tool、check、effect、budget、checkpoint、approval 與 terminal events。Turns、calls、time、bytes、changed files、retries 與 spend 都在 execution 前 reserve,outcome 後 reconcile。
檢查點 · Reviewer 能由 events 重建 fixture run,model-facing 與 default operator view 都找不到 seeded canary。
- 02
偵測 meaningful progress
Normalize validated action、observation code、evidence coverage、diff hash、failing check 與 state version。只有這些訊號往 contract 前進才 reset counter,prose 改寫不算。
檢查點 · Repeated-loop fixture 在預期 cycle 終止;真正 repair 改變 evidence 或 state 時能繼續。
- 03
在 persistence boundary 注入 failure
依序在五個位置 crash,以 fresh session 重驗 identity、policy、environment、branch、contract、state、budget、lease 與 effects,選 retry、reconcile、resume 或 stop。
檢查點 · 五個 fixture 都到預期 terminal,一個 logical effect,reservation 正確,沒有碰 unowned environment。
- 04
演練 kill、restore 與 handoff
Active run 中觸發 fixture kill,驗 intake、dispatch、lease、resume 與 in-flight evidence,再由 named operator restore。將 packet 交給沒看過 run 的 reviewer。
檢查點 · Reviewer 能指出 stop reason 與 safe next action;target bounded,unrelated environment 正常。
實務脈絡
展示版之後
只記能回答操作問題的 event
Operator 要能回答:哪個 contract 與 commit、state 如何變、tool 做了什麼、evidence 是什麼、budget 花在哪、為何停止、哪些 effect 可能存在、下一步是否安全。Event 依需要帶 run、session、task、environment、contract、commit、feature、span 與 parent IDs。
保存 validated arguments 的安全 projection 或 hash,不存 credential、raw cookie、完整 source、敏感 fixture 與 hidden model reasoning。完整 redacted log 和 screenshot 以 evidence ID 連結,另有 retention 與 access policy。
把 recovery 寫成 fixture suite
在 dispatch 前、dispatch 後未收到 receipt、effect persist 後、observation persist 後、checkpoint 後依序 crash。每個 case 先寫 expected state version、logical effect、lease、budget reservation、next action 與 terminal reason。Unknown write 要 reconcile,safe read 才能在 bounded policy 下 retry。
Resume 跟新 session 一樣,重新驗 caller authority、environment ownership、branch/commit、contract、checkpoint、lease、approval、budget 與 effect ledger。Mismatch 進 named blocked 或 reconcile,不用 prompt 猜測。
交付補強
Budget ledger 要記 reservation,而不是事後加總。Controller 準備呼叫 tool 或 model 前,先以可接受上界 reserve;額度不足就 budget_exhausted,不先執行再解釋。Outcome 回來後將實際用量對帳並釋放差額。Crash 時 outstanding reservation 留在 checkpoint,resume 先 reconcile provider 或 tool receipt,避免同一筆支出被忘記,或錯把保留額度當成還能使用。
Non-progress 不只看完全相同的動作。兩個 search query 文字不同,若命中同一組檔案、沒有新 evidence、state 與 diff 不變,仍可能是 loop。反過來,相同 test command 在修正後得到新 failure layer,代表有進展。Detector 使用 normalized action、observation code、coverage set、artifact hash 與 state transition;threshold 依 task class 設定,並保留人工 override 但需要 reason 與 expiry。
Operator packet 依 terminal reason 給不同內容。Non-progress 列重複訊號與缺口;budget exhausted 列 reserved、used、remaining 與未完成 scope;denied 列 policy code 與 authority owner;unknown effect 列 idempotency key、dispatch 與 reconciliation status;killed 列 target ownership與 in-flight evidence。Packet 由 events 組合,不再請模型自由摘要,值班人員才能直接選 close、reconcile、補權限或從 checkpoint resume。
Redaction 要在 event ingestion 前執行,並有 canary test。若先寫 raw trace 再由 dashboard 遮蔽,storage、backup 與 debug export 已經暴露。對 path、email-like fixture、token、cookie、query parameter 與 screenshot metadata 設 field-level rule;需要授權調查時,走另外的 protected source,不在一般 trace 反向還原。Redaction failure 本身是 critical event,應停止該 run 的正常 telemetry export。
Kill control 需要涵蓋 intake、scheduler、worker lease、tool dispatch、resume 與 approval queue。只把 UI 關掉,background run 仍可能繼續。Drill 中先拒 new work,取消帶 target environment owner 的 lease,撤銷 tool authority,保留 unknown effects 供 reconcile;restore 由 named operator 重新驗 policy 與 health。另一個 project、worktree 或 shared system service 不在 target list,就不應受到任何 stop action。
Checkpoint 內容要小而完整。保存 active contract、feature state、commit 或 dirty hash、environment、tool catalog、budget、lease、last completed check、outstanding effect、approval reference 與 next action,不保存無限 transcript。寫入採 versioned atomic replace 或交易,避免 crash 留下半份檔案;讀取時驗 schema、hash 與前後版本。若 checkpoint 損壞,runner 回 blocked 並保留檔案供調查,不自動退到更舊狀態後繼續寫入。
復原測試還要涵蓋 authority 變動。舊 session 的 reviewer role 被移除、approval 超過期限、tool scope 縮小、contract 升版或 branch 已合併時,即使 checkpoint 完整也不能直接 resume。Runner 重新取得當前身份與 policy,計算哪些 planned effects 失效,將 task 移到 denied、blocked 或 needs_review。這能防止 resume token 變成長期通行證,也讓權限收回真正作用到背景工作。
營運報表按 terminal reason 與 task class 看趨勢。Non-progress 增加時檢查 knowledge 與 tools;budget exhausted 增加時拆 retry、測試與 context;denied 增加時分攻擊、需求擴張或 policy drift;unknown effect 增加時查外部服務與 idempotency。被 guard 成功阻止的危險行為要和功能失敗分開呈現,否則團隊可能為了提高完成率而關掉有效控制。每個異常趨勢連一位 owner 與下一次 review。
Alert 不應直接對每個 event 發通知。先依 run、task、terminal reason 與 criticality 聚合,避免同一 failure 產生數十個訊息淹沒值班人員。Critical secret、越權、unknown consequential effect 與 kill failure 立即升級;一般 non-progress 或 budget exhausted 進可排序 queue,附 operator packet 與期限。Alert acknowledgement、指派、處置與關閉也寫事件,並檢查關閉是否真的對帳 effect 或恢復 health。沒有 owner 或逾期的 critical item 會自動提升,不能因 dashboard 被標已讀就消失。這讓 observability 從觀看圖表變成可追責的處理流程。
復原完成後要跑 recovery-specific acceptance。除了原 feature suite,還要驗 reservation 全部對帳、舊 lease 失效、stale session 無法再 dispatch、effect count 正確、checkpoint 指向新 state、redacted trace 完整、environment cleanup 仍 scoped。若只看畫面恢復,可能留下雙重 worker、凍結 budget 或可被舊 token 操作的背景工作。每個事故樣本都進 retained fixture,並標示何時可退休與哪一版修復。
成本對帳要區分估計與供應端回報。Runner 在 call 前用保守估值 reserve,完成後保存實際 token、工具費、執行時間與資料量;兩者差距持續放大時,先修 estimator,不把超支歸咎於單一 session。Reviewer time 也要按 task class 記錄,因為低模型費用但高人工排錯的 harness 並不便宜。報表呈現中位數、尾端與超標案例,不用平均值掩蓋少數長迴圈。每項 budget 都有 soft warning、hard stop、owner 與變更紀錄,臨時放寬只能套在明確 run 且會到期。
Telemetry 自身故障時,系統要採保守路徑。若 critical event 無法持久化或 effect receipt 無法讀取,停止新的 consequential dispatch,將目前 run 標為 observability_degraded,保存本機安全 checkpoint 並通知 owner。唯讀探索是否可繼續,由 task policy 事先決定,不能由 agent 自行推測。恢復後先補送可驗 hash 的 events、對帳 effect 與 budgets,再決定 resume;缺口無法補齊就維持 hold。這避免監控失效時系統反而進入最難稽核的自治狀態。
動手實作
替 Release Desk run 加 event、budget 與 crash drill
加入 event schema、budget ledger、non-progress detector、checkpoint validator、effect reconciliation 與 kill control,執行五個 crash boundaries 和一個 loop。
準備項目
- • 在 input、tool output、environment 與 screenshot metadata 放 fixture canary 測 redaction
- • Commit healthy checkpoint,記 expected state、branch、environment、effect 與 budgets
本課產出
Versioned event contract、trace fixture、multi-dimensional budget ledger、progress detector、五份 crash receipts、redaction report、kill/restore drill 與 recovery runbook。
起始模板: Harness event envelope
JSON Schema{"type":"object","required":["eventId","runId","taskId","type","occurredAt","payloadVersion"],"properties":{"type":{"enum":["state.changed","tool.dispatched","tool.observed","check.completed","effect.reconciled","budget.changed","run.terminated"]},"evidenceIds":{"type":"array","items":{"type":"string"}}}}可下載的實作檔
Harness event schema
harness-event.schema.json · JSON Schema
An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.
Run receipt template
he-08-receipt.json · JSON
A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.
驗收指令
npm run harness:recovery -- --faults fixtures/crash-boundaries.jsonl --kill-drill預期 receipt
PASS he-08 observability-recovery
crashBoundaries=5 logicalEffects=1 duplicateWrites=0
canaryHits=0 killScopeViolations=0 budgetsReconciled=true預期結果
Background run 在 evidence 與 state 不再前進時停止;每個 interruption 都有 deterministic recovery,budget 可對帳,operator 不看 transcript 也能介入。
留給下一課
用 event 與 budget distribution 決定 parallel 是否值得。Recovery runbook、kill drill 與 terminal taxonomy 會進 capstone。
驗收條件
- 01Events 能重建 contract、commit、environment、state、tools、checks、effects、budgets 與 terminal
- 02Non-progress 依 declared unchanged cycle 停止,不受 paraphrased prose 欺騙
- 03五個 crash boundaries 都維持一個 logical effect,依 certainty 選 retry 或 reconcile
- 04Kill/restore 僅作用 owned resources,拒 stale authority 並保存 named operator event
常見故障
故障診間
F1Trace 很大,仍說不出 run 為何停止。
- 先檢查
- 查 correlation、state version、terminal event、budget、effect 與 evidence link。
- 可能原因
- 只記 raw text,沒有 control decision 與 authoritative transition。
- 修復方式
- 補 typed event 與 evidence ID,刪除不能回答操作問題的欄位。
- 下次怎麼避免
- 將 trace reconstruction 設為 acceptance case。
F2Resume 重複一筆 crash 前已完成的 write。
- 先檢查
- 比 dispatch reservation、idempotency、effect ledger、checkpoint 與 observation。
- 可能原因
- 把 missing observation 當作 effect 未發生。
- 修復方式
- 從 authoritative ledger reconcile,補 observation,禁止再次 dispatch。
- 下次怎麼避免
- 每個 effect boundary 前後都 crash,assert logical 與 physical counts。
F3Kill switch 關掉另一個本機專案。
- 先檢查
- 檢查 environment ID、lease ownership、PID、port、path 與 target list。
- 可能原因
- 用 broad port 或 process match,沒有 task ownership。
- 修復方式
- 復原不相關程序,改成 exact environment resolver,加 collision fixture。
- 下次怎麼避免
- Action 前列印並驗 exact targets,拒 broad path、empty variable 與 port-only ownership。
展示版之後
正式上線前的邊界
- 01Event schema 有 stable correlation、version、redaction、retention 與 access policy
- 02Turn、call、time、byte、change、retry、spend 在 dispatch 前 reserve 並對帳
- 03Progress 依 action、observation、evidence、diff 與 state,不依文字新鮮度
- 04每個 terminal reason 有 operator packet、safe next action、owner 與 resume policy
- 05Recovery 重驗 identity、permission、environment、Git、contract、state、lease、budget、approval 與 effects
- 06Kill、restore、crash、outage、unknown effect、stale authority 與 unrelated collision 定期演練
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張,不代表換一個系統也會得到相同結果。
- [1]長時間執行 agent 的有效 harnessinitializer 模式 · feature ledger · session 交接 · 端到端驗證
Anthropic · 已發表研究 · 2026-08-26
- [2]長時間應用程式開發的 harness 設計planner、generator、evaluator · 可測合約 · 簡化 harness · 成本取捨
Anthropic · 已發表研究 · 2026-08-26
- [3]Harness engineering:在 agent-first 開發環境中運用 Codex知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
OpenAI · 公開案例 · 2026-08-26
- [4]Harness Engineering Guide執行環境邊界 · 工具系統 · sandbox · 復原模式
Nexu · 公開案例 · 2026-08-26
- [5]打造有效的 agent採用能通過需求的最簡架構 · workflow 模式 · 環境回饋 · 停止條件
Anthropic · 官方文件 · 2026-08-26
延伸的 Tenten 資源