CC Switch v3.7.0 发布解析：Gemini CLI 集成、MCP 统一架构与从配置切换到 AI CLI 管理平台的演进

CC Switch v3.7.0 是该项目从“AI CLI 供应商切换器”走向“All-in-One AI CLI 管理平台”的关键版本：它以约 1.8 万行新增代码引入了 Gemini CLI 集成、MCP 统一管理架构、Claude Skills 技能生态与 Prompts 提示词管理系统四大核心模块。本文基于官方发布说明（v3.7.0 英文版 / 中文版）展开，并结合当前仓库中的 Rust 后端源码与测试用例，逐条印证各功能的实际实现方式，帮助读者完整掌握该版本的能力边界、配置机制与底层原理。

版本概览：一次“平台化”的大版本

v3.7.0 的发布说明给出了清晰的量化基线（发布日期 2025-11-19）：

维度	数据
提交数	v3.6.0 之后共 85 个 commit
文件变更	152 个文件
代码变更	+18,104 / -3,732 行
新增功能	6 项主要功能

新增代码的模块分布大致为：Skills 管理约 2,034 行（21 个文件）、Prompts 管理约 1,302 行（20 个文件）、Gemini 集成约 1,000 行、MCP 重构约 3,000 行。发布说明将该版本定位为“从工具到平台”的转折点——从 v3.6 的“供应商切换器”（管理 Claude + Codex 两个应用的配置），升级为管理 Claude + Codex + Gemini 三个应用、并可扩展能力（Skills）、可视化定制行为（Prompts）的统一管理平台。

Gemini CLI 集成：第三个受支持应用

v3.7.0 最重要的功能是完整接入 Google Gemini CLI，使其成为继 Claude Code、Codex 之后第三个受支持的应用。其核心能力包括：

• 双文件配置：同时支持 .env 与 settings.json 两种 Gemini 配置格式；
• 自动检测：自动识别 GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL 等关键环境变量；
• 完整 MCP 支持：为 Gemini 提供与 Claude/Codex 对等的 MCP server 管理；
• 深链集成：通过 ccswitch:// 协议导入供应商配置；
• 系统托盘：从托盘菜单快速切换 Gemini 供应商。

官方预置了三类供应商：Google Official（OAuth 认证）、PackyCode（合作方集成）、Custom（完全自定义）。

源码印证：双文件配置与原子写入

当前仓库中该功能的后端主体是 gemini_config.rs，其实现细节与发布说明高度吻合，且包含若干值得注意的工程决策：

1. .env 的宽松/严格双模式解析。parse_env_file() 采用宽松策略：跳过空行与 # 注释行，仅接受 KEY=VALUE 形式且 key 由字母、数字、下划线组成的行，遇到无效行直接忽略，保证读取现有配置时不会因脏数据而崩溃；同时预留了 parse_env_file_strict()，在遇到缺少 =、空 key 或非法 key 时返回携带行号的本地化错误，用于配置导入校验等严格场景。这种“读取宽松、写入严格”的分层设计在源码注释中有明确说明。
2. settings.json 写入策略。get_gemini_settings_path() 返回 ~/.gemini/settings.json（与 .env 同级）。针对不同供应商有不同的写入入口：write_google_oauth_settings() 面向 Google 官方 OAuth 模式，write_packycode_settings() 面向 PackyCode 供应商；两者都会先读取现有 settings.json（如果存在）再做合并更新，避免破坏用户已有的其他字段。
3. 原子写入。write_gemini_env_atomic() 与 write_gemini_settings() 相关函数确保配置写入采用“写临时文件再替换”的原子模式，防止写一半失败导致配置损坏——这正是发布说明中“Dual-file atomic writes”的具体落点。
4. 可覆盖的配置目录。get_gemini_dir() 支持通过设置项覆盖默认的 ~/.gemini 路径，用户可以把 Gemini CLI 指向自定义目录，这一能力在 settings.rs 中有对应的读取接口。

单元测试直接覆盖了文档中提到的两个关键变量。例如测试中构造了包含 GOOGLE_GEMINI_BASE_URL=https://example.com、GEMINI_MODEL=gemini-3.5-flash 的 .env 样例，并断言序列化、去重、字段保留等行为正确。MCP 侧对应模块为 gemini_mcp.rs 与统一 MCP 子模块中的 mcp/gemini.rs。

前端与预设

前端侧，Gemini 表单与“环境变量编辑器”保持双向同步（发布说明中的 Form synchronization），供应商预设定义在 geminiProviderPresets.ts，其中包含 Google Official 与 PackyCode 等预设条目，相关行为由 tests/config/ 下的预设测试（如 codexChatProviderPresets.test.ts 同类的预设校验测试）覆盖。

MCP v3.7.0 统一架构：跨应用统一管理

v3.7.0 对 MCP 管理系统做了完整重构，目标是把此前各应用分散的 MCP 实现统一为一套跨应用架构：

