CC Switch v3.7.0/v3.7.1 更新解析：Gemini CLI 集成、MCP 统一管理与 Skills 系统落地

本文基于 CC Switch 官方发布说明 v3.7.1 中文版本 撰写，覆盖 v3.7.1 的全部 Bug 修复与新功能（Skills 子目录仓库安装、Gemini 配置目录、对话框遮罩保护等），并完整继承 v3.7.0 的完整更新说明：Gemini CLI 集成、MCP 统一管理架构、Claude Skills 生命周期管理、Prompts 系统提示词管理、ccswitch:// 深度链接协议与环境变量冲突检测。读完本文后，你将理解这一版本从"供应商切换器"向"AI CLI 一体化管理平台"定位转变的具体能力，并能对照当前仓库源码验证每项功能的实现位置。

版本概览

CC Switch 是面向 Claude Code、Codex 等 AI CLI 工具的跨平台桌面助手（后续版本扩展到 OpenCode、OpenClaw、Grok Build、Hermes Agent 等）。v3.7 系列是整个产品线上的一次关键迭代：

版本	发布日期	代码变更	定位
v3.7.0	2025-11-19	152 个文件，+18,104 / -3,732 行（自 v3.6.0 起 85 个提交）	从供应商切换器到 AI CLI 一体化管理平台
v3.7.1	2025-11-22	17 个文件，+524 / -81 行	稳定性增强与用户体验改进

v3.7.1 更新内容：Bug 修复与新增功能

v3.7.1 是一个小型但关键的稳定性版本，发布说明将其概括为"稳定性增强与用户体验改进"，包含 3 项 Bug 修复和 2 项新增功能。

修复 Skills 第三方仓库安装失败（#268）

v3.7.0 引入的 Skills 管理系统在安装带有自定义子目录的仓库时存在缺陷，v3.7.1 修复了此类仓库（如 ComposioHQ/awesome-claude-skills）无法安装的问题。

在当前仓库源码中可以验证这一能力仍然存在且更加完善。Skill 服务实现 中的安装流程会先下载仓库到临时目录，再通过 resolve_skill_source_dir 将 skill.directory（即仓库内的子目录路径）解析为真实源目录，并做规范化校验（canonicalize + 前缀检查）防止路径逃逸：

// 复制到 SSOT
let source =
    Self::resolve_skill_source_dir(temp_dir, &skill.directory)
    .ok_or_else(|| {
        // SKILL_DIR_NOT_FOUND：提示缺失的完整路径，建议 checkRepoUrl
    })?;

安装目录名始终取源路径的最后一段，避免在 SSOT 中创建多级目录（见 skill.rs 第 781-791 行）。这保证了"仓库 → 子目录 → 技能目录"的映射在安装时是健壮且安全的。

修复 Gemini 配置持久化问题

v3.7.1 解决了在 Gemini 表单中编辑 settings.json 后、切换供应商时修改丢失的问题。这一问题的根源与 Gemini 的双文件配置模型有关：CC Switch 同时管理 ~/.gemini/.env 与 ~/.gemini/settings.json 两个文件，任何一侧的状态如果未落盘，切换供应商时就会被覆盖。

从源码结构看，gemini_config.rs 对两个文件均采用"先读原文 → 定向修改 → 原子写入"的模式：

• ~/.gemini/.env 使用原子写入（写入临时文件后替换），保证进程崩溃不会留下半截文件；
• settings.json 的修改（如 security.auth.selectedType 字段）也是读取现有文件后仅更新目标字段，保留其余内容。

这一实现是 v3.7.1 修复"编辑后丢失"问题的工程基础。

防止对话框意外关闭

v3.7.1 为所有 11 个对话框组件添加了点击遮罩层（overlay）时的保护，避免用户误点外部区域导致表单数据丢失。这一改进覆盖的是 shadcn/ui 风格的 Dialog 组件族（参见 dialog.tsx），属于典型的"输入保护"类 UX 修复：多行配置表单（如供应商的 Base URL、API Key、模型映射）一旦误关闭，重填成本高，因此拦截遮罩点击是低成本高收益的防护。

新增：Gemini 配置目录支持（#255）

