shield_lock
JinDaGe
← Back to skills
extension
Category: OtherNo API key required

Agent 输出多重保护机制 · Harness Engineering

Essential foundational skill for anyone building, operating, or reviewing AI Agents. Use this whenever designing, debugging, or hardening an Agent/LLM app for production reliability. Triggers on "why does my agent fail", "make my agent production-grade", "improve Agent reliability", "Harness review", "三道防线 review", "Agent 可靠性 review", or when changing an Agent's loop, tools, context, memory, verification, or feedback. Core thesis: reliability is rarely about a stronger model; it is about hardening the Harness — the 3 defense lines (pre-check / context compression / API recovery) and the 6-layer architecture (constraint / tool / context / memory / verification / feedback).

personAuthor: user_e8a8339chubcommunity
downloadDownload package

Harness Engineering · 让 Agent 在生产环境不崩的工程基石

🛡 多重保护机制的建立，是目前 Agent 最欠缺的能力。 它保证所有输出都有边界、有刹车、有安全冗余——而不是把模型直接推向无防护的生产环境。

为什么这是每个 AI 时代 Agent 使用者都该装的基础 Skill

你写了一个 Agent，demo 跑得飞起，一上生产就：误删文件、上下文爆炸、API 抖动后崩、烧钱不收敛、配额耗尽页面空白。 这些几乎都不是模型的问题——是 Harness（模型之外的工程结构）没焊牢。

一个被反复验证的事实：提升 Agent 可靠性的最高效路径，往往不是换更强的模型，而是改进 Harness。把同一份模型套上不同的 Harness，结果天差地别——同一个模型，套上严谨的 Harness 能 5 步闭环一气呵成，套上松散的 Harness 却上下文溢出崩溃。不是模型不会做，是 Harness 不同。

本 skill 把"让 Agent 在生产环境站稳"这件事，沉淀成可复用的三道防线、六层架构、五个原则，并附自检脚本。无论你用哪个模型、哪个框架，这套结构都通用。装上它，等于给你的 Agent 项目装上一份"可靠性验收清单"——每一个开始调用 Agent 的人，都应该先读这一份。

Agent = Compose(Model, Harness) —— 提升 Agent 可靠性的最高效路径不是换更强的模型，而是改进 Harness。三道防线（发送请求前的预检 / 上下文接近满载时的自动压缩 / API 报错后的恢复）一旦同时失守，再强的模型也会失败。

何时启用本 skill

✅ 用于以下场景：

  • 评审 / 调试一个 AI Agent 在生产中失败、卡死、烧钱、上下文爆炸、API 报错后崩溃的根因
  • 设计新的 Agent Harness 时检查是否覆盖 6 层架构、5 个设计原则
  • 评估"换模型 vs 改 Harness"的取舍（90% 的情况下答案都是后者）
  • 给团队成员讲清楚"为什么 Agent 在 demo 阶段能跑、生产阶段就崩"

❌ 不适用：单纯 Prompt 调优、单次问答、模型选型横评、与 Harness 无关的话题。

核心公式

Agent = Compose(Model, Harness)
  • Model：大模型本身的能力（包括推理、生成、理解）。
  • Harness：模型之外的所有工程结构 —— 工具、约束、上下文、记忆、验证、反馈、可观测性、权限、预算……
  • Compose：把两者组合起来的运行循环（Agent Loop）。

同一个 Model 套上不同的 Harness，会得到截然不同的结果。Claude Code 5 步闭环一气呵成，Claw Code 上下文溢出崩溃 —— 不是模型不会做，而是 Harness 不同。

🔰 三道防线（用户引用的核心）

失败原因不在模型不会做，而在 Harness 的 3 道防线同时失守。每道防线都有明确的"何时触发 / 谁负责 / 失守的典型症状 / 推荐修复"。

防线 1：发送请求前的预检（Pre-check）

