cc-switch/README_ZH.md

<div align="center">

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

[![Version](https://img.shields.io/badge/version-3.10.2-blue.svg)](https://github.com/farion1231/cc-switch/releases)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/farion1231/cc-switch/releases)
[![Built with Tauri](https://img.shields.io/badge/built%20with-Tauri%202-orange.svg)](https://tauri.app/)
[![Downloads](https://img.shields.io/endpoint?url=https://api.pinstudios.net/api/badges/downloads/farion1231/cc-switch/total)](https://github.com/farion1231/cc-switch/releases/latest)

<a href="https://trendshift.io/repositories/15372" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15372" alt="farion1231%2Fcc-switch | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

[English](README.md) | 中文 | [日本語](README_JA.md) | [更新日志](CHANGELOG.md) | [v3.9.0 发布说明](docs/release-note-v3.9.0-zh.md)

</div>

## ❤️赞助商

[![MiniMax](assets/partners/banners/minimax-zh.jpeg)](https://platform.minimaxi.com/subscribe/coding-plan?code=7kYF2VoaCn&source=link)

MiniMax M2.x 系列模型是面向实际开发与智能体工作流打造的编码模型，M2.1 基于 100 亿激活 / 2300 亿总参的混合专家架构打造，推理更快、部署更便捷且支持本地运行，在 SWE、VIBE、Multi-SWE 等主流代码评测基准中均表现顶尖，擅长代码开发、数字环境适配及规模化处理长链路多步骤任务。

[点击](https://platform.minimaxi.com/subscribe/coding-plan?code=7kYF2VoaCn&source=link)即可领取 MiniMax Coding Plan 专属 88 折优惠！

---

<table>
<tr>
<td width="180"><a href="https://www.packyapi.com/register?aff=cc-switch"><img src="assets/partners/logos/packycode.png" alt="PackyCode" width="150"></a></td>
<td>感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的API中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本软件的用户提供了特别优惠，使用<a href="https://www.packyapi.com/register?aff=cc-switch">此链接</a>注册并在充值时填写"cc-switch"优惠码，首次充值可以享受9折优惠！</td>
</tr>

<tr>
<td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td>
<td>感谢 AIGoCode 赞助了本项目！AIGoCode 是一个集成了 Claude Code、Codex 以及 Gemini 最新模型的一站式平台，为你提供稳定、高效且高性价比的AI编程服务。本站提供灵活的订阅计划，零封号风险，国内直连，无需魔法，极速响应。AIGoCode 为 CC Switch 的用户提供了特别福利，通过<a href="https://aigocode.com/invite/CC-SWITCH">此链接</a>注册的用户首次充值可以获得额外10%奖励额度！</td>
</tr>

<tr>
<td width="180"><a href="https://www.aicodemirror.com/register?invitecode=9915W3"><img src="assets/partners/logos/aicodemirror.jpg" alt="AICodeMirror" width="150"></a></td>
<td>感谢 AICodeMirror 赞助了本项目！AICodeMirror 提供 Claude Code / Codex / Gemini CLI 官方高稳定中转服务，支持企业级高并发、极速开票、7×24 专属技术支持。
Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更有折上折！AICodeMirror 为 CCSwitch 的用户提供了特别福利，通过<a href="https://www.aicodemirror.com/register?invitecode=9915W3">此链接</a>注册的用户，可享受首充8折，企业客户最高可享 7.5 折！</td>
</tr>

<tr>
<td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td>
<td>感谢 Cubence 赞助本项目！Cubence 是一家可靠高效的 API 中继服务提供商，提供对 Claude Code、Codex、Gemini 等模型的中继服务，并提供按量、包月等灵活的计费方式。Cubence 为 CC Switch 的用户提供了特别优惠：使用 <a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">此链接</a> 注册，并在充值时输入 "CCSWITCH" 优惠码，每次充值均可享受九折优惠！</td>
</tr>

<tr>
<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-zh.jpeg" alt="DMXAPI" width="150"></a></td>
<td>感谢 DMXAPI（大模型API）赞助了本项目！ DMXAPI，一个Key用全球大模型。
为200多家企业用户提供全球大模型API服务。· 充值即开票 ·当天开票 ·并发不限制  ·1元起充 ·  7x24 在线技术辅导，GPT/Claude/Gemini全部6.8折，国内模型5~8折，Claude Code 专属模型3.4折进行中！<a href="https://www.dmxapi.cn/register?aff=bUHu">点击这里注册</a></td>
</tr>

<tr>
<td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td>
<td>感谢 Right Code 赞助了本项目！Right Code 稳定提供 Claude Code、Codex、Gemini 等模型的中转服务。主打<strong>极高性价比</strong>的Codex包月套餐，<strong>提供额度转结，套餐当天用不完的额度，第二天还能接着用！</strong>充值即可开票，企业、团队用户一对一对接。同时为 CC Switch 的用户提供了特别优惠：通过<a href="https://www.right.codes/register?aff=CCSWITCH">此链接</a>注册，每次充值均可获得实付金额25%的按量额度！</td>
</tr>

<tr>
<td width="180"><a href="https://aicoding.sh/i/CCSWITCH"><img src="assets/partners/logos/aicoding.jpg" alt="AICoding" width="150"></a></td>
<td>感谢 AICoding.sh 赞助了本项目！AICoding.sh —— 全球大模型 API 超值中转服务！Claude Code 1.9 折，GPT 0.1 折，已为数百家企业提供高性价比 AI 服务。支持 Claude Code、GPT、Gemini 及国内主流模型，企业级高并发、极速开票、7×24 专属技术支持，通过<a href="https://aicoding.sh/i/CCSWITCH">此链接</a> 注册的 CC Switch 用户，首充可享受九折优惠！</td>
</tr>

</table>

## 界面预览

|                  主界面                   |                  添加供应商                  |
| :---------------------------------------: | :------------------------------------------: |
| ![主界面](assets/screenshots/main-zh.png) | ![添加供应商](assets/screenshots/add-zh.png) |

## 功能特性

### 当前版本：v3.10.2 | [完整更新日志](CHANGELOG.md) | [发布说明](docs/release-note-v3.9.0-zh.md)

**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](../../releases) 页面下载最新版本的 `CC-Switch-v{版本号}-Windows.msi` 安装包或者 `CC-Switch-v{版本号}-Windows-Portable.zip` 绿色版。

### macOS 用户

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

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

更新：

```bash
brew upgrade --cask cc-switch
```

**方式二：手动下载**

从 [Releases](../../releases) 页面下载 `CC-Switch-v{版本号}-macOS.zip` 解压使用。

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

### ArchLinux 用户

**通过 paru 安装（推荐）**

```bash
paru -S cc-switch-bin
```

### Linux 用户

从 [Releases](../../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 安装与运行：

```bash
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+

### 开发命令

```bash
# 安装依赖
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 后端开发

```bash
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 面板功能

**运行测试**：

```bash
# 运行所有测试
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](CHANGELOG.md) 了解版本更新详情。

## Electron 旧版

[Releases](../../releases) 里保留 v2.0.3 Electron 旧版

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

## 贡献

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

提交 PR 前请确保：

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

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=farion1231/cc-switch&type=Date)](https://www.star-history.com/#farion1231/cc-switch&Date)

## License

MIT © Jason Young