CC Switch v3.7.1 版本深度解析：Gemini 配置目录、Skills 子目录安装修复与对话框误触防护

本文基于 CC Switch v3.7.1 英文更新说明（发布于 2025-11-22，涉及 17 个文件、+524 / -81 行改动）展开，逐项解析该版本的 Bug 修复、新特性与改进点，并结合仓库源码验证每项改动的实际实现位置；同时完整梳理其承载的 v3.7.0 大版本（Gemini CLI 集成、MCP 统一架构、Skills/Prompts 管理系统）的能力全貌。读完后你将了解本次稳定版具体解决了哪些配置持久化与交互问题，以及这些能力在代码层是如何落地的。

1. 版本概览

v3.7.1 是一个以稳定性增强与用户体验改进为主题的补丁版本，官方定位即“Stability Enhancements and User Experience Improvements”。其规模不大（17 个文件，+524 / -81 行），但每一项改动都针对真实用户反馈：

类别	内容	关联 Issue
Bug 修复	第三方 Skills 仓库安装失败（自定义子目录）	#268
Bug 修复	Gemini 配置切换供应商后丢失	-
Bug 修复	点击遮罩层导致对话框意外关闭（11 个对话框组件）	-
新特性	设置中支持自定义 Gemini 配置目录	#255
新特性	ArchLinux 通过 AUR 安装	#259
改进	Skills 错误信息 i18n（28+ 条，中英双语）	-
改进	下载超时从 15s 延长到 60s	-
改进	统一的 Rust / TypeScript 代码格式化标准	-

该版本紧随 v3.7.0（2025-11-19 发布，85 个 commit、152 个文件、+18,104 / -3,732 行）之后，可以视为对 v3.7.0 大版本（Gemini 集成、MCP 重构、Skills 与 Prompts 系统）的快速护航。对应的 CHANGELOG.md 中 [3.7.1] - 2025-11-22 条目与本文描述一致，可作为交叉验证依据。中文版更新说明见 v3.7.1-zh.md。

2. Bug 修复

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

v3.7.1 修复了带有自定义子目录的 Skills 仓库（例如 ComposioHQ/awesome-claude-skills）安装失败的问题。这类仓库的特点是不把 SKILL.md 放在仓库根目录，而是分散在若干子目录中。

从源码结构看，该修复对应的核心逻辑位于 SkillService 的 install 流程。安装时服务会把整个仓库归档下载到临时目录，随后调用 resolve_skill_source_dir 解析真实源目录。当前仓库中该函数采用三级回退策略（skill.rs）：

1. 直接相对路径命中：root/directory 存在且包含 SKILL.md 时直接采用（且必须校验 SKILL.md，避免把同名空壳目录误判为源目录）；
2. 按名字递归查找：在仓库内递归搜索同名的、含 SKILL.md 的目录；
3. 兜底仓库根：仓库根本身存在 SKILL.md 时视为单技能仓库。

这一解析逻辑有完整的单元测试覆盖，包括根级技能、嵌套目录、按安装名回退、拒绝同名包装目录、两级目录目录型技能、无 SKILL.md 时返回 None 等场景（测试代码），印证了 v3.7.1 对子目录场景的系统性修复。

2.2 修复 Gemini 配置持久化问题

v3.7.1 解决了在 Gemini 表单中编辑 settings.json 后切换供应商时编辑内容丢失的问题。结合 v3.7.0 的 Gemini 双文件（.env + settings.json）架构，该修复保证了表单中两个文件的编辑结果在切换供应商时被完整回写，而不是只写入当前激活的那一份配置。

Gemini 配置读取路径的入口在 gemini_config.rs：get_gemini_dir() 返回配置目录，get_gemini_env_path() 在其下定位 .env 文件，settings.json 则在同目录下读写，二者共同构成 Gemini 的双文件配置面。

2.3 防止点击遮罩层关闭对话框

v3.7.1 为全部 11 个对话框组件增加了遮罩层（overlay/backdrop）点击保护，避免用户误点背景区域导致表单数据丢失。

从源码结构看，该保护统一落在基础对话框组件 dialog.tsx 的 DialogContent 上——通过 onInteractOutside 回调调用 e.preventDefault() 直接阻止“点击外部关闭”行为。由于各业务对话框（Provider 编辑、MCP 表单、导入导出等）都复用这一基础组件，单点修改即可覆盖全部 11 个对话框，这也是该版本改动行数控制得较紧凑的原因。

3. 新特性

3.1 Gemini 配置目录支持（#255）

v3.7.1 在设置中新增 Gemini 配置目录选项，允许用户自定义 ~/.gemini/ 的位置。这在多账号、容器化环境或将 CLI 配置目录迁移到非默认路径（例如 ~/.config/gemini 类 XDG 布局）的场景下非常实用。

实现链路可以在源码中完整追踪：

