cc-switch/docs/release-notes/v3.12.2-zh.md

CC Switch v3.12.2

代理接管期间通用配置保护、Snippet 生命周期稳定性、Codex TOML Section 感知编辑

English → | 日本語版 →

---

概览

CC Switch v3.12.2 是一个以可靠性为核心的补丁版本，重点解决代理（Proxy）接管模式下通用配置（Common Config）丢失的问题，并改进了 Codex TOML 配置的编辑准确性。代理接管的热切换和供应商同步现在会更新恢复备份而非直接覆盖 live 文件；启动流程重新排序，确保先从干净的 live 文件提取 Snippet 再恢复接管状态；Codex 的 base_url 编辑重构为 Section 感知模式，不再错误追加到文件末尾。

发布日期：2026-03-12

更新规模：5 commits | 22 files changed | +1,716 / -288 lines

---

重点内容

• 首次使用引导优化：供应商列表空状态显示详细的导入说明，Claude/Codex/Gemini 还会提示通用配置 Snippet 功能

• 代理接管恢复流程重构：热切换和供应商同步现在刷新恢复备份，而非覆盖 live 配置文件，回滚时保留完整的用户配置

• Snippet 生命周期稳定：引入 cleared 标志防止已清除的 Snippet 被自动重新提取，启动顺序调整确保从干净状态提取

• Codex TOML Section 感知编辑：base_url 和 model 字段的读写现在定位到正确的 [model_providers.<name>] Section

• Codex MCP 配置保护：热切换供应商时保留恢复快照中已有的 mcp_servers 配置块，按 server id 合并而非整表替换，供应商/通用配置的 MCP 定义优先

---

新功能

空状态引导优化

改善首次使用体验，当供应商列表为空时显示详细的导入说明。

• 空状态页面展示导入供应商的操作指引
• 对 Claude/Codex/Gemini 应用有条件地显示通用配置 Snippet 提示（OpenCode/OpenClaw 不显示）

---

变更

代理接管恢复流程

代理接管的热切换和供应商同步逻辑经过重构，确保通用配置在整个接管生命周期中得到保护。

• 接管活跃时，供应商同步更新恢复备份而非直接写入 live 配置文件
• 保存恢复快照前先应用通用配置，使回滚能还原真实的用户配置
• 遗留供应商中推断使用了通用配置的条目自动标记 commonConfigEnabled=true

Codex TOML 编辑引擎

将 Codex config.toml 的更新逻辑重构到共享的 Section 感知 TOML 辅助函数上。

• Rust 端新增 codex_config.rs 模块，包含 update_codex_toml_field 和 remove_codex_toml_base_url_if
• 前端新增 getTomlSectionRange / getCodexProviderSectionName 等 Section 感知工具函数
• proxy.rs 中散落的 TOML 内联编辑逻辑统一委托给新模块

通用配置初始化生命周期

启动流程重新排序，通用配置 Snippet 的提取和迁移逻辑更加健壮。

• 启动时先从干净的 live 文件自动提取通用配置 Snippet，再恢复代理接管状态
• 引入 Snippet cleared 标志，追踪用户是否主动清除了某个 Snippet
• 持久化一次性遗留迁移标志，避免重复执行旧版 commonConfigEnabled 回填

---

Bug 修复

通用配置丢失

• 修复代理接管期间通用配置可能被丢弃的多种场景：同步覆盖 live 文件、热切换产生不完整的恢复快照、供应商切换丢失配置变更

Codex 恢复快照保护

• 修复 Codex 接管恢复备份在供应商热切换时丢弃已有 mcp_servers 配置块的问题；将 MCP 备份保留策略从整表替换改为按 server id 合并，供应商/通用配置的 MCP 定义在冲突时优先，备份中独有的服务器仍被保留

已清除 Snippet 复活

• 修复启动时自动提取机制重新创建用户已主动清除的通用配置 Snippet 的问题

Codex base_url 位置错误

• 修复 Codex base_url 提取和编辑未定位到正确的 [model_providers.<name>] Section，导致追加到文件末尾或误将 mcp_servers.*.base_url 识别为供应商端点的问题

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

macOS

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

注意：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开

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