CC Switch v3.12.3 深度解析：GitHub Copilot 反向代理、Reasoning Effort 映射与 Skill 备份恢复生命周期

本篇基于 CC Switch 官方发布说明 docs/release-notes/v3.12.3-zh.md，完整覆盖 v3.12.3（2026-03-24 发布，36 commits / 107 files changed / +9,124 / -802 lines）的全部更新内容：GitHub Copilot 反向代理与 Auth Center、macOS 代码签名与公证、Reasoning Effort 两级映射、Tool Search 环境变量开关、OpenCode SQLite 会话后端、Skill 备份/恢复生命周期，以及代理 gzip 压缩、o 系列模型兼容性等变更与十余项 Bug 修复，并结合仓库源码逐条印证底层实现。读完本文，你将理解该版本每项功能在代理转换层、会话管理层与前端配置层的具体落点，以及启用 Copilot 反向代理前必须知晓的合规风险。

发布概览

v3.12.3 是 CC Switch 的一次功能密度很高的版本，主线包括：

• GitHub Copilot 反向代理：新增 Copilot 反向代理支持，通过 Copilot Auth Center 管理 GitHub Token 认证，实现 Copilot 模型在 Claude Code 中的无缝使用
• macOS 代码签名与公证：macOS 版本已通过 Apple 代码签名和公证，新增 DMG 安装格式，无需再手动绕过“未知开发者”警告
• Reasoning Effort 映射：代理层自动映射 —— 显式 output_config.effort 优先，回退到 budget_tokens 阈值（<4000→low, 4000–16000→medium, ≥16000→high），支持 o 系列和 GPT-5+ 模型
• Tool Search 环境变量开关：利用 Claude 2.1.76+ 原生 ENABLE_TOOL_SEARCH 环境变量，在通用配置编辑器中一键启用 Tool Search
• Skill 备份/恢复生命周期：卸载前自动备份 Skill 文件；新增备份列表、恢复和删除管理
• OpenCode SQLite 后端：为 OpenCode 新增 SQLite 会话存储（与现有 JSON 后端并存），ID 冲突时 SQLite 优先的双后端扫描
• Codex 1M 上下文窗口开关：配置编辑器中一键设置 model_context_window = 1000000，自动填充 model_auto_compact_token_limit
• 禁用自动升级开关：通用配置编辑器中新增 DISABLE_AUTOUPDATER 环境变量复选框
• 代理 Gzip 压缩：非流式代理请求自动协商 gzip 压缩，减少带宽消耗
• o 系列模型兼容性：Chat Completions 代理正确使用 max_completion_tokens 处理 o1/o3/o4-mini 模型
• Skills 导入重构：将基于文件系统的隐式应用推断替换为显式的 ImportSkillSelection，防止多应用错误激活

以下按功能逐项展开，并给出仓库内可核查的源码位置。

GitHub Copilot 反向代理与 Copilot Auth Center

v3.12.3 新增完整的 GitHub Copilot 集成，将其作为 Claude Code 供应商接入。核心能力包括：

• 通过 OAuth Device Code 流程进行 GitHub 认证（无需本地回调服务，适合桌面应用场景）
• 支持多账号管理和自动 Token 刷新
• Anthropic ↔ OpenAI 格式自动转换，使 Claude Code 协议请求可以透传给 Copilot 后端
• 实时获取可用模型列表和用量统计（#930，感谢 @Mason-mengze）

在设置中新增的 Copilot Auth Center 认证中心面板可全局管理 GitHub 账号，支持按供应商绑定账号（通过 meta.authBinding），并提供统一的 Token 管理和刷新机制。

从源码结构看，该功能集中在代理的 providers 目录下：Copilot 认证模块 实现了标准 OAuth 设备码流程——GitHubDeviceCodeResponse 结构体持有 device_code 与 user_code，后续以 grant_type=urn:ietf:params:oauth:grant-type:device_code 轮询换取访问令牌（见 copilot_auth.rs 中的 github_device_code_url 与令牌交换逻辑）。配套还有 Copilot 模型映射表 与 copilot_optimizer.rs，分别负责模型名映射与请求优化；转发层中还专门处理了统一所有 Copilot API 调用点的请求指纹头，防止 User-Agent 泄漏和 Stream Check 不匹配（本次版本 Bug 修复项之一）。

风险提示

