cc-switch v3.7.0 技术解析：Gemini CLI 集成、MCP 统一管理与 Skills/Prompts 管理体系的完整落地

本篇基于 cc-switch v3.7.0 中文发布说明（docs/release-notes/v3.7.0-zh.md），完整还原该版本的六大核心功能：Gemini CLI 集成、MCP 统一架构、Claude Skills 管理、Prompts 管理、ccswitch:// 深度链接协议与环境变量冲突检测，并结合当前仓库中的 Rust 后端源码与 React 前端组件，说明每项功能背后的实现机制、关键文件路径与数据格式，帮助读者理解 cc-switch 如何从一个"供应商切换器"演进为覆盖 Claude Code、Codex、Gemini 三个 AI CLI 的一体化管理平台。

版本概览与战略定位

发布日期：2025-11-19 提交数量：从 v3.6.0 开始 85 个提交 代码变更：152 个文件，+18,104 / -3,732 行

v3.7.0 代表了一个定位上的转变——从"供应商切换器"到"AI CLI 管理平台"：

方面	v3.6	v3.7.0
身份	供应商切换器	AI CLI 管理平台
范围	配置管理	生态系统管理
应用	Claude + Codex	Claude + Codex + Gemini
能力	切换配置	扩展能力（Skills）
定制	手动编辑	可视化管理（Prompts）
集成	孤立应用	统一管理（MCP）

围绕这一定位，v3.7.0 确立了 AI CLI 管理的六大支柱：

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

以下章节逐一拆解这六大支柱的技术实现。

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

v3.7.0 新增了对 Google Gemini CLI 的完整支持，使 cc-switch 成为同时管理三个 CLI 应用（Claude Code、Codex、Gemini）的工具。核心能力包括：

• 双文件配置：同时支持 ~/.gemini/ 目录下的 .env 和 settings.json 两种格式
• 自动检测：自动检测 GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL 等环境变量
• 完整 MCP 支持：为 Gemini 提供完整的 MCP 服务器管理
• 深度链接集成：通过 ccswitch:// 协议导入配置
• 系统托盘：从托盘菜单快速切换

供应商预设方面提供三类选项：Google Official（支持 OAuth 认证）、PackyCode（合作伙伴集成）、自定义（完全自定义）。前端预设定义见 src/config/geminiProviderPresets.ts。

双文件配置的实现：.env 解析

Gemini CLI 使用双配置文件：.env 存放环境变量（如 GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL），settings.json 存放结构化设置。后端模块 src-tauri/src/gemini_config.rs 负责这两个文件的读写。其中 .env 解析采用"宽松模式"，跳过空行与注释、对非法行静默容错，保证用户手工修改过的配置不会因为个别格式问题而整体不可读：

// src-tauri/src/gemini_config.rs
pub fn parse_env_file(content: &str) -> HashMap<String, String> {
    let mut map = HashMap::new();
    for line in content.lines() {
        let line = line.trim();
        // 跳过空行和注释
        if line.is_empty() || line.starts_with('#') {
            continue;
        }
        // 解析 KEY=VALUE
        if let Some((key, value)) = line.split_once('=') {
            // 验证 key 是否有效（不为空，只包含字母、数字和下划线）
            if !key.is_empty() && key.chars().all(|c| c.is_alphanumeric() || c == '_') {
                map.insert(key, value);
            }
        }
    }
    map
}

该文件还提供了一个带行号错误信息的严格解析函数 parse_env_file_strict（参见 src-tauri/src/gemini_config.rs#L74-L120），用于配置导入验证等场景，为诊断 .env 格式错误提供了具体到行号的报错能力。同时配置目录支持用户自定义覆盖（get_gemini_dir() 优先读取 settings 中的覆盖目录，否则回退到 ~/.gemini）。

Gemini 的 MCP 配置与传输类型推断

Gemini CLI 的 MCP 服务器配置在 ~/.gemini/settings.json 的 mcpServers 字段中。由于 Gemini 不显式声明传输类型，cc-switch 在读写时做了双向格式转换，将 Gemini 特有格式归一化为统一的 MCP 结构，参见 src-tauri/src/gemini_mcp.rs#L32-L72：

