Code Agent Harness 如何通过规划、记忆和工具调用形成差异化？

Code Agent 看起来往往都遵循相似循环：读取任务、分析上下文、调用工具、观察结果，再决定下一步。仅比较这层循环，产品确实容易显得同质化。真正形成差异的不是有没有 ReAct，也不是预置了多少个“角色”，而是系统能否把模型的一次次概率性输出，约束成可恢复、可验证、可持续推进的工程过程。换句话说，模型决定能力上限，Agent Harness 决定这些能力在真实仓库里能稳定兑现多少。

Agent Harness 可以理解为包围模型的软件运行层。它负责把仓库、终端、编辑器、测试系统和权限边界接到模型上，同时保存状态、控制执行、收集反馈。相关研究提出“Code as Agent Harness”的视角：代码不只是 Agent 最终交付的产物，也是推理、行动、环境建模和执行验证的载体。代码可执行、可检查、可持久化，因此比一段只存在于对话中的自然语言计划更适合支撑长时间任务。

差异化首先来自 Harness，而不是循环名称

一个最小 Agent 可以用几十行代码实现“模型输出工具调用，工具返回结果，再交给模型”的循环。但进入真实开发环境后，困难迅速转移到循环之外：如何只加载当前步骤需要的文件，如何识别生成的补丁是否破坏既有行为，如何在进程中断后恢复，如何阻止高风险命令，如何让用户知道 Agent 改了什么，以及如何在预算耗尽前停止无效尝试。

这些问题共同决定了实际体验。同一个模型接入两个不同 Harness，可能在一次性小题上差别不大，在跨文件修改、依赖升级、复杂调试或持续数小时的任务上却产生明显分化。优秀系统的优势通常表现为更少的无关读取、更准确的局部修改、更早发现失败、更可靠地保留进度，以及在不确定时选择停下而不是制造更大副作用。

因此，评估 Code Agent 不能只看它能否调用 shell、搜索和编辑工具。更有价值的问题是：它如何表示任务状态，如何挑选上下文，工具结果是否结构化，验证是否覆盖真实风险，错误能否回到计划层，以及权限机制能否约束状态变更。差异化是这些机制的组合效果。

规划的价值在于形成可检查的执行契约

规划不是把任务改写成一串漂亮的待办项。有效规划要把目标转化为可以被环境检验的约束，例如“修改解析器但保持公开接口不变”“迁移数据库后旧数据仍可读取”“修复移动端溢出且桌面布局不回退”。这样的计划为后续验证定义了成功条件，也为失败后的重新规划提供依据。

不同任务需要不同粒度。单文件命名修正可能无需显式长计划；仓库级重构则需要先定位调用关系、明确不可变接口、划分修改批次，再逐层验证。若系统对所有任务都套用固定步骤，工作编排很容易成为额外开销。真正有用的编排会依据依赖结构、可逆性、风险和反馈成本动态调整。

可以把一次执行单元抽象为下面的结构。它不是给用户看的文案，而是 Harness 可以保存和检查的状态：

{
  "goal": "修复配置加载的兼容性问题",
  "constraints": ["保持公开接口", "不丢弃旧格式"],
  "evidence": ["失败测试", "调用位置", "配置样例"],
  "next_action": "修改解析分支",
  "verification": ["目标测试", "回归测试", "静态检查"],
  "rollback_point": "patch-before-parser-change"
}

这种结构让计划具有三个作用：限制行动范围，记录做出判断的证据，并声明验证方式。它也解释了为什么“多 Agent”不天然优于单 Agent。若多个角色只是重复阅读同一段上下文、输出互相重叠的意见，增加的只是通信成本；只有当任务可分解、角色有明确输入输出、共享状态可同步，并且并行收益高于协调成本时，多 Agent 编排才有价值。

记忆的核心不是存得多，而是取回得准

模型上下文有限，仓库信息却可能持续增长。把所有历史对话、终端日志和文件内容不断塞入上下文，会造成成本上升、注意力稀释和过期信息干扰。成熟的记忆系统通常会区分工作记忆、语义记忆、经验记忆和长期状态。

工作记忆保存当前步骤直接需要的目标、打开的文件、未解决错误和近期工具结果；语义记忆保存仓库结构、模块职责、接口关系等相对稳定的信息；经验记忆记录某类故障曾经如何定位，但不能未经验证就当作本次事实；长期状态则用于跨会话恢复任务进度、决策与产物。不同层次有不同的写入、失效和召回策略。

差异主要体现在上下文工程：系统能否根据当前动作找到最小充分证据，能否区分源代码事实与模型推断，能否在文件变化后让旧摘要失效，能否压缩冗长日志而保留错误位置、退出码和关键调用链。高质量记忆减少重复搜索，也避免 Agent 因一条过期结论在错误方向上持续推进。

记忆还必须可追溯。若系统只留下“这里应该改”的摘要，却丢失对应文件、测试失败或用户约束，后续步骤无法判断结论是否仍然成立。更稳妥的方式是让记忆项携带来源、生成时间、适用范围和置信状态，在使用前按当前仓库状态重新校验。

工具调用的竞争点是契约、反馈和权限

工具数量不是越多越好。每增加一种工具，就增加参数选择、错误处理和安全控制的复杂度。高质量工具接口应当让输入边界明确、输出结构稳定、失败可诊断，并尽可能支持幂等或回滚。比如，搜索工具不仅返回文本，还应返回文件位置；编辑工具应暴露实际 diff；测试工具应保留退出码、失败用例和截断说明。