在设置中新增 Gemini 配置目录选项，支持自定义 ~/.gemini/ 路径。对于在容器、多用户或自定义 Home 环境下运行 Gemini CLI 的用户，这是一个实用的逃生口。对应实现集中在 gemini_config.rs 的 get_gemini_dir() 等路径解析函数中——所有 .env 与 settings.json 的路径都由该目录派生，因此"改一处、全链路生效"。

新增：ArchLinux 安装支持（#259）

v3.7.1 起 ArchLinux 用户可以通过 AUR 安装：

paru -S cc-switch-bin

这与官方提供的其他安装方式（见下载与安装一节）共同构成完整的跨平台分发矩阵。

改进：Skills 错误消息国际化增强

v3.7.1 为 Skills 模块新增 28+ 条带具体解决建议的中英文错误消息，并把下载超时从 15 秒延长到 60 秒。在当前源码中可以直接看到 60 秒超时的落地位置——仓库下载被包裹在 tokio::time::timeout 中，超时后抛出结构化的 DOWNLOAD_TIMEOUT 错误（附带 owner/name/timeout 参数与建议检查项）：

// 下载仓库
let (temp_guard, used_branch) = timeout(
    std::time::Duration::from_secs(60),
    self.download_repo(&repo),
)
.await
.map_err(|_| {
    anyhow!(format_skill_error(
        "DOWNLOAD_TIMEOUT",
        &[("owner", &repo.owner), ("name", &repo.name), ("timeout", "60")],
        Some("checkNetwork"),
    ))
})??;

见 skill.rs 第 821-836 行。同一文件中还有多处 Duration::from_secs(60) 的超时包裹（如分支回退下载、download_repo 调用点），说明 60 秒已成为 Skills 网络操作的统一超时预算。错误消息采用 format_skill_error 生成错误码 + 上下文参数 + 建议操作（如 checkNetwork、checkRepoUrl、checkZipContent）的三段式结构，前端据此渲染带解决建议的本地化文案。

此外，v3.7.1 还应用了统一的 Rust 和 TypeScript 代码格式化标准（release notes 归类为"代码格式化"）。

v3.7.0：Gemini CLI 集成

v3.7.0 是功能大版本。其最重要的能力是让 CC Switch 完整支持 Google Gemini CLI，成为第三个被管理的应用（Claude Code、Codex、Gemini）。

双文件配置模型

Gemini CLI 的供应商配置分散在两个文件中，CC Switch 需要同时管理：

• ~/.gemini/.env —— 环境变量文件，承载 GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL 等键值对；
• ~/.gemini/settings.json —— 结构化配置，承载认证类型（如 security.auth.selectedType）等字段。

从源码看，gemini_config.rs 对这套模型做了完整的工具化封装：

• 宽松解析 + 严格解析双轨制：parse_env_file 宽松地解析 .env，跳过无效行；严格版本则逐行报告错误（缺少 = 分隔符、空键名、非法键名等），错误信息中直接带上行号与原始行内容，便于用户在编辑器中定位；
• 定向删除而非整文件重写：提供"按「键名 + 值」双匹配删除若干行，其余内容逐字保留"的原语（gemini_config.rs 第 155 行附近），这解释了为什么用户手写在 .env 里的其他内容不会被切换供应商时破坏；
• .env 与 settings_config（JSON Value）互转：后端在 Provider 记录中以 JSON 保存 .env 内容，切换时再序列化回 .env 文本，保证"表单 ↔ 文件"双向同步。

切换供应商时，settings.json 的写入同样是定向的：Google 官方供应商写入 OAuth 认证类型，PackyCode 等 API 中转供应商写入对应的 base URL 配置（见 gemini_config.rs 第 399-419 行 附近的供应商专属写入函数）。

供应商预设

发布说明列出三个 Gemini 供应商预设：

• Google Official —— 支持 OAuth 认证；
• PackyCode —— 合作伙伴集成（API 中转）；
• 自定义 —— 完全自定义支持。

预设定义在 geminiProviderPresets.ts 中，可以看到 Google 官方预设（partnerPromotionKey: "google-official"）与 PackyCode 预设（GOOGLE_GEMINI_BASE_URL 指向其中转域名）的具体形态，与发布说明一一对应。

配套能力

发布说明还列出了 Gemini 集成的配套能力，均可在仓库中找到对应实现：

