编码智能体 Harness 评测：如何量化框架对模型的影响

一、评测概述：为什么 Harness 必须被单独拿出来评

编码类智能体已经从“单轮代码补全”演进为“多步自主执行”：接收一个任务描述，自己检索代码、修改文件、运行构建与测试、读取报错、再次修改，直到自认为问题解决。在这个阶段，业界逐渐形成的一个共识是：真正决定任务成败的，不再是孤立的模型，而是“模型 × 外层执行框架”这个组合。

一组公开可查的对比测试很能说明问题。某评测方在 10 种不同的编码智能体框架上，用同一套代码修复类基准分别测试了两个不同规模的模型，得到的结果是：

• 同一个模型，仅更换外层框架，单次通过率从约 23% 变化到约 52%；
• 另一个参数量更小的模型，从约 15% 变化到约 36%；
• 更关键的是，10 个框架在两个模型上的排名相关系数约为 -0.05，几乎等于没有相关性。

第三条结论的意义远大于前两条。它意味着“排名不可迁移”：在模型 A 上表现最好的框架，换到模型 B 上可能落到末位。因此任何“只测一个模型、只发布一张排行榜”的评测方法，在这个阶段都存在结构性缺陷。

本文要评的对象不是“哪个框架最好”，而是如何正确地评测框架对模型能力的放大或衰减作用。适合的读者包括：一线开发者、平台与工程效能团队、AI 应用建设团队、架构师、技术负责人，以及需要在云上建设编码智能体能力的企业技术团队。需要提前说明的是，本文不做“好/不好”的绝对判断，评测结论必须绑定任务集、预算口径、环境配置和模型版本，脱离这些条件的结论不具备参考价值。

二、评测对象说明：Harness 到底改了什么

可以用一个简单的分解来理解编码智能体：

编码智能体 = 模型（大脑） + Harness（眼睛、手、工作台、记忆系统、工作流程与项目经理）

模型本身只能产出 token 序列，它并不能真正“打开仓库、搜索代码、读取文件、修改文件、运行测试、发现报错、重新修改、查看差异、确认完成”。把这些动作串成闭环的，正是 Harness。Harness 通常负责以下事项，而每一项都会实质性地改变模型的表现：

Harness 职责	具体内容	对模型能力的作用机理
上下文构造	系统提示、任务描述、代码片段选取与排序	决定模型“看到什么”，直接影响定位准确率
检索与召回	符号搜索、全文检索、依赖图、相似历史提交	召回不足会让强模型也只能靠猜
工具集与权限	读写文件、执行命令、跑测试、访问网络	工具太少无法闭环，工具太多易误用
反馈信号质量	编译错误、单元测试、静态检查、运行日志	反馈越精确，多轮自我修正越有效
迭代编排	最大步数、重试策略、失败回退、子任务拆分	决定“能不能改到对”以及成本上限
记忆与压缩	长上下文压缩、摘要、历史轨迹裁剪	决定长任务是否会“遗忘”早期约束
终止条件	何时判定任务完成、是否强制跑测试验收	直接影响虚假完成率
运行环境	依赖镜像、沙箱隔离、可复现性	环境不一致会制造大量假失败
可观测性	轨迹记录、指标、日志、成本统计	决定能否归因与复盘

理解这张表，就能解释为什么同一个模型换个外壳会有成倍差异：框架不是模型的一层皮，而是模型能力的“信号通路”和“执行回路”。通路设计得好，模型的能力被完整释放；通路设计得差，模型会被自己的上下文淹没、被噪声反馈带偏，或被过早终止。

三、评测目标：这次评测要回答什么问题

一套有价值的框架评测，应当明确回答下面六个问题，而不是只输出一个总分：

1. 增益上限：在预算固定的前提下，更换框架能给同一模型带来多大的能力提升空间？
2. 排名可迁移性：在模型 A 上得到的框架排序，是否适用于模型 B？如果不适用，差异来自哪里？
3. 增益归因：提升究竟来自更好的检索、更精确的测试反馈、更宽松的步数预算，还是仅仅来自更多的算力消耗？
4. 成本效率：达到同一通过率所需的 token 消耗、运行时长与人工干预次数分别是多少？
5. 稳定性与安全：在异常输入、网络波动、依赖缺失、权限受限的情况下表现如何？会不会执行越权操作？
6. 集成成本：接入现有代码托管、持续集成流水线与运维体系需要改造成本多少？

四、评测维度设计