| 项 | 说明 | |------|------| | 何时触发 | Agent 即将调用工具 / 发起 HTTP 请求 / 写入文件 / 触发副作用动作之前 | | 谁负责 | Harness 约束层 + 工具层 | | 要预检什么 | ① 路径是否在沙箱白名单内 ② 命令是否命中危险列表（rm -rf / 删库 / 推送 / 付款 / 对外发布） ③ 输入是否含敏感数据（PII / 凭据 / 越权指令） ④ 工具参数 schema 是否合法 ⑤ 上下文是否已满载（如果满载，应先压缩再发） | | 失守症状 | Agent 误删文件、误推代码、误发邮件、Prompt Injection 把高危指令塞进读到的内容里就执行了 | | 对应章节 | 第 3 章约束层（3.2 路径安全 / 危险命令 / 危险内容；3.4 沙箱隔离机制；3.5 权限模式与运行时守卫） |

防线 2：上下文接近满载时的自动压缩（Context Compression）

| 项 | 说明 | |------|------| | 何时触发 | Token 用量达到阈值（建议阈值：模型窗口的 70% / 80% / 90% / 98% 四级） | | 谁负责 | Harness 记忆层 + 上下文层 | | L0-L3 级渐进压缩 | L0 工具返回即时裁剪（默认）→ L1 旧工具返回替换为摘要（70%）→ L2 模型生成全局摘要（85%）→ L3 窗口溢出紧急截断 + 断点续传（95%） | | 关键原则 | 压缩是有损的，但目标不能丢（保 compact instruction：当前任务、约束、已完成步骤、待办）。工具调用必须配对修复（tool call 与 tool result 一起裁，不能孤立裁 tool result，否则模型会幻觉补调用） | | 失守症状 | 长会话后期回答质量悄悄下降（信噪比塌陷、上下文腐烂）、超过窗口直接 400 报错、Agent 在结尾突然跑题 / 重复动作 / 忘记上下文约束 | | 对应章节 | 第 6 章 6.1 上下文腐烂 + 6.2 L0-L3 渐进式有损压缩 + 6.3 4 级压力响应 + 6.5 JSONL 断点续传 |

防线 3：API 报错后的恢复（API Recovery）

| 项 | 说明 | |------|------| | 何时触发 | 模型 API / 工具 API 返回 5xx、超时、配额耗尽（code 429/50112）、schema 校验失败、网络抖动 | | 谁负责 | Harness 工具层 + 反馈调节层 | | 4 级恢复阶梯（2.1.4 节） | L1 自动重试（指数退避，最多 3 次）→ L2 切换备用模型/备用节点 → L3 降级为只读 / 截断输出 / 简化任务 → L4 升级到人（人在环中、高风险动作） | | 关键配套 | 重试必须幂等（同一请求多次发起不会产生副作用）；配额耗尽必须自动回退本地缓存快照（lastgood）；每一次失败都要写结构化日志便于事后挖掘 | | 失守症状 | Agent 在某次 API 抖动后整体崩溃、烧钱继续调用同一个失败端点、配额耗尽后页面空白而非回退到已知可用数据 | | 对应章节 | 第 2.1.4 节纠正：4 级恢复阶梯 + 第 12 章 12.2 成本熔断与模型路由 + 第 8.4 在线观测与漂移告警 |

铁律：3 道防线同时失守才会出现生产级灾难。任意 1 道还在工作，Agent 都能从错误中恢复。设计 Harness 时，先确保这 3 道防线都至少有一道闸门，再考虑其他层。

🧱 6 层参考架构

