0 前言

Harness Engineering 是一种更生动、更直观的方式来系统地总结和命名这些现有的 AI 实践。

1 Harness Engineering

公式：AI 代理 = SOTA 模型（野马）+ 驾驭系统（控制系统）= 一位精英表演者。

一个 AI 代理是一匹潜力无限的"野马"，而 Harness Engineering 是驯服它的完整系统。你并不是在改变马的 DNA（模型本身），而是在设计让它为你工作的专业装备和训练协议。

Harness 本质上是除 LLM 之外所有能够使代理实际交付结果的基础设施。它不关乎“更好的提示”或“更强大的模型”。它关乎优化模型运行的环境和机制。它是一种工程哲学和框架，旨在将原始的 AI 智能转化为可靠、可控和可扩展的生产力。

让我们明确： Harness Engineering 并不是什么能引发你 FOMO 的新玩意儿。它更像是一个用于 AI 工程的驾驭框架，旨在解决一个核心问题。

它解决的核心问题很简单：既然 AI 已经加入了你的工作流程，我们实际上该如何管理这个“超级实习生”？

2 为什么需要？

随着 AI 从简单的“应答机”演变为能够规划和执行复杂任务的自主代理，工程师的角色正在经历一个根本性的范式转变。

Harness Engineering应运而生，专门应对这种演变带来的新挑战。

2.1 构建更可靠的 Agent 系统

为了将 Agent 从玩具阶段推向可投入生产的工程领域，它们必须基于四个核心目标：

2.1.1 可靠性

系统在面对预期或非预期的输入、环境变化和内部故障时，提供稳定、持续的服务并完成指定任务的能力。

要求

• 故障恢复：在任务中断后自动从检查点恢复的能力
• 幂等性操作：确保关键写操作可以安全地重试，而不会损坏系统状态
• 行为一致性：确保在相同的一组输入下行为保持可预测

2.1.2 效率

在满足功能性和可靠性需求的同时，有效利用计算、存储和网络资源。这直接影响服务成本和可扩展性。

关键要求

• 资源控制：对 token 消耗、API 调用和计算时间进行精确的预算管理
• 低延迟响应：在交互场景中快速提供有意义的反馈
• 高吞吐量：在批处理场景中，每单位时间内处理更多任务的能力

2.1.3 安全

保护系统及其数据免受未经授权的访问、使用或破坏。对于自主代理，安全是不可协商的红线。

关键要求

• 最小权限：仅授予完成特定子任务所需的最低权限
• 沙盒执行：在严格隔离的沙盒环境中执行所有不受信任的代码或指令
• I/O 过滤：防止提示注入、敏感数据泄露和有害内容的生成

2.1.4 可追溯性

为开发人员和操作人员提供足够的数据（日志、指标和跟踪信息），以便他们能够理解代理的内部状态、决策过程和行为历史。

关键要求

• 端到端追踪：为每一步从最初请求到最终结果维护清晰、可追溯的调用链
• 可解释决策：确保每个关键决策都有明确的归属与可审计记录
• 可审计状态：确保在系统历史上的任何时刻，都可以查询并审计系统的完整状态

2.2 代理优先时代的工程必需性

2.2.1 工程复杂度正达到新的高度

随着 AI 能力不断扩展，我们对“能够构建什么”的期待也在同步提升。我们早已不再停留在“氛围式编程”（Vibe Coding——快速做出诸如贪吃蛇或俄罗斯方块克隆之类的演示）阶段，而是进入了 严肃的、面向生产的工程 领域。

2.2.2 从执行者到架构师

随着 AI 接管编写特定代码行的重体力工作，人类工程师的核心价值被提升到系统设计层面。我们不再是一行行砌砖的劳工，而是绘制蓝图、定义规则并最终签发输出的建筑师：我们称之为 Spec Coding 的概念。

这种实践是一个有力的概念验证：当 AI 成为生产力的主要引擎时，传统的工程管理模型不再适用。通过提示来指导 AI 是一种"软约束"，这远远不足以保证质量、可靠性或可维护性。