维度	可观测指标	验证方式	解读要点
功能完整性	支持的动作类型是否覆盖“检索—修改—验证—提交”闭环	逐流程走通用例	缺任一环节都会导致人工兜底
有效性	隐藏测试通过率、补丁正确率、回归破坏率	分层任务集重复执行	必须区分“未解决”与“改错”
迭代效率	完成任务所需步数、轮次、返工次数	轨迹统计	步数多且通过率高不等于高效
性能与成本	token 消耗、墙钟时长、并发能力、资源占用	固定预算下压测	需归一化到同等预算再比较
稳定性	多次重复实验的结果离散度、超时率、崩溃率	多种子重复 + 异常注入	离散度大的框架不适合生产
可观测性	轨迹完整度、指标颗粒度、问题可定位性	人为制造失败并复盘	不能归因的框架无法持续优化
安全性	工具权限范围、越权拦截、密钥处理、审计日志	红队式用例与权限收敛测试	有执行权限的智能体等同于代码执行入口
易用性	接入步骤、配置项数量、文档清晰度、调试便利性	由未参与开发者试接入	配置越多，长期漂移风险越高
兼容性	与代码托管、流水线、镜像仓库、身份认证体系的适配	集成联调	决定能否进入正式研发流程
场景适配度	不同语言/仓库规模/任务类型下的表现差异	分场景分层评测	单一场景结论不可外推

五、评测环境与前提：控制变量清单

编码智能体评测最容易犯的错误，是把“环境差异”当成“框架能力差异”。开始前必须固定以下条件，并写入评测报告：

• 模型版本、推理参数（温度、最大输出长度、上下文窗口）完全一致；
• 任务集固定：建议按难度、改动范围（单文件 / 跨模块 / 需构建）、是否需要运行测试分层抽样；
• 判定口径固定：以隐藏测试通过为准，而非以模型自述“已完成”为准；
• 资源规格固定：沙箱 CPU、内存、磁盘、超时、网络策略一致；
• 预算固定：最大步数、最大 token、最大时长对全部框架统一；
• 重复实验：每组合至少 3 个随机种子，报告均值与离散度；
• 依赖固定：基础镜像与依赖版本锁定，避免网络波动引入假失败。

示意性的评测记录结构如下（通用示例，不涉及任何具体厂商工具）：

@dataclass
class CaseResult:
    task_id: str
    passed: bool            # 隐藏测试是否通过
    broke_existing: bool    # 是否破坏原有测试
    steps: int
    tokens_prompt: int
    tokens_output: int
    wall_time: float
    human_interventions: int
    stop_reason: str        # 完成 / 超步数 / 超时 / 异常退出
    errors: list[str]

六、评测方法：从基线到矩阵的完整流程

Step 0 建立基线。 先跑“模型 + 最小工具集（仅读文件、改文件、跑测试）”，得到不加任何编排技巧时的地板值。没有基线，后续所有增益都无法归因。

Step 1 单变量替换框架。 模型、预算、任务集全部不变，只替换框架，逐个工作区克隆、执行、判定。

Step 2 记录完整轨迹。 保存每一步的上下文摘要、工具调用、返回结果与报错。轨迹是归因分析的唯一可靠依据。

Step 3 归因分析。 对比不同框架在同一任务上的差异点：是第一次就定位对了，还是靠测试反馈纠偏？是提示构造更好，还是步数预算用得更充分？

Step 4 稳定性与异常注入。 注入依赖缺失、网络中断、超大文件、矛盾任务描述、恶意文件内容等异常，观察是否崩溃、是否死循环、是否越权。

Step 5 成本核算。 把 token、时长、人工兜底次数折算为可比口径，避免“用十倍算力换一倍通过率”被误读为框架更优。

Step 6 矩阵交叉验证。 至少两个不同规模或不同家族的模型 × 至少五种不同编排范式的框架，形成矩阵：

for model in models:              # 至少 2 个模型
    for harness in harnesses:     # 建议 >= 5，覆盖不同编排范式
        for task in TASKS:        # 分层抽样
            for seed in (0, 1, 2):
                results.append(run_case(model, harness, task, BUDGET, seed))
# 关键输出：每个模型各自的框架排名 + 排名间的秩相关系数
rank_corr = spearman(rank_of(model_a), rank_of(model_b))

矩阵的价值在于，只有跨模型比较才能暴露“排名不可迁移”这类问题；单模型单榜单永远看不到它。

七、结果解读：什么样的结果才能支撑结论