• 统一面板：一个界面管理 Claude/Codex/Gemini 三个应用的 MCP servers；
• SSE 传输：新增 Server-Sent Events 传输方式支持；
• 智能解析器：容错的 JSON 解析，坏格式不再直接抛错；
• 格式纠正：自动修正 Codex TOML 中 [mcp_servers] 段落的格式问题；
• 扩展字段保留：用户自定义的 TOML 字段在往返编辑后原样保留，不被序列化吞掉。

用户体验层面包括：表单默认应用选择、用于校验的 JSON 格式化器、更清晰的视觉层级与错误提示；导入/导出层面则实现了三个应用之间的统一导入、双向同步与状态保持。

从当前仓库源码结构看，统一架构落在 src-tauri/src/mcp/ 目录下：claude.rs、codex.rs、gemini.rs 分别处理各应用的读写差异（后续版本还扩展到 opencode.rs、hermes.rs、grokbuild.rs），validation.rs 承担校验逻辑，mod.rs 组织统一入口。发布说明提到该重构删除了约 1,000 行旧代码并保持向后兼容——现有配置无需迁移。集成测试 mcp_commands.rs 对 MCP 命令的端到端行为提供了回归保障，前端对应 UnifiedMcpPanel.tsx 统一面板组件及 useMcp.ts 状态管理 Hook。

Claude Skills 管理系统：技能生态平台

Skills 模块是发布说明中体量最大的新功能（约 2,000 行），目标是把 Claude 的技能（Skill）生态纳入图形化管理。

GitHub 集成方面：

• 自动扫描 GitHub 仓库中的技能；
• 预配置仓库包括 ComposioHQ/awesome-claude-skills（精选合集）、anthropics/skills（Anthropic 官方）、cexll/myclaude（社区贡献），并支持添加自定义仓库；
• 支持子目录扫描（skillsPath 参数），仓库无需把技能放在根目录。

生命周期管理：

• Discover：自动检测 SKILL.md 文件；
• Install：一键安装到 ~/.claude/skills/；
• Uninstall：带追踪的安全卸载；
• Update：更新检查基础设施就绪（在 v3.7.0 中尚未完整开放）。

技术架构（按发布说明口径）：后端 SkillService 封装 GitHub API 集成，前端由 SkillsPage、SkillCard、RepoManager 三个组件构成，UI 基于 shadcn/ui 的 Badge/Card/Table 组件，持久化存储在 skills.json，国际化覆盖 47+ 翻译键。

在当前仓库中，该模块的主体是 services/skill.rs——注意该文件在后续版本中已大幅演进（当前约 6,000 行，远超 v3.7.0 时的 526 行基线），说明 Skills 是发布后迭代最活跃的后端模块之一；命令层入口在 commands/skill.rs，前端对应 SkillsPage.tsx、SkillCard.tsx 与 RepoManagerPanel.tsx。回归测试见 skill_sync.rs。

Prompts 管理系统：系统提示词的可视化定制

Prompts 模块（约 1,300 行）提供了完整的系统提示词预设管理：

多预设管理：可创建任意数量提示词预设、快速切换、同一时刻仅一个激活，且激活中的预设受删除保护。

跨应用文件映射：

应用	目标文件
Claude	~/.claude/CLAUDE.md
Codex	~/.codex/AGENTS.md
Gemini	~/.gemini/GEMINI.md

当前仓库中的 prompt_files.rs 完整印证了这一映射：prompt_file_path() 按应用类型返回对应目录与文件名（Claude→CLAUDE.md、Codex→AGENTS.md、Gemini→GEMINI.md），并对主目录不可解析的情况做了兜底处理；文件内的单元测试还断言了目录推导逻辑。可以看到，后续版本已将该机制扩展到 Grok Build、OpenCode、OpenClaw、Hermes 等更多应用（Hermes 使用 SOUL.md），但三应用的基本映射自 v3.7.0 起保持不变。

Markdown 编辑器：基于 CodeMirror 6 的完整编辑器，支持语法高亮、One Dark 深色主题与实时预览，对应前端组件 MarkdownEditor.tsx。

智能同步机制是该模块最值得关注的工程设计：

• Auto-write：保存即写入活动文件，无需手动应用；
• Backfill protection：切换预设前先把当前活动文件内容回填到对应预设，防止丢失用户手动改动；
• Auto-import：首次启动时自动从活动文件导入既有内容作为预设；
• Modification protection：保留对文件的直接手工修改，不被预设覆盖。

后端为 PromptService（发布说明口径 213 行），前端由 PromptPanel.tsx、PromptFormPanel.tsx 与 usePromptActions.ts 组成，测试覆盖见 PromptPanel.test.tsx 与 usePromptActions.test.tsx。

深链协议（ccswitch://）与环境变量冲突检测