我们需要一套"硬约束"系统，一个强大的工程框架来锚定代理性能。这正是 Harness Engineering 发挥作用的地方。

Harness Engineering 的核心哲学

当模型遇到瓶颈时，我们通过实施工程化机制来确保同一类故障永远不再发生。

它是一个动态系统。随着模型的持续迭代，许多基础能力最终将被模型自身内化，从而允许某些 Harness 实践被淘汰。同时，随着新应用场景的出现，它们不可避免地将催生新的 Harness 创新。

那么，让我们深入探讨 Harness 工程实际上是什么样子的。

3 解构 Harness 工程

在当前的基于 Transformer 和自回归 LLM 架构的底层，原始输出本质上是随机且无序。

Harness Engineering是对原始计算施加确定性约束，以实现复杂的工程工作流。

要理解“是什么”，我们必须看代理实际是如何运作的。一个可投入生产的代理在一个连续的四阶段循环中运行：感知、规划、行动和反馈/反思（PPAF，Perception, Planning, Action, and Feedback/Reflection）。

我们将代理堆栈分解为四个核心维度，每个维度都与 PPAF 循环直接对应。将这些视为“缰绳”——即指导、约束和释放模型真正潜力的必要结构。

为了梳理不同智能体的能力边界与工程障碍，我们基于 认知循环（Cognitive Loop） 和 上下文效率（Context Efficiency） 使用一个二维矩阵进行划分。

横轴：AI 认知循环（AI Cognitive Loop）

• React（被动响应）：行为由单一外部触发器驱动。代理执行预定义的确定性任务，但缺乏自主规划或反思。
• 主动计划与反思：代理追求长期目标，自主管理多步规划、执行和基于结果的动态调整。

垂直轴：上下文效率

• 低效（手动/点供）：大部分上下文由人工提供或通过有限、低效的接口获取
• 高效（沙盒化/自动注入）：代理在高度集成的环境中运行，上下文通过文件系统、API 网关或状态引擎等系统级接口自动捕获和注入

这份矩阵揭示了 Harness Engineering 的核心价值：你的 Harness 成熟度会直接决定一个智能体能否从低效率、被动的下方象限跃迁到高效率、主动的上方层级。

4 Harness 系统的架构

在已经建立起框架之后，现在是从概念走向实践的时候。我们来逐层拆解如何构建一个具有韧性的 Harness 系统层。

4.1 高层抽象：把 Harness 视作受管理的 REPL 容器

从架构层面来看，Harness 本质上是一个 REPL（Read-Eval-Print Loop 读-求值-打印）容器，并配备边界控制、工具路由以及确定性的反馈机制。

可将其视为一个确定性外壳，包裹着非确定性的 LLM “大脑”。它的任务是管理从感知到行动再到反思的整个生命周期，有效地将 LLM 推理嵌入到可预测的软件工程世界中。

REPL Harness 的核心逻辑

Read读取：Harness 使用一个上下文管理器将外部世界（例如用户输入或 API 状态）和内部内存转换为 LLM 实际可以消化的高度结构化提示。这就是我们如何将工程严谨性带到“感知”阶段。

Eval评估：当 LLM 生成一个计划（例如，一个函数调用）时，调用拦截器会捕获该意图并将其路由到适当的工具执行器。每次执行都严格监控超时、资源配额和错误处理。

Print打印：该工具的输出（无论是成功数据还是异常）都被反馈组装器捕获。然后将其重新打包为结构化的“观察”并重新注入到上下文中，为 LLM 提供其下一轮反思和规划的原始材料。

Loop: “Read-Eval-Print” 循环会持续不断地重复，直到代理达到其目标或触发终止条件。这个循环是驱动 PPAF 进程的基本引擎。

4.2 底层转换机制：连接无限状态和有限标记

代理的涌现智能依赖于其消化大量状态信息的能力。然而，底层的 Transformer 架构本质上是在一个有限的、线性的标记序列上运行的。

因此，Harness 的核心挑战在于建立一种高效、可靠的、双向映射关系，将外部世界的“无限”状态与 LLM 的“有限”token 上下文联系起来。

