1. 从一次线上事故说起：为什么 Harness 工程值得单独拎出来讲

去年冬天，我们团队负责的一个自动化代码审查 Agent 在灰度环境跑得好好的，一上生产就翻车了。表现很诡异：前 20 分钟一切正常，第 21 分钟开始，Agent 开始重复执行同一个文件读取操作，像卡带一样循环了 47 次，最后把上下文窗口撑爆，整个任务链断裂。事后复盘，问题不在模型本身，也不在提示词，而在于我们压根没有为 Agent 设计一套完整的“运行骨架”——也就是今天要聊的Harness 工程。

这个词最近在 Agent 开发圈子里被反复提及，但很多人对它的理解还停留在“不就是个执行器吗”。实际上，Harness 工程涵盖的范围远比一个 while 循环大得多：它要管 Agent 怎么循环、上下文怎么组织、沙箱怎么隔离、结果怎么验证、长时运行怎么保持稳定。你可以把模型想象成一台性能强悍但脾气不定的发动机，Harness 就是那套底盘、变速箱、冷却系统和仪表盘——没有它，发动机再猛也上不了路。

这篇文章适合三类人看：正在做 Agent 应用但总被稳定性问题折磨的开发者、想从“调提示词”进阶到“做系统工程”的 AI 工程师、以及需要评估 Agent 方案可行性的技术负责人。我会从整体设计思路讲到每个核心模块的实操细节，把踩过的坑和验证过的方案都摊开来说。全文基于我们团队在多个模拟项目中的实践总结，涉及具体参数和代码的地方都会给出可复现的参考。

2. Harness 工程的整体设计与核心思路拆解

2.1 什么是 Harness，它和普通 Agent 框架的区别在哪

先把这个概念钉死。Harness 在英文里是“马具、挽具”的意思，套在马身上用来控制方向、传递力量。放到 Agent 语境里，它指的是包裹在模型外层的一整套运行时基础设施，负责把模型的单次推理能力转化为可控制、可观测、可恢复的持续任务执行能力。

很多人会把它和 LangChain、AutoGPT 这类框架混为一谈。区别在于：框架提供的是“能力组件”，比如工具调用、记忆存储、链式编排；而 Harness 关注的是“运行契约”，也就是 Agent 在真实环境中跑起来之后，怎么保证它不跑偏、不卡死、不失控。举个具体例子，框架能让你轻松定义一个“读取文件”的工具，但 Harness 要解决的是：这个工具被连续调用 50 次时怎么熔断？读取失败时重试几次？重试间隔怎么设计？这些才是生产环境真正要命的问题。

我们内部有个粗线条的划分标准：如果一个 Agent 任务在 5 分钟内、10 步以内能完成，框架层面的能力基本够用；一旦任务时长超过 30 分钟、步骤超过 50 步、涉及外部环境交互，就必须认真设计 Harness。这个阈值不是拍脑袋来的，而是根据上下文窗口消耗速率和错误累积概率算出来的——后面会详细展开。

2.2 为什么“循环”只是冰山一角：五个核心模块的协作关系

一个完整的 Harness 至少包含五个模块，它们之间的关系不是简单的串联，而是相互制约的闭环。

Agent 循环是心脏，负责驱动“推理-行动-观察”这个基本节拍。但循环本身不产生智能，它只是节奏控制器。上下文管理是记忆系统，决定每一轮循环里模型能看到什么、看不到什么。沙箱环境是手脚，提供文件操作、命令执行、网络请求等实际能力，同时承担隔离和安全职责。验证机制是免疫系统，在每一步行动后检查结果是否符合预期，决定继续、重试还是中止。长时运行保障是耐力系统，处理超时、断连、状态持久化和恢复。

