一个聊天机器人主要负责生成回答，而一个 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 Engineering 到 Harness Engineering
2023 到 2024 年，工程重点主要是 Prompt Engineering，即通过调整措辞、示例和指令来影响模型在单轮交互中的输出。2025 年以后，Context Engineering 逐渐成为重要方向，工程师开始关注模型在执行任务时看到了哪些资料、工具、记忆和外部知识。进入 2026 年，报告进一步把关注点扩展到完整运行环境，也就是 Harness Engineering。
这三个阶段并不是相互替代的关系。生产级 Agent 仍然需要清晰的 Prompt 和高质量 Context，但这些内容必须被放入一个能够验证和约束执行过程的环境中。Prompt 影响模型的思考方式，Context 影响模型可使用的信息，Harness 影响模型最终能够做什么，以及系统是否能够承受失败。
公开案例
当 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 数量或对话轮数，可能会把“更忙”误判成“更有效”。报告建议关注已经完成、经过验证且不需要人工返工的任务数量。
其中，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 负责限制模型的行动边界、检查结果、保存状态和追踪运行。
什么时候不需要建设完整 Harness
Harness 也不是所有对话都值得投入的基础设施。一次性问题、低风险的头脑风暴、个人笔记和探索性分析，通常不需要完整的指南、传感器、checkpoint 和审批链路。若任务没有重复发生、结果不可验证、失败没有实际后果，也没有跨会话恢复需求，那么对话本身可能已经足够作为轻量 Harness。
当 Agent 按日运行、会修改代码、需要发送外部消息、面向客户、需要引用资料、运行在 CI/CD 中，或者失败会造成数据和声誉损失时，建设 Harness 的收益会明显增加。
第一个误区是过度工程化。五百条规则、多个 LLM-as-judge、复杂审批链和多级 Agent Review，可能让系统检查自身的时间超过真正工作的时间。Harness 应该是让 Agent 可靠工作的最小基础设施，而不是一个把所有事情都交给审批的瓶颈。
第二个误区是规则只增不减。规则积累后可能互相矛盾，也可能与实际工具行为脱节。应定期合并重复规则，把能够被 Sensor 验证的规则移出 Guide，并清理已经失效的约束。
第三个误区是 Sensor 只检查形式而不检查问题本身。一个始终通过的测试套件不一定说明 Agent 工作正确，也可能说明测试过于容易。测试集应包含边界输入、对抗样例、格式正确但数据错误的输出，以及能够暴露逻辑问题的案例。
第四个误区是只增加上下文，不解决状态管理。更长的对话可能让 Agent 暂时“想起”更多信息，但不能替代结构化 checkpoint，也不能保证跨会话恢复。状态应以可读、可验证和可清理的方式持久化。
第五个误区是把错误的目标包装成可靠系统。若验收标准本身不正确，Harness 可能只是更稳定地生成错误结果。指南、Sensor 和指标都应与业务目标保持一致，并定期审查评测标准是否仍然有效。
把 Agent 当成一个需要运行环境的系统
Harness Engineering 的核心并不是给 Agent 增加更多模型调用，而是把 Agent 放入一个能够持续反馈、限制风险、保存状态和记录证据的环境中。模型负责推理，Guide 负责预防已知错误，Sensor 负责发现新错误，Agentic Loop 负责有边界地执行，Memory 负责跨步骤和跨会话恢复，Permissions 负责控制风险，Observability 负责定位问题并推动改进。
对于准备把 Agent 推向生产的团队，一个可执行的起点可以很小：先建立一个项目级 Guide，接入一个确定性 Sensor，设置一个权限边界，记录一个核心指标，再配置一个异常 Trip Wire。之后，每次真实失败都判断它应该沉淀为规则、测试、权限、状态或日志改进。
最终要达到的状态不是“Agent 永远不会犯错”，而是每个重要结果都能够回答以下问题：什么规则影响了它？什么 Sensor 验证了它？哪个预算约束了它？哪个 checkpoint 保存了它？哪条日志记录了它？如果这些问题都无法回答，继续增加模型调用往往只会增加系统的不透明性；如果这些问题能够被稳定回答，Harness 才真正成为一种可组合、可审计、可改进的工程机制。