深链协议：v3.7.0 在所有平台注册 ccswitch:// URL scheme，支持从共享链接一键导入供应商配置，并与应用生命周期、安全校验集成。源码入口在 src-tauri/src/deeplink/ 模块（供应商导入在 provider.rs、技能导入在 skill.rs），端到端行为由 deeplink_import.rs 测试验证，前端配套 DeepLinkImportDialog.tsx 确认对话框与风险检查逻辑 deeplinkRisk.ts。仓库根目录的 deplink.html 则用于演示深链唤起。

环境变量冲突检测：针对多应用共存时的配置冲突，提供跨应用（Claude 与 Codex）、Gemini 自动发现、MCP server 配置三个维度的检测，配套可视化冲突指示、解决建议、覆盖警告与“变更前备份”四类管理能力。

其他改进与缺陷修复

供应商预设：新增 DouBaoSeed（字节跳动豆包）、Kimi For Coding（Moonshot AI）、BaiLing 三个预设，移除 AnyRouter 以避免混淆；为 Codex 与 Gemini 增加模型名配置、为供应商增加备注（notes）字段以辅助组织。

配置管理：通用配置从浏览器 localStorage 迁移到 config.json 文件持久化，实现跨应用共享；首次启动自动导入；回填（backfill）时正确处理活动文件优先级。

UI/UX：采用对齐系统外观的 macOS 原生配色方案、窗口默认居中；修复了密码输入框在 Edge/IE 的显隐按钮问题、卡片中 URL 溢出、错误信息复制失败，以及托盘与拖拽排序的实时同步问题。

关键缺陷修复包括：用量脚本的边界检查、Gemini 校验约束放宽、TOML 解析对 CJK 引号的处理、MCP 自定义字段保留、FormLabel 崩溃导致的白屏问题；稳定性方面，托盘逻辑由 unwrap() 改为安全的模式匹配，使托盘故障不会阻塞主操作。

技术层面还涉及：MCP 旧代码清理（约 1,000 行）与统一初始化结构、Windows 下 winreg 0.52 的 API 适配、完整 TypeScript 类型覆盖与 Rust 类型精化；依赖方面包括 Tauri 2.8.x、Rust 侧 anyhow/zip/serde_yaml/tempfile、前端 CodeMirror 6 系列包。

系统要求、安装与迁移

系统要求（按发布说明）：

• Windows 10 及以上；
• macOS 10.15（Catalina）及以上；
• Linux：Ubuntu 22.04+ / Debian 11+ / Fedora 34+。

下载产物（以 Releases 页面为准，此处仅列命名）：Windows 提供 CC-Switch-v3.7.0-Windows.msi 或 -Portable.zip；macOS 提供 CC-Switch-v3.7.0-macOS.tar.gz 或 .zip；Linux 提供 CC-Switch-v3.7.0-Linux.AppImage 或 .deb。macOS 用户也可通过 Homebrew 安装与升级：

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

# 升级
brew upgrade --cask cc-switch

迁移说明：

• 从 v3.6.x 升级：自动迁移，无需任何操作，配置完全兼容；
• 从 v3.1.x 或更早版本升级：需两步走——先升级到 v3.2.x 完成一次性迁移，再升级到 v3.7.0；
• 新功能迁移：Skills 无需迁移、从零开始；Prompts 首次启动时自动从活动文件导入；Gemini 需自行安装 Gemini CLI；MCP 新架构向后兼容既有配置。

战略定位：六大支柱

发布说明用一张对比表总结了 v3.6 与 v3.7.0 的定位差异：身份从“Provider Switcher”变为“AI CLI Management Platform”，范围从配置管理扩展为生态管理，应用从 Claude+Codex 扩展为 Claude+Codex+Gemini，能力从“切换配置”扩展为“扩展能力（Skills）”，定制方式从手动编辑变为可视化管理（Prompts），集成方式从孤立应用变为统一管理（MCP）。

由此凝练出的“AI CLI 管理六支柱”为：

1. 配置管理——供应商切换与管理；
2. 能力扩展——Skills 安装与生命周期；
3. 行为定制——系统提示词预设；
4. 生态集成——深链与共享；
5. 多 AI 支持——Claude / Codex / Gemini；
6. 智能检测——冲突预防。

小结与延伸阅读

v3.7.0 的实质是把 CC Switch 从“配置文件切换器”重构为覆盖配置（Providers）、能力（Skills）、行为（Prompts）、集成（MCP + 深链）四个维度的 AI CLI 管理平台；其工程价值体现在双文件原子写入、宽松/严格双模式解析、回填保护等防御性设计上。发布说明中预告的 v3.8.0 本地代理功能（Local proxy）已在后续版本落地，当前仓库中可见完整的 src-tauri/src/proxy/ 实现。

如需进一步深入，建议按以下路径阅读当前仓库：版本历史见 CHANGELOG.md 与 docs/release-notes/ 目录；Gemini 配置实现见 src-tauri/src/gemini_config.rs；MCP 统一架构见 src-tauri/src/mcp/；Skills 与 Prompts 分别见 src-tauri/src/services/skill.rs 与 src-tauri/src/prompt_files.rs；集成测试入口在 src-tauri/tests/ 与 tests/ 目录。