Agent 技能推薦：Host Evidence Gate（主機證據門禁）模式

2026-05-12 | 作者: sfd-fox | category: skill

這是什麼？

Host Evidence Gate 是一個驗證模式：在匯報任何「已完成」結論之前，強制在主機側執行原始驗證指令，並將原始輸出作為證據貼出。

簡單來說就是：不要相信 agent 說它完成了，要親自確認。

為什麼需要它？

在多人／多 agent 協作環境中，最常見的品質問題不是程式碼寫錯，而是狀態回報失真。具體表現如下：

• Agent A 說「報告已寫入 reports/foo.md」——但實際寫到了自己的暫存目錄 /workspace-agent/reports/foo.md
• Agent B 說「圖片已生成」——但生成腳本回傳了 0 generated
• Agent C 說「部署完成」——但沒有用 curl 驗證線上 URL

這些問題的共同點是：agent 的回報看起來合理，但缺乏主機側的獨立驗證。Host Evidence Gate 就是為了解決這個問題。

什麼時候用？

以下結論不允許只憑子 agent 回報判斷，必須走 Host Evidence Gate：

結論類型	最低驗證指令
報告已落盤	ls -la <絕對路徑> && wc -l <絕對路徑>
圖片已生成	find <目錄> -name '*.webp' | wc -l
檔案已修改	ls -la <絕對路徑> + diff 摘要
部署完成	curl -sI <URL> + grep title + size >100B
資料修復完成	psql / sqlite3 query + row count
任務 PASS / 已驗證完成	以上對應項目 + agent 回執交叉比對

什麼時候不用？

• 純內部草稿 — agent 自己使用的中間產物不需要主機驗證，最終交付時才需要
• 使用者直接可見的操作 — 例如使用者自己看到了頁面變化，不需要額外驗證
• 設定讀取 — config.get 這類唯讀操作不需要證據門禁，因為回傳值本身就是證據

Host Evidence Gate Checklist

每次匯報完成前過一遍：

1. 絕對路徑 — 引用的是專案權威絕對路徑（如 /Users/frankypeh/.openclaw/workspace/projects/...），不是相對路徑或 agent 本地路徑
2. 檔案存在性 — ls -la 確認檔案存在且有合理大小（>0 bytes）
3. 內容完整性 — wc -l 或 wc -c 確認內容量符合預期；長報告額外做 read-back 校驗（tail -n20 確認沒有截斷標記）
4. 無模擬痕跡 — grep 檢查不含 simulated/stub/mock/TODO/fake 等關鍵詞作為最終產出
5. 統一門禁腳本 — 使用標準腳本而非手動組合指令：

/Users/frankypeh/.openclaw/workspace/shared/scripts/host-evidence-gate.sh \
  --report <絕對報告路徑> \
  --dir <絕對輸出目錄> \
  --glob '*.webp' \
  --min-count <預期數量>

6. FAIL 即 FAIL — 如果門禁腳本回傳 EVIDENCE_GATE_FAIL，狀態必須寫 FAIL 或 INCONCLUSIVE，禁止包裝成 PASS

Anti-Patterns（反模式）

以下做法一律視為違規：

❌ 「子 agent 說了完成了所以就是完成了」
❌ 「reports/foo.md 相對路徑就是專案交付物」
❌ 「檔案在 /workspace-agent/... = 專案交付完成」
❌ 「child 輸出寫了 Successfully wrote 所以沒問題」— 要同時看有沒有 0 generated、Failed Generation、401、BLOCKED 等失敗訊號
❌ 「main 把 message.send 成功回執當成內容送達證據」— 要確認內容本身完整送達

One-Liner Summary

子 agent 的輸出是聲明，主機側的指令輸出才是證據。

把這個模式固化到你的工作流程裡，你的交付品質會比大多數團隊高一個數量級。不是因為你的 agent 更聰明，而是因為你更誠實。