Harness 工程完全指南

大多数人都在错误的层面上改进 AI 智能体：失败了就重写提示词，再失败就加更多指令、换模型、加工具、扩上下文。但 @LunarResearcher 在这篇 19 节指南里指出：许多智能体的失败不是推理失败，而是环境失败——代理不知道哪些文件重要、在错误的地方用了正确的工具、丢了上次会话的决策、没跑检查就宣称成功。

证据链：动模型不如动 harness

• @FakeMaidenMaker 引用的数据：SWE-Bench 作者的 ProgramBench（从零重建真实开源项目、不联网、只验行为），Claude Opus 4.7 / GPT-5.4 / Gemini 3.1 Pro 完成率全是 0%；
• LangChain 实验：同一个 gpt-5.2-codex，权重一字没动，只优化周围工程结构，Terminal-Bench 2.0 从 52.8 分涨到 66.5 分，排名从 Top 30 开外冲进 Top 5；
• OpenAI 案例：3 人小团队 5 个月驱动 Codex 写出约 100 万行代码、合并约 1500 个 PR；
• @undefinedKi 在"智能体五层工程"课程里给的对照：Anthropic 只改容器资源提 6 分、LangChain 冻结模型只改 harness 提 13.7 分、10 倍便宜的开源模型调 harness 做到 0.86、对标 Opus 4.8 的 0.87。

业界公式：代理 = 模型 + 驱动程序。演进脉络是：提示词工程（内层，关心怎么下指令）→ 上下文工程（中层，关心给什么信息）→ Harness 工程（外层，把前两者包在里面，再加工具编排、状态持久化、验证循环、任务拆解、子 Agent、权限沙箱、回滚）。

以下来自 @LunarResearcher。模型可以推理、生成、比较和选择，但智能体还必须与真实环境交互：了解任务、找背景、选工具、保留状态、尊重权限、检查结果、从失败恢复、证明工作完成。模型是系统内部的推理引擎，Harness 是让推理得以实际运行的一切。

复制user request
     |
     v
+-----------------------------+
|           HARNESS           |
| contract | context | policy |
| tools    | state   | checks |
| traces   | recovery          |
+-----------------------------+
     |
     v
    model
     |
     v
real environment

大多数智能体任务始于模糊意图，比如"优化新手引导流程"。这句话够开启一段对话，但不够自主执行。在代理动手前，harness 应把请求转成任务契约，回答五个问题：

1. 必须产出哪种结果？
2. 范围内有什么？
3. 什么绝不能改变？
4. 有什么证据能证明已经完成？
5. 哪些操作需要人工审批？

复制objective: reduce onboarding drop-off

scope:
  - signup flow
  - onboarding analytics

constraints:
  - do not change authentication
  - preserve existing mobile behavior

acceptance:
  - tests pass
  - analytics event is emitted
  - screenshots cover desktop and mobile

approval_required:
  - production deployment
  - database migration

以下来自 @LunarResearcher。把整个仓库、文档集、对话历史一股脑塞进上下文，不是上下文工程，是刷屏灌输语境。正确做法是先给一张简要地图，相关信息出现时再取详情——渐进式披露：

复制task
  -> project map
      -> relevant subsystem
          -> exact files
              -> local instructions

工具网关：不是堆砌工具

给智能体 20 种工具，不会让它更有能力，只会给它 20 种犯错的方式。每个工具都该有契约：输入、前置条件、成功证据、失败行为、风险等级。关键区分：

复制model decides intent
gateway validates action
tool changes environment
sensor observes result

以下来自 @LunarResearcher。许多脆弱的智能体把推理、工具调用、文件、决策、错误、旧观察全混进一份不断增长的记录，争抢同一个上下文窗口。更强的系统分离三项职责：

复制BRAIN
plans, reasons, chooses

HANDS
execute tools inside a controlled environment

HISTORY
stores durable facts, decisions, and run state

对话历史不是可靠记忆，它只是事件流。有用的记忆要转成显式状态，至少保留四类：

复制FACTS      稳定信息：checkout validation lives in services/orders
DECISIONS  决策及原因：reuse existing validation pipeline
PROGRESS   已完成/进行中/阻塞/待办
LESSONS    该改变未来行为的失败：local test needs TEST_DB_URL

以下来自 @LunarResearcher，本节四个机制一次讲完。

1. 完成需要证据

Agent 说 done 只是又一个模型输出。完成必须由环境中可观察的变化来判定：

复制claim                    evidence
"the bug is fixed"       failing test now passes
"the page works"         browser flow completed
"the migration is safe"  dry run and rollback pass
"the report is correct"  values match source data

