模型之外，Coding Agent 还需要一套怎样的执行系统

一句需求进入 Coding Agent 后，背后是模型、Harness 与执行环境的协同运作。Harness 作为核心执行系统，决定上下文组织、工具调用与任务验证方式，直接影响 Agent 的最终表现。本文深入拆解 Harness 的运作机制，揭示任务越长其作用越明显，为产品经理理解 AI 编程工具提供新视角。

如果我们把一句需求交给 Coding Agent，例如：

“登录接口偶尔返回 500，请找到原因，修复问题并补上测试。”

用户输入只有一句话，Agent 接下来却要完成一连串动作。它先查看代码仓库，找到登录接口和相关测试，再读取项目说明与依赖配置。确认问题位置以后，它修改代码，运行测试，根据报错继续调整。测试通过也不一定代表任务结束，它还要检查改动范围，确认没有破坏其他功能，最后向用户说明改了什么。

一句需求进入 Coding Agent 后，会经历读取代码、修改代码、运行测试和确认完成等步骤。

这些动作经常被笼统地归入“模型能力”。沿着执行过程拆开，会发现模型主要负责理解当前信息并判断下一步。例如决定先搜索哪个文件，看到报错后选择怎样修改。读取文件、执行命令和保存改动，需要外部系统把模型的判断转成实际操作。操作产生的新结果还要送回模型，供它继续判断。

只要任务尚未完成，或者结果仍需验证，系统就会继续组织上下文、调用模型和执行工具。

模型判断、工具执行和结果返回构成 Agent 的基本运行循环，验证通过后任务才结束。

围绕模型运行的这套执行系统，就是 Harness。

一、Harness 怎样把模型接入代码环境

用户提交任务后，Harness 会整理模型当前需要的信息，其中可能包含用户要求、项目说明和前面完成的操作。模型读完这些内容，决定下一步行动。假如它提出搜索某段代码，Harness 就调用相应工具，再把搜索结果送进后续上下文。模型获得新信息后继续判断，直到系统确认任务完成，或者遇到需要用户处理的情况。

这个循环是 Harness 最基本的部分。它还要处理很多不会直接出现在最终回答中的工作。工具执行失败以后，错误信息要以什么格式返回。任务进行到一半，哪些状态需要保存。模型准备执行高风险命令时，是否需要用户确认。

OpenAI 在介绍 Codex App Server 时，把 Codex Harness 描述为支撑各类 Codex 使用体验的 Agent 循环和核心逻辑。Codex 可以出现在命令行、IDE、网页和桌面应用中，底层仍然能够复用同一套 Harness。界面负责让用户提交任务和查看过程，Harness 负责维持任务运行。

Anthropic 对 Agent Harness 的描述与此接近。它处理输入，协调模型的工具调用，再将执行结果返回。Anthropic 还把 Session、Harness 和 Sandbox 分开。Session 保存任务中发生的事件，Sandbox 提供运行代码和修改文件的环境，Harness 位于两者之间，持续调用模型并安排工具执行。

模型负责当前判断，Session 保存过程，Sandbox 提供执行环境，Harness 在中间协调信息和行动。

继续沿着登录接口的任务理解。模型读完代码，判断应该修改某处逻辑。Harness 收到这个判断，调用编辑工具。工具在受控环境中修改文件，结果随后被记录下来。模型再次获得相关信息，决定运行哪组测试。

一次代码修改中，模型作出判断，Harness 调度工具，执行环境完成实际操作。

Agent SDK 也常与 Harness 一起出现。SDK 通常提供模型调用、工具接入和会话管理等基础能力，开发者可以用这些能力搭建执行流程。Harness 包含更明确的运行规则，它决定工具怎样进入循环、上下文如何组织，以及系统在什么条件下停止。

一个 Coding Agent 因此包含模型、Harness 和执行环境。模型没有变化时，只要其中的上下文组织、工具设计或执行规则发生变化，用户得到的结果仍然可能不同。

二、同一个模型进入不同 Harness

两个 Coding Agent 即使调用同一个模型，也可能从完全不同的信息开始工作。

一个 Harness 会先读取项目说明，搜索登录接口的调用关系，再挑选相关文件放进上下文。另一个 Harness 可能直接提供大量代码。前一种方式给出的信息更集中。后一种方式包含更多内容，关键线索也可能被无关文件和冗长输出挤到后面。

同一个模型获得的上下文不同，后续判断和代码修改也可能出现明显差异。

