CC Switch 为什么移除 Hermes 的 Auto 协议：api_mode 从猜测到显式声明的机制拆解

CC Switch 为什么移除 Hermes 的 Auto 协议api_mode 从猜测到显式声明的机制拆解【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch你在 CC Switch 里给 Hermes Agent 建过供应商大概遇到过这么个场景供应商看着配置没问题请求发出去却 400。翻来覆去排查最后发现是协议请求走哪条 API 路径选错了而且这个选择还是没人做的——工具自己猜的。猜错了也不吭声。CC Switch 是一个跨平台桌面端工具统一托管 Claude Code、Codex、OpenCode、Hermes Agent 等多个编码 Agent 的供应商配置与本地路由。v3.14.0 对 Hermes 供应商做了一个 breaking changeapi_mode协议字段的 Auto 模式被移除协议从此只能显式声明。这篇文章把这次变更的机制讲透为什么自动反而成了故障源以及新设计如何把协议选择钉死在持久化配置里。30 秒摘要v3.14.0 起Hermes 供应商的api_mode不再允许 Auto运行时不再靠 URL 启发式猜协议CC Switch 在导入与新建时一律写入显式值。Deeplink 导入和预设导入的供应商默认落到chat_completions兼容性最广的协议事后可在表单里改。既有配置里带 Auto 的用户升级后不会被静默处理而是被提示手动选一个协议。受影响最重的是 Hermes 供应商用户和用 Deeplink 分享导入的用户其余客户端Claude Code、Codex 等完全不受影响。行为前后对比旧行为Auto 存在时新行为v3.14.0 起协议来源Hermes 按base_url启发式猜测CC Switch 写入显式api_modeHermes 照单执行自定义网关启发式认不出协议静默选错默认chat_completionsUI 随时可改存量 Auto 配置一直存在行为随 Hermes 版本漂移升级时被拦截要求人工选协议预设库部分预设不带协议字段全部 Hermes 预设显式携带机制拆解设计理念与事件时间线设计理念一句话把运行时行为锚定在持久化配置上而不是运行时猜测。协议是供应商语义的一部分语义必须由人声明机器只负责执行。触发。有两条路会创建一个 Hermes 供应商UI 表单手动新建或 Deeplink 分享导入。后者的输入里根本没有协议字段——分享链接只携带名称、端点、密钥和模型协议信息无处安放。判定。旧逻辑把空缺留给 Hermes 内置的 URL 启发式去补新逻辑在 CC Switch 侧就填上确定值。Deeplink 路径的代码是这么写的// 协议永远显式写入。Deeplink 没有字段承载它 // 默认落到兼容性最广的 chat_completions导入后用户可在 UI 调整。 // 我们从不依赖 Hermes 内置的 URL 启发式——它只认识少数官方端点。 config.insert(api_mode.to_string(), json!(chat_completions));对应 src-tauri/src/deeplink/provider.rs#L562-L589api_mode的固定写入在 L579。注意 L557-L561 的注释点破了旧路径的软肋启发式只认得一小撮官方端点自定义网关和聚合器端点全部落空。持久化。保存供应商时走set_provider读~/.hermes/config.yaml把条目 upsert 进custom_providers:列表原子写回并留存带时间戳的备份src-tauri/src/hermes_config.rs#L792-L861备份逻辑见 L363-L381。写入前有一步清洗历史上 Deeplink 写入过 camelCase 的apiMode这种 Hermes 不认识的键sanitize_hermes_provider_keys会把它们统一改写成 snake_case 的api_modeL538-L565——老数据在下一次保存时自愈而不是带毒进 YAML。section 级替换只动custom_providers区块文件里其他内容和注释原样保留。执行与状态。Hermes 运行时读custom_providers里的api_mode选择协议路径CC Switch 不再参与运行时决策。前端表单把协议选择器锁死在四个显式值上chat_completions/anthropic_messages/codex_responses/bedrock_conversesrc/config/hermesProviderPresets.ts#L87-L95没有 Auto 兜底UI 层从结构上不可能再产生隐式状态。影响面矩阵 ⚠️用户类型影响需要做什么不需要做什么Hermes 供应商用户带 Auto 的存量供应商升级后被提示选协议逐张确认协议并保存显式协议的供应商与 Claude Code / Codex 等其他客户端零改动Deeplink 导入用户导入结果默认chat_completions端点走原生 Anthropic / Codex responses 协议的手改协议选项用 Chat Completions 兼容端点的直接可用预设库用户v3.14.0 起新增供应商自带显式协议无存量预设卡保持原样发布管理者需注明 Auto 移除属 breaking change在发布说明标注协议选择流程变化本次变更不引入数据库 schema 迁移常见误解默认 chat_completions 就是自动判断不用管。不是。chat_completions是固定兜底取的是兼容性最大公约数。选错了 CC Switch 不会纠正只会以请求失败的形式暴露。Auto 被移除是因为它总是猜错。方向反了。问题不是猜错而是猜的覆盖面太窄URL 启发式只认识一小撮官方端点自定义网关场景下它等于静默随机。一个只在 10% 场景有效的自动剩下 90% 都在制造故障。存量的 Auto 配置升级后会自动迁到新协议。不会。变更刻意不静默迁移而是拦下来让你选。用默认值替你决定协议等于用一次猜测替换另一次猜测。测试如何守住这个行为不看文件清单看三个断言各守什么契约。第一个在 src-tauri/src/deeplink/provider.rs#L1099-L1104测试构造一次 Hermes 导入断言产出的设置里api_mode必须存在且等于chat_completions断言注释直接写明意图——协议必须显式写入Hermes 永远不要回落到 URL 自动检测。它守的契约是导入路径永不产生隐式协议。第二个在 tests/components/HermesFormFields.test.tsx#L25表单测试锁定默认值就是chat_completions确保 UI 侧永远给出显式值防止将来有人往选项列表里塞回一个 Auto。第三个是往返测试 src-tauri/tests/hermes_roundtrip.rs写入再读回验证 camelCase 历史键apiMode被改写成api_mode、models在数组与字典形态间正确转换。它守的是老数据自愈这条持久化链路不回归。附录配置速查与相关文件Hermes 供应商条目写在~/.hermes/config.yaml的custom_providers:下键类型默认值含义api_modestring导入时chat_completions协议路径chat_completions/anthropic_messages/codex_responses/bedrock_conversebase_urlstring必填供应商端点api_keystring必填访问密钥modelstring模型列表首项运行时与/model选择器读取的默认模型modelsdict—每模型context_length等元数据相关文件变更骨架docs/release-notes/v3.14.0-zh.mdBreaking 一节在 L375-L403显式写入判定src-tauri/src/deeplink/provider.rs持久化与清洗src-tauri/src/hermes_config.rs协议选项与预设库src/config/hermesProviderPresets.ts测试src-tauri/tests/hermes_roundtrip.rs、tests/components/HermesFormFields.test.tsx想深入时直接读 docs/user-manual/zh/2-providers/ 里的 Hermes 章节供应商面板的操作流程和协议选项的含义都有说明。【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考