企业官网建设流程全解析

1. 从“能跑”到“好用”之间，隔着一条叫 Harness 的河

Vibe Coding 这个词从去年火到现在，很多人已经过了“哇，AI 能写代码”的新鲜期。真正把 Coding Agent 塞进日常研发流程的人，都会撞上同一堵墙：Demo 里三分钟生成一个贪吃蛇很惊艳，但让它在一个有十年历史、几十万行代码、依赖关系盘根错节的生产仓库里改一个真实需求，它就开始胡言乱语——改错文件、漏掉边界、跑不通测试、把无关模块一起重构掉。

问题往往不出在模型本身。你把同一个模型放进一个裸的对话框，和放进一个精心设计的 Harness 里，产出质量能差出一个数量级。Harness 这个词直译是“马具”“挽具”，放在 Coding Agent 语境里，它指的是包裹在模型外面那一整套工程化框架：怎么给模型喂上下文、怎么约束它的动作空间、怎么验证它的输出、怎么在失败时回滚和重试。模型是马，Harness 是缰绳、鞍具和跑道。马再壮，没有合适的挽具，也拉不动生产级的车。

这篇实录讲的就是“最后一公里”的事。前面九十公里，是选模型、搭环境、跑通第一个 Agent 循环，网上教程一抓一大把。最后十公里，是把一个能跑的 Coding Agent 调优到在生产环境里稳定交付——这才是真正卡住绝大多数团队的地方。我会围绕华为 CodeArts 体系下的生产级实践，把 Harness 工程的核心思路、调优手段、踩过的坑，尽可能掰开揉碎讲清楚。不管你现在用的是 Claude Code、DeepSeek Harness 还是自研的 Agent 框架，这套调优逻辑都是通用的。

适合谁看？如果你已经能让 Agent 跑起来，但产出质量忽高忽低、不敢让它碰核心代码、每次都要人工大改，那这篇就是写给你的。如果你还在纠结怎么安装、怎么配 API Key，也可以看，但重点建议放在第二、三章的工程思路上，那些才是决定成败的东西。

2. Harness 工程到底是什么：把模型关进一个“可验证的笼子”

2.1 模型能力的天花板，不等于系统能力的天花板

先纠正一个特别普遍的认知偏差。很多人调优 Coding Agent 的第一反应是“换个更强的模型”。换模型有用，但边际收益递减得很快。我做过一组对比：同一个中等规模的重构任务，用同一个模型，只改 Harness 设计，任务成功率从 40% 出头拉到了 85% 以上。模型没变，变的只是它看到什么、能做什么、做完之后谁来验收。

这背后的逻辑其实很朴素。大模型本质是一个“根据上下文预测下一个 token”的概率机器。它没有记忆，没有真正的执行反馈，也没有对代码库全局状态的理解。你给它一个模糊的指令，它就给你一个模糊的、看起来合理的输出。Harness 的作用，就是把这个概率机器约束到一个确定性的工程流程里：把模糊变具体，把开放变封闭，把“看起来对”变成“验证过对”。

打个比方。模型像一个极其聪明但完全没有工程纪律的实习生。你让他“优化一下这个模块”，他可能真的去优化了，也可能顺手把你不想动的地方也改了，还可能改完不跑测试就说“搞定了”。Harness 就是给这个实习生配的导师加 CI 流水线：任务拆解清楚、改动范围圈定、每步都有检查、交付前必须过测试。

2.2 Harness 的四个核心职责

把 Harness 拆开看，它主要在干四件事，这四件事构成了调优的四个抓手。

第一是上下文供给。模型在每一步需要看到什么？是整个仓库还是相关文件？是原始代码还是带注释的摘要？历史对话保留多少？检索用什么策略？这一块直接决定模型“知不知道自己在干什么”。上下文给少了，模型瞎猜；给多了，关键信息被淹没，还烧 token。