这五个模块的协作有个关键原则：循环的每一步都必须经过验证才能进入下一步，验证的结果必须反馈到上下文管理中，上下文的膨胀必须触发压缩或截断策略，而所有状态变更必须能被长时运行模块持久化。缺了任何一环，Agent 在长任务中都会出问题。我们早期做过一个实验，只做循环和沙箱，不做验证和上下文压缩，结果 Agent 在第 38 步开始出现“幻觉累积”——前面读错了一个配置项，后面所有推理都建立在错误前提上，最终输出了一份完全不可用的报告。

2.3 方案选型：为什么我们最终放弃了“全自主”路线

市面上关于 Agent 的设计哲学大致分两派：一派追求“全自主”，给模型最大的自由度，让它自己规划、自己纠错；另一派主张“强约束”，把任务拆成固定流程，模型只在关键节点做决策。我们两种都试过，最后选了中间路线：宏观流程强约束，微观步骤给自主。

全自主路线的问题在于错误传播不可控。模型在长任务中一旦进入错误状态，很难靠自己跳出来，因为它看到的上下文已经被自己的错误输出污染了。我们实测过一个全自主的代码重构 Agent，在 200 步左右的任务中，有 60% 的概率会在某个点开始“自我说服”，把明显错误的方案论证成正确的。强约束路线则走向另一个极端：流程太死，遇到预期外的情况就卡住，需要人工介入的频率太高，失去了自动化的意义。

最终方案是：用状态机定义任务的宏观阶段（比如“探索-规划-执行-验证-收尾”），每个阶段内部允许模型自由决策，但阶段之间的跃迁必须满足预设条件。这样既保留了灵活性，又给错误传播设了防火墙。这个设计决策直接影响了后面所有模块的实现方式。

3. 核心模块深度解析与实操要点

3.1 Agent 循环：不只是 while True，而是带状态的心跳

Agent 循环最朴素的写法就是一个 while 循环，不断调用模型、执行工具、把结果塞回上下文。但生产级的循环需要处理至少四种状态：正常推进、等待外部输入、重试中、终止。每种状态对应不同的循环行为。

我们用的循环骨架大致是这样的逻辑：每轮开始先检查终止条件（步数上限、时间上限、任务完成标志），然后从上下文管理器获取当前轮次的输入，调用模型推理，解析输出中的行动指令，交给沙箱执行，执行结果经过验证器检查后写回上下文，最后更新循环状态。这个顺序不能乱，尤其是验证必须在写回之前，否则错误结果会污染上下文。

这里有个容易忽略的细节：循环的步数上限不能设成固定值。我们最初设了 100 步硬上限，结果发现有些复杂任务确实需要 150 步以上，而有些简单任务 20 步就该结束却因为模型“恋战”拖到 80 步。后来改成动态上限：根据任务类型给一个基准值，再根据当前已消耗的上下文比例动态调整。具体公式是max_steps = base_steps * (1 + context_used_ratio)，其中context_used_ratio是已用上下文占窗口的比例。这样上下文用得越多，允许的步数反而越多，因为说明任务确实复杂。

注意：循环中一定要有“无进展检测”。如果连续 N 轮的行动和观察结果高度相似（可以用简单的文本相似度判断），说明 Agent 卡住了，必须强制中断或切换策略。我们设的 N 是 3，实测能拦住大部分死循环。

3.2 上下文管理：在有限窗口里做无限任务的取舍艺术

上下文管理是 Harness 工程里最考验工程判断力的部分。模型的上下文窗口就那么大，但长任务产生的信息量可能是窗口的几十倍。怎么取舍，直接决定 Agent 的“记忆力”和“判断力”。

我们的策略是分层管理：系统提示层永远保留，包含角色定义、核心规则、当前任务目标；近期交互层保留最近 K 轮完整的推理-行动-观察记录，K 根据任务类型在 5 到 15 之间调整；摘要层存放更早历史的压缩摘要，由模型自己生成，但生成时机和压缩比例由 Harness 控制；外部存储层存放完整的原始记录，需要时通过检索工具按需拉取。

