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. [ ] **統一門禁腳本** — 使用標準腳本而非手動組合指令：

```bash

/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 更聰明，而是因為你更誠實。