• httpUrl 字段 → 转换为 url + type: "http"
• 仅有 command 字段 → 推断为 type: "stdio"
• 仅有 url 字段 → 推断为 type: "sse"（即本次新增的 SSE 传输类型支持）

写入时使用 atomic_write（先写临时文件再原子替换），避免中途崩溃产生半写入的 JSON 文件；且只覆盖 mcpServers 字段，settings.json 中的其他字段保持不变。这套机制正是"双文件原子写入"与"表单-编辑器同步"在 Gemini 场景下的落地。

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

MCP 管理系统在 v3.7.0 中完成了整体重构，从各应用独立维护升级为跨应用统一管理。

架构改进

• 统一管理面板：单一界面管理 Claude/Codex/Gemini 的 MCP 服务器，对应前端组件 src/components/mcp/UnifiedMcpPanel.tsx，表单弹窗见 src/components/mcp/McpFormModal.tsx
• SSE 传输类型：新增 Server-Sent Events 支持（除 stdio、http 之外）
• 智能解析器：容错性 JSON 解析，对格式不完美的配置也能尽量恢复
• 格式修正：自动修复 Codex [mcp_servers] 段落格式
• 扩展字段：保留自定义 TOML 字段，不被归一化过程丢弃

后端模块划分

当前仓库中 MCP 逻辑按应用拆分为独立模块，统一挂载在 src-tauri/src/mcp/ 目录下：

• src-tauri/src/mcp/claude.rs —— Claude Code 的 MCP 读写
• src-tauri/src/mcp/codex.rs —— Codex 的 TOML [mcp_servers] 格式处理
• src-tauri/src/mcp/gemini.rs —— Gemini 的 settings.json 处理
• src-tauri/src/mcp/validation.rs —— 统一校验逻辑

各应用适配器共享同一套 MCP 服务器数据结构，这使"从三个应用统一导入、双向同步、状态保持"成为可能：导入时保留各应用的启用/禁用状态，同步时逐应用写入各自的配置格式。

用户体验改进

• 表单中的默认应用选择
• JSON 格式化器用于内容验证
• 改进的视觉层次与更好的错误消息

技术架构要点

按发布说明的统计，MCP 重构约 3,000 行，其中移除了约 1,000 行遗留代码，统一了初始化结构，并保持与之前版本的配置向后兼容。

Claude Skills 管理系统：技能生态的发现、安装与生命周期

Skills 管理是 v3.7.0 中体量最大的新功能（约 2,000 行代码，21 个文件），为 Claude Code 提供了完整的技能生态平台。

GitHub 仓库集成

系统从 GitHub 仓库自动扫描技能（以 SKILL.md 文件作为技能的发现标识）。按发布说明，v3.7.0 预配置了三个仓库：

• ComposioHQ/awesome-claude-skills —— 精选集合
• anthropics/skills —— Anthropic 官方技能
• cexll/myclaude —— 社区贡献

从当前源码看，默认仓库列表定义在 src-tauri/src/services/skill.rs#L159-L191 的 SkillStore::default() 中，此后又扩展了 JimLiu/baoyu-skills；每个仓库条目包含 owner、name、branch、enabled 四个字段，用户也可以添加自定义仓库，并支持 skillsPath 子目录扫描。

技能生命周期

• 发现：自动检测仓库中的 SKILL.md 文件并解析名称与描述（DiscoverableSkill 结构，唯一标识格式为 owner/name:directory）
• 安装：一键安装到技能目录（v3.7.0 阶段为 ~/.claude/skills/）
• 卸载：安全移除并跟踪状态
• 更新：更新检查基础设施已就绪（当前版本与远程哈希对比，参见 SkillUpdateInfo 结构，src-tauri/src/services/skill.rs#L210-L221）

从当前源码结构看，技能存储位置后续演进为可选 SSOT 目录（SkillStorageLocation 枚举，默认 ~/.cc-switch/skills/，可选统一的 ~/.agents/skills/），说明 v3.7.0 建立的"发现—安装—状态跟踪"框架为后续跨 Agent 的技能部署留下了扩展点。

技术架构