压缩时机的选择很关键。我们试过两种方案：一种是固定轮次压缩，比如每 10 轮压缩一次；另一种是阈值触发，当上下文使用率达到 70% 时启动压缩。实测下来阈值触发更合理，因为不同任务的上下文消耗速率差异很大。压缩比例也有讲究：压缩太狠会丢失关键细节，压缩太松起不到释放空间的作用。我们的经验值是每次压缩把目标区域压缩到原长度的 20% 到 30%，同时保留所有“决策点”信息——也就是 Agent 做出关键选择的那些轮次，这些轮次的记录不参与压缩。

还有个实操技巧：给上下文打标签。每一条写入上下文的信息都标注类型（事实、推理、行动结果、错误信息）和重要性等级。压缩时优先丢弃低重要性的推理过程，保留事实和错误信息。这个标签机制让压缩后的上下文质量明显提升，Agent 在压缩后“失忆”的情况减少了大概七成。

3.3 沙箱环境：隔离不是目的，可控才是

沙箱的核心诉求有两个：安全隔离和能力供给。安全隔离好理解，不能让 Agent 随便操作宿主机。能力供给则经常被低估——沙箱里提供什么工具、工具的粒度怎么设计，直接影响 Agent 的执行效率和错误率。

我们最初给沙箱配了一套“万能工具”：一个能执行任意 shell 命令的接口。结果 Agent 经常写出又长又复杂的命令，出错后很难定位是命令本身的问题还是环境的问题。后来改成“细粒度工具集”：读文件、写文件、列目录、搜索内容、执行预定义脚本，每个工具职责单一，参数明确。这样虽然工具数量多了，但每个工具的行为可预测，验证器也容易判断执行结果是否正常。

沙箱的生命周期管理也有讲究。我们采用“任务级沙箱”：每个任务启动时创建一个干净的沙箱实例，任务结束后销毁。这样避免了任务间的状态污染。但创建沙箱有开销，对于高频短任务不划算。所以又加了一层“沙箱池”：预热一批沙箱实例，任务来了直接分配，用完重置后放回池子。重置操作包括清空工作目录、恢复环境变量、重置网络访问策略。实测下来，沙箱池能把任务启动延迟从 3 秒降到 200 毫秒左右。

提示：沙箱内的文件操作一定要做路径规范化。我们遇到过 Agent 用相对路径../../etc/passwd试图越界访问的情况，虽然沙箱本身有隔离，但路径检查能提前拦截这类异常行为，减少无效尝试。

3.4 验证机制：让 Agent 学会“停下来想一想”

验证机制是 Harness 里最容易被做薄的部分。很多实现只在任务结束时验证最终结果，中间步骤完全不检查。这在短任务里问题不大，长任务里就是灾难——错误像滚雪球一样越滚越大。

我们的验证分三层：格式验证检查模型输出是否符合预期结构（比如 JSON 能不能解析、必填字段在不在）；语义验证检查行动结果是否符合任务逻辑（比如读文件操作返回了内容而不是错误码）；进度验证检查当前状态是否在向目标靠近（比如距离完成还有多少步、关键里程碑是否达成）。

格式验证和语义验证是确定性的，用规则就能实现。进度验证则需要一些启发式判断。我们的做法是让模型在每轮输出时附带一个“进度自评”，用 0 到 100 表示任务完成度。Harness 记录这个自评值的变化曲线，如果连续多轮自评值不增反降，或者增长极其缓慢，就触发预警。这个信号不一定准确，但作为辅助判断很有价值。

验证失败时的处理策略也要分层。格式错误直接重试，把错误信息反馈给模型让它修正。语义错误先重试一次，再失败就切换工具或换一种实现方式。进度停滞则触发“策略重规划”：把当前状态和已完成的部分总结一下，让模型重新规划剩余步骤。这套分层处理机制把我们的任务成功率从 62% 提升到了 89%。