• 完整 MCP 支持：gemini_mcp.rs 为 Gemini 提供 MCP 服务器管理；
• 深度链接集成：通过 ccswitch:// 协议导入配置，见 deeplink 模块；
• 系统托盘：从托盘菜单快速切换应用与供应商，见 tray.rs；
• 自动检测：自动检测 GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL 等现有环境变量，避免重复配置；
• 表单与环境编辑器同步：Gemini 表单中的字段与 .env/settings.json 编辑器内容保持同步，配合 v3.7.1 的持久化修复形成完整闭环。

v3.7.0：MCP 统一架构

MCP（Model Context Protocol）服务器管理在 v3.7.0 经历了完整重构，目标是"跨应用统一管理"。架构与体验要点：

• 统一管理面板：单一界面管理 Claude / Codex / Gemini 三端 MCP 服务器。前端对应 UnifiedMcpPanel，后端 MCP 服务位于 services/mcp.rs；
• SSE 传输类型：在 stdio 之外新增 Server-Sent Events 支持；
• 智能解析器：容错性 JSON 解析，对格式不完美的配置也能恢复；
• 格式修正：自动修复 Codex [mcp_servers] 的 TOML 格式问题；
• 扩展字段保留：用户自定义的 TOML 字段在读写往返后不丢失——这与 v3.7.1 的 Skills 错误消息增强类似，属于"不破坏用户手工配置"的产品原则；
• 导入/导出：统一从三个应用导入、双向同步、状态保持。

重构的技术代价记录在发布说明中：移除约 1,000 行遗留代码、统一初始化结构、保持向后兼容（MCP v3.7.0 与之前的配置向后兼容）。

v3.7.0：Claude Skills 管理系统

发布说明称其为"约 2,000 行代码的完整技能生态平台"，是 v3.7.0 中最具平台属性的能力。

发现与安装

• 自动扫描：从 GitHub 仓库自动扫描技能，识别标准是仓库内存在 SKILL.md 文件；
• 预配置仓库：ComposioHQ/awesome-claude-skills（精选集合）、anthropics/skills（官方技能）、cexll/myclaude（社区贡献），并支持添加自定义仓库；
• 子目录扫描（skillsPath）：这是 v3.7.1 修复的焦点，带子目录的仓库现在可正确安装（见前文 skill.rs 的 resolve_skill_source_dir 分析）；
• 安装目标：一键安装到 ~/.claude/skills/。

生命周期管理

发现（自动检测 SKILL.md）→ 安装（写入目标目录）→ 卸载（安全移除并跟踪状态）→ 更新（检查更新基础设施已就绪）的完整生命周期。当前源码中 skill.rs 已增长到近 6,000 行，包含安装目录复用（reuse_existing_install）、分支自动回退（配置分支不存在时自动切换并记录日志）、文档路径推导（doc_path_for_source）等增强，说明该系统在后续版本中持续深化。

技术架构

• 后端：SkillService 集成 GitHub API；
• 前端：SkillsPage、SkillCard、RepoManagerPanel；
• UI 组件：基于 shadcn/ui 的 Badge、Card、Table（见 components/ui）；
• 状态：持久化存储在 config.json；
• 国际化：47+ 个翻译键（见 locales 目录）。

v3.7.0：Prompts 管理系统

约 1,300 行代码的系统提示词管理能力，核心是"多预设 + 跨应用 + 智能同步"。

多预设管理

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

跨应用文件映射

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

这一映射在后续版本中继续扩展（如 OpenCode 的 AGENTS.md），后端服务位于 services/prompt.rs，前端由 PromptPanel、PromptFormModal 与基于 CodeMirror 6 的 MarkdownEditor 组成（语法高亮、One Dark 暗色主题、实时预览）。

智能同步策略

• 自动写入：编辑后立即写入 live 文件，所见即所得；
• 回填保护：切换预设前保存当前内容，避免覆盖用户修改；
• 自动导入：首次启动时从 live 文件导入现有内容作为预设；
• 修改保护：用户在 live 文件中的手动修改在往返过程中被保留。

v3.7.0：深度链接协议（ccswitch://）

通过 URL 方案一键导入供应商配置，功能特性包括：

• 所有平台（Windows/macOS/Linux）的协议注册；
• 从共享链接导入供应商配置；
• 应用生命周期集成（协议事件接入 Tauri 生命周期）；
• 安全验证（前端配有风险检测，见 deeplinkRisk.ts 与 DeepLinkImportDialog）。

后端实现位于 deeplink 模块，该协议也是合作伙伴"一键导入"按钮的载体。

