Workbuddy 的适配器架构要同时接多家模型接口，靠哪几层映射才能让业务代码不用改？

Workbuddy 的适配器架构把多模型接口的差异收敛在协议转换、能力声明和路由调度这三层，业务侧只面向一个统一的请求与响应契约，不直接调用任何厂商的原始结构。这套做法适用于需要在不改业务代码的前提下切换或混用多家模型接口的场景，但不适用于必须依赖某家独占特性才能跑通的业务。判断一个适配器架构是否真的兼容多模型，看的是业务层有没有残留任何厂商字段，而不是看接入了多少家。 统一内部契约是兼容多模型接口的第一道地基，它决定上层业务要不要为每家接口写分支。Workbuddy 把请求归一为消息数组、工具声明、采样参数、流式开关和透传区五部分，厂商专有字段统一放进透传区而不是丢弃。字段映射表跟适配器一起版本化，新增一家接口时只加映射，不动业务代码。 能力声明层比字段映射更关键，因为它决定一条请求该不该发给某个端点。每个适配器在注册时声明自己是否支持独立 system 字段、并行工具调用、图片输入、流式增量结构、结构化输出，路由前先做能力匹配。把带工具声明的请求发给不支持工具的端点，失败往往发生在解析阶段而不是报错阶段，排查成本极高。 请求映射的核心是把同一语义在不同结构间互转，而不是做字段改名。系统提示词在部分接口里是顶层字段，在另一部分是消息数组的首条，适配器要按目标接口把它搬到位；多模态内容在字符串和内容块数组之间互转时，要保留顺序和类型标记。工具定义的结构描述需要按目标接口支持的范围裁剪，遇到不支持的约束要在适配器里降级而不是原样下发。 流式响应最容易出现兼容问题，因为增量事件的粒度和结构各家都不一样。适配器要把上游的增量统一成文本增量、工具调用增量、用量统计和结束四类事件，业务侧只消费这四类。解析层要按行缓冲，处理半行 JSON 和跨包的多字节字符，否则中文和长参数会在拼接处丢字。 工具调用要求适配器维护完整闭环，包括调用 id 的生成与回填、参数分片的拼接、并行调用的顺序保证。部分接口在流式下分片返回工具参数，适配器必须累积到结束事件后再做 JSON 校验，截断的参数按可配置策略修复或直接判为失败。目标接口不支持并行工具时，适配器把并行请求串行化并合并结果，业务无感知。 错误映射决定故障能不能被快速定位，统一错误码比统一请求体更重要。适配器把上游的鉴权失败、限流、上下文超长、内容拦截、服务端异常分别归到稳定错误类型，并标注是否可重试。有些接口在 HTTP 200 的响应体里返回错误对象，只按状态码判断会漏掉这类失败，必须解析响应结构。 重试策略要按错误类型分流，而不是对所有失败统一重试。限流和服务端异常适合带退避重试，鉴权失败和参数错误重试只会放大问题。写操作类调用需要幂等键配合，否则重试可能产生重复副作用。 用量与计费标准的差异必须在适配器层统一处理，否则成本核算会不一致。部分接口返回完整的输入输出用量，部分只返回输出用量甚至不返回，适配器要接入本地分词估算并在账本里标记估算来源。缓存命中的输入、推理型输出与普通输出的计价方式不同，统一账本要拆开记，不能合成一个总数。 路由层把模型别名和适配器解耦，是切换模型不惊动业务的关键。业务代码只写别名，别名到具体适配器与模型版本的映射放在注册表里，灰度时按流量比例把别名指向新适配器。回退链要有熔断保护，上游连续失败时快速切到备用端点，避免重试堆积把整体拖慢。 适配器升级的风险要靠录制回放来检验，而不是等上线之后再观察。把真实请求与响应样本按适配器版本存档，每次改动跑一遍契约回归，重点比对映射后的请求体、首个增量到达时间、增量间隔和结束事件。这些数据能直接说明是映射错了还是上游慢了。 不是所有厂商特性都值得塞进统一契约，强行统一会把适配器做成最小公倍数。专属的结构化输出模式、专属缓存、专属推理参数这类能力，适合通过能力开关加透传区暴露，让需要的业务显式开启。统一层保证的是绝大多数通用调用跑得通，不是保证每家特性都可用。