4.2.1 上下文管理：从“无限状态”到“有限 Token”

代理的上下文是其感知的基准，涵盖了从任务目标、交互历史到工具定义和实时状态等所有内容。将这股庞大的数据流提炼成一个有限的 token 窗口，是规划质量的最根本瓶颈。

💬 Engineering Decisions: Reduction Rules and Injection Boundaries
💬 工程决策：缩减规则和注入边界

At its core, context management is a set of Reduction Rules.
其核心，上下文管理是一套缩减规则。

The Harness must define explicit rules to determine which information to prioritize and which to prune when the token budget is tight. Furthermore, the Injection Boundary is vital. It dictates exactly where external data (such as RAG results) is inserted within the prompt to maximize performance and avoid the “Lost in the Middle” phenomenon.
Harness 必须定义明确的规则，以确定在代币预算紧张时优先哪些信息以及修剪哪些信息。此外，注入边界至关重要。它规定了外部数据（如 RAG 结果）在提示符中插入的确切位置，以最大化性能并避免“中间丢失”现象。

4.2.2 函数调用：从“文本预测”到“物理执行”

函数调用（FC）是 LLM 规划与现实世界行动之间的桥梁。虽然看似简单，但它涉及一个严格且通常脆弱的生命周期循环：

• 模式序列化：Harness 将可用的工具及其参数（JSON Schema）序列化成特定的文本格式，并将其注入到提示中。这是 LLM 理解其“能力边界”的唯一方式。
• Trigger Generation: Through pattern matching across its vast parameter space, the LLM generates text following a specific syntax (including the tool name and argument values) when it determines a tool is needed for the plan.
• Deterministic Deserialization: The Harness intercepts this text and attempts to deserialize it into a structured request. This is the most brittle stage, as LLM output may violate syntax rules, such as malformed JSON or type mismatches.
• 观察注入：Harness 执行调用并将结果（成功或失败）包装成一个“观察”文本块，然后将其重新注入提示中，以形成闭环。

a) Failure Surfaces and Fallback Paths

鉴于 LLM 输出的非确定性，函数调用的每一步都是潜在的失败点。一个有弹性的 Harness 必须实现强大的回退路径：

反序列化失败：

• Retry: Provide the LLM with the specific error (e.g., “Invalid JSON format”) to trigger a re-generation.
  重试：向 LLM 提供具体的错误（例如，“无效的 JSON 格式”）以触发重新生成。
• Fallback to Text: Request natural language instructions for a traditional parser instead.
  回退到文本：请求传统解析器的自然语言指令。

执行失败：

• Interactive Clarification: Request missing parameters directly from the user.
  交互式澄清：直接从用户请求缺失的参数。
• Reflection and Re-planning: Inject detailed error logs into the context to guide the agent toward an alternative path in the next round.
  反思和重新规划：将详细的错误日志注入上下文，引导代理在下一轮中选择替代路径。

b) Core Architectural Decision: The State Separation Principle

• You must treat the LLM strictly as a stateless compute unit (a “CPU”). All state requiring cross-turn consistency such as user sessions or task progress must be offloaded to an external Context State Manager or persistence engine (Memory/Disk) controlled by the Harness.
• The Anti-Pattern: Attempting to force the LLM to maintain complex state via prompt engineering leads to chaotic, unpredictable, and untraceable system behavior.

4.2.3 Core Constraints and Design Principles

When building a Harness, we must confront three fundamental constraints and address them through six core design principles.

The Three Core Constraints

六个设计原则

1. Design for Failure: Treat exceptions and failures as the norm, not the outlier. Every component must support fault tolerance, retries, and graceful degradation.
   设计为失败：将异常和失败视为常态，而非例外。每个组件都必须支持容错、重试和优雅降级。
2. Contract-First: Define all interactions through explicit, machine-readable contracts (Schemas, APIs, Events). This is the foundation for modularity and system evolution.
   协议优先：通过显式、机器可读的协议（模式、API、事件）定义所有交互。这是模块化和系统演进的基石。
