1. 从“能跑”到“好用”之间隔着一条叫 Harness 的河如果你最近半年在折腾 Coding Agent大概率会有一种很割裂的体验Demo 阶段惊艳得不行一旦扔进真实项目里它就开始胡言乱语、乱改文件、跑一半卡死、把好好的代码库搅成一锅粥。问题往往不在模型本身而在模型外面那层“壳”——也就是现在圈子里被反复念叨的Harness。这篇东西想聊的就是Vibe Coding 的最后一公里当模型能力已经够用怎么通过 Harness 这一层的工程化调优把一个“玩具级”的 Coding Agent 打磨成能在生产环境里稳定干活的工具。关键词里出现的 Coding Agent、Harness、Vibe Coding、调优基本就是本文的四根柱子。我会把 Harness 和 Agent 的区别讲清楚把调优的完整链路拆开把踩过的坑一个个摆出来最后给一套可以直接抄的配置思路。先说清楚适合谁看。如果你只是想让 AI 帮你写个脚本、改个函数那随便一个对话式工具就够了不需要 Harness。但如果你在做的是让 Agent 自动读代码库、定位 bug、改多个文件、跑测试、提交结果并且希望这个过程可复现、可观测、可回滚——那你绕不开 Harness 工程。这篇文章面向的就是后者无论你用的是哪家的模型底层逻辑是通用的。我自己的体感是很多人把 80% 的精力花在“换更强的模型”上却只花 20% 在 Harness 上结果就是效果提升越来越边际。反过来把 Harness 调好同一个模型的表现能有肉眼可见的跃迁。这就是“最后一公里”的含义——路已经修了 99%最后那 1% 决定了你能不能真正到达终点。2. Harness 和 Agent 到底差在哪一次把概念掰开2.1 模型、Agent、Harness 的三层关系先把概念理清楚不然后面全是糊涂账。我习惯用“开车”来类比模型Model是发动机提供动力决定上限。Agent是驾驶员负责决策——往哪开、什么时候刹车、遇到岔路怎么选。Harness是整辆车的底盘、方向盘、仪表盘和刹车系统它决定了驾驶员的操作能不能被准确执行、状态能不能被感知、出事了能不能兜住。很多人把 Agent 和 Harness 混为一谈其实它们职责完全不同。Agent 关心的是“下一步做什么”Harness 关心的是“这一步怎么安全、准确、可观测地执行以及执行完的结果怎么反馈回去”。一个负责策略一个负责执行与反馈的闭环。举个具体例子。Agent 决定“我要读取src/utils/parser.py这个文件”。这句话本身是策略。但真正去读文件、处理编码、截断超长内容、把结果格式化成模型能吃的结构、记录这次读取的耗时和 token 消耗——这些全是 Harness 的活。Agent 说“我要跑测试”Harness 负责在沙箱里起进程、设超时、抓 stdout/stderr、解析测试报告、把失败用例结构化返回。2.2 为什么 Harness 决定了生产可用性Demo 能跑是因为 Demo 场景里一切顺利文件不大、路径简单、没有并发、没有超时、模型一次就答对。生产环境恰恰相反全是边界情况。Harness 的价值就体现在这些边界上维度没有 Harness 的裸 Agent有成熟 Harness 的 Agent文件操作直接读写容易越界路径白名单 沙箱 变更预览命令执行无超时卡死就挂超时控制 资源限制 输出截断上下文一股脑塞爆 token分层检索 动态裁剪 摘要压缩错误处理报错就崩无法恢复重试 降级 断点续跑可观测黑盒出问题靠猜全链路 trace 每步耗时与 token可复现每次结果不一样固定种子 快照 回放这张表基本就是“玩具”和“生产级”的分水岭。你会发现模型能力在这张表里几乎没出现——因为当模型够用之后差距全在 Harness 上。2.3 Vibe Coding 语境下的特殊要求Vibe Coding 这个词本身就带着一种“凭感觉、快速迭代、边写边调”的气质。它追求的是心流你描述意图Agent 快速给出可运行的代码你看着结果继续微调。这种模式下Harness 的要求和传统批处理式 Agent 不太一样反馈要快每一步的延迟都要压到最低否则心流断了。变更要可见Agent 改了什么必须一眼能看清否则不敢让它继续。回滚要容易Vibe 意味着试错试错意味着要能一键撤销。上下文要连贯多轮迭代之间Agent 得记得住之前的设计决策。这四点没有一个是模型能单独搞定的全是 Harness 的工程活。所以我说Vibe Coding 的最后一公里本质是 Harness 的调优。3. 效果调优的完整链路从输入到落地的六个环节调优不是调一个参数而是一条链路。我把它拆成六个环节每个环节都有独立的调优点也都有各自的坑。3.1 上下文构建决定 Agent 看到什么Agent 的表现七成取决于它看到了什么。上下文构建是 Harness 里最容易被低估、也最值得投入的部分。核心矛盾是代码库太大塞不进上下文但塞得太少Agent 又会缺信息乱猜。我的做法是分层第一层任务相关文件全文。通过关键词、符号引用、最近修改记录定位到最相关的 3-5 个文件给全文。第二层接口与签名摘要。把相关模块的函数签名、类定义、类型声明抽出来让 Agent 知道“有什么可用”。第三层项目级约定。比如代码风格、目录结构、依赖清单、构建命令这些用固定模板注入不占太多 token 但极其关键。这里有个反直觉的经验不是给得越多越好。我实测过把整个src目录塞进去Agent 反而更容易迷失因为它分不清哪些是当前任务相关的。精准的 5 个文件效果远好于模糊的 50 个文件。提示上下文构建里最值钱的是“检索质量”不是“模型能力”。花时间把检索做好比换模型划算得多。3.2 工具设计Agent 的手脚怎么长Agent 能做什么取决于你给它哪些工具。工具设计有两个极端给太少Agent 干不了活给太多Agent 选择困难还容易误用。我的原则是最小可用工具集 语义清晰。一个 Coding Agent 的核心工具通常就这几个read_file读文件支持行范围。write_file写文件必须带变更预览。search按关键词或正则搜索代码库。run_command执行命令带超时和沙箱。list_dir列目录帮助 Agent 建立空间感。工具的描述description比工具本身还重要。模型是靠描述来决定用哪个工具的。描述里要写清楚什么时候用、参数含义、返回什么、有什么限制。我见过太多 Harness 的工具描述写得含糊导致 Agent 该用search的时候去read_file一个个翻效率极低。3.3 执行沙箱让 Agent 的手脚有边界生产环境里Agent 执行命令必须被关在笼子里。这不是不信任模型而是工程常识——任何自动化系统都需要边界。沙箱要解决几件事文件系统隔离Agent 只能操作指定工作目录不能碰系统文件。网络限制默认禁止外联需要时白名单放行。资源限制CPU、内存、执行时间都要有上限。超时控制任何命令超过阈值直接杀掉返回超时错误让 Agent 决策。超时这个点特别关键。我踩过的坑是Agent 跑了一个会阻塞的命令比如等待输入的交互式程序没有超时控制整个流程就挂在那里token 还在烧。后来我给所有命令加了硬超时默认 60 秒长任务单独配置问题就解决了。3.4 反馈回路Agent 怎么知道自己做对了这是调优里最见功力的地方。Agent 执行完一个动作Harness 要把结果“翻译”成模型能理解、能据此决策的反馈。反馈分三类成功反馈命令退出码 0输出正常。要告诉 Agent“成功了”并附上关键输出。失败反馈退出码非 0或抛异常。要把错误信息结构化最好能定位到行号和原因。模糊反馈命令成功了但结果不符合预期比如测试通过了但覆盖率下降。这类最难需要 Harness 有额外的校验逻辑。我的经验是反馈要短、要准、要可操作。不要把几百行日志原样丢回去要提取关键信息。比如测试失败只返回失败的用例名、断言差异、相关代码行而不是整个测试输出。3.5 重试与降级出错了怎么优雅地继续生产环境里失败是常态。Harness 必须有重试和降级策略。重试不是简单重跑。要区分错误类型瞬时错误网络抖动、临时锁直接重试指数退避。逻辑错误代码写错、参数不对不能盲目重试要把错误反馈给 Agent 让它修正。致命错误权限不足、依赖缺失降级或终止给出明确提示。我一般配置 3 次重试上限超过就停下来把完整上下文交给人工或上层决策。无限重试是最危险的设计会烧钱还会掩盖真正的问题。3.6 可观测性看不见的东西没法调优最后但同样重要的是可观测性。你要能回答这些问题这次任务花了多少 token每一步耗时多少Agent 在哪一步卡住了哪个工具调用最频繁我的做法是给每次任务生成一条完整的 trace记录每个步骤的输入、输出、耗时、token 消耗、工具调用。有了这些数据调优才有依据而不是凭感觉。4. 实测中最容易翻车的五个坑这一节全是血泪。我把调优过程中反复出现的问题整理出来每个都给出排查思路和修复方案。4.1 坑一上下文污染导致 Agent “精神分裂”现象Agent 前几轮表现正常突然开始引用不存在的文件、编造函数名、把不同任务的代码混在一起。根因上下文里混入了过期或无关的信息。常见来源是多轮对话没有做上下文清理旧任务的残留信息一直挂着。排查链路先打印每一轮实际送给模型的完整上下文逐条检查有没有不该出现的内容。我当时的做法是把上下文 dump 成文件人工过一遍很快就发现上一轮的文件内容没被清掉。修复给上下文加生命周期管理。任务切换时清理任务级上下文只保留项目级约定。同时给每段上下文打标签方便追踪来源。4.2 坑二工具描述含糊导致调用错乱现象Agent 频繁用错工具比如该搜索的时候去读文件该写文件的时候去执行命令。根因工具描述写得太抽象模型无法区分使用场景。排查链路统计工具调用分布看哪些工具被误用。我当时的统计显示read_file被调用的次数异常高远超合理范围说明 Agent 在用它替代搜索。修复重写工具描述明确“什么时候用这个工具”“什么时候不要用”。比如search的描述里加上“当你不确定文件位置时优先用这个而不是逐个读文件”。改完之后误用率明显下降。4.3 坑三超时缺失导致流程假死现象任务跑到一半不动了日志停在某个命令上token 还在缓慢消耗。根因执行了一个阻塞命令没有超时控制。排查链路看 trace 里最后一条记录定位到具体命令。我遇到的是 Agent 跑了一个需要交互输入的命令进程一直等 stdin。修复所有命令加硬超时默认 60 秒。同时给命令执行加上“非交互模式”标志避免需要输入的命令被误触发。4.4 坑四反馈信息过载淹没关键信号现象Agent 收到一大堆日志后抓不住重点反复在无关细节上打转。根因Harness 把原始输出直接丢回给模型没有做信息提取。排查链路对比“原始输出”和“结构化反馈”两种模式下 Agent 的决策质量。差异非常明显。修复写一层输出解析器把命令输出转成结构化结果。测试输出提取失败用例构建输出提取错误行日志输出提取 ERROR 级别。只把关键信息回传。4.5 坑五重试策略不当导致成本失控现象某个任务反复重试token 消耗飙升但始终没成功。根因重试没有区分错误类型逻辑错误也在盲目重试。排查链路看 trace 里的重试记录发现同一个逻辑错误被重试了十几次。修复给错误分类只有瞬时错误才自动重试逻辑错误直接反馈给 Agent 修正致命错误立即终止。重试上限设为 3 次。5. 一套可以直接抄的 Harness 配置思路讲了这么多原理和坑最后给一套可落地的配置框架。这不是某个具体产品的配置而是通用的设计模板你可以按自己用的工具去映射。5.1 上下文策略配置context: max_tokens: 100000 layers: - name: task_files strategy: relevance_rank top_k: 5 full_text: true - name: interface_summary strategy: symbol_extract max_items: 50 - name: project_convention strategy: static_template content: [style_guide, dir_structure, build_cmd] lifecycle: clear_on_task_switch: true keep_project_level: true核心思路分层、限量、有生命周期。top_k: 5是我实测下来比较稳的值再多收益递减。5.2 工具集配置tools: - name: read_file desc: 读取指定文件的指定行范围。不确定文件位置时先用 search。 timeout: 10 - name: write_file desc: 写入文件必须先展示变更预览。 require_preview: true - name: search desc: 按关键词或正则搜索代码库。定位文件时优先使用。 max_results: 20 - name: run_command desc: 执行 shell 命令。禁止交互式命令。 timeout: 60 sandbox: true每个工具的描述都明确写了“什么时候用”这是降低误用的关键。5.3 反馈与重试配置feedback: parse_output: true extract: test: [failed_cases, assertion_diff] build: [error_lines] log: [error_level] retry: max_attempts: 3 backoff: exponential retryable_errors: [timeout, network, lock] non_retryable_errors: [syntax, logic, permission]这套配置的核心是“分类处理”。不同错误走不同路径避免一刀切。5.4 可观测性配置observability: trace_level: step record: [input, output, duration, tokens, tool_calls] export: jsonl retention_days: 30trace 一定要落到文件方便事后分析。我习惯用 jsonl 格式一行一条记录好解析也好过滤。6. 调优之外几个容易被忽略的工程习惯技术配置之外有些工程习惯对最终效果影响巨大但很少被写进文档。第一给 Agent 写“项目说明书”。在项目根目录放一个约定文件写清楚构建命令、测试命令、代码风格、目录含义。Harness 每次启动时把它注入上下文。这一招对提升 Agent 的“项目感”立竿见影比任何 prompt 技巧都管用。第二变更必须可预览、可回滚。Vibe Coding 的精髓是快速试错但试错的前提是能撤销。我给所有写操作加了变更预览和快照Agent 每次改文件前先展示 diff确认后才落盘落盘前自动备份。这样即使 Agent 改错了也能一键回到上一个状态。第三把“失败”当成一等公民。很多 Harness 只关心成功路径失败路径草草了事。但生产环境里失败才是常态。我花在失败处理上的时间比成功路径多得多。错误分类、结构化反馈、优雅降级这些才是稳定性的来源。第四定期回放历史 trace。我会定期把过去的 trace 拿出来重放看 Agent 的决策是否合理有没有可以优化的地方。这个过程经常能发现新的调优点比凭空想有效得多。第五控制单次任务的规模。Agent 一次任务做得越多出错概率越高。我倾向于把大任务拆成小步骤每步都有明确的输入输出和验证点。这样即使某步失败影响范围也可控。7. 关于“最后一公里”的一点个人体会折腾 Harness 这段时间我最大的感受是模型能力的提升是线性的Harness 的优化是非线性的。同一个模型Harness 调好前后效果差距可能是几倍。而且这种优化是可积累的——你今天调好的上下文策略、工具描述、反馈机制换一个模型依然适用。另一个体会是调优这件事没有终点。每次我以为已经调得差不多了回放 trace 总能发现新的问题。但这恰恰是它有意思的地方——它不像换模型那样一锤子买卖而是一个持续打磨的过程每一点改进都能被量化地看到。如果你也在做 Coding Agent我的建议是先把 Harness 的基础设施搭扎实再谈模型选型。上下文、工具、沙箱、反馈、重试、可观测这六块每一块都值得投入。等这些稳了你会发现所谓“最后一公里”其实是最值得走的那一公里。