Harness Engineering：让 Agent 从“能工作”走向“可交付”

Agent 的本质是任务系统，不是生成器

一个聊天机器人主要负责生成回答，而一个 Agent 通常需要完成一项任务：读取资料、调用工具、修改文件、执行测试、处理失败，并在必要时向人请求决策。两者之间的差别，不仅体现在模型是否更聪明，也体现在模型周围是否存在一套能够约束行动、验证结果、保存状态和记录过程的工程系统。

Harness Engineering: Agent = Model + Harness: The 6-Layer Production Playbook

https://drive.google.com/file/d/1wZeuP0t4WOA2COMxcrU-Uv34IutM13UR/view

模型提供理解和推理能力，Harness 则决定模型可以访问什么、能够执行什么、失败后如何恢复、结果是否经过验证，以及整个过程能否被追踪和改进。

一张图理解 Harness

从流程上看，用户首先提出任务目标，模型据此进行规划和推理，并通过工具与上下文完成实际执行。执行结果不会直接被当作最终答案，而是进入测试、校验、权限和质量检查环节。验证通过后，系统才把结果标记为可交付；验证失败时，系统根据错误证据决定修复、重试或升级。

因此，Harness 可以被理解为 Agent 的“运行控制面”。它不替代模型的推理能力，而是为模型提供可执行的工作边界，并把一次性的生成行为转化为一个有反馈、有状态、有停止条件的任务流程。

Prompt → Context → Harness：工程重心的演进

2023 到 2024 年，工程重点主要是 Prompt Engineering，即通过调整措辞、示例和指令来影响模型在单轮交互中的输出。2025 年以后，Context Engineering 逐渐成为重要方向，工程师开始关注模型在执行任务时看到了哪些资料、工具、记忆和外部知识。进入 2026 年，报告进一步把关注点扩展到完整运行环境，也就是 Harness Engineering。

工程阶段	主要关注对象	主要优化内容	解决不了的问题
Prompt Engineering	模型如何理解任务	指令、示例、输出格式	无法稳定限制权限和执行成本
Context Engineering	模型能够看到什么	RAG、MCP、记忆、上下文组织	无法单独保证结果正确或动作安全
Harness Engineering	模型如何在环境中行动	验证、重试、权限、状态、日志和告警	需要更多工程建设和维护成本

这三个阶段并不是相互替代的关系。生产级 Agent 仍然需要清晰的 Prompt 和高质量 Context，但这些内容必须被放入一个能够验证和约束执行过程的环境中。Prompt 影响模型的思考方式，Context 影响模型可使用的信息，Harness 影响模型最终能够做什么，以及系统是否能够承受失败。

公开案例印证 Harness 的实际价值

报告引用的案例	报告中的结果	变化来源	应如何理解
GAIA 与 Claude Sonnet 4.5	30.91% 提升至 74.55%	报告称模型保持不变，增加结构化工具、验证循环和状态管理	说明运行环境可能显著影响任务完成率，但还应核对实验设置与评测协议
Terminal Bench 2.0	第 30 名提升至第 5 名	报告称模型不变，调整 Guides、传感器、恢复逻辑和工具配置	说明编码 Agent 的排名不仅取决于模型本身
Codex 生产项目	约 1,500 个自动化 PR、约 100 万行代码、零手写代码	人类主要设计指南、测试、审查和部署环境	说明人的工作可能从逐行编程转向设计 Agent 的工作环境
Hashline 实验	多个模型在同一类编码任务上获得提升	修改工具格式和编辑方式	说明工具接口和交互协议会改变模型的有效能力
Ghostty 的 AGENTS.md	规则逐条来自实际失败	每次错误都沉淀为一条可复用规则	说明项目指南可以成为组织记忆和持续改进机制

当 Agent 需要多步骤执行、调用外部工具或长期运行时，模型能力只是系统的一部分。系统是否能够在失败后获得明确反馈、在风险动作前受到限制、在中断后恢复状态，通常同样决定了最终效果。

Harness 的六层架构

报告将 Harness 拆分为六个层次。Guides 和 Sensors 构成前馈加反馈的控制回路；Agentic Loop 负责实际执行；Memory、Permissions 和 Observability 则构成运行时基础设施。

Guides：执行前的约束