GitHub Copilot 反向代理免责声明：本版本的 Copilot 反向代理功能通过逆向工程的非官方 API 访问 GitHub Copilot 服务。启用此功能前请注意以下风险：

1. 违反服务条款：此功能可能违反 GitHub 可接受使用政策和附加产品条款，其中禁止过度自动化批量活动、未经授权的服务复制以及通过自动化手段对服务器施加不当负担。
2. 账号风险：已有类似工具的用户收到 GitHub 官方警告邮件，指出其存在“脚本化交互或其他刻意的异常或高强度使用”行为。收到警告后继续使用可能导致 Copilot 访问权限被暂停甚至永久封禁。
3. 无法保证长期可用：GitHub 可能随时更新其检测机制，当前可用的使用方式未来可能被标记。

用户启用此功能即表示自行承担所有风险。CC Switch 不对因使用此功能而导致的任何账号限制、警告或服务暂停承担责任。

macOS 代码签名与 Apple 公证

CI 流程新增完整的 macOS 代码签名和 Apple 公证支持：

• 导入 Apple Developer ID 证书，签名 Universal Binary
• 提交 Apple 公证并将票据装订到 .app 和 .dmg
• 硬性验证步骤（codesign --verify + spctl -a + stapler validate）把关发布

配套地，用户手册的 README、安装指南和 FAQ 中所有 xattr 变通方案和“未知开发者”警告说明已被移除，替换为“已通过 Apple 代码签名和公证”的说明。仓库中 dmg-background.png 即为新增 DMG 安装格式的窗口背景素材。macOS 发行文件因此新增推荐的 CC-Switch-v3.12.3-macOS.dmg（见文末下载与安装章节）。

Reasoning Effort 两级映射：源码级解析

新增的代理层自动推理强度映射是本次版本中实现细节最丰富的特性，支持 OpenAI o 系列和 GPT-5+ 模型。

两级解析规则（与源码 transform.rs 中的 resolve_reasoning_effort 实现一致）：

1. 显式 output_config.effort 优先：low/medium/high 一一对应透传；max 映射为 OpenAI 侧的 xhigh（主流 GPT 模型支持的最大推理档）；未知值不注入
2. 回退到 thinking.type + budget_tokens 阈值：
   • adaptive → xhigh（adaptive 即最大推理强度）
   • enabled 且带 budget：< 4000 → low；4000–15999 → medium；≥ 16000 → high
   • enabled 但缺 budget → 保守取 high
   • disabled 或缺失 → 不注入

模型侧的准入判断由 supports_reasoning_effort 完成（transform.rs）：o 系列（o1、o3、o4-mini 等）、gpt-5 及更高主版本（gpt-5.x、gpt-5-codex 等），此外还覆盖 xAI 的 grok-4.5 家族与旧版 grok-build-* 命名。测试套件中可见 supports_reasoning_effort("o1")、supports_reasoning_effort("o3-mini")、supports_reasoning_effort("gpt-5") 等断言（transform.rs 测试）。

发布说明称该映射覆盖 Chat Completions 和 Responses API 两条路径，含 17 个单元测试；从源码结构看，两条路径分别由 transform_codex_chat.rs 与 transform_responses.rs 承载，均复用上述解析函数，保证两条协议路径推理强度行为一致。

Tool Search 开关与禁用自动升级开关

本版本利用 Claude 2.1.76+ 原生的 ENABLE_TOOL_SEARCH 环境变量控制 Tool Search 功能，替代了之前的二进制补丁方案，更简洁可靠（#930，感谢 @Mason-mengze）。同时 Claude 通用配置编辑器中新增禁用自动升级复选框：勾选后设置 DISABLE_AUTOUPDATER=1，阻止 Claude Code 自动升级；两个开关与 Teammates 模式、高强度思考等开关同一排显示。

前端实现位于 CommonConfigEditor.tsx：Tool Search 复选框勾选时写入 config.env.ENABLE_TOOL_SEARCH = "true"，取消勾选时删除该键；禁用自动升级复选框勾选时写入 config.env.DISABLE_AUTOUPDATER = "1"，取消时同样删除。后端服务层 provider/mod.rs 中对 ENABLE_TOOL_SEARCH 亦有对应的读写与校验逻辑，保证通用配置编辑器中的开关最终落到供应商的 env 配置段。

OpenCode SQLite 会话后端