3.5 长时运行保障：断点续跑与状态持久化

长时运行的核心问题是：任务跑到一半，进程挂了、机器重启了、网络断了，怎么办？答案只有一个：状态持久化 + 断点续跑。

状态持久化不是简单地把上下文存下来就完事。需要持久化的包括：当前循环轮次、上下文快照、沙箱工作目录状态、已完成步骤的清单、验证器的历史记录。这些状态要能原子性地写入存储，并且在恢复时能完整重建运行环境。

我们用的是“检查点”机制：每完成一个宏观阶段（比如“探索”阶段结束进入“规划”阶段），就写一个检查点。检查点包含重建运行所需的最小状态集。恢复时从最近的检查点加载，重放检查点之后的步骤日志来恢复到中断点。这里有个细节：重放不能真的重新执行工具调用，而是从日志中读取当时的执行结果。所以日志必须记录每一步的完整输入输出。

断点续跑还有个隐蔽的坑：外部副作用。如果 Agent 在中断前已经修改了外部系统（比如发了一封邮件、提交了一个表单），恢复后不能重复执行这些操作。我们的解法是给每个有副作用的操作分配一个幂等键，执行前先检查这个键是否已经执行过。这个机制在模拟项目中救过我们好几次，避免了重复提交导致的脏数据。

4. 完整实操流程：从零搭建一个可运行的 Harness

4.1 环境准备与基础依赖

先列一下我们用的技术栈，都是常见组件，不涉及任何特殊工具。运行时用 Python 3.11，异步框架用 asyncio，状态存储用 SQLite（轻量场景）或 PostgreSQL（生产场景），沙箱用容器化方案，日志用结构化日志库。模型接口走标准的 HTTP 调用，不绑定特定供应商。

目录结构大致这样组织：harness/core放循环和状态机，harness/context放上下文管理，harness/sandbox放沙箱接口和实现，harness/validator放验证器，harness/persistence放持久化，harness/tools放工具定义。每个模块之间通过明确的接口通信，方便单独测试和替换。

初始化配置里几个关键参数：max_context_tokens根据模型窗口设，留 20% 余量给输出；compression_threshold设 0.7；max_steps_base按任务类型设，代码类任务 80，文本类任务 40；checkpoint_interval按阶段设，不按固定步数。这些参数没有绝对最优值，需要根据实际任务分布调优。

4.2 循环控制器的实现细节

循环控制器是整个 Harness 的调度中心。它的主循环逻辑用伪代码表示大概是这样：

async def run_loop(task, context, sandbox, validator, persistence): state = LoopState.RUNNING step = 0 while state == LoopState.RUNNING: step += 1 if should_terminate(step, context, task): state = LoopState.TERMINATED break model_input = context.build_input() model_output = await call_model(model_input) action = parse_action(model_output) if action is None: context.add_error("无法解析行动指令") continue result = await sandbox.execute(action) validation = validator.check(action, result, context) if validation.passed: context.add_observation(result) context.update_progress(model_output.progress) else: handle_validation_failure(validation, context) if should_checkpoint(step, context): persistence.save_checkpoint(build_checkpoint(state, context, sandbox)) return state

这段逻辑里，should_terminate综合判断步数、时间、完成标志和进度停滞。handle_validation_failure根据失败类型决定重试、换策略还是中止。should_checkpoint按阶段跃迁触发。每个函数的具体实现根据任务类型有差异，但骨架是通用的。

4.3 上下文压缩的具体操作

压缩操作在上下文使用率达到阈值时触发。具体步骤：先标记出所有“决策点”轮次（Agent 做出关键选择的轮次，比如选择工具、确定参数、判断完成），这些轮次不压缩。然后把剩余轮次按时间倒序排列，保留最近 K 轮完整记录。更早的记录按类型分组：事实类信息合并成摘要，推理类信息只保留结论，错误信息保留错误码和简要描述。最后让模型对合并后的内容生成一段连贯的摘要文本，替换原始记录。

