docs/release-notes/v3.15.0-zh.md
Claude Desktop 升级为一等管理面板（含第三方供应商代理切换）、按角色的模型映射、反向代理大幅强化、Codex OAuth 实时模型发现、用量看板筛选驱动 Hero 卡
CC Switch v3.15.0 是 v3.14.x 之后的一次大版本更新，核心聚焦在把 Claude Desktop 升级为一等管理面板，并配套提供第三方供应商通过内置代理网关进行切换、按角色的模型映射（sonnet / opus / haiku）+ supports1m 长上下文标志、Copilot/Codex OAuth 供应商复用、重新设计的 Claude Code 导入流程、App 切换器对"Claude Code"和"Claude Desktop"的可视化区分，以及 44 个从 Claude Code 预设目录翻译而来的 Claude Desktop 预设。
围绕反向代理的可靠性，本版本进行了一次系统性硬化：P0–P3 多轮针对路由 / 生命周期 / 重试 / 故障转移 / 补正器的修补；非 Anthropic 后端启用 HTTPS 连接池复用以降低单请求延迟；Codex 与 OpenAI Responses 缓存命中率提升（prompt_cache_key 仅在有真实客户端会话标识时发送、对外请求体与 tool_call 参数 / tool_result 内容的 JSON key 规范化排序、session_id 串入用量记录器）；Anthropic ↔ OpenAI tool_choice 正确互转；Vertex AI 完整 URL 不再被截断；Gemini 改为从 URI 路径提取模型名；Local Routing 接管检测更精细；可监听 IPv6 地址。Codex OAuth 类 Claude 供应商不再依赖硬编码的模型列表，CC Switch 会按需从 ChatGPT 后端拉取实时模型列表。
Claude Code 的模型映射改为基于角色（sonnet / opus / haiku）+ 显示名，并引入 supports1m 布尔标志，替代旧版的 [1M] 后缀写法，把路由决策与原始模型 ID 解耦。用量看板新增筛选驱动的 Hero 卡，展示缓存归一化后的真实总 token 与缓存命中率，并跟随当前日期范围 / 供应商 / 模型筛选实时更新；配套修复了缓存成本语义错误以及每个请求都触发的定价警告噪声。在 OpenAI Responses API usage 解析路径上做了鲁棒化处理，让上游缺失或畸形的 usage 不再让 VSCode Claude Code 插件因 null 输出崩溃。
供应商生态进一步扩张：新增 BytePlus、火山 Agentplan、ClaudeAPI、ClaudeCN、RunAPI、RelaxyCode、PatewayAI、百度千帆 Coding Plan 合作伙伴预设；豆包 Seed 升级为合作伙伴预设；供应商卡片现在会显示"是否支持 Local Routing"的徽章。本版本还修复了大量 Codex 会话、OAuth、Claude Desktop 表单、Linux 段错误、终端 fallback 等场景下的细节问题，并完成了多项 GitHub Actions 依赖升级。
发布日期：2026-05-16
更新规模：127 commits | 211 files changed | +17,980 / -2,748 lines
supports1m 长上下文标志、Copilot/Codex OAuth 供应商复用、44 个从 Claude Code 预设目录翻译过来的预设。注意：20 个 Claude Desktop 预设默认从代理模式切到直连模式，升级后如依赖代理路由请验证连通性tool_choice 正确映射；Vertex AI URL 完整保留；Gemini 路径式模型提取；接管检测细化；支持 IPv6 监听地址supports1m 标志，替代旧的 [1M] 后缀reasoning_content (#2543, 感谢 @bling-yshs)；最终 message_delta 总是带 usage 块（即便全为 0），严格 Anthropic 客户端不再因 null 崩溃 (#2485, 感谢 @Myoontyee)CC Switch 第一次把 Claude Desktop 作为一等受管面板对待，与 Claude Code / Codex / Gemini / OpenCode / OpenClaw / Hermes 并列。
sonnet / opus / haikuClaude Code 与 Codex 面板中的供应商卡片新增"路由代理支持"徽章，方便一眼识别哪些供应商可以通过 Local Routing 提供服务。
ChatGPT Codex 类供应商不再依赖硬编码的模型选择，CC Switch 会按需从 ChatGPT 后端拉取实时模型列表。
Claude Code 模型映射改为基于角色（sonnet / opus / haiku）+ 显示名，并引入 supports1m 布尔标志，替代旧版 [1M] 后缀，把路由决策与原始模型 ID 解耦。
用量看板的 Hero 摘要现在是筛选驱动的，跟随当前日期范围 / 供应商 / 模型筛选实时变化；展示缓存归一化后的真实总 token与缓存命中率，让 Hero 数字与下方明细列表对齐。
软化供应商表单的输入校验，把非阻塞性的输入问题改为"先存上再说"的提示，不会因为一个无伤大雅的字段问题阻止保存 (#2307, 感谢 @allenxln)。
为 universal 供应商在供应商列表中新增"复制"按钮 (#2416, 感谢 @hubutui)。
窗口位置和尺寸现在跨重启保留 (#2377, 感谢 @BillSaul)。
系统托盘图标现在悬浮显示状态提示 (#2417, 感谢 @Coconut-Fish)。
新增对 Warp 终端的支持，可在 Warp 中执行保存的会话 (#2466, 感谢 @tisonkun)。
reasoning_contentDeepSeek 工具调用响应现在同时返回 reasoning_content 和 tool_calls，调用方可以两者一并渲染 (#2543, 感谢 @bling-yshs)。
新增百度千帆 Coding Plan 预设 (#2322, 感谢 @jimmyzhuu)。
Compshare Coding Plan 预设跨 claude / codex / hermes / openclaw 全应用就位。
新增 BytePlus、火山 Agentplan、ClaudeAPI、ClaudeCN、RunAPI、RelaxyCode、PatewayAI 合作伙伴预设；豆包 Seed 升级合作伙伴预设（端点和链接刷新）。
从 Claude Code 预设目录翻译 44 个供应商预设进入新的 Claude Desktop 面板。
20 个 Claude Desktop 预设默认从代理模式切到直连模式，降低对不需要代理兼容垫片的用户的上手摩擦。如果你升级前依赖代理路由这些预设的连通性，请升级后验证。
切换 Claude Desktop 供应商会写入 CC Switch 管理的 3P profile，需要重启 Claude Desktop 才能生效；代理模式的供应商在使用期间需要 CC Switch 的 Local Routing 保持运行。
Failover 控件现在要求目标应用的 Local Routing 接管已启用才能开启；只关代理服务但仍有应用依赖接管状态的情况会被拦下，避免出现"代理关了但应用仍以为接管在跑"的不一致。
用量摘要现在报告缓存归一化后的真实总 token和缓存命中率。历史 token 与成本数字在数据去重 + 价格重算后可能会有偏移——新数字更准，但不会等于旧版给出的数字。
预设列表现在按作者定义的数组顺序渲染，合作伙伴排前面，替代之前的隐式排序。
modelMappingOffHint 跨中 / 英 / 日重写为动作导向的简洁文案。
应用内和 README 中所有"官网"引用都统一到 ccswitch.io 作为唯一官方网站；Release notes 模板也呈现 ccswitch.io。
移除主题切换时的圆形扩散动画，改为即时交叉淡入。
App 切换器视觉上区分"Claude Code"和"Claude Desktop"，应用可见性设置中使用"Claude Code"标签。
Claude review GitHub Action 升级到 Opus 4.7；调整 prompt 降低 nitpick 噪声；新增 @claude 仅 review 的 Code Action；锁定 PR head SHA 用于 checkout；移除 --max-turns 5 限制。
actions/checkout 4 → 6 (#2517)pnpm/action-setup 5 → 6 (#2518)softprops/action-gh-release 2 → 3 (#2519)actions/stale 9 → 10 (#2520)DeepSeek 预设现在出货 V4（flash / pro）+ 刷新定价种子。
Codex 供应商编辑表单中不再呈现 1M 上下文开关，降低对当前 Codex 部署无实际效果的旋钮密度。
OpenClaudeCode 预设迁移到 MicuAPI 域名；Micu API 链接刷新到 micuapi.ai。
cn 子域CrazyRouter 预设端点改用 cn 子域。
RelaxyCode 预设图标改用自定义 relaxcode.png 资源。
Kimi For Coding 网站 URL 更新到 /code/docs/ 路径。
SiliconFlow 国际站的余额显示正确为 USD（之前错显 CNY）。
强化 build_anthropic_usage_from_responses() 与 Responses → Anthropic SSE 翻译器，让上游缺失或畸形的 usage 不再在 message_delta 中产出 "usage": null。这解决了严格 Anthropic 客户端（典型如 VSCode Claude Code 插件）在某些供应商（Codex OAuth、DashScope 的 compatible-mode/v1/responses 端点）下崩在 Cannot read properties of null (reading 'output_tokens') 的问题。增加 OpenAI 字段名回退（prompt_tokens / completion_tokens）、null / 空 / 部分对象处理、即使 input/output tokens 缺失也保留缓存 token 字段 (#2422, 感谢 @magucas)。
跨 request-forwarder 路径多轮路由 / 生命周期 / 重试 / 补正器修补；抽取共享的 handle_rectifier_retry_failure helper 与 auth_header_value helper。
非 Anthropic 后端复用池化的 HTTPS 连接，不再每个请求开新 TLS session，显著降低单请求延迟。
不再硬编码 POST，按客户端实际的 HTTP 方法转发；上游的非 POST 端点（如 GET /v1/models）现在能正常工作。
max_retries 接线客户端请求计数器移出每次尝试的循环；AppProxyConfig.max_retries 现在正确接到请求转发器。
请求转发器中重试 / 不可重试错误的分类更准确。
接管检测更紧；关接管时走 fallback 恢复，避免遗留状态把供应商卡住。
tool_choice 互转格式转换时把 Anthropic 的 tool_choice 正确映射到 OpenAI Chat 的嵌套形式。
Gemini 请求模型从 URI 路径提取（不再从 body 取），转换后的流量上报正确的模型名。
get_auth_headers 现在返回 Result，凭据有问题时不再 panic。
代理面板现在接受 IPv6 监听地址。
通过稳定缓存键派生提高 Codex 与 OpenAI Responses 请求的缓存命中率；只在客户端确实带了会话标识时才发 prompt_cache_key，避免不相关对话被坍缩到同一个 key 上；对外请求体与 tool_call 参数 / tool_result 内容里的 JSON key 做规范化排序以便前缀缓存能字节级匹配；把 session_id 串到 usage 日志记录器做请求关联。
私参过滤现在保留 JSON Schema name map（properties、patternProperties、definitions、$defs）内的下划线前缀字段名，用户自定义 schema key（如 _id、_meta）能正常穿过过滤。
从 Read 工具输入中剔除空白页，避免供应商拒绝请求 (#2472, 感谢 @Kwensiu)。
缩减每个请求的热路径开销和数据库等待时间。
接管运行时，Claude Code 菜单现在暴露真实供应商模型名，不是陈旧的 alias。
message_delta 总是带 usage最终 message_delta 事件现在总是包含 usage 块（即使全为 0），严格 Anthropic 客户端不再因为 null 崩溃 (#2485, 感谢 @Myoontyee)。
message_delta 去重对某些上游会发两次的 message_delta 事件做去重 (#2366, 感谢 @codeasier)。
reasoning_content 保留工具调用路径转换时正确保留 scoped reasoning_content 字段；Kimi / Moonshot 的 OpenAI Chat 兼容路径保留该字段，通用 OpenAI 兼容请求保持不带 (#2367, 感谢 @codeasier)。
Vertex AI 的完整 URL 在代理转发时不再被截断 (#2415, 感谢 @xpfo-go)。
某些上游会在 system message 开头插一段计费 header 内容，现在被剥离 (#2350)。
ANTHROPIC_* 环境变量名派生不再依赖不透明的启发式，鉴权策略从实际的 ANTHROPIC_* 环境变量名派生。
对那些不一致实现 /v1/models 的第三方 Claude 网关，关闭模型探测。
/models/models 发现现在对 Anthropic 兼容的子路径供应商生效。
/modelsCopilot 后端的供应商现在用实时 /models 列表来比对 Claude 模型 ID，避免陈旧 ID 不一致。
environment_contextCodex 会话标题提取不再把 environment_context 的噪声拉进来 (#2439, 感谢 @eclipsehx)。
Codex subagent 会话从主会话列表隐藏 (#2445, 感谢 @LanternCX)。
修复 Codex 启动期 live import 路径里的重复导入 bug (#2590, 感谢 @DhruvShankpal)。
切换激活 Codex 供应商不再改动现有会话历史 (#2349, 感谢 @SaladDay)。
修正一条 Codex 会话用量的误导性日志 (#2473, 感谢 @tisonkun)。
max effort 通过 env 持久化max effort 现在能跨重启正确通过 env 变量持久化 (#2493, 感谢 @makoMakoGo)。
[1M] 后缀路由匹配不再要求遗留的 [1M] 后缀。
修复 Claude Desktop 供应商表单中输入框编辑时丢失焦点的问题。
移除代理主动停止时假触发的提示。
当 Claude Desktop 是激活应用时，空的工具栏胶囊会被隐藏。
在 App 切换器里居中 Monitor 徽章图标。
防止在 Linux 上选择主题触发 segfault (#2502, 感谢 @definfo)。
防止冷启动时把不存在的 iTerm 选为 fallback (#2448, 感谢 @hulkbig)。
配置写入现在按字母序排 JSON key，输出确定 (#2469, 感谢 @fuleinist)。
"导入已有"操作改为无副作用 (#2429, 感谢 @xwil1)。
修正智谱周窗口的等级名以匹配实际重置时间 (#2420, 感谢 @TuYv)。
强化 DashScope usage 解析，畸形 payload 不会再让 VSCode Claude Code 插件崩 (#2425, 感谢 @magucas)。
跨代理和会话日志两个来源的用量记录去重。
修正缓存成本语义，并消除每个请求都触发的噪声定价警告。
恢复前端格式化与 Linux clippy 在 CI 中的运行。
修复代理测试 helper 中的一个 clippy 警告。
移除原本计划在本周期上线的 Hermes Agent 用量追踪集成——上游行为变化让维护这个集成变得不切实际。该集成从未在任何已发布版本中启用；开发过程中发现的"零成本渲染" bug 在回滚集成前已经修复。
移除主题切换时的圆形扩散动画——在性能较弱的合成器上会卡顿，视觉收益有限。
移除 DDSHub 作为合作伙伴预设，并删除各 README 中的交叉链接段落。
新增 BytePlus、ClaudeCN、RunAPI、PatewayAI 赞助商条目；交叉链接 BytePlus 与火山条目；刷新 CrazyRouter 的 $2 额度领取流程、Compshare 描述、Right Code 描述、其他赞助商的 logo 与列表项；把 LionCC logo 抹平到白底；中文 README 的赞助商 logo 切到火山图；在 README 副标题中加入 Hermes Agent。
Release notes 模板中呈现 ccswitch.io。
在各 README 与应用内引用中把 ccswitch.io 文档化为唯一官方网站。
这 20 个预设之前默认通过代理路由，现在默认直连。如果你升级前正好用着其中某个、又依赖代理路由的连通性（比如代理里有特殊补正器或转换层），请验证一下连通性；如有需要，可在 CC Switch 面板里手动切回代理模式。
切换 Claude Desktop 供应商需要重启 Claude Desktop 才能生效；代理模式的供应商在使用期间需要 CC Switch 的 Local Routing 保持运行——退出 CC Switch 或停止 Local Routing 会让代理模式的 Claude Desktop 供应商断流。
启用 Failover 前请先确认目标应用的 Local Routing 接管已开启，否则 Failover 控件会拒绝启动；想关代理服务但仍有应用依赖接管的情况会被拦下，需要先在应用层关掉接管再停代理。
用量摘要现在用缓存归一化的真实总 token + 缓存命中率。历史 token 与成本数字在数据去重 + 价格重算后可能会有偏移——新数字更准，但不会等于旧版给出的数字。
本版本在涉及反向代理类功能上沿用 v3.12.3 / v3.13.0 提出的风险提示。
GitHub Copilot 反向代理：使用 Copilot 的反代路径可能违反 GitHub / Microsoft 服务条款。详情见 v3.12.3 release notes。
Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。
Claude Desktop 第三方供应商代理切换：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，第三方供应商对计费、合规与数据留存的约束各不相同，请在使用前阅读目标供应商的服务条款。
用户启用上述功能即表示自行承担所有风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
访问 Releases 下载对应版本。
| 系统 | 最低版本 | 架构 |
|---|---|---|
| Windows | Windows 10 及以上 | x64 |
| macOS | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
| Linux | 见下表 | x64 / ARM64 |
| 文件 | 说明 |
|---|---|
CC-Switch-v3.15.0-Windows.msi | 推荐 - MSI 安装包，支持自动更新 |
CC-Switch-v3.15.0-Windows-Portable.zip | 便携版，解压即用，不写入注册表 |
| 文件 | 说明 |
|---|---|
CC-Switch-v3.15.0-macOS.dmg | 推荐 - DMG 安装包，拖入 Applications 即可 |
CC-Switch-v3.15.0-macOS.zip | 解压后拖入 Applications，Universal Binary |
CC-Switch-v3.15.0-macOS.tar.gz | 用于 Homebrew 安装和自动更新 |
macOS 版本已通过 Apple 代码签名和公证，可直接安装使用。
brew tap farion1231/ccswitch
brew install --cask cc-switch
更新：
brew upgrade --cask cc-switch
Linux 资产同时提供 x86_64 和 ARM64（
aarch64）两种架构。资产文件名中包含架构标识，请按你机器的uname -m输出选择对应版本：
CC-Switch-v3.15.0-Linux-x86_64.AppImage/.deb/.rpmCC-Switch-v3.15.0-Linux-arm64.AppImage/.deb/.rpm
| 发行版 | 推荐格式 | 安装方式 |
|---|---|---|
| Ubuntu / Debian / Linux Mint / Pop!_OS | .deb | sudo dpkg -i CC-Switch-*.deb 或 sudo apt install ./CC-Switch-*.deb |
| Fedora / RHEL / CentOS / Rocky Linux | .rpm | sudo rpm -i CC-Switch-*.rpm 或 sudo dnf install ./CC-Switch-*.rpm |
| openSUSE | .rpm | sudo zypper install ./CC-Switch-*.rpm |
| Arch Linux / Manjaro | .AppImage | 添加执行权限后直接运行，或使用 AUR |
| 其他发行版 / 不确定 | .AppImage | chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage |