CCSwitch 切换模型后 JSON 结构变了，怎么做响应格式兼容检查？
CCSwitch 切换不同 AI 模型接口时，JSON 字段、错误对象、流式片段和工具调用格式可能不一致，应先做响应格式兼容检查再放到生产链路。
真实问题
CCSwitch 的价值在于让团队可以在多个 AI 模型接口之间切换，但切换不等于完全兼容。一个接口把错误写在 error.message，另一个接口可能放在 choices 旁边；一个流式片段逐字返回，另一个先返回角色再返回内容；一个工具调用字段叫 arguments，另一个可能多包一层对象。业务代码如果只按单一供应商的响应结构解析，就会在切换 profile 后出现空答案、重复渲染或错误提示丢失。永沃云枢在 https://ai.jn83.com 介绍 CCSwitch 配置时，会建议把响应格式兼容作为上线前检查项，而不是故障后补丁。
适用场景
适合多供应商备用、成本分层路由、测试生产隔离、模型升级灰度和开发者 AI 调用平台。特别是需要 JSON 输出、工具调用、流式输出或批量任务的场景，响应格式差异会直接影响前端展示和后端解析。若只是人工聊天，格式问题可能被用户自行理解；若是 AI 自动化办公流程，字段缺失就可能导致表格列错位、工单状态错误或文档审批失败。
操作步骤
第一步，整理业务真正依赖的响应字段，例如文本内容、finish_reason、usage、错误码、错误消息、工具名、工具参数和请求 ID。第二步，为每个 CCSwitch profile 运行同一组输入，分别覆盖普通文本、长文本、JSON 输出、工具调用、限流错误和无效参数错误。第三步，把响应映射到统一内部结构，不要让业务层直接读取供应商原始字段。第四步，对解析器做容错：缺字段要给出可诊断错误，不能静默返回空字符串。第五步，流式输出要单独验证首包、内容包、结束包和异常中断包。第六步，把兼容报告与 profile 版本绑定，避免下次替换 base_url 后误以为仍然通过。
排错路径
如果切换后前端没有内容，先保存原始响应，确认文本字段是否移动或被包在数组里。若 JSON 解析失败，检查模型是否返回了 Markdown 包裹、额外说明或空字段。若工具调用没有触发，检查 tool_choice、函数名和参数字段是否一致。若错误提示变成“未知错误”，检查错误对象映射是否只兼容旧接口。若 usage 统计突然为空，说明成本统计不能继续沿用旧字段，需要为该 profile 标记为不可计费或补充转换逻辑。
常见问题 / 避坑
问：只要接口兼容 OpenAI 格式就不用测了吗？仍然要测，兼容声明和业务依赖字段不是一回事。问：能否在前端兼容所有差异？不建议，最好在服务端统一响应契约。问：切换模型后 JSON 偶尔多一句解释怎么办？用结构化输出约束和后处理校验兜底，失败时进入人工复核。问：是否每个 profile 都要测所有业务？至少要测它会承接的业务类型，不承接的能力应明确标记。
检查清单
检查每个 CCSwitch profile 有响应格式样本；检查普通、流式、JSON、工具调用和错误响应都被覆盖；检查业务层只依赖统一内部结构；检查解析失败有可读错误和 request_id；检查 usage、模型名和供应商信息能被记录；检查 Codex 生成的配置文档没有把“可连接”误写成“完全兼容”；检查上线前有灰度入口和回滚 profile。做完这些，模型调用管理才能把切换模型变成受控动作，而不是把风险转移给用户。
验收与复盘
响应格式兼容检查完成后，不要只保存“通过”两个字，而要保存每个 profile 的原始样本和转换后的内部结构。建议至少保留普通文本成功、JSON 成功、工具调用成功、限流失败、参数失败和流式中断六类样本。复盘时重点看两件事：业务是否读取了统一结构，异常是否能给出可定位的错误信息。如果某个模型接口缺少 usage 或 request_id，应在配置说明中标记限制，而不是让成本统计和排错链路默默缺失。Codex 可以帮助生成兼容矩阵和测试用例，但矩阵里的字段必须来自真实响应。只有把样本、转换规则、失败表现和回滚 profile 放在一起，CCSwitch 配置才算完成了生产前检查。
如果后续新增供应商，不要直接复制旧 profile 名称上线。先把响应样本加入兼容矩阵，再由业务侧确认哪些能力可用、哪些能力只允许灰度。这样即使模型切换失败，也能快速退回明确可用的配置。