| 层级 | 职责 | 失守的典型症状 | 关键章节 | |------|------|----------------|----------| | ① 约束层 | 沙箱、路径白名单、危险命令拦截、权限分级、预算熔断、LoopGuard | Agent 越权写文件 / 误删 / 误推；无限循环空转 | 第 3 章 | | ② 工具层 | 工具注册、参数 schema、MCP 接入、工具描述精度、动态管控 | Agent 选错工具 / 调错参数 / 重复调用同一工具 | 第 4 章 | | ③ 上下文层 | AGENTS.md 精简、系统提示词拼接顺序、Prompt Cache 静态前缀最大化、3 层文档架构 | 上下文腐烂、token 浪费、Cache 命中率低、长会话后行为漂移 | 第 5 章 | | ④ 记忆层 | L0-L3 渐进压缩、跨会话长期记忆（6 层记忆架构）、JSONL 持久化、断点续传 | 长会话后期回答质量塌陷；超窗口崩溃；中断后无法恢复 | 第 6 章 | | ⑤ 验证层 | 计算性验证 vs 推理性验证、独立 Evaluator、4 层循环守卫、Plan Mode 事前验证、5 个评估维度 | Agent 自评高分但生产失败；无限反思；行动前没看清边界 | 第 7 章 | | ⑥ 反馈调节 | 离线评估（Subject-Task-Runner）、在线观测、JSONL 日志、漂移告警、Red Team、灰度发布、影子测试 | 错误模式反复出现却没人知道；优化靠运气不靠数据 | 第 8 章 |

设计原则：6 层任意一层缺失，Harness 都可能在生产中失守。最常被忽视的是 ⑤ 验证层和 ⑥ 反馈调节 —— 这两层不显眼，但缺了就会让前 4 层的努力变成"自嗨"。

🧭 5 个设计原则（递进关系）

约束 → 告知 → 验证 → 纠正 → 人在环中
  ↓      ↓      ↓      ↓        ↓
边界   路径   质量   恢复    兜底
  1. 约束（Constraint）：3 条红线 —— 边界、能力、风险。先划清"绝对不能做"。
  2. 告知（Inform）：缩短试错路径。AGENTS.md、工具描述、错误信息本身就是反馈。
  3. 验证（Verify）：闭环反馈。每步都要有"对不对"的判断，不能靠 Agent 自评。
  4. 纠正（Correct）：4 级恢复阶梯（详见三道防线之 API 恢复）。
  5. 人在环中（Human-in-the-loop）：分级授权。高风险动作（删 / 发 / 付 / 推送）必须人工审批。

5 个原则递进：前一个做不好，后一个就形同虚设。

🩺 失败诊断速查表

| 你看到的问题 | 别换模型，先检查这道防线 / 这一层 | |-------------|----------------------------------| | Agent 误删文件、误推代码 | 约束层 · 危险命令拦截 / 路径白名单 | | Agent 调错工具 / 重复调用 | 工具层 · 工具描述精度 / 动态管控 | | 长会话后回答质量悄悄变差 | 记忆层 · 上下文腐烂 / 没接 L1-L2 压缩 | | Agent 跑题 / 重复动作 / 烧钱不收敛 | 验证层 · 没接循环守卫 / 没设停止条件 | | 某次 API 报错后整体崩 | 反馈层 · API 恢复 / 4 级阶梯缺位 | | 配额耗尽页面空白 | 反馈层 · 没接 lastgood 自动回退 | | 演示能跑生产就崩 | 多半是验证层 + 反馈层缺位（这两个最容易被 demo 阶段掩盖） | | Agent 把读到的内容当指令执行 | 约束层 · 没做内容脱敏 / 危险内容检测 |

🛠️ 设计 Harness 的最小检查清单（自检用）

