企业官网建设流程全解析

上个月周五晚上，我的手机被三时区的连环消息炸醒。北美分部同事在群里扔了一段trace日志：客服Agent在"订单改地址"任务上连续三次工具调用失败，欧洲那边补了一句"模型服务返回了奇怪的400"，亚太这边刚起床的我，一边翻日志一边意识到——这是我们自建Agent以来第七次因为同一个根因在周末加班：每个人对Agent运行方式的理解都不一样。

那会儿我们团队分布在三个大洲，各有各的模型API、各有各的prompt风格、各有各的工具调用写法。北美用某开源agent框架，欧洲自己封装了一层模型调用，亚太这边直接裸调API。表面上看大家都在做Agent，实际上每个人都在造自己的轮子。后来我们花了一个季度的时间，把"AI Agent Harness Engineering"这件事收口成了一套统一规范，也把线上问题的定位时间从"跨时区开电话会"压缩到了"直接看trace"。这篇文章就聊聊我们在跨国团队场景下落地harness层的完整过程、架构取舍，以及那些踩完才发现"原来应该早点做"的协作细节。

1. 从"各写各的Agent"到harness层收口：一次被迫的架构统一

1.1 为什么是"harness"而不是"多写几个工具函数"

先说清楚harness这个概念在Agent体系里到底指什么。模型本身是那个"会思考的发动机"，但发动机不能直接上路，你还需要底盘、变速箱、仪表盘、油路——这些把模型的思考能力真正接到业务场景里的外围工程，就是harness。具体到Agent系统，它包含任务解析、工具选择与调用、上下文组装、状态持久化、错误恢复、可观测性追踪这一整套运行时骨架。

我们最早犯的错误，是把这些逻辑散落在各业务代码里。客服组有自己的Agent循环，订单组有另一套，每个组自己拼上下文、自己处理模型返回的JSON、自己写重试逻辑。问起来都说"我们在做Agent"，但代码层面完全是三套东西。这不是"多写几个工具函数"能解决的——问题不在重复代码，而在大家对任务的运行模型没有共同语言。一个组说"Agent执行完了"，另一个组可能指的是"模型把文本吐完了但工具还没调"，线上对账的时候特别痛苦。

所以我理解Harness Engineering的核心价值，不是让你少写代码，而是让整个系统对"Agent怎么从一个原始需求走到最终结果"这件事，有唯一且可审查的定义。有了这层定义，跨团队协作才有可能：你负责工具层，我负责策略层，他负责模型层，大家对着同一份契约干活。

1.2 收口过程中吵得最凶的三个问题

第一次拉齐架构时，三个时区的讨论群里吵得最凶的是三件事。

第一，Agent循环到底放harness还是放业务层。有人觉得Agent循环是业务逻辑，应该留在各业务代码里，方便各自调整。我们当时的结论是：循环骨架（拿到任务、选工具、调模型、看结果、决定下一步）必须放harness，业务层只能通过配置和回调干预。原因很实际——跨时区协作不存在"随时问一句"的便利，如果每个人都能改循环结构，线上行为根本没法预测。

第二，prompt到底是谁的资产。产品组想直接改prompt来调Agent行为，工程组觉得prompt改动应该走代码评审。吵到最后我们定了一个折中方案：prompt模板由产品提供文案，但必须放进harness的配置仓库，走完整的变更流程。谁也别绕过流程直接改线上配置。

第三，模型升级谁说了算。原来模型供应商一更新版本，各团队自己就切过去了，结果经常出现"北美升级了、欧洲没升"的混乱局面。后来我们规定：harness层适配新模型版本后，必须先跑完整评测集，再由一个专门的"模型升级协调人"统一推动，任何团队不得自行切换生产模型版本。这个协调人不是技术多牛，而是能保证所有时区的人都在同一个时间窗口内完成验证。

这轮架构争论最大的收获，是我们第一次把"模型的一次输出"和"Agent的一次任务"从概念上拆开了。前者是模型行为，后者是系统行为——harness管的永远是后者。

