farion1231_cc-switch/README_ZH.md

Claude Code / Codex / Gemini CLI 全方位辅助工具

English | 中文 | 日本語 | 更新日志 | v3.9.0 发布说明

❤️赞助商

感谢智谱AI的 GLM CODING PLAN 赞助了本项目！GLM CODING PLAN 是专为AI编码打造的订阅套餐,每月最低仅需20元，即可在十余款主流AI编码工具如 Claude Code、Cline 中畅享智谱旗舰模型 GLM-4.6，为开发者提供顶尖、高速、稳定的编码体验。CC Switch 已经预设了智谱GLM，只需要填写 key 即可一键导入编程工具。智谱AI为本软件的用户提供了特别优惠，使用此链接购买可以享受九折优惠。

---

	感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的API中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本软件的用户提供了特别优惠，使用此链接注册并在充值时填写"cc-switch"优惠码，可以享受9折优惠！
	感谢 AIGoCode 赞助了本项目！AIGoCode 是一个集成了 Claude Code、Codex 以及 Gemini 最新模型的一站式平台，为你提供稳定、高效且高性价比的AI编程服务。本站提供灵活的订阅计划，零封号风险，国内直连，无需魔法，极速响应。AIGoCode 为 CC Switch 的用户提供了特别福利，通过此链接注册的用户首次充值可以获得额外10%奖励额度！
	感谢 DMXAPI（大模型API）赞助了本项目！ DMXAPI，一个Key用全球大模型。 为200多家企业用户提供全球大模型API服务。· 充值即开票 ·当天开票 ·并发不限制 ·1元起充 · 7x24 在线技术辅导，GPT/Claude/Gemini全部6.8折，国内模型5~8折，Claude Code 专属模型3.4折进行中！点击这里注册
	感谢 Cubence 赞助本项目！Cubence 是一家可靠高效的 API 中继服务提供商，提供对 Claude Code、Codex、Gemini 等模型的中继服务，并提供按量、包月等灵活的计费方式。Cubence 为 CC Switch 的用户提供了特别优惠：使用 此链接 注册，并在充值时输入 "CCSWITCH" 优惠码，每次充值均可享受九折优惠！

界面预览

主界面	添加供应商

功能特性

当前版本：v3.10.0 | 完整更新日志 | 发布说明

v3.8.0 重大更新（2025-11-28）

持久化架构升级 & 全新用户界面

• SQLite + JSON 双层架构

  • 从 JSON 文件存储迁移到 SQLite + JSON 双层结构
  • 可同步数据（供应商、MCP、Prompts、Skills）存入 SQLite
  • 设备级数据（窗口状态、本地路径）保留在 JSON
  • 为未来云同步功能奠定基础
  • Schema 版本管理支持数据库迁移

• 全新用户界面

  • 完全重新设计的界面布局
  • 统一的组件样式和更流畅的动画
  • 优化的视觉层次
  • Tailwind CSS 从 v4 降级到 v3.4 以提升浏览器兼容性

• 日语支持

  • 新增日语界面支持（现支持中文/英文/日语）

• 开机自启

  • 在设置中一键开启/关闭
  • 使用平台原生 API（注册表/LaunchAgent/XDG autostart）

• Skills 递归扫描

  • 支持多层目录结构
  • 允许不同仓库的同名技能

• 关键 Bug 修复

  • 修复更新供应商时自定义端点丢失问题
  • 修复 Gemini 配置写入问题
  • 修复 Linux WebKitGTK 渲染问题

v3.7.0 亮点

六大核心功能，18,000+ 行新增代码

• Gemini CLI 集成

  • 第三个支持的 AI CLI（Claude Code / Codex / Gemini）
  • 双文件配置支持（.env + settings.json）
  • 完整 MCP 服务器管理
  • 预设：Google Official (OAuth) / PackyCode / 自定义

• Claude Skills 管理系统

  • 从 GitHub 仓库自动扫描技能（预配置 3 个精选仓库）
  • 一键安装/卸载到 ~/.claude/skills/
  • 自定义仓库支持 + 子目录扫描
  • 完整生命周期管理（发现/安装/更新）