□ 约束层：路径白名单 + 危险命令列表 + 沙箱隔离
□ 约束层：LoopGuard（最大迭代 / Token / 时间预算 / 无进展检测）
□ 工具层：每个工具都有明确 schema + 错误码可解析
□ 工具层：高频工具调用结果走 L0 裁剪（默认）
□ 上下文层：系统提示词拆 base+project+rules，静态前缀最大化以提升 Prompt Cache 命中率
□ 上下文层：AGENTS.md 控制在一屏内，详细规则下沉到 docs/
□ 记忆层：70%/85%/95% 三档触发 L1/L2/L3 压缩
□ 记忆层：压缩后保持 compact instruction（目标 + 约束 + 已完成 + 待办）
□ 记忆层：JSONL 持久化 + 3 步唤醒（断点续传）
□ 验证层：每个关键动作后接验证（计算性 > 推理性）
□ 验证层：4 层循环守卫（重复检测 / 无进展检测 / 边界检测 / 超预算熔断）
□ 反馈层：所有 API 调用写 JSONL 结构化日志（含 request/response/latency/cost/error）
□ 反馈层：4 级 API 恢复阶梯（重试 → 切换 → 降级 → 升级）
□ 反馈层：配额耗尽自动回退 lastgood，页面透明标注 tplus_asof
□ 反馈层：每周跑一次 Red Team + 漂移告警

📚 三个实战案例（详见 references/case-studies.md）

  1. 遗留系统重构（第 9 章）：万行 Java 临床路径系统 → Harness 配置 + God Service 拆分 + 反馈闭环
  2. 医疗合规加固（第 10 章）：沙箱 + Hook + CLAUDE.md 三层防御 → PII 脱敏 + 审计日志 + 跨行业迁移
  3. 跨语言多 Agent 协作（第 11 章）：Architect / 2× Developer / QA Engineer → 文件作为协作接口 → 8 项 verify.py 验收

三个案例的共同模式：Harness 不是一次性建好，而是 执行监控 → 问题统计 → 规则优化 → 效果验证 的闭环迭代。

与 6 层架构 / 5 原则 / 3 防线 的映射关系

| 防线 | 主要落在哪一层 | 关键原则 | |------|----------------|----------| | 预检 | ① 约束层 + ② 工具层 | 约束（3 红线） | | 上下文压缩 | ④ 记忆层 + ③ 上下文层 | 约束 + 告知 | | API 恢复 | ② 工具层 + ⑥ 反馈层 | 纠正（4 级阶梯） |

→ 6 层架构是结构、5 原则是设计准则、3 防线是失守后果。三者视角互补，评审任何一个 Agent 都建议从这三个维度各问一遍。

常见误区

| 误区 | 反例 | |------|------| | "换更强的模型就好了" | 同样 Claude Sonnet，套 Claude Code Harness 全跑通，套 Claw Code 上下文溢出 —— 模型没变 | | "Prompt 写得越详细越稳" | Prompt 是模型读到的，Harness 是 Agent实际跑起来的。Prompt 工程 ≠ Harness 工程 | | "演示能跑就能上线" | 演示阶段几乎不触发上下文压缩、不触发 API 抖动、不触发 PII 数据、不触发长时间无人值守。生产场景才是 Harness 的真正考场 | | "约束越严越好" | 过度约束会让 Agent 失去完成任务的能力。约束的目标是"在限定范围内推理"，不是"完全不让推理" | | "6 层必须一次建全" | 推荐渐进式构建路径（2.6 节）：先做最便宜的约束层和验证层，再补工具层、上下文层、记忆层，最后做反馈层 | | "反馈层就是加监控" | 反馈层的核心是闭环：监控 → 发现问题 → 改 Harness 规则 → 灰度验证 → 全量 → 监控。单向监控 = 没有反馈 |

Resources

  • references/three-defense-lines.md：三道防线深度展开（预检 / 压缩 / 恢复的完整 checklist + 代码骨架）
  • references/six-layer-architecture.md：6 层架构的代码模块映射 + 业界实践对照
  • references/design-principles.md：5 个设计原则的递进关系 + 红线 + 错误模式
  • references/case-studies.md：3 个实战案例的可复用模板（重构 / 合规 / 多 Agent）
  • scripts/harness_self_check.py：3 道防线 / 6 层 / 5 原则自检脚本，扫描一个 Agent 项目报告缺哪些闸门

一句话记住

失败的根因往往不是模型不会做，而是 Harness 的 3 道防线同时失守。要修，先修 Harness；模型不动，效果常常立竿见影。