代码仓库通常远大于一次上下文能够容纳的范围，Harness 必须决定先查哪里，保留哪些结果，以及什么时候重新读取文件。它删掉了一段仍有用的报错，模型可能重复排查。它一直保留冗长的命令输出，后面的需求和关键代码又可能失去位置。

工具设计也会改变模型的行动质量。模型想查找登录接口时，可以调用文件搜索工具，也可以执行一条终端命令。工具名称、参数说明和返回格式越清楚，模型越容易选择合适的操作。如果搜索工具只返回零散代码，没有文件位置和周围上下文，模型还要继续猜测代码之间的关系。一次不完整的工具返回，可能让后面几轮操作都偏离问题。

权限机制影响的是另一部分体验。有些 Coding Agent 每次修改文件或运行命令都要求确认，用户可以及时阻止危险操作，任务也会频繁中断。有些系统允许 Agent 在受控环境中连续执行，只在访问敏感目录或进行高风险操作时请求确认。两种设计对应不同的安全条件，也决定用户需要投入多少注意力。

频繁确认会增加用户注意力成本。受控执行需要明确环境边界，并在高风险操作前暂停。

结果验证同样属于 Harness 的工作范围。模型修改代码以后，如果系统只让它阅读自己的改动，它很容易根据代码表面判断任务已经完成。接入测试、静态检查和代码差异以后，模型会收到外部反馈。测试失败会触发下一轮排查，意外改动也有机会在提交前被发现。

OpenAI 在一项使用 Codex 开发内部产品的实验中，把项目知识保存在仓库里，并通过自动检查约束代码结构。他们给 Agent 提供可以读取的文档，也让架构规则能够被工具验证。按照 OpenAI 的复盘，这些做法减少了 Agent 理解项目和检查改动时的困难。

这项实践来自 OpenAI 自己的项目，开发方式和资源条件不能直接代表普通团队。不过，它揭示了一个容易被忽略的问题。用户写下的 Prompt 只是 Coding Agent 的一部分输入。仓库结构、项目文档和工具执行结果也会进入它的判断过程。

三、任务越长，Harness 的作用越明显

修复一个范围明确的接口问题，可能在一次上下文窗口内完成。开发完整应用会持续几个小时，代码和任务状态不断增加，模型很难始终保留全部过程。

上下文压缩可以把早期对话整理成较短的摘要，为后续信息腾出位置。摘要必然会舍弃细节。前一轮为什么修改某段代码，还有哪项测试没有通过，这些信息一旦没有保留下来，后续模型就只能重新检查，或者根据当前仓库状态猜测发生过什么。

Anthropic 在 2025 年公布过一项长任务实验。他们让 Claude Agent SDK 根据一段高层需求开发 Web 应用。根据 Anthropic 的记录，缺少额外安排时，Agent 经常一次承担过多功能，在上下文耗尽时留下一项只完成一半的改动。后续会话接手以后，需要花时间恢复项目状态。项目进入后期，Agent 看到仓库里已经有不少功能，也可能提前判断整个任务已经完成。

研究团队为此设计了两类会话。第一次运行由初始化 Agent 建立项目环境，把用户需求展开成结构化的功能清单，同时创建进度文件和初始 Git 记录。后续的 Coding Agent 每次只推进一项功能，结束前更新进度并提交代码。新会话开始时，它先读取进度文件和 Git 历史，检查项目能否正常运行，然后再选择下一项工作。

进度文件、Git 记录和测试状态让新的会话能够理解已有工作并继续推进。

这里最值得产品经理关注的，是信息怎样从一次会话传到下一次会话。开发进度没有被压缩成一句模糊的“项目已经完成大半”，它被拆进功能清单、代码提交和测试状态。后续模型可以通过这些记录确认哪些功能已经完成，哪些仍然失败。

任务拆分解决了执行范围的问题。高层需求只描述最终目标，模型很容易在一次会话中铺开太多工作。Harness 要求 Coding Agent 每次处理一项功能，也要求它在上下文结束前把仓库留在可以继续开发的状态。

完成状态还需要外部验证。Anthropic 在实验中发现，Agent 有时会修改代码并运行局部测试，却没有从用户操作的角度检查完整功能。他们随后让 Agent 使用浏览器自动化工具操作应用，确认页面上的功能能否走通。

局部测试通过只能证明部分代码可运行，端到端验证还要确认用户流程能够完成。

这套方案针对的是特定模型和全栈应用开发实验，不能直接推导出所有 Coding Agent 都应该采用相同结构。它说明了一个更稳定的问题。长任务需要留下后续可读取的状态，也需要把宽泛目标拆成能够检查的阶段。