2. 接口契约先行：三时区异步协作的真正地基

2.1 Task协议：一次任务从进入到产出的标准信封

跨国团队异步协作最大的敌人，是"沟通链条太长"。为了不让每个人在讨论时都带着自己对"任务"的理解，我们定义了一套标准信封：task_request（任务进入）、task_event（过程事件）、task_result（最终结果）。所有Agent运行，不管业务是什么，都通过这三个结构交换信息。

{ "task_request": { "task_id": "task_8f3a1c2e", "trace_id": "tr_9d0b77aa", "agent_profile": "customer_service_v3", "input": { "intent": "change_delivery_address", "payload": { "order_id": "ORD-20250115-008", "new_address": "Building 5, No.88 Innovation Road" } }, "constraints": { "max_steps": 10, "max_tokens_per_step": 2048, "deadline_ms": 30000 } } }

task_id是业务主键，trace_id贯穿整个调用链，agent_profile标记用的是哪套prompt和工具集，constraints是关键——它让harness层在不修改代码的情况下就能给任务设限。这些字段看起来简单，但统一它们的成本远超我们预期，因为每个团队原来都有自己的命名习惯，比如"session_id""request_id""conversation_id"，其实都是同一个东西。定义标准信封之后，只要看消息里的id，就能跨系统把一次Agent运行从入口到出口全部串起来。

{ "event_type": "tool_call", "tool_name": "check_inventory", "tool_args": { "sku": "SKU-40291", "warehouse": "us_east" }, "status": "success", "duration_ms": 820, "model_turns": 3, "tokens_used": 1560, "occurred_at": "2025-01-15T06:32:18Z" }

事件结构里我们特意加了model_turns和tokens_used，不是为了好看，而是为了成本审计。一次Agent任务到底调了多少次模型、消耗了多少token，必须有据可查。跨国团队的预算是分开审批的，如果没有统一事件格式，连"为什么这个月API账单涨了40%"都说不清。

2.2 工具注册与Function Calling的全局规范

工具是Agent和大千世界交互的手脚，而工具描述是模型理解"能做什么、怎么做"的唯一窗口。我们有三套工具系统散落在各地，有的用OpenAI function calling格式，有的用内部自定义的XML，还有的直接让模型输出JSON字符串然后正则解析——把适配层收口后，统一成了JSON Schema风格的工具注册表。

{ "name": "check_inventory", "description": "根据SKU和仓库编码查询商品实时库存", "parameters": { "type": "object", "properties": { "sku": { "type": "string", "pattern": "^SKU-[0-9]{5}$" }, "warehouse": { "type": "string", "enum": ["us_east", "eu_west", "apac_south"] } }, "required": ["sku", "warehouse"] }, "idempotent": false, "timeout_ms": 3000, "rate_limit": 50 }

这条规范里有几个容易被忽视的细节。工具名称必须全局唯一，而且一旦发布，语义不能变——某个分区的工具叫"check_inventory"，另一个分区的叫"query_stock"，模型只会更困惑。参数的enum列表尽量收敛，别给模型太多自由发挥空间。idempotent字段表示工具是否幂等，这个字段直接决定harness的重试策略：可以安全重试的工具，失败后自动重发；不能幂等的工具，重试必须人工确认。

我们吃过亏的地方是：工具描述里的语言风格必须统一。北美工程师写的描述喜欢用长句和委婉表达，欧洲工程师写的又过于简练，最后发现模型理解和实际执行的行为差异很大。后来规定所有工具描述用同一套从句结构："根据{参数}，执行{动作}，返回{结果}"，简单粗暴但效果稳定。

2.3 上下文管理：harness层最容易崩的地方

模型一次只能读有限长度的上下文，但Agent任务跑着跑着，中间步骤的累积可能撑爆窗口。我们在设计harness时把上下文管理拆成了三段：系统指令区（prompt模板+工具描述）、工作记忆区（本次任务产生的中间结果）、长期记忆区（历史订单、用户偏好等检索结果）。每段有独立的token预算，超了就按不同策略处理——系统指令区只压缩不裁剪，工作记忆区可以丢细节但必须保留摘要，长期记忆区按相关性截断。