工具设计还影响模型的行动空间。一个只能接收任意 shell 字符串的接口很灵活，但难以细粒度授权；一个区分读取、写入、网络访问和发布动作的接口，更容易在执行前评估风险。对于删除数据、修改生产配置或对外发送内容等操作，Harness 应建立显式权限边界，而不是依赖模型在提示词中“记得谨慎”。

沙箱、允许列表、路径范围、超时、资源配额和人工确认都属于工具层能力。它们并不直接提升模型智力，却能显著提高可用性，因为系统可以放心地允许低风险动作自动执行，把高风险状态变更留给确定的授权点。对企业场景而言，审计记录和身份权限往往比多一种规划算法更能形成采购壁垒。

执行反馈把语言推断变成工程闭环

代码作为 Harness 的关键优势，是它能产生相对确定的反馈：编译器错误、测试通过与失败、静态分析告警、运行轨迹、性能数据和补丁差异。模型负责提出候选行动，环境负责揭示候选行动的实际后果。只有把这些结果重新送入决策过程，Agent 才不是一次性的代码生成器。

一个可靠闭环通常包含“计划、执行、验证、修正”。其中最容易被弱化的是验证。只检查命令退出码不够，因为测试可能没有覆盖目标行为；只检查最终测试通过也不够，因为 Agent 可能删除了测试、扩大了忽略规则或改变了不应变化的接口。验证需要同时观察产物、行为和约束。

while task.not_finished():
    action = plan(task.state, evidence)
    result = execute_in_sandbox(action)
    evidence = verify(result, task.constraints)
    if evidence.indicates_regression:
        restore_or_replan()
    elif evidence.is_insufficient:
        gather_more_evidence()
    else:
        commit_progress()

这个闭环的差异化体现在验证传感器是否可靠，以及失败是否能改变上层策略。低水平系统遇到同类错误会反复重试；更好的系统会识别失败类别，判断是上下文不足、计划错误、工具故障还是权限受限，然后选择补充信息、缩小修改、切换策略或请求人工介入。

共享状态决定多 Agent 是否真正有效

多 Agent 系统常见的角色包括规划、编码、审查、测试和执行。角色名称本身不会产生收益，关键是它们是否围绕同一份可检查状态协作。仓库、补丁、测试、执行轨迹和结构化任务记录可以充当共享媒介，使不同角色看到同一个事实基础。

如果共享状态只存在于自然语言消息中，就容易出现版本不一致：审查者检查的是旧补丁，测试者使用的是另一套依赖，规划者不知道某项假设已被推翻。随着 Agent 数量增加，上下文同步成本会快速上升。因而，多 Agent 产品真正需要解决的是状态收敛、冲突合并、任务所有权和验证责任，而不是简单增加对话轮数。

适合并行的工作通常具有清晰边界，例如分别调查互不依赖的模块、并行运行不同测试集，或让审查角色基于固定补丁寻找风险。不适合并行的工作包括频繁修改同一文件、依赖尚未确定的接口设计，以及必须按顺序获得反馈的调试链路。编排是否有价值，可以用节省的关键路径时间减去协调、重复读取和冲突处理成本来判断。

产品竞争最终落在稳定兑现率

Code Agent 的竞争壁垒可以分成几个层面。第一层是模型适配，包括提示策略、上下文格式和不同任务的模型路由；第二层是仓库理解与状态管理；第三层是工具、沙箱和验证设施；第四层是用户工作流，包括编辑器交互、审查体验、恢复机制和团队权限；第五层是持续优化所需的遥测与评测体系。

这些能力具有累积效应。真实任务产生的失败分类和执行轨迹，可以帮助团队发现哪类上下文经常缺失、哪种工具返回不够明确、哪些验证容易漏报，再以受控方式改进 Harness。但优化必须防止回归：提高某类基准成绩的改动，可能同时增加成本、破坏另一类任务或扩大权限风险。因而，稳定的离线评测、影子运行、分阶段发布和可回退配置也是产品能力的一部分。

市场并非只给拥有基础模型的厂商留下空间。模型提供商在推理能力、成本和默认集成上有优势，但垂直团队仍可以通过更深的环境接入、更强的领域验证器、更准确的权限模型和更贴近用户的工作流建立差异。例如，面向大型单体仓库、受监管行业、特定构建系统或内部运维平台的 Agent，需要大量领域状态和执行约束，这些并不能由通用 ReAct 循环自动获得。

如何判断一个 Harness 是否成熟

选型或设计时，可以用真实长任务观察系统，而不是只看演示。首先检查它能否说明读取了哪些证据，以及计划如何对应验收条件；其次检查中途失败、上下文压缩或进程重启后能否恢复；再次检查每次修改是否展示可审查的差异，并运行与风险匹配的验证；最后检查敏感动作是否有明确权限、审计与停止机制。

评测指标也不应只有最终成功率。还应记录首次有效修改所需时间、无效工具调用比例、回退次数、验证覆盖、人工接管点、成本、延迟，以及成功任务中是否引入隐藏回归。对于多 Agent，还要衡量重复工作、同步开销和共享状态冲突。只有这样，才能分辨系统是在稳定解决问题，还是偶然得到一个看似正确的结果。

归根结底，规划、记忆和工具调用都不是孤立卖点。规划定义可检验的行动契约，记忆保存并召回相关状态，工具把意图变成受控操作，执行反馈再把结果送回计划。Code Agent 的差异化正是这条闭环在具体环境中的可靠程度：能否用更少干扰找到证据，用更低风险实施修改，用更强验证证明结果，并在失败时安全恢复。这比循环叫什么名字，更接近真正可持续的产品壁垒。