3. Secure by Default: Security isn’t a bolt-on. It should be the starting point. We follow the principles of least privilege, zero trust, and defense-in-depth.
   默认安全：安全不是附加功能。它应该是起点。我们遵循最小权限、零信任和纵深防御的原则。
4. Separation of Concerns (Decision vs. Execution): Decouple “deciding what to do” (planning) from “how to do it” (execution) both logically and physically to increase system flexibility.
   关注点分离（决策与执行）：将“决定做什么”（规划）与“如何做”（执行）在逻辑上和物理上分离，以提高系统灵活性。
5. Everything is Measurable: Every behavior, decision, and resource used must be quantifiable. Without measurement, there is no path to optimization.
   所有事物都是可衡量的：每个行为、决策和使用资源都必须可量化。没有测量，就没有优化的路径。
6. Data-Driven Evolution: Treat every agent run as a learning opportunity. Building a closed loop of data collection, labeling, and feedback is the only way to achieve long-term intelligent growth.
   数据驱动进化：将每个代理运行视为一个学习机会。建立数据收集、标记和反馈的闭环是实现长期智能增长的唯一方法。

4.2.4 关键工程里程碑

为了驱动 REPL 循环并落实这些设计原则，一个 Harness 需要在整个架构中部署几个关键组件或“工程里程碑”。

Harness Engineering 不过是我们协调 LLM 的总称。无论是 SDK、代理还是自定义插件，其使命始终如一：阻止模型重复犯同样的错误。

这些“Harness”并非静态。随着模型的演进，今天的外部护栏最终将直接集成到模型本身中。

5 实施 Harness 工程

概念框架是一个很好的起点，但对于构建平台和基础设施的工程师来说，Harness 必须被视为一个有生命、可操作的系统。要真正理解它的工作原理，我们需要通过四个关键视角来审视它：架构分层、核心机制、运营治理和数据驱动进化。

5.1 架构概述：控制平面和数据平面

一个生产级的 Harness 通常解耦为控制平面和数据平面：

• 控制平面（“什么”）：管理高级逻辑，包括任务调度、资源配额、行为规划和策略执行。
• 数据平面（“如何”）：处理繁重的工作，如实际代理运行时实例、状态和内存存储以及沙盒执行环境。

我们进一步将其抽象为四个功能层：

在实践中，可以把 Harness 理解为一种 **“智能粘合剂（intelligent glue）。”**它位于你模型的 API 网关和各类服务之间，借助工程化的严谨性，把原本割裂的基础设施“缝合”成一个统一、连贯的系统。

5.2 核心机制：循环、记忆与 Token 管道

5.2.1 Agent 核心循环

我们将智能体行为抽象为一个持续的 Observe → Think → Act（观察 → 思考 → 行动） 循环：

• Observe（观察）：感知当前世界状态，包括用户输入、工具输出、交互历史以及任务进展。
• Think（思考）：基于这些感知来更新目标、拆解任务，并决定下一步行动。
• Act（行动）：执行操作——既可以是内部操作（更新记忆），也可以是外部操作（调用工具或回复），其结果会反馈到下一次观察中。

💬 工程备注：这不是一个简单的 while (true) 循环

在生产环境中，这个循环必须与工作流引擎或状态机框架集成。它需要支持暂停/恢复（pause/resume）、幂等重试（idempotent retries）以及并发事件处理（concurrent event handling），以解决长时间任务中的“上下文焦虑（context anxiety）”。

5.2.2 分层记忆与 Token 管道

将最大信号压缩到有限的内容窗口中，大多数代理依赖于外部内存。

此外，Harness 运行一个 Token 转换管道，在每次调用之前将多源信息提炼为受控的提示：

1. 收集：聚合用户请求、短期记忆和长期知识检索。
2. 排序：根据时效性和语义相关性对信息进行评分。
3. 压缩：对高容量、低密度的内容进行摘要或结构化优化。
4. 预算分配：将令牌限制分配到不同的信息类别。
5. 组装：使用结构化模板（例如显式的[user_request]或[tool_output]块）将最终提示语组合在一起。