为什么这么分？因为我们发现，三时区协作调试一个Agent问题时，最常问的问题是"它当时看到了什么"。如果每次运行结束都把最终上下文快照落盘，任何时区的人拿到task_id就能回放模型当时的完整输入。这比"模型输出了什么"更重要——很多时候模型的输出看起来离谱，其实是它看到的上下文里有误导信息。上下文快照保留原始prompt、工具返回、截断操作，一条不漏。

2.4 Schema变更的工程纪律

接口契约定好了，真正考验人的是变更。跨国团队最怕的是：亚太这边的工程师改了一个工具参数，欧洲还在按旧参数调用，北美测试环境已经用上新版本——三地代码同时漂移。

我们立了三条规矩。第一，所有契约变更必须以diff形式提交，写明兼容性影响，禁止"顺手改"。第二，发布契约前必须过contract test，测试集里包含旧版本客户端的模拟调用，保证向后兼容。第三，每个契约有独立版本号，运行日志里记录实际使用的契约版本，排查问题时先看版本号再谈别的。

这些规矩在实行初期被人嫌烦，但后来所有人都体会到了好处：接口契约的稳定性，直接决定了你半夜被叫醒的概率。为了一条"顺手改"的字段，让三个时区重新对齐投入的时间成本，远比改的时候多填一份文档高得多。

3. 模型无关与多区域部署：harness层拆分与大三洲流量三角

3.1 Provider适配层不是简单的API封装

很多团队做模型适配时，就是写一个函数，把各家的请求参数翻译一下。真正落地会发现远不止这么简单——不同模型供应商在能力边界上的差异，必须靠harness层抹平，否则上层业务代码会被模型选择绑架。

我们做了一张适配对照表，把所有供应商的能力差异列出来，这个表帮了大忙：

这张表解决了一个关键问题：业务代码永远不要感知"当前用的是哪家模型"。上层拿到的永远是标准结果结构或标准错误，至于背后是模型A还是模型B，由路由策略决定。业务团队因此不用关心某个模型今天是不是抽风了，那是harness层的事。

3.2 多区域路由策略：延迟、成本、质量的三角权衡

我们在三个区域都有业务流量，模型调用自然也要考虑区域就近。但这个"就近"没那么简单，因为模型服务的质量在不同区域并不一致。我们做的路由策略有四个优先级：

区域端点优先——用户从哪个区域进来，首选该区域的模型端点，降低首token延迟。高峰容灾——首选区域如果触发了熔断或限流，自动切到邻近区域，同时把trace里的region字段标清楚。成本感知——某些非核心场景（比如摘要生成），路由到成本更低的模型上，但必须满足质量评测阈值。质量保底——涉及退款、改地址这类高风险操作，强制走质量最高的模型，不允许为了成本降级。

这个路由决策全部放在harness层，业务无感。可一旦切区域成功，模型行为可能有微妙差异，所以我们要求每次跨区域路由都必须写入trace，方便后续复盘"这次Agent表现异常是不是因为换模型了"。

这里还有个大坑：不要在harness层做跨区域的分布式锁。我们早期想给"同一用户同时只能跑一个Agent任务"加个全局锁，结果跨区域分布式锁本身就成了单点和最慢环节，一个区域抖动，全世界的任务都排队。后来改成区域本地锁加最终一致性校验，用户并发冲突的概率极低，偶尔冲突就让用户重试，体验上完全可接受。分布式系统里，为了一个几乎不可能发生的边界情况引入全局强一致，往往得不偿失。

3.3 超时、熔断与降级：数字背后是血泪教训

跨国场景下模型服务的延迟波动比单一区域严重得多。我们最初只设了一个"总超时30秒"，结果发现某区域的模型在高峰期首token就要8秒，一次Agent任务调用多次模型，经常整体超时。后来把超时拆成了四级：