为 OpenCode 新增 SQLite 会话存储支持（与现有 JSON 后端并存），实现在 session_manager/providers/opencode.rs 中。关键设计：

• 双后端扫描，ID 冲突时 SQLite 优先：源码中先调用 scan_sessions_sqlite() 取 SQLite 会话，若结果为空再回退 JSON 扫描；合并时以 sqlite_ids 集合去重，SQLite 来源的会话始终保留（见 opencode.rs 的合并逻辑）
• SQLite 来源引用：会话来源以 sqlite:<db_path>:<session_id> 格式编码，解析函数 parse_sqlite_source 负责还原数据库路径与会话 ID
• 原子会话删除和路径校验：删除前先做路径校验，避免越界操作
• JSON 后端保持向后兼容：老用户已有的 JSON 会话数据无需迁移即可继续读取

Codex 1M 上下文窗口开关

配置编辑器中新增 Codex 1M 上下文窗口一键开关：

• 勾选后在 config.toml 中设置 model_context_window = 1000000
• 启用时自动填充 model_auto_compact_token_limit = 900000
• 关闭时干净移除两个字段

该开关面向需要长上下文场景的 Codex 用户，避免手动编辑 config.toml。

Skill 备份/恢复生命周期

v3.12.3 为 Skill 卸载引入了完整的备份/恢复生命周期，实现集中在 skill.rs：

卸载自动备份

• 备份存储在 ~/.cc-switch/skill-backups/，包含所有 skill 文件和记录原始元数据的 meta.json（源码中由 get_app_config_dir().join("skill-backups") 定位，见 skill.rs）
• 旧备份自动清理：SKILL_BACKUP_RETAIN_COUNT 常量限制最多保留 20 个备份（skill.rs），超出即删除最旧的
• 备份路径返回前端并在成功提示中显示

备份恢复与删除

• 列出所有可用的 skill 备份及元数据
• 恢复操作将文件拷回 SSOT，保存数据库记录，并同步到当前应用，失败时自动回滚
• 删除操作在确认对话框后移除备份目录

变更：代理 gzip、模型兼容与预设更新

代理 Gzip 压缩

非流式请求允许 reqwest 自动协商 gzip 并透明解压响应，流式请求保守地保持 Accept-Encoding: identity，避免中断的 SSE 流解压出错。从源码结构看，这一区分体现在转发层 forwarder.rs：转换/SSE 路径通过 force_identity_encoding 强制写入 identity 并补全缺失的 accept-encoding 头，其余普通路径保留原始值交由 reqwest 协商。

o1/o3 模型兼容性

• Chat Completions 路径对 o1/o3/o4-mini 模型使用 max_completion_tokens 替代 max_tokens（#1451，感谢 @Hemilt0n）
• Responses API 路径保持使用正确的 max_output_tokens 字段

transform_codex_chat.rs 中可见将 max_tokens 重写为 max_completion_tokens 的字段迁移逻辑。

Skills 缓存策略优化

• 将 invalidateQueries 替换为直接 setQueryData 更新，用于 skill 安装/卸载/导入操作
• 新增 staleTime: Infinity 和 keepPreviousData，消除加载闪烁（#1573，感谢 @TangZhiZzz）

Skills 导入流程

• 将基于文件系统的隐式应用推断替换为显式的 ImportSkillSelection，防止同一 skill 目录存在于多个应用路径时错误激活多个应用
• 为 sync_to_app 增加协调逻辑，移除已禁用/孤立的符号链接
• MCP sync_all_enabled 现在会从 live 配置中移除已禁用的服务器

模型预设更新

• Claude 4.6 上下文窗口：Claude Opus 4.6 和 Sonnet 4.6 上下文窗口从 200K 更新至 1M（GA 发布）
• MiniMax 模型升级：预设从 M2.5 升级至 M2.7，更新三语合作伙伴描述
• 小米 MiMo 模型升级：预设从 mimo-v2-flash 升级至 mimo-v2-pro
• OpenCode 模型变体：将模型变体放在预设顶层而非嵌套在 options 内部，提升可发现性（#1317）

供应商表单交互简化

• 添加供应商对话框移除冗余的 OAuth 标签页，从 3 个标签页减少到 2 个（应用专属 + 通用）
• Claude 供应商表单中的模型映射、API 格式等高级字段在未填写时默认折叠；预设填充值后自动展开，手动清空不会自动折叠

