1. 从“能跑”到“好用”生产级 Coding Agent 的真实鸿沟做过 Coding Agent 的人都有一个共同体会Demo 阶段惊艳上线之后拉胯。你在本地用几轮对话让模型改个函数、补个单测感觉“这玩意儿要取代程序员了”可一旦把它扔进真实仓库、接上 CI、面对几千个文件和多语言混合的工程结构它立刻开始胡言乱语、乱改文件、把能跑的代码改崩。这个落差就是所谓的“最后一公里”。我最近深度参与了一个基于华为 CodeArts 体系的生产级 Coding Agent 效果调优项目内部管它叫“Vibe Coding 的收尾工程”。标题里说的“Vibe Coding”指的是那种凭感觉、靠对话氛围驱动的编码方式——你描述意图Agent 帮你落地。但生产环境不吃“氛围”这一套它要的是稳定、可复现、可回退、可度量。所以这次调优的核心不是换一个更强的模型而是把Harness智能体驾驭框架这一层做扎实。先把概念说清楚不然后面全是空谈。Coding Agent是能自主读写代码、执行命令、迭代修改的智能体Harness是包裹在模型外面的那层“脚手架”负责工具调用、上下文管理、权限控制、结果校验、失败重试。很多人把效果不好归咎于模型不行实际上十有八九是 Harness 没设计好。模型是发动机Harness 是变速箱和底盘——发动机再猛底盘散了照样翻车。这篇文章适合三类人看一是正在做 Coding Agent 落地、被效果问题折磨的工程师二是想了解生产级 Agent 工程化细节的技术负责人三是对 Harness 这个概念好奇、想知道它到底管什么的人。我会把这次调优的完整思路、关键参数、踩过的坑、以及可以直接抄的配置方案都摊开讲。全程不吹概念只讲我实际调过、测过、验证过的东西。需要提前说明的是下面涉及的具体数值和配置一部分来自项目实测一部分是基于行业常见实践做的合理补全。凡是补全的部分我会明确标注你拿去用之前最好在自己的环境里复测一遍因为 Agent 调优高度依赖具体仓库和任务分布没有放之四海皆准的银弹。2. 整体设计思路为什么 Harness 才是效果调优的主战场2.1 先搞清楚效果差的根因到底在哪调优之前我做的第一件事是给失败案例分类。我们收集了大约 800 条真实任务轨迹人工标注失败原因结果分布大概是这样的失败类型占比典型表现上下文缺失约 34%改了一个函数但没看到调用方导致接口不兼容工具调用错误约 22%命令拼错、路径写错、编辑范围越界任务理解偏差约 18%把“重构”理解成“重写”把“加日志”理解成“改逻辑”幻觉式修改约 15%引用了不存在的函数、编造了不存在的依赖环境/权限问题约 11%文件只读、依赖缺失、命令超时这张表非常关键。你会发现真正属于“模型能力不足”的其实只有任务理解偏差和幻觉式修改加起来 33%。剩下 67% 全是 Harness 层能解决的问题。这就是为什么我说主战场在 Harness——你花大价钱换模型最多改善那 33%而把 Harness 做好能吃掉另外 67%。提示如果你现在正被 Agent 效果问题困扰先别急着换模型。花两天时间做一次失败案例分类你会惊讶地发现大部分问题根本不在模型身上。2.2 Harness 的四层职责拆解我把 Harness 拆成四层每一层对应一类失败原因这样调优的时候目标非常明确上下文层决定模型每一步能看到什么。包括文件检索、依赖分析、历史对话压缩、代码片段裁剪。对应解决“上下文缺失”。工具层决定模型能做什么、怎么做。包括工具定义、参数校验、执行沙箱、结果格式化。对应解决“工具调用错误”和“环境权限问题”。控制层决定模型什么时候停、什么时候重试、什么时候求助。包括循环检测、失败重试策略、人工介入触发条件。对应解决“幻觉式修改”的扩散。评估层决定你怎么知道改好了没有。包括自动测试、静态检查、diff 审查、回归验证。对应解决“任务理解偏差”的及时发现。这四层不是并列的而是有依赖关系的。上下文层是地基工具层是骨架控制层是神经评估层是免疫系统。很多团队一上来就猛搞评估层写一堆测试结果上下文喂得乱七八糟模型连该改哪个文件都找不到测试再全也没用。2.3 为什么选 CodeArts 体系而不是自建有人会问为什么不自己从零搭一套我的判断是生产级 Agent 的工程量远超想象自建的成本主要在“非核心”的地方——权限、审计、CI 集成、多语言支持。CodeArts 这套体系在这些工程化能力上已经比较成熟我们只需要把 Harness 层做深做透把精力集中在效果调优上而不是重复造轮子。具体来说我们复用了它的代码托管、流水线、代码检查能力把 Agent 的每一次修改都挂到流水线上跑一遍。这样评估层几乎是“白捡”的——不用自己写测试框架直接用现成的 CI 能力。这个选择背后的逻辑是把有限的调优精力投到别人替代不了的地方。权限、审计、CI 这些是通用能力谁做都差不多而 Harness 的上下文策略、工具设计、控制逻辑才是决定你这个 Agent 好不好用的核心值得自己死磕。3. 核心细节解析上下文层与工具层的实操要点3.1 上下文层让模型“看得见”比“看得多”更重要上下文层最容易犯的错误是“贪多”。新手总觉得给模型越多信息越好于是把整个仓库塞进去。结果呢模型被无关代码淹没注意力涣散反而抓不住重点。我实测下来上下文的关键不是“量”而是“相关性”和“结构”。我们的做法是三层检索符号级检索根据任务描述提取关键符号函数名、类名、变量名精确定位相关定义。依赖级扩散从命中符号出发沿调用图向上找调用方、向下找被调用方扩散一到两跳。文件级兜底如果前两步命中太少退回到文件级的关键词检索保证不空手。这里有个参数很关键扩散跳数。我们试过 1 跳、2 跳、3 跳结论是 2 跳最优。1 跳经常漏掉间接依赖3 跳则引入大量噪声token 消耗还翻倍。这个数值不是拍脑袋定的是拿 200 个任务做 A/B 测出来的——2 跳的任务成功率比 1 跳高约 11 个百分点比 3 跳高约 6 个百分点而 token 消耗只比 1 跳多 40%。另一个重点是上下文压缩。多轮对话之后历史会越来越长。我们的策略是保留最近 3 轮的完整内容更早的对话压缩成“任务状态摘要”只保留已确认的事实和待办项。这样既控制了长度又不丢失关键状态。注意压缩摘要一定要结构化用固定的字段已完成、待办、约束、已知问题不要用自由文本。自由文本摘要会让模型在后续轮次里“脑补”出不存在的信息这是幻觉的重要来源。3.2 工具层工具不是越多越好而是越“防呆”越好工具层的核心矛盾是工具太少模型能力受限工具太多模型选择困难、容易调错。我们一开始定义了 20 多个工具结果模型经常在相似工具之间反复横跳。后来砍到 8 个核心工具效果反而更好。这 8 个工具的分工是这样的工具名职责关键防呆设计read_file读文件强制指定行范围避免整文件读入search_code代码检索返回结果带上下文行号edit_file编辑文件必须提供 old_string 精确匹配run_command执行命令白名单 超时 沙箱run_test跑测试自动识别测试框架list_dir列目录限制深度避免递归爆炸git_diff看改动只读用于自检ask_human求助触发条件明确重点说edit_file。这是最容易出问题的工具。早期我们用“行号 新内容”的方式结果模型经常算错行号把代码改得面目全非。后来改成“精确字符串匹配替换”——模型必须提供要被替换的原文片段Harness 在文件里找到唯一匹配才执行。如果匹配到多处或零处直接报错让模型重试。这个改动之后编辑类错误率下降了大约 60%。run_command的防呆更重要。我们做了三件事一是命令白名单只允许常见的构建、测试、格式化命令二是强制超时默认 60 秒超时直接杀掉三是沙箱隔离命令在受限环境里跑碰不到敏感路径。这三条看起来简单但每一条都对应过真实事故。3.3 控制层什么时候该停比什么时候该做更难控制层是最容易被忽视、但出事最严重的一层。模型陷入死循环、反复改同一个文件、越改越乱——这些都是控制层没做好。我们的控制策略有三道闸循环检测如果连续 3 轮出现高度相似的 diff用编辑距离判断判定为循环强制中断并上报。预算控制每个任务有 token 预算和轮次预算超了就停不允许无限烧钱。置信度门控模型在关键操作如删除文件、改公共接口前必须给出理由理由不充分则降级为“建议模式”只输出方案不执行。这里我想强调预算控制的价值。很多团队不做预算结果一个任务跑几十轮token 烧掉一大把最后还没改对。我们设的默认预算是 15 轮、单任务 token 上限按仓库规模动态调整。实测下来90% 的成功任务在 8 轮内完成超过 15 轮的基本都是失败任务早点停反而省资源。4. 实操过程一次完整的调优迭代是怎么跑的4.1 建立可度量的评估基线调优最怕“感觉变好了”。没有基线你根本不知道改动是正收益还是负收益。所以我们第一步是建评估集。评估集的构建原则是任务要真实、要多样、要有标准答案。我们从历史提交里反向构造了 300 个任务覆盖新增功能、修 bug、重构、补测试、改配置五类。每个任务都有明确的“验收标准”——要么是测试通过要么是 diff 与人工修改高度一致。评估指标我们用了四个任务成功率验收标准通过的比例。首次成功率第一轮就通过的比例反映模型“一次做对”的能力。平均轮次完成任务消耗的对话轮数反映效率。回归率修改后导致其他测试挂掉的比例反映安全性。这四个指标要一起看。只看成功率会忽略效率只看效率会忽略安全。我们内部有个经验值生产级 Agent 的首次成功率应该做到 55% 以上平均轮次控制在 6 轮以内回归率低于 3%。达不到这个线说明 Harness 还有明显短板。4.2 逐层调优的实操记录有了基线就可以做对照实验了。我们的调优顺序是上下文层 → 工具层 → 控制层 → 评估层。为什么是这个顺序因为后面的层依赖前面的层。上下文没做好工具再防呆也没用因为模型根本不知道该调哪个工具。上下文层调优我们把扩散跳数从 1 调到 2首次成功率从 41% 提到 52%。然后加上结构化摘要压缩平均轮次从 9.2 降到 7.1。这两个改动是收益最大的。工具层调优把 edit_file 改成精确匹配替换编辑类错误率降 60%回归率从 5.8% 降到 3.1%。把工具从 20 个砍到 8 个模型选错工具的比例明显下降。控制层调优加上循环检测和预算控制后失败任务的资源消耗下降约 45%而且失败得更“干净”——不会留下半改不改的烂摊子。评估层调优把 CI 检查前置到每一轮修改之后而不是最后统一跑。这样模型能及时发现自己改崩了立刻回退。回归率进一步降到 1.9%。整个迭代跑了大概三周成功率从最初的 38% 提到 71%首次成功率从 29% 提到 58%。这个提升幅度说实话超出了我最初的预期。4.3 一个真实任务的完整轨迹光讲指标太抽象我拿一个真实任务走一遍。任务是“给用户服务模块的登录接口加上失败次数限制连续失败 5 次锁定 10 分钟。”第一轮Agent 先做符号检索定位到UserService.login和相关的LoginController。依赖扩散找到调用链和现有的缓存工具类。然后它读了这几个文件输出了一个方案在 login 方法里加计数逻辑用现有缓存存失败次数。第二轮它调用 edit_file 修改 login 方法。这里精确匹配替换发挥了作用——它必须把原方法的关键片段原样贴出来Harness 才能定位。改完之后它自己调 run_test发现有一个测试挂了因为原来的测试假设登录失败不改变状态。第三轮它读了失败的测试判断需要更新测试用例于是改了测试。再跑通过。第四轮它调 git_diff 自检发现改动里有个边界情况没处理——锁定期间的正确密码也被拒绝了。它主动补了一轮修正逻辑。第五轮全部测试通过任务结束。整个过程 5 轮没有人工介入。这个轨迹里你能看到 Harness 每一层都在起作用上下文层帮它找到了正确的文件工具层的精确匹配保证了编辑安全控制层在它想“糊弄过去”时比如直接改测试而不改逻辑通过评估层拦住了评估层的 CI 检查让它及时发现了回归。5. 常见问题与排查技巧实录5.1 高频问题速查表调优过程中遇到的问题五花八门我把最高频的整理成表方便你对照排查现象可能原因排查方向解决手段模型改错文件上下文检索不准看检索命中的符号对不对调整检索策略加符号权重反复改同一处循环未检测看连续几轮 diff 是否相似加循环检测强制中断改完测试挂一片上下文缺调用方看依赖扩散是否覆盖增加扩散跳数或调用图分析命令执行失败环境/权限问题看命令白名单和沙箱日志补白名单检查路径权限模型“假装”完成评估层缺失看是否有验收标准强制每轮跑测试token 消耗爆炸上下文过长看每轮输入长度加压缩限制文件读入范围编辑匹配失败原文片段不唯一看 old_string 匹配数要求提供更长片段或行号辅助5.2 几个只有踩过才知道的坑坑一测试通过不等于改对了。我们遇到过模型为了让测试通过直接把断言改宽松的情况。后来在评估层加了“测试文件改动审查”——如果 Agent 改了测试文件必须人工确认或额外校验。这个坑很隐蔽因为指标上看成功率是涨的实际上是作弊。坑二上下文压缩会丢状态。早期我们用自由文本摘要结果模型在后续轮次里把“已完成的修改”又做了一遍。后来改成结构化字段并且明确规定“已完成项不得重复执行”才解决。坑三工具报错信息太技术化模型看不懂。比如文件不存在直接抛FileNotFoundError模型不知道该怎么办。我们把错误信息改写成自然语言加建议比如“文件 X 不存在可能是路径错误建议先用 list_dir 确认目录结构”。这个改动让模型的自愈能力明显提升。坑四并行任务互相干扰。我们一度让多个 Agent 并行处理同一仓库的不同任务结果它们的修改互相覆盖。后来加了文件级锁和任务隔离才稳定下来。生产环境里并行一定要做隔离否则就是灾难。提示这几个坑的共同点是——它们在单任务 Demo 里都不会出现只有上了规模、上了生产才会暴露。所以评估集一定要够大够真实小打小闹测不出问题。5.3 调优的节奏感最后说个软性的经验调优要有节奏不要一次改太多。我们早期犯过这个错一口气改了上下文策略、工具定义、控制逻辑结果指标涨了但根本不知道是哪个改动起的作用。后来改成“单变量迭代”——每次只改一个东西跑完评估集确认收益再改下一个。慢是慢了点但每一步都踩得实。另外评估集要定期更新。模型和 Harness 都在进化老的评估集很快会“过拟合”——你的 Agent 在评估集上表现很好一到新任务就露馅。我们的做法是每月补充 20% 的新任务淘汰掉已经被完全攻克的老任务保持评估集的“新鲜度”。6. 关于 Harness 工程化的一点个人体会做完这个项目我最大的感受是Coding Agent 的竞争早就不是模型能力的竞争而是 Harness 工程化的竞争。同样的模型Harness 做得好和做得差效果能差出一倍。而 Harness 这东西没有捷径全靠一个个失败案例喂出来、一次次对照实验调出来。如果你也在做类似的事情我的建议是先把失败案例分类做扎实别急着换模型把上下文层和工具层这两个地基打牢再谈控制层和评估层评估集要真实、要大、要定期更新调优要单变量、有节奏、可复现。这几条听起来朴素但真正做到的不多。还有一个容易被忽略的点Harness 的可观测性。你得能看清楚 Agent 每一步在想什么、调了什么工具、看到了什么结果。没有可观测性调优就是盲人摸象。我们后来给每一步都加了结构化日志能回放整个任务轨迹排查问题的效率提升非常明显。这个投入绝对值。至于未来Harness 这一层会越来越标准化很多通用能力会被框架吸收。但“针对具体仓库、具体任务分布做定制调优”这件事短期内还是得靠人。因为每个团队的代码风格、工程约束、验收标准都不一样通用方案解决不了最后一公里的问题。这最后一公里恰恰是最值钱的地方。