HarnessOpt-Bench 这类基准测试圈内人第一眼看标题就知道它在补一个什么窟窿现在大家都在测 LLM 能不能写代码、能不能解数学题、能不能跑 Agent 工具调用但很少有人认真测“模型到底会不会优化 Agent 系统自己的运行框架”。这个运行框架也就是标题里的 Harness——一个管着工具调用、上下文整理、错误恢复和测试执行的脚手架层。这次要聊的 HarnessOpt-Bench就是专门把“Harness 优化”这件事拎出来做成评测基准的项目。它评估的不是模型写业务代码的水平而是模型能否读懂一个 Agent 系统的 Harness 源码定位问题给出合理修改并且在改完之后不破坏原有行为。简单说让模型当 Agent 系统的维护者而不是单纯的代码生成器。这篇文章会拆解四件事为什么 Harness Optimization 值得单独做基准和普通代码生成有什么区别。HarnessOpt-Bench 这类评测通常包含哪些任务类型和能力维度。评测流程怎么设计指标怎么算。如果你想在本地复现一套类似评测环境怎么搭、代码怎么写、坑在哪里。先说结论这不是一个能一键启动的 WebUI 工具也不是某个可以直接 pip install 的推理服务而是一个研究方法论层面的 Benchmark 工作。但它产出的任务设计、评测脚本和指标方案完全可以落到你自己的 Agent 工程里用来度量“当前这个模型到底能不能安全地改我手上的 Harness 代码”。1. 核心能力速览先给一张速览表把 HarnessOpt-Bench 的定位和关键属性列清楚。部分参数取决于最终开源版本写“以项目发布为准”的地方就是需要你拿到仓库后自己确认的。能力项说明项目定位LLM 能力评估基准聚焦 Harness 优化任务评估对象代码大模型、Agent 系统集成模型等任务类型Harness 代码理解、缺陷修复、功能增强、参数调优、重构与适配核心假设模型对 Agent 运行框架的修改能力可以独立评测评测方式任务描述 Harness 代码 测试集模型输出补丁后自动验证典型指标测试通过率、目标达成度、回归率、patch 正确性、token 效率硬件需求低主要开销来自 LLM 推理。API 模式几乎不需要本地 GPU本地部署方式评测脚本 模型推理服务一般以 Python 脚本方式运行依赖环境Python、LLM API 或本地推理后端、测试框架是否支持 API取决于评测脚本通常需要调用外部或本地 LLM API是否支持批量任务支持批量跑多任务、多次采样是基准测试的基本要求适合人群研究 LLM 能力的算法工程师、Agent 框架开发者、评测平台研发开源情况以项目官方仓库为准建议关注 arXiv 与 GitHub 发布页从定位上看HarnessOpt-Bench 不属于“显存不够就跑不动”的项目。它烧的是 token 和时间不是显存。你完全可以把评测任务丢给云端 API 模型跑本地只保留数据准备和结果分析脚本。2. 为什么 Harness Optimization 值得单独做基准现在主流的 LLM Benchmark 大致分两类一类测知识能力比如 MMLU、GPQA另一类测代码能力比如 HumanEval、SWE-bench。Agent 兴起之后又多了一类测工具调用和任务完成度比如各类 Web 导航测试集。但 Harness 本身处于一个尴尬位置——它既不是业务代码也不是纯算法逻辑而是连接 LLM 与外部环境的系统代码。Harness 优化的特殊性体现在三个地方。第一修改风险高。Agent Harness 通常包含主循环、工具注册表、上下文裁剪逻辑、停止条件、错误重试机制。改坏任何一个环节都会直接影响 Agent 的稳定性和成本。普通代码生成任务里模型写出的代码跑不通只需要报错Harness 优化里代码能编译、测试能通过但整个 Agent 的行为可能已经悄悄跑偏。第二回归问题突出。一个 Harness 往往同时支撑多个任务场景。你今天为任务 A 加了一个上下文压缩逻辑任务 B 的长对话能力可能就退化了。评测必须同时检测“目标能力提升”和“存量能力回退”。第三调试链路长。Harness 的问题往往不在单次运行中暴露而是需要多轮交互、多个工具调用组合才会触发。模型如果只看单点代码片段很难理解全局行为。HarnessOpt-Bench 的价值就是把这些“维护 Agent 系统”的隐性工程能力显式化成任务集和指标。它不关心模型能不能从零写出一个 Agent 框架只关心模型能不能在已有框架上做安全、正确、高效的修改。这个能力画像更接近真实研发场景大多数工程师面对的不是空白文件而是几千行没人敢动的历史代码。从另一个角度看这个基准也能反推模型对“系统行为”的理解深度。一个只会在局部补代码、不考虑全局状态的模型在 Harness 优化任务里会明显露馅。3. 先搞清 Harness 在 Agent 系统里的位置在深入评测细节之前必须把 Harness 这个概念对齐。这里说的 Harness不是测试领域里的 test harness而是 Agent 运行时的那层“壳”。以常见的 Agent 工程为例Harness 通常负责这些事情组织 LLM 与外部工具之间的请求循环把用户目标拆解成可执行的步骤序列管理上下文窗口决定哪些历史信息要保留、哪些要压缩注册和调用工具函数捕获异常并决定是否重试判断任务完成条件终止循环输出日志和过程信息方便后续分析。下面是一个极度简化的 Harness 示意代码。它不代表任何具体开源项目只是用来演示“Harness 层”和“业务代码”的区别。class AgentHarness: def __init__(self, llm, tools, max_steps10): self.llm llm self.tools {tool.name: tool for tool in tools} self.max_steps max_steps self.messages [] def run(self, task: str) - str: self.messages.append({role: user, content: task}) for step in range(self.max_steps): response self.llm.chat(self.messages) action self._parse_action(response) if action[type] finish: return action[result] result self._execute_tool(action) self.messages.append({ role: tool, name: action[name], content: result, }) return Timeout def _parse_action(self, response): # 解析模型输出中的工具调用指令 pass def _execute_tool(self, action): if action[name] not in self.tools: return fUnknown tool: {action[name]} return self.tools[action[name]].run(action[args])在一个真实 Agent 项目里上述代码可能膨胀到上千行还会加入上下文压缩、并发控制、缓存、日志埋点等逻辑。HarnessOpt-Bench 评测的就是模型在“上面这段复杂化、真实化的代码”上做修改的能力。模型需要先理解 main loop、tool executor、context manager 之间如何协作再动手改。4. HarnessOpt-Bench 评估什么任务类型与能力维度从 Harness 优化的实际工作内容出发HarnessOpt-Bench 这类基准通常会覆盖五类任务。4.1 Harness 缺陷修复给出一段存在明确缺陷的 Harness 代码模型需要定位 bug 原因并生成修复补丁。典型缺陷包括上下文无限增长导致长对话 token 超限错误重试机制没有退避策略短时间反复调用失败工具停止条件判断错误任务已完成但循环仍不退出工具返回结果被错误截断模型看不到关键信息。这类任务考察的是代码调试能力和对 Harness 运行语义的理解。4.2 功能增强在现有 Harness 上增加一个明确指定的能力例如“增加一个全局系统提示词注入功能”或“新增对工具返回结果的长度限制选项”。模型需要理解现有代码的扩展点在哪里并以最小侵入方式完成改动。4.3 参数调优不要求改动代码结构只要求调整关键配置参数。比如调整 max_steps、temperature、上下文保留窗口大小。这类任务更贴近实际调参场景但容易被低估——模型需要结合任务描述和已有测试数据判断参数应该往哪个方向调。4.4 重构与维护在保持行为不变的前提下把一段时间内累积的重复代码合并、抽象出公共函数、消除明显的坏味道。验证方式是对比重构前后的测试通过情况确保没有回归。4.5 跨环境适配把 Harness 从一个运行环境迁移到另一个环境比如把工具执行器从同步实现改为异步实现或者把配置加载方式从环境变量改为配置文件。这类任务要求模型理解外部依赖变化对内部逻辑的影响。在能力维度划分上一个合格的 Harness 优化评测至少应该覆盖下面这张表能力维度考察内容失败典型表现目标理解模型能否从任务描述中提取准确的修改目标修改方向与任务描述相反代码定位模型能否准确找到需要修改的函数和文件改动范围过大包含无关文件修改正确性补丁能否解决任务描述中的问题补丁可应用但功能未实现回归控制修改后既有功能是否保持正常目标功能提升但其他用例失败测试意识模型是否主动补充或修改测试只改实现不更新测试资源效率是否避免无效循环、重复 API 调用引入了明显的死循环或重复请求输出规范性是否按规定格式返回 patch输出包含解释文字无法自动应用其中“回归控制”和“资源效率”最容易拉开模型差距。许多模型能写出功能正确的 patch但补丁会把 Harness 的容错能力弄坏或者在错误处理上留下隐患。5. 评测流程与方法论HarnessOpt-Bench 这类评测基准通常按“数据准备 → 模型推理 → 补丁应用 → 自动验证 → 指标统计”五个阶段执行。5.1 数据准备每个评测样本包含三个核心部分一个 Harness 代码快照可能是单一 Python 文件也可能是一个小仓库一份任务描述用自然语言说明希望模型完成什么改动一组验证用例由当前行为断言和目标行为断言组成。验证用例的设计是评测质量的关键。只验证“目标行为是否出现”不够还要验证“原有行为是否保持”。因此评测数据里通常包含 hidden tests专门测试模型补丁是否引入回归。5.2 模型推理评测脚本将任务描述和代码快照组装成 prompt发给目标模型。一般会要求模型只输出 unified diff 或标准 patch 格式方便后续自动应用。为了减少随机性同一任务通常会采样多次计算 passk。5.3 补丁应用与验证拿到模型输出后评测脚本先做格式清洗再用 patch 工具应用补丁。如果补丁无法应用直接判失败。如果应用成功就运行验证用例集记录每个用例的通过情况。这里给出的是一套通用评测循环的 Python 伪代码你可以根据自己的数据格式调整import subprocess import tempfile from pathlib import Path def evaluate_sample(model, sample, work_dir): # 1. 准备测试目录 with tempfile.TemporaryDirectory() as tmp: repo_dir Path(tmp) / repo copy_repo(sample[repo], repo_dir) # 2. 组装 prompt prompt build_prompt( sample[task], read_repo(repo_dir), ) # 3. 调用模型生成 patch response model.generate(prompt) patch_text extract_patch(response) if not patch_text: return {status: invalid_format, score: 0.0} # 4. 应用 patch applied apply_patch(repo_dir, patch_text) if not applied: return {status: apply_failed, score: 0.0} # 5. 运行全部验证用例 passed run_tests(repo_dir, sample[tests]) return { status: finished, target_pass: passed[target], regression_count: passed[regression], score: compute_score(passed), }5.4 指标统计单个样本的得分汇总后按任务类型分组统计。常见做法是输出一张总表包含不同类型的通过率和整体排名。5.5 人工复核自动验证无法覆盖的开放性任务比如 Harness 重构质量、代码风格、设计合理性一般需要引入人工评分或者让更强模型做裁判。这类任务的数据量占比通常不大但能反映模型的高级工程素养。6. 指标设计与打分方式Harness 优化评测的指标不能只依赖“测试是否通过”一个维度否则会出现“功能对了架构烂了”的边角情况。更合理的指标设计会组合下面几种要素指标名称计算方式关注点target_pass目标测试用例通过数 / 目标测试用例总数功能是否达成regression_rate回归失败的存量用例数 / 存量用例总数是否破坏既有功能patch_apply_rate补丁成功应用次数 / 模型回答次数模型输出是否规范passkk 次采样中至少一次全部目标用例通过的概率模型潜在能力上限token_efficiency单任务平均消耗 token成本可控性execution_time单任务平均运行时间实际工程效率一个通行的打分思路是只有 target_pass 和 regression_rate 同时满足阈值才算该样本成功。具体实现时可以先算一个基础成功率再用回归用例做惩罚。例如def compute_score(passed): target_total passed[target_total] target_ok passed[target_ok] regression_total passed[regression_total] regression_ok passed[regression_ok] if target_total 0: return 0.0 target_rate target_ok / target_total regression_rate regression_ok / regression_total if regression_total 0 else 1.0 # 回归率作为惩罚系数回归越少分数越高 penalty 1.0 if regression_total 0 else max(0.0, regression_rate) return round(target_rate * penalty, 4)这种设计的核心思路是目标功能做对了但引入回归仍然要扣分。回归率是乘性惩罚回归越多得分掉得越快。在批量评测中还要考虑任务难度均衡。如果所有样本都是“修改一个 if 条件”级别的任务评测会失去区分度。更专业的做法是按难度分层分别统计不同难度档位的通过率。7. 如何跑一个 HarnessOpt-Bench 风格的本地评测如果你不想干等官方仓库发布可以自己搭一套精简版评测流程。下面给出一套可落地的通用方案。7.1 环境准备Python 3.10 以上一个可调用的 LLM 推理服务OpenAI 兼容 API 或者本地 vLLM 都行git 命令一个测试框架例如 pytest数据集目录建议按下面结构组织harness_bench/ ├── tasks/ │ ├── task_001/ │ │ ├── repo/ │ │ ├── task.md │ │ ├── target_tests/ │ │ └── regression_tests/ │ ├── task_002/ │ └── ... ├── run_eval.py ├── config.yaml └── results/7.2 配置文件下面是一个 YAML 配置示例。这里的路径和 API 均为示例你需要替换成实际环境。model: base_url: http://127.0.0.1:8000/v1 api_key: EMPTY model_name: your-model temperature: 0.2 max_tokens: 4096 eval: tasks_dir: ./tasks results_dir: ./results sampling_times: 5 timeout_seconds: 6007.3 主流程评测脚本的核心逻辑可以按下面几个函数组织import json import time from pathlib import Path import yaml import requests def load_config(path): with open(path, r, encodingutf-8) as f: return yaml.safe_load(f) def call_llm(config, prompt): payload { model: config[model][model_name], messages: [{role: user, content: prompt}], temperature: config[model][temperature], max_tokens: config[model][max_tokens], } resp requests.post( f{config[model][base_url]}/chat/completions, jsonpayload, headers{Authorization: fBearer {config[model][api_key]}}, timeout300, ) resp.raise_for_status() return resp.json()[choices][0][message][content] def run_task(config, task_dir, sample_index): task_id ftask_{sample_index:03d} task_md task_dir / task.md prompt build_prompt(task_md.read_text(encodingutf-8)) all_scores [] for i in range(config[eval][sampling_times]): response call_llm(config, prompt) result apply_and_test(task_dir, response) all_scores.append(result) time.sleep(1) # 统计 passk 与平均分 summary summarize(all_scores) save_result(config[eval][results_dir], task_id, summary) print(json.dumps(summary, ensure_asciiFalse, indent2))apply_and_test 函数负责把模型输出解析成 patch应用后执行 pytest。这个函数需要根据你的测试目录和仓库结构做调整没有统一写法。7.4 结果输出建议每个任务单独保存一个 JSON 结果{ task_id: task_001, model: your-model, sampling_times: 5, pass_at_1: 0.6, pass_at_5: 1.0, avg_target_pass: 0.8, avg_regression_rate: 1.0, avg_token_cost: 12000 }批量跑完之后再用一个汇总脚本把所有 JSON 合并成总表按任务类型和难度排序输出。8. 资源占用与性能观察HarnessOpt-Bench 这类评测对本地计算资源的要求极低真正的开销集中在 LLM 推理侧。如果你使用云端 API 模型本机只需要关心三个指标单任务平均耗时单任务平均 token 消耗采样次数与成本之间的关系。如果你使用本地模型重点关注显存占用和推理并发。以常见的 7B 到 14B 模型为例量化后显存占用通常在 6GB 到 16GB 之间但具体数值取决于模型精度、上下文长度和并发数不能一概而论。这里给出一套通用的性能观察方法在评测脚本中记录每个任务的开始时间和结束时间记录每次 LLM 调用的 token 使用量通过 nvidia-smi 或 vLLM 的监控接口观察显存峰值如果并发跑多个评测任务注意 API 限流和本地推理队列堆积。评测一次完整的 Harness 优化任务通常比普通代码生成的 token 消耗要高因为 prompt 里要包含完整的 Harness 代码快照。上下文越长推理延迟越高。如果发现单任务耗时异常先从 prompt 长度和模型上下文窗口是否被占满这两个方向排查。9. 常见问题与排查方法以下是运行 Harness 优化评测时最常遇见的几类问题整理成排查表问题现象可能原因排查方式解决方案模型输出大量解释文字没有 patchprompt 未明确输出格式查看原始模型响应在 prompt 中强约束“只输出 unified diff”必要时做后处理截取补丁能生成但应用失败代码快照与模型看到的版本不一致对比 prompt 中的代码和仓库实际内容统一从同一目录读取代码避免格式转换目标测试通过但回归测试失败模型修改范围过大查看 diff 与回归用例的关联在 prompt 中提示“尽量最小化修改”同一任务多次采样结果波动大采样温度过高或任务描述有歧义检查温度参数和任务文本降低 temperature或增强任务描述API 调用超时上下文过长或服务端限流查看调用日志和响应码缩短代码快照、增加重试逻辑本地推理显存溢出并发任务过多或上下文超长观察 nvidia-smi 日志降低并发数改用量化模型测试跑完但没有任何断言验证用例设计不完整检查测试文件补充目标断言和回归断言评测结果可复现性差测试环境依赖不一致检查运行环境和依赖版本使用容器或固定依赖版本如果你拿到的 HarnessOpt-Bench 官方数据已经做完了大部分数据清洗上面的问题可能不会全部出现。但如果你是自建评测集排序和边界情况处理就要提前设计好。10. 最佳实践与使用建议跑 Harness 优化评测建议遵循几条工程化原则。第一先跑通一条最小样本。不要一上来就批量跑几十个任务。先用一个任务验证评测脚本的完整链路读取任务、组装 prompt、调用模型、解析 patch、应用 patch、执行测试、保存结果。全链路跑通后再扩量。第二统一 prompt 模板。模型对 Harness 代码的修改质量和 prompt 里给出的上下文高度相关。建议把“任务目标、代码快照、修改限制、输出格式、回归要求”固定成一套模板避免不同任务之间提示词风格漂移。第三拆分目标测试和回归测试。所有验证用例都放在一起容易掩盖回归问题。建议在评测数据目录上就完成拆分后续统计指标时也更清晰。第四多次采样取统计值。Harness 优化任务的随机性不低单次采样很难代表模型真实能力。合理做法是每个任务采样 5 次或更多同时报告 pass1 和 passk。第五关注 token 成本和延迟。这类评测的 token 消耗比普通代码评测更高因为 prompt 里要放整个 Harness 项目代码。成本超预算时优先裁剪非关键文件和注释。第六注意数据合规。如果你要评测的 Harness 代码来自公司内部仓库注意脱敏。评测结果如要对外发布确保不泄露内部架构细节和敏感配置。第七不要把评测结果当作模型绝对质量的全部证据。HarnessOpt-Bench 只反映模型在“修改 Agent 运行框架”这一能力维度上的表现。生产环境是否可用还要结合真实业务场景做小范围灰度验证。11. 总结HarnessOpt-Bench 这类工作最值得关注的点是把“修改 Agent 系统自身”这件事从普通代码生成任务里剥离出来单独评测。它让你看清一个事实代码写得好不等于框架改得稳。前者只要满足输入输出约束后者还要面对回归、全局状态和运行成本的约束。如果你要验证一个模型在 Agent 工程维护上的能力最先做的是拿到官方数据后跑一遍目标测试通过率和回归率重点观察模型是否只改目标逻辑而不动周边代码。最容易踩的坑是 prompt 里放人放太多代码导致模型定位不到核心修改点以及回归测试设计不足导致“改坏了却没被测出来”。后续你可以继续扩展的方向包括把评测结果与真实 Agent 生产指标联动观察 Harness 修改对任务完成率、token 成本、延迟的影响也可以设计更难的任务比如让模型在多个相互冲突的 Harness 需求之间做取舍。这两个方向都比单纯刷一个通过率数字更有工程价值。