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更聪明，而是因为你更诚实。