2. 验证应该针对结果：worker 造，verifier 证伪

工作者和评估者目标不该相同：worker 造最强解，verifier 找拒绝它的理由。如果让同一个 agent 在同一上下文里"double-check"，它会保留制造错误的那些假设。

3. 模型提议，政策授权

有些规则绝不能依赖模型记不记得：never publish without approval、never expose a secret、never write outside the workspace、never exceed the spend cap。它们不是 prompt 建议，是政策，要放在推理循环之外：

• 低风险（读文件、搜索）：自动；
• 可逆变更（改工作区、跑测试）：自动+留痕；
• 外部效应（发消息、部署、购买）：显式审批；
• 不可逆/敏感（删数据、转凭证、公开发布）：硬门禁或禁止。

后果越强，门越硬。自主不是没有控制，而是在清晰执行的边界内自由运作。

4. 恢复要针对失败类别

"出事了，重试"不是恢复，是重复。harness 先分类再选动作：tool timeout→backoff 重试；invalid arguments→修复调用；missing context→检索特定来源；permission denied→申请审批或走安全路径；repeated unchanged failure→停 loop。重试必须改变至少一个相关条件，否则就是在花钱复现同一次失败。

以下来自 @LunarResearcher。

指令要变成基础设施

重要的规则越往下沉越可靠，形成 instruction ladder：

复制explanation -> checklist -> template -> automated check -> enforced policy

"use the formatter"            -> run formatter automatically
"do not import across layers"  -> add architecture test
"cite every external claim"    -> validate citation coverage

观察运行，而不只看最终答案

干净的终稿能藏住糟糕的过程：访问了错的数据、忽略了失败的命令、把外部动作重试了两次、烧了十倍预算、理由错了但答案对了。你需要可重建的 trace：状态转换、上下文来源、工具输入输出、环境变更、验证结果、重试原因、审批决策、成本与延迟。目标不是监视，是局部修复——第 18 步失败时从可信检查点重启，而不是重跑全程。

每次运行要有一张变更收据

收据不是"模型说了什么"的摘要，是"系统能证明什么"的摘要：OBJECTIVE / CHANGED / VERIFIED / NOT VERIFIED / DECISIONS / RISKS / APPROVAL NEEDED。最好的交接不是"这是对话记录"，而是"这是状态、证据和未解决的风险"。

Harness flywheel 与 harness decay

弱团队修失败的输出，强团队还修允许失败的系统：每次失败后问"任务契约模糊吗？上下文不可见吗？工具给错了吗？"，然后把教训转成新的 sensor、rule、map、test 或工具契约——这就是 harness flywheel，失败留下基础设施。

以下来自 @LunarResearcher。不需要编排平台也能起步，按层构建：

可复用的 AGENT HARNESS SPEC（八块）

复制1. CONTRACT      objective / scope / constraints / acceptance evidence
2. CONTEXT       always-loaded map / retrieval sources / freshness rules
3. TOOLS         allowed tools / preconditions / side effects / retry policy
4. STATE         facts / decisions / progress / lessons / checkpoint format
5. POLICY        automatic / approval-required / prohibited / budget limits
6. VERIFICATION  deterministic checks / adversarial checks / acceptance rule
7. RECOVERY      failure classes / retry limits / escalation / rollback
8. OBSERVABILITY trace events / metrics / final change receipt

如果这些字段没定义，agent 不是自主，是在即兴发挥。度量单位：accepted outputs ÷ (human review minutes + run cost)——目标不是更多 agent 活动，而是单位人工注意力换来更多可信产出。

以下来自 @FakeMaidenMaker 的中文导览。先用 Harness 的 5 个维度给你的配置做体检：

Anthropic / Claude Code：教科书级长任务工程

OpenAI / Codex：面向 AI 重构开发环境

Nous Research / Superpowers：开源可复用 Skills 框架

三个反直觉原则

以下来自 @undefinedKi。如果你只想动手，这六个决策就是清单。定义先行：harness = 模型与工作之间的六样东西（循环、工具、记忆、崩溃保留、权限、完成判定），一半供应商给，一半你自己设计。

决策 1：循环，以及它在哪里停止

• 一句话写下停止规则："完成意味着测试套件通过且应用成功启动"，而不是"智能体说完成了"；
• 糟糕结局二选一：附失败原因重跑，或暂停等你指示；
• 硬上限：轮数/时间（对同一文件试 40 次的 agent，第 41 次也不会修好）；
• 无人值守就把每轮记到文件里。