💬 核心观点：将注意力管理任务委托给工程技术人员。与其寄希望于模型“自行判断”应该关注什么，不如使用 Token 转换管道来主动构建上下文。将那宝贵的时间窗口留给真正重要的信息。

5.2.3 规划模型与执行策略

在规划层，我们通常根据任务的复杂性对模式进行分类：

💬 建议：

• 默认采用“计划-执行”模式，仅在需要时才添加重新规划或多智能体编排
• 对于大多数企业场景，一个结构化的计划配合“异常触发的重新规划”已经足够稳健

5.2.4 运行时与治理：沙箱、安全与成本

沙箱执行框架

为了让代理能够“完成任务”而不破坏您的系统，您必须提供一个安全、隔离的运行时环境。

• 级别 1：进程级隔离：使用 chroot、Linux 命名空间或 seccomp-bpf。它速度快，但共享内核；最适合受信任的内部工具。
• 级别 2：容器隔离：Docker 或 containerd。这是大多数工具执行成熟的、行业标准的选择
• 第 3 级：MicroVM（微型虚拟机）：Firecracker。提供独立的虚拟内核，使其非常适合多租户环境，或用于执行不可信代码。
• 第 4 级：完整虚拟机（Full VMs）：KVM/QEMU。以最高安全性为目标、但成本最高；仅保留给最敏感的任务。

策略（The Strategy）：默认使用第 2 级（容器），并搭配加固的内核与只读根文件系统。对不可信代码或高敏感数据，引入第 3 级（MicroVMs）作为增强型沙箱。

资源管理与韧性（Resource Management and Resilience）

控制成本并确保稳定性需要几个关键的工程控制措施：

• 预算和配额：在平台、租户或单个任务中为令牌、API 调用和 CPU 时间设置限制。
• 超时控制：对所有网络请求和工具执行实施严格的超时，以防止下游服务挂起而拖累整个 Agent。
• 重试策略：对暂时性、可恢复的错误使用带退避的重试，但对永久性错误快速失败。
• 断路器：如果依赖项反复失败，则暂时跳闸电路，以防止级联故障。
• 优雅降级：如果关键功能离线，则自动切换到“弱但安全”模式（例如，从“可执行代码”切换到“只读建议”）。

安全和合规：策略网关

在沙盒之外，您需要在规划器与执行层之间设置一个策略网关来验证每个操作：

• 权限：RBAC/ABAC 检查以验证代理是否有权访问特定资源。
• 数据过滤：对输入参数和返回值进行 PII 和机密检测。
• 注入防御：在执行层之前识别恶意提示模式或命令拼接。
• 审计日志：记录“谁在何时做了什么以及结果”，用于事后分析和合规审计。

指标与演进：通过数据成长

最后，你需要一个强大的评估套件来确保你的智能体系统保持在正确的轨道上：

• 任务有效性：成功率、指令遵循率和工具使用效能。
• 服务质量（QoS）：端到端延迟、首次响应时间和整体错误率。
• 资源效率：平均令牌消耗和平均工具调用。
• 安全和合规：策略拒绝率和安全事件数量。

这些指标不仅仅是虚荣指标或仪表盘填充物；它们是推动您的 Harness 进化的反馈循环。当成功率达到瓶颈时，这是一个重新审视您的规划器或上下文策略的信号。如果错误率或成本激增，您可能需要排查您的沙盒、资源配额或断路器逻辑。

6 总结

Harness Engineering 并非什么值得供奉的“银弹”。它是一种在真实世界中形成并为之构建的工程理念。

尽管行业专注于生成式 AI 对开发者进行“颠覆”和“取代”，但这一方法论提供了一个坚实的基础提醒：工程师的角色并未消失。它正在演变。我们正从代码的创造者转变为创作过程的守护者。

构建一个可靠的 Harness 最终是在混沌与秩序之间寻求平衡。我们不再期望 AI 完美，正如我们不再期望人类无懈可击。真正的工程智慧在于构建能够从失败中学习并在不确定性中展现韧性的系统。

这些“缰绳”的最终目标从未是为了限制，而是为了实现更安全、更完整的潜力释放。或许，在不久的将来，模型将完全超越这些基础约束。