mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-23 09:29:13 +08:00
139 lines
6.7 KiB
Markdown
139 lines
6.7 KiB
Markdown
# CC Switch v3.12.2
|
||
|
||
> 代理接管期间通用配置保护、Snippet 生命周期稳定性、Codex TOML Section 感知编辑
|
||
|
||
**[English →](v3.12.2-en.md) | [日本語版 →](v3.12.2-ja.md)**
|
||
|
||
---
|
||
|
||
## 概览
|
||
|
||
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](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||
|
||
### 系统要求
|
||
|
||
| 系统 | 最低版本 | 架构 |
|
||
| ------- | ----------------------------- | ----------------------------------- |
|
||
| 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）
|
||
|
||
```bash
|
||
brew tap farion1231/ccswitch
|
||
brew install --cask cc-switch
|
||
```
|
||
|
||
更新：
|
||
|
||
```bash
|
||
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` |
|