• 后端：SkillService 集成 GitHub API（发布说明标注约 526 行，当前 src-tauri/src/services/skill.rs 已扩展至近 6,000 行，反映了后续功能叠加）
• 前端：src/components/skills/SkillsPage.tsx（页面容器）、src/components/skills/SkillCard.tsx（技能卡片）、src/components/skills/RepoManagerPanel.tsx（仓库管理面板）
• UI 组件：基于 shadcn/ui 的 Badge、Card、Table
• 状态：持久化存储在 skills.json（仓库配置 + 安装状态）
• 国际化：47+ 个翻译键

Prompts 管理系统：系统提示词的多预设与跨应用同步

Prompts 管理（约 1,300 行代码，20 个文件）提供了完整的系统提示词管理能力。

多预设管理规则

• 可创建无限数量的提示词预设
• 快速在预设间切换
• 同一时间只能激活一个提示词
• 活动提示词删除保护——防止误删正在生效的预设

跨应用的文件映射

每个应用使用不同的提示词文件约定，映射关系由 src-tauri/src/prompt_files.rs#L12-L44 统一维护：

应用	提示词文件
Claude	~/.claude/CLAUDE.md
Codex	~/.codex/AGENTS.md
Gemini	~/.gemini/GEMINI.md

该函数在 v3.7.0 阶段覆盖上述三个应用；从当前源码结构看，映射表已扩展到 Grok Build、OpenCode、OpenClaw（AGENTS.md）、Hermes（SOUL.md）等更多应用，体现了同一套提示词框架的横向复用。

数据模型与智能同步

提示词的数据模型定义在 src-tauri/src/prompt.rs#L4-L16：id、name、content、可选的 description、enabled 标志以及创建/更新时间戳。发布说明描述的四项同步机制在实现上对应如下：

• 自动写入：激活预设时立即写入对应应用的 live 文件
• 回填保护：切换预设前，先把 live 文件的当前内容回填保存，避免用户在 CLI 里手动编辑的内容被覆盖
• 自动导入：首次启动时从 live 文件读取并导入为一个预设
• 修改保护：整体策略保留用户手动修改

Markdown 编辑器与前端结构

• 完整的 CodeMirror 6 集成：语法高亮、One Dark 暗色主题、实时预览，见 src/components/MarkdownEditor.tsx
• 前端组件：src/components/prompts/PromptPanel.tsx（主面板）、src/components/prompts/PromptFormPanel.tsx（表单）、src/components/prompts/PromptLibrary.tsx（预设库）
• Hooks：src/hooks/usePromptActions.ts 封装预设的增删改与激活动作
• 国际化：41+ 个翻译键

深度链接协议（ccswitch://）：一键导入供应商配置

v3.7.0 引入了 ccswitch:// URL 协议，实现通过共享链接一键导入配置，覆盖所有平台（Windows 注册表 / macOS URL Scheme / Linux 桌面条目），并集成应用生命周期与安全验证。

协议格式与解析

协议格式与严格校验逻辑见 src-tauri/src/deeplink/parser.rs#L11-L68。标准结构为：

ccswitch://v1/import?resource={type}&...

解析器强制执行三层校验：

1. Scheme 校验：必须为 ccswitch
2. 版本校验：host 必须是 v1（当前唯一受支持的协议版本）
3. 路径校验：必须是 /import

随后按 resource 参数分发到四类资源解析器（provider / prompt / mcp / skill）。以供应商导入为例，参数包含 app（目标应用）、name（供应商名称）以及 homepage、endpoint、apiKey 等字段；app 取值受白名单约束（当前源码中为 claude | codex | gemini | grokbuild | opencode | openclaw | hermes，v3.7.0 发布时至少覆盖 claude/codex/gemini）。

协议各资源类型分别由 src-tauri/src/deeplink/provider.rs、src-tauri/src/deeplink/prompt.rs、src-tauri/src/deeplink/mcp.rs、src-tauri/src/deeplink/skill.rs 实现，前端弹窗见 src/components/DeepLinkImportDialog.tsx，导入前的风险提示逻辑见 src/utils/deeplinkRisk.ts。测试覆盖位于 src-tauri/src/deeplink/tests.rs。

环境变量冲突检测：智能检测和管理配置冲突

由于 cc-switch 同时管理多个 CLI 应用的配置，环境变量冲突（如不同应用/供应商写入了同名变量）是真实风险。v3.7.0 的智能检测覆盖：

• Claude & Codex：跨应用冲突检测
• Gemini：.env 中的环境变量自动发现（依赖上文 parse_env_file 的键值解析）
• MCP：服务器配置冲突（同名服务器在不同应用中的定义差异）

配套的管理功能包括：可视化冲突指示器、解决建议、覆盖前警告、更改前自动备份。

供应商管理与其他改进优化

供应商预设变更

• 新增：DouBaoSeed（字节跳动的豆包）、Kimi For Coding（月之暗面）、BaiLing（百灵 AI）
• 移除：AnyRouter（避免误导）
• 增强：Codex 和 Gemini 的模型名称配置、供应商备注字段（用于组织）、增强的预设元数据

配置管理

• 通用配置迁移：从 localStorage 迁移到 config.json
• 统一持久化：跨所有应用共享
• 自动导入：首次启动配置导入
• 回填优先级：正确处理 live 文件

UI/UX 改进

设计系统：macOS 原生配色（与系统对齐）、窗口默认居中、改进的间距和视觉层次。

交互优化：密码输入框修复 Edge/IE 显示按钮问题、修复卡片中 URL 溢出、错误信息可复制到剪贴板、托盘菜单实时拖放同步。

Bug 修复与技术改进

关键修复

• 用量脚本验证：边界检查
• Gemini 验证：放宽约束
• TOML 解析：CJK 引号处理（中文引号曾导致 TOML 解析失败）
• MCP 字段：自定义字段保留
• 白屏：FormLabel 崩溃修复

稳定性

• 托盘安全：模式匹配替代 unwrap()，托盘失败不阻塞主操作（错误隔离）
• 导入分类：正确的类别分配

UI 修复

• 移除模型输入框的误导性占位符
• 第三方供应商 Base URL 自动填充
• 托盘菜单拖拽排序同步

平台兼容性与依赖

• Windows winreg API 升级至 0.52 修复
• 安全模式匹配（无 unwrap()）、跨平台托盘处理
• 核心依赖：Tauri 2.8.x；Rust 侧 anyhow、zip、serde_yaml、tempfile；前端 CodeMirror 6 系列包

技术统计

总体变更：
- 提交数：85
- 文件数：152 个文件变更
- 新增：+18,104 行
- 删除：-3,732 行

新增模块：
- Skills 管理：2,034 行（21 个文件）
- Prompts 管理：1,302 行（20 个文件）
- Gemini 集成：约 1,000 行
- MCP 重构：约 3,000 行重构

代码分布：
- 后端（Rust）：约 4,500 行新增
- 前端（React）：约 3,000 行新增
- 配置：约 1,500 行重构
- 测试：约 500 行

下载与安装

系统要求

• Windows：Windows 10+
• macOS：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 或更早版本升级

需要两步迁移：

1. 首先升级到 v3.2.x（执行一次性迁移）
2. 然后升级到 v3.7.0

新功能迁移

• Skills：无需迁移，全新开始
• Prompts：首次启动时从 live 文件自动导入
• Gemini：需要单独安装 Gemini CLI
• MCP v3.7.0：与之前的配置向后兼容

小结

v3.7.0 通过 Gemini 集成把管理范围从两个 CLI 扩展到三个，通过 MCP 统一架构把"配置散落各处"收敛为单一管理面板，再用 Skills 与 Prompts 两个新模块把管理对象从"连接供应商"延伸到"扩展能力"与"行为定制"，最后以 ccswitch:// 协议和冲突检测补全生态协作与安全网。对照仓库源码可以看到，这一版本奠定了几条至今仍可追溯的主线：按应用拆分的 MCP 适配层（src-tauri/src/mcp/）、SkillService 驱动的技能生命周期（src-tauri/src/services/skill.rs）、统一的提示词文件映射（src-tauri/src/prompt_files.rs）以及严格校验的深度链接解析器（src-tauri/src/deeplink/parser.rs）。中文发布说明的英文版本见 docs/release-notes/v3.7.0-en.md，完整历史见 CHANGELOG.md，项目总览见 README_ZH.md。