• Prompts 管理系统

  • 多预设系统提示词管理（无限数量，快速切换）
  • 跨应用支持（Claude: CLAUDE.md / Codex: AGENTS.md / Gemini: GEMINI.md）
  • Markdown 编辑器（CodeMirror 6 + 实时预览）
  • 智能回填保护，保留手动修改

• MCP v3.7.0 统一架构

  • 单一面板管理三个应用的 MCP 服务器
  • 新增 SSE (Server-Sent Events) 传输类型
  • 智能 JSON 解析器 + Codex TOML 格式自动修正
  • 统一导入/导出 + 双向同步

• 深度链接协议

  • ccswitch:// 协议注册（全平台）
  • 通过共享链接一键导入供应商配置
  • 安全验证 + 生命周期集成

• 环境变量冲突检测

  • 自动检测跨应用配置冲突（Claude/Codex/Gemini/MCP）
  • 可视化冲突指示器 + 解决建议
  • 覆盖警告 + 更改前备份

核心功能

• 供应商管理：一键切换 Claude Code、Codex 与 Gemini 的 API 配置
• 速度测试：测量 API 端点延迟，可视化连接质量指示器
• 导入导出：备份和恢复配置，自动轮换（保留最近 10 个）
• 国际化支持：完整的中英文本地化（UI、错误、托盘）
• Claude 插件同步：一键应用或恢复 Claude 插件配置

v3.6 亮点

• 供应商复制 & 拖拽排序
• 多端点管理 & 自定义配置目录（支持云同步）
• 细粒度模型配置（四层：Haiku/Sonnet/Opus/自定义）
• WSL 环境支持，配置目录切换自动同步
• 100% hooks 测试覆盖 & 完整架构重构

系统功能

• 系统托盘快速切换
• 单实例守护
• 内置自动更新器
• 原子写入与回滚保护

下载安装

系统要求

• Windows: Windows 10 及以上
• macOS: macOS 10.15 (Catalina) 及以上
• Linux: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ 等主流发行版

Windows 用户

从 Releases 页面下载最新版本的 CC-Switch-v{版本号}-Windows.msi 安装包或者 CC-Switch-v{版本号}-Windows-Portable.zip 绿色版。

macOS 用户

方式一：通过 Homebrew 安装（推荐）

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

更新：

brew upgrade --cask cc-switch

方式二：手动下载

从 Releases 页面下载 CC-Switch-v{版本号}-macOS.zip 解压使用。

注意：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开

ArchLinux 用户

通过 paru 安装（推荐）

paru -S cc-switch-bin

Linux 用户

从 Releases 页面下载最新版本的 Linux 安装包：

• CC-Switch-v{版本号}-Linux.deb（Debian/Ubuntu）
• CC-Switch-v{版本号}-Linux.rpm（Fedora/RHEL/openSUSE）
• CC-Switch-v{版本号}-Linux.AppImage（通用）
• CC-Switch-v{版本号}-Linux.flatpak（Flatpak）

Flatpak 安装与运行：

flatpak install --user ./CC-Switch-v{版本号}-Linux.flatpak
flatpak run com.ccswitch.desktop

快速开始

基本使用

1. 添加供应商：点击"添加供应商" → 选择预设或创建自定义配置
2. 切换供应商：
   • 主界面：选择供应商 → 点击"启用"
   • 系统托盘：直接点击供应商名称（立即生效）
3. 生效方式：重启终端或 Claude Code / Codex / Gemini 客户端以应用更改
4. 恢复官方登录：选择"官方登录"预设（Claude/Codex）或"Google 官方"预设（Gemini），重启对应客户端后按照其登录/OAuth 流程操作

MCP 管理

• 位置：点击右上角"MCP"按钮
• 添加服务器：
  • 使用内置模板（mcp-fetch、mcp-filesystem 等）
  • 支持 stdio / http / sse 三种传输类型
  • 为不同应用配置独立的 MCP 服务器
• 启用/禁用：切换开关以控制哪些服务器同步到 live 配置
• 同步：启用的服务器自动同步到各应用的 live 文件
• 导入/导出：支持从 Claude/Codex/Gemini 配置文件导入现有 MCP 服务器