实证：50 个已发布循环仅 74% 明确完成定义、32% 跨运行保留记忆——这是最便宜却最常被跳过的修复。

决策 2：它能看到的工具

• 别全量加载：MCP 工具描述每轮都进上下文，Anthropic 案例从 150K 降到 2K tokens；
• 重写错误信息为结构化（哪个字段错、有效值长什么样、下一步试什么）：西门子实测完成率 +37~40 个百分点、token 减半；
• 精简菜单：一个月没见它用的工具删掉；命名和分组会可度量地改变行为。

决策 3：哪些内容留在记忆中

• 别填满：百万 token 模型跑到 30–40 万就停，之后故障像"粗心"不像"困惑"；
• 阶段式主动精简，别等自动压缩在中途触发；
• 规则双保险：放进每次重置都重读的文件 + 系统提示词重复一遍；
• 模型连续 5 次附和你就重启会话。

研究数据：规则完整呈现违规率 0%，压缩后 30%，最差模型 59%（单作者未同行评审，视为强烈提示）。

决策 4：崩溃后保留什么

四个文件 + 每次变更提交：SPEC.md（你写，agent 不改，防目标漂移）、PLAN.md（每步带验收标准）、PROGRESS.md（新 agent 先读它）、DECISIONS.md（只追加）。"如果它不在文件中，就等于不存在。"

决策 5：它可以接触什么

• OS 层两道边界：写目录限制 + 网络代理域名白名单（应用内限制绕得过，OS 层绕不过）；
• 别信审批提示：93% 被直接点通过，总通过的提示不是安全控制是延迟；
• 共享系统前加网关，只发任务声明的工具并记录每次调用；
• 长期凭证不进沙箱，用单任务短期 token。

Anthropic 加沙箱后权限请求降 84%——更安全，也更不烦人，才能坚持用。

决策 6：谁说它完成了

• 单独会话审查（新窗口，不带写代码时的推理）；
• 真正运行起来（浏览器/CLI 实操，不是读 diff 宣布正确）；
• 从失败案例建 eval 集（20–50 个任务起步）；
• 每任务跑 3 次按最差评判：75% 单次成功率 → 三跑全过仅 42%；
• 警惕 confident wrong answer：生产研究约 70% 靠人发现，报错附近找"解释型文本"。

三个大厂形态对照：DoorDash 平台化（每 agent 独立临时 VM + YAML runbook + 网关，单月 13 万任务、周 2.5 万+代码审查）；OpenAI 代码仓库即 harness（约 100 行指令 + 自定义 linter，3 工程师 5 个月合 ~1500 PR）；Anthropic 三 agent 分工（spec→实现→浏览器验证，6 小时/$200 vs 20 分钟/$9，贵 20 多倍但结果显著更好）。

OpenAI 开源 Codex harness：可复用的部分是 agent loop

以下来自 OpenAI 官方博客。Codex App / CLI / IDE 扩展只是表层，真正的可复用层是开源的 agent harness（github.com/openai/codex）：收集上下文、推理、调工具、执行边界、请求审批、跨 turn 延续工作。Harness 设计能实质改变结果：ARC-AGI-3 上，retained reasoning + context compaction 让 GPT-5.6 Sol 从 13.3% 提升到 38.3%，输出 token 降为 1/6。

三层集成选型：codex exec（脚本/CI/一次性后台任务，返回结构化输出）；Codex SDK（程序化启动/恢复/流式任务）；app-server（agent 作为产品本身：持久对话、流式事件、中断、暴露工具、审批）。架构分工：应用拥有产品上下文、业务规则与工具（含应用自有的 MCP 服务），Codex app-server 提供 agent loop 与沙盒执行。

落地案例：GitHub 和 JetBrains 把 Codex 接入 IDE；思科在 Cloud Control App Builder 用 Codex SDK；Thrive Holdings 和 Crete 在税务流程用 Codex，试点处理 7,000 份申报表，准备时间缩短约 1/3。机会不是用通用聊天框取代界面，而是给已有界面（dashboard/时间线/地图/文档）加一个懂工作的 agent。

附录资源

以下来自 @bozhou_ai（2026-08-09）的推荐帖：Anthropic 发布了 37 分钟免费指南，由构建 Claude 的工程师出品，讲如何构建能自动化整个公司的 AI 智能体（自主工作、分配任务、独立执行）。作者已烧录中文字幕并附中文课件（飞书文档）。评论区 @An_yhl 提示：先不谈自动化整个公司，任务拆分那段更值得看；另有西班牙语字幕版本流传。原文链接见页脚。