压缩后的上下文结构变成：系统提示 + 决策点记录 + 近期完整记录 + 历史摘要。这个结构在多次压缩后依然保持稳定，不会出现“摘要的摘要”导致信息严重失真。我们实测过连续压缩 8 次后的上下文质量，关键信息的保留率在 85% 以上。

4.4 沙箱工具集的定义与实现

工具定义用 JSON Schema 描述参数，实现层做具体的操作。以文件读取工具为例，参数包括path（必填，字符串）、encoding（可选，默认 utf-8）、max_bytes（可选，默认 1MB）。实现时先做路径规范化，检查是否在允许的工作目录内，然后读取文件，超过大小限制就截断并返回截断标志。

工具执行结果统一格式：{success: bool, data: any, error: str, metadata: dict}。metadata里放执行耗时、资源消耗等信息，供验证器和监控使用。这个统一格式让验证器可以用同一套逻辑处理所有工具的结果。

4.5 验证器的规则配置

验证器分三层，每层的规则用配置驱动。格式验证的规则比如“输出必须是合法 JSON”“必须包含 action 字段”。语义验证的规则比如“读文件操作 success 为 true 时 data 不能为空”“写文件操作后文件大小应大于 0”。进度验证的规则比如“连续 3 轮 progress 增量小于 5 则触发预警”。

规则配置支持热更新，不用重启 Harness 就能调整验证策略。这在调试阶段特别有用，发现某个规则误报率高，直接改配置就行。

4.6 持久化与恢复的实操

检查点写入用事务保证原子性。检查点内容序列化成 JSON，包含循环状态、上下文快照、沙箱工作目录的文件清单和校验和、已完成步骤的 ID 列表。恢复时先加载检查点，重建上下文和沙箱环境，然后从步骤日志中读取检查点之后的记录，按顺序重放（只读结果，不重新执行）。

步骤日志用追加写的方式，每条记录包含步骤 ID、时间戳、行动指令、执行结果、验证结论。日志文件按任务 ID 分片，方便检索和清理。

5. 常见问题与排查技巧实录

5.1 循环卡死与无效重试的排查

症状：Agent 反复执行同一个操作，上下文里堆满了相同的错误信息。

排查思路：先看错误信息是否完全一致。如果完全一致，说明 Agent 没有从错误中学习，可能是上下文里缺少“这个操作已经失败过”的明确提示。解法是在验证失败时，除了写入错误信息，还要写入一条“禁止重复此操作”的指令。如果不完全一致但高度相似，说明 Agent 在微调参数但方向错误，需要触发策略重规划。

避坑技巧：给每个工具调用生成一个指纹（工具名 + 参数哈希），在上下文里维护一个“已尝试指纹”集合。当 Agent 尝试一个已存在的指纹时，直接拦截并提示“此操作已尝试过，结果如下”，避免无效重试。

5.2 上下文溢出与信息丢失的平衡

症状：压缩后 Agent 突然“忘记”了之前的关键信息，开始重复已完成的工作。

排查思路：检查压缩时是否误删了决策点记录。决策点识别逻辑可能漏判了一些关键轮次。另一个可能是摘要生成质量太差，丢失了关键细节。

避坑技巧：压缩后加一步“一致性检查”：让模型回答几个关于任务状态的问题（比如“当前完成了哪些步骤”“下一步计划是什么”），如果回答与压缩前矛盾，说明压缩过度，需要回滚并调整压缩比例。

5.3 沙箱环境不一致导致的诡异错误

症状：同样的操作在本地测试正常，在沙箱里报错。

排查思路：对比本地和沙箱的环境差异，重点检查工作目录、环境变量、依赖版本、文件权限。沙箱重置不彻底是常见原因，上一个任务留下的文件可能影响当前任务。