Bug 修复

问题	修复方式
WebDAV 密码被静默清除	ProviderList 或 UsageScriptModal 保存设置时 WebDAV 密码被清空；前端 payload 中剥离 webdavSync，后端 merge_settings_for_save() 增加回填逻辑保护现有密码
工具消息解析	修复 Claude（tool_result content blocks）、Codex（function_call/function_call_output payloads）和 Gemini（array content + toolCalls extraction）的 tool_use/tool_result 消息分类（#1401，感谢 @BlueOcean223）
暗色模式选择器	Tailwind darkMode 从 ["selector", "class"] 改为 ["selector", ".dark"]，确保暗色模式正确激活（#1596，感谢 @qinxiandiqi），配置位于 tailwind.config.cjs
Copilot 请求指纹	统一所有 Copilot API 调用点的请求指纹头，防止 User-Agent 泄漏和 Stream Check 不匹配
供应商表单防重复提交	修复快速连续点击按钮时供应商添加/编辑表单重复提交的问题（#1352，感谢 @Hexi1997）
Ghostty 终端会话恢复	修复在 Ghostty 终端中恢复 Claude 会话失败的问题（#1506，感谢 @canyonsehun）
Skill ZIP 导入扩展名	ZIP 导入对话框现在支持 .skill 文件扩展名（#1240、#1455，感谢 @yovinchen）
Skill ZIP 安装目标应用	ZIP 方式安装的 skill 现在使用当前活跃应用，而非始终默认为 Claude
OpenClaw 活跃供应商高亮	修复 OpenClaw 当前激活的供应商卡片未高亮显示的问题（#1419，感谢 @funnytime75）
响应式布局与 TOC	改善存在 TOC 标题时的响应式布局（#1491，感谢 @West-Pavilion）
Skills 导入对话框白屏	在 ImportSkillsDialog 中补充缺失的 TooltipProvider，修复打开对话框时的运行时崩溃
面板底部空白区域	将所有内容面板的硬编码 h-[calc(100vh-8rem)] 替换为 flex-1 min-h-0，消除因不同平台偏移量不匹配导致的底部空白

文档更新

• 定价模型 ID 归一化：在中英日三语用户手册（如 3.3-skills.md 同级的定价章节）中新增模型 ID 归一化规则说明（前缀剥离、后缀修剪、@→- 替换）（#1591，感谢 @makoMakoGo）
• macOS 签名与公证说明：移除 README、安装指南和 FAQ 中所有 xattr 变通方案和“未知开发者”警告，替换为“已通过 Apple 代码签名和公证”的说明

下载与安装

访问项目的 Releases 页面下载对应版本。

系统要求

系统	最低版本	架构
Windows	Windows 10 及以上	x64
macOS	macOS 12 (Monterey) 及以上	Intel (x64) / Apple Silicon (arm64)
Linux	见下表	x64

Windows

文件	说明
CC-Switch-v3.12.3-Windows.msi	推荐 - MSI 安装包，支持自动更新
CC-Switch-v3.12.3-Windows-Portable.zip	便携版，解压即用，不写入注册表

macOS

文件	说明
CC-Switch-v3.12.3-macOS.dmg	推荐 - DMG 安装包，拖入 Applications 即可
CC-Switch-v3.12.3-macOS.zip	解压后拖入 Applications，Universal Binary
CC-Switch-v3.12.3-macOS.tar.gz	用于 Homebrew 安装和自动更新

macOS 版本已通过 Apple 代码签名和公证，可直接安装使用。

Homebrew（macOS）

brew tap farion1231/ccswitch
brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

Linux

发行版	推荐格式	安装方式
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

小结

v3.12.3 的核心价值在于让 CC Switch 的代理层进一步“协议感知化”：Reasoning Effort 两级映射、max_completion_tokens 字段修正与 gzip/identity 分流，都在转发路径上按模型家族与请求形态做了精细区分；Copilot 反向代理与 Auth Center 则把桌面端的 OAuth 设备码流程、多账号令牌管理与模型映射整合进了既有代理架构。对于希望把 GitHub Copilot 作为 Claude Code 供应商使用的读者，务必先阅读本文风险提示一节，确认账号风险可接受后再启用；而 Skill 备份/恢复生命周期与 macOS 官方签名则为日常使用提供了数据安全感与安装信任度的双重保障。