四、AI 产品经理应该观察什么

产品经理不需要亲手实现整套 Agent 循环，仍然要说明这套循环应该怎样服务用户任务。否则，需求文档里很容易只剩下一句话，让 Agent 自动修复代码。

“自动修复”无法直接用于产品设计。产品经理需要继续追问，Agent 可以修改哪些仓库，遇到信息不足时怎样处理，什么操作需要用户确认，系统又凭什么判断修复已经完成。

产品经理可以从任务结果、信息来源、权限边界和完成证据四个方面检查 Agent 产品。

产品经理先要把用户目标写成可检查的任务结果。

以登录接口为例，用户需要的结果可能包括错误不再出现，已有登录流程保持正常，相关测试可以通过。Agent 回复“问题已经修复”，只能说明模型给出了一个结论。代码是否成功运行、测试是否通过，属于环境中的最终状态。

Anthropic 在介绍 Agent 评测时也强调了这种区别。评测一次预订航班的 Agent，不能只检查它是否回复“已经预订”，还要查看数据库里是否真的产生了订单。换到 Coding Agent，验收对象就是代码仓库、测试结果和应用行为。

产品经理还要和工程团队确认信息来源。Agent 是否能够读取项目说明，能否找到历史报错，用户补充的限制会保留多久，这些都会影响后面的判断。信息缺失时，产品需要决定让 Agent 继续搜索、向用户提问，还是停止当前任务。

权限范围则要根据用户、环境和操作后果确定。在临时 Sandbox 中运行测试，与直接修改生产环境，显然不能采用同样的设置。产品经理需要确认谁承担错误后果，以及操作能否撤销。

一次 Agent 任务可能经过十几轮模型判断和工具调用。最终结果失败时，团队需要知道模型获得了什么信息，调用工具后收到了什么结果，又在哪一步改变了原来的计划。只有最终回答，团队很难判断下一版应该调整 Prompt、工具还是工作流。

一次任务失败需要继续定位到上下文、模型判断、工具执行或结果验证环节。

“Agent 不够聪明”无法直接指导迭代。上下文没有包含关键文件、工具返回缺少错误信息、系统没有验证最终状态，这些描述才能进入需求和评测。

五、Harness 也需要持续删减

理解 Harness 以后，很容易产生一个新的误区。多加一些机制似乎总会提高可靠性。

每个机制都会带来成本。多一次模型调用会增加等待时间和费用，多一个 Agent 会增加交接过程，复杂的状态管理也可能产生新的信息损失。系统越复杂，团队越难判断最终效果究竟来自哪一部分。

有效机制能够改善任务表现，组件持续增加也会带来成本、延迟和协调负担。

Anthropic 的实验提供了一个具体例子。研究人员使用 Claude Sonnet 4.5 执行长任务时，观察到模型在接近上下文限制时倾向于提前收尾。他们在 Harness 中加入上下文重置，让新的会话根据结构化记录继续工作。这项机制解决了当时遇到的问题，也增加了编排复杂度、Token 消耗和运行时间。

换用 Claude Opus 4.5 后，研究人员发现这种提前收尾的表现已经明显减弱，于是从后续 Harness 中移除了上下文重置。后来测试新模型时，他们继续尝试删减原有结构，逐项观察最终结果是否下降。

Harness 中的机制通常对应某种具体失败。上下文重置用于处理长任务后期的状态问题，任务拆分用于限制一次执行的范围。独立评估可以发现 Agent 对自己结果判断过于宽松。模型升级或任务改变以后，原来的失败可能减弱，解决方案也要重新接受验证。

产品团队可以把每个 Harness 组件当成一项待验证的产品假设。加入结构化任务清单以前，先记录它要解决的需求遗漏问题。上线以后检查遗漏是否减少，同时观察任务时间和人工介入有没有增加。如果结果没有改善，这个组件缺少继续保留的依据。

团队先记录失败，再加入针对性机制，通过固定评测决定保留或删除。

Harness 也有基本的能力边界。模型无法理解代码关系时，增加更多循环可能只会让它反复执行错误判断。工具无法访问必要环境时，任务拆分得再细也得不到结果。

以后再看一个 Coding Agent，可以从一次具体任务开始。观察模型获得了哪些信息，Harness 允许它采取哪些行动，再检查系统用什么证据确认任务完成。沿着执行过程，我们才能理解一个 Agent 产品的能力来自哪里，也能知道它下一次失败时应该从哪里查起。

本文由 @但是木已成舟 原创发布于人人都是产品经理。未经作者许可，禁止转载

题图来自作者提供