1. 持久化字段：设备级设置结构体中新增了 gemini_config_dir 字段（settings.rs），与 claude_config_dir、codex_config_dir 等并列，属于“设备级目录覆盖”一族，未设置时为 None，序列化时自动跳过；
2. 覆盖目录解析：get_gemini_override_dir() 读取该字段并经 resolve_override_path 归一化为绝对路径；
3. 全局生效：get_gemini_dir() 优先返回覆盖目录，否则回退到 ~/.gemini；后续所有 .env、settings.json、GEMINI.md、MCP 配置的读写均基于该目录派生。

可以推断，由于该覆盖属于设备级（存于本机 settings.json）而非云端共享的供应商数据，同一账号在不同机器上可以指向各自的 Gemini 目录，不会互相污染——这与 CC Switch 对 Claude/Codex 目录覆盖的处理策略保持一致。

3.2 ArchLinux 安装支持（#259）

v3.7.1 为 ArchLinux 用户提供了 AUR 安装方式：

paru -S cc-switch-bin

即通过 paru/yay 等 AUR 助手安装 cc-switch-bin 包。此前 ArchLinux 用户只能手动下载 AppImage/deb，AUR 渠道使其获得了与其他发行版一致的一键安装与升级体验。

4. 改进

4.1 Skills 错误信息 i18n 增强

新增 28+ 条详细错误消息（英文与中文），每条都带有针对性的解决建议（resolution suggestion），并配合错误分类码与操作提示（如“检查网络”“检查仓库地址”“检查压缩包内容”）。

从源码结构看，skill.rs 引入统一的 format_skill_error 错误格式化函数，安装/卸载流程中的各类失败（DOWNLOAD_TIMEOUT、SKILL_DIR_NOT_FOUND、INVALID_SKILL_DIRECTORY、SKILL_DIRECTORY_CONFLICT 等）都通过它生成带错误码、上下文变量和建议动作的结构化消息，再交由 i18n 层渲染成用户语言——这正是 v3.7.1 中“带具体解决建议”错误体验的代码来源。

4.2 下载超时从 15s 延长到 60s

仓库归档下载的网络超时由 15 秒延长至 60 秒，用于降低弱网环境下误报 DOWNLOAD_TIMEOUT 的概率。源码中的证据是 install 流程中的 60 秒超时包裹：

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"),
    ))
})??;

超时触发后会生成带 timeout: "60" 与 checkNetwork 建议的 i18n 错误，与 4.1 节的错误体系闭环。

4.3 代码格式化

对 Rust（cargo fmt）与 TypeScript（prettier）应用了统一的格式化标准，属于纯代码卫生改动，不改变运行行为。

5. v3.7.0 完整能力回顾（v3.7.1 的能力基线）

v3.7.1 的修复全部落在 v3.7.0 建立的能力面上，因此有必要完整梳理 v3.7.0 的发布内容（85 个 commit，152 个文件，+18,104 / -3,732 行）。

5.1 Gemini CLI 集成

v3.7.0 使 CC Switch 支持的第三个应用从 Claude Code、Codex 扩展到 Google Gemini CLI，核心能力包括：

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

内置供应商预设包括 Google 官方（支持 OAuth 认证）、PackyCode（合作伙伴集成）与 Custom（完全自定义）。

技术实现上，v3.7.0 新增了后端模块 gemini_config.rs（当时约 20KB）与 gemini_mcp.rs（当前仓库中 MCP 侧已演进为 mcp/gemini.rs），并实现了表单与环境编辑器之间的同步、双文件原子写入。.env 解析本身也有宽松/严格两档：parse_env_file 宽松解析并跳过无效行，parse_env_file_strict 则返回带行号的详细错误（gemini_config.rs）。

5.2 MCP v3.7.0 统一架构

MCP 管理系统被完整重构以实现跨应用统一：

• 统一面板：Claude/Codex/Gemini 的 MCP server 在单一界面管理（前端为 UnifiedMcpPanel.tsx）；
• SSE 传输：新增 Server-Sent Events 支持；
• 智能解析器：容错 JSON 解析；
• 格式纠正：自动修复 Codex [mcp_servers] 表格式；
• 扩展字段保留：自定义 TOML 字段不被丢弃；
• 导入/导出：三个应用的统一导入、双向同步、状态保留。

后端实现按应用拆分为 mcp/claude.rs、mcp/codex.rs、mcp/gemini.rs，并配有 mcp/validation.rs 做统一校验，与文档中“统一初始化结构、保持向后兼容”的描述相符。

5.3 Claude Skills 管理系统

约 2,000 行的完整技能生态平台，v3.7.1 所修复的正是这一系统：