第二是动作空间约束。模型能执行哪些操作？只能读还是能写？能跑终端命令吗？能装依赖吗？能改配置文件吗？动作空间越大，能力越强，但失控风险也越高。生产环境里，动作空间的设计是一门取舍的艺术。

第三是输出验证。模型说改完了，怎么知道真的改对了？编译过了吗？测试过了吗？静态检查过了吗？改动是否符合代码规范？验证环节是 Harness 里最容易被忽视、却最影响最终质量的部分。

第四是失败恢复。模型改错了怎么办？是回滚重来，还是带着错误信息让它自我修正？重试几次？每次重试给什么新信息？这一块决定了 Agent 在长任务里的鲁棒性。

2.3 为什么“最后一公里”这么难

前面九十公里好走，是因为任务简单、环境干净、容错率高。最后一公里难，是因为生产环境的三个特性：规模大、耦合深、后果重。

规模大意味着上下文塞不下，必须做检索和裁剪。耦合深意味着改 A 可能影响 B，模型很难自己发现这种隐性依赖。后果重意味着不能试错，一次错误的提交可能污染主干分支。这三条叠加起来，就是为什么很多团队在 Demo 阶段信心满满，一上生产就翻车。

华为 CodeArts 这套体系的价值，恰恰在于它把软件工程的既有能力——代码检索、依赖分析、CI/CD、代码检查——和 Agent 循环缝合在了一起。Agent 不是孤立地写代码，而是在一个已经被工程化治理过的代码库里工作。这是它和裸用 Claude Code 最大的区别。

3. 上下文供给调优：让模型“看得准”比“看得多”重要

3.1 全量塞入是新手最容易犯的错

我见过太多团队的第一版 Harness，就是把整个相关目录的文件内容拼起来塞进 prompt。结果呢？模型要么被无关代码带偏，要么在长上下文里“迷失中间”，关键的那几行反而没注意到。更现实的问题是成本——一个中等仓库全量塞入，单次调用轻松几十万 token，跑几十轮下来账单能吓死人。

正确的做法是分层检索加动态裁剪。第一层用符号索引（函数名、类名、接口定义）快速定位相关实体；第二层用调用关系图扩展一跳或两跳的依赖；第三层才把真正相关的代码片段按优先级拼进上下文。每一层都有预算上限，超了就按相关性分数砍。

这里有个实操细节：相关性分数不能只看文本相似度。纯向量检索在代码场景里经常翻车，因为代码的语义相似和文本相似是两回事。一个函数叫processOrder，另一个叫handleTransaction，文本上不相似，但业务上可能强相关。所以检索要融合符号匹配、调用图距离、最近改动历史三个信号，加权打分。

3.2 上下文里必须有的“元信息”

光给代码不够。模型还需要知道一些“元信息”才能做出正确判断。我在实践里固定会塞进上下文的几类信息：

• 任务描述的结构化版本：不是一句自然语言，而是拆成“目标、约束、验收标准、禁止改动范围”四段。
• 代码库的约定：命名规范、错误处理模式、日志格式、测试框架。这些约定如果不在上下文里，模型就会按自己的习惯写，产出风格和仓库格格不入。
• 相关测试文件：让模型知道这个模块是怎么被测试的，它写出来的代码才更可能通过测试。
• 最近的提交历史：特别是相关文件的最近改动，能帮模型理解这块代码正在往哪个方向演进。

提示：元信息不要一次性全塞。按任务类型动态组装。重构任务重点给约定和测试，修 bug 任务重点给复现步骤和相关提交。

3.3 上下文窗口的“预算管理”

把上下文窗口当成一个有限预算来管理，是调优的关键思维。我的经验分配大致是这样：任务描述和约束占 10%，核心相关代码占 40%，依赖和调用方占 20%，测试文件占 15%，约定和历史占 10%，留 5% 给模型自己的推理空间。