熔断逻辑不是简单的"连续失败N次就断开"，而是滑动窗口统计：5分钟内错误率超过40%或p95延迟超过20秒，熔断30秒，让下游喘口气。这个阈值我们调了好几轮，一开始太灵敏，模型稍微波动整个业务就停了；后来放宽到上面的数值，既保护了下游，又不至于误伤正常流量。

降级策略也分层：模型全挂了，降级到规则引擎，用流程化的if-else处理高确定性场景；规则引擎也没有数据权限，就降级到"转人工"，并且给用户明确的排队预期。这里有个细节：降级路径同样要产出task_events，不能"悄悄换成规则"了事——跨时区协作最怕的就是系统行为悄悄变了而没人知道。

3.4 可观测性：让三个时区的人用同一套语言debug

最后一块底座是可观测性。我们说"一次Agent运行"从trace角度看，就是一棵调用树：模型调用、工具调用、上下文压缩、路由切换，每个环节都挂在同一个trace_id下。三个时区的人半夜被拉进来debug时，只需要说"trace tr_9d0b77aa，在第三步工具调用挂了"，其他人立刻就能在各自的时间范围内查日志、查指标、查上下文快照。

日志规范再强调一次：所有事件必须走harness定义的标准event schema，任何团队都不允许在业务代码里自建一套日志往自己的文件里写。否则跨时区排查时，你只有一堆格式各异的日志片段，谁也拼不出完整链路。

4. 异步协同的质量保障：评测集、灰度与"别在我这边是好的"

4.1 "它在我这边是好的" 是分布式团队的诅咒

这句话不知道听了多少遍。每次线上出问题，各时区一排查，第一反应都是"我这边测试环境跑得好好的"。分布式团队天然缺少"所有人都对着同一台机器同一个环境"的条件，所以质量问题必须在harness层通过机制来解决，不能靠自觉。

我们的根本解是：把一切可能影响行为的变量收进harness层并固定下来。prompt模板版本、工具注册表版本、模型版本、契约版本，四者组成一个不可分割的"运行快照"，每次Agent任务启动时都带上这个快照。复现问题的时候不用问"你当时用的哪版prompt"，直接看快照就行。这个机制看起来重，但它彻底消灭了"在我这边是好的"这个争论的基础。

4.2 多区域黄金评测集与回归流水线

质量保障不能靠抽查，需要一套可自动运行的评测集。我们构建了三类测试数据，每类都做分区域子集：

离线回归集：收集历史上所有线上问题样本，每次harness核心代码变更，必须全量跑，防止老问题复发。红队测试集：我们主动构造的刁钻输入——模糊意图、恶意指令、超长上下文、多任务混合，专门测agent的边界防御能力。线上采样集：从低风险流量中按比例抽样保存，带人工标注，用于评估新模型候选版本的"无监督表现"。

分区域子集非常重要。客服Agent在不同区域的用户提问习惯差异很大，欧洲用户喜欢用长句描述问题，亚太用户经常用短句加关键词，北美用户爱用反问句。一套北美调优过的prompt模板，拿到欧洲可能就是灾难级表现。所以黄金集的用例必须覆盖各区域的典型语言风格，并且每个区域子集的通过率有独立底线，不允许"总平均分过线"掩盖某个区域的塌方。

评测的触发点也要卡死：任何harness核心代码变更、任何模型供应商版本升级、任何工具注册表变更，都要跑完整评测集。CI流水线会自动拦截未通过评测的合并请求，人工评审意见不能覆盖机器评测结论。一开始有人说太死板，但事实证明这个"死板"才是跨时区合作的公平裁决者——不需要争论"我觉得行"，直接看评测报告。

4.3 灰度发布与责任矩阵

跨国团队做发布，最大的问题是"谁在什么时间上线"。我们的发布策略分成四步走：harness代码先灰度（只在某一个区域开放5%流量），模型服务升级紧随其后（如果变更涉及模型版本或路由策略），工具新增或变更最后放开。每一步之间有观测窗口，至少要看到一个完整业务周期的指标稳定，才走下一步。