• GitHub 集成：自动扫描仓库中的技能；预置仓库包括 anthropics/skills（官方）、ComposioHQ/awesome-claude-skills（精选集）、cexll/myclaude（社区），也支持添加自定义仓库与 skillsPath 子目录扫描——源码中 SkillStore 的默认仓库列表 与文档一致（当前版本还新增了 JimLiu/baoyu-skills）；
• 生命周期管理：发现（自动检测 SKILL.md）→ 安装（一键落到应用 skills 目录）→ 卸载（带跟踪的安全删除）→ 更新检测（当时基础设施就绪）；
• 技术架构：后端 SkillService（当时 526 行）负责 GitHub API 集成，前端为 SkillsPage、SkillCard、RepoManager（对应 SkillsPage.tsx、SkillCard.tsx、RepoManagerPanel.tsx），状态持久化于 config.json，i18n 提供 47+ 翻译键。

5.4 Prompts 管理系统

约 1,300 行的系统提示词管理：

• 多预设管理：可创建无限量预设、快速切换、同一时刻仅一个激活、激活预设受删除保护；
• 跨应用文件映射：Claude 写 ~/.claude/CLAUDE.md、Codex 写 ~/.codex/AGENTS.md、Gemini 写 ~/.gemini/GEMINI.md；
• Markdown 编辑器：CodeMirror 6 完整集成、语法高亮、One Dark 暗色主题、实时预览（对应 MarkdownEditor.tsx）；
• 智能同步：自动写入生效文件、切换前回填保护、首次启动从生效文件自动导入、手动修改保护。后端为 services/prompt.rs。

5.5 深链协议与环境变量冲突检测

• ccswitch:// 协议：全平台注册协议、从分享链接导入、生命周期集成与安全校验（前端入口见 DeepLinkImportDialog.tsx）；
• 环境变量冲突检测：覆盖 Claude/Codex 跨应用冲突、Gemini 自动发现、MCP server 配置冲突三类检测范围，提供可视化冲突指示、解决建议、覆盖警告与变更前备份。

5.6 v3.7.0 其他改进与修复

• 供应商管理：新增 DouBaoSeed（字节跳动）、Kimi For Coding（月之暗面）、BaiLing 预设，移除易混淆的 AnyRouter；Codex 与 Gemini 支持模型名配置；新增供应商备注字段；
• 配置管理：通用配置从 localStorage 迁移到 config.json、跨应用统一持久化、首次启动自动导入；
• UI/UX：macOS 原生风格配色、窗口默认居中、密码输入回显按钮修复、URL 溢出修复、托盘拖拽实时同步；
• 关键 Bug 修复：用量脚本边界检查、Gemini 校验放宽、TOML 中日韩引号处理、MCP 自定义字段保留、FormLabel 白屏崩溃修复、托盘安全模式匹配（去除 unwrap()）等；
• 依赖：Tauri 2.8.x、Rust 侧 anyhow/zip/serde_yaml/tempfile、前端 CodeMirror 6、winreg 0.52（Windows）。

5.7 战略定位：从工具到平台

维度	v3.6	v3.7.0
定位	供应商切换器	AI CLI 管理平台
范围	配置管理	生态管理
应用	Claude + Codex	Claude + Codex + Gemini
能力	切换配置	扩展能力（Skills）
定制	手动编辑	可视化管理（Prompts）
集成	应用相互隔离	统一管理（MCP）

官方将其概括为 AI CLI 管理六大支柱：配置管理、能力扩展（Skills）、行为定制（Prompts）、生态集成（深链）、多 AI 支持（Claude/Codex/Gemini）、智能检测（冲突预防）。

6. 下载与安装

系统要求：

• 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：paru -S cc-switch-bin（v3.7.1 新增）

Homebrew（macOS）：

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

更新：

brew upgrade --cask cc-switch

7. 迁移说明

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

8. 小结与延伸阅读

v3.7.1 是一个典型的“护航补丁”：以 17 个文件的改动精准修补了 v3.7.0 大版本暴露的三类问题——多子目录 Skills 仓库的安装健壮性（resolve_skill_source_dir 三级回退 + 单元测试）、Gemini 双文件配置的持久化正确性（覆盖目录机制 + ~/.gemini 默认回退）以及表单误触丢失（基础对话框组件单点拦截 onInteractOutside）。同时新增的 Gemini 自定义配置目录与 AUR 安装渠道进一步补齐了多环境与多发行版下的可用性。

若需继续深入，建议按以下路径阅读当前仓库：

• 版本记录：CHANGELOG.md（[3.7.1] 条目）、docs/release-notes/v3.7.1-zh.md
• Skills 安装与子目录解析：src-tauri/src/services/skill.rs
• Gemini 目录覆盖与双文件配置：src-tauri/src/settings.rs、src-tauri/src/gemini_config.rs
• 对话框遮罩层保护：src/components/ui/dialog.tsx
• MCP 统一架构：src-tauri/src/mcp/、src/components/mcp/UnifiedMcpPanel.tsx