这个比例不是死的，但核心原则是永远给模型留出“思考的余地”。如果上下文塞到 95% 满，模型几乎没有空间做推理，输出质量会断崖式下跌。我实测过，同样任务，上下文占用 70% 和 95% 两种情况下，前者的一次通过率明显更高。

还有一个反直觉的点：有时候删掉一些“看起来相关”的代码，效果反而更好。因为那些代码会干扰模型的注意力。判断标准是——这段代码如果模型看不到，它会不会做出错误决策？如果不会，那就别塞。

4. 动作空间设计：给 Agent 划出“能碰”和“不能碰”的红线

4.1 动作分级：从只读到全权限

动作空间的设计，本质是在能力和风险之间找平衡。我习惯把 Agent 的动作分成四级，按任务风险逐级开放。

生产环境里，绝大多数任务应该跑在 L2 到 L3。L4 只在有完整回滚机制和人工审核的前提下开放。我见过有团队一上来就给 Agent 全权限，结果它把 CI 配置文件改了，整个流水线挂掉，排查了半天才发现是 Agent 干的。

4.2 文件级白名单比目录级更靠谱

圈定改动范围时，很多人用目录白名单。但目录粒度太粗，一个目录里可能既有该改的也有不该碰的。更精细的做法是文件级白名单加符号级约束。

具体来说，任务开始时，Harness 先根据任务描述和检索结果，生成一个“预期改动文件列表”。Agent 只能改这个列表里的文件。如果它在执行过程中发现需要改列表外的文件，必须显式请求扩展权限，由 Harness 判断是否放行。这个机制能挡掉大量“顺手乱改”的情况。

符号级约束更进一步：允许改某个文件，但只允许改指定的函数。这在维护老代码时特别有用——你只想让 Agent 修一个函数里的 bug，不想它把整个文件重排一遍。

4.3 终端命令的“沙箱化”

让 Agent 跑终端命令是能力也是风险。我的做法是命令白名单加参数校验。只允许跑测试、构建、格式化、静态检查这几类命令，且命令模板固定，参数由 Harness 填充，Agent 不能自由拼命令。

比如跑测试，Harness 提供的是一个run_test(module_name)的工具，Agent 只能传模块名，实际执行的命令由 Harness 组装。这样既给了 Agent 执行反馈的能力，又杜绝了它跑出rm -rf这种灾难。

注意：即使有白名单，也要在隔离环境里跑。容器、临时工作区、只读挂载，这些基础设施该上就上。别指望白名单能挡住所有意外。

4.4 动作空间的“渐进开放”策略

一个很实用的技巧是渐进开放。任务开始时给最小权限，随着任务推进和验证通过，逐步放开。比如一个重构任务，先让 Agent 在只读模式下出方案，方案通过人工或自动审核后，再开放写权限；写完跑通测试后，才允许它提交。

这种策略的好处是，风险被切成了小段，每段都可控。坏处是流程变长，需要 Harness 有状态管理能力。但对于生产环境的核心模块，这点开销完全值得。

5. 输出验证与失败恢复：让 Agent 自己“照镜子”

5.1 验证要分层，不能只看“编译过了”

编译通过只是最低标准。一个生产级的验证体系至少要有四层。

第一层是语法与编译验证，这是硬门槛，不过直接打回。第二层是测试验证，包括单元测试和相关的集成测试。第三层是静态检查，代码规范、复杂度、潜在 bug 模式。第四层是语义验证，这一层最难也最有价值——改动是否真的实现了任务目标，而不只是“看起来像”。

语义验证可以借助另一个模型来做，让一个“审查者”Agent 对照任务描述检查改动。也可以借助测试覆盖率变化、接口契约检查等工程手段。华为 CodeArts 体系里，这一层往往和代码检视流程结合，把 Agent 的产出纳入既有的质量门禁。

5.2 失败信息的“结构化回喂”

Agent 失败后，怎么把失败信息喂回去，直接决定它能不能自我修正。最差的做法是把原始报错日志一股脑塞回去，模型在几百行堆栈里根本找不到重点。