Skills 管理（v3.7.0 新增）

• 位置：点击右上角"Skills"按钮
• 发现技能：
  • 自动扫描预配置的 GitHub 仓库（Anthropic 官方、ComposioHQ、社区等）
  • 添加自定义仓库（支持子目录扫描）
• 安装技能：点击"安装"一键安装到 ~/.claude/skills/
• 卸载技能：点击"卸载"安全移除并清理状态
• 管理仓库：添加/删除自定义 GitHub 仓库

Prompts 管理（v3.7.0 新增）

• 位置：点击右上角"Prompts"按钮
• 创建预设：
  • 创建无限数量的系统提示词预设
  • 使用 Markdown 编辑器编写提示词（语法高亮 + 实时预览）
• 切换预设：选择预设 → 点击"激活"立即应用
• 同步机制：
  • Claude: ~/.claude/CLAUDE.md
  • Codex: ~/.codex/AGENTS.md
  • Gemini: ~/.gemini/GEMINI.md
• 保护机制：切换前自动保存当前提示词内容，保留手动修改

配置文件

Claude Code

• Live 配置：~/.claude/settings.json（或 claude.json）
• API key 字段：env.ANTHROPIC_AUTH_TOKEN 或 env.ANTHROPIC_API_KEY
• MCP 服务器：~/.claude.json → mcpServers

Codex

• Live 配置：~/.codex/auth.json（必需）+ config.toml（可选）
• API key 字段：auth.json 中的 OPENAI_API_KEY
• MCP 服务器：~/.codex/config.toml → [mcp_servers] 表

Gemini

• Live 配置：~/.gemini/.env（API Key）+ ~/.gemini/settings.json（保存认证模式）
• API key 字段：.env 文件中的 GEMINI_API_KEY 或 GOOGLE_GEMINI_API_KEY
• 环境变量：支持 GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL 等自定义变量
• MCP 服务器：~/.gemini/settings.json → mcpServers
• 托盘快速切换：每次切换供应商都会重写 ~/.gemini/.env，无需重启 Gemini CLI 即可生效

CC Switch 存储（v3.8.0 新架构）

• 数据库（SSOT）：~/.cc-switch/cc-switch.db（SQLite，存储供应商、MCP、Prompts、Skills）
• 本地设置：~/.cc-switch/settings.json（设备级设置）
• 备份：~/.cc-switch/backups/（自动轮换，保留 10 个）

云同步设置

1. 前往设置 → "自定义配置目录"
2. 选择您的云同步文件夹（Dropbox、OneDrive、iCloud、坚果云等）
3. 重启应用以应用
4. 在其他设备上重复操作以启用跨设备同步

注意：首次启动会自动导入现有 Claude/Codex 配置作为默认供应商。

架构总览

设计原则

┌─────────────────────────────────────────────────────────────┐
│                    前端 (React + TS)                         │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│  │ Components  │  │    Hooks     │  │  TanStack Query  │    │
│  │   （UI）     │──│ （业务逻辑）   │──│   （缓存/同步）    │    │
│  └─────────────┘  └──────────────┘  └──────────────────┘    │
└────────────────────────┬────────────────────────────────────┘
                         │ Tauri IPC
┌────────────────────────▼────────────────────────────────────┐
│                  后端 (Tauri + Rust)                         │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│  │  Commands   │  │   Services   │  │  Models/Config   │    │
│  │ （API 层）   │──│  （业务层）    │──│    （数据）       │    │
│  └─────────────┘  └──────────────┘  └──────────────────┘    │
└─────────────────────────────────────────────────────────────┘

核心设计模式

• SSOT（单一事实源）：所有数据存储在 ~/.cc-switch/cc-switch.db（SQLite）
• 双层存储：SQLite 存储可同步数据，JSON 存储设备级设置
• 双向同步：切换时写入 live 文件，编辑当前供应商时从 live 回填
• 原子写入：临时文件 + 重命名模式防止配置损坏
• 并发安全：Mutex 保护的数据库连接避免竞态条件
• 分层架构：清晰分离（Commands → Services → DAO → Database）

核心组件