Guides 是 Agent 开始任务前读取的规则和工作说明，可以表现为 AGENTS.md、CLAUDE.md、.cursorrules 或其他项目级配置。它们属于前馈控制，在错误发生之前影响 Agent 的行为。

一个有效的 Guide 不应只是“写高质量代码”“认真完成任务”这类无法验证的要求，而应包含项目名称、语言环境、构建命令、测试命令、Lint 命令、目录边界、禁止操作以及典型失败模式。例如，与其要求 Agent“完成后进行充分测试”，不如明确指定 npm test、触发时机、通过标准和失败后的处理方式。

Guide 的价值在于把一次性的人工纠正转化为后续任务可以复用的规则。如果一个 Agent 曾经误删配置文件，项目就可以增加一条明确的访问边界；如果 Agent 经常修改代码后忘记运行测试，就可以把测试命令和执行时机写入指南。这样，修复不再只存在于某一次对话中。

Sensors：执行后的反馈

Sensors 用于检查 Agent 的产出，是执行后的反馈控制。常见的计算型 Sensor 包括单元测试、类型检查、Lint、Schema 校验和安全扫描；需要语义判断时，也可以使用 LLM-as-judge 或 AI Code Review。

报告建议优先建设计算型 Sensor，因为它们通常更快、更便宜、可重复性更强。例如，接口返回值是否符合 JSON Schema、代码是否能够通过编译、SQL 是否命中只读白名单，都可以优先用确定性规则进行检查。对于“邮件语气是否合适”“研究摘要是否遗漏核心观点”这类难以完全形式化的问题，才更适合加入推理型 Sensor。

LLM-as-judge 并不是天然可靠的裁判。它具有成本、延迟和非确定性，判定结果还可能受到提示词和上下文组织方式的影响。因此，语义评审更适合作为补充信号，而不应在所有场景中替代测试、Schema 或权限检查。对于已经能够形式化的规则，最好逐步迁移为确定性检查。

Agentic Loop：有边界的执行循环

Agentic Loop 是 Harness 的执行核心。它不应被理解为一次模型调用，而应被理解为一个有边界的循环：先规划，再执行；执行后验证；失败时修复或重试；重试耗尽或遇到不可恢复问题时升级给人。

def agentic_loop(task, agent, sensors, budget):
    plan = agent.plan(task)

    for step in plan.steps:
        for attempt in range(budget.max_retries):
            result = agent.execute(step)
            verdict = verify(result, sensors)

            if verdict.passed:
                break

            if not verdict.retryable:
                return escalate(step, verdict)

            result = agent.fix(result, verdict)
        else:
            return escalate(step, "retry budget exhausted")

    return synthesize(plan.results)

循环必须有明确边界。报告给出的示例包括每个步骤最多重试 3 次、单任务最多运行 30 分钟、最多消耗 100K tokens、最多调用 50 次工具，并设置单任务成本上限。具体数值需要根据业务风险和任务类型调整，但“必须有边界”本身是生产化设计的基本要求。

Memory and State：让任务能够恢复

模型每次调用时只拥有当前上下文，不能天然记住上一个会话完成了什么。Harness 需要通过显式状态恢复连续性。报告将状态持久化分成多个层次：当前上下文只能维持当前交互，任务 Scratchpad 可以保存一次任务中的计划和中间结果，文件或对象存储可以跨会话保存产物，决策日志可以保留关键选择，知识图谱则适合需要长期关系查询的场景。

对于很多 Agent 工作流，最简单的持久化方式就是文件系统。plan.md 可以保存计划，todo.md 可以记录待办，progress.json 可以记录已完成步骤，decisions.jsonl 可以保存重要决策。它们不一定比向量数据库“更智能”，但通常更透明、更容易审计，也更适合存放任务状态和实际产物。

一个最小 checkpoint 至少应包括任务标识、当前状态、已完成步骤、产物路径和更新时间。Agent 在每个有意义的步骤后写入 checkpoint，在新会话开始时读取它。恢复测试也应成为系统验收的一部分：在多步骤任务中途关闭进程，重新启动后，Agent 应从最后一个已完成步骤继续，而不是重复执行或要求人重新解释全部背景。

Permissions and Budgets：模型之外的安全边界