好的做法是结构化回喂：把失败信息拆成“失败类型、失败位置、期望值、实际值、相关代码片段”几个字段，只把最相关的部分给模型。比如测试失败，就告诉它哪个测试、哪一行断言、期望什么、实际什么，再附上被测函数和测试函数。这样模型能快速定位问题。

我实测过一个对比：原始日志回喂，模型二次修正成功率大概三成；结构化回喂，能到七成以上。差距非常明显。

5.3 重试策略：次数、退避、换路

重试不是简单地“再来一次”。我的策略是有限次数加策略切换。

第一次失败，原样重试，给结构化失败信息。第二次失败，换一种上下文组织方式，比如补充更多相关代码或换个检索策略。第三次失败，换模型或换方案，比如从“直接改”换成“先写测试再改”。三次还不行，就交回人工，并把整个失败过程记录下来，作为后续调优的素材。

重试次数不宜多。超过三次还在原地打转，说明要么任务本身超出 Agent 能力，要么 Harness 的某个环节有系统性问题，继续重试只是烧钱。

5.4 回滚机制：改错了要能干净地退回去

回滚是生产环境的底线。每次 Agent 开始改动前，Harness 应该自动创建一个检查点——可以是 git stash、临时分支、或者文件快照。改动失败或验证不通过，一键回滚到检查点，环境干净如初。

这里有个容易忽略的点：回滚要包括副作用。Agent 可能装了依赖、生成了临时文件、改了环境变量。回滚时这些都要清理，否则下次任务会在一个被污染的环境里跑，问题很难复现。

6. 实操调优全流程：一个真实重构任务的拆解

6.1 任务准备：把模糊需求变成可执行规格

假设任务是“优化订单模块的查询性能”。这句话直接丢给 Agent，它大概率会给你一堆似是而非的改动。正确的做法是先把它变成可执行规格。

我会拆成：目标是把订单列表接口的 P99 延迟从 800ms 降到 300ms 以内；约束是不能改变接口签名、不能引入新依赖、必须保持现有测试全绿；验收标准是压测报告达标加所有测试通过；禁止改动范围是订单写入逻辑和数据库 schema。

这份规格本身就是 Harness 的一部分，它让 Agent 知道边界在哪。规格的生成可以半自动——Harness 根据任务类型套模板，人工补充关键约束。

6.2 上下文组装：检索加裁剪的实际操作

规格定了，接下来组装上下文。先用符号索引找到订单查询相关的入口函数，再沿调用图往下找两跳，得到候选文件集。然后按相关性打分排序，取前若干名。同时把订单模块的测试文件、最近的性能相关提交、代码库的日志和错误处理约定一起打包。

组装完检查一下 token 占用，如果超过预算，就按分数从低到高砍。砍的时候优先砍依赖方代码，保留核心实现和测试。这一步的实操心得是：宁可少给，不要多给。模型缺信息会问或猜，但信息过载会直接让它变笨。

6.3 执行与验证：一轮完整的 Agent 循环

Agent 拿到上下文和规格，开始工作。它先读代码、分析瓶颈，然后提出改动方案。Harness 在方案阶段可以做一次拦截——如果方案明显偏离规格，直接打回让它重想，不用等到改完才发现方向错了。

方案通过后，Agent 在文件白名单内改动。改完，Harness 自动跑测试和静态检查。如果失败，结构化回喂，进入重试。如果通过，再跑一次性能压测，对照验收标准。全部达标，生成改动摘要，进入人工审核或自动合并。

这一轮循环里，最耗时的往往不是模型推理，而是验证环节。所以验证的并行化和缓存很重要。测试能并行跑的就并行，静态检查结果能缓存的就缓存。

6.4 效果度量：怎么知道调优有没有用

调优不能凭感觉。我固定跟踪几个指标：一次通过率（Agent 第一轮就通过验证的比例）、平均重试次数、人工介入率（需要人改的比例）、单任务 token 成本、端到端耗时。

