第 16 章 · 生产级 Harness 七层架构

本篇目标：搭出「凌晨三点没人看着也能安全跑完」的系统。 社区 生产 Harness 与编码 Harness 的根本差别：编码 Harness 每个 loop 末端都有一个人，生产 Harness 常常没有。

16.1 两种 Harness 并排

社区 对照表（左列为常见工程实践，右列为 Heym 公开运行时的实现，仅作参照，不是规范）：

判据 20：把「有人会看」当成默认传感器，是生产事故最常见的设计假设。无人值守时，gate 必须坐在 run 内部，sensor 必须按时间窗触发。

16.2 七层运行顺序

① Guide      事前引导        → 系统提示词 / skills / tool 描述
② Constrain  环境约束        → 沙箱 / guardrails / 深度与时间上限
③ Gate       副作用前审批    → pending + 一次性 review link
④ Sense      事后反馈        → trace / eval / 确定性检查
⑤ Alert      时间窗告警      → error / duration / cost / execution count
⑥ Audit      贯穿全程        → 一行一动作，脱敏后落持久存储
⑦ Recover    失败恢复        → fallback 凭据 / fallback 模型 / Error Handler

社区 一句关键判断："Each stage catches a different failure, so a production harness needs all of them, not the strongest one." 只做最强的那一层，其余六类失败照旧发生。

16.3 逐层落地清单

① Guide

• system prompt 只写模型无法从代码推断的内容（命令、禁区、done 的定义）
• 大份文档做成 skill，按需 prepend；skill 的 Python 文件可变成 Agent 可调用工具
• node 作为 tool 暴露时，只允许 Agent 填标记为 agent-provided 的字段；其余保持配置值（例：未授权时 Agent 不能改 Slack channel）
• tools 来源明确：MCP（stdio / SSE）、sub-agents、workflow nodes

② Constrain

社区 一组可直接借鉴的默认值（Heym 公开运行时，不是通用规范，按自己场景调整）：

"No defaults for safety decisions." 社区 缺 placement 就让构建失败，缺 sandbox 就让 run 失败。任何静默 fallback 都在隐藏一个本该有人拍板的安全决策。

③ Gate

• 开启 human review 后，Agent 获得 request_human_review 工具，run 转为 pending
• 生成一次性 review link；社区 参照值 168 小时过期
• 三种结果：Accept / Edit & Continue / Refuse；从 stored snapshot 恢复
• gate 只放在 side effect 前：send / pay / delete / change records
• 原则：fewer, better gates —— 每步都 gate 会训练审核者无脑点 Accept

④ Sense

• 每次 model call 与 tool call 全记：status、start、finish、duration
• payload 脱敏 + 限制大小
• 开 OTel 时导出 workflow span / 每 node span / 每 tool call span
• eval 用例来自真实输入；评分用 Exact Match / Contains / LLM-as-judge（judge 温度 0）
• 能确定性检查的，一律不用模型判断

⑤ Alert

• 四类：error threshold、workflow duration、token/USD cost、execution count
• 基于时间窗，不基于单次事件：「一次失败是噪音，十分钟十二次是事故」
• 保存前对最近 24 小时做 backtest，避免静态阈值一上线就误报
• 告警与 cost budget 联动（第 18 章）

⑥ Audit

• 每条 security-relevant action 一行：who / to what / succeeded
• always on，不可关闭
• 字段名含 password / secret / token 的，写入前替换为 ***
• 日志不能只留在容器 stdout，必须 ship 到持久存储

⑦ Recover

• 配置 fallback 凭据 + fallback 模型；主 provider 失败先按第二套凭据重试
• blocked message 可被 Error Handler 捕获，不要直接崩掉整条流水线
• 每个失败路径写清：重试 / 跳过 / 升级人工，以及是否幂等（第 14 章状态契约）

16.4 从零起步的最低路径

社区 Heym 给的「这周就能开始」五步，不要求先有平台：

1. 写下最近 5 次 Agent 犯的错（症状 / 文件 / 正确行为）
2. 每条错误写一条带原因的规则（AGENTS.md 一节一条）
3. 给关键规则写 coverage test，失败消息写明修复方法
4. 给生产运行加传感器：全量 traces + 真实输入的 eval suite
5. 在 side effect 前加 gate，并配时间窗告警与审计

顺序很重要：先有失败记录，再有规则；先有规则，再有测试；先有 traces，再有告警。 反过来做（先上平台再找问题）通常得到一个很贵但没人用的 Harness。

16.5 在 DSH 上的映射

⚠️ 重要边界：官方 SAFETY.md 明确 DSH 未经过安全审计、不得视为生产就绪。上表是「用 DSH 作为参照实现来理解七层」，不是「把 DSH 直接搬上生产」的建议。真正上生产请走隔离容器、固定版本、自建告警与审计，详见第 17 章。

16.6 本章产出与验收

核心产出：一份七层逐项勾验的 checklist（可直接用 appendix/production-checklist.md），加一次无人值守 7×24 试跑记录。

验收点：

• 能说明为什么 gate 只放 side effect 前
• 能列出四类时间窗告警，并解释为何不用单事件阈值
• 能指出自己系统里缺失的层，并说明该层专门拦截哪类失败
• 能说清 fail closed 与静默 fallback 的区别
• 能解释「DSH 不能视为生产就绪」对架构决策的约束

延伸阅读