权限不应依赖模型“自觉遵守”。只要一个工具对 Agent 可见，模型就可能尝试调用它；只要文件系统允许写入，错误的指令就可能造成修改。因此 Harness 必须成为主要的安全边界。

最小权限原则要求系统只授予完成任务所需的最小范围。例如，代码修复 Agent 可能需要读取 src/** 和 tests/**，写入 src/**，执行测试和 Lint，但不应默认拥有推送远程仓库、发布包、部署生产环境或发送外部邮件的权限。

权限设计还应考虑四个维度。Scope 决定可以访问哪些账户、工具、文件和操作；Rate 决定单位时间内允许多少次写入或外部调用；Reversibility 区分可回滚动作和不可逆动作；Visibility 决定谁会被通知以及需要保留哪些审计证据。删除数据、向外发送消息、生产部署和资金操作通常需要更严格的批准策略。

Observability：把执行过程变成可调试数据

没有结构化日志，Agent 的错误往往只能通过重放整段对话来定位。生产级 Harness 至少应记录任务开始和结束时间、工具调用及结果、Guide 版本、使用过的 Sensors、尝试次数、Token 和费用、生成的产物、审批和升级事件。

Observability 的作用不是单纯展示监控面板，而是回答具体问题：哪一次工具调用返回了异常数据？哪个 Sensor 错误地判定为通过？Agent 是否读到了过时的 Guide？某类任务的重试次数是否正在增加？某个模型版本上线后，未经人工修改的完成率是否下降？

从失败到基础设施：Ratchet Principle

Harness Engineering 中最有实践价值的思想之一，是把每次失败转化为永久性的系统改进。报告将这种方法称为 Ratchet Principle，即棘轮原则：系统可以持续向前积累改进，而不会每次都回到同样的错误起点。

一个完整的改进过程可以分为六步。首先用完全相同的输入复现问题，避免修复一个并不存在的假象。其次判断根因属于缺少 Guide、缺少 Sensor、权限过宽、状态丢失，还是日志盲区。然后选择能够覆盖整个错误类别的最强修复层。完成修复后，使用原始失败案例验证，再运行回归测试，确认修复没有破坏已有能力。

这一区分非常重要。一次对话中的提醒只能修复当前交互；一条 Guide 规则可以影响之后的任务；一个自动化 Sensor 可以阻止一类错误产出；一个环境权限边界则可以让某些危险动作在结构上无法执行。修复层级越靠近环境，通常越稳定，但建设成本也越高。

人工 Review 意见也可以按照同样方式升级。如果同一条意见第一次出现，可以先加入 Guide；第二次出现时，检查 Agent 是否真正读取和遵循了 Guide；第三次出现时，如果该意见已经能够形式化，就将它转化为阻断式 Sensor。这样，人的审查经验会逐渐沉淀为可执行约束。

生产指标不应只看模型调用次数

如果只统计模型调用次数、Token 数量或对话轮数，可能会把“更忙”误判成“更有效”。报告建议关注已经完成、经过验证且不需要人工返工的任务数量。

指标	含义	期望方向
Completion Rate	通过验证的任务数 ÷ 启动任务数	上升
Rework Rate	需要人工修改的任务比例	下降
Escalation Rate	每个任务触发人工介入的次数	下降，但不能通过隐瞒风险来降低
Recovery Time	从失败到安全状态所需时间	下降
Cost per Verified Result	获得一个经过验证结果的 Token、工具和人工成本	下降
Guide Growth	每周新增规则数量	在问题覆盖后逐渐下降

其中，Escalation Rate 不能被简单理解为越低越好。如果 Agent 遇到高风险动作时从不升级，可能意味着它正在错误地自行决策。合理的目标是减少不必要的升级，同时保留对不可逆动作和不确定结果的正确升级。

成本也应按任务和验证结果归因，而不是只看每天消耗了多少钱。一个每天花费 50 美元、完成 100 个已验证任务的系统，与每天花费 50 美元但只完成 2 个任务的系统，工程质量明显不同。只有把成本和完成结果关联起来，才能判断新增规则或 Sensor 是否真正降低了单位产出成本。

七日最小生产化路径

报告给出了一条循序渐进的七日路径。它的重点不是在第一天就搭建复杂的多 Agent 编排，而是每增加一层能力，就用明确的退出标准验证这一层是否真正生效。

第一天建立一个最小 Guide，写清构建、测试和 Lint 命令，并确认 Agent 能正确执行它们。第二天从真实失败中增加三条规则，检查 Agent 是否能够避免对应的反模式。第三天接入成本最低的计算型 Sensor，通常可以从已有测试套件开始。第四天把测试放入 Agentic Loop，为重试和升级设置上限。

第五天增加文件型状态 checkpoint，并在任务中途关闭和重启进程，确认 Agent 可以继续执行。第六天设置文件、工具、网络、写入次数和成本预算，验证越权动作会被阻断。第七天加入结构化日志和一个 Trip Wire，例如模拟成本异常并确认告警能够触发。

七天之后，系统仍然不是“建设完成”的终点。后续工作应继续基于真实任务观察错误，并逐层强化最薄弱的地方。报告建议在扩大使用范围前设置 Scale Gate，例如未经人工修正的完成率达到预定标准、没有任务超过成本预算、并且 Agent 至少正确升级过一次。正确升级是重要证据，因为它说明系统不仅会成功，也知道何时不能继续自行行动。

多 Agent 场景需要额外的边界设计

当多个 Agent 协作时，六层架构仍然适用于每个单独 Agent，但 Agent 之间还需要新的系统级约束。

首先是类型化 Handoff。Agent A 交给 Agent B 的内容，不应只是“已经完成，看起来没问题”，而应包含任务标识、产物位置、已经验证的内容、尚未解决的问题、假设和截止时间。接收方应能够打开产物并独立验证，而不是完全信任发送方的自然语言总结。

其次是共享状态，而不是共享全部对话。多个 Agent 共用一段长对话，容易把每个 Agent 的思考、错误和纠正都塞入同一个上下文，造成上下文污染。更稳定的做法是使用结构化 Ledger、图或数据库保存跨 Agent 状态，每个 Agent 只读取与当前任务相关的部分。

再次是独立验证者。生产产物不应由生成它的 Agent 独自判定质量。可以优先使用确定性检查；对无法形式化的重要任务，再使用独立的验证 Agent。验证 Agent 应报告问题，而不是在没有记录的情况下直接重写产物。路由器根据验证结果决定重试、转交其他角色或升级给人。

Harness 与 Prompt、Context 的关系

Prompt、Context 和 Harness 解决的是不同问题。Prompt 负责告诉模型任务目标、行为风格和输出要求；Context 负责把相关资料、工具描述、记忆和外部知识放进模型可见范围；Harness 负责限制模型的行动边界、检查结果、保存状态和追踪运行。

问题	Prompt 的典型做法	Context 的典型做法	Harness 的典型做法
事实错误	增加指令和示例	增加检索资料	加入引用、事实或结果校验
忘记历史工作	在提示中总结	使用记忆系统	写入文件 checkpoint
使用错误工具	在提示中提醒	限制工具说明	使用权限策略和工具边界
输出质量波动	增加 Few-shot	优化上下文组织	接入自动化测试和评估
无限循环	要求“简洁完成”	限制上下文长度	设置重试、时间和成本预算
生产事故	要求“谨慎执行”	过滤高风险上下文	设置权限、预算与升级机制

JOTO 企业落地观察

• Harness Engineering 的落地成败，高度依赖企业现有 DevOps 与安全治理体系的兼容性。Guides 和 Sensors 可快速引入，但 Permissions 层需与企业 IAM、CI/CD、网络策略等基础设施深度集成，否则无法形成真正的生产级安全边界。
• Ratchet Principle 要求每一次失败都能触发可复现、可归因、可验证的修复闭环。这对企业的 traceability（全链路追踪）和 replayability（可重放性）能力提出刚性要求，远超单次对话调试范畴，本质是将 AI 运行时纳入企业 SRE 实践体系。
• 多 Agent 协作中的类型化 Handoff 和独立验证者设计，暴露了传统微服务治理模式的局限：企业需为 Agent 间交互定义结构化契约（如产物 Schema、验证协议、升级 SLA），而非依赖自然语言摘要传递上下文。
• 七日路径并非功能清单，而是验证节奏——Day 1 确认 Agent 能执行基础命令，Day 7 验证系统能否自主识别并响应成本异常。这标志着企业从模型调用者，转变为智能体运行环境的构建者与监护者。