这几个指标里，一次通过率最能反映 Harness 的整体质量。它上去了，其他指标通常都会跟着改善。我自己的经验是，通过上下文和验证两块的调优，一次通过率能从三成提到七成左右，再往上就要靠更精细的动作空间设计和模型能力提升了。

7. 常见问题与排查技巧实录

7.1 Agent 改错文件、改超范围

这是最高频的问题。排查顺序是：先看文件白名单有没有生效，再看上下文里有没有误导性的相关代码，最后看任务规格里的禁止改动范围是否清晰。

我遇到过一次，Agent 反复去改一个无关的工具类。查下来发现是检索环节把那个工具类排到了前面，因为它的名字和任务关键词有重叠。解决办法是在检索打分里加入“是否在预期改动范围内”这个信号，把范围外的文件降权。

7.2 测试跑不通但 Agent 说改好了

这通常是验证环节缺失或验证结果没回喂。检查 Harness 有没有在 Agent 声称完成后强制跑测试，以及测试失败信息有没有结构化地喂回去。另一个可能是 Agent 在沙箱里跑测试通过了，但沙箱环境和真实环境有差异。这种情况要统一环境，别让沙箱和真实环境两套配置。

7.3 长任务跑到一半“失忆”

长任务里 Agent 忘记前面的约束，是上下文管理的问题。解决办法是关键约束在每个循环都重新注入，不要指望模型记住几十轮前说的话。另外可以把任务拆成子任务，每个子任务独立组装上下文，减少对长历史的依赖。

7.4 成本失控

成本失控通常来自三个地方：上下文过大、重试次数过多、验证环节重复跑。对策分别是收紧检索预算、设置重试上限、给验证结果加缓存。我还会给每个任务设一个 token 预算上限，超了就中止并报警，避免一个任务烧掉一天的额度。

7.5 常见问题速查表

7.6 几条踩坑换来的经验

第一条，别在调优初期就追求全自动。人工审核环节该保留就保留，它既是质量兜底，也是收集失败样本的渠道。等一次通过率稳定在高位，再逐步减少人工介入。

第二条，失败样本比成功样本值钱。每次 Agent 失败，都把完整的上下文、动作、验证结果存下来。攒够一批做分析，能发现 Harness 的系统性短板，比零散调参高效得多。

第三条，模型和 Harness 要匹配着调。换个模型，Harness 的上下文预算、重试策略可能都要跟着变。别指望一套 Harness 打遍所有模型。

第四条，验证要快。验证慢会拖垮整个循环的吞吐。能并行的并行，能缓存的缓存，能增量的增量。验证速度上去了，同样的时间能跑更多轮，调优迭代也更快。

8. 关于 Harness 工程的一点个人体会

调了这么久 Coding Agent，我最大的体会是：决定生产级效果的，从来不是模型有多聪明，而是 Harness 有多克制。克制地给上下文，克制地开权限，克制地重试，克制地相信模型的自我报告。每一次克制，都是在用工程手段弥补模型的不确定性。

Vibe Coding 的“最后一公里”，说到底就是把“感觉能跑”变成“验证过能跑”。这条路没有捷径，靠的是一轮轮真实任务的打磨，靠的是把每次失败都变成 Harness 的一次改进。华为 CodeArts 这套体系给我的启发，不是某个具体功能，而是它把 Agent 放进了软件工程既有的质量框架里——检索、验证、门禁、回滚，这些老东西配上新模型，才是生产级的样子。

如果你现在正卡在这一公里上，我的建议是从验证环节先动手。把验证做扎实，Agent 的产出质量会立刻上一个台阶，后面的上下文和动作空间调优也有了可靠的反馈信号。至于模型选型、工具链搭建这些，反而是相对好解决的。真正难的是那套让模型“不敢乱来、错了能发现、发现能修正”的工程机制，那才是 Harness 的灵魂。