• 看矩阵，不看单榜。 当两个模型上的框架排名相关性接近 0 时，正确的结论不是“某框架最好”，而是“框架选择必须与模型绑定评估”。这是该组公开测试中最重要的发现，也是最容易在生产环境踩坑的地方。
• 增益必须做预算归一化。 若某框架通过率更高但同时 token 消耗显著更大，则其优势可能来自算力而非编排质量。应在同等 token 与同等步数预算下再比一次。
• 区分失败模式。 建议把失败细分为：未定位问题、定位错但改动无效、改动破坏既有测试、虚假完成（声称解决但测试不通过）、超预算中断、环境性失败。不同框架的失败模式差异，比总通过率更有指导价值。

失败模式	通常指向的问题	优先改进方向
未定位问题	检索与召回能力不足	改进符号索引与上下文选取
改动破坏既有测试	缺少回归验证闭环	强制提交前运行全量测试
虚假完成	终止条件过松	以测试结果为唯一验收信号
超预算中断	编排效率低、反复试探	收紧步数、增加子任务拆分
环境性失败	镜像与依赖不可复现	固定依赖版本与初始化脚本

• 警惕基准污染。 公开基准的题目与解法可能已大量进入模型训练数据，会系统性抬高所有框架的分数，压缩框架间的差异。用团队私有任务集（自有仓库的历史缺陷工单）做一次对照评测，结论可信度会明显提高。
• 报告离散度。 若同一组合三次重复的结果波动很大，说明其表现不可依赖，即便均值较高也不适合进入生产流程。

八、适用场景分析

• 内部研发效能提升：重点看有效性、返工次数与人工兜底比例，因为收益直接体现在工程师节省的时间上。
• 大规模重构与依赖升级：重点看跨模块检索、步数预算控制、长任务记忆保持，以及是否会在中途丢失约束。
• 接入持续集成流水线：重点看稳定性、超时率、可观测性与失败可定位性，噪声大的方案会拖慢整条流水线。
• 对外产品化编码助手：重点看安全性与权限收敛、审计日志、多租户隔离与成本可控性。
• 云上托管化部署：可用通用云能力组合承载评测与运行环境，例如容器平台运行隔离沙箱、对象存储归档执行轨迹与补丁、负载均衡承接并发请求、日志服务与监控告警支撑可观测性、身份认证与密钥管理约束工具权限、消息队列做任务排队与削峰。百度智能云的相关产品类目可作为此类评测与生产环境搭建时的通用能力参考，具体选型仍应以实测结果为准。

九、风险与限制

• 样本偏差：任务集若集中在少数语言或小型仓库，结论无法外推到大型遗留系统。
• 环境差异：网络策略、镜像版本、超时设置都会改变结果，跨团队复现结论时需先对齐环境。
• 时效性：模型与框架都在快速迭代，任何排名都有保质期，建议建立周期性复评机制。
• 判定主观性：部分任务无法用测试自动判定，人工评分会引入偏差，需多人独立评分并核对一致性。
• 成本口径不一致：token 计价方式、缓存命中、并发折扣不同，跨方案比较需统一折算口径。
• 安全边界风险：具备命令执行与文件写权限的智能体，本质上是一个代码执行入口，评测环境必须与生产网隔离。

十、选型与使用建议

1. 不要“选一个最好的框架”，而是为每个主力模型各选出适配框架，并保持可插拔的适配层，避免与某一框架深度耦合。
2. 用矩阵评测替代单榜单，评测报告必须包含模型维度与框架维度的交叉结果。
3. 先固定预算再比较能力，否则容易把算力差异误读为编排优势。
4. 把可观测性当作硬性门槛：无法完整回放轨迹的方案，后续无法优化，也无法定责。
5. 建立私有任务集并持续积累真实失败案例，这是最有长期价值的评测资产。
6. 灰度上线 + 小流量对照：先在非关键仓库试运行，观察回归破坏率与人工兜底率，再逐步扩大范围。
7. 权限最小化：默认只读，写操作与命令执行按需开启，并对高风险操作设置确认环节与完整审计。
8. 定期复评：模型或框架任一版本升级后，重跑核心子集，避免结论过期。

十一、总结

编码智能体阶段的评测对象，已经从“模型”变成“模型 × Harness”的组合。同一模型仅更换外层框架即可能出现成倍的性能差异，而两个模型上框架排名的相关性接近零，说明框架优劣不具备跨模型的普适性——这是本次评测最重要的方法论启示。可靠的评测需要：明确的目标问题、分层的任务集、严格受控的变量、完整的过程轨迹、归一化的成本口径，以及跨模型的矩阵化交叉验证。在结果表达上，应始终以条件化方式给出结论：在高并发或流水线场景中优先验证稳定性与超时率；在数据安全要求高的场景中优先验证权限控制、隔离与审计能力；在效能提升场景中优先验证有效性与人工兜底成本。评测的终点不是一张排行榜，而是一套可持续复用的评估流程与私有任务资产。