Release v3.6.0: Major architecture refactoring and feature enhancements
New Features: - Provider duplication and manual sorting via drag-and-drop - Custom endpoint management for aggregator providers - Usage query with auto-refresh interval and test script API - Config editor improvements (JSON format button, real-time TOML validation) - Auto-sync on directory change for WSL environment support - Load live config when editing active provider to protect manual modifications - New provider presets: DMXAPI, Azure Codex, AnyRouter, AiHubMix, MiniMax - Partner promotion mechanism (Zhipu GLM Z.ai) Architecture Improvements: - Backend: 5-phase refactoring (error handling → command split → services → concurrency) - Frontend: 4-stage refactoring (tests → hooks → components → cleanup) - Testing: 100% hooks unit test coverage, integration tests for critical flows Documentation: - Complete README rewrite with detailed architecture overview - Separate Chinese (README_ZH.md) and English (README.md) versions - Comprehensive v3.6.0 changelog with categorized changes - New bilingual screenshots and partner banners Bug Fixes: - Fixed configuration sync issues (apiKeyUrl priority, MCP sync, import sync) - Fixed usage query interval timing and refresh button animation - Fixed UI issues (edit mode alignment, language switch state) - Fixed endpoint speed test and provider duplicate insertion position - Force exit on config error to prevent silent fallback Technical Details: - Updated to Tauri 2.8.x, TailwindCSS 4.x, TanStack Query v5.90.x - Removed legacy v1 migration logic for better startup performance - Standardized command parameters (unified to camelCase `app`) - Result pattern for graceful error handling
This commit is contained in:
Jason
108
CHANGELOG.md
108
CHANGELOG.md
@@ -5,6 +5,114 @@ All notable changes to CC Switch will be documented in this file.
|
|||||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||||
|
|
||||||
|
## [3.6.0] - 2025-11-07
|
||||||
|
|
||||||
|
### ✨ New Features
|
||||||
|
|
||||||
|
- **Provider Duplicate** - Quick duplicate existing provider configurations for easy variant creation
|
||||||
|
- **Edit Mode Toggle** - Show/hide drag handles to optimize editing experience
|
||||||
|
- **Custom Endpoint Management** - Support multi-endpoint configuration for aggregator providers
|
||||||
|
- **Usage Query Enhancements**
|
||||||
|
- Auto-refresh interval: Support periodic automatic usage query
|
||||||
|
- Test Script API: Validate JavaScript scripts before execution
|
||||||
|
- Template system expansion: Custom blank template, support for access token and user ID parameters
|
||||||
|
- **Configuration Editor Improvements**
|
||||||
|
- Add JSON format button
|
||||||
|
- Real-time TOML syntax validation for Codex configuration
|
||||||
|
- **Auto-sync on Directory Change** - When switching Claude/Codex config directories (e.g., WSL environment), automatically sync current provider to new directory without manual operation
|
||||||
|
- **Load Live Config When Editing Active Provider** - When editing the currently active provider, prioritize displaying the actual effective configuration to protect user manual modifications
|
||||||
|
- **New Provider Presets** - DMXAPI, Azure Codex, AnyRouter, AiHubMix, MiniMax
|
||||||
|
- **Partner Promotion Mechanism** - Support ecosystem partner promotion (e.g., Zhipu GLM Z.ai)
|
||||||
|
|
||||||
|
### 🔧 Improvements
|
||||||
|
|
||||||
|
- **Configuration Directory Switching**
|
||||||
|
- Introduced unified post-change sync utility (`postChangeSync.ts`)
|
||||||
|
- Auto-sync current providers to new directory when changing Claude/Codex config directories
|
||||||
|
- Perfect support for WSL environment switching
|
||||||
|
- Auto-sync after config import to ensure immediate effectiveness
|
||||||
|
- Use Result pattern for graceful error handling without blocking main flow
|
||||||
|
- Distinguish "fully successful" and "partially successful" states for precise user feedback
|
||||||
|
- **UI/UX Enhancements**
|
||||||
|
- Provider cards: Unique icons and color identification
|
||||||
|
- Unified border design system across all components
|
||||||
|
- Drag interaction optimization: Push effect animation, improved handle icons
|
||||||
|
- Enhanced current provider visual feedback
|
||||||
|
- Dialog size standardization and layout consistency
|
||||||
|
- Form experience: Optimized model placeholders, simplified provider hints, category-specific hints
|
||||||
|
- **Complete Internationalization Coverage**
|
||||||
|
- Error messages internationalization
|
||||||
|
- Tray menu internationalization
|
||||||
|
- All UI components internationalization
|
||||||
|
- **Usage Display Moved Inline** - Usage display moved next to enable button
|
||||||
|
|
||||||
|
### 🐛 Bug Fixes
|
||||||
|
|
||||||
|
- **Configuration Sync**
|
||||||
|
- Fixed `apiKeyUrl` priority issue
|
||||||
|
- Fixed MCP sync-to-other-side functionality failure
|
||||||
|
- Fixed sync issues after config import
|
||||||
|
- Prevent silent fallback and data loss on config error
|
||||||
|
- **Usage Query**
|
||||||
|
- Fixed auto-query interval timing issue
|
||||||
|
- Ensure refresh button shows loading animation on click
|
||||||
|
- **UI Issues**
|
||||||
|
- Fixed name collision error (`get_init_error` command)
|
||||||
|
- Fixed language setting rollback after successful save
|
||||||
|
- Fixed language switch state reset (dependency cycle)
|
||||||
|
- Fixed edit mode button alignment
|
||||||
|
- **Configuration Management**
|
||||||
|
- Fixed Codex API Key auto-sync
|
||||||
|
- Fixed endpoint speed test functionality
|
||||||
|
- Fixed provider duplicate insertion position (next to original provider)
|
||||||
|
- Fixed custom endpoint preservation in edit mode
|
||||||
|
- **Startup Issues**
|
||||||
|
- Force exit on config error (no silent fallback)
|
||||||
|
- Eliminate code duplication causing initialization errors
|
||||||
|
|
||||||
|
### 🏗️ Technical Improvements (For Developers)
|
||||||
|
|
||||||
|
**Backend Refactoring (Rust)** - Completed 5-phase refactoring:
|
||||||
|
- **Phase 1**: Unified error handling (`AppError` + i18n error messages)
|
||||||
|
- **Phase 2**: Command layer split by domain (`commands/{provider,mcp,config,settings,plugin,misc}.rs`)
|
||||||
|
- **Phase 3**: Integration tests and transaction mechanism (config snapshot + failure rollback)
|
||||||
|
- **Phase 4**: Extracted Service layer (`services/{provider,mcp,config,speedtest}.rs`)
|
||||||
|
- **Phase 5**: Concurrency optimization (`RwLock` instead of `Mutex`, scoped guard to avoid deadlock)
|
||||||
|
|
||||||
|
**Frontend Refactoring (React + TypeScript)** - Completed 4-stage refactoring:
|
||||||
|
- **Stage 1**: Test infrastructure (vitest + MSW + @testing-library/react)
|
||||||
|
- **Stage 2**: Extracted custom hooks (`useProviderActions`, `useMcpActions`, `useSettings`, `useImportExport`, etc.)
|
||||||
|
- **Stage 3**: Component splitting and business logic extraction
|
||||||
|
- **Stage 4**: Code cleanup and formatting unification
|
||||||
|
|
||||||
|
**Testing System**:
|
||||||
|
- Hooks unit tests 100% coverage
|
||||||
|
- Integration tests covering key processes (App, SettingsDialog, MCP Panel)
|
||||||
|
- MSW mocking backend API to ensure test independence
|
||||||
|
|
||||||
|
**Code Quality**:
|
||||||
|
- Unified parameter format: All Tauri commands migrated to camelCase (Tauri 2 specification)
|
||||||
|
- `AppType` renamed to `AppId`: Semantically clearer
|
||||||
|
- Unified parsing with `FromStr` trait: Centralized `app` parameter parsing
|
||||||
|
- Eliminate code duplication: DRY violations cleanup
|
||||||
|
- Remove unused code: `missing_param` helper function, deprecated `tauri-api.ts`, redundant `KimiModelSelector` component
|
||||||
|
|
||||||
|
**Internal Optimizations**:
|
||||||
|
- **Removed Legacy Migration Logic**: v3.6 removed v1 config auto-migration and copy file scanning logic
|
||||||
|
- ✅ **Impact**: Improved startup performance, cleaner code
|
||||||
|
- ✅ **Compatibility**: v2 format configs fully compatible, no action required
|
||||||
|
- ⚠️ **Note**: Users upgrading from v3.1.0 or earlier should first upgrade to v3.2.x or v3.5.x for one-time migration, then upgrade to v3.6
|
||||||
|
- **Command Parameter Standardization**: Backend unified to use `app` parameter (values: `claude` or `codex`)
|
||||||
|
- ✅ **Impact**: More standardized code, friendlier error prompts
|
||||||
|
- ✅ **Compatibility**: Frontend fully adapted, users don't need to care about this change
|
||||||
|
|
||||||
|
### 📦 Dependencies
|
||||||
|
|
||||||
|
- Updated to Tauri 2.8.x
|
||||||
|
- Updated to TailwindCSS 4.x
|
||||||
|
- Updated to TanStack Query v5.90.x
|
||||||
|
- Maintained React 18.2.x and TypeScript 5.3.x
|
||||||
|
|
||||||
## [3.5.0] - 2025-01-15
|
## [3.5.0] - 2025-01-15
|
||||||
|
|
||||||
### ⚠ Breaking Changes
|
### ⚠ Breaking Changes
|
||||||
|
|||||||
574
README.md
574
README.md
@@ -1,284 +1,512 @@
|
|||||||
# Claude Code & Codex 供应商切换器
|
# Claude Code & Codex Provider Switcher
|
||||||
|
|
||||||
[](https://github.com/farion1231/cc-switch/releases)
|
<div align="center">
|
||||||
|
|
||||||
|
[](https://github.com/farion1231/cc-switch/releases)
|
||||||
[](https://github.com/farion1231/cc-switch/releases)
|
[](https://github.com/farion1231/cc-switch/releases)
|
||||||
[](https://tauri.app/)
|
[](https://tauri.app/)
|
||||||
|
|
||||||
一个用于管理和切换 Claude Code 与 Codex 不同供应商配置的桌面应用。
|
English | [中文](README_ZH.md) | [Changelog](CHANGELOG.md)
|
||||||
|
|
||||||
> v3.5.0 ：新增 **MCP 管理**、**配置导入/导出**、**端点速度测试**功能，完善国际化覆盖，新增 Longcat、kat-coder 预设，标准化发布文件命名规范。
|
A desktop application for managing and switching between different provider configurations & MCP for Claude Code and Codex.
|
||||||
|
|
||||||
> v3.4.0 ：新增 i18next 国际化（还有部分未完成）、对新模型（qwen-3-max, GLM-4.6, DeepSeek-V3.2-Exp）的支持、Claude 插件、单实例守护、托盘最小化及安装器优化等。
|
</div>
|
||||||
|
|
||||||
> v3.3.0 ：VS Code Codex 插件一键配置/移除（默认自动同步）、Codex 通用配置片段与自定义向导增强、WSL 环境支持、跨平台托盘与 UI 优化。（该 VS Code 写入功能已在 v3.4.x 停用）
|
## ❤️ Sponsor
|
||||||
|
|
||||||
> v3.2.0 ：全新 UI、macOS系统托盘、内置更新器、原子写入与回滚、改进暗色样式、单一事实源（SSOT）与一次性迁移/归档。
|
|
||||||
|
|
||||||
> v3.1.0 ：新增 Codex 供应商管理与一键切换，支持导入当前 Codex 配置为默认供应商，并在内部配置从 v1 → v2 迁移前自动备份（详见下文“迁移与归档”）。
|
This project is sponsored by Z.ai, supporting us with their GLM CODING PLAN.
|
||||||
|
|
||||||
> v3.0.0 重大更新：从 Electron 完全迁移到 Tauri 2.0，应用体积显著降低、启动性能大幅提升。
|
GLM CODING PLAN is a subscription service designed for AI coding, starting at just $3/month. It provides access to their flagship GLM-4.6 model across 10+ popular AI coding tools (Claude Code, Cline, Roo Code, etc.), offering developers top-tier, fast, and stable coding experiences.
|
||||||
|
|
||||||
## 功能特性（v3.5.0）
|
Get 10% OFF the GLM CODING PLAN with [this link](https://z.ai/subscribe?ic=8JVLJQFSKB)!
|
||||||
|
|
||||||
- **MCP (Model Context Protocol) 管理**：完整的 MCP 服务器配置管理系统
|
## Release Notes
|
||||||
- 支持 stdio 和 http 服务器类型，并提供命令校验
|
|
||||||
- 内置常用 MCP 服务器模板（如 mcp-fetch 等）
|
|
||||||
- 实时启用/禁用 MCP 服务器，原子文件写入防止配置损坏
|
|
||||||
- **配置导入/导出**：备份和恢复你的供应商配置
|
|
||||||
- 一键导出所有配置到 JSON 文件
|
|
||||||
- 导入配置时自动验证并备份，自动轮换备份（保留最近 10 个）
|
|
||||||
- 带有详细状态反馈的进度模态框
|
|
||||||
- **端点速度测试**：测试 API 端点响应时间
|
|
||||||
- 测量不同供应商端点的延迟，可视化连接质量指示器
|
|
||||||
- 帮助用户选择最快的供应商
|
|
||||||
- **国际化与语言切换**：完整的 i18next 国际化覆盖，默认显示中文，可在设置中快速切换到英文，界面文案自动实时刷新。
|
|
||||||
- **Claude 插件同步**：内置按钮可一键应用或恢复 Claude 插件配置，切换供应商后立即生效。
|
|
||||||
- **供应商预设扩展**：新增 Longcat、kat-coder 等预设，更新 GLM 供应商配置至最新模型。
|
|
||||||
- **系统托盘与窗口行为**：窗口关闭可最小化到托盘，macOS 支持托盘模式下隐藏/显示 Dock，托盘切换时同步 Claude/Codex/插件状态。
|
|
||||||
- **单实例**：保证同一时间仅运行一个实例，避免多开冲突。
|
|
||||||
- **标准化发布命名**：所有平台发布文件使用一致的版本标签命名（macOS: `.tar.gz` / `.zip`，Windows: `.msi` / `-Portable.zip`，Linux: `.AppImage` / `.deb`）。
|
|
||||||
|
|
||||||
## 界面预览
|
> **v3.6.0**: Added edit mode (provider duplication, manual sorting), custom endpoint management, usage query features. Optimized config directory switching experience (perfect WSL environment support). Added multiple provider presets (DMXAPI, Azure Codex, AnyRouter, AiHubMix, MiniMax). Completed full-stack architecture refactoring and testing infrastructure.
|
||||||
|
|
||||||
### 主界面
|
> v3.5.0: Added MCP management, config import/export, endpoint speed testing. Complete i18n coverage. Added Longcat and kat-coder presets. Standardized release file naming conventions.
|
||||||
|
|
||||||
|
> v3.4.0: Added i18next internationalization, support for new models (qwen-3-max, GLM-4.6, DeepSeek-V3.2-Exp), Claude plugin, single-instance daemon, tray minimize, and installer optimizations.
|
||||||
|
|
||||||
### 添加供应商
|
> v3.3.0: One-click VS Code Codex plugin configuration/removal (auto-sync by default), Codex common config snippets, enhanced custom wizard, WSL environment support, cross-platform tray and UI optimizations. (VS Code write feature deprecated in v3.4.x)
|
||||||
|
|
||||||
|
> v3.2.0: Brand new UI, macOS system tray, built-in updater, atomic write with rollback, improved dark mode, Single Source of Truth (SSOT) with one-time migration/archival.
|
||||||
|
|
||||||
## 下载安装
|
> v3.1.0: Added Codex provider management with one-click switching. Import current Codex config as default provider. Auto-backup before internal config v1 → v2 migration (see "Migration & Archival" below).
|
||||||
|
|
||||||
### 系统要求
|
> v3.0.0 Major Update: Complete migration from Electron to Tauri 2.0. Significantly reduced app size and greatly improved startup performance.
|
||||||
|
|
||||||
- **Windows**: Windows 10 及以上
|
## Features (v3.6.0)
|
||||||
- **macOS**: macOS 10.15 (Catalina) 及以上
|
|
||||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ 等主流发行版
|
|
||||||
|
|
||||||
### Windows 用户
|
### Core Features
|
||||||
|
|
||||||
从 [Releases](../../releases) 页面下载最新版本的 `CC-Switch-v{版本号}-Windows.msi` 安装包或者 `CC-Switch-v{版本号}-Windows-Portable.zip` 绿色版。
|
- **MCP (Model Context Protocol) Management**: Complete MCP server configuration management system
|
||||||
|
- Support for stdio and http server types with command validation
|
||||||
|
- Built-in templates for popular MCP servers (e.g., mcp-fetch)
|
||||||
|
- Real-time enable/disable MCP servers with atomic file writes to prevent configuration corruption
|
||||||
|
- **Config Import/Export**: Backup and restore your provider configurations
|
||||||
|
- One-click export all configurations to JSON file
|
||||||
|
- Import configs with automatic validation and backup, auto-rotate backups (keep 10 most recent)
|
||||||
|
- Auto-sync to live config files after import to ensure immediate effect
|
||||||
|
- **Endpoint Speed Testing**: Test API endpoint response times
|
||||||
|
- Measure latency to different provider endpoints with visual connection quality indicators
|
||||||
|
- Help users choose the fastest provider
|
||||||
|
- **Internationalization & Language Switching**: Complete i18next i18n coverage (including error messages, tray menu, all UI components)
|
||||||
|
- **Claude Plugin Sync**: Built-in button to apply or restore Claude plugin configurations with one click. Takes effect immediately after switching providers.
|
||||||
|
|
||||||
### macOS 用户
|
### v3.6 New Features
|
||||||
|
|
||||||
**方式一：通过 Homebrew 安装（推荐）**
|
- **Provider Duplication**: Quickly duplicate existing provider configs to easily create variants
|
||||||
|
- **Manual Sorting**: Drag and drop to manually reorder providers
|
||||||
|
- **Custom Endpoint Management**: Support multi-endpoint configuration for aggregator providers
|
||||||
|
- **Usage Query Features**
|
||||||
|
- Auto-refresh interval: Supports periodic automatic usage queries
|
||||||
|
- Test Script API: Validate JavaScript scripts before execution
|
||||||
|
- Template system expansion: Custom blank templates, support for access token and user ID parameters
|
||||||
|
- **Config Editor Improvements**
|
||||||
|
- Added JSON format button
|
||||||
|
- Real-time TOML syntax validation (for Codex configs)
|
||||||
|
- **Auto-sync on Directory Change**: When switching Claude/Codex config directories (e.g., switching to WSL environment), automatically sync current provider to new directory to avoid config file conflicts
|
||||||
|
- **Load Live Config When Editing Active Provider**: When editing the currently active provider, prioritize displaying the actual effective configuration to protect user manual modifications
|
||||||
|
- **New Provider Presets**: DMXAPI, Azure Codex, AnyRouter, AiHubMix, MiniMax
|
||||||
|
- **Partner Promotion Mechanism**: Support ecosystem partner promotion (e.g., Zhipu GLM Z.ai)
|
||||||
|
|
||||||
|
### v3.6 Architecture Improvements
|
||||||
|
|
||||||
|
- **Backend Refactoring**: Completed 5-phase refactoring (unified error handling → command layer split → integration tests → Service layer extraction → concurrency optimization)
|
||||||
|
- **Frontend Refactoring**: Completed 4-stage refactoring (test infrastructure → Hooks extraction → component splitting → code cleanup)
|
||||||
|
- **Testing System**: 100% Hooks unit test coverage, integration tests covering critical flows (vitest + MSW + @testing-library/react)
|
||||||
|
|
||||||
|
### System Features
|
||||||
|
|
||||||
|
- **System Tray & Window Behavior**: Window can minimize to tray, macOS supports hide/show Dock in tray mode, tray switching syncs Claude/Codex/plugin status.
|
||||||
|
- **Single Instance**: Ensures only one instance runs at a time to avoid multi-instance conflicts.
|
||||||
|
- **Standardized Release Naming**: All platform release files use consistent version-tagged naming (macOS: `.tar.gz` / `.zip`, Windows: `.msi` / `-Portable.zip`, Linux: `.AppImage` / `.deb`).
|
||||||
|
|
||||||
|
## Screenshots
|
||||||
|
|
||||||
|
### Main Interface
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Add Provider
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Download & Installation
|
||||||
|
|
||||||
|
### System Requirements
|
||||||
|
|
||||||
|
- **Windows**: Windows 10 and above
|
||||||
|
- **macOS**: macOS 10.15 (Catalina) and above
|
||||||
|
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ and other mainstream distributions
|
||||||
|
|
||||||
|
### Windows Users
|
||||||
|
|
||||||
|
Download the latest `CC-Switch-v{version}-Windows.msi` installer or `CC-Switch-v{version}-Windows-Portable.zip` portable version from the [Releases](../../releases) page.
|
||||||
|
|
||||||
|
### macOS Users
|
||||||
|
|
||||||
|
**Method 1: Install via Homebrew (Recommended)**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
brew tap farion1231/ccswitch
|
brew tap farion1231/ccswitch
|
||||||
brew install --cask cc-switch
|
brew install --cask cc-switch
|
||||||
```
|
```
|
||||||
|
|
||||||
更新：
|
Update:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
brew upgrade --cask cc-switch
|
brew upgrade --cask cc-switch
|
||||||
```
|
```
|
||||||
|
|
||||||
**方式二：手动下载**
|
**Method 2: Manual Download**
|
||||||
|
|
||||||
从 [Releases](../../releases) 页面下载 `CC-Switch-v{版本号}-macOS.zip` 解压使用。
|
Download `CC-Switch-v{version}-macOS.zip` from the [Releases](../../releases) page and extract to use.
|
||||||
|
|
||||||
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开
|
> **Note**: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it first, then go to "System Settings" → "Privacy & Security" → click "Open Anyway", and you'll be able to open it normally afterwards.
|
||||||
|
|
||||||
### Linux 用户
|
### Linux Users
|
||||||
|
|
||||||
从 [Releases](../../releases) 页面下载最新版本的 `CC-Switch-v{版本号}-Linux.deb` 包或者 `CC-Switch-v{版本号}-Linux.AppImage` 安装包。
|
Download the latest `CC-Switch-v{version}-Linux.deb` package or `CC-Switch-v{version}-Linux.AppImage` from the [Releases](../../releases) page.
|
||||||
|
|
||||||
## 使用说明
|
## Usage Guide
|
||||||
|
|
||||||
1. 点击"添加供应商"添加你的 API 配置
|
1. Click "Add Provider" to add your API configuration
|
||||||
2. 切换方式：
|
2. Switching methods:
|
||||||
- 在主界面选择供应商后点击切换
|
- Select a provider on the main interface and click switch
|
||||||
- 或通过“系统托盘（菜单栏）”直接选择目标供应商，立即生效
|
- Or directly select target provider from "System Tray (Menu Bar)" for immediate effect
|
||||||
3. 切换会写入对应应用的“live 配置文件”（Claude：`settings.json`；Codex：`auth.json` + `config.toml`）
|
3. Switching will write to the corresponding app's "live config file" (Claude: `settings.json`; Codex: `auth.json` + `config.toml`)
|
||||||
4. 重启或新开终端以确保生效
|
4. Restart or open new terminal to ensure it takes effect
|
||||||
5. 若需切回官方登录，在预设中选择“官方登录”并切换即可；重启终端后按官方流程登录
|
5. To switch back to official login, select "Official Login" from presets and switch; after restarting terminal, follow the official login process
|
||||||
|
|
||||||
### MCP 配置说明（v3.5.x）
|
### MCP Configuration Guide (v3.5.x)
|
||||||
|
|
||||||
- 管理位置：所有 MCP 服务器定义集中保存在 `~/.cc-switch/config.json`（按客户端 `claude` / `codex` 分类）
|
- Management Location: All MCP server definitions are centrally saved in `~/.cc-switch/config.json` (categorized by client `claude` / `codex`)
|
||||||
- 同步机制：
|
- Sync Mechanism:
|
||||||
- 启用的 Claude MCP 会投影到 `~/.claude.json`（路径可随覆盖目录而变化）
|
- Enabled Claude MCP servers are projected to `~/.claude.json` (path may vary with override directory)
|
||||||
- 启用的 Codex MCP 会投影到 `~/.codex/config.toml`
|
- Enabled Codex MCP servers are projected to `~/.codex/config.toml`
|
||||||
- 校验与归一化：新增/导入时自动校验字段合法性（stdio/http），并自动修复/填充 `id` 等键名
|
- Validation & Normalization: Auto-validate field legality (stdio/http) when adding/importing, and auto-fix/populate keys like `id`
|
||||||
- 导入来源：支持从 `~/.claude.json` 与 `~/.codex/config.toml` 导入；已存在条目只强制 `enabled=true`，不覆盖其他字段
|
- Import Sources: Support importing from `~/.claude.json` and `~/.codex/config.toml`; existing entries only force `enabled=true`, don't override other fields
|
||||||
|
|
||||||
### 检查更新
|
### Check for Updates
|
||||||
|
|
||||||
- 在“设置”中点击“检查更新”，若内置 Updater 配置可用将直接检测与下载；否则会回退打开 Releases 页面
|
- Click "Check for Updates" in Settings. If built-in Updater config is available, it will detect and download directly; otherwise, it will fall back to opening the Releases page
|
||||||
|
|
||||||
### Codex 说明（SSOT）
|
### Codex Guide (SSOT)
|
||||||
|
|
||||||
- 配置目录：`~/.codex/`
|
- Config Directory: `~/.codex/`
|
||||||
- live 主配置：`auth.json`（必需）、`config.toml`（可为空）
|
- Live main config: `auth.json` (required), `config.toml` (can be empty)
|
||||||
- API Key 字段：`auth.json` 中使用 `OPENAI_API_KEY`
|
- API Key Field: Uses `OPENAI_API_KEY` in `auth.json`
|
||||||
- 切换行为（不再写“副本文件”）：
|
- Switching Behavior (no longer writes "copy files"):
|
||||||
- 供应商配置统一保存在 `~/.cc-switch/config.json`
|
- Provider configs are uniformly saved in `~/.cc-switch/config.json`
|
||||||
- 切换时将目标供应商写回 live 文件（`auth.json` + `config.toml`）
|
- When switching, writes target provider back to live files (`auth.json` + `config.toml`)
|
||||||
- 采用“原子写入 + 失败回滚”，避免半写状态；`config.toml` 可为空
|
- Uses "atomic write + rollback on failure" to avoid half-written state; `config.toml` can be empty
|
||||||
- 导入默认：当该应用无任何供应商时，从现有 live 主配置创建一条默认项并设为当前
|
- Import Default: When the app has no providers, creates a default entry from existing live main config and sets it as current
|
||||||
- 官方登录：可切换到预设“Codex 官方登录”，重启终端后按官方流程登录
|
- Official Login: Can switch to preset "Codex Official Login", restart terminal and follow official login process
|
||||||
|
|
||||||
### Claude Code 说明（SSOT）
|
### Claude Code Guide (SSOT)
|
||||||
|
|
||||||
- 配置目录：`~/.claude/`
|
- Config Directory: `~/.claude/`
|
||||||
- live 主配置：`settings.json`（优先）或历史兼容 `claude.json`
|
- Live main config: `settings.json` (preferred) or legacy-compatible `claude.json`
|
||||||
- API Key 字段：`env.ANTHROPIC_AUTH_TOKEN`
|
- API Key Field: `env.ANTHROPIC_AUTH_TOKEN`
|
||||||
- 切换行为（不再写“副本文件”）：
|
- Switching Behavior (no longer writes "copy files"):
|
||||||
- 供应商配置统一保存在 `~/.cc-switch/config.json`
|
- Provider configs are uniformly saved in `~/.cc-switch/config.json`
|
||||||
- 切换时将目标供应商 JSON 直接写入 live 文件（优先 `settings.json`）
|
- When switching, writes target provider JSON directly to live file (preferring `settings.json`)
|
||||||
- 编辑当前供应商时，先写 live 成功，再更新应用主配置，保证一致性
|
- When editing current provider, writes live first successfully, then updates app main config to ensure consistency
|
||||||
- 导入默认：当该应用无任何供应商时，从现有 live 主配置创建一条默认项并设为当前
|
- Import Default: When the app has no providers, creates a default entry from existing live main config and sets it as current
|
||||||
- 官方登录：可切换到预设“Claude 官方登录”，重启终端后可使用 `/login` 完成登录
|
- Official Login: Can switch to preset "Claude Official Login", restart terminal and use `/login` to complete login
|
||||||
|
|
||||||
### 迁移与归档（自 v3.2.0 起）
|
### Migration & Archival
|
||||||
|
|
||||||
- 一次性迁移：首次启动 3.2.0 及以上版本会扫描旧的“副本文件”并合并到 `~/.cc-switch/config.json`
|
#### v3.6 Technical Improvements
|
||||||
- Claude：`~/.claude/settings-*.json`（排除 `settings.json` / 历史 `claude.json`）
|
|
||||||
- Codex：`~/.codex/auth-*.json` 与 `config-*.toml`（按名称成对合并）
|
|
||||||
- 去重与当前项：按“名称（忽略大小写）+ API Key”去重；若当前为空，将 live 合并项设为当前
|
|
||||||
- 归档与清理：
|
|
||||||
- 归档目录：`~/.cc-switch/archive/<timestamp>/<category>/...`
|
|
||||||
- 归档成功后删除原副本；失败则保留原文件（保守策略）
|
|
||||||
- v1 → v2 结构升级：会额外生成 `~/.cc-switch/config.v1.backup.<timestamp>.json` 以便回滚
|
|
||||||
- 注意：迁移后不再持续归档日常切换/编辑操作，如需长期审计请自备备份方案
|
|
||||||
|
|
||||||
## 架构总览（v3.5.x）
|
**Internal Optimizations (User Transparent)**:
|
||||||
|
|
||||||
- 前端（Renderer）
|
- **Removed Legacy Migration Logic**: v3.6 removed v1 config auto-migration and copy file scanning logic
|
||||||
- 技术栈：TypeScript + React 18 + Vite + TailwindCSS
|
- ✅ **Impact**: Improved startup performance, cleaner code
|
||||||
- 数据层：TanStack React Query 统一查询与变更（`@/lib/query`），Tauri API 统一封装（`@/lib/api`）
|
- ✅ **Compatibility**: v2 format configs are fully compatible, no action required
|
||||||
- 事件流：监听后端 `provider-switched` 事件，驱动 UI 刷新与托盘状态一致
|
- ⚠️ **Note**: Users upgrading from v3.1.0 or earlier should first upgrade to v3.2.x or v3.5.x for one-time migration, then upgrade to v3.6
|
||||||
- 组织结构：按领域拆分组件（providers/settings/mcp），动作逻辑下沉至 Hooks（如 `useProviderActions`）
|
|
||||||
|
|
||||||
- 后端（Tauri + Rust）
|
- **Command Parameter Standardization**: Backend unified to use `app` parameter (values: `claude` or `codex`)
|
||||||
- Commands（接口层）：`src-tauri/src/commands/*` 按领域拆分（provider/config/mcp 等）
|
- ✅ **Impact**: More standardized code, friendlier error messages
|
||||||
- Services（业务层）：`src-tauri/src/services/*` 承载核心逻辑（Provider/MCP/Config/Speedtest）
|
- ✅ **Compatibility**: Frontend fully adapted, users don't need to care about this change
|
||||||
- 模型与状态：`provider.rs`（领域模型）+ `app_config.rs`（多应用配置）+ `store.rs`（全局 RwLock）
|
|
||||||
- 可靠性：
|
|
||||||
- 统一错误类型 `AppError`（包含本地化消息）
|
|
||||||
- 事务式变更（配置快照 + 失败回滚）与原子写入（避免半写入）
|
|
||||||
- 托盘菜单与事件：切换后重建菜单并向前端发射 `provider-switched` 事件
|
|
||||||
|
|
||||||
- 设计要点（SSOT）
|
#### Startup Failure & Recovery
|
||||||
- 单一事实源：供应商配置集中存放于 `~/.cc-switch/config.json`
|
|
||||||
- 切换时仅写 live 配置（Claude: `settings.json`；Codex: `auth.json` + `config.toml`）
|
|
||||||
- 首次缺省导入：当某应用无任何供应商时，会从已有 live 配置生成默认项
|
|
||||||
|
|
||||||
- 兼容性与变更
|
- Trigger Conditions: Triggered when `~/.cc-switch/config.json` doesn't exist, is corrupted, or fails to parse.
|
||||||
- 命令参数统一：Tauri 命令仅接受 `app`（值为 `claude` / `codex`）
|
- User Action: Check JSON syntax according to popup prompt, or restore from backup files.
|
||||||
- 前端类型统一：使用 `AppId` 表达应用标识（替代历史 `AppType` 导出）
|
- Backup Location & Rotation: `~/.cc-switch/backups/backup_YYYYMMDD_HHMMSS.json` (keep up to 10, see `src-tauri/src/services/config.rs`).
|
||||||
|
- Exit Strategy: To protect data safety, the app will show a popup and force exit when the above errors occur; restart after fixing.
|
||||||
|
|
||||||
## 开发
|
#### Migration Mechanism (v3.2.0+)
|
||||||
|
|
||||||
### 环境要求
|
- One-time Migration: First launch of v3.2.0+ will scan old "copy files" and merge into `~/.cc-switch/config.json`
|
||||||
|
- Claude: `~/.claude/settings-*.json` (excluding `settings.json` / legacy `claude.json`)
|
||||||
|
- Codex: `~/.codex/auth-*.json` and `config-*.toml` (merged in pairs by name)
|
||||||
|
- Deduplication & Current Item: Deduplicate by "name (case-insensitive) + API Key"; if current is empty, set live merged item as current
|
||||||
|
- Archival & Cleanup:
|
||||||
|
- Archive directory: `~/.cc-switch/archive/<timestamp>/<category>/...`
|
||||||
|
- Delete original copies after successful archival; keep original files on failure (conservative strategy)
|
||||||
|
- v1 → v2 Structure Upgrade: Additionally generates `~/.cc-switch/config.v1.backup.<timestamp>.json` for rollback
|
||||||
|
- Note: After migration, daily switch/edit operations are no longer archived; prepare your own backup solution if long-term auditing is needed
|
||||||
|
|
||||||
|
## Architecture Overview (v3.6)
|
||||||
|
|
||||||
|
### Architecture Refactoring Highlights (v3.6)
|
||||||
|
|
||||||
|
**Backend Refactoring (Rust)**: Completed 5-phase refactoring
|
||||||
|
|
||||||
|
- **Phase 1**: Unified error handling (`AppError` + i18n error messages)
|
||||||
|
- **Phase 2**: Command layer split by domain (`commands/{provider,mcp,config,settings,plugin,misc}.rs`)
|
||||||
|
- **Phase 3**: Introduced integration tests and transaction mechanism (config snapshot + failure rollback)
|
||||||
|
- **Phase 4**: Extracted Service layer (`services/{provider,mcp,config,speedtest}.rs`)
|
||||||
|
- **Phase 5**: Concurrency optimization (`RwLock` instead of `Mutex`, scoped guard to avoid deadlock)
|
||||||
|
|
||||||
|
**Frontend Refactoring (React + TypeScript)**: Completed 4-stage refactoring
|
||||||
|
|
||||||
|
- **Stage 1**: Established test infrastructure (vitest + MSW + @testing-library/react)
|
||||||
|
- **Stage 2**: Extracted custom hooks (`useProviderActions`, `useMcpActions`, `useSettings`, `useImportExport`, etc.)
|
||||||
|
- **Stage 3**: Component splitting and business logic extraction
|
||||||
|
- **Stage 4**: Code cleanup and formatting unification
|
||||||
|
|
||||||
|
**Test Coverage**:
|
||||||
|
|
||||||
|
- 100% Hooks unit test coverage
|
||||||
|
- Integration tests covering critical flows (App, SettingsDialog, MCP Panel)
|
||||||
|
- MSW mocking backend API to ensure test independence
|
||||||
|
|
||||||
|
### Layered Architecture
|
||||||
|
|
||||||
|
- **Frontend (Renderer)**
|
||||||
|
- Tech Stack: TypeScript + React 18 + Vite + TailwindCSS 4
|
||||||
|
- Data Layer: TanStack React Query unified queries and mutations (`@/lib/query`), Tauri API unified wrapper (`@/lib/api`)
|
||||||
|
- Business Logic Layer: Custom Hooks (`@/hooks`) carry domain logic, components stay simple
|
||||||
|
- Event Flow: Listen to backend `provider-switched` events, drive UI refresh and tray state consistency
|
||||||
|
- Organization: Components split by domain (`providers/settings/mcp/ui`)
|
||||||
|
|
||||||
|
- **Backend (Tauri + Rust)**
|
||||||
|
- **Commands Layer** (Interface Layer): `src-tauri/src/commands/*` split by domain, only responsible for parameter parsing and permission validation
|
||||||
|
- **Services Layer** (Business Layer): `src-tauri/src/services/*` carry core logic, reusable and testable
|
||||||
|
- `ProviderService`: Provider CRUD, switch, backfill, sorting
|
||||||
|
- `McpService`: MCP server management, import/export, sync
|
||||||
|
- `ConfigService`: Config file import/export, backup/restore
|
||||||
|
- `SpeedtestService`: API endpoint latency testing
|
||||||
|
- **Models & State**:
|
||||||
|
- `provider.rs`: Domain models (`Provider`, `ProviderManager`, `ProviderMeta`)
|
||||||
|
- `app_config.rs`: Multi-app config (`MultiAppConfig`, `AppId`, `McpRoot`)
|
||||||
|
- `store.rs`: Global state (`AppState` + `RwLock<MultiAppConfig>`)
|
||||||
|
- **Reliability**:
|
||||||
|
- Unified error type `AppError` (with localized messages)
|
||||||
|
- Transactional changes (config snapshot + failure rollback)
|
||||||
|
- Atomic writes (temp file + rename, avoid half-writes)
|
||||||
|
- Tray menu & events: Rebuild menu after switch and emit `provider-switched` event to frontend
|
||||||
|
|
||||||
|
- **Design Points (SSOT + Dual-way Sync)**
|
||||||
|
- **Single Source of Truth**: Provider configs centrally stored in `~/.cc-switch/config.json`
|
||||||
|
- **Write on Switch**: Write target provider config to live files (Claude: `settings.json`; Codex: `auth.json` + `config.toml`)
|
||||||
|
- **Backfill Mechanism**: Immediately read back live files after switch, update SSOT to protect user manual modifications
|
||||||
|
- **Directory Switch Sync**: Auto-sync current provider to new directory when changing config directories (perfect WSL environment support)
|
||||||
|
- **Prioritize Live When Editing**: When editing current provider, prioritize loading live config to ensure display of actually effective configuration
|
||||||
|
|
||||||
|
- **Compatibility & Changes**
|
||||||
|
- Command Parameters Unified: Tauri commands only accept `app` (values: `claude` / `codex`)
|
||||||
|
- Frontend Types Unified: Use `AppId` to express app identifiers (replacing legacy `AppType` export)
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
### Environment Requirements
|
||||||
|
|
||||||
- Node.js 18+
|
- Node.js 18+
|
||||||
- pnpm 8+
|
- pnpm 8+
|
||||||
- Rust 1.75+
|
- Rust 1.85+
|
||||||
- Tauri CLI 2.0+
|
- Tauri CLI 2.8+
|
||||||
|
|
||||||
### 开发命令
|
### Development Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 安装依赖
|
# Install dependencies
|
||||||
pnpm install
|
pnpm install
|
||||||
|
|
||||||
# 开发模式（热重载）
|
# Dev mode (hot reload)
|
||||||
pnpm dev
|
pnpm dev
|
||||||
|
|
||||||
# 类型检查
|
# Type check
|
||||||
pnpm typecheck
|
pnpm typecheck
|
||||||
|
|
||||||
# 代码格式化
|
# Format code
|
||||||
pnpm format
|
pnpm format
|
||||||
|
|
||||||
# 检查代码格式
|
# Check code format
|
||||||
pnpm format:check
|
pnpm format:check
|
||||||
|
|
||||||
# 运行前端单元测试
|
# Run frontend unit tests
|
||||||
pnpm test:unit
|
pnpm test:unit
|
||||||
|
|
||||||
# 监听模式运行测试
|
# Run tests in watch mode (recommended for development)
|
||||||
pnpm test:unit:watch
|
pnpm test:unit:watch
|
||||||
|
|
||||||
# 构建应用
|
# Build application
|
||||||
pnpm build
|
pnpm build
|
||||||
|
|
||||||
# 构建调试版本
|
# Build debug version
|
||||||
pnpm tauri build --debug
|
pnpm tauri build --debug
|
||||||
```
|
```
|
||||||
|
|
||||||
### Rust 后端开发
|
### Rust Backend Development
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd src-tauri
|
cd src-tauri
|
||||||
|
|
||||||
# 格式化 Rust 代码
|
# Format Rust code
|
||||||
cargo fmt
|
cargo fmt
|
||||||
|
|
||||||
# 运行 clippy 检查
|
# Run clippy checks
|
||||||
cargo clippy
|
cargo clippy
|
||||||
|
|
||||||
# 运行测试
|
# Run backend tests
|
||||||
cargo test
|
cargo test
|
||||||
|
|
||||||
|
# Run specific tests
|
||||||
|
cargo test test_name
|
||||||
|
|
||||||
|
# Run tests with test-hooks feature
|
||||||
|
cargo test --features test-hooks
|
||||||
```
|
```
|
||||||
|
|
||||||
## 技术栈
|
### Testing Guide (v3.6 New)
|
||||||
|
|
||||||
- **[Tauri 2](https://tauri.app/)** - 跨平台桌面应用框架（集成 updater/process/opener/log/tray-icon）
|
**Frontend Testing**:
|
||||||
- **[React 18](https://react.dev/)** - 用户界面库
|
|
||||||
- **[TypeScript](https://www.typescriptlang.org/)** - 类型安全的 JavaScript
|
|
||||||
- **[Vite](https://vitejs.dev/)** - 极速的前端构建工具
|
|
||||||
- **[Rust](https://www.rust-lang.org/)** - 系统级编程语言（后端）
|
|
||||||
- **[TanStack Query](https://tanstack.com/query/latest)** - 前端数据获取与缓存
|
|
||||||
- **[i18next](https://www.i18next.com/)** - 国际化框架
|
|
||||||
|
|
||||||
## 项目结构
|
- Uses **vitest** as test framework
|
||||||
|
- Uses **MSW (Mock Service Worker)** to mock Tauri API calls
|
||||||
|
- Uses **@testing-library/react** for component testing
|
||||||
|
|
||||||
|
**Test Coverage**:
|
||||||
|
|
||||||
|
- ✅ Hooks unit tests (100% coverage)
|
||||||
|
- `useProviderActions` - Provider operations
|
||||||
|
- `useMcpActions` - MCP management
|
||||||
|
- `useSettings` series - Settings management
|
||||||
|
- `useImportExport` - Import/export
|
||||||
|
- ✅ Integration tests
|
||||||
|
- App main application flow
|
||||||
|
- SettingsDialog complete interaction
|
||||||
|
- MCP panel functionality
|
||||||
|
|
||||||
|
**Running Tests**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run all tests
|
||||||
|
pnpm test:unit
|
||||||
|
|
||||||
|
# Watch mode (auto re-run)
|
||||||
|
pnpm test:unit:watch
|
||||||
|
|
||||||
|
# With coverage report
|
||||||
|
pnpm test:unit --coverage
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
|
||||||
|
- **[React 18](https://react.dev/)** - User interface library
|
||||||
|
- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript
|
||||||
|
- **[Vite](https://vitejs.dev/)** - Lightning fast frontend build tool
|
||||||
|
- **[TailwindCSS 4](https://tailwindcss.com/)** - Utility-first CSS framework
|
||||||
|
- **[TanStack Query v5](https://tanstack.com/query/latest)** - Powerful data fetching and caching
|
||||||
|
- **[react-i18next](https://react.i18next.com/)** - React internationalization framework
|
||||||
|
- **[react-hook-form](https://react-hook-form.com/)** - High-performance forms library
|
||||||
|
- **[zod](https://zod.dev/)** - TypeScript-first schema validation
|
||||||
|
- **[shadcn/ui](https://ui.shadcn.com/)** - Reusable React components
|
||||||
|
- **[@dnd-kit](https://dndkit.com/)** - Modern drag and drop toolkit
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
|
||||||
|
- **[Tauri 2.8](https://tauri.app/)** - Cross-platform desktop app framework
|
||||||
|
- tauri-plugin-updater - Auto update
|
||||||
|
- tauri-plugin-process - Process management
|
||||||
|
- tauri-plugin-dialog - File dialogs
|
||||||
|
- tauri-plugin-store - Persistent storage
|
||||||
|
- tauri-plugin-log - Logging
|
||||||
|
- **[Rust](https://www.rust-lang.org/)** - Systems programming language
|
||||||
|
- **[serde](https://serde.rs/)** - Serialization/deserialization framework
|
||||||
|
- **[tokio](https://tokio.rs/)** - Async runtime
|
||||||
|
- **[thiserror](https://github.com/dtolnay/thiserror)** - Error handling derive macro
|
||||||
|
|
||||||
|
### Testing Tools
|
||||||
|
|
||||||
|
- **[vitest](https://vitest.dev/)** - Fast unit testing framework
|
||||||
|
- **[MSW](https://mswjs.io/)** - API mocking tool
|
||||||
|
- **[@testing-library/react](https://testing-library.com/react)** - React testing utilities
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
├── src/ # 前端代码 (React + TypeScript)
|
├── src/ # Frontend code (React + TypeScript)
|
||||||
│ ├── components/ # React 组件（providers/settings/mcp/ui 等）
|
│ ├── components/ # React components
|
||||||
│ ├── hooks/ # 领域动作与状态（如 useProviderActions）
|
│ │ ├── providers/ # Provider management components
|
||||||
|
│ │ │ ├── forms/ # Form sub-components (Claude/Codex fields)
|
||||||
|
│ │ │ ├── ProviderList.tsx
|
||||||
|
│ │ │ ├── ProviderForm.tsx
|
||||||
|
│ │ │ ├── AddProviderDialog.tsx
|
||||||
|
│ │ │ └── EditProviderDialog.tsx
|
||||||
|
│ │ ├── settings/ # Settings related components
|
||||||
|
│ │ │ ├── SettingsDialog.tsx
|
||||||
|
│ │ │ ├── DirectorySettings.tsx
|
||||||
|
│ │ │ └── ImportExportSection.tsx
|
||||||
|
│ │ ├── mcp/ # MCP management components
|
||||||
|
│ │ │ ├── McpPanel.tsx
|
||||||
|
│ │ │ ├── McpFormModal.tsx
|
||||||
|
│ │ │ └── McpWizard.tsx
|
||||||
|
│ │ └── ui/ # shadcn/ui base components
|
||||||
|
│ ├── hooks/ # Custom Hooks (business logic layer)
|
||||||
|
│ │ ├── useProviderActions.ts # Provider operations
|
||||||
|
│ │ ├── useMcpActions.ts # MCP operations
|
||||||
|
│ │ ├── useSettings.ts # Settings management
|
||||||
|
│ │ ├── useImportExport.ts # Import/export
|
||||||
|
│ │ └── useDirectorySettings.ts # Directory config
|
||||||
│ ├── lib/
|
│ ├── lib/
|
||||||
│ │ ├── api/ # Tauri API 封装（providers/settings/mcp 等）
|
│ │ ├── api/ # Tauri API wrapper (type-safe)
|
||||||
│ │ └── query/ # TanStack Query 查询/变更与 client
|
│ │ │ ├── providers.ts # Provider API
|
||||||
│ ├── i18n/ # 国际化资源
|
│ │ │ ├── settings.ts # Settings API
|
||||||
│ ├── config/ # 供应商/MCP 预设
|
│ │ │ ├── mcp.ts # MCP API
|
||||||
│ └── utils/ # 工具函数
|
│ │ │ └── usage.ts # Usage query API
|
||||||
├── src-tauri/ # 后端代码 (Rust)
|
│ │ └── query/ # TanStack Query config
|
||||||
│ ├── src/ # Rust 源代码
|
│ │ ├── queries.ts # Query definitions
|
||||||
│ │ ├── commands/ # Tauri 命令定义（按域拆分）
|
│ │ ├── mutations.ts # Mutation definitions
|
||||||
│ │ ├── services/ # 领域服务（Provider/MCP/Speedtest 等）
|
│ │ └── queryClient.ts
|
||||||
│ │ ├── mcp.rs # MCP 同步与规范化
|
│ ├── i18n/ # Internationalization resources
|
||||||
│ │ ├── migration.rs # 配置迁移逻辑
|
│ │ └── locales/
|
||||||
│ │ ├── config.rs # 配置文件管理
|
│ │ ├── zh/ # Chinese translations
|
||||||
│ │ ├── provider.rs # 供应商管理逻辑
|
│ │ └── en/ # English translations
|
||||||
│ │ └── store.rs # 状态管理
|
│ ├── config/ # Config & presets
|
||||||
│ ├── capabilities/ # 权限配置
|
│ │ ├── claudeProviderPresets.ts # Claude provider presets
|
||||||
│ └── icons/ # 应用图标资源
|
│ │ ├── codexProviderPresets.ts # Codex provider presets
|
||||||
└── screenshots/ # 界面截图
|
│ │ └── mcpPresets.ts # MCP server templates
|
||||||
|
│ ├── utils/ # Utility functions
|
||||||
|
│ │ ├── postChangeSync.ts # Config sync utility
|
||||||
|
│ │ └── ...
|
||||||
|
│ └── types/ # TypeScript type definitions
|
||||||
|
├── src-tauri/ # Backend code (Rust)
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── commands/ # Tauri command layer (split by domain)
|
||||||
|
│ │ │ ├── provider.rs # Provider commands
|
||||||
|
│ │ │ ├── mcp.rs # MCP commands
|
||||||
|
│ │ │ ├── config.rs # Config query commands
|
||||||
|
│ │ │ ├── settings.rs # Settings commands
|
||||||
|
│ │ │ ├── plugin.rs # Plugin commands
|
||||||
|
│ │ │ ├── import_export.rs # Import/export commands
|
||||||
|
│ │ │ └── misc.rs # Misc commands
|
||||||
|
│ │ ├── services/ # Service layer (business logic)
|
||||||
|
│ │ │ ├── provider.rs # ProviderService
|
||||||
|
│ │ │ ├── mcp.rs # McpService
|
||||||
|
│ │ │ ├── config.rs # ConfigService
|
||||||
|
│ │ │ └── speedtest.rs # SpeedtestService
|
||||||
|
│ │ ├── app_config.rs # Config data models
|
||||||
|
│ │ ├── provider.rs # Provider domain models
|
||||||
|
│ │ ├── store.rs # Global state management
|
||||||
|
│ │ ├── mcp.rs # MCP sync & validation
|
||||||
|
│ │ ├── error.rs # Unified error type
|
||||||
|
│ │ ├── usage_script.rs # Usage script execution
|
||||||
|
│ │ ├── claude_plugin.rs # Claude plugin management
|
||||||
|
│ │ └── lib.rs # App entry point
|
||||||
|
│ ├── capabilities/ # Tauri permission config
|
||||||
|
│ └── icons/ # App icons
|
||||||
|
├── tests/ # Frontend tests (v3.6 new)
|
||||||
|
│ ├── hooks/ # Hooks unit tests
|
||||||
|
│ ├── components/ # Component integration tests
|
||||||
|
│ └── setup.ts # Test config
|
||||||
|
└── assets/ # Static resources
|
||||||
|
├── screenshots/ # Interface screenshots
|
||||||
|
└── partners/ # Partner resources
|
||||||
|
├── logos/ # Partner logos
|
||||||
|
└── banners/ # Partner banners/promotional images
|
||||||
```
|
```
|
||||||
|
|
||||||
## 更新日志
|
## Changelog
|
||||||
|
|
||||||
查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新详情。
|
See [CHANGELOG.md](CHANGELOG.md) for version update details.
|
||||||
|
|
||||||
## Electron 旧版
|
## Legacy Electron Version
|
||||||
|
|
||||||
[Releases](../../releases) 里保留 v2.0.3 Electron 旧版
|
[Releases](../../releases) retains v2.0.3 legacy Electron version
|
||||||
|
|
||||||
如果需要旧版 Electron 代码，可以拉取 electron-legacy 分支
|
If you need legacy Electron code, you can pull the electron-legacy branch
|
||||||
|
|
||||||
## 贡献
|
## Contributing
|
||||||
|
|
||||||
欢迎提交 Issue 反馈问题和建议！
|
Issues and suggestions are welcome!
|
||||||
|
|
||||||
提交 PR 前请确保：
|
Before submitting PRs, please ensure:
|
||||||
- 通过类型检查：`pnpm typecheck`
|
|
||||||
- 通过格式检查：`pnpm format:check`
|
- Pass type check: `pnpm typecheck`
|
||||||
- 通过单元测试：`pnpm test:unit`
|
- Pass format check: `pnpm format:check`
|
||||||
|
- Pass unit tests: `pnpm test:unit`
|
||||||
|
- Functional PRs should be discussed in the issue area first
|
||||||
|
|
||||||
## Star History
|
## Star History
|
||||||
|
|
||||||
|
|||||||
517
README_ZH.md
Normal file
517
README_ZH.md
Normal file
@@ -0,0 +1,517 @@
|
|||||||
|
# Claude Code & Codex 供应商管理器
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
[](https://github.com/farion1231/cc-switch/releases)
|
||||||
|
[](https://github.com/farion1231/cc-switch/releases)
|
||||||
|
[](https://tauri.app/)
|
||||||
|
|
||||||
|
[English](README.md) | 中文 | [更新日志](CHANGELOG.md)
|
||||||
|
|
||||||
|
一个用于管理和切换 Claude Code 与 Codex 不同供应商配置、MCP的桌面应用。
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## ❤️ 赞助商
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
感谢智谱AI的 GLM CODING PLAN 赞助了本项目！
|
||||||
|
|
||||||
|
GLM CODING PLAN 是专为AI编码打造的订阅套餐，每月最低仅需20元，即可在十余款主流AI编码工具如 Claude Code、Cline 中畅享智谱旗舰模型 GLM-4.6，为开发者提供顶尖、高速、稳定的编码体验。
|
||||||
|
|
||||||
|
CC Switch 已经预设了智谱GLM，只需要填写 key 即可一键导入编程工具。智谱AI为本软件的用户提供了特别优惠，使用[此链接](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII)购买可以享受九折优惠。
|
||||||
|
|
||||||
|
## 更新记录
|
||||||
|
|
||||||
|
> **v3.6.0** ：新增编辑模式（供应商复制、手动排序）、自定义端点管理、使用量查询等功能，优化配置目录切换体验（WSL 环境完美支持），新增多个供应商预设（DMXAPI、Azure Codex、AnyRouter、AiHubMix、MiniMax），完成全栈架构重构和测试体系建设。
|
||||||
|
|
||||||
|
> v3.5.0 ：新增 MCP 管理、配置导入/导出、端点速度测试功能，完善国际化覆盖，新增 Longcat、kat-coder 预设，标准化发布文件命名规范。
|
||||||
|
|
||||||
|
> v3.4.0 ：新增 i18next 国际化、对新模型（qwen-3-max, GLM-4.6, DeepSeek-V3.2-Exp）的支持、Claude 插件、单实例守护、托盘最小化及安装器优化等。
|
||||||
|
|
||||||
|
> v3.3.0 ：VS Code Codex 插件一键配置/移除（默认自动同步）、Codex 通用配置片段与自定义向导增强、WSL 环境支持、跨平台托盘与 UI 优化。（该 VS Code 写入功能已在 v3.4.x 停用）
|
||||||
|
|
||||||
|
> v3.2.0 ：全新 UI、macOS系统托盘、内置更新器、原子写入与回滚、改进暗色样式、单一事实源（SSOT）与一次性迁移/归档。
|
||||||
|
|
||||||
|
> v3.1.0 ：新增 Codex 供应商管理与一键切换，支持导入当前 Codex 配置为默认供应商，并在内部配置从 v1 → v2 迁移前自动备份（详见下文“迁移与归档”）。
|
||||||
|
|
||||||
|
> v3.0.0 重大更新：从 Electron 完全迁移到 Tauri 2.0，应用体积显著降低、启动性能大幅提升。
|
||||||
|
|
||||||
|
## 功能特性（v3.6.0）
|
||||||
|
|
||||||
|
### 核心功能
|
||||||
|
|
||||||
|
- **MCP (Model Context Protocol) 管理**：完整的 MCP 服务器配置管理系统
|
||||||
|
- 支持 stdio 和 http 服务器类型，并提供命令校验
|
||||||
|
- 内置常用 MCP 服务器模板（如 mcp-fetch 等）
|
||||||
|
- 实时启用/禁用 MCP 服务器，原子文件写入防止配置损坏
|
||||||
|
- **配置导入/导出**：备份和恢复你的供应商配置
|
||||||
|
- 一键导出所有配置到 JSON 文件
|
||||||
|
- 导入配置时自动验证并备份，自动轮换备份（保留最近 10 个）
|
||||||
|
- 导入后自动同步到 live 配置文件，确保立即生效
|
||||||
|
- **端点速度测试**：测试 API 端点响应时间
|
||||||
|
- 测量不同供应商端点的延迟，可视化连接质量指示器
|
||||||
|
- 帮助用户选择最快的供应商
|
||||||
|
- **国际化与语言切换**：完整的 i18next 国际化覆盖（包含错误消息、托盘菜单、所有 UI 组件）
|
||||||
|
- **Claude 插件同步**：内置按钮可一键应用或恢复 Claude 插件配置，切换供应商后立即生效。
|
||||||
|
|
||||||
|
### v3.6 新增功能
|
||||||
|
|
||||||
|
- **供应商复制功能**：快速复制现有供应商配置，轻松创建变体配置
|
||||||
|
- **手动排序功能**：通过拖拽来对供应商进行手动排序
|
||||||
|
- **自定义端点管理**：支持聚合类供应商的多端点配置
|
||||||
|
- **使用量查询功能**
|
||||||
|
- 自动刷新间隔：支持定时自动查询使用量
|
||||||
|
- 测试脚本 API：测试 JavaScript 脚本是否正确
|
||||||
|
- 模板系统扩展：自定义空白模板、支持 access token 和 user ID 参数
|
||||||
|
- **配置编辑器改进**
|
||||||
|
- 新增 JSON 格式化按钮
|
||||||
|
- 实时 TOML 语法验证（Codex 配置）
|
||||||
|
- **配置目录切换自动同步**：切换 Claude/Codex 配置目录（如切换到 WSL 环境）时，自动同步当前供应商到新目录，避免冲突导致配置文件混乱
|
||||||
|
- **编辑当前供应商时加载 live 配置**：编辑正在使用的供应商时，优先显示实际生效的配置，保护用户手动修改
|
||||||
|
- **新增供应商预设**：DMXAPI、Azure Codex、AnyRouter、AiHubMix、MiniMax
|
||||||
|
- **合作伙伴推广机制**：支持生态合作伙伴推广（如智谱 GLM Z.ai）
|
||||||
|
|
||||||
|
### v3.6 架构改进
|
||||||
|
|
||||||
|
- **后端重构**：完成 5 阶段重构（统一错误处理 → 命令层拆分 → 集成测试 → Service 层提取 → 并发优化）
|
||||||
|
- **前端重构**：完成 4 阶段重构（测试基础设施 → Hooks 提取 → 组件拆分 → 代码清理）
|
||||||
|
- **测试体系**：Hooks 单元测试 100% 覆盖，集成测试覆盖关键流程（vitest + MSW + @testing-library/react）
|
||||||
|
|
||||||
|
### 系统功能
|
||||||
|
|
||||||
|
- **系统托盘与窗口行为**：窗口关闭可最小化到托盘，macOS 支持托盘模式下隐藏/显示 Dock，托盘切换时同步 Claude/Codex/插件状态。
|
||||||
|
- **单实例**：保证同一时间仅运行一个实例，避免多开冲突。
|
||||||
|
- **标准化发布命名**：所有平台发布文件使用一致的版本标签命名（macOS: `.tar.gz` / `.zip`，Windows: `.msi` / `-Portable.zip`，Linux: `.AppImage` / `.deb`）。
|
||||||
|
|
||||||
|
## 界面预览
|
||||||
|
|
||||||
|
### 主界面
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### 添加供应商
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 下载安装
|
||||||
|
|
||||||
|
### 系统要求
|
||||||
|
|
||||||
|
- **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` 解压使用。
|
||||||
|
|
||||||
|
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开
|
||||||
|
|
||||||
|
### Linux 用户
|
||||||
|
|
||||||
|
从 [Releases](../../releases) 页面下载最新版本的 `CC-Switch-v{版本号}-Linux.deb` 包或者 `CC-Switch-v{版本号}-Linux.AppImage` 安装包。
|
||||||
|
|
||||||
|
## 使用说明
|
||||||
|
|
||||||
|
1. 点击"添加供应商"添加你的 API 配置
|
||||||
|
2. 切换方式：
|
||||||
|
- 在主界面选择供应商后点击切换
|
||||||
|
- 或通过“系统托盘（菜单栏）”直接选择目标供应商，立即生效
|
||||||
|
3. 切换会写入对应应用的“live 配置文件”（Claude：`settings.json`；Codex：`auth.json` + `config.toml`）
|
||||||
|
4. 重启或新开终端以确保生效
|
||||||
|
5. 若需切回官方登录，在预设中选择“官方登录”并切换即可；重启终端后按官方流程登录
|
||||||
|
|
||||||
|
### MCP 配置说明（v3.5.x）
|
||||||
|
|
||||||
|
- 管理位置：所有 MCP 服务器定义集中保存在 `~/.cc-switch/config.json`（按客户端 `claude` / `codex` 分类）
|
||||||
|
- 同步机制：
|
||||||
|
- 启用的 Claude MCP 会投影到 `~/.claude.json`（路径可随覆盖目录而变化）
|
||||||
|
- 启用的 Codex MCP 会投影到 `~/.codex/config.toml`
|
||||||
|
- 校验与归一化：新增/导入时自动校验字段合法性（stdio/http），并自动修复/填充 `id` 等键名
|
||||||
|
- 导入来源：支持从 `~/.claude.json` 与 `~/.codex/config.toml` 导入；已存在条目只强制 `enabled=true`，不覆盖其他字段
|
||||||
|
|
||||||
|
### 检查更新
|
||||||
|
|
||||||
|
- 在“设置”中点击“检查更新”，若内置 Updater 配置可用将直接检测与下载；否则会回退打开 Releases 页面
|
||||||
|
|
||||||
|
### Codex 说明（SSOT）
|
||||||
|
|
||||||
|
- 配置目录：`~/.codex/`
|
||||||
|
- live 主配置：`auth.json`（必需）、`config.toml`（可为空）
|
||||||
|
- API Key 字段：`auth.json` 中使用 `OPENAI_API_KEY`
|
||||||
|
- 切换行为（不再写“副本文件”）：
|
||||||
|
- 供应商配置统一保存在 `~/.cc-switch/config.json`
|
||||||
|
- 切换时将目标供应商写回 live 文件（`auth.json` + `config.toml`）
|
||||||
|
- 采用“原子写入 + 失败回滚”，避免半写状态；`config.toml` 可为空
|
||||||
|
- 导入默认：当该应用无任何供应商时，从现有 live 主配置创建一条默认项并设为当前
|
||||||
|
- 官方登录：可切换到预设“Codex 官方登录”，重启终端后按官方流程登录
|
||||||
|
|
||||||
|
### Claude Code 说明（SSOT）
|
||||||
|
|
||||||
|
- 配置目录：`~/.claude/`
|
||||||
|
- live 主配置：`settings.json`（优先）或历史兼容 `claude.json`
|
||||||
|
- API Key 字段：`env.ANTHROPIC_AUTH_TOKEN`
|
||||||
|
- 切换行为（不再写“副本文件”）：
|
||||||
|
- 供应商配置统一保存在 `~/.cc-switch/config.json`
|
||||||
|
- 切换时将目标供应商 JSON 直接写入 live 文件（优先 `settings.json`）
|
||||||
|
- 编辑当前供应商时，先写 live 成功，再更新应用主配置，保证一致性
|
||||||
|
- 导入默认：当该应用无任何供应商时，从现有 live 主配置创建一条默认项并设为当前
|
||||||
|
- 官方登录：可切换到预设“Claude 官方登录”，重启终端后可使用 `/login` 完成登录
|
||||||
|
|
||||||
|
### 迁移与归档
|
||||||
|
|
||||||
|
#### v3.6 技术改进
|
||||||
|
|
||||||
|
**内部优化（用户无感知）**：
|
||||||
|
|
||||||
|
- **移除遗留迁移逻辑**：v3.6 移除了 v1 配置自动迁移和副本文件扫描逻辑
|
||||||
|
- ✅ **影响**：启动性能提升，代码更简洁
|
||||||
|
- ✅ **兼容性**：v2 格式配置完全兼容，无需任何操作
|
||||||
|
- ⚠️ **注意**：从 v3.1.0 或更早版本升级的用户，请先升级到 v3.2.x 或 v3.5.x 完成一次性迁移，再升级到 v3.6
|
||||||
|
|
||||||
|
- **命令参数标准化**：后端统一使用 `app` 参数（取值：`claude` 或 `codex`）
|
||||||
|
- ✅ **影响**：代码更规范，错误提示更友好
|
||||||
|
- ✅ **兼容性**：前端已完全适配，用户无需关心此变更
|
||||||
|
|
||||||
|
#### 启动失败与恢复
|
||||||
|
|
||||||
|
- 触发条件：`~/.cc-switch/config.json` 不存在、损坏或解析失败时触发。
|
||||||
|
- 用户动作：根据弹窗提示检查 JSON 语法，或从备份文件恢复。
|
||||||
|
- 备份位置与轮换：`~/.cc-switch/backups/backup_YYYYMMDD_HHMMSS.json`（最多保留 10 个，参见 `src-tauri/src/services/config.rs`）。
|
||||||
|
- 退出策略：为保护数据安全，出现上述错误时应用会弹窗提示并强制退出；修复后重新启动即可。
|
||||||
|
|
||||||
|
#### v3.2.0 起的迁移机制
|
||||||
|
|
||||||
|
- 一次性迁移：首次启动 3.2.0 及以上版本会扫描旧的"副本文件"并合并到 `~/.cc-switch/config.json`
|
||||||
|
- Claude：`~/.claude/settings-*.json`（排除 `settings.json` / 历史 `claude.json`）
|
||||||
|
- Codex：`~/.codex/auth-*.json` 与 `config-*.toml`（按名称成对合并）
|
||||||
|
- 去重与当前项：按"名称（忽略大小写）+ API Key"去重；若当前为空，将 live 合并项设为当前
|
||||||
|
- 归档与清理：
|
||||||
|
- 归档目录：`~/.cc-switch/archive/<timestamp>/<category>/...`
|
||||||
|
- 归档成功后删除原副本；失败则保留原文件（保守策略）
|
||||||
|
- v1 → v2 结构升级：会额外生成 `~/.cc-switch/config.v1.backup.<timestamp>.json` 以便回滚
|
||||||
|
- 注意：迁移后不再持续归档日常切换/编辑操作，如需长期审计请自备备份方案
|
||||||
|
|
||||||
|
## 架构总览（v3.6）
|
||||||
|
|
||||||
|
### 架构重构亮点（v3.6）
|
||||||
|
|
||||||
|
**后端重构（Rust）**：完成 5 阶段重构
|
||||||
|
|
||||||
|
- **Phase 1**：统一错误处理（`AppError` + 国际化错误消息）
|
||||||
|
- **Phase 2**：命令层按领域拆分（`commands/{provider,mcp,config,settings,plugin,misc}.rs`）
|
||||||
|
- **Phase 3**：引入集成测试和事务机制（配置快照 + 失败回滚）
|
||||||
|
- **Phase 4**：提取 Service 层（`services/{provider,mcp,config,speedtest}.rs`）
|
||||||
|
- **Phase 5**：并发优化（`RwLock` 替代 `Mutex`，作用域 guard 避免死锁）
|
||||||
|
|
||||||
|
**前端重构（React + TypeScript）**：完成 4 阶段重构
|
||||||
|
|
||||||
|
- **Stage 1**：建立测试基础设施（vitest + MSW + @testing-library/react）
|
||||||
|
- **Stage 2**：提取自定义 hooks（`useProviderActions`, `useMcpActions`, `useSettings`, `useImportExport` 等）
|
||||||
|
- **Stage 3**：组件拆分和业务逻辑提取
|
||||||
|
- **Stage 4**：代码清理和格式化统一
|
||||||
|
|
||||||
|
**测试覆盖**：
|
||||||
|
|
||||||
|
- Hooks 单元测试 100% 覆盖
|
||||||
|
- 集成测试覆盖关键流程（App、SettingsDialog、MCP 面板）
|
||||||
|
- MSW 模拟后端 API，确保测试独立性
|
||||||
|
|
||||||
|
### 分层架构
|
||||||
|
|
||||||
|
- **前端（Renderer）**
|
||||||
|
- 技术栈：TypeScript + React 18 + Vite + TailwindCSS 4
|
||||||
|
- 数据层：TanStack React Query 统一查询与变更（`@/lib/query`），Tauri API 统一封装（`@/lib/api`）
|
||||||
|
- 业务逻辑层：自定义 Hooks（`@/hooks`）承载领域逻辑，组件保持简洁
|
||||||
|
- 事件流：监听后端 `provider-switched` 事件，驱动 UI 刷新与托盘状态一致
|
||||||
|
- 组织结构：按领域拆分组件（`providers/settings/mcp/ui`）
|
||||||
|
|
||||||
|
- **后端（Tauri + Rust）**
|
||||||
|
- **Commands 层**（接口层）：`src-tauri/src/commands/*` 按领域拆分，仅负责参数解析和权限校验
|
||||||
|
- **Services 层**（业务层）：`src-tauri/src/services/*` 承载核心逻辑，可复用和测试
|
||||||
|
- `ProviderService`：供应商增删改查、切换、回填、排序
|
||||||
|
- `McpService`：MCP 服务器管理、导入导出、同步
|
||||||
|
- `ConfigService`：配置文件导入导出、备份恢复
|
||||||
|
- `SpeedtestService`：API 端点延迟测试
|
||||||
|
- **模型与状态**：
|
||||||
|
- `provider.rs`：领域模型（`Provider`, `ProviderManager`, `ProviderMeta`）
|
||||||
|
- `app_config.rs`：多应用配置（`MultiAppConfig`, `AppId`, `McpRoot`）
|
||||||
|
- `store.rs`：全局状态（`AppState` + `RwLock<MultiAppConfig>`）
|
||||||
|
- **可靠性**：
|
||||||
|
- 统一错误类型 `AppError`（包含本地化消息）
|
||||||
|
- 事务式变更（配置快照 + 失败回滚）
|
||||||
|
- 原子写入（临时文件 + 重命名，避免半写入）
|
||||||
|
- 托盘菜单与事件：切换后重建菜单并向前端发射 `provider-switched` 事件
|
||||||
|
|
||||||
|
- **设计要点（SSOT + 双向同步）**
|
||||||
|
- **单一事实源**：供应商配置集中存放于 `~/.cc-switch/config.json`
|
||||||
|
- **切换时写入**：将目标供应商配置写入 live 文件（Claude: `settings.json`；Codex: `auth.json` + `config.toml`）
|
||||||
|
- **回填机制**：切换后立即读回 live 文件，更新 SSOT，保护用户手动修改
|
||||||
|
- **目录切换同步**：修改配置目录时自动同步当前供应商到新目录（WSL 环境完美支持）
|
||||||
|
- **编辑时优先 live**：编辑当前供应商时，优先加载 live 配置，确保显示实际生效的配置
|
||||||
|
|
||||||
|
- **兼容性与变更**
|
||||||
|
- 命令参数统一：Tauri 命令仅接受 `app`（值为 `claude` / `codex`）
|
||||||
|
- 前端类型统一：使用 `AppId` 表达应用标识（替代历史 `AppType` 导出）
|
||||||
|
|
||||||
|
## 开发
|
||||||
|
|
||||||
|
### 环境要求
|
||||||
|
|
||||||
|
- 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](https://react.dev/)** - 用户界面库
|
||||||
|
- **[TypeScript](https://www.typescriptlang.org/)** - 类型安全的 JavaScript
|
||||||
|
- **[Vite](https://vitejs.dev/)** - 极速的前端构建工具
|
||||||
|
- **[TailwindCSS 4](https://tailwindcss.com/)** - 实用优先的 CSS 框架
|
||||||
|
- **[TanStack Query v5](https://tanstack.com/query/latest)** - 强大的数据获取与缓存
|
||||||
|
- **[react-i18next](https://react.i18next.com/)** - React 国际化框架
|
||||||
|
- **[react-hook-form](https://react-hook-form.com/)** - 高性能表单库
|
||||||
|
- **[zod](https://zod.dev/)** - TypeScript 优先的模式验证
|
||||||
|
- **[shadcn/ui](https://ui.shadcn.com/)** - 可复用的 React 组件
|
||||||
|
- **[@dnd-kit](https://dndkit.com/)** - 现代拖拽工具包
|
||||||
|
|
||||||
|
### 后端
|
||||||
|
|
||||||
|
- **[Tauri 2.8](https://tauri.app/)** - 跨平台桌面应用框架
|
||||||
|
- tauri-plugin-updater - 自动更新
|
||||||
|
- tauri-plugin-process - 进程管理
|
||||||
|
- tauri-plugin-dialog - 文件对话框
|
||||||
|
- tauri-plugin-store - 持久化存储
|
||||||
|
- tauri-plugin-log - 日志记录
|
||||||
|
- **[Rust](https://www.rust-lang.org/)** - 系统级编程语言
|
||||||
|
- **[serde](https://serde.rs/)** - 序列化/反序列化框架
|
||||||
|
- **[tokio](https://tokio.rs/)** - 异步运行时
|
||||||
|
- **[thiserror](https://github.com/dtolnay/thiserror)** - 错误处理派生宏
|
||||||
|
|
||||||
|
### 测试工具
|
||||||
|
|
||||||
|
- **[vitest](https://vitest.dev/)** - 快速的单元测试框架
|
||||||
|
- **[MSW](https://mswjs.io/)** - API mock 工具
|
||||||
|
- **[@testing-library/react](https://testing-library.com/react)** - React 测试工具
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
├── src/ # 前端代码 (React + TypeScript)
|
||||||
|
│ ├── components/ # React 组件
|
||||||
|
│ │ ├── providers/ # 供应商管理组件
|
||||||
|
│ │ │ ├── forms/ # 表单子组件（Claude/Codex 字段）
|
||||||
|
│ │ │ ├── ProviderList.tsx
|
||||||
|
│ │ │ ├── ProviderForm.tsx
|
||||||
|
│ │ │ ├── AddProviderDialog.tsx
|
||||||
|
│ │ │ └── EditProviderDialog.tsx
|
||||||
|
│ │ ├── settings/ # 设置相关组件
|
||||||
|
│ │ │ ├── SettingsDialog.tsx
|
||||||
|
│ │ │ ├── DirectorySettings.tsx
|
||||||
|
│ │ │ └── ImportExportSection.tsx
|
||||||
|
│ │ ├── mcp/ # MCP 管理组件
|
||||||
|
│ │ │ ├── McpPanel.tsx
|
||||||
|
│ │ │ ├── McpFormModal.tsx
|
||||||
|
│ │ │ └── McpWizard.tsx
|
||||||
|
│ │ └── ui/ # shadcn/ui 基础组件
|
||||||
|
│ ├── hooks/ # 自定义 Hooks（业务逻辑层）
|
||||||
|
│ │ ├── useProviderActions.ts # 供应商操作
|
||||||
|
│ │ ├── useMcpActions.ts # MCP 操作
|
||||||
|
│ │ ├── useSettings.ts # 设置管理
|
||||||
|
│ │ ├── useImportExport.ts # 导入导出
|
||||||
|
│ │ └── useDirectorySettings.ts # 目录配置
|
||||||
|
│ ├── lib/
|
||||||
|
│ │ ├── api/ # Tauri API 封装（类型安全）
|
||||||
|
│ │ │ ├── providers.ts # 供应商 API
|
||||||
|
│ │ │ ├── settings.ts # 设置 API
|
||||||
|
│ │ │ ├── mcp.ts # MCP API
|
||||||
|
│ │ │ └── usage.ts # 用量查询 API
|
||||||
|
│ │ └── query/ # TanStack Query 配置
|
||||||
|
│ │ ├── queries.ts # 查询定义
|
||||||
|
│ │ ├── mutations.ts # 变更定义
|
||||||
|
│ │ └── queryClient.ts
|
||||||
|
│ ├── i18n/ # 国际化资源
|
||||||
|
│ │ └── locales/
|
||||||
|
│ │ ├── zh/ # 中文翻译
|
||||||
|
│ │ └── en/ # 英文翻译
|
||||||
|
│ ├── config/ # 配置与预设
|
||||||
|
│ │ ├── claudeProviderPresets.ts # Claude 供应商预设
|
||||||
|
│ │ ├── codexProviderPresets.ts # Codex 供应商预设
|
||||||
|
│ │ └── mcpPresets.ts # MCP 服务器模板
|
||||||
|
│ ├── utils/ # 工具函数
|
||||||
|
│ │ ├── postChangeSync.ts # 配置同步工具
|
||||||
|
│ │ └── ...
|
||||||
|
│ └── types/ # TypeScript 类型定义
|
||||||
|
├── src-tauri/ # 后端代码 (Rust)
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── commands/ # Tauri 命令层（按领域拆分）
|
||||||
|
│ │ │ ├── provider.rs # 供应商命令
|
||||||
|
│ │ │ ├── mcp.rs # MCP 命令
|
||||||
|
│ │ │ ├── config.rs # 配置查询命令
|
||||||
|
│ │ │ ├── settings.rs # 设置命令
|
||||||
|
│ │ │ ├── plugin.rs # 插件命令
|
||||||
|
│ │ │ ├── import_export.rs # 导入导出命令
|
||||||
|
│ │ │ └── misc.rs # 杂项命令
|
||||||
|
│ │ ├── services/ # Service 层（业务逻辑）
|
||||||
|
│ │ │ ├── provider.rs # ProviderService
|
||||||
|
│ │ │ ├── mcp.rs # McpService
|
||||||
|
│ │ │ ├── config.rs # ConfigService
|
||||||
|
│ │ │ └── speedtest.rs # SpeedtestService
|
||||||
|
│ │ ├── app_config.rs # 配置数据模型
|
||||||
|
│ │ ├── provider.rs # 供应商领域模型
|
||||||
|
│ │ ├── store.rs # 全局状态管理
|
||||||
|
│ │ ├── mcp.rs # MCP 同步与校验
|
||||||
|
│ │ ├── error.rs # 统一错误类型
|
||||||
|
│ │ ├── usage_script.rs # 用量脚本执行
|
||||||
|
│ │ ├── claude_plugin.rs # Claude 插件管理
|
||||||
|
│ │ └── lib.rs # 应用入口
|
||||||
|
│ ├── capabilities/ # Tauri 权限配置
|
||||||
|
│ └── icons/ # 应用图标
|
||||||
|
├── tests/ # 前端测试（v3.6 新增）
|
||||||
|
│ ├── hooks/ # Hooks 单元测试
|
||||||
|
│ ├── components/ # 组件集成测试
|
||||||
|
│ └── setup.ts # 测试配置
|
||||||
|
└── assets/ # 静态资源
|
||||||
|
├── screenshots/ # 界面截图
|
||||||
|
└── partners/ # 合作商资源
|
||||||
|
├── logos/ # 合作商 Logo
|
||||||
|
└── banners/ # 合作商横幅/宣传图
|
||||||
|
```
|
||||||
|
|
||||||
|
## 更新日志
|
||||||
|
|
||||||
|
查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新详情。
|
||||||
|
|
||||||
|
## Electron 旧版
|
||||||
|
|
||||||
|
[Releases](../../releases) 里保留 v2.0.3 Electron 旧版
|
||||||
|
|
||||||
|
如果需要旧版 Electron 代码，可以拉取 electron-legacy 分支
|
||||||
|
|
||||||
|
## 贡献
|
||||||
|
|
||||||
|
欢迎提交 Issue 反馈问题和建议！
|
||||||
|
|
||||||
|
提交 PR 前请确保：
|
||||||
|
|
||||||
|
- 通过类型检查：`pnpm typecheck`
|
||||||
|
- 通过格式检查：`pnpm format:check`
|
||||||
|
- 通过单元测试：`pnpm test:unit`
|
||||||
|
- 功能性 PR 请先经过 issue 区讨论
|
||||||
|
|
||||||
|
## Star History
|
||||||
|
|
||||||
|
[](https://www.star-history.com/#farion1231/cc-switch&Date)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT © Jason Young
|
||||||
BIN
assets/partners/banners/glm-en.jpg
Normal file
BIN
assets/partners/banners/glm-en.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 102 KiB |
BIN
assets/partners/banners/glm-zh.jpg
Normal file
BIN
assets/partners/banners/glm-zh.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 110 KiB |
BIN
assets/screenshots/add-en.png
Normal file
BIN
assets/screenshots/add-en.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 185 KiB |
BIN
assets/screenshots/add-zh.png
Normal file
BIN
assets/screenshots/add-zh.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 203 KiB |
BIN
assets/screenshots/main-en.png
Normal file
BIN
assets/screenshots/main-en.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 204 KiB |
BIN
assets/screenshots/main-zh.png
Normal file
BIN
assets/screenshots/main-zh.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 205 KiB |
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "cc-switch",
|
"name": "cc-switch",
|
||||||
"version": "3.5.1",
|
"version": "3.6.0",
|
||||||
"description": "Claude Code & Codex 供应商切换工具",
|
"description": "Claude Code & Codex 供应商切换工具",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"dev": "pnpm tauri dev",
|
"dev": "pnpm tauri dev",
|
||||||
|
|||||||
Binary file not shown.
|
Before Width: | Height: | Size: 203 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 200 KiB |
2
src-tauri/Cargo.lock
generated
2
src-tauri/Cargo.lock
generated
@@ -563,7 +563,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "cc-switch"
|
name = "cc-switch"
|
||||||
version = "3.5.1"
|
version = "3.6.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"chrono",
|
"chrono",
|
||||||
"dirs 5.0.1",
|
"dirs 5.0.1",
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "cc-switch"
|
name = "cc-switch"
|
||||||
version = "3.5.1"
|
version = "3.6.0"
|
||||||
description = "Claude Code & Codex 供应商配置管理工具"
|
description = "Claude Code & Codex 供应商配置管理工具"
|
||||||
authors = ["Jason Young"]
|
authors = ["Jason Young"]
|
||||||
license = "MIT"
|
license = "MIT"
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"$schema": "https://schema.tauri.app/config/2",
|
"$schema": "https://schema.tauri.app/config/2",
|
||||||
"productName": "CC Switch",
|
"productName": "CC Switch",
|
||||||
"version": "3.5.1",
|
"version": "3.6.0",
|
||||||
"identifier": "com.ccswitch.desktop",
|
"identifier": "com.ccswitch.desktop",
|
||||||
"build": {
|
"build": {
|
||||||
"frontendDist": "../dist",
|
"frontendDist": "../dist",
|
||||||
|
|||||||
@@ -131,10 +131,10 @@ export const providerPresets: ProviderPreset[] = [
|
|||||||
env: {
|
env: {
|
||||||
ANTHROPIC_BASE_URL: "https://api.moonshot.cn/anthropic",
|
ANTHROPIC_BASE_URL: "https://api.moonshot.cn/anthropic",
|
||||||
ANTHROPIC_AUTH_TOKEN: "",
|
ANTHROPIC_AUTH_TOKEN: "",
|
||||||
ANTHROPIC_MODEL: "kimi-k2-0905-preview",
|
ANTHROPIC_MODEL: "kimi-k2-thinking",
|
||||||
ANTHROPIC_DEFAULT_HAIKU_MODEL: "kimi-k2-0905-preview",
|
ANTHROPIC_DEFAULT_HAIKU_MODEL: "kimi-k2-thinking",
|
||||||
ANTHROPIC_DEFAULT_SONNET_MODEL: "kimi-k2-0905-preview",
|
ANTHROPIC_DEFAULT_SONNET_MODEL: "kimi-k2-thinking",
|
||||||
ANTHROPIC_DEFAULT_OPUS_MODEL: "kimi-k2-0905-preview",
|
ANTHROPIC_DEFAULT_OPUS_MODEL: "kimi-k2-thinking",
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
category: "cn_official",
|
category: "cn_official",
|
||||||
|
|||||||
Reference in New Issue
Block a user