• ProviderService：供应商增删改查、切换、回填、排序
• McpService：MCP 服务器管理、导入导出、live 文件同步
• ConfigService：配置导入导出、备份轮换
• SpeedtestService：API 端点延迟测量

v3.6 重构

• 后端：5 阶段重构（错误处理 → 命令拆分 → 测试 → 服务 → 并发）
• 前端：4 阶段重构（测试基础 → hooks → 组件 → 清理）
• 测试：100% hooks 覆盖 + 集成测试（vitest + MSW）

开发

环境要求

• Node.js 18+
• pnpm 8+
• Rust 1.85+
• Tauri CLI 2.8+

开发命令

# 安装依赖
pnpm install

# 开发模式（热重载）
pnpm dev

# 类型检查
pnpm typecheck

# 代码格式化
pnpm format

# 检查代码格式
pnpm format:check

# 运行前端单元测试
pnpm test:unit

# 监听模式运行测试（推荐开发时使用）
pnpm test:unit:watch

# 构建应用
pnpm build

# 构建调试版本
pnpm tauri build --debug

Rust 后端开发

cd src-tauri

# 格式化 Rust 代码
cargo fmt

# 运行 clippy 检查
cargo clippy

# 运行后端测试
cargo test

# 运行特定测试
cargo test test_name

# 运行带测试 hooks 的测试
cargo test --features test-hooks

测试说明（v3.6 新增）

前端测试：

• 使用 vitest 作为测试框架
• 使用 MSW (Mock Service Worker) 模拟 Tauri API 调用
• 使用 @testing-library/react 进行组件测试

测试覆盖：

• Hooks 单元测试（100% 覆盖）
  • useProviderActions - 供应商操作
  • useMcpActions - MCP 管理
  • useSettings 系列 - 设置管理
  • useImportExport - 导入导出
• 集成测试
  • App 主应用流程
  • SettingsDialog 完整交互
  • MCP 面板功能

运行测试：

# 运行所有测试
pnpm test:unit

# 监听模式（自动重跑）
pnpm test:unit:watch

# 带覆盖率报告
pnpm test:unit --coverage

技术栈

前端：React 18 · TypeScript · Vite · TailwindCSS 4 · TanStack Query v5 · react-i18next · react-hook-form · zod · shadcn/ui · @dnd-kit

后端：Tauri 2.8 · Rust · serde · tokio · thiserror · tauri-plugin-updater/process/dialog/store/log

测试：vitest · MSW · @testing-library/react

项目结构

├── src/                      # 前端 (React + TypeScript)
│   ├── components/           # UI 组件 (providers/settings/mcp/ui)
│   ├── hooks/                # 自定义 hooks (业务逻辑)
│   ├── lib/
│   │   ├── api/              # Tauri API 封装（类型安全）
│   │   └── query/            # TanStack Query 配置
│   ├── i18n/locales/         # 翻译 (zh/en)
│   ├── config/               # 预设 (providers/mcp)
│   └── types/                # TypeScript 类型定义
├── src-tauri/                # 后端 (Rust)
│   └── src/
│       ├── commands/         # Tauri 命令层（按领域）
│       ├── services/         # 业务逻辑层
│       ├── app_config.rs     # 配置数据模型
│       ├── provider.rs       # 供应商领域模型
│       ├── mcp.rs            # MCP 同步与校验
│       └── lib.rs            # 应用入口 & 托盘菜单
├── tests/                    # 前端测试
│   ├── hooks/                # 单元测试
│   └── components/           # 集成测试
└── assets/                   # 截图 & 合作商资源

更新日志

查看 CHANGELOG.md 了解版本更新详情。

Electron 旧版

Releases 里保留 v2.0.3 Electron 旧版

如果需要旧版 Electron 代码，可以拉取 electron-legacy 分支

贡献

欢迎提交 Issue 反馈问题和建议！

提交 PR 前请确保：

• 通过类型检查：pnpm typecheck
• 通过格式检查：pnpm format:check
• 通过单元测试：pnpm test:unit
• 💡 新功能开发前，欢迎先开 issue 讨论实现方案

Star History

License

MIT © Jason Young