避坑技巧：沙箱重置时做一次“干净度检查”：列出工作目录所有文件，与初始状态对比，多出来的文件全部删除。环境变量恢复成基线快照。这个检查耗时不多，但能拦住大部分环境不一致问题。

5.4 长时运行中的内存泄漏与资源耗尽

症状：任务运行几小时后，进程内存持续增长，最终被系统杀掉。

排查思路：检查上下文管理是否及时释放了不再需要的对象。日志和检查点数据是否无限累积。沙箱池是否有实例泄漏（借出后没归还）。

避坑技巧：给所有资源加计数器，定期打印资源使用快照。上下文对象用弱引用持有，避免循环引用。日志文件按大小滚动，检查点只保留最近 N 个。沙箱实例加超时自动回收。

5.5 验证器误报与漏报的调优

症状：验证器频繁拦截正常操作，或者放过了明显错误的结果。

排查思路：收集误报和漏报的案例，分析规则哪里过严或过松。格式验证的误报通常是 Schema 定义太死，语义验证的漏报通常是规则覆盖不全。

避坑技巧：验证器加一个“影子模式”：新规则先只记录不拦截，观察一段时间后再决定是否启用。这个模式让我们在调整验证规则时有了数据支撑，避免了拍脑袋改规则导致的连锁问题。

6. 长时运行场景下的进阶优化

6.1 任务分解与子任务编排

超过一定规模的任务，单靠一个循环跑到底效率很低。我们的做法是在 Harness 上层加一个“任务编排器”，把大任务拆成子任务，每个子任务独立运行一个 Harness 实例，子任务之间通过消息队列传递结果。这样单个子任务失败不影响整体，重试成本也低。

拆分粒度是个经验活。太粗起不到隔离作用，太细增加编排开销。我们的参考标准是：每个子任务能在 10 到 30 分钟内完成，步骤数在 30 到 80 之间。这个范围是根据上下文消耗速率和错误恢复成本综合定的。

6.2 跨会话的状态继承

有些任务需要跨会话保持状态，比如一个持续多天的数据收集任务。我们的方案是把持久化层做成独立的服务，Harness 实例启动时从服务加载状态，运行中定期同步，结束时写回。状态服务用版本号做并发控制，避免多个实例同时修改同一任务状态。

6.3 监控与告警体系

生产环境的 Harness 必须有监控。我们采集的指标包括：每轮循环耗时、上下文使用率、验证通过率、工具调用成功率、检查点写入延迟。这些指标按任务 ID 和时间维度聚合，异常时触发告警。告警阈值不是固定的，而是根据历史数据的百分位数动态调整，避免误报。

这套监控体系帮我们提前发现了多次潜在故障，比如上下文使用率异常攀升往往预示着 Agent 陷入了低效循环，验证通过率骤降通常意味着任务环境发生了变化。

7. 我个人在实际操作中的几点体会

做 Harness 工程这一年多，最大的感受是：Agent 的智能程度取决于模型，但 Agent 的可靠程度完全取决于 Harness。我们花在调提示词上的时间可能只占两成，剩下八成都在打磨循环、上下文、沙箱、验证和持久化这些“脏活累活”上。但正是这些脏活累活，决定了 Agent 能不能从 demo 走向生产。

另一个体会是：不要追求一步到位。我们最初的 Harness 只有循环和沙箱，验证和持久化都是后来遇到问题才补上的。每个模块都是在真实故障的驱动下逐步完善的。如果你刚开始做，建议先把循环和上下文管理做扎实，这两个是基础中的基础，其他模块可以边跑边加。

最后分享一个小技巧：给 Harness 加一个“回放模式”。把任务执行过程中的所有输入输出记录下来，需要调试时用回放模式重新跑一遍，但模型调用和工具执行都走录制的数据。这个模式让我们能在不消耗模型额度的前提下复现问题，调试效率提升非常明显。这个功能实现起来不复杂，但在排查偶发问题时价值巨大。