同时我们定义了一张责任矩阵，贴在团队wiki最显眼的位置，明确每类变更的owner：

发布方和回滚方刻意分开，是为了避免"自己发布自己回滚"的侥幸心理。让另一个时区的团队负责回滚，也保证了在线上的任何异常时刻，始终有一个"不在发布兴奋期"的人做冷静决策。

5. 磨合出来的协作细则：文档、评审和踩坑实录

5.1 文档即代码：ADR与"写给别人看的注释"

跨国团队最便宜的沟通成本是文档，但最容易被省掉的也是文档。我们后来强制推行了一套ADR（架构决策记录）机制：每次架构级变更，必须写一份简短的决策记录，包含背景、可选方案、最终选择、理由和代价。

ADR的写法有一条硬要求：重点写"为什么"而不是"是什么"。因为代码自己会说明"是什么"，但跨时区协作里没人能在你旁边追问"你当时为什么这么设计"。一份好的ADR，应该让三个月后的陌生人能理解你的全部思考链路。后来我们做线上问题复盘时发现，ADR帮了大忙——很多看似诡异的代码，背后都是当时某个权衡的结果，没有ADR就只能靠猜。

5.2 异步代码评审怎么开才有效

代码评审在跨国团队里天然是异步的，没人能实时在线盯屏幕。我们的经验是把评审成本压到足够低，否则大家宁可推迟也不走评审流程。

单PR只解决一个原子问题，不要混入无关重命名、格式调整、依赖升级。一个PR的目标是评审人能10分钟内看完并给出明确结论。强制跑自动检查再转人工：contract test、lint、评测集子集都必须绿了，才允许挂"待人工评审"标签。每个PR设置评审截止时间：如果24小时无异议，默认通过（48小时内可撤回）。这个做法一开始争议很大，但实际运行之后，团队协作反而更顺畅了，因为大家知道"没人反对不代表需要等所有人表态"。

5.3 踩坑记录：schema漂移、prompt文化差异与框架升级

写几个我们踩过且成功修复的坑，给同行一个参考。

第一个是schema漂移。某欧洲团队改了一个工具的枚举值，加了新仓库编码，但没同步更新工具注册表版本。结果北美区域的模型还按旧schema调用，欧洲已经返回新枚举，harness解析工具返回时直接报错。整整半天，三个时区的工程师都在查各自负责的环节，最后发现就是"改了一行没更新版本"。

第二个是prompt文化差异。北美团队负责的prompt模板里用了大量口语化表达，比如"You want to cancel？Let me check that for you."。这套语气放到亚太区域，用户反馈"太随便了，不像正规客服"。后来我们把prompt模板拆成两层：结构化指令（谁来做、按什么流程做、遇到什么情况怎么处理）+ 文化适配变量（语气、称呼、礼貌程度）。指令层全局统一，适配层按区域配置，才算解决了这个问题。

第三个是框架升级事故。有同事顺手把某个开源agent框架升了大版本，结果所有工具调用日志的事件格式变了，harness的解析器懵了三天。因为日志格式是harness的契约之一，任何上游框架升级都必须走变更评审流程，不能"顺手"升级。

5.4 一点个人的体会

如果你也要在跨国团队里落地Agent项目，我的建议是从最小契约开始：先定task协议和trace规范，让所有人都能用同一种语言描述一次Agent运行；然后逐步补上工具注册表、上下文管理、评测集。不要一开始就追求完美架构，先把"线上出问题时，三个时区能各自独立定位再对齐"这件事跑通，后续的迭代都是在这个底盘上堆能力。

Harness Engineering本质上不是算法问题，而是工程组织问题。它能不能落地，取决于团队是否愿意为"统一的运行骨架"牺牲一点各自的灵活。在我们团队里，这个代价换来的最大收益，是任何一次线上问题都不再需要"跨时区集合开会才能定位"，每个人都能在各自的工作时间段内推进问题的解决——对于分布式团队来说，这比任何技术指标都重要。