v3.7.0：环境变量冲突检测

智能检测和管理配置冲突，检测范围覆盖：

• Claude & Codex：跨应用冲突（如 ~/.claude 与 ~/.codex 配置了互相矛盾的 base URL / 模型变量）；
• Gemini：自动发现 GOOGLE_GEMINI_BASE_URL 等已存在的环境变量；
• MCP：服务器配置冲突。

管理功能包括可视化冲突指示器、解决建议、覆盖警告与更改前备份。相关检测基础设施见 env_manager.rs 与 env_checker.rs。

改进优化、Bug 修复与技术改进

发布说明将 v3.7.0 的其余内容归类为改进优化、Bug 修复与技术改进三块，摘要如下：

供应商管理

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

配置管理

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

UI/UX 改进

• macOS 原生配色方案对齐系统；窗口默认居中；间距与视觉层次优化；
• 修复 Edge/IE 密码输入显示按钮、卡片 URL 溢出、错误信息可复制到剪贴板、托盘实时拖放同步。

关键 Bug 修复

• 用量脚本验证的边界检查；
• Gemini 验证约束放宽；
• TOML 解析的 CJK 引号处理；
• MCP 自定义字段保留；
• FormLabel 崩溃导致的白屏修复。

稳定性

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

技术改进

• 平台兼容性：Windows winreg API 修复（升级至 winreg 0.52）、安全模式匹配（无 unwrap()）、跨平台托盘处理；
• 同步机制：跨应用 MCP 同步、Gemini 表单-编辑器同步、双文件读取（.env + settings.json）；
• 验证增强：输入边界检查、TOML 引号规范化（CJK）、自定义字段保留、增强错误消息；
• 依赖项：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 行

战略定位：从工具到平台

发布说明将 v3.7.0 定义为 CC Switch 定位的转变：

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

并归纳出"AI CLI 管理六大支柱"：

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

这一转变在仓库结构中可以得到印证：v3.7 引入的 Skills、Prompts、MCP 统一面板、Gemini 配置模块如今仍是代码库的一级模块（services/skill.rs、services/prompt.rs、gemini_config.rs 等），且应用矩阵在此后又扩展到 OpenCode、OpenClaw、Grok Build、Hermes Agent 等。

下载与安装：系统要求与迁移说明

系统要求

• Windows：Windows 10+
• macOS：macOS 10.15（Catalina）+
• Linux：Ubuntu 22.04+ / Debian 11+ / Fedora 34+ / ArchLinux

下载与安装方式

通过项目官方 Releases 页面下载对应平台的安装包：

• Windows：CC-Switch-Windows.msi 或 -Portable.zip
• macOS：CC-Switch-macOS.tar.gz 或 .zip
• Linux：CC-Switch-Linux.AppImage 或 .deb
• ArchLinux（v3.7.1 新增）：paru -S cc-switch-bin

macOS 亦可通过 Homebrew 安装与更新：

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

brew upgrade --cask cc-switch

仓库内还包含 flatpak 元数据，用于 Linux 的 Flatpak 分发。

迁移说明

• 从 v3.6.x 升级：自动迁移，无需任何操作，配置完全兼容；
• 从 v3.1.x 或更早版本升级：需要两步迁移——先升级到 v3.2.x 执行一次性迁移，再升级到 v3.7.0；
• 新功能迁移：Skills 无需迁移（全新开始）；Prompts 首次启动时从 live 文件自动导入；Gemini 需要单独安装 Gemini CLI；MCP v3.7.0 与之前配置向后兼容。

结语

v3.7.0/v3.7.1 这一版本对 CC Switch 的意义在于：它从一个"切配置"的工具长出了"管生态"的平台骨架——Gemini 的加入使应用矩阵达到三端，MCP 重构确立了跨应用统一的资源管理范式，Skills 与 Prompts 两条能力线分别补齐了"能力扩展"与"行为定制"支柱，而 v3.7.1 则用子目录安装修复、Gemini 持久化修复、对话框遮罩保护和结构化的国际化错误消息，为这套新能力补上了稳定性拼图。发布说明中预告的 v3.8.0 本地代理功能，在后续版本中已落地为当前仓库中的 proxy 模块，这也印证了该路线图的方向。更多版本演进可参考 CHANGELOG.md 与 README，完整更新说明系列见 release-notes 目录。