mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-24 21:30:17 +08:00
Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jason
|
ea81c3d839 | ||
|
TinsFox
|
aa05a8475f |
@@ -20,8 +20,6 @@ jobs:
|
||||
include:
|
||||
- os: windows-2022
|
||||
- os: ubuntu-22.04
|
||||
- os: ubuntu-22.04-arm
|
||||
arch: arm64
|
||||
- os: macos-14
|
||||
|
||||
steps:
|
||||
@@ -55,12 +53,7 @@ jobs:
|
||||
wget \
|
||||
file \
|
||||
patchelf \
|
||||
libssl-dev \
|
||||
rpm \
|
||||
flatpak \
|
||||
flatpak-builder \
|
||||
elfutils \
|
||||
xdg-utils
|
||||
libssl-dev
|
||||
# GTK/GLib stack for gdk-3.0, glib-2.0, gio-2.0
|
||||
sudo apt-get install -y --no-install-recommends \
|
||||
libgtk-3-dev \
|
||||
@@ -88,8 +81,8 @@ jobs:
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: ${{ steps.pnpm-store.outputs.path }}
|
||||
key: ${{ runner.os }}-${{ runner.arch }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
|
||||
restore-keys: ${{ runner.os }}-${{ runner.arch }}-pnpm-store-
|
||||
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
|
||||
restore-keys: ${{ runner.os }}-pnpm-store-
|
||||
|
||||
- name: Install frontend deps
|
||||
run: pnpm install --frozen-lockfile
|
||||
@@ -160,7 +153,7 @@ jobs:
|
||||
|
||||
- name: Build Tauri App (Linux)
|
||||
if: runner.os == 'Linux'
|
||||
run: pnpm tauri build --bundles appimage,deb,rpm
|
||||
run: pnpm tauri build
|
||||
|
||||
- name: Prepare macOS Assets
|
||||
if: runner.os == 'macOS'
|
||||
@@ -168,7 +161,6 @@ jobs:
|
||||
run: |
|
||||
set -euxo pipefail
|
||||
mkdir -p release-assets
|
||||
VERSION="${GITHUB_REF_NAME}" # e.g., v3.5.0
|
||||
echo "Looking for updater artifact (.tar.gz) and .app for zip..."
|
||||
TAR_GZ=""; APP_PATH=""
|
||||
for path in \
|
||||
@@ -185,18 +177,15 @@ jobs:
|
||||
echo "No macOS .tar.gz updater artifact found" >&2
|
||||
exit 1
|
||||
fi
|
||||
# 重命名 tar.gz 为统一格式
|
||||
NEW_TAR_GZ="CC-Switch-${VERSION}-macOS.tar.gz"
|
||||
cp "$TAR_GZ" "release-assets/$NEW_TAR_GZ"
|
||||
[ -f "$TAR_GZ.sig" ] && cp "$TAR_GZ.sig" "release-assets/$NEW_TAR_GZ.sig" || echo ".sig for macOS not found yet"
|
||||
echo "macOS updater artifact copied: $NEW_TAR_GZ"
|
||||
cp "$TAR_GZ" release-assets/
|
||||
[ -f "$TAR_GZ.sig" ] && cp "$TAR_GZ.sig" release-assets/ || echo ".sig for macOS not found yet"
|
||||
echo "macOS updater artifact copied: $(basename "$TAR_GZ")"
|
||||
if [ -n "$APP_PATH" ]; then
|
||||
APP_DIR=$(dirname "$APP_PATH"); APP_NAME=$(basename "$APP_PATH")
|
||||
NEW_ZIP="CC-Switch-${VERSION}-macOS.zip"
|
||||
cd "$APP_DIR"
|
||||
ditto -c -k --sequesterRsrc --keepParent "$APP_NAME" "$NEW_ZIP"
|
||||
mv "$NEW_ZIP" "$GITHUB_WORKSPACE/release-assets/"
|
||||
echo "macOS zip ready: $NEW_ZIP"
|
||||
ditto -c -k --sequesterRsrc --keepParent "$APP_NAME" "CC-Switch-macOS.zip"
|
||||
mv "CC-Switch-macOS.zip" "$GITHUB_WORKSPACE/release-assets/"
|
||||
echo "macOS zip ready: CC-Switch-macOS.zip"
|
||||
else
|
||||
echo "No .app found to zip (optional)" >&2
|
||||
fi
|
||||
@@ -207,7 +196,6 @@ jobs:
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
New-Item -ItemType Directory -Force -Path release-assets | Out-Null
|
||||
$VERSION = $env:GITHUB_REF_NAME # e.g., v3.5.0
|
||||
# 仅打包 MSI 安装器 + .sig（用于 Updater）
|
||||
$msi = Get-ChildItem -Path 'src-tauri/target/release/bundle/msi' -Recurse -Include *.msi -ErrorAction SilentlyContinue | Select-Object -First 1
|
||||
if ($null -eq $msi) {
|
||||
@@ -215,7 +203,7 @@ jobs:
|
||||
$msi = Get-ChildItem -Path 'src-tauri/target/release/bundle' -Recurse -Include *.msi -ErrorAction SilentlyContinue | Select-Object -First 1
|
||||
}
|
||||
if ($null -ne $msi) {
|
||||
$dest = "CC-Switch-$VERSION-Windows.msi"
|
||||
$dest = 'CC-Switch-Setup.msi'
|
||||
Copy-Item $msi.FullName (Join-Path release-assets $dest)
|
||||
Write-Host "Installer copied: $dest"
|
||||
$sigPath = "$($msi.FullName).sig"
|
||||
@@ -244,10 +232,9 @@ jobs:
|
||||
'portable=true'
|
||||
)
|
||||
$portableContent | Set-Content -Path $portableIniPath -Encoding UTF8
|
||||
$portableZip = "release-assets/CC-Switch-$VERSION-Windows-Portable.zip"
|
||||
Compress-Archive -Path "$portableDir/*" -DestinationPath $portableZip -Force
|
||||
Compress-Archive -Path "$portableDir/*" -DestinationPath 'release-assets/CC-Switch-Windows-Portable.zip' -Force
|
||||
Remove-Item -Recurse -Force $portableDir
|
||||
Write-Host "Windows portable zip created: CC-Switch-$VERSION-Windows-Portable.zip"
|
||||
Write-Host 'Windows portable zip created'
|
||||
} else {
|
||||
Write-Warning 'Portable exe not found'
|
||||
}
|
||||
@@ -258,34 +245,23 @@ jobs:
|
||||
run: |
|
||||
set -euxo pipefail
|
||||
mkdir -p release-assets
|
||||
VERSION="${GITHUB_REF_NAME}" # e.g., v3.5.0
|
||||
ARCH="${{ matrix.arch || 'x86_64' }}"
|
||||
# Updater artifact: AppImage（含对应 .sig）
|
||||
APPIMAGE=$(find src-tauri/target/release/bundle -name "*.AppImage" | head -1 || true)
|
||||
if [ -n "$APPIMAGE" ]; then
|
||||
NEW_APPIMAGE="CC-Switch-${VERSION}-Linux-${ARCH}.AppImage"
|
||||
cp "$APPIMAGE" "release-assets/$NEW_APPIMAGE"
|
||||
[ -f "$APPIMAGE.sig" ] && cp "$APPIMAGE.sig" "release-assets/$NEW_APPIMAGE.sig" || echo ".sig for AppImage not found"
|
||||
echo "AppImage copied: $NEW_APPIMAGE"
|
||||
cp "$APPIMAGE" release-assets/
|
||||
[ -f "$APPIMAGE.sig" ] && cp "$APPIMAGE.sig" release-assets/ || echo ".sig for AppImage not found"
|
||||
echo "AppImage copied"
|
||||
else
|
||||
echo "No AppImage found under target/release/bundle" >&2
|
||||
fi
|
||||
# 额外上传 .deb（用于手动安装，不参与 Updater）
|
||||
DEB=$(find src-tauri/target/release/bundle -name "*.deb" | head -1 || true)
|
||||
if [ -n "$DEB" ]; then
|
||||
cp "$DEB" "release-assets/CC-Switch-${VERSION}-Linux-${ARCH}.deb"
|
||||
echo "Deb package copied: CC-Switch-${VERSION}-Linux-${ARCH}.deb"
|
||||
cp "$DEB" release-assets/
|
||||
echo "Deb package copied"
|
||||
else
|
||||
echo "No .deb found (optional)"
|
||||
fi
|
||||
# 额外上传 .rpm（用于 Fedora/RHEL/openSUSE 等，不参与 Updater）
|
||||
RPM=$(find src-tauri/target/release/bundle -name "*.rpm" | head -1 || true)
|
||||
if [ -n "$RPM" ]; then
|
||||
cp "$RPM" "release-assets/CC-Switch-${VERSION}-Linux-${ARCH}.rpm"
|
||||
echo "RPM package copied: CC-Switch-${VERSION}-Linux-${ARCH}.rpm"
|
||||
else
|
||||
echo "No .rpm found (optional)"
|
||||
fi
|
||||
|
||||
- name: List prepared assets
|
||||
shell: bash
|
||||
@@ -312,13 +288,12 @@ jobs:
|
||||
|
||||
### 下载
|
||||
|
||||
- **macOS**: `CC-Switch-${{ github.ref_name }}-macOS.zip`（解压即用）或 `CC-Switch-${{ github.ref_name }}-macOS.tar.gz`（Homebrew）
|
||||
- **Windows**: `CC-Switch-${{ github.ref_name }}-Windows.msi`（安装版）或 `CC-Switch-${{ github.ref_name }}-Windows-Portable.zip`（绿色版）
|
||||
- **Linux (x86_64)**: `CC-Switch-${{ github.ref_name }}-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- **Linux (ARM64)**: `CC-Switch-${{ github.ref_name }}-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
- macOS: `CC-Switch-macOS.zip`（解压即用）
|
||||
- Windows: `CC-Switch-Setup.msi`（安装版）；`CC-Switch-Windows-Portable.zip`（绿色版）
|
||||
- Linux: `*.deb`（Debian/Ubuntu 安装包）
|
||||
|
||||
---
|
||||
提示：macOS 如遇"已损坏"提示，可在终端执行：`xattr -cr "/Applications/CC Switch.app"`
|
||||
提示：macOS 如遇“已损坏”提示，可在终端执行：`xattr -cr "/Applications/CC Switch.app"`
|
||||
files: release-assets/*
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
@@ -363,8 +338,7 @@ jobs:
|
||||
# 初始化空平台映射
|
||||
mac_url=""; mac_sig=""
|
||||
win_url=""; win_sig=""
|
||||
linux_x64_url=""; linux_x64_sig=""
|
||||
linux_arm64_url=""; linux_arm64_sig=""
|
||||
linux_url=""; linux_sig=""
|
||||
shopt -s nullglob
|
||||
for sig in dl/*.sig; do
|
||||
base=${sig%.sig}
|
||||
@@ -375,10 +349,8 @@ jobs:
|
||||
*.tar.gz)
|
||||
# 视为 macOS updater artifact
|
||||
mac_url="$url"; mac_sig="$sig_content";;
|
||||
*-Linux-arm64.AppImage|*-Linux-arm64.appimage)
|
||||
linux_arm64_url="$url"; linux_arm64_sig="$sig_content";;
|
||||
*-Linux-x86_64.AppImage|*-Linux-x86_64.appimage)
|
||||
linux_x64_url="$url"; linux_x64_sig="$sig_content";;
|
||||
*.AppImage|*.appimage)
|
||||
linux_url="$url"; linux_sig="$sig_content";;
|
||||
*.msi|*.exe)
|
||||
win_url="$url"; win_sig="$sig_content";;
|
||||
esac
|
||||
@@ -405,14 +377,9 @@ jobs:
|
||||
echo " \"windows-x86_64\": {\"signature\": \"$win_sig\", \"url\": \"$win_url\"}"
|
||||
first=0
|
||||
fi
|
||||
if [ -n "$linux_x64_url" ] && [ -n "$linux_x64_sig" ]; then
|
||||
if [ -n "$linux_url" ] && [ -n "$linux_sig" ]; then
|
||||
[ $first -eq 0 ] && echo ','
|
||||
echo " \"linux-x86_64\": {\"signature\": \"$linux_x64_sig\", \"url\": \"$linux_x64_url\"}"
|
||||
first=0
|
||||
fi
|
||||
if [ -n "$linux_arm64_url" ] && [ -n "$linux_arm64_sig" ]; then
|
||||
[ $first -eq 0 ] && echo ','
|
||||
echo " \"linux-aarch64\": {\"signature\": \"$linux_arm64_sig\", \"url\": \"$linux_arm64_url\"}"
|
||||
echo " \"linux-x86_64\": {\"signature\": \"$linux_sig\", \"url\": \"$linux_url\"}"
|
||||
first=0
|
||||
fi
|
||||
echo ' }'
|
||||
|
||||
+1
-15
@@ -8,18 +8,4 @@ release/
|
||||
*.tsbuildinfo
|
||||
.npmrc
|
||||
CLAUDE.md
|
||||
# AGENTS.md
|
||||
GEMINI.md
|
||||
/.claude
|
||||
/.codex
|
||||
/.gemini
|
||||
/.cc-switch
|
||||
/.idea
|
||||
/.vscode
|
||||
vitest-report.json
|
||||
nul
|
||||
|
||||
# Flatpak build artifacts
|
||||
flatpak/cc-switch.deb
|
||||
flatpak-build/
|
||||
flatpak-repo/
|
||||
AGENTS.md
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
22.12.0
|
||||
+2
-904
File diff suppressed because it is too large
Load Diff
@@ -1,495 +1,199 @@
|
||||
<div align="center">
|
||||
# Claude Code & Codex 供应商切换器
|
||||
|
||||
# All-in-One Assistant for Claude Code, Codex & Gemini CLI
|
||||
|
||||
[](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://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>
|
||||
一个用于管理和切换 Claude Code 与 Codex 不同供应商配置的桌面应用。
|
||||
|
||||
English | [中文](README_ZH.md) | [日本語](README_JA.md) | [Changelog](CHANGELOG.md)
|
||||
> v3.3.0 ：VS Code Codex 插件一键配置/移除（默认自动同步）、Codex 通用配置片段与自定义向导增强、WSL 环境支持、跨平台托盘与 UI 优化。
|
||||
|
||||
</div>
|
||||
> v3.2.0 ：全新 UI、macOS系统托盘、内置更新器、原子写入与回滚、改进暗色样式、单一事实源（SSOT）与一次性迁移/归档。
|
||||
|
||||
## ❤️Sponsor
|
||||
> v3.1.0 ：新增 Codex 供应商管理与一键切换，支持导入当前 Codex 配置为默认供应商，并在内部配置从 v1 → v2 迁移前自动备份（详见下文“迁移与归档”）。
|
||||
|
||||
[](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
> v3.0.0 重大更新：从 Electron 完全迁移到 Tauri 2.0，应用体积显著降低、启动性能大幅提升。
|
||||
|
||||
This project is sponsored by Z.ai, supporting us with their GLM CODING PLAN.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.Get 10% OFF the GLM CODING PLAN with [this link](https://z.ai/subscribe?ic=8JVLJQFSKB)!
|
||||
## 功能特性（v3.3.0）
|
||||
|
||||
---
|
||||
- **VS Code Codex 插件一键配置**：供应商卡片支持「应用到 VS Code / 从 VS Code 移除」，默认开启自动同步，并可跨 Code / Insiders / VSCodium 写入 `settings.json`
|
||||
- **通用配置片段**：Claude 与 Codex 共用 JSON/TOML 片段，提供编辑器 lint、内容校验、统一错误提示与本地持久化
|
||||
- **Codex 配置向导**：新增显示名称、专用 API Key URL、HTML5 校验与预设模板，方便快速配置第三方服务
|
||||
- **系统托盘与快捷操作**：窗口隐藏时仍可通过托盘切换供应商，并在自动同步开启时触发 VS Code 写入
|
||||
- **平台适配**：新增 Windows WSL 环境支持、Linux 自动禁用模态背景模糊解决白屏问题、macOS Dock 点击即可恢复窗口
|
||||
- **UI优化**：多处 UI 和使用体验优化
|
||||
|
||||
<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>Thanks to PackyCode for sponsoring this project! PackyCode is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more. PackyCode provides special discounts for our software users: register using <a href="https://www.packyapi.com/register?aff=cc-switch">this link</a> and enter the "cc-switch" promo code during recharge to get 10% off.</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>Thanks to AIGoCode for sponsoring this project! AIGoCode is an all-in-one platform that integrates Claude Code, Codex, and the latest Gemini models, providing you with stable, efficient, and highly cost-effective AI coding services. The platform offers flexible subscription plans, zero risk of account suspension, direct access with no VPN required, and lightning-fast responses. AIGoCode has prepared a special benefit for CC Switch users: if you register via <a href="https://aigocode.com/invite/CC-SWITCH">this link</a>, you'll receive an extra 10% bonus credit on your first top-up!</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>Thanks to AICodeMirror for sponsoring this project! AICodeMirror provides official high-stability relay services for Claude Code / Codex / Gemini CLI, with enterprise-grade concurrency, fast invoicing, and 24/7 dedicated technical support.
|
||||
Claude Code / Codex / Gemini official channels at 38% / 2% / 9% of original price, with extra discounts on top-ups! AICodeMirror offers special benefits for CC Switch users: register via <a href="https://www.aicodemirror.com/register?invitecode=9915W3">this link</a> to enjoy 20% off your first top-up, and enterprise customers can get up to 25% off!</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>Thanks to Cubence for sponsoring this project! Cubence is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more with flexible billing options including pay-as-you-go and monthly plans. Cubence provides special discounts for CC Switch users: register using <a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">this link</a> and enter the "CCSWITCH" promo code during recharge to get 10% off every top-up!</td>
|
||||
</tr>
|
||||
### 添加供应商
|
||||
|
||||
<tr>
|
||||
<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-en.jpg" alt="DMXAPI" width="150"></a></td>
|
||||
<td>Thanks to DMXAPI for sponsoring this project! DMXAPI provides global large model API services to 200+ enterprise users. One API key for all global models. Features include: instant invoicing, unlimited concurrency, starting from $0.15, 24/7 technical support. GPT/Claude/Gemini all at 32% off, domestic models 20-50% off, Claude Code exclusive models at 66% off! <a href="https://www.dmxapi.cn/register?aff=bUHu">Register here</a></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>Thanks to AICoding.sh for sponsoring this project! AICoding.sh — Global AI Model API Relay Service at Unbeatable Prices! Claude Code at 19% of original price, GPT at just 1%! Trusted by hundreds of enterprises for cost-effective AI services. Supports Claude Code, GPT, Gemini and major domestic models, with enterprise-grade high concurrency, fast invoicing, and 24/7 dedicated technical support. CC Switch users who register via <a href="https://aicoding.sh/i/CCSWITCH">this link</a> get 10% off their first top-up!</td>
|
||||
</tr>
|
||||
## 下载安装
|
||||
|
||||
</table>
|
||||
### 系统要求
|
||||
|
||||
## Screenshots
|
||||
- **Windows**: Windows 10 及以上
|
||||
- **macOS**: macOS 10.15 (Catalina) 及以上
|
||||
- **Linux**: Ubuntu 20.04+ / Debian 11+ / Fedora 34+ 等主流发行版
|
||||
|
||||
| Main Interface | Add Provider |
|
||||
| :-----------------------------------------------: | :--------------------------------------------: |
|
||||
|  |  |
|
||||
### Windows 用户
|
||||
|
||||
## Features
|
||||
从 [Releases](../../releases) 页面下载最新版本的 `CC-Switch-Setup.msi` 安装包或者 `CC-Switch-Windows-Portable.zip` 绿色版。
|
||||
|
||||
### Current Version: v3.10.2 | [Full Changelog](CHANGELOG.md) | [Release Notes](docs/release-note-v3.9.0-en.md)
|
||||
### macOS 用户
|
||||
|
||||
**v3.8.0 Major Update (2025-11-28)**
|
||||
从 [Releases](../../releases) 页面下载 `CC-Switch-macOS.zip` 解压使用。
|
||||
|
||||
**Persistence Architecture Upgrade & Brand New UI**
|
||||
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开
|
||||
|
||||
- **SQLite + JSON Dual-layer Architecture**
|
||||
- Migrated from JSON file storage to SQLite + JSON dual-layer structure
|
||||
- Syncable data (providers, MCP, Prompts, Skills) stored in SQLite
|
||||
- Device-level data (window state, local paths) stored in JSON
|
||||
- Lays the foundation for future cloud sync functionality
|
||||
- Schema version management for database migrations
|
||||
### Linux 用户
|
||||
|
||||
- **Brand New User Interface**
|
||||
- Completely redesigned interface layout
|
||||
- Unified component styles and smoother animations
|
||||
- Optimized visual hierarchy
|
||||
- Tailwind CSS downgraded from v4 to v3.4 for better browser compatibility
|
||||
从 [Releases](../../releases) 页面下载最新版本的 `.deb` 包或者 `AppImage`安装包。
|
||||
|
||||
- **Japanese Language Support**
|
||||
- Added Japanese interface support (now supports Chinese/English/Japanese)
|
||||
## 使用说明
|
||||
|
||||
- **Auto Launch on Startup**
|
||||
- One-click enable/disable in settings
|
||||
- Platform-native APIs (Registry/LaunchAgent/XDG autostart)
|
||||
1. 点击"添加供应商"添加你的 API 配置
|
||||
2. 切换方式：
|
||||
- 在主界面选择供应商后点击切换
|
||||
- 或通过“系统托盘（菜单栏）”直接选择目标供应商，立即生效
|
||||
3. 切换会写入对应应用的“live 配置文件”（Claude：`settings.json`；Codex：`auth.json` + `config.toml`）
|
||||
4. 重启或新开终端以确保生效
|
||||
5. 若需切回官方登录，在预设中选择“官方登录”并切换即可；重启终端后按官方流程登录
|
||||
|
||||
- **Skills Recursive Scanning**
|
||||
- Support for multi-level directory structures
|
||||
- Allow same-named skills from different repositories
|
||||
### 检查更新
|
||||
|
||||
- **Critical Bug Fixes**
|
||||
- Fixed custom endpoints lost when updating providers
|
||||
- Fixed Gemini configuration write issues
|
||||
- Fixed Linux WebKitGTK rendering issues
|
||||
- 在“设置”中点击“检查更新”，若内置 Updater 配置可用将直接检测与下载；否则会回退打开 Releases 页面
|
||||
|
||||
**v3.7.0 Highlights**
|
||||
### Codex 说明（SSOT）
|
||||
|
||||
**Six Core Features, 18,000+ Lines of New Code**
|
||||
- 配置目录：`~/.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 官方登录”，重启终端后按官方流程登录
|
||||
|
||||
- **Gemini CLI Integration**
|
||||
- Third supported AI CLI (Claude Code / Codex / Gemini)
|
||||
- Dual-file configuration support (`.env` + `settings.json`)
|
||||
- Complete MCP server management
|
||||
- Presets: Google Official (OAuth) / PackyCode / Custom
|
||||
### Claude Code 说明（SSOT）
|
||||
|
||||
- **Claude Skills Management System**
|
||||
- Auto-scan skills from GitHub repositories (3 pre-configured curated repos)
|
||||
- One-click install/uninstall to `~/.claude/skills/`
|
||||
- Custom repository support + subdirectory scanning
|
||||
- Complete lifecycle management (discover/install/update)
|
||||
- 配置目录：`~/.claude/`
|
||||
- live 主配置：`settings.json`（优先）或历史兼容 `claude.json`
|
||||
- API Key 字段：`env.ANTHROPIC_AUTH_TOKEN`
|
||||
- 切换行为（不再写“副本文件”）：
|
||||
- 供应商配置统一保存在 `~/.cc-switch/config.json`
|
||||
- 切换时将目标供应商 JSON 直接写入 live 文件（优先 `settings.json`）
|
||||
- 编辑当前供应商时，先写 live 成功，再更新应用主配置，保证一致性
|
||||
- 导入默认：当该应用无任何供应商时，从现有 live 主配置创建一条默认项并设为当前
|
||||
- 官方登录：可切换到预设“Claude 官方登录”，重启终端后可使用 `/login` 完成登录
|
||||
|
||||
- **Prompts Management System**
|
||||
- Multi-preset system prompt management (unlimited presets, quick switching)
|
||||
- Cross-app support (Claude: `CLAUDE.md` / Codex: `AGENTS.md` / Gemini: `GEMINI.md`)
|
||||
- Markdown editor (CodeMirror 6 + real-time preview)
|
||||
- Smart backfill protection, preserves manual modifications
|
||||
### 迁移与归档（自 v3.2.0 起）
|
||||
|
||||
- **MCP v3.7.0 Unified Architecture**
|
||||
- Single panel manages MCP servers across three applications
|
||||
- New SSE (Server-Sent Events) transport type
|
||||
- Smart JSON parser + Codex TOML format auto-correction
|
||||
- Unified import/export + bidirectional sync
|
||||
- 一次性迁移：首次启动 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` 以便回滚
|
||||
- 注意：迁移后不再持续归档日常切换/编辑操作，如需长期审计请自备备份方案
|
||||
|
||||
- **Deep Link Protocol**
|
||||
- `ccswitch://` protocol registration (all platforms)
|
||||
- One-click import provider configs via shared links
|
||||
- Security validation + lifecycle integration
|
||||
## 开发
|
||||
|
||||
- **Environment Variable Conflict Detection**
|
||||
- Auto-detect cross-app configuration conflicts (Claude/Codex/Gemini/MCP)
|
||||
- Visual conflict indicators + resolution suggestions
|
||||
- Override warnings + backup before changes
|
||||
|
||||
**Core Capabilities**
|
||||
|
||||
- **Provider Management**: One-click switching between Claude Code, Codex, and Gemini API configurations
|
||||
- **Speed Testing**: Measure API endpoint latency with visual quality indicators
|
||||
- **Import/Export**: Backup and restore configs with auto-rotation (keep 10 most recent)
|
||||
- **i18n Support**: Complete Chinese/English localization (UI, errors, tray)
|
||||
- **Claude Plugin Sync**: One-click apply/restore Claude plugin configurations
|
||||
|
||||
**v3.6 Highlights**
|
||||
|
||||
- Provider duplication & drag-and-drop sorting
|
||||
- Multi-endpoint management & custom config directory (cloud sync ready)
|
||||
- Granular model configuration (4-tier: Haiku/Sonnet/Opus/Custom)
|
||||
- WSL environment support with auto-sync on directory change
|
||||
- 100% hooks test coverage & complete architecture refactoring
|
||||
|
||||
**System Features**
|
||||
|
||||
- System tray with quick switching
|
||||
- Single instance daemon
|
||||
- Built-in auto-updater
|
||||
- Atomic writes with rollback protection
|
||||
|
||||
## 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
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
**Method 2: Manual Download**
|
||||
|
||||
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.
|
||||
|
||||
### Arch Linux Users
|
||||
|
||||
**Install via paru (Recommended)**
|
||||
|
||||
```bash
|
||||
paru -S cc-switch-bin
|
||||
```
|
||||
|
||||
### Linux Users
|
||||
|
||||
Download the latest Linux build from the [Releases](../../releases) page:
|
||||
|
||||
- `CC-Switch-v{version}-Linux.deb` (Debian/Ubuntu)
|
||||
- `CC-Switch-v{version}-Linux.rpm` (Fedora/RHEL/openSUSE)
|
||||
- `CC-Switch-v{version}-Linux.AppImage` (Universal)
|
||||
- `CC-Switch-v{version}-Linux.flatpak` (Flatpak)
|
||||
|
||||
Flatpak install & run:
|
||||
|
||||
```bash
|
||||
flatpak install --user ./CC-Switch-v{version}-Linux.flatpak
|
||||
flatpak run com.ccswitch.desktop
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Usage
|
||||
|
||||
1. **Add Provider**: Click "Add Provider" → Choose preset or create custom configuration
|
||||
2. **Switch Provider**:
|
||||
- Main UI: Select provider → Click "Enable"
|
||||
- System Tray: Click provider name directly (instant effect)
|
||||
3. **Takes Effect**: Restart your terminal or Claude Code / Codex / Gemini clients to apply changes
|
||||
4. **Back to Official**: Select the "Official Login" preset (Claude/Codex) or "Google Official" preset (Gemini), restart the corresponding client, then follow its login/OAuth flow
|
||||
|
||||
### MCP Management
|
||||
|
||||
- **Location**: Click "MCP" button in top-right corner
|
||||
- **Add Server**:
|
||||
- Use built-in templates (mcp-fetch, mcp-filesystem, etc.)
|
||||
- Support stdio / http / sse transport types
|
||||
- Configure independent MCP servers for different apps
|
||||
- **Enable/Disable**: Toggle switches to control which servers sync to live config
|
||||
- **Sync**: Enabled servers auto-sync to each app's live files
|
||||
- **Import/Export**: Import existing MCP servers from Claude/Codex/Gemini config files
|
||||
|
||||
### Skills Management (v3.7.0 New)
|
||||
|
||||
- **Location**: Click "Skills" button in top-right corner
|
||||
- **Discover Skills**:
|
||||
- Auto-scan pre-configured GitHub repositories (Anthropic official, ComposioHQ, community, etc.)
|
||||
- Add custom repositories (supports subdirectory scanning)
|
||||
- **Install Skills**: Click "Install" to one-click install to `~/.claude/skills/`
|
||||
- **Uninstall Skills**: Click "Uninstall" to safely remove and clean up state
|
||||
- **Manage Repositories**: Add/remove custom GitHub repositories
|
||||
|
||||
### Prompts Management (v3.7.0 New)
|
||||
|
||||
- **Location**: Click "Prompts" button in top-right corner
|
||||
- **Create Presets**:
|
||||
- Create unlimited system prompt presets
|
||||
- Use Markdown editor to write prompts (syntax highlighting + real-time preview)
|
||||
- **Switch Presets**: Select preset → Click "Activate" to apply immediately
|
||||
- **Sync Mechanism**:
|
||||
- Claude: `~/.claude/CLAUDE.md`
|
||||
- Codex: `~/.codex/AGENTS.md`
|
||||
- Gemini: `~/.gemini/GEMINI.md`
|
||||
- **Protection Mechanism**: Auto-save current prompt content before switching, preserves manual modifications
|
||||
|
||||
### Configuration Files
|
||||
|
||||
**Claude Code**
|
||||
|
||||
- Live config: `~/.claude/settings.json` (or `claude.json`)
|
||||
- API key field: `env.ANTHROPIC_AUTH_TOKEN` or `env.ANTHROPIC_API_KEY`
|
||||
- MCP servers: `~/.claude.json` → `mcpServers`
|
||||
|
||||
**Codex**
|
||||
|
||||
- Live config: `~/.codex/auth.json` (required) + `config.toml` (optional)
|
||||
- API key field: `OPENAI_API_KEY` in `auth.json`
|
||||
- MCP servers: `~/.codex/config.toml` → `[mcp_servers]` tables
|
||||
|
||||
**Gemini**
|
||||
|
||||
- Live config: `~/.gemini/.env` (API key) + `~/.gemini/settings.json` (auth mode)
|
||||
- API key field: `GEMINI_API_KEY` or `GOOGLE_GEMINI_API_KEY` in `.env`
|
||||
- Environment variables: Support `GOOGLE_GEMINI_BASE_URL`, `GEMINI_MODEL`, etc.
|
||||
- MCP servers: `~/.gemini/settings.json` → `mcpServers`
|
||||
- Tray quick switch: Each provider switch rewrites `~/.gemini/.env`, no need to restart Gemini CLI
|
||||
|
||||
**CC Switch Storage (v3.8.0 New Architecture)**
|
||||
|
||||
- Database (SSOT): `~/.cc-switch/cc-switch.db` (SQLite, stores providers, MCP, Prompts, Skills)
|
||||
- Local settings: `~/.cc-switch/settings.json` (device-level settings)
|
||||
- Backups: `~/.cc-switch/backups/` (auto-rotate, keep 10)
|
||||
|
||||
### Cloud Sync Setup
|
||||
|
||||
1. Go to Settings → "Custom Configuration Directory"
|
||||
2. Choose your cloud sync folder (Dropbox, OneDrive, iCloud, etc.)
|
||||
3. Restart app to apply
|
||||
4. Repeat on other devices to enable cross-device sync
|
||||
|
||||
> **Note**: First launch auto-imports existing Claude/Codex configs as default provider.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Design Principles
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Frontend (React + TS) │
|
||||
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │ Components │ │ Hooks │ │ TanStack Query │ │
|
||||
│ │ (UI) │──│ (Bus. Logic) │──│ (Cache/Sync) │ │
|
||||
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│ Tauri IPC
|
||||
┌────────────────────────▼────────────────────────────────────┐
|
||||
│ Backend (Tauri + Rust) │
|
||||
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │ Commands │ │ Services │ │ Models/Config │ │
|
||||
│ │ (API Layer) │──│ (Bus. Layer) │──│ (Data) │ │
|
||||
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Core Design Patterns**
|
||||
|
||||
- **SSOT** (Single Source of Truth): All data stored in `~/.cc-switch/cc-switch.db` (SQLite)
|
||||
- **Dual-layer Storage**: SQLite for syncable data, JSON for device-level settings
|
||||
- **Dual-way Sync**: Write to live files on switch, backfill from live when editing active provider
|
||||
- **Atomic Writes**: Temp file + rename pattern prevents config corruption
|
||||
- **Concurrency Safe**: Mutex-protected database connection avoids race conditions
|
||||
- **Layered Architecture**: Clear separation (Commands → Services → DAO → Database)
|
||||
|
||||
**Key Components**
|
||||
|
||||
- **ProviderService**: Provider CRUD, switching, backfill, sorting
|
||||
- **McpService**: MCP server management, import/export, live file sync
|
||||
- **ConfigService**: Config import/export, backup rotation
|
||||
- **SpeedtestService**: API endpoint latency measurement
|
||||
|
||||
**v3.6 Refactoring**
|
||||
|
||||
- Backend: 5-phase refactoring (error handling → command split → tests → services → concurrency)
|
||||
- Frontend: 4-stage refactoring (test infra → hooks → components → cleanup)
|
||||
- Testing: 100% hooks coverage + integration tests (vitest + MSW)
|
||||
|
||||
## Development
|
||||
|
||||
### Environment Requirements
|
||||
### 环境要求
|
||||
|
||||
- Node.js 18+
|
||||
- pnpm 8+
|
||||
- Rust 1.85+
|
||||
- Tauri CLI 2.8+
|
||||
- Rust 1.75+
|
||||
- Tauri CLI 2.0+
|
||||
|
||||
### Development Commands
|
||||
### 开发命令
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# Dev mode (hot reload)
|
||||
# 开发模式（热重载）
|
||||
pnpm dev
|
||||
|
||||
# Type check
|
||||
# 类型检查
|
||||
pnpm typecheck
|
||||
|
||||
# Format code
|
||||
# 代码格式化
|
||||
pnpm format
|
||||
|
||||
# Check code format
|
||||
# 检查代码格式
|
||||
pnpm format:check
|
||||
|
||||
# Run frontend unit tests
|
||||
pnpm test:unit
|
||||
|
||||
# Run tests in watch mode (recommended for development)
|
||||
pnpm test:unit:watch
|
||||
|
||||
# Build application
|
||||
# 构建应用
|
||||
pnpm build
|
||||
|
||||
# Build debug version
|
||||
# 构建调试版本
|
||||
pnpm tauri build --debug
|
||||
```
|
||||
|
||||
### Rust Backend Development
|
||||
### Rust 后端开发
|
||||
|
||||
```bash
|
||||
cd src-tauri
|
||||
|
||||
# Format Rust code
|
||||
# 格式化 Rust 代码
|
||||
cargo fmt
|
||||
|
||||
# Run clippy checks
|
||||
# 运行 clippy 检查
|
||||
cargo clippy
|
||||
|
||||
# Run backend tests
|
||||
# 运行测试
|
||||
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)
|
||||
## 技术栈
|
||||
|
||||
**Frontend Testing**:
|
||||
- **[Tauri 2](https://tauri.app/)** - 跨平台桌面应用框架（集成 updater/process/opener/log/tray-icon）
|
||||
- **[React 18](https://react.dev/)** - 用户界面库
|
||||
- **[TypeScript](https://www.typescriptlang.org/)** - 类型安全的 JavaScript
|
||||
- **[Vite](https://vitejs.dev/)** - 极速的前端构建工具
|
||||
- **[Rust](https://www.rust-lang.org/)** - 系统级编程语言（后端）
|
||||
|
||||
- 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 · TypeScript · Vite · TailwindCSS 4 · TanStack Query v5 · react-i18next · react-hook-form · zod · shadcn/ui · @dnd-kit
|
||||
|
||||
**Backend**: Tauri 2.8 · Rust · serde · tokio · thiserror · tauri-plugin-updater/process/dialog/store/log
|
||||
|
||||
**Testing**: vitest · MSW · @testing-library/react
|
||||
|
||||
## Project Structure
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
├── src/ # Frontend (React + TypeScript)
|
||||
│ ├── components/ # UI components (providers/settings/mcp/ui)
|
||||
│ ├── hooks/ # Custom hooks (business logic)
|
||||
│ ├── lib/
|
||||
│ │ ├── api/ # Tauri API wrapper (type-safe)
|
||||
│ │ └── query/ # TanStack Query config
|
||||
│ ├── i18n/locales/ # Translations (zh/en)
|
||||
│ ├── config/ # Presets (providers/mcp)
|
||||
│ └── types/ # TypeScript definitions
|
||||
├── src-tauri/ # Backend (Rust)
|
||||
│ └── src/
|
||||
│ ├── commands/ # Tauri command layer (by domain)
|
||||
│ ├── services/ # Business logic layer
|
||||
│ ├── app_config.rs # Config data models
|
||||
│ ├── provider.rs # Provider domain models
|
||||
│ ├── mcp.rs # MCP sync & validation
|
||||
│ └── lib.rs # App entry & tray menu
|
||||
├── tests/ # Frontend tests
|
||||
│ ├── hooks/ # Unit tests
|
||||
│ └── components/ # Integration tests
|
||||
└── assets/ # Screenshots & partner resources
|
||||
├── src/ # 前端代码 (React + TypeScript)
|
||||
│ ├── components/ # React 组件
|
||||
│ ├── config/ # 预设供应商配置
|
||||
│ ├── lib/ # Tauri API 封装
|
||||
│ └── utils/ # 工具函数
|
||||
├── src-tauri/ # 后端代码 (Rust)
|
||||
│ ├── src/ # Rust 源代码
|
||||
│ │ ├── commands.rs # Tauri 命令定义
|
||||
│ │ ├── config.rs # 配置文件管理
|
||||
│ │ ├── provider.rs # 供应商管理逻辑
|
||||
│ │ └── store.rs # 状态管理
|
||||
│ ├── capabilities/ # 权限配置
|
||||
│ └── icons/ # 应用图标资源
|
||||
└── screenshots/ # 界面截图
|
||||
```
|
||||
|
||||
## Changelog
|
||||
## 更新日志
|
||||
|
||||
See [CHANGELOG.md](CHANGELOG.md) for version update details.
|
||||
查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新详情。
|
||||
|
||||
## Legacy Electron Version
|
||||
## Electron 旧版
|
||||
|
||||
[Releases](../../releases) retains v2.0.3 legacy Electron version
|
||||
[Releases](../../releases) 里保留 v2.0.3 Electron 旧版
|
||||
|
||||
If you need legacy Electron code, you can pull the electron-legacy branch
|
||||
如果需要旧版 Electron 代码，可以拉取 electron-legacy 分支
|
||||
|
||||
## Contributing
|
||||
## 贡献
|
||||
|
||||
Issues and suggestions are welcome!
|
||||
|
||||
Before submitting PRs, please ensure:
|
||||
|
||||
- Pass type check: `pnpm typecheck`
|
||||
- Pass format check: `pnpm format:check`
|
||||
- Pass unit tests: `pnpm test:unit`
|
||||
- 💡 For new features, please open an issue for discussion before submitting a PR
|
||||
欢迎提交 Issue 和 Pull Request！
|
||||
|
||||
## Star History
|
||||
|
||||
|
||||
-500
@@ -1,500 +0,0 @@
|
||||
<div align="center">
|
||||
|
||||
# Claude Code / Codex / Gemini CLI オールインワン・アシスタント
|
||||
|
||||
[](https://github.com/farion1231/cc-switch/releases)
|
||||
[](https://github.com/farion1231/cc-switch/releases)
|
||||
[](https://tauri.app/)
|
||||
[](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_ZH.md) | 日本語 | [Changelog](CHANGELOG.md) | [v3.9.0 リリースノート](docs/release-note-v3.9.0-ja.md)
|
||||
|
||||
</div>
|
||||
|
||||
## ❤️スポンサー
|
||||
|
||||
[](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
本プロジェクトは Z.ai の GLM CODING PLAN による支援を受けています。GLM CODING PLAN は AI コーディング向けのサブスクリプションで、月額わずか 3 ドルから。Claude Code、Cline、Roo Code など 10 以上の人気 AI コーディングツールでフラッグシップモデル GLM-4.6 を利用でき、速く安定した開発体験を提供します。[このリンク](https://z.ai/subscribe?ic=8JVLJQFSKB) から申し込むと 10% オフになります！
|
||||
|
||||
---
|
||||
|
||||
<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 は Claude Code、Codex、Gemini などのリレーサービスを提供する信頼性の高い API 中継プラットフォームです。本ソフト利用者向けに特別割引があります：<a href="https://www.packyapi.com/register?aff=cc-switch">このリンク</a>で登録し、チャージ時に「cc-switch」クーポンを入力すると 10% オフになります。</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コーディングプラットフォームで、安定性・高速性・コストパフォーマンスに優れた開発サービスを提供します。柔軟なサブスクリプションプランを備え、レスポンスも非常に高速です。さらに、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 の公式高安定リレーサービスを提供しており、エンタープライズ級の同時接続、迅速な請求書発行、24時間年中無休の専用テクニカルサポートを備えています。
|
||||
Claude Code / Codex / Gemini 公式チャンネルが最安で元価格の 38% / 2% / 9%、チャージ時にはさらに割引！AICodeMirror は CC Switch ユーザー向けに特別特典を用意：<a href="https://www.aicodemirror.com/register?invitecode=9915W3">このリンク</a>から登録すると初回チャージ 20% オフ、法人のお客様は最大 25% オフ！</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 は Claude Code、Codex、Gemini などのリレーサービスを提供する信頼性の高い API 中継プラットフォームで、従量課金や月額プランなど柔軟な料金体系を提供しています。CC Switch ユーザー向けの特別割引：<a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">このリンク</a>で登録し、チャージ時に「CCSWITCH」クーポンを入力すると、毎回 10% オフになります！</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-en.jpg" alt="DMXAPI" width="150"></a></td>
|
||||
<td>DMXAPI のご支援に感謝します！DMXAPI は 200 社以上の企業ユーザーにグローバル大規模モデル API サービスを提供しています。1 つの API キーで全世界のモデルにアクセス可能。即時請求書発行、同時接続数無制限、最低 $0.15 から、24 時間年中無休のテクニカルサポート。GPT/Claude/Gemini が全て 32% オフ、国内モデルは 20〜50% オフ、Claude Code 専用モデルは 66% オフ実施中！<a href="https://www.dmxapi.cn/register?aff=bUHu">登録はこちら</a></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 —— グローバル AI モデル API 超お得な中継サービス！Claude Code 81% オフ、GPT 99% オフ！数百社の企業に高コストパフォーマンスの AI サービスを提供。Claude Code、GPT、Gemini および国内主要モデルに対応、エンタープライズ級の高同時接続、迅速な請求書発行、24 時間年中無休の専属テクニカルサポート。<a href="https://aicoding.sh/i/CCSWITCH">こちらのリンク</a>から登録した CC Switch ユーザーは、初回チャージ 10% オフ！</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
## スクリーンショット
|
||||
|
||||
| メイン画面 | プロバイダ追加 |
|
||||
| :-------------------------------------------: | :----------------------------------------------: |
|
||||
|  |  |
|
||||
|
||||
## 特長
|
||||
|
||||
### 現在のバージョン：v3.10.2 | [完全な更新履歴](CHANGELOG.md) | [リリースノート](docs/release-note-v3.9.0-ja.md)
|
||||
|
||||
**v3.8.0 メジャーアップデート (2025-11-28)**
|
||||
|
||||
**永続化アーキテクチャ刷新 & 新 UI**
|
||||
|
||||
- **SQLite + JSON 二層構造**
|
||||
- JSON 単独保存から SQLite + JSON の二層構造へ移行
|
||||
- 同期対象データ（プロバイダ、MCP、Prompts、Skills）は SQLite に保存
|
||||
- デバイス固有データ（ウィンドウ状態、ローカルパス）は JSON に保存
|
||||
- 将来のクラウド同期の土台を用意
|
||||
- DB マイグレーション用にスキーマバージョンを管理
|
||||
|
||||
- **新しいユーザーインターフェース**
|
||||
- レイアウトを全面再設計
|
||||
- コンポーネントスタイルとアニメーションを統一
|
||||
- 視覚的な階層を最適化
|
||||
- ブラウザ互換性向上のため Tailwind CSS を v4 から v3.4 にダウングレード
|
||||
|
||||
- **日本語対応**
|
||||
- UI が中国語/英語/日本語の 3 言語対応に
|
||||
|
||||
- **自動起動**
|
||||
- 設定画面でワンクリック ON/OFF
|
||||
- プラットフォームネイティブ API（Registry/LaunchAgent/XDG autostart）を使用
|
||||
|
||||
- **Skills 再帰スキャン**
|
||||
- 多階層ディレクトリをサポート
|
||||
- リポジトリが異なる同名スキルを許可
|
||||
|
||||
- **重要なバグ修正**
|
||||
- プロバイダ更新時にカスタムエンドポイントが失われる問題を修正
|
||||
- Gemini 設定の書き込み問題を修正
|
||||
- Linux WebKitGTK の描画問題を修正
|
||||
|
||||
**v3.7.0 ハイライト**
|
||||
|
||||
**6 つのコア機能、18,000 行超の新コード**
|
||||
|
||||
- **Gemini CLI 統合**
|
||||
- Claude Code / Codex / Gemini の 3 番目のサポート AI CLI
|
||||
- 2 つの設定ファイル（`.env` + `settings.json`）に対応
|
||||
- MCP サーバー管理を完備
|
||||
- プリセット：Google 公式（OAuth）/ PackyCode / カスタム
|
||||
|
||||
- **Claude Skills 管理システム**
|
||||
- GitHub リポジトリを自動スキャン（3 つのキュレーション済みリポジトリを同梱）
|
||||
- `~/.claude/skills/` へワンクリックでインストール/アンインストール
|
||||
- カスタムリポジトリ + サブディレクトリスキャンをサポート
|
||||
- ライフサイクル管理（検出/インストール/更新）を完備
|
||||
|
||||
- **Prompts 管理システム**
|
||||
- 無制限のシステムプロンプトプリセットを作成
|
||||
- Markdown エディタ（CodeMirror 6 + リアルタイムプレビュー）付き
|
||||
- スマートなバックフィル保護で手動変更を保持
|
||||
- 複数アプリに同時対応（Claude: `CLAUDE.md` / Codex: `AGENTS.md` / Gemini: `GEMINI.md`）
|
||||
|
||||
- **MCP v3.7.0 統合アーキテクチャ**
|
||||
- 1 つのパネルで 3 アプリの MCP を管理
|
||||
- 新たに SSE（Server-Sent Events）トランスポートを追加
|
||||
- スマート JSON パーサー + Codex TOML 自動修正
|
||||
- 双方向のインポート/エクスポート + 双方向同期
|
||||
|
||||
- **ディープリンクプロトコル**
|
||||
- `ccswitch://` を全プラットフォームで登録
|
||||
- 共有リンクからプロバイダ設定をワンクリックでインポート
|
||||
- セキュリティ検証 + ライフサイクル統合
|
||||
|
||||
- **環境変数の競合検知**
|
||||
- Claude/Codex/Gemini/MCP 間の設定競合を自動検出
|
||||
- 競合表示 + 解決ガイド
|
||||
- 上書き前の警告 + バックアップ
|
||||
|
||||
**コア機能**
|
||||
|
||||
- **プロバイダ管理**：Claude Code、Codex、Gemini の API 設定をワンクリックで切り替え
|
||||
- **速度テスト**：エンドポイント遅延を計測し、品質を可視化
|
||||
- **インポート/エクスポート**：設定をバックアップ・復元（最新 10 件を自動ローテーション）
|
||||
- **多言語対応**：UI/エラー/トレイを含む中国語・英語・日本語ローカライズ
|
||||
- **Claude プラグイン同期**：Claude プラグイン設定をワンクリックで適用/復元
|
||||
|
||||
**v3.6 ハイライト**
|
||||
|
||||
- プロバイダの複製とドラッグ＆ドロップ並び替え
|
||||
- 複数エンドポイント管理とカスタム設定ディレクトリ（クラウド同期準備済み）
|
||||
- 4 階層のモデル設定（Haiku/Sonnet/Opus/Custom）
|
||||
- WSL 環境をサポートし、ディレクトリ変更時に自動同期
|
||||
- Hooks テスト 100% カバレッジ + アーキテクチャ全面リファクタ
|
||||
|
||||
**システム機能**
|
||||
|
||||
- クイックスイッチ付きシステムトレイ
|
||||
- シングルインスタンス常駐
|
||||
- ビルトイン自動アップデータ
|
||||
- ロールバック保護付きのアトミック書き込み
|
||||
|
||||
## ダウンロード & インストール
|
||||
|
||||
### システム要件
|
||||
|
||||
- **Windows**: Windows 10 以上
|
||||
- **macOS**: macOS 10.15 (Catalina) 以上
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ など主要ディストリビューション
|
||||
|
||||
### Windows ユーザー
|
||||
|
||||
[Releases](../../releases) ページから最新版の `CC-Switch-v{version}-Windows.msi` インストーラー、またはポータブル版 `CC-Switch-v{version}-Windows-Portable.zip` をダウンロード。
|
||||
|
||||
### macOS ユーザー
|
||||
|
||||
**方法 1: Homebrew でインストール（推奨）**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
アップデート:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
**方法 2: 手動ダウンロード**
|
||||
|
||||
[Releases](../../releases) から `CC-Switch-v{version}-macOS.zip` をダウンロードして展開。
|
||||
|
||||
> **注意**: 開発者アカウント未登録のため、初回起動時に「開発元を確認できません」と表示される場合があります。一度閉じてから「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックしてください。以降は通常通り起動できます。
|
||||
|
||||
### ArchLinux ユーザー
|
||||
|
||||
**paru でインストール（推奨）**
|
||||
|
||||
```bash
|
||||
paru -S cc-switch-bin
|
||||
```
|
||||
|
||||
### Linux ユーザー
|
||||
|
||||
[Releases](../../releases) から最新版の Linux ビルドをダウンロード：
|
||||
|
||||
- `CC-Switch-v{version}-Linux.deb`（Debian/Ubuntu）
|
||||
- `CC-Switch-v{version}-Linux.rpm`（Fedora/RHEL/openSUSE）
|
||||
- `CC-Switch-v{version}-Linux.AppImage`（汎用）
|
||||
- `CC-Switch-v{version}-Linux.flatpak`（Flatpak）
|
||||
|
||||
Flatpak のインストールと起動：
|
||||
|
||||
```bash
|
||||
flatpak install --user ./CC-Switch-v{version}-Linux.flatpak
|
||||
flatpak run com.ccswitch.desktop
|
||||
```
|
||||
|
||||
## クイックスタート
|
||||
|
||||
### 基本的な使い方
|
||||
|
||||
1. **プロバイダ追加**：「Add Provider」をクリック → プリセットを選ぶかカスタム設定を作成
|
||||
2. **プロバイダ切り替え**:
|
||||
- メイン UI: プロバイダを選択 → 「Enable」をクリック
|
||||
- システムトレイ: プロバイダ名をクリック（即時反映）
|
||||
3. **反映**: ターミナルや Claude Code / Codex / Gemini クライアントを再起動して適用
|
||||
4. **公式設定に戻す**: 「Official Login」プリセット（Claude/Codex）または「Google Official」プリセット（Gemini）を選び、対応クライアントを再起動してログイン/OAuth を実行
|
||||
|
||||
### MCP 管理
|
||||
|
||||
- **入口**: 右上の「MCP」ボタンをクリック
|
||||
- **サーバー追加**:
|
||||
- 組み込みテンプレート（mcp-fetch、mcp-filesystem など）を使用
|
||||
- stdio / http / sse の各トランスポートをサポート
|
||||
- アプリごとに独立した MCP を設定可能
|
||||
- **有効/無効**: トグルでライブ設定への同期を切り替え
|
||||
- **同期**: 有効なサーバーは各アプリのライブファイルへ自動同期
|
||||
- **インポート/エクスポート**: Claude/Codex/Gemini の設定ファイルから既存 MCP を取り込み
|
||||
|
||||
### Skills 管理 (v3.7.0 新機能)
|
||||
|
||||
- **入口**: 右上の「Skills」ボタンをクリック
|
||||
- **スキル探索**:
|
||||
- 事前設定済みの GitHub リポジトリを自動スキャン（Anthropic 公式、ComposioHQ、コミュニティなど）
|
||||
- カスタムリポジトリを追加（サブディレクトリスキャン対応）
|
||||
- **インストール**: 「Install」を押すだけで `~/.claude/skills/` に配置
|
||||
- **アンインストール**: 「Uninstall」で安全に削除と状態クリーンアップ
|
||||
- **リポジトリ管理**: カスタム GitHub リポジトリを追加/削除
|
||||
|
||||
### Prompts 管理 (v3.7.0 新機能)
|
||||
|
||||
- **入口**: 右上の「Prompts」ボタンをクリック
|
||||
- **プリセット作成**:
|
||||
- 無制限のシステムプロンプトプリセットを作成
|
||||
- Markdown エディタで記述（シンタックスハイライト + リアルタイムプレビュー）
|
||||
- **プリセット切り替え**: プリセットを選択 → 「Activate」で即適用
|
||||
- **同期先**:
|
||||
- Claude: `~/.claude/CLAUDE.md`
|
||||
- Codex: `~/.codex/AGENTS.md`
|
||||
- Gemini: `~/.gemini/GEMINI.md`
|
||||
- **保護機構**: 切り替え前に現在の内容を自動保存し、手動変更を保持
|
||||
|
||||
### 設定ファイルパス
|
||||
|
||||
**Claude Code**
|
||||
|
||||
- ライブ設定: `~/.claude/settings.json`（または `claude.json`）
|
||||
- API キーフィールド: `env.ANTHROPIC_AUTH_TOKEN` または `env.ANTHROPIC_API_KEY`
|
||||
- MCP サーバー: `~/.claude.json` → `mcpServers`
|
||||
|
||||
**Codex**
|
||||
|
||||
- ライブ設定: `~/.codex/auth.json`（必須）+ `config.toml`（任意）
|
||||
- API キーフィールド: `auth.json` 内の `OPENAI_API_KEY`
|
||||
- MCP サーバー: `~/.codex/config.toml` → `[mcp_servers]` テーブル
|
||||
|
||||
**Gemini**
|
||||
|
||||
- ライブ設定: `~/.gemini/.env`（API キー）+ `~/.gemini/settings.json`（認証モード）
|
||||
- API キーフィールド: `.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. 設定 → 「Custom Configuration Directory」へ進む
|
||||
2. クラウド同期フォルダ（Dropbox、OneDrive、iCloud など）を選択
|
||||
3. アプリを再起動して反映
|
||||
4. 他のデバイスでも同じフォルダを指定すればクロスデバイス同期が有効に
|
||||
|
||||
> **補足**: 初回起動時に既存の Claude/Codex 設定をデフォルトプロバイダとして自動インポートします。
|
||||
|
||||
## アーキテクチャ概要
|
||||
|
||||
### 設計原則
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Frontend (React + TS) │
|
||||
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │ Components │ │ Hooks │ │ TanStack Query │ │
|
||||
│ │ (UI) │──│ (Bus. Logic) │──│ (Cache/Sync) │ │
|
||||
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│ Tauri IPC
|
||||
┌────────────────────────▼────────────────────────────────────┐
|
||||
│ Backend (Tauri + Rust) │
|
||||
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │ Commands │ │ Services │ │ Models/Config │ │
|
||||
│ │ (API Layer) │──│ (Bus. Layer) │──│ (Data) │ │
|
||||
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**コア設計パターン**
|
||||
|
||||
- **SSOT** (Single Source of Truth): すべてのデータを `~/.cc-switch/cc-switch.db`（SQLite）に集約
|
||||
- **二層ストレージ**: 同期データは SQLite、デバイスデータは JSON
|
||||
- **双方向同期**: 切り替え時はライブファイルへ書き込み、編集時はアクティブプロバイダから逆同期
|
||||
- **アトミック書き込み**: 一時ファイル + rename パターンで設定破損を防止
|
||||
- **並行安全**: Mutex で保護された DB 接続でレースを防ぐ
|
||||
- **レイヤードアーキテクチャ**: Commands → Services → DAO → Database を明確に分離
|
||||
|
||||
**主要コンポーネント**
|
||||
|
||||
- **ProviderService**: プロバイダの CRUD、切り替え、バックフィル、ソート
|
||||
- **McpService**: MCP サーバー管理、インポート/エクスポート、ライブファイル同期
|
||||
- **ConfigService**: 設定のインポート/エクスポート、バックアップローテーション
|
||||
- **SpeedtestService**: API エンドポイントの遅延計測
|
||||
|
||||
**v3.6 リファクタリング**
|
||||
|
||||
- バックエンド: エラーハンドリング → コマンド分割 → テスト → サービス層 → 並行性の 5 フェーズ
|
||||
- フロントエンド: テスト基盤 → hooks → コンポーネント → クリーンアップの 4 ステージ
|
||||
- テスト: hooks 100% カバレッジ + 統合テスト（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
|
||||
|
||||
# test-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` - インポート/エクスポート
|
||||
- 統合テスト
|
||||
- アプリのメインフロー
|
||||
- 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/ # ビジネスロジック用カスタムフック
|
||||
│ ├── 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-legacy` ブランチを取得してください。
|
||||
|
||||
## 貢献
|
||||
|
||||
Issue や提案を歓迎します！
|
||||
|
||||
PR を送る前に以下をご確認ください:
|
||||
|
||||
- 型チェック: `pnpm typecheck`
|
||||
- フォーマットチェック: `pnpm format:check`
|
||||
- 単体テスト: `pnpm test:unit`
|
||||
- 💡 新機能の場合は、事前に Issue でディスカッションしていただけると助かります
|
||||
|
||||
## Star History
|
||||
|
||||
[](https://www.star-history.com/#farion1231/cc-switch&Date)
|
||||
|
||||
## ライセンス
|
||||
|
||||
MIT © Jason Young
|
||||
-501
@@ -1,501 +0,0 @@
|
||||
<div align="center">
|
||||
|
||||
# Claude Code / Codex / Gemini CLI 全方位辅助工具
|
||||
|
||||
[](https://github.com/farion1231/cc-switch/releases)
|
||||
[](https://github.com/farion1231/cc-switch/releases)
|
||||
[](https://tauri.app/)
|
||||
[](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>
|
||||
|
||||
## ❤️赞助商
|
||||
|
||||
[](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII)
|
||||
|
||||
感谢智谱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)购买可以享受九折优惠。
|
||||
|
||||
---
|
||||
|
||||
<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://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>
|
||||
|
||||
## 界面预览
|
||||
|
||||
| 主界面 | 添加供应商 |
|
||||
| :---------------------------------------: | :------------------------------------------: |
|
||||
|  |  |
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 当前版本：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
|
||||
|
||||
[](https://www.star-history.com/#farion1231/cc-switch&Date)
|
||||
|
||||
## License
|
||||
|
||||
MIT © Jason Young
|
||||
@@ -0,0 +1,76 @@
|
||||
# CC Switch 国际化功能说明
|
||||
|
||||
## 已完成的工作
|
||||
|
||||
1. **安装依赖**：添加了 `react-i18next` 和 `i18next` 包
|
||||
2. **配置国际化**：在 `src/i18n/` 目录下创建了配置文件
|
||||
3. **翻译文件**：创建了英文和中文翻译文件
|
||||
4. **组件更新**：替换了主要组件中的硬编码文案
|
||||
5. **语言切换器**：添加了语言切换按钮
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── i18n/
|
||||
│ ├── index.ts # 国际化配置文件
|
||||
│ └── locales/
|
||||
│ ├── en.json # 英文翻译
|
||||
│ └── zh.json # 中文翻译
|
||||
├── components/
|
||||
│ └── LanguageSwitcher.tsx # 语言切换组件
|
||||
└── main.tsx # 导入国际化配置
|
||||
```
|
||||
|
||||
## 默认语言设置
|
||||
|
||||
- **默认语言**：英文 (en)
|
||||
- **回退语言**：英文 (en)
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. 在组件中导入 `useTranslation`：
|
||||
```tsx
|
||||
import { useTranslation } from 'react-i18next';
|
||||
|
||||
function MyComponent() {
|
||||
const { t } = useTranslation();
|
||||
return <div>{t('common.save')}</div>;
|
||||
}
|
||||
```
|
||||
|
||||
2. 切换语言：
|
||||
```tsx
|
||||
const { i18n } = useTranslation();
|
||||
i18n.changeLanguage('zh'); // 切换到中文
|
||||
```
|
||||
|
||||
## 翻译键结构
|
||||
|
||||
- `common.*` - 通用文案（保存、取消、设置等）
|
||||
- `header.*` - 头部相关文案
|
||||
- `provider.*` - 供应商相关文案
|
||||
- `notifications.*` - 通知消息
|
||||
- `settings.*` - 设置页面文案
|
||||
- `apps.*` - 应用名称
|
||||
- `console.*` - 控制台日志信息
|
||||
|
||||
## 测试功能
|
||||
|
||||
应用已添加了语言切换按钮（地球图标），点击可以在中英文之间切换，验证国际化功能是否正常工作。
|
||||
|
||||
## 已更新的组件
|
||||
|
||||
- ✅ App.tsx - 主应用组件
|
||||
- ✅ ConfirmDialog.tsx - 确认对话框
|
||||
- ✅ AddProviderModal.tsx - 添加供应商弹窗
|
||||
- ✅ EditProviderModal.tsx - 编辑供应商弹窗
|
||||
- ✅ ProviderList.tsx - 供应商列表
|
||||
- ✅ LanguageSwitcher.tsx - 语言切换器
|
||||
- 🔄 SettingsModal.tsx - 设置弹窗（部分完成）
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 所有新的文案都应该添加到翻译文件中，而不是硬编码
|
||||
2. 翻译键名应该有意义且结构化
|
||||
3. 可以通过修改 `src/i18n/index.ts` 中的 `lng` 配置来更改默认语言
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 264 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 299 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 68 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 8.1 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 179 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 6.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 206 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 216 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 212 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 227 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 226 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 225 KiB |
@@ -1,162 +0,0 @@
|
||||
/**
|
||||
* 统一供应商（Universal Provider）预设配置
|
||||
*
|
||||
* 统一供应商是跨应用共享的配置，修改后会自动同步到 Claude、Codex、Gemini 三个应用。
|
||||
* 适用于 NewAPI 等支持多种协议的 API 网关。
|
||||
*/
|
||||
|
||||
import type {
|
||||
UniversalProvider,
|
||||
UniversalProviderApps,
|
||||
UniversalProviderModels,
|
||||
} from "@/types";
|
||||
|
||||
/**
|
||||
* 统一供应商预设接口
|
||||
*/
|
||||
export interface UniversalProviderPreset {
|
||||
/** 预设名称 */
|
||||
name: string;
|
||||
/** 供应商类型标识 */
|
||||
providerType: string;
|
||||
/** 默认启用的应用 */
|
||||
defaultApps: UniversalProviderApps;
|
||||
/** 默认模型配置 */
|
||||
defaultModels: UniversalProviderModels;
|
||||
/** 网站链接 */
|
||||
websiteUrl?: string;
|
||||
/** 图标名称 */
|
||||
icon?: string;
|
||||
/** 图标颜色 */
|
||||
iconColor?: string;
|
||||
/** 描述 */
|
||||
description?: string;
|
||||
/** 是否为自定义模板（允许用户完全自定义） */
|
||||
isCustomTemplate?: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* NewAPI 默认模型配置
|
||||
*/
|
||||
const NEWAPI_DEFAULT_MODELS: UniversalProviderModels = {
|
||||
claude: {
|
||||
model: "claude-sonnet-4-20250514",
|
||||
haikuModel: "claude-haiku-4-20250514",
|
||||
sonnetModel: "claude-sonnet-4-20250514",
|
||||
opusModel: "claude-sonnet-4-20250514",
|
||||
},
|
||||
codex: {
|
||||
model: "gpt-4o",
|
||||
reasoningEffort: "high",
|
||||
},
|
||||
gemini: {
|
||||
model: "gemini-2.5-pro",
|
||||
},
|
||||
};
|
||||
|
||||
const N1N_DEFAULT_MODELS: UniversalProviderModels = {
|
||||
claude: {
|
||||
model: "claude-3-5-sonnet-20240620",
|
||||
haikuModel: "claude-3-haiku-20240307",
|
||||
sonnetModel: "claude-3-5-sonnet-20240620",
|
||||
opusModel: "claude-3-opus-20240229",
|
||||
},
|
||||
codex: {
|
||||
model: "gpt-4o",
|
||||
reasoningEffort: "high",
|
||||
},
|
||||
gemini: {
|
||||
model: "gemini-1.5-pro-latest",
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* 统一供应商预设列表
|
||||
*/
|
||||
export const universalProviderPresets: UniversalProviderPreset[] = [
|
||||
{
|
||||
name: "n1n.ai",
|
||||
providerType: "n1n",
|
||||
defaultApps: {
|
||||
claude: true,
|
||||
codex: true,
|
||||
gemini: true,
|
||||
},
|
||||
defaultModels: N1N_DEFAULT_MODELS,
|
||||
websiteUrl: "https://n1n.ai",
|
||||
icon: "openai",
|
||||
iconColor: "#000000",
|
||||
description:
|
||||
"n1n.ai - 聚合 OpenAI, Anthropic, Google 等主流大模型的一站式 AI 服务平台",
|
||||
},
|
||||
{
|
||||
name: "NewAPI",
|
||||
providerType: "newapi",
|
||||
defaultApps: {
|
||||
claude: true,
|
||||
codex: true,
|
||||
gemini: true,
|
||||
},
|
||||
defaultModels: NEWAPI_DEFAULT_MODELS,
|
||||
websiteUrl: "https://www.newapi.pro",
|
||||
icon: "newapi",
|
||||
iconColor: "#00A67E",
|
||||
description:
|
||||
"NewAPI 是一个可自部署的 API 网关，支持 Anthropic、OpenAI、Gemini 等多种协议",
|
||||
},
|
||||
{
|
||||
name: "自定义网关",
|
||||
providerType: "custom_gateway",
|
||||
defaultApps: {
|
||||
claude: true,
|
||||
codex: true,
|
||||
gemini: true,
|
||||
},
|
||||
defaultModels: NEWAPI_DEFAULT_MODELS,
|
||||
icon: "openai",
|
||||
iconColor: "#6366F1",
|
||||
description: "自定义配置的 API 网关",
|
||||
isCustomTemplate: true,
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* 根据预设创建统一供应商
|
||||
*/
|
||||
export function createUniversalProviderFromPreset(
|
||||
preset: UniversalProviderPreset,
|
||||
id: string,
|
||||
baseUrl: string,
|
||||
apiKey: string,
|
||||
customName?: string,
|
||||
): UniversalProvider {
|
||||
return {
|
||||
id,
|
||||
name: customName || preset.name,
|
||||
providerType: preset.providerType,
|
||||
apps: { ...preset.defaultApps },
|
||||
baseUrl,
|
||||
apiKey,
|
||||
models: JSON.parse(JSON.stringify(preset.defaultModels)), // Deep copy
|
||||
websiteUrl: preset.websiteUrl,
|
||||
icon: preset.icon,
|
||||
iconColor: preset.iconColor,
|
||||
createdAt: Date.now(),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取预设的显示名称（用于 UI）
|
||||
*/
|
||||
export function getPresetDisplayName(preset: UniversalProviderPreset): string {
|
||||
return preset.name;
|
||||
}
|
||||
|
||||
/**
|
||||
* 根据类型查找预设
|
||||
*/
|
||||
export function findPresetByType(
|
||||
providerType: string,
|
||||
): UniversalProviderPreset | undefined {
|
||||
return universalProviderPresets.find((p) => p.providerType === providerType);
|
||||
}
|
||||
@@ -1,21 +0,0 @@
|
||||
{
|
||||
"$schema": "https://ui.shadcn.com/schema.json",
|
||||
"style": "default",
|
||||
"rsc": false,
|
||||
"tsx": true,
|
||||
"tailwind": {
|
||||
"config": "tailwind.config.cjs",
|
||||
"css": "src/index.css",
|
||||
"baseColor": "neutral",
|
||||
"cssVariables": true,
|
||||
"prefix": ""
|
||||
},
|
||||
"iconLibrary": "lucide",
|
||||
"aliases": {
|
||||
"components": "@/components",
|
||||
"utils": "@/lib/utils",
|
||||
"ui": "@/components/ui",
|
||||
"lib": "@/lib",
|
||||
"hooks": "@/hooks"
|
||||
}
|
||||
}
|
||||
-2178
File diff suppressed because it is too large
Load Diff
@@ -1,169 +0,0 @@
|
||||
# CC Switch Rust 后端重构方案
|
||||
|
||||
## 目录
|
||||
- [背景与现状](#背景与现状)
|
||||
- [问题确认](#问题确认)
|
||||
- [方案评估](#方案评估)
|
||||
- [渐进式重构路线](#渐进式重构路线)
|
||||
- [测试策略](#测试策略)
|
||||
- [风险与对策](#风险与对策)
|
||||
- [总结](#总结)
|
||||
|
||||
## 背景与现状
|
||||
- 前端已完成重构，后端 (Tauri + Rust) 仍维持历史结构。
|
||||
- 核心文件集中在 `src-tauri/src/commands.rs`、`lib.rs` 等超大文件中，业务逻辑与界面事件耦合严重。
|
||||
- 测试覆盖率低，只有零散单元测试，缺乏集成验证。
|
||||
|
||||
## 问题确认
|
||||
|
||||
| 提案问题 | 实际情况 | 严重程度 |
|
||||
| --- | --- | --- |
|
||||
| `commands.rs` 过长 | ✅ 1526 行，包含 32 个命令，职责混杂 | 🔴 高 |
|
||||
| `lib.rs` 缺少服务层 | ✅ 541 行，托盘/事件/业务逻辑耦合 | 🟡 中 |
|
||||
| `Result<T, String>` 泛滥 | ✅ 118 处，错误上下文丢失 | 🟡 中 |
|
||||
| 全局 `Mutex` 阻塞 | ✅ 31 处 `.lock()` 调用，读写不分离 | 🟡 中 |
|
||||
| 配置逻辑分散 | ✅ 分布在 5 个文件 (`config`/`app_config`/`app_store`/`settings`/`codex_config`) | 🟢 低 |
|
||||
|
||||
代码规模分布（约 5.4k SLOC）：
|
||||
- `commands.rs`: 1526 行（28%）→ 第一优先级 🎯
|
||||
- `lib.rs`: 541 行（10%）→ 托盘逻辑与业务耦合
|
||||
- `mcp.rs`: 732 行（14%）→ 相对清晰
|
||||
- `migration.rs`: 431 行（8%）→ 一次性逻辑
|
||||
- 其他文件合计：2156 行（40%）
|
||||
|
||||
## 方案评估
|
||||
|
||||
### ✅ 优点
|
||||
1. **分层架构清晰**
|
||||
- `commands/`：Tauri 命令薄层
|
||||
- `services/`：业务流程，如供应商切换、MCP 同步
|
||||
- `infrastructure/`：配置读写、外设交互
|
||||
- `domain/`：数据模型 (`Provider`, `AppType` 等)
|
||||
→ 提升可测试性、降低耦合度、方便团队协作。
|
||||
|
||||
2. **统一错误处理**
|
||||
- 引入 `AppError`（`thiserror`），保留错误链和上下文。
|
||||
- Tauri 命令仍返回 `Result<T, String>`，通过 `From<AppError>` 自动转换。
|
||||
- 改善日志可读性，利于排查。
|
||||
|
||||
3. **并发优化**
|
||||
- `AppState` 切换为 `RwLock<MultiAppConfig>`。
|
||||
- 读多写少的场景提升吞吐（如频繁查询供应商列表）。
|
||||
|
||||
### ⚠️ 风险
|
||||
1. **过度设计**
|
||||
- 完整 DDD 四层在 5k 行项目中会增加 30-50% 维护成本。
|
||||
- Rust trait + repository 样板较多，收益不足。
|
||||
- 推荐“轻量分层”而非正统 DDD。
|
||||
|
||||
2. **迁移成本高**
|
||||
- `commands.rs` 拆分、错误统一、锁改造触及多文件。
|
||||
- 测试缺失导致重构风险高，需先补测试。
|
||||
- 估算完整改造需 5-6 周；建议分阶段输出可落地价值。
|
||||
|
||||
3. **技术选型需谨慎**
|
||||
- `parking_lot` 相比标准库 `RwLock` 提升有限，不必引入。
|
||||
- `spawn_blocking` 仅用于 >100ms 的阻塞任务，避免滥用。
|
||||
- 以现有依赖为主，控制复杂度。
|
||||
|
||||
## 实施进度
|
||||
- **阶段 1：统一错误处理 ✅**
|
||||
- 引入 `thiserror` 并在 `src-tauri/src/error.rs` 定义 `AppError`，提供常用构造函数和 `From<AppError> for String`，保留错误链路。
|
||||
- 配置、存储、同步等核心模块（`config.rs`、`app_config.rs`、`app_store.rs`、`store.rs`、`codex_config.rs`、`claude_mcp.rs`、`claude_plugin.rs`、`import_export.rs`、`mcp.rs`、`migration.rs`、`speedtest.rs`、`usage_script.rs`、`settings.rs`、`lib.rs` 等）已统一返回 `Result<_, AppError>`，避免字符串错误丢失上下文。
|
||||
- Tauri 命令层继续返回 `Result<_, String>`，通过 `?` + `Into<String>` 统一转换，前端无需调整。
|
||||
- `cargo check` 通过，`rg "Result<[^>]+, String"` 巡检确认除命令层外已无字符串错误返回。
|
||||
- **阶段 2：拆分命令层 ✅**
|
||||
- 已将单一 `src-tauri/src/commands.rs` 拆分为 `commands/{provider,mcp,config,settings,misc,plugin}.rs` 并通过 `commands/mod.rs` 统一导出，保持对外 API 不变。
|
||||
- 每个文件聚焦单一功能域（供应商、MCP、配置、设置、杂项、插件），命令函数平均 150-250 行，可读性与后续维护性显著提升。
|
||||
- 相关依赖调整后 `cargo check` 通过，静态巡检确认无重复定义或未注册命令。
|
||||
- **阶段 3：补充测试 ✅**
|
||||
- `tests/import_export_sync.rs` 集成测试涵盖配置备份、Claude/Codex live 同步、MCP 投影与 Codex/Claude 双向导入流程，并新增启用项清理、非法 TOML 抛错等失败场景验证；统一使用隔离 HOME 目录避免污染真实用户环境。
|
||||
- 扩展 `lib.rs` re-export，暴露 `AppType`、`MultiAppConfig`、`AppError`、配置 IO 以及 Codex/Claude MCP 路径与同步函数，方便服务层及测试直接复用核心逻辑。
|
||||
- 新增负向测试验证 Codex 供应商缺少 `auth` 字段时的错误返回，并补充备份数量上限测试；顺带修复 `create_backup` 采用内存读写避免拷贝继承旧的修改时间，确保最新备份不会在清理阶段被误删。
|
||||
- 针对 `codex_config::write_codex_live_atomic` 补充成功与失败场景测试，覆盖 auth/config 原子写入与失败回滚逻辑（模拟目标路径为目录时的 rename 失败），降低 Codex live 写入回归风险。
|
||||
- 新增 `tests/provider_commands.rs` 覆盖 `switch_provider` 的 Codex 正常流程与供应商缺失分支，并抽取 `switch_provider_internal` 以复用 `AppError`，通过 `switch_provider_test_hook` 暴露测试入口；同时共享 `tests/support.rs` 提供隔离 HOME / 互斥工具函数。
|
||||
- 补充 Claude 切换集成测试，验证 live `settings.json` 覆写、新旧供应商快照回填以及 `.cc-switch/config.json` 持久化结果，确保阶段四提取服务层时拥有可回归的用例。
|
||||
- 增加 Codex 缺失 `auth` 场景测试，确认 `switch_provider_internal` 在关键字段缺失时返回带上下文的 `AppError`，同时保持内存状态未被污染。
|
||||
- 为配置导入命令抽取复用逻辑 `import_config_from_path` 并补充成功/失败集成测试，校验备份生成、状态同步、JSON 解析与文件缺失等错误回退路径；`export_config_to_file` 亦具备成功/缺失源文件的命令级回归。
|
||||
- 新增 `tests/mcp_commands.rs`，通过测试钩子覆盖 `import_default_config`、`import_mcp_from_claude`、`set_mcp_enabled` 等命令层行为，验证缺失文件/非法 JSON 的错误回滚以及成功路径落盘效果；阶段三目标达成，命令层关键边界已具备回归保障。
|
||||
- **阶段 4：服务层抽象 🚧（进行中）**
|
||||
- 新增 `services/provider.rs` 并实现 `ProviderService::switch` / `delete`，集中处理供应商切换、回填、MCP 同步等核心业务；命令层改为薄封装并在 `tests/provider_service.rs`、`tests/provider_commands.rs` 中完成成功与失败路径的集成验证。
|
||||
- 新增 `services/mcp.rs` 提供 `McpService`，封装 MCP 服务器的查询、增删改、启用同步与导入流程；命令层改为参数解析 + 调用服务，`tests/mcp_commands.rs` 直接使用 `McpService` 验证成功与失败路径，阶段三测试继续适配。
|
||||
- `McpService` 在内部先复制内存快照、释放写锁，再执行文件同步，避免阶段五升级后的 `RwLock` 在 I/O 场景被长时间占用；`upsert/delete/set_enabled/sync_enabled` 均已修正。
|
||||
- 新增 `services/config.rs` 提供 `ConfigService`，统一处理配置导入导出、备份与 live 同步；命令层迁移至 `commands/import_export.rs`，在落盘操作前释放锁并复用现有集成测试。
|
||||
- 新增 `services/speedtest.rs` 并实现 `SpeedtestService::test_endpoints`，将 URL 校验、超时裁剪与网络请求封装在服务层，命令改为薄封装；补充单元测试覆盖空列表与非法 URL 分支。
|
||||
- 后续可选：应用设置（Store）命令仍较薄，可按需评估是否抽象；当前阶段四核心服务已基本齐备。
|
||||
- **阶段 5：锁与阻塞优化 ✅（首轮）**
|
||||
- `AppState` 已由 `Mutex<MultiAppConfig>` 切换为 `RwLock<MultiAppConfig>`，托盘、命令与测试均按读写语义区分 `read()` / `write()`；`cargo test` 全量通过验证并未破坏现有流程。
|
||||
- 针对高开销 IO 的配置导入/导出命令提取 `load_config_for_import`，并通过 `tauri::async_runtime::spawn_blocking` 将文件读写与备份迁至阻塞线程，保持命令处理线程轻量。
|
||||
- 其余命令梳理后确认仍属轻量同步操作，暂不额外引入 `spawn_blocking`；若后续出现新的长耗时流程，再按同一模式扩展。
|
||||
|
||||
## 渐进式重构路线
|
||||
|
||||
### 阶段 1：统一错误处理（高收益 / 低风险）
|
||||
- 新增 `src-tauri/src/error.rs`，定义 `AppError`。
|
||||
- 底层文件 IO、配置解析等函数返回 `Result<T, AppError>`。
|
||||
- 命令层通过 `?` 自动传播，最终 `.map_err(Into::into)`。
|
||||
- 预估 3-5 天，立即启动。
|
||||
|
||||
### 阶段 2：拆分 `commands.rs`（高收益 / 中风险）
|
||||
- 按业务拆分为 `commands/provider.rs`、`commands/mcp.rs`、`commands/config.rs`、`commands/settings.rs`、`commands/misc.rs`。
|
||||
- `commands/mod.rs` 统一导出和注册。
|
||||
- 文件行数降低到 200-300 行/文件，职责单一。
|
||||
- 预估 5-7 天，可并行进行部分重构。
|
||||
|
||||
### 阶段 3：补充测试（中收益 / 中风险）
|
||||
- 引入 `tests/` 或 `src-tauri/tests/` 集成测试，覆盖供应商切换、MCP 同步、配置迁移。
|
||||
- 使用 `tempfile`/`tempdir` 隔离文件系统，组合少量回归脚本。
|
||||
- 预估 5-7 天，为后续重构提供安全网。
|
||||
|
||||
### 阶段 4：提取轻量服务层（中收益 / 中风险）
|
||||
- 新增 `services/provider_service.rs`、`services/mcp_service.rs`。
|
||||
- 不强制使用 trait；直接以自由函数/结构体实现业务流程。
|
||||
```rust
|
||||
pub struct ProviderService;
|
||||
impl ProviderService {
|
||||
pub fn switch(config: &mut MultiAppConfig, app: AppType, id: &str) -> Result<(), AppError> {
|
||||
// 业务流程：验证、回填、落盘、更新 current、触发事件
|
||||
}
|
||||
}
|
||||
```
|
||||
- 命令层负责参数解析，服务层处理业务逻辑，托盘逻辑重用同一接口。
|
||||
- 预估 7-10 天，可在测试补齐后执行。
|
||||
|
||||
### 阶段 5：锁与阻塞优化（低收益 / 低风险）
|
||||
- ✅ `AppState` 已从 `Mutex` 切换为 `RwLock`，命令与托盘读写按需区分，现有测试全部通过。
|
||||
- ✅ 配置导入/导出命令通过 `spawn_blocking` 处理高开销文件 IO；其他命令维持同步执行以避免不必要调度。
|
||||
- 🔄 持续监控：若后续引入新的批量迁移或耗时任务，再按相同模式扩展到阻塞线程；观察运行时锁竞争情况，必要时考虑进一步拆分状态或引入缓存。
|
||||
|
||||
## 测试策略
|
||||
- **优先覆盖场景**
|
||||
- 供应商切换：状态更新 + live 配置同步
|
||||
- MCP 同步：enabled 服务器快照与落盘
|
||||
- 配置迁移：归档、备份与版本升级
|
||||
- **推荐结构**
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod integration {
|
||||
use super::*;
|
||||
#[test]
|
||||
fn switch_provider_updates_live_config() { /* ... */ }
|
||||
#[test]
|
||||
fn sync_mcp_to_codex_updates_claude_config() { /* ... */ }
|
||||
#[test]
|
||||
fn migration_preserves_backup() { /* ... */ }
|
||||
}
|
||||
```
|
||||
- 目标覆盖率：关键路径 >80%，文件 IO/迁移 >70%。
|
||||
|
||||
## 风险与对策
|
||||
- **测试不足** → 阶段 3 强制补齐，建立基础集成测试。
|
||||
- **重构跨度大** → 按阶段在独立分支推进（如 `refactor/backend-step1` 等）。
|
||||
- **回滚困难** → 每阶段结束打 tag（如 `v3.6.0-backend-step1`），保留回滚点。
|
||||
- **功能回归** → 重构后执行手动冒烟流程：供应商切换、托盘操作、MCP 同步、配置导入导出。
|
||||
|
||||
## 总结
|
||||
- 当前规模下不建议整体引入完整 DDD/四层架构，避免过度设计。
|
||||
- 建议遵循“错误统一 → 命令拆分 → 补测试 → 服务层抽象 → 锁优化”的渐进式策略。
|
||||
- 完成阶段 1-3 后即可显著提升可维护性与可靠性；阶段 4-5 可根据资源灵活安排。
|
||||
- 重构过程中同步维护文档与测试，确保团队成员对架构演进保持一致认知。
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,490 +0,0 @@
|
||||
# CC Switch 重构实施清单
|
||||
|
||||
> 用于跟踪重构进度的详细检查清单
|
||||
|
||||
**开始日期**: ___________
|
||||
**预计完成**: ___________
|
||||
**当前阶段**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 0: 准备阶段 (预计 1 天)
|
||||
|
||||
### 环境准备
|
||||
|
||||
- [ ] 创建新分支 `refactor/modernization`
|
||||
- [ ] 创建备份标签 `git tag backup-before-refactor`
|
||||
- [ ] 备份用户配置文件 `~/.cc-switch/config.json`
|
||||
- [ ] 通知团队成员重构开始
|
||||
|
||||
### 依赖安装
|
||||
|
||||
```bash
|
||||
pnpm add @tanstack/react-query
|
||||
pnpm add react-hook-form @hookform/resolvers
|
||||
pnpm add zod
|
||||
pnpm add sonner
|
||||
pnpm add next-themes
|
||||
pnpm add @radix-ui/react-dialog @radix-ui/react-dropdown-menu
|
||||
pnpm add @radix-ui/react-label @radix-ui/react-select
|
||||
pnpm add @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs
|
||||
pnpm add class-variance-authority clsx tailwind-merge tailwindcss-animate
|
||||
```
|
||||
|
||||
- [ ] 安装核心依赖 (上述命令)
|
||||
- [ ] 验证依赖安装成功 `pnpm install`
|
||||
- [ ] 验证编译通过 `pnpm typecheck`
|
||||
|
||||
### 配置文件
|
||||
|
||||
- [ ] 创建 `components.json`
|
||||
- [ ] 更新 `tsconfig.json` 添加路径别名
|
||||
- [ ] 更新 `vite.config.mts` 添加路径解析
|
||||
- [ ] 验证开发服务器启动 `pnpm dev`
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 1: 基础设施 (预计 2-3 天)
|
||||
|
||||
### 1.1 工具函数和基础组件
|
||||
|
||||
- [ ] 创建 `src/lib/utils.ts` (cn 函数)
|
||||
- [ ] 创建 `src/components/ui/button.tsx`
|
||||
- [ ] 创建 `src/components/ui/dialog.tsx`
|
||||
- [ ] 创建 `src/components/ui/input.tsx`
|
||||
- [ ] 创建 `src/components/ui/label.tsx`
|
||||
- [ ] 创建 `src/components/ui/textarea.tsx`
|
||||
- [ ] 创建 `src/components/ui/select.tsx`
|
||||
- [ ] 创建 `src/components/ui/switch.tsx`
|
||||
- [ ] 创建 `src/components/ui/tabs.tsx`
|
||||
- [ ] 创建 `src/components/ui/sonner.tsx`
|
||||
- [ ] 创建 `src/components/ui/form.tsx`
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证所有 UI 组件可以正常导入
|
||||
- [ ] 创建一个测试页面验证组件样式
|
||||
|
||||
### 1.2 Query Client 设置
|
||||
|
||||
- [ ] 创建 `src/lib/query/queryClient.ts`
|
||||
- [ ] 配置默认选项 (retry, staleTime 等)
|
||||
- [ ] 导出 queryClient 实例
|
||||
|
||||
### 1.3 API 层
|
||||
|
||||
- [ ] 创建 `src/lib/api/providers.ts`
|
||||
- [ ] getAll
|
||||
- [ ] getCurrent
|
||||
- [ ] add
|
||||
- [ ] update
|
||||
- [ ] delete
|
||||
- [ ] switch
|
||||
- [ ] importDefault
|
||||
- [ ] updateTrayMenu
|
||||
|
||||
- [ ] 创建 `src/lib/api/settings.ts`
|
||||
- [ ] get
|
||||
- [ ] save
|
||||
|
||||
- [ ] 创建 `src/lib/api/mcp.ts`
|
||||
- [ ] getConfig
|
||||
- [ ] upsertServer
|
||||
- [ ] deleteServer
|
||||
|
||||
- [ ] 创建 `src/lib/api/index.ts` (聚合导出)
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证 API 调用不会出现运行时错误
|
||||
- [ ] 确认类型定义正确
|
||||
|
||||
### 1.4 Query Hooks
|
||||
|
||||
- [ ] 创建 `src/lib/query/queries.ts`
|
||||
- [ ] useProvidersQuery
|
||||
- [ ] useSettingsQuery
|
||||
- [ ] useMcpConfigQuery
|
||||
|
||||
- [ ] 创建 `src/lib/query/mutations.ts`
|
||||
- [ ] useAddProviderMutation
|
||||
- [ ] useSwitchProviderMutation
|
||||
- [ ] useDeleteProviderMutation
|
||||
- [ ] useUpdateProviderMutation
|
||||
- [ ] useSaveSettingsMutation
|
||||
|
||||
- [ ] 创建 `src/lib/query/index.ts` (聚合导出)
|
||||
|
||||
**测试**:
|
||||
- [ ] 在临时组件中测试每个 hook
|
||||
- [ ] 验证 loading/error 状态正确
|
||||
- [ ] 验证缓存和自动刷新工作
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 2: 核心功能重构 (预计 3-4 天)
|
||||
|
||||
### 2.1 主题系统
|
||||
|
||||
- [ ] 创建 `src/components/theme-provider.tsx`
|
||||
- [ ] 创建 `src/components/mode-toggle.tsx`
|
||||
- [ ] 更新 `src/index.css` 添加主题变量
|
||||
- [ ] 删除 `src/hooks/useDarkMode.ts`
|
||||
- [ ] 更新所有组件使用新的主题系统
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证主题切换正常工作
|
||||
- [ ] 验证系统主题跟随功能
|
||||
- [ ] 验证主题持久化
|
||||
|
||||
### 2.2 更新 main.tsx
|
||||
|
||||
- [ ] 引入 QueryClientProvider
|
||||
- [ ] 引入 ThemeProvider
|
||||
- [ ] 添加 Toaster 组件
|
||||
- [ ] 移除旧的 API 导入
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证应用可以正常启动
|
||||
- [ ] 验证 Context 正确传递
|
||||
|
||||
### 2.3 重构 App.tsx
|
||||
|
||||
- [ ] 使用 useProvidersQuery 替代手动状态管理
|
||||
- [ ] 移除所有 loadProviders 相关代码
|
||||
- [ ] 移除手动 notification 状态
|
||||
- [ ] 简化事件监听逻辑
|
||||
- [ ] 更新对话框为新的 Dialog 组件
|
||||
|
||||
**目标**: 将 412 行代码减少到 ~100 行
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证供应商列表正常加载
|
||||
- [ ] 验证切换 Claude/Codex 正常工作
|
||||
- [ ] 验证事件监听正常工作
|
||||
|
||||
### 2.4 重构 ProviderList
|
||||
|
||||
- [ ] 创建 `src/components/providers/ProviderList.tsx`
|
||||
- [ ] 使用 mutation hooks 处理操作
|
||||
- [ ] 移除 onNotify prop
|
||||
- [ ] 移除手动状态管理
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证供应商列表渲染
|
||||
- [ ] 验证切换操作
|
||||
- [ ] 验证删除操作
|
||||
|
||||
### 2.5 重构表单系统
|
||||
|
||||
- [ ] 创建 `src/lib/schemas/provider.ts` (Zod schema)
|
||||
- [ ] 创建 `src/components/providers/ProviderForm.tsx`
|
||||
- [ ] 使用 react-hook-form
|
||||
- [ ] 使用 zodResolver
|
||||
- [ ] 字段级验证
|
||||
|
||||
- [ ] 创建 `src/components/providers/AddProviderDialog.tsx`
|
||||
- [ ] 使用新的 Dialog 组件
|
||||
- [ ] 集成 ProviderForm
|
||||
- [ ] 使用 useAddProviderMutation
|
||||
|
||||
- [ ] 创建 `src/components/providers/EditProviderDialog.tsx`
|
||||
- [ ] 使用新的 Dialog 组件
|
||||
- [ ] 集成 ProviderForm
|
||||
- [ ] 使用 useUpdateProviderMutation
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证表单验证正常工作
|
||||
- [ ] 验证错误提示显示正确
|
||||
- [ ] 验证提交操作成功
|
||||
- [ ] 验证表单重置功能
|
||||
|
||||
### 2.6 清理旧组件
|
||||
|
||||
- [x] 删除 `src/components/AddProviderModal.tsx`
|
||||
- [x] 删除 `src/components/EditProviderModal.tsx`
|
||||
- [x] 更新所有引用这些组件的地方
|
||||
- [x] 删除 `src/components/ProviderForm.tsx` 及 `src/components/ProviderForm/`
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 3: 设置和辅助功能 (预计 2-3 天)
|
||||
|
||||
### 3.1 重构 SettingsDialog
|
||||
|
||||
- [ ] 创建 `src/components/settings/SettingsDialog.tsx`
|
||||
- [ ] 使用 Tabs 组件
|
||||
- [ ] 集成各个设置子组件
|
||||
|
||||
- [ ] 创建 `src/components/settings/GeneralSettings.tsx`
|
||||
- [ ] 语言设置
|
||||
- [ ] 配置目录设置
|
||||
- [ ] 其他通用设置
|
||||
|
||||
- [ ] 创建 `src/components/settings/AboutSection.tsx`
|
||||
- [ ] 版本信息
|
||||
- [ ] 更新检查
|
||||
- [ ] 链接
|
||||
|
||||
- [ ] 创建 `src/components/settings/ImportExportSection.tsx`
|
||||
- [ ] 导入功能
|
||||
- [ ] 导出功能
|
||||
|
||||
**目标**: 将 643 行拆分为 4-5 个小组件，每个 100-150 行
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证设置保存功能
|
||||
- [ ] 验证导入导出功能
|
||||
- [ ] 验证更新检查功能
|
||||
|
||||
### 3.2 重构通知系统
|
||||
|
||||
- [ ] 在所有 mutations 中使用 `toast` 替代 `showNotification`
|
||||
- [ ] 移除 App.tsx 中的 notification 状态
|
||||
- [ ] 移除自定义通知组件
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证成功通知显示
|
||||
- [ ] 验证错误通知显示
|
||||
- [ ] 验证通知自动消失
|
||||
|
||||
### 3.3 重构确认对话框
|
||||
|
||||
- [ ] 更新 `src/components/ConfirmDialog.tsx` 使用新的 Dialog
|
||||
- [ ] 或者直接使用 shadcn/ui 的 AlertDialog
|
||||
|
||||
**测试**:
|
||||
- [ ] 验证删除确认对话框
|
||||
- [ ] 验证其他确认场景
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 4: 清理和优化 (预计 1-2 天)
|
||||
|
||||
### 4.1 移除旧代码
|
||||
|
||||
- [x] 删除 `src/lib/styles.ts`
|
||||
- [x] 从 `src/lib/tauri-api.ts` 移除 `window.api` 绑定
|
||||
- [x] 精简 `src/lib/tauri-api.ts`，只保留事件监听相关
|
||||
- [x] 删除或更新 `src/vite-env.d.ts` 中的过时类型
|
||||
|
||||
### 4.2 代码审查
|
||||
|
||||
- [ ] 检查所有 TODO 注释
|
||||
- [x] 检查是否还有 `window.api` 调用
|
||||
- [ ] 检查是否还有手动状态管理
|
||||
- [x] 统一代码风格
|
||||
|
||||
### 4.3 类型检查
|
||||
|
||||
- [x] 运行 `pnpm typecheck` 确保无错误
|
||||
- [x] 修复所有类型错误
|
||||
- [x] 更新类型定义
|
||||
|
||||
### 4.4 性能优化
|
||||
|
||||
- [ ] 检查是否有不必要的重渲染
|
||||
- [ ] 添加必要的 React.memo
|
||||
- [ ] 优化 Query 缓存配置
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段 5: 测试和修复 (预计 2-3 天)
|
||||
|
||||
### 5.1 功能测试
|
||||
|
||||
#### 供应商管理
|
||||
- [ ] 添加供应商 (Claude)
|
||||
- [ ] 添加供应商 (Codex)
|
||||
- [ ] 编辑供应商
|
||||
- [ ] 删除供应商
|
||||
- [ ] 切换供应商
|
||||
- [ ] 导入默认配置
|
||||
|
||||
#### 应用切换
|
||||
- [ ] Claude <-> Codex 切换
|
||||
- [ ] 切换后数据正确加载
|
||||
- [ ] 切换后托盘菜单更新
|
||||
|
||||
#### 设置
|
||||
- [ ] 保存通用设置
|
||||
- [ ] 切换语言
|
||||
- [ ] 配置目录选择
|
||||
- [ ] 导入配置
|
||||
- [ ] 导出配置
|
||||
|
||||
#### UI 交互
|
||||
- [ ] 主题切换 (亮色/暗色)
|
||||
- [ ] 对话框打开/关闭
|
||||
- [ ] 表单验证
|
||||
- [ ] Toast 通知
|
||||
|
||||
#### MCP 管理
|
||||
- [ ] 列表显示
|
||||
- [ ] 添加 MCP
|
||||
- [ ] 编辑 MCP
|
||||
- [ ] 删除 MCP
|
||||
- [ ] 启用/禁用 MCP
|
||||
|
||||
### 5.2 边界情况测试
|
||||
|
||||
- [ ] 空供应商列表
|
||||
- [ ] 无效配置文件
|
||||
- [ ] 网络错误
|
||||
- [ ] 后端错误响应
|
||||
- [ ] 并发操作
|
||||
- [ ] 表单输入边界值
|
||||
|
||||
### 5.3 兼容性测试
|
||||
|
||||
- [ ] Windows 测试
|
||||
- [ ] macOS 测试
|
||||
- [ ] Linux 测试
|
||||
|
||||
### 5.4 性能测试
|
||||
|
||||
- [ ] 100+ 供应商加载速度
|
||||
- [ ] 快速切换供应商
|
||||
- [ ] 内存使用情况
|
||||
- [ ] CPU 使用情况
|
||||
|
||||
### 5.5 Bug 修复
|
||||
|
||||
**Bug 列表** (发现后记录):
|
||||
|
||||
1. ___________
|
||||
- [ ] 已修复
|
||||
- [ ] 已验证
|
||||
|
||||
2. ___________
|
||||
- [ ] 已修复
|
||||
- [ ] 已验证
|
||||
|
||||
**完成时间**: ___________
|
||||
**遇到的问题**: ___________
|
||||
|
||||
---
|
||||
|
||||
## 📋 最终检查
|
||||
|
||||
### 代码质量
|
||||
|
||||
- [ ] 所有 TypeScript 错误已修复
|
||||
- [ ] 运行 `pnpm format` 格式化代码
|
||||
- [ ] 运行 `pnpm typecheck` 通过
|
||||
- [ ] 代码审查完成
|
||||
|
||||
### 文档更新
|
||||
|
||||
- [ ] 更新 `CLAUDE.md` 反映新架构
|
||||
- [ ] 更新 `README.md` (如有必要)
|
||||
- [ ] 添加 Migration Guide (可选)
|
||||
|
||||
### 性能基准
|
||||
|
||||
记录性能数据:
|
||||
|
||||
**旧版本**:
|
||||
- 启动时间: _____ms
|
||||
- 供应商加载: _____ms
|
||||
- 内存占用: _____MB
|
||||
|
||||
**新版本**:
|
||||
- 启动时间: _____ms
|
||||
- 供应商加载: _____ms
|
||||
- 内存占用: _____MB
|
||||
|
||||
### 代码统计
|
||||
|
||||
**代码行数对比**:
|
||||
|
||||
| 文件 | 旧版本 | 新版本 | 减少 |
|
||||
|------|--------|--------|------|
|
||||
| App.tsx | 412 | ~100 | -76% |
|
||||
| tauri-api.ts | 712 | ~50 | -93% |
|
||||
| ProviderForm.tsx | 271 | ~150 | -45% |
|
||||
| settings 模块 | 1046 | ~470 (拆分) | -55% |
|
||||
| **总计** | 2038 | ~700 | **-66%** |
|
||||
|
||||
---
|
||||
|
||||
## 📦 发布准备
|
||||
|
||||
### Pre-release 测试
|
||||
|
||||
- [ ] 创建 beta 版本 `v4.0.0-beta.1`
|
||||
- [ ] 在测试环境验证
|
||||
- [ ] 收集用户反馈
|
||||
|
||||
### 正式发布
|
||||
|
||||
- [ ] 合并到 main 分支
|
||||
- [ ] 创建 Release Tag `v4.0.0`
|
||||
- [ ] 更新 Changelog
|
||||
- [ ] 发布 GitHub Release
|
||||
- [ ] 通知用户更新
|
||||
|
||||
---
|
||||
|
||||
## 🚨 回滚触发条件
|
||||
|
||||
如果出现以下情况，考虑回滚:
|
||||
|
||||
- [ ] 重大功能无法使用
|
||||
- [ ] 用户数据丢失
|
||||
- [ ] 严重性能问题
|
||||
- [ ] 无法修复的兼容性问题
|
||||
|
||||
**回滚命令**:
|
||||
```bash
|
||||
git reset --hard backup-before-refactor
|
||||
# 或
|
||||
git revert <commit-range>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 总结报告
|
||||
|
||||
### 成功指标
|
||||
|
||||
- [ ] 所有现有功能正常工作
|
||||
- [ ] 代码量减少 40%+
|
||||
- [ ] 无用户数据丢失
|
||||
- [ ] 性能未下降
|
||||
|
||||
### 经验教训
|
||||
|
||||
**遇到的主要挑战**:
|
||||
1. ___________
|
||||
2. ___________
|
||||
3. ___________
|
||||
|
||||
**解决方案**:
|
||||
1. ___________
|
||||
2. ___________
|
||||
3. ___________
|
||||
|
||||
**未来改进**:
|
||||
1. ___________
|
||||
2. ___________
|
||||
3. ___________
|
||||
|
||||
---
|
||||
|
||||
**重构完成日期**: ___________
|
||||
**总耗时**: _____ 天
|
||||
**参与人员**: ___________
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,834 +0,0 @@
|
||||
# 重构快速参考指南
|
||||
|
||||
> 常见模式和代码示例的速查表
|
||||
|
||||
---
|
||||
|
||||
## 📑 目录
|
||||
|
||||
1. [React Query 使用](#react-query-使用)
|
||||
2. [react-hook-form 使用](#react-hook-form-使用)
|
||||
3. [shadcn/ui 组件使用](#shadcnui-组件使用)
|
||||
4. [代码迁移示例](#代码迁移示例)
|
||||
|
||||
---
|
||||
|
||||
## React Query 使用
|
||||
|
||||
### 基础查询
|
||||
|
||||
```typescript
|
||||
// 定义查询 Hook
|
||||
export const useProvidersQuery = (appId: AppId) => {
|
||||
return useQuery({
|
||||
queryKey: ['providers', appId],
|
||||
queryFn: async () => {
|
||||
const data = await providersApi.getAll(appId)
|
||||
return data
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// 在组件中使用
|
||||
function MyComponent() {
|
||||
const { data, isLoading, error } = useProvidersQuery('claude')
|
||||
|
||||
if (isLoading) return <div>Loading...</div>
|
||||
if (error) return <div>Error: {error.message}</div>
|
||||
|
||||
return <div>{/* 使用 data */}</div>
|
||||
}
|
||||
```
|
||||
|
||||
### Mutation (变更操作)
|
||||
|
||||
```typescript
|
||||
// 定义 Mutation Hook
|
||||
export const useAddProviderMutation = (appId: AppId) => {
|
||||
const queryClient = useQueryClient()
|
||||
|
||||
return useMutation({
|
||||
mutationFn: async (provider: Provider) => {
|
||||
return await providersApi.add(provider, appId)
|
||||
},
|
||||
onSuccess: () => {
|
||||
// 重新获取数据
|
||||
queryClient.invalidateQueries({ queryKey: ['providers', appId] })
|
||||
toast.success('添加成功')
|
||||
},
|
||||
onError: (error: Error) => {
|
||||
toast.error(`添加失败: ${error.message}`)
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// 在组件中使用
|
||||
function AddProviderDialog() {
|
||||
const mutation = useAddProviderMutation('claude')
|
||||
|
||||
const handleSubmit = (data: Provider) => {
|
||||
mutation.mutate(data)
|
||||
}
|
||||
|
||||
return (
|
||||
<button
|
||||
onClick={() => handleSubmit(formData)}
|
||||
disabled={mutation.isPending}
|
||||
>
|
||||
{mutation.isPending ? '添加中...' : '添加'}
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 乐观更新
|
||||
|
||||
```typescript
|
||||
export const useSwitchProviderMutation = (appId: AppId) => {
|
||||
const queryClient = useQueryClient()
|
||||
|
||||
return useMutation({
|
||||
mutationFn: async (providerId: string) => {
|
||||
return await providersApi.switch(providerId, appId)
|
||||
},
|
||||
// 乐观更新: 在请求发送前立即更新 UI
|
||||
onMutate: async (providerId) => {
|
||||
// 取消正在进行的查询
|
||||
await queryClient.cancelQueries({ queryKey: ['providers', appId] })
|
||||
|
||||
// 保存当前数据(以便回滚)
|
||||
const previousData = queryClient.getQueryData(['providers', appId])
|
||||
|
||||
// 乐观更新
|
||||
queryClient.setQueryData(['providers', appId], (old: any) => ({
|
||||
...old,
|
||||
currentProviderId: providerId,
|
||||
}))
|
||||
|
||||
return { previousData }
|
||||
},
|
||||
// 如果失败，回滚
|
||||
onError: (err, providerId, context) => {
|
||||
queryClient.setQueryData(['providers', appId], context?.previousData)
|
||||
toast.error('切换失败')
|
||||
},
|
||||
// 无论成功失败，都重新获取数据
|
||||
onSettled: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ['providers', appId] })
|
||||
},
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 依赖查询
|
||||
|
||||
```typescript
|
||||
// 第二个查询依赖第一个查询的结果
|
||||
const { data: providers } = useProvidersQuery(appId)
|
||||
const currentProviderId = providers?.currentProviderId
|
||||
|
||||
const { data: currentProvider } = useQuery({
|
||||
queryKey: ['provider', currentProviderId],
|
||||
queryFn: () => providersApi.getById(currentProviderId!),
|
||||
enabled: !!currentProviderId, // 只有当 ID 存在时才执行
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## react-hook-form 使用
|
||||
|
||||
### 基础表单
|
||||
|
||||
```typescript
|
||||
import { useForm } from 'react-hook-form'
|
||||
import { zodResolver } from '@hookform/resolvers/zod'
|
||||
import { z } from 'zod'
|
||||
|
||||
// 定义验证 schema
|
||||
const schema = z.object({
|
||||
name: z.string().min(1, '请输入名称'),
|
||||
email: z.string().email('邮箱格式不正确'),
|
||||
age: z.number().min(18, '年龄必须大于18'),
|
||||
})
|
||||
|
||||
type FormData = z.infer<typeof schema>
|
||||
|
||||
function MyForm() {
|
||||
const form = useForm<FormData>({
|
||||
resolver: zodResolver(schema),
|
||||
defaultValues: {
|
||||
name: '',
|
||||
email: '',
|
||||
age: 0,
|
||||
},
|
||||
})
|
||||
|
||||
const onSubmit = (data: FormData) => {
|
||||
console.log(data)
|
||||
}
|
||||
|
||||
return (
|
||||
<form onSubmit={form.handleSubmit(onSubmit)}>
|
||||
<input {...form.register('name')} />
|
||||
{form.formState.errors.name && (
|
||||
<span>{form.formState.errors.name.message}</span>
|
||||
)}
|
||||
|
||||
<button type="submit">提交</button>
|
||||
</form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 使用 shadcn/ui Form 组件
|
||||
|
||||
```typescript
|
||||
import { useForm } from 'react-hook-form'
|
||||
import { zodResolver } from '@hookform/resolvers/zod'
|
||||
import {
|
||||
Form,
|
||||
FormControl,
|
||||
FormField,
|
||||
FormItem,
|
||||
FormLabel,
|
||||
FormMessage,
|
||||
} from '@/components/ui/form'
|
||||
import { Input } from '@/components/ui/input'
|
||||
import { Button } from '@/components/ui/button'
|
||||
|
||||
function MyForm() {
|
||||
const form = useForm<FormData>({
|
||||
resolver: zodResolver(schema),
|
||||
})
|
||||
|
||||
return (
|
||||
<Form {...form}>
|
||||
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
|
||||
<FormField
|
||||
control={form.control}
|
||||
name="name"
|
||||
render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormLabel>名称</FormLabel>
|
||||
<FormControl>
|
||||
<Input placeholder="请输入名称" {...field} />
|
||||
</FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)}
|
||||
/>
|
||||
|
||||
<Button type="submit">提交</Button>
|
||||
</form>
|
||||
</Form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 动态表单验证
|
||||
|
||||
```typescript
|
||||
// 根据条件动态验证
|
||||
const schema = z.object({
|
||||
type: z.enum(['official', 'custom']),
|
||||
apiKey: z.string().optional(),
|
||||
baseUrl: z.string().optional(),
|
||||
}).refine(
|
||||
(data) => {
|
||||
// 如果是自定义供应商，必须填写 baseUrl
|
||||
if (data.type === 'custom') {
|
||||
return !!data.baseUrl
|
||||
}
|
||||
return true
|
||||
},
|
||||
{
|
||||
message: '自定义供应商必须填写 Base URL',
|
||||
path: ['baseUrl'],
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### 手动触发验证
|
||||
|
||||
```typescript
|
||||
function MyForm() {
|
||||
const form = useForm<FormData>()
|
||||
|
||||
const handleBlur = async () => {
|
||||
// 验证单个字段
|
||||
await form.trigger('name')
|
||||
|
||||
// 验证多个字段
|
||||
await form.trigger(['name', 'email'])
|
||||
|
||||
// 验证所有字段
|
||||
const isValid = await form.trigger()
|
||||
}
|
||||
|
||||
return <form>...</form>
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## shadcn/ui 组件使用
|
||||
|
||||
### Dialog (对话框)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
Dialog,
|
||||
DialogContent,
|
||||
DialogHeader,
|
||||
DialogTitle,
|
||||
DialogDescription,
|
||||
DialogFooter,
|
||||
} from '@/components/ui/dialog'
|
||||
import { Button } from '@/components/ui/button'
|
||||
|
||||
function MyDialog() {
|
||||
const [open, setOpen] = useState(false)
|
||||
|
||||
return (
|
||||
<Dialog open={open} onOpenChange={setOpen}>
|
||||
<DialogContent>
|
||||
<DialogHeader>
|
||||
<DialogTitle>标题</DialogTitle>
|
||||
<DialogDescription>描述信息</DialogDescription>
|
||||
</DialogHeader>
|
||||
|
||||
{/* 内容 */}
|
||||
<div>对话框内容</div>
|
||||
|
||||
<DialogFooter>
|
||||
<Button variant="outline" onClick={() => setOpen(false)}>
|
||||
取消
|
||||
</Button>
|
||||
<Button onClick={handleConfirm}>确认</Button>
|
||||
</DialogFooter>
|
||||
</DialogContent>
|
||||
</Dialog>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Select (选择器)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
Select,
|
||||
SelectContent,
|
||||
SelectItem,
|
||||
SelectTrigger,
|
||||
SelectValue,
|
||||
} from '@/components/ui/select'
|
||||
|
||||
function MySelect() {
|
||||
const [value, setValue] = useState('')
|
||||
|
||||
return (
|
||||
<Select value={value} onValueChange={setValue}>
|
||||
<SelectTrigger>
|
||||
<SelectValue placeholder="请选择" />
|
||||
</SelectTrigger>
|
||||
<SelectContent>
|
||||
<SelectItem value="option1">选项1</SelectItem>
|
||||
<SelectItem value="option2">选项2</SelectItem>
|
||||
<SelectItem value="option3">选项3</SelectItem>
|
||||
</SelectContent>
|
||||
</Select>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Tabs (标签页)
|
||||
|
||||
```typescript
|
||||
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
|
||||
|
||||
function MyTabs() {
|
||||
return (
|
||||
<Tabs defaultValue="tab1">
|
||||
<TabsList>
|
||||
<TabsTrigger value="tab1">标签1</TabsTrigger>
|
||||
<TabsTrigger value="tab2">标签2</TabsTrigger>
|
||||
<TabsTrigger value="tab3">标签3</TabsTrigger>
|
||||
</TabsList>
|
||||
|
||||
<TabsContent value="tab1">
|
||||
<div>标签1的内容</div>
|
||||
</TabsContent>
|
||||
|
||||
<TabsContent value="tab2">
|
||||
<div>标签2的内容</div>
|
||||
</TabsContent>
|
||||
|
||||
<TabsContent value="tab3">
|
||||
<div>标签3的内容</div>
|
||||
</TabsContent>
|
||||
</Tabs>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Toast 通知 (Sonner)
|
||||
|
||||
```typescript
|
||||
import { toast } from 'sonner'
|
||||
|
||||
// 成功通知
|
||||
toast.success('操作成功')
|
||||
|
||||
// 错误通知
|
||||
toast.error('操作失败')
|
||||
|
||||
// 加载中
|
||||
const toastId = toast.loading('处理中...')
|
||||
// 完成后更新
|
||||
toast.success('处理完成', { id: toastId })
|
||||
// 或
|
||||
toast.dismiss(toastId)
|
||||
|
||||
// 自定义持续时间
|
||||
toast.success('消息', { duration: 5000 })
|
||||
|
||||
// 带操作按钮
|
||||
toast('确认删除?', {
|
||||
action: {
|
||||
label: '删除',
|
||||
onClick: () => handleDelete(),
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 代码迁移示例
|
||||
|
||||
### 示例 1: 状态管理迁移
|
||||
|
||||
**旧代码** (手动状态管理):
|
||||
|
||||
```typescript
|
||||
const [providers, setProviders] = useState<Record<string, Provider>>({})
|
||||
const [currentProviderId, setCurrentProviderId] = useState('')
|
||||
const [loading, setLoading] = useState(false)
|
||||
const [error, setError] = useState<Error | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
const load = async () => {
|
||||
setLoading(true)
|
||||
setError(null)
|
||||
try {
|
||||
const data = await window.api.getProviders(appType)
|
||||
const currentId = await window.api.getCurrentProvider(appType)
|
||||
setProviders(data)
|
||||
setCurrentProviderId(currentId)
|
||||
} catch (err) {
|
||||
setError(err as Error)
|
||||
} finally {
|
||||
setLoading(false)
|
||||
}
|
||||
}
|
||||
load()
|
||||
}, [appId])
|
||||
```
|
||||
|
||||
**新代码** (React Query):
|
||||
|
||||
```typescript
|
||||
const { data, isLoading, error } = useProvidersQuery(appId)
|
||||
const providers = data?.providers || {}
|
||||
const currentProviderId = data?.currentProviderId || ''
|
||||
```
|
||||
|
||||
**减少**: 从 20+ 行到 3 行
|
||||
|
||||
---
|
||||
|
||||
### 示例 2: 表单验证迁移
|
||||
|
||||
**旧代码** (手动验证):
|
||||
|
||||
```typescript
|
||||
const [name, setName] = useState('')
|
||||
const [nameError, setNameError] = useState('')
|
||||
const [apiKey, setApiKey] = useState('')
|
||||
const [apiKeyError, setApiKeyError] = useState('')
|
||||
|
||||
const validate = () => {
|
||||
let valid = true
|
||||
|
||||
if (!name.trim()) {
|
||||
setNameError('请输入名称')
|
||||
valid = false
|
||||
} else {
|
||||
setNameError('')
|
||||
}
|
||||
|
||||
if (!apiKey.trim()) {
|
||||
setApiKeyError('请输入 API Key')
|
||||
valid = false
|
||||
} else if (apiKey.length < 10) {
|
||||
setApiKeyError('API Key 长度不足')
|
||||
valid = false
|
||||
} else {
|
||||
setApiKeyError('')
|
||||
}
|
||||
|
||||
return valid
|
||||
}
|
||||
|
||||
const handleSubmit = () => {
|
||||
if (validate()) {
|
||||
// 提交
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<form>
|
||||
<input value={name} onChange={e => setName(e.target.value)} />
|
||||
{nameError && <span>{nameError}</span>}
|
||||
|
||||
<input value={apiKey} onChange={e => setApiKey(e.target.value)} />
|
||||
{apiKeyError && <span>{apiKeyError}</span>}
|
||||
|
||||
<button onClick={handleSubmit}>提交</button>
|
||||
</form>
|
||||
)
|
||||
```
|
||||
|
||||
**新代码** (react-hook-form + zod):
|
||||
|
||||
```typescript
|
||||
const schema = z.object({
|
||||
name: z.string().min(1, '请输入名称'),
|
||||
apiKey: z.string().min(10, 'API Key 长度不足'),
|
||||
})
|
||||
|
||||
const form = useForm({
|
||||
resolver: zodResolver(schema),
|
||||
})
|
||||
|
||||
return (
|
||||
<Form {...form}>
|
||||
<form onSubmit={form.handleSubmit(onSubmit)}>
|
||||
<FormField
|
||||
control={form.control}
|
||||
name="name"
|
||||
render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormControl>
|
||||
<Input {...field} />
|
||||
</FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)}
|
||||
/>
|
||||
|
||||
<FormField
|
||||
control={form.control}
|
||||
name="apiKey"
|
||||
render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormControl>
|
||||
<Input {...field} />
|
||||
</FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)}
|
||||
/>
|
||||
|
||||
<Button type="submit">提交</Button>
|
||||
</form>
|
||||
</Form>
|
||||
)
|
||||
```
|
||||
|
||||
**减少**: 从 40+ 行到 30 行，且更健壮
|
||||
|
||||
---
|
||||
|
||||
### 示例 3: 通知系统迁移
|
||||
|
||||
**旧代码** (自定义通知):
|
||||
|
||||
```typescript
|
||||
const [notification, setNotification] = useState<{
|
||||
message: string
|
||||
type: 'success' | 'error'
|
||||
} | null>(null)
|
||||
const [isVisible, setIsVisible] = useState(false)
|
||||
|
||||
const showNotification = (message: string, type: 'success' | 'error') => {
|
||||
setNotification({ message, type })
|
||||
setIsVisible(true)
|
||||
setTimeout(() => {
|
||||
setIsVisible(false)
|
||||
setTimeout(() => setNotification(null), 300)
|
||||
}, 3000)
|
||||
}
|
||||
|
||||
return (
|
||||
<>
|
||||
{notification && (
|
||||
<div className={`notification ${isVisible ? 'visible' : ''} ${notification.type}`}>
|
||||
{notification.message}
|
||||
</div>
|
||||
)}
|
||||
{/* 其他内容 */}
|
||||
</>
|
||||
)
|
||||
```
|
||||
|
||||
**新代码** (Sonner):
|
||||
|
||||
```typescript
|
||||
import { toast } from 'sonner'
|
||||
|
||||
// 在需要的地方直接调用
|
||||
toast.success('操作成功')
|
||||
toast.error('操作失败')
|
||||
|
||||
// 在 main.tsx 中只需添加一次
|
||||
import { Toaster } from '@/components/ui/sonner'
|
||||
|
||||
<Toaster />
|
||||
```
|
||||
|
||||
**减少**: 从 20+ 行到 1 行调用
|
||||
|
||||
---
|
||||
|
||||
### 示例 4: 对话框迁移
|
||||
|
||||
**旧代码** (自定义 Modal):
|
||||
|
||||
```typescript
|
||||
const [isOpen, setIsOpen] = useState(false)
|
||||
|
||||
return (
|
||||
<>
|
||||
<button onClick={() => setIsOpen(true)}>打开</button>
|
||||
|
||||
{isOpen && (
|
||||
<div className="modal-backdrop" onClick={() => setIsOpen(false)}>
|
||||
<div className="modal-content" onClick={e => e.stopPropagation()}>
|
||||
<div className="modal-header">
|
||||
<h2>标题</h2>
|
||||
<button onClick={() => setIsOpen(false)}>×</button>
|
||||
</div>
|
||||
<div className="modal-body">
|
||||
{/* 内容 */}
|
||||
</div>
|
||||
<div className="modal-footer">
|
||||
<button onClick={() => setIsOpen(false)}>取消</button>
|
||||
<button onClick={handleConfirm}>确认</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
</>
|
||||
)
|
||||
```
|
||||
|
||||
**新代码** (shadcn/ui Dialog):
|
||||
|
||||
```typescript
|
||||
import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog'
|
||||
|
||||
const [isOpen, setIsOpen] = useState(false)
|
||||
|
||||
return (
|
||||
<>
|
||||
<Button onClick={() => setIsOpen(true)}>打开</Button>
|
||||
|
||||
<Dialog open={isOpen} onOpenChange={setIsOpen}>
|
||||
<DialogContent>
|
||||
<DialogHeader>
|
||||
<DialogTitle>标题</DialogTitle>
|
||||
</DialogHeader>
|
||||
{/* 内容 */}
|
||||
<DialogFooter>
|
||||
<Button variant="outline" onClick={() => setIsOpen(false)}>取消</Button>
|
||||
<Button onClick={handleConfirm}>确认</Button>
|
||||
</DialogFooter>
|
||||
</DialogContent>
|
||||
</Dialog>
|
||||
</>
|
||||
)
|
||||
```
|
||||
|
||||
**优势**:
|
||||
- 无需自定义样式
|
||||
- 内置无障碍支持
|
||||
- 自动管理焦点和 ESC 键
|
||||
|
||||
---
|
||||
|
||||
### 示例 5: API 调用迁移
|
||||
|
||||
**旧代码** (window.api):
|
||||
|
||||
```typescript
|
||||
// 添加供应商
|
||||
const handleAdd = async (provider: Provider) => {
|
||||
try {
|
||||
await window.api.addProvider(provider, appType)
|
||||
await loadProviders()
|
||||
showNotification('添加成功', 'success')
|
||||
} catch (error) {
|
||||
showNotification('添加失败', 'error')
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**新代码** (React Query Mutation):
|
||||
|
||||
```typescript
|
||||
// 在组件中
|
||||
const addMutation = useAddProviderMutation(appId)
|
||||
|
||||
const handleAdd = (provider: Provider) => {
|
||||
addMutation.mutate(provider)
|
||||
// 成功和错误处理已在 mutation 定义中处理
|
||||
}
|
||||
```
|
||||
|
||||
**优势**:
|
||||
- 自动处理 loading 状态
|
||||
- 统一的错误处理
|
||||
- 自动刷新数据
|
||||
- 更少的样板代码
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何在 mutation 成功后关闭对话框?
|
||||
|
||||
```typescript
|
||||
const mutation = useAddProviderMutation(appId)
|
||||
|
||||
const handleSubmit = (data: Provider) => {
|
||||
mutation.mutate(data, {
|
||||
onSuccess: () => {
|
||||
setIsOpen(false) // 关闭对话框
|
||||
},
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Q: 如何在表单中使用异步验证?
|
||||
|
||||
```typescript
|
||||
const schema = z.object({
|
||||
name: z.string().refine(
|
||||
async (name) => {
|
||||
// 检查名称是否已存在
|
||||
const exists = await checkNameExists(name)
|
||||
return !exists
|
||||
},
|
||||
{ message: '名称已存在' }
|
||||
),
|
||||
})
|
||||
```
|
||||
|
||||
### Q: 如何手动刷新 Query 数据?
|
||||
|
||||
```typescript
|
||||
const queryClient = useQueryClient()
|
||||
|
||||
// 方式1: 使缓存失效，触发重新获取
|
||||
queryClient.invalidateQueries({ queryKey: ['providers', appId] })
|
||||
|
||||
// 方式2: 直接刷新
|
||||
queryClient.refetchQueries({ queryKey: ['providers', appId] })
|
||||
|
||||
// 方式3: 更新缓存数据
|
||||
queryClient.setQueryData(['providers', appId], newData)
|
||||
```
|
||||
|
||||
### Q: 如何在组件外部使用 toast?
|
||||
|
||||
```typescript
|
||||
// 直接导入并使用即可
|
||||
import { toast } from 'sonner'
|
||||
|
||||
export const someUtil = () => {
|
||||
toast.success('工具函数中的通知')
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 调试技巧
|
||||
|
||||
### React Query DevTools
|
||||
|
||||
```typescript
|
||||
// 在 main.tsx 中添加
|
||||
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
|
||||
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<App />
|
||||
<ReactQueryDevtools initialIsOpen={false} />
|
||||
</QueryClientProvider>
|
||||
```
|
||||
|
||||
### 查看表单状态
|
||||
|
||||
```typescript
|
||||
const form = useForm()
|
||||
|
||||
// 在开发模式下打印表单状态
|
||||
console.log('Form values:', form.watch())
|
||||
console.log('Form errors:', form.formState.errors)
|
||||
console.log('Is valid:', form.formState.isValid)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
### 1. 避免不必要的重渲染
|
||||
|
||||
```typescript
|
||||
// 使用 React.memo
|
||||
export const ProviderCard = React.memo(({ provider, onEdit }: Props) => {
|
||||
// ...
|
||||
})
|
||||
|
||||
// 或使用 useMemo
|
||||
const sortedProviders = useMemo(
|
||||
() => Object.values(providers).sort(...),
|
||||
[providers]
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Query 配置优化
|
||||
|
||||
```typescript
|
||||
const { data } = useQuery({
|
||||
queryKey: ['providers', appId],
|
||||
queryFn: fetchProviders,
|
||||
staleTime: 1000 * 60 * 5, // 5分钟内不重新获取
|
||||
gcTime: 1000 * 60 * 10, // 10分钟后清除缓存
|
||||
})
|
||||
```
|
||||
|
||||
### 3. 表单性能优化
|
||||
|
||||
```typescript
|
||||
// 使用 mode 控制验证时机
|
||||
const form = useForm({
|
||||
mode: 'onBlur', // 失去焦点时验证
|
||||
// mode: 'onChange', // 每次输入都验证(较慢)
|
||||
// mode: 'onSubmit', // 提交时验证(最快)
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**提示**: 将此文档保存在浏览器书签或编辑器中，方便随时查阅！
|
||||
@@ -1,73 +0,0 @@
|
||||
# 前端测试开发计划
|
||||
|
||||
## 1. 背景与目标
|
||||
- **背景**：v3.5.0 起前端功能快速扩张（供应商管理、MCP、导入导出、端点测速、国际化），缺失系统化测试导致回归风险与人工验证成本攀升。
|
||||
- **目标**：在 3 个迭代内建立覆盖关键业务的自动化测试体系，形成稳定的手动冒烟流程，并将测试执行纳入 CI/CD。
|
||||
|
||||
## 2. 范围与优先级
|
||||
| 范围 | 内容 | 优先级 |
|
||||
| --- | --- | --- |
|
||||
| 供应商管理 | 列表、排序、预设/自定义表单、切换、复制、删除 | P0 |
|
||||
| 配置导入导出 | JSON 校验、备份、进度反馈、失败回滚 | P0 |
|
||||
| MCP 管理 | 列表、启停、模板、命令校验 | P1 |
|
||||
| 设置面板 | 主题/语言切换、目录设置、关于、更新检查 | P1 |
|
||||
| 端点速度测试 & 使用脚本 | 启动测试、状态指示、脚本保存 | P2 |
|
||||
| 国际化 | 中英切换、缺省文案回退 | P2 |
|
||||
|
||||
## 3. 测试分层策略
|
||||
- **单元测试（Vitest）**：纯函数与 Hook（`useProviderActions`、`useSettingsForm`、`useDragSort`、`useImportExport` 等）验证数据处理、错误分支、排序逻辑。
|
||||
- **组件测试（React Testing Library）**：关键组件（`ProviderList`、`AddProviderDialog`、`SettingsDialog`、`McpPanel`）模拟交互、校验、提示；结合 MSW 模拟 API。
|
||||
- **集成测试（App 级别）**：挂载 `App.tsx`，覆盖应用切换、编辑模式、导入导出回调、语言切换，验证状态同步与 toast 提示。
|
||||
- **端到端测试（Playwright）**：依赖 `pnpm dev:renderer`，串联供应商 CRUD、排序拖拽、MCP 启停、语言切换即时刷新、更新检查跳转。
|
||||
- **手动冒烟**：Tauri 桌面包 + dev server 双通道，验证托盘、系统权限、真实文件写入。
|
||||
|
||||
## 4. 环境与工具
|
||||
- 依赖：Node 18+、pnpm 8+、Vitest、React Testing Library、MSW、Playwright、Testing Library User Event、Playwright Trace Viewer。
|
||||
- 配置要点：
|
||||
- 在 `tsconfig` 中共享别名，Vitest 配合 `vite.config.mts`。
|
||||
- `setupTests.ts` 统一注册 MSW/RTL、自定义 matcher。
|
||||
- Playwright 使用多浏览器矩阵（Chromium 必选，WebKit 可选），并共享 `.env.test`。
|
||||
- Mock `@tauri-apps/api` 与 `providersApi`/`settingsApi`，隔离 Rust 层。
|
||||
|
||||
## 5. 自动化建设里程碑
|
||||
| 周期 | 目标 | 交付 |
|
||||
| --- | --- | --- |
|
||||
| Sprint 1 | Vitest 基础设施、核心 Hook 单测（P0） | `pnpm test:unit`、覆盖率报告、10+ 用例 |
|
||||
| Sprint 2 | 组件/集成测试、MSW Mock 层 | `pnpm test:component`、App 主流程用例 |
|
||||
| Sprint 3 | Playwright E2E、CI 接入 | `pnpm test:e2e`、CI job、冒烟脚本 |
|
||||
| 持续 | 回归用例补齐、视觉比对探索 | Playwright Trace、截图基线 |
|
||||
|
||||
## 6. 用例规划概览
|
||||
- **供应商管理**：新增（预设+自定义）、编辑校验、复制排序、切换失败回退、删除确认、使用脚本保存。
|
||||
- **导入导出**：成功、重复导入、校验失败、备份失败提示、导入后托盘刷新。
|
||||
- **MCP**：模板应用、协议切换（stdio/http）、命令校验、启停状态持久化。
|
||||
- **设置**：主题/语言即时生效、目录路径更新、更新检查按钮外链、关于信息渲染。
|
||||
- **端点速度测试**：触发测试、loading/成功/失败状态、指示器颜色、测速数据排序。
|
||||
- **国际化**：默认中文、切换英文后主界面/对话框文案变化、缺失 key fallback。
|
||||
|
||||
## 7. 数据与 Mock 策略
|
||||
- 在 `tests/fixtures/` 维护标准供应商、MCP、设置数据集。
|
||||
- 使用 MSW 拦截 `providersApi`、`settingsApi`、`providersApi.onSwitched` 等调用；提供延迟/错误注入接口以覆盖异常分支。
|
||||
- Playwright 端提供临时用户目录（`TMP_CC_SWITCH_HOME`）+ 伪配置文件，以验证真实文件交互路径。
|
||||
|
||||
## 8. 质量门禁与指标
|
||||
- 覆盖率目标：单元 ≥75%，分支 ≥70%，逐步提升至 80%+。
|
||||
- CI 阶段：`pnpm typecheck` → `pnpm format:check` → `pnpm test:unit` → `pnpm test:component` → `pnpm test:e2e`（可在 nightly 执行）。
|
||||
- 缺陷处理：修复前补充最小复现测试；E2E 冒烟必须陪跑重大功能发布。
|
||||
|
||||
## 9. 工作流与职责
|
||||
- **测试负责人**：前端工程师轮值；负责测试计划维护、PR 流水线健康。
|
||||
- **开发者职责**：提交功能需附新增/更新测试、列出手动验证步骤、如涉及 UI 提交截图。
|
||||
- **Code Review 检查**：测试覆盖说明、mock 合理性、易读性。
|
||||
|
||||
## 10. 风险与缓解
|
||||
| 风险 | 影响 | 缓解 |
|
||||
| --- | --- | --- |
|
||||
| Tauri API Mock 难度高 | 单测无法稳定 | 抽象 API 适配层 + MSW 统一模拟 |
|
||||
| Playwright 运行时间长 | CI 变慢 | 拆分冒烟/完整版，冒烟只跑关键路径 |
|
||||
| 国际化文案频繁变化 | 用例脆弱 | 优先断言 data-testid/结构，文案使用翻译 key |
|
||||
|
||||
## 11. 输出与维护
|
||||
- 文档维护者：前端团队；每个版本更新后检查测试覆盖清单。
|
||||
- 交付物：测试报告（CI artifact）、Playwright Trace、覆盖率摘要。
|
||||
- 复盘：每次发布后召开 30 分钟测试复盘，记录缺陷、补齐用例。
|
||||
@@ -1,485 +0,0 @@
|
||||
# OpenCode 第四应用支持实现计划
|
||||
|
||||
> **范围说明**：本计划暂不包含统一供应商（UniversalProvider）对 OpenCode 的支持，以降低初期实现复杂度。
|
||||
|
||||
## 概述
|
||||
|
||||
为 CC Switch 添加 OpenCode 支持，这是第四个受管理的 CLI 应用。OpenCode 的核心差异在于采用**累加式**供应商管理（多供应商共存，应用内热切换），而非现有三应用的**替换式**管理。
|
||||
|
||||
## 关键设计决策
|
||||
|
||||
| 特性 | Claude/Codex/Gemini | OpenCode |
|
||||
|------|---------------------|----------|
|
||||
| 供应商模式 | 替换式（单一活跃） | 累加式（多供应商共存） |
|
||||
| UI 按钮 | 启用/切换 | 添加/删除 |
|
||||
| is_current | 需要 | 不需要 |
|
||||
| 代理/故障转移 | 支持 | 不支持 |
|
||||
| API 格式字段 | 无 | 需要（npm 包名） |
|
||||
| 配置文件 | 各自独立 | `~/.config/opencode/opencode.json` |
|
||||
|
||||
## 配置文件格式
|
||||
|
||||
### 供应商配置
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"provider-id": {
|
||||
"npm": "@ai-sdk/openai-compatible",
|
||||
"name": "Provider Name",
|
||||
"options": {
|
||||
"baseURL": "https://api.example.com/v1",
|
||||
"apiKey": "{env:API_KEY}"
|
||||
},
|
||||
"models": {
|
||||
"model-id": { "name": "Model Name" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MCP 配置
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"remote-server": {
|
||||
"type": "remote",
|
||||
"url": "https://example.com/mcp",
|
||||
"enabled": true
|
||||
},
|
||||
"local-server": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "my-mcp-command"],
|
||||
"enabled": true,
|
||||
"environment": { "KEY": "value" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 实现步骤
|
||||
|
||||
### Phase 1: 后端数据结构扩展
|
||||
|
||||
#### 1.1 AppType 枚举扩展
|
||||
**文件**: `src-tauri/src/app_config.rs`
|
||||
|
||||
```rust
|
||||
pub enum AppType {
|
||||
Claude,
|
||||
Codex,
|
||||
Gemini,
|
||||
OpenCode, // 新增
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.2 McpApps / SkillApps 扩展
|
||||
**文件**: `src-tauri/src/app_config.rs`
|
||||
|
||||
```rust
|
||||
pub struct McpApps {
|
||||
pub claude: bool,
|
||||
pub codex: bool,
|
||||
pub gemini: bool,
|
||||
pub opencode: bool, // 新增
|
||||
}
|
||||
|
||||
pub struct SkillApps {
|
||||
pub claude: bool,
|
||||
pub codex: bool,
|
||||
pub gemini: bool,
|
||||
pub opencode: bool, // 新增
|
||||
}
|
||||
```
|
||||
|
||||
#### 1.3 数据库 Schema 迁移
|
||||
**文件**: `src-tauri/src/database/schema.rs`
|
||||
|
||||
- `SCHEMA_VERSION` 递增
|
||||
- 添加迁移：
|
||||
```sql
|
||||
ALTER TABLE mcp_servers ADD COLUMN enabled_opencode BOOLEAN NOT NULL DEFAULT 0;
|
||||
ALTER TABLE skills ADD COLUMN enabled_opencode BOOLEAN NOT NULL DEFAULT 0;
|
||||
```
|
||||
|
||||
### Phase 2: OpenCode 供应商数据结构
|
||||
|
||||
#### 2.1 OpenCode 专属配置结构
|
||||
**文件**: `src-tauri/src/provider.rs`（或新建 `opencode_provider.rs`）
|
||||
|
||||
```rust
|
||||
/// OpenCode 供应商的 settings_config 结构
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct OpenCodeProviderConfig {
|
||||
/// AI SDK 包名，如 "@ai-sdk/openai-compatible"
|
||||
pub npm: String,
|
||||
/// 供应商选项
|
||||
pub options: OpenCodeProviderOptions,
|
||||
/// 模型定义
|
||||
pub models: HashMap<String, OpenCodeModel>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct OpenCodeProviderOptions {
|
||||
#[serde(rename = "baseURL", skip_serializing_if = "Option::is_none")]
|
||||
pub base_url: Option<String>,
|
||||
#[serde(rename = "apiKey", skip_serializing_if = "Option::is_none")]
|
||||
pub api_key: Option<String>,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub headers: Option<HashMap<String, String>>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct OpenCodeModel {
|
||||
pub name: String,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub limit: Option<OpenCodeModelLimit>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct OpenCodeModelLimit {
|
||||
pub context: Option<u64>,
|
||||
pub output: Option<u64>,
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: OpenCode Live 配置读写
|
||||
|
||||
#### 3.1 新建 OpenCode 配置模块
|
||||
**文件**: `src-tauri/src/opencode_config.rs`
|
||||
|
||||
核心功能：
|
||||
- `get_opencode_config_path()` → `~/.config/opencode/opencode.json`
|
||||
- `read_opencode_config()` → 读取整个配置文件
|
||||
- `write_opencode_config()` → 原子写入配置文件
|
||||
- `get_providers()` → 获取 `provider` 对象
|
||||
- `set_provider(id, config)` → 添加/更新供应商
|
||||
- `remove_provider(id)` → 删除供应商
|
||||
- `get_mcp_servers()` → 获取 `mcp` 对象
|
||||
- `set_mcp_server(id, config)` → 添加/更新 MCP 服务器
|
||||
- `remove_mcp_server(id)` → 删除 MCP 服务器
|
||||
|
||||
### Phase 4: MCP 同步模块
|
||||
|
||||
#### 4.1 新建 OpenCode MCP 同步
|
||||
**文件**: `src-tauri/src/mcp/opencode.rs`
|
||||
|
||||
```rust
|
||||
/// 同步所有 enabled_opencode=true 的服务器到 OpenCode 配置
|
||||
pub fn sync_enabled_to_opencode(config: &MultiAppConfig) -> Result<(), AppError>
|
||||
|
||||
/// 同步单个服务器
|
||||
pub fn sync_single_server_to_opencode(
|
||||
config: &MultiAppConfig,
|
||||
id: &str,
|
||||
server_spec: &Value
|
||||
) -> Result<(), AppError>
|
||||
|
||||
/// 从 OpenCode 配置移除服务器
|
||||
pub fn remove_server_from_opencode(id: &str) -> Result<(), AppError>
|
||||
|
||||
/// 从 OpenCode 配置导入服务器
|
||||
pub fn import_from_opencode(config: &mut MultiAppConfig) -> Result<usize, AppError>
|
||||
```
|
||||
|
||||
**格式转换**：
|
||||
| CC Switch 统一格式 | OpenCode 格式 |
|
||||
|-------------------|---------------|
|
||||
| `type: "stdio"` | `type: "local"` |
|
||||
| `command` + `args` | `command: [cmd, ...args]` |
|
||||
| `env` | `environment` |
|
||||
| `type: "sse"/"http"` | `type: "remote"` |
|
||||
| `url` | `url` |
|
||||
|
||||
### Phase 5: 供应商服务层
|
||||
|
||||
#### 5.1 OpenCode 供应商服务
|
||||
**文件**: `src-tauri/src/services/provider/opencode.rs`
|
||||
|
||||
核心方法：
|
||||
```rust
|
||||
/// 获取所有 OpenCode 供应商
|
||||
pub fn list(state: &AppState) -> Result<IndexMap<String, Provider>, AppError>
|
||||
|
||||
/// 添加供应商（同时写入 live 配置）
|
||||
pub fn add(state: &AppState, provider: Provider) -> Result<bool, AppError>
|
||||
|
||||
/// 更新供应商
|
||||
pub fn update(state: &AppState, provider: Provider) -> Result<bool, AppError>
|
||||
|
||||
/// 删除供应商（同时从 live 配置移除）
|
||||
pub fn delete(state: &AppState, id: &str) -> Result<(), AppError>
|
||||
|
||||
/// 从 live 配置导入供应商到数据库
|
||||
pub fn import_from_live(state: &AppState) -> Result<usize, AppError>
|
||||
```
|
||||
|
||||
**关键差异**：
|
||||
- 不需要 `switch()` 方法
|
||||
- 不需要 `is_current` 管理
|
||||
- `add()` 自动写入 live
|
||||
- `delete()` 自动从 live 移除
|
||||
|
||||
### Phase 6: Tauri 命令扩展
|
||||
|
||||
#### 6.1 更新现有命令
|
||||
**文件**: `src-tauri/src/commands/providers.rs`
|
||||
|
||||
- 所有命令支持 `app_type = "opencode"`
|
||||
- OpenCode 特定逻辑分支
|
||||
|
||||
#### 6.2 新增 OpenCode 专属命令（如需要）
|
||||
```rust
|
||||
#[tauri::command]
|
||||
pub async fn opencode_sync_all_providers(state: State<'_, AppState>) -> Result<(), AppError>
|
||||
```
|
||||
|
||||
### Phase 7: 前端类型定义
|
||||
|
||||
#### 7.1 TypeScript 类型扩展
|
||||
**文件**: `src/types.ts`
|
||||
|
||||
```typescript
|
||||
// AppId 扩展
|
||||
type AppId = "claude" | "codex" | "gemini" | "opencode";
|
||||
|
||||
// OpenCode 专属配置
|
||||
interface OpenCodeProviderConfig {
|
||||
npm: string; // AI SDK 包名
|
||||
options: {
|
||||
baseURL?: string;
|
||||
apiKey?: string;
|
||||
headers?: Record<string, string>;
|
||||
};
|
||||
models: Record<string, OpenCodeModel>;
|
||||
}
|
||||
|
||||
interface OpenCodeModel {
|
||||
name: string;
|
||||
limit?: {
|
||||
context?: number;
|
||||
output?: number;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
#### 7.2 MCP 应用状态扩展
|
||||
**文件**: `src/types.ts`
|
||||
|
||||
```typescript
|
||||
interface McpApps {
|
||||
claude: boolean;
|
||||
codex: boolean;
|
||||
gemini: boolean;
|
||||
opencode: boolean; // 新增
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 8: 前端预设配置
|
||||
|
||||
#### 8.1 新建 OpenCode 供应商预设
|
||||
**文件**: `src/config/opencodeProviderPresets.ts`
|
||||
|
||||
```typescript
|
||||
export const opencodeProviderPresets: ProviderPreset[] = [
|
||||
{
|
||||
name: "OpenAI",
|
||||
npmPackage: "@ai-sdk/openai",
|
||||
settingsConfig: {
|
||||
npm: "@ai-sdk/openai",
|
||||
options: { apiKey: "{env:OPENAI_API_KEY}" },
|
||||
models: {
|
||||
"gpt-4o": { name: "GPT-4o" },
|
||||
"gpt-4o-mini": { name: "GPT-4o Mini" },
|
||||
},
|
||||
},
|
||||
theme: { icon: "openai", iconColor: "#00A67E" },
|
||||
},
|
||||
{
|
||||
name: "Anthropic",
|
||||
npmPackage: "@ai-sdk/anthropic",
|
||||
settingsConfig: {
|
||||
npm: "@ai-sdk/anthropic",
|
||||
options: { apiKey: "{env:ANTHROPIC_API_KEY}" },
|
||||
models: {
|
||||
"claude-sonnet-4-20250514": { name: "Claude Sonnet 4" },
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "OpenAI Compatible",
|
||||
npmPackage: "@ai-sdk/openai-compatible",
|
||||
settingsConfig: {
|
||||
npm: "@ai-sdk/openai-compatible",
|
||||
options: {
|
||||
baseURL: "",
|
||||
apiKey: "{env:API_KEY}",
|
||||
},
|
||||
models: {},
|
||||
},
|
||||
isCustomTemplate: true,
|
||||
},
|
||||
// ... 更多预设
|
||||
];
|
||||
|
||||
// npm 包选项
|
||||
export const opencodeNpmPackages = [
|
||||
{ value: "@ai-sdk/openai", label: "OpenAI" },
|
||||
{ value: "@ai-sdk/anthropic", label: "Anthropic" },
|
||||
{ value: "@ai-sdk/openai-compatible", label: "OpenAI Compatible" },
|
||||
{ value: "@ai-sdk/google", label: "Google" },
|
||||
{ value: "@ai-sdk/azure", label: "Azure OpenAI" },
|
||||
{ value: "@ai-sdk/amazon-bedrock", label: "Amazon Bedrock" },
|
||||
// ... 更多选项
|
||||
];
|
||||
```
|
||||
|
||||
### Phase 9: 前端 UI 组件
|
||||
|
||||
#### 9.1 OpenCode 供应商表单
|
||||
**文件**: `src/components/providers/forms/OpenCodeFormFields.tsx`
|
||||
|
||||
新增字段：
|
||||
- npm 包选择器（下拉框 + 自定义输入）
|
||||
- options 编辑器（baseURL, apiKey, headers）
|
||||
- models 编辑器（动态添加/删除模型）
|
||||
|
||||
#### 9.2 供应商卡片按钮适配
|
||||
**文件**: `src/components/providers/ProviderActions.tsx`
|
||||
|
||||
```tsx
|
||||
// OpenCode 使用不同的主按钮
|
||||
if (appId === "opencode") {
|
||||
return (
|
||||
<Button onClick={onAdd}>
|
||||
{isInConfig ? t("provider.removeFromConfig") : t("provider.addToConfig")}
|
||||
</Button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### 9.3 隐藏 OpenCode 不需要的功能
|
||||
|
||||
在以下组件中检查 `appId !== "opencode"`：
|
||||
- 代理设置面板
|
||||
- 故障转移队列
|
||||
- 供应商切换逻辑
|
||||
|
||||
### Phase 10: 国际化
|
||||
|
||||
#### 10.1 新增翻译 Key
|
||||
**文件**: `src/locales/zh/translation.json` & `en/translation.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"app.opencode": "OpenCode",
|
||||
"provider.addToConfig": "添加到配置",
|
||||
"provider.removeFromConfig": "从配置移除",
|
||||
"provider.inConfig": "已添加",
|
||||
"provider.npmPackage": "AI SDK 包",
|
||||
"provider.models": "模型配置",
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键文件清单
|
||||
|
||||
### 后端（Rust）
|
||||
| 操作 | 文件路径 |
|
||||
|------|---------|
|
||||
| 修改 | `src-tauri/src/app_config.rs` |
|
||||
| 修改 | `src-tauri/src/database/schema.rs` |
|
||||
| 修改 | `src-tauri/src/database/dao/mcp.rs` |
|
||||
| 修改 | `src-tauri/src/database/dao/providers.rs` |
|
||||
| 修改 | `src-tauri/src/services/provider/mod.rs` |
|
||||
| 修改 | `src-tauri/src/services/mcp.rs` |
|
||||
| 修改 | `src-tauri/src/commands/providers.rs` |
|
||||
| 修改 | `src-tauri/src/commands/mcp.rs` |
|
||||
| 修改 | `src-tauri/src/mcp/mod.rs` |
|
||||
| 新建 | `src-tauri/src/opencode_config.rs` |
|
||||
| 新建 | `src-tauri/src/mcp/opencode.rs` |
|
||||
| 新建 | `src-tauri/src/services/provider/opencode.rs` |
|
||||
|
||||
### 前端（TypeScript/React）
|
||||
| 操作 | 文件路径 |
|
||||
|------|---------|
|
||||
| 修改 | `src/types.ts` |
|
||||
| 修改 | `src/lib/api/types.ts` |
|
||||
| 修改 | `src/lib/api/providers.ts` |
|
||||
| 修改 | `src/components/providers/ProviderActions.tsx` |
|
||||
| 修改 | `src/components/providers/ProviderCard.tsx` |
|
||||
| 修改 | `src/components/providers/AddProviderDialog.tsx` |
|
||||
| 修改 | `src/components/providers/forms/ProviderForm.tsx` |
|
||||
| 修改 | `src/App.tsx` |
|
||||
| 新建 | `src/config/opencodeProviderPresets.ts` |
|
||||
| 新建 | `src/components/providers/forms/OpenCodeFormFields.tsx` |
|
||||
|
||||
### 国际化
|
||||
| 操作 | 文件路径 |
|
||||
|------|---------|
|
||||
| 修改 | `src/locales/zh/translation.json` |
|
||||
| 修改 | `src/locales/en/translation.json` |
|
||||
| 修改 | `src/locales/ja/translation.json` |
|
||||
|
||||
---
|
||||
|
||||
## 验证计划
|
||||
|
||||
### 单元测试
|
||||
1. OpenCode 配置读写测试
|
||||
2. MCP 格式转换测试（stdio ↔ local, sse ↔ remote）
|
||||
3. 供应商 CRUD 操作测试
|
||||
|
||||
### 集成测试
|
||||
1. 添加 OpenCode 供应商 → 验证写入 `~/.config/opencode/opencode.json`
|
||||
2. 删除供应商 → 验证从配置文件移除
|
||||
3. MCP 同步测试 → 验证格式正确转换
|
||||
4. 从 live 配置导入 → 验证正确解析
|
||||
|
||||
### 手动测试
|
||||
1. UI 流程：添加预设 → 编辑 → 删除
|
||||
2. 切换应用 Tab → OpenCode 显示正确的 UI（无代理/故障转移）
|
||||
3. 托盘菜单正确显示 OpenCode 供应商
|
||||
4. 深链接导入 OpenCode 供应商
|
||||
|
||||
---
|
||||
|
||||
## 风险评估
|
||||
|
||||
1. **数据库迁移**：需要在升级时自动执行 `ALTER TABLE` 语句
|
||||
2. **配置文件冲突**：OpenCode 可能有自己的配置，需要合并而非覆盖
|
||||
3. **MCP 格式差异**：`stdio` → `local` 转换需要处理边界情况
|
||||
4. **UI 一致性**：OpenCode 的"添加/删除"模式需要与其他应用的"启用/切换"清晰区分
|
||||
|
||||
---
|
||||
|
||||
## 补充说明
|
||||
|
||||
### 托盘菜单特殊处理
|
||||
|
||||
由于 OpenCode 采用累加式管理，托盘菜单行为需要调整：
|
||||
|
||||
- **现有三应用**：托盘菜单显示 `CheckMenuItem`（单选，切换当前供应商）
|
||||
- **OpenCode**：显示当前所有启用的供应商（普通 MenuItem，无勾选逻辑），点击打开主界面
|
||||
|
||||
**修改文件**：`src-tauri/src/tray.rs`（`TRAY_SECTIONS` 常量）
|
||||
|
||||
### 数据库约束更新
|
||||
|
||||
`proxy_config` 表的 CHECK 约束需要扩展：
|
||||
```sql
|
||||
CHECK (app_type IN ('claude','codex','gemini','opencode'))
|
||||
```
|
||||
|
||||
### Settings 结构体扩展
|
||||
|
||||
**文件**：`src-tauri/src/settings.rs`
|
||||
|
||||
需要添加：
|
||||
- `current_provider_opencode: Option<String>` - 对 OpenCode 可能无意义，但保持结构一致
|
||||
- `opencode_config_dir: Option<String>` - 自定义配置目录
|
||||
@@ -1,165 +0,0 @@
|
||||
# CC Switch 代理功能使用指南
|
||||
|
||||
## 功能介绍
|
||||
|
||||
CC Switch 的代理功能是一个本地 HTTP 代理服务器，可以统一管理 Claude Code、Codex 和 Gemini CLI 的 API 请求。主要特性包括：
|
||||
|
||||
- **统一代理入口** - 所有 CLI 应用的请求通过本地代理转发
|
||||
- **自动故障转移** - 当前供应商故障时自动切换到备用供应商
|
||||
- **按应用控制** - 可独立控制每个应用是否启用代理
|
||||
- **配置保护** - 自动备份原始配置，停止代理时安全恢复
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 启动代理
|
||||
|
||||
在 CC Switch 主界面，点击右上角的 **Proxy** 按钮，可以看到代理控制面板。
|
||||
|
||||
点击 **启动代理** 按钮启动本地代理服务器。代理默认监听 `127.0.0.1:15721`。
|
||||
|
||||
### 2. 启用应用接管
|
||||
|
||||
代理启动后，你可以选择让哪些应用的请求通过代理：
|
||||
|
||||
- **Claude** - 接管 Claude Code 的 API 请求
|
||||
- **Codex** - 接管 Codex CLI 的 API 请求
|
||||
- **Gemini** - 接管 Gemini CLI 的 API 请求
|
||||
|
||||
点击对应应用的开关即可启用/禁用接管。
|
||||
|
||||
> **注意**：启用接管后，CC Switch 会自动修改对应应用的配置文件，将 API 端点指向本地代理。原始配置会被安全备份。
|
||||
|
||||
### 3. 正常使用 CLI
|
||||
|
||||
启用接管后，你可以正常使用各个 CLI 工具。所有请求都会经过 CC Switch 代理转发到配置的供应商。
|
||||
|
||||
### 4. 停止代理
|
||||
|
||||
当你不再需要代理时，点击 **停止代理** 按钮。CC Switch 会：
|
||||
|
||||
1. 安全关闭代理服务器
|
||||
2. 自动恢复所有应用的原始配置
|
||||
3. 清除代理状态
|
||||
|
||||
## 自动故障转移
|
||||
|
||||
### 工作原理
|
||||
|
||||
代理功能内置了智能故障转移机制：
|
||||
|
||||
1. **健康监控** - 实时监控每个供应商的响应状态
|
||||
2. **熔断器** - 连续失败 5 次后触发熔断，暂停使用该供应商
|
||||
3. **自动切换** - 熔断后自动切换到列表中的下一个供应商
|
||||
4. **自动恢复** - 30 秒后尝试恢复熔断的供应商
|
||||
|
||||
### 配置故障转移
|
||||
|
||||
要使用故障转移功能，你需要：
|
||||
|
||||
1. 在对应应用下添加多个供应商（至少 2 个）
|
||||
2. 启动代理并启用接管
|
||||
3. 当主供应商故障时，代理会自动切换到备用供应商
|
||||
|
||||
### 健康状态指示
|
||||
|
||||
在供应商卡片上可以看到健康状态指示：
|
||||
|
||||
- **绿色** - 供应商正常
|
||||
- **红色** - 供应商故障/熔断中
|
||||
- **灰色** - 未使用代理或未检测
|
||||
|
||||
## 按应用接管
|
||||
|
||||
v3.9.0 新增了按应用分粒度控制功能：
|
||||
|
||||
- 你可以只接管 Claude，而让 Codex 使用原始配置
|
||||
- 每个应用的接管状态独立管理
|
||||
- 启用/禁用不会影响其他应用
|
||||
|
||||
### 接管状态检测
|
||||
|
||||
CC Switch 通过检测配置备份来判断接管状态：
|
||||
|
||||
- 存在备份 = 已接管
|
||||
- 无备份 = 未接管
|
||||
|
||||
这确保了即使 CC Switch 异常退出，重新启动后也能正确识别状态。
|
||||
|
||||
## 代理配置
|
||||
|
||||
在代理面板中，你可以配置以下参数：
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| 监听地址 | 127.0.0.1 | 代理服务器绑定地址 |
|
||||
| 监听端口 | 15721 | 代理服务器端口 |
|
||||
| 最大重试 | 3 | 请求失败时的最大重试次数 |
|
||||
| 请求超时 | 120 秒 | 单个请求的超时时间 |
|
||||
| 启用日志 | 是 | 是否记录请求日志 |
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 代理启动失败，提示端口被占用？
|
||||
|
||||
A: 默认端口 15721 可能被其他程序占用。你可以：
|
||||
- 关闭占用该端口的程序
|
||||
- 在代理配置中修改端口号
|
||||
|
||||
### Q: 启用接管后 CLI 无法使用？
|
||||
|
||||
A: 请检查：
|
||||
1. 代理服务器是否正常运行（查看代理面板状态）
|
||||
2. 供应商配置是否正确（API Key 等）
|
||||
3. 网络连接是否正常
|
||||
|
||||
### Q: 如何恢复原始配置？
|
||||
|
||||
A: 点击 **停止代理** 按钮，CC Switch 会自动恢复所有应用的原始配置。
|
||||
|
||||
如果 CC Switch 异常退出，重新启动后会检测到之前的备份，你可以：
|
||||
- 点击停止代理来恢复配置
|
||||
- 或继续使用代理功能
|
||||
|
||||
### Q: 故障转移没有生效？
|
||||
|
||||
A: 请确保：
|
||||
1. 配置了至少 2 个供应商
|
||||
2. 代理已启动且接管已启用
|
||||
3. 故障转移只在代理模式下工作
|
||||
|
||||
### Q: 代理会影响性能吗？
|
||||
|
||||
A: 本地代理的延迟开销非常小（通常 < 1ms）。但如果启用了请求日志，在高频请求场景下可能会有少量性能影响。
|
||||
|
||||
## 技术细节
|
||||
|
||||
### 配置文件位置
|
||||
|
||||
启用接管后，CC Switch 会修改以下配置文件：
|
||||
|
||||
| 应用 | 配置文件 | 修改内容 |
|
||||
|------|----------|----------|
|
||||
| Claude | `~/.claude/settings.json` | `apiBaseUrl` 指向代理 |
|
||||
| Codex | `~/.codex/config.toml` | `[api] baseUrl` 指向代理 |
|
||||
| Gemini | `~/.gemini/.env` | `GEMINI_BASE_URL` 指向代理 |
|
||||
|
||||
原始配置备份在 CC Switch 数据库中，停止代理时自动恢复。
|
||||
|
||||
### 代理模式
|
||||
|
||||
代理服务器运行在接管模式下，会：
|
||||
|
||||
1. 接收来自 CLI 的 HTTPS 请求
|
||||
2. 根据当前供应商配置转发到真实 API 端点
|
||||
3. 返回响应给 CLI
|
||||
4. 记录请求日志和健康状态
|
||||
|
||||
### 数据库表
|
||||
|
||||
代理功能使用以下数据库表：
|
||||
|
||||
- `proxy_config` - 代理配置
|
||||
- `provider_health` - 供应商健康状态
|
||||
- `proxy_request_logs` - 请求日志
|
||||
- `circuit_breaker_config` - 熔断器配置
|
||||
- `proxy_live_backup` - Live 配置备份
|
||||
@@ -1,206 +0,0 @@
|
||||
# CC Switch v3.10.0
|
||||
|
||||
> OpenCode Support, Global Proxy, Claude Rectifier & Multi-App Experience Enhancements
|
||||
|
||||
**[中文版 →](release-note-v3.10.0-zh.md) | [日本語版 →](release-note-v3.10.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.10.0 introduces OpenCode support, becoming the fourth managed CLI application.
|
||||
This release also brings global proxy settings, Claude Rectifier (thinking signature fixer), enhanced health checks, per-provider configuration, and many other important features, along with comprehensive improvements to multi-app workflows and terminal experience.
|
||||
|
||||
**Release Date**: 2026-01-21
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- OpenCode Support: Full management of providers, MCP servers, and Skills with auto-import on first launch
|
||||
- Global Proxy: Configure a unified proxy for all outbound network requests
|
||||
- Claude Rectifier: Thinking signature fixer for better compatibility with third-party APIs
|
||||
- Enhanced Health Checks: Configurable prompts and CLI-compatible request format
|
||||
- Per-Provider Config: Persistent provider-specific configuration support
|
||||
- App Visibility Control: Freely show/hide apps with synchronized tray menu updates
|
||||
- Terminal Improvements: Provider-specific terminal buttons, fnm path support, cross-platform safe launch
|
||||
- WSL Tool Detection: Detect tool versions in WSL environment with security hardening
|
||||
|
||||
---
|
||||
|
||||
## Main Features
|
||||
|
||||
### OpenCode Support (New Fourth App)
|
||||
|
||||
- Complete OpenCode provider management: add, edit, switch, delete
|
||||
- MCP server management: unified architecture with Claude/Codex/Gemini
|
||||
- Skills support: OpenCode can also use Skills functionality
|
||||
- Auto-import on first launch: automatically imports existing OpenCode configuration when detected
|
||||
- Full internationalization: Chinese/English/Japanese support (#695)
|
||||
|
||||
### Global Proxy
|
||||
|
||||
- Configure a unified proxy for all outbound network requests (#596, thanks @yovinchen)
|
||||
- Supports HTTP/HTTPS proxy protocols
|
||||
- Suitable for network environments requiring proxy access to external APIs
|
||||
|
||||
### Claude Rectifier (Thinking Signature Fixer)
|
||||
|
||||
- Automatically fixes Claude API thinking signatures (#595, thanks @yovinchen)
|
||||
- Resolves incompatible thinking block formats returned by some third-party API gateways
|
||||
- Can be enabled/disabled in Advanced Settings
|
||||
|
||||
### Enhanced Health Checks
|
||||
|
||||
- Configurable custom prompts for streaming health checks (#623, thanks @yovinchen)
|
||||
- Supports CLI-compatible request format for better simulation of real usage scenarios
|
||||
- Improves fault detection accuracy
|
||||
|
||||
### Per-Provider Config
|
||||
|
||||
- Support for saving configuration separately for each provider (#663, thanks @yovinchen)
|
||||
- Persistent configuration: provider-specific settings retained after restart
|
||||
- Suitable for scenarios where different providers require different configurations
|
||||
|
||||
### App Visibility Control
|
||||
|
||||
- Freely show/hide any app (Gemini hidden by default)
|
||||
- Tray menu automatically syncs visibility settings
|
||||
- Hidden apps won't appear in the main interface or tray menu
|
||||
|
||||
### Takeover Compact Mode
|
||||
|
||||
- Automatically uses compact layout when 3 or more visible apps are displayed
|
||||
- Optimizes space utilization in multi-app scenarios
|
||||
|
||||
### Terminal Improvements
|
||||
|
||||
- Provider-specific terminal button: one-click to use current provider in terminal (#564, thanks @kkkman22)
|
||||
- `fnm` path support: automatically recognizes Node.js paths managed by fnm
|
||||
- Cross-platform safe launch: improved terminal launch logic for Windows/macOS/Linux
|
||||
|
||||
### WSL Tool Detection
|
||||
|
||||
- Detect tool versions in WSL environment (#627, thanks @yovinchen)
|
||||
- Added security hardening to prevent command injection risks
|
||||
|
||||
### Skills Preset Enhancements
|
||||
|
||||
- Added `baoyu-skills` preset repository
|
||||
- Automatically supplements missing default repositories for out-of-the-box experience
|
||||
|
||||
---
|
||||
|
||||
## Experience Improvements
|
||||
|
||||
- Keyboard shortcuts: Press `ESC` to quickly return/close panels (#670, thanks @xxk8)
|
||||
- Simplified proxy logs: cleaner and more readable output (#585, thanks @yovinchen)
|
||||
- Pricing editor UX: unified `FullScreenPanel` style
|
||||
- Advanced settings layout: Rectifier section moved below Failover for better logical flow
|
||||
- OpenRouter compatibility mode: disabled by default, UI toggle hidden (reduces clutter)
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Proxy & Failover
|
||||
|
||||
- Immediately switch to P1 when auto-failover is enabled (instead of waiting for next request)
|
||||
|
||||
### Provider Management
|
||||
|
||||
- Fixed stale data when reopening provider edit dialog after save (#654, thanks @YangYongAn)
|
||||
- Fixed baseUrl and apiKey state not resetting when switching presets
|
||||
- Fixed endpoint auto-selection state not persisting (#611, thanks @yovinchen)
|
||||
- Automatically apply default color when icon color is not set
|
||||
|
||||
### Deep Links
|
||||
|
||||
- Support multi-endpoint import (#597, thanks @yovinchen)
|
||||
- Prefer `GOOGLE_GEMINI_BASE_URL` over `GEMINI_BASE_URL`
|
||||
|
||||
### MCP
|
||||
|
||||
- Skip `cmd /c` wrapper for WSL target paths (#592, thanks @cxyfer)
|
||||
|
||||
### Usage Templates
|
||||
|
||||
- Added variable hints, fixed validation issues (#628, thanks @YangYongAn)
|
||||
- Prevent configuration leakage between providers
|
||||
- Usage block offset automatically adapts to action button width (#613, thanks @yovinchen)
|
||||
|
||||
### Gemini
|
||||
|
||||
- Convert timeout parameters to Gemini CLI format (#580, thanks @cxyfer)
|
||||
|
||||
### UI
|
||||
|
||||
- Fixed Select dropdown rendering issues in `FullScreenPanel`
|
||||
|
||||
---
|
||||
|
||||
## Notes & Considerations
|
||||
|
||||
- **OpenCode is a newly supported app**: OpenCode CLI must be installed first to use related features.
|
||||
- **Global proxy affects all outbound requests**: including usage queries, health checks, and other network operations.
|
||||
- **Rectifier is experimental**: can be disabled in Advanced Settings if issues occur.
|
||||
|
||||
---
|
||||
|
||||
## Special Thanks
|
||||
|
||||
Thanks to @yovinchen @YangYongAn @cxyfer @xxk8 @kkkman22 @Shuimo03 for their contributions to this release!
|
||||
Thanks to @libukai for designing the elegant failover-related UI!
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| System | Minimum Version | Architecture |
|
||||
| ------- | ------------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 or later | x64 |
|
||||
| macOS | macOS 10.15 (Catalina) or later | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ---------------------------------------------------- |
|
||||
| `CC-Switch-v3.10.0-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.10.0-Windows-Portable.zip` | Portable version, extract and run, no registry write |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ------------------------------------------------------------------ |
|
||||
| `CC-Switch-v3.10.0-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.10.0-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> **Note**: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" → "Privacy & Security" → click "Open Anyway", and it will open normally afterwards.
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
| Distribution | Recommended Format | Installation Method |
|
||||
| --------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
|
||||
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
|
||||
| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm` |
|
||||
| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` |
|
||||
| Arch Linux / Manjaro | `.AppImage` | Add execute permission and run directly, or use AUR |
|
||||
| Other distributions / Unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -1,206 +0,0 @@
|
||||
# CC Switch v3.10.0
|
||||
|
||||
> OpenCode サポート、グローバルプロキシ、Claude Rectifier とマルチアプリ体験の強化
|
||||
|
||||
**[中文版 →](release-note-v3.10.0-zh.md) | [English →](release-note-v3.10.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.10.0 では OpenCode サポートが追加され、4番目の管理対象 CLI アプリケーションとなりました。
|
||||
また、グローバルプロキシ設定、Claude Rectifier（thinking 署名修正機能）、ヘルスチェックの強化、プロバイダー別設定など、多くの重要な機能が追加され、マルチアプリワークフローとターミナル体験が全面的に改善されました。
|
||||
|
||||
**リリース日**: 2026-01-21
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- OpenCode サポート：プロバイダー、MCP サーバー、Skills の完全管理、初回起動時の自動インポート
|
||||
- グローバルプロキシ：すべての送信ネットワークリクエストに統一プロキシを設定
|
||||
- Claude Rectifier：thinking 署名修正機能、サードパーティ API との互換性向上
|
||||
- ヘルスチェック強化：カスタムプロンプト設定、CLI 互換リクエスト形式
|
||||
- プロバイダー別設定：プロバイダー固有の設定の永続化をサポート
|
||||
- アプリ表示制御：アプリの表示/非表示を自由に設定、トレイメニューと同期
|
||||
- ターミナル改善：プロバイダー専用ターミナルボタン、fnm パスサポート、クロスプラットフォーム安全起動
|
||||
- WSL ツール検出：WSL 環境でのツールバージョン検出とセキュリティ強化
|
||||
|
||||
---
|
||||
|
||||
## 主な機能
|
||||
|
||||
### OpenCode サポート（新しい4番目のアプリ）
|
||||
|
||||
- 完全な OpenCode プロバイダー管理：追加、編集、切り替え、削除
|
||||
- MCP サーバー管理：Claude/Codex/Gemini と統一されたアーキテクチャ
|
||||
- Skills サポート：OpenCode でも Skills 機能を使用可能
|
||||
- 初回起動時の自動インポート：既存の OpenCode 設定を検出すると自動的にインポート
|
||||
- 完全な国際化：中国語/英語/日本語サポート (#695)
|
||||
|
||||
### グローバルプロキシ
|
||||
|
||||
- すべての送信ネットワークリクエストに統一プロキシを設定 (#596、@yovinchen に感謝)
|
||||
- HTTP/HTTPS プロキシプロトコルをサポート
|
||||
- 外部 API へのプロキシアクセスが必要なネットワーク環境に適用
|
||||
|
||||
### Claude Rectifier（Thinking 署名修正機能）
|
||||
|
||||
- Claude API の thinking 署名を自動修正 (#595、@yovinchen に感謝)
|
||||
- 一部のサードパーティ API ゲートウェイが返す互換性のない thinking ブロック形式を解決
|
||||
- 詳細設定で有効/無効を切り替え可能
|
||||
|
||||
### ヘルスチェック強化
|
||||
|
||||
- ストリーミングヘルスチェック用のカスタムプロンプトを設定可能 (#623、@yovinchen に感謝)
|
||||
- CLI 互換リクエスト形式をサポートし、実際の使用シナリオをより良くシミュレート
|
||||
- 障害検出の精度を向上
|
||||
|
||||
### プロバイダー別設定
|
||||
|
||||
- 各プロバイダーごとに設定を個別に保存可能 (#663、@yovinchen に感謝)
|
||||
- 設定の永続化：再起動後もプロバイダー固有の設定を保持
|
||||
- 異なるプロバイダーに異なる設定が必要なシナリオに適用
|
||||
|
||||
### アプリ表示制御
|
||||
|
||||
- 任意のアプリを自由に表示/非表示（Gemini はデフォルトで非表示）
|
||||
- トレイメニューは表示設定と自動的に同期
|
||||
- 非表示のアプリはメインインターフェースとトレイメニューに表示されない
|
||||
|
||||
### Takeover コンパクトモード
|
||||
|
||||
- 3つ以上の表示アプリがある場合、自動的にコンパクトレイアウトを使用
|
||||
- マルチアプリシナリオでのスペース利用を最適化
|
||||
|
||||
### ターミナル改善
|
||||
|
||||
- プロバイダー専用ターミナルボタン：ワンクリックでターミナルで現在のプロバイダーを使用 (#564、@kkkman22 に感謝)
|
||||
- `fnm` パスサポート：fnm で管理された Node.js パスを自動認識
|
||||
- クロスプラットフォーム安全起動：Windows/macOS/Linux のターミナル起動ロジックを改善
|
||||
|
||||
### WSL ツール検出
|
||||
|
||||
- WSL 環境でツールバージョンを検出 (#627、@yovinchen に感謝)
|
||||
- コマンドインジェクションリスクを防ぐためのセキュリティ強化を追加
|
||||
|
||||
### Skills プリセット強化
|
||||
|
||||
- `baoyu-skills` プリセットリポジトリを追加
|
||||
- 不足しているデフォルトリポジトリを自動補完し、すぐに使える状態を確保
|
||||
|
||||
---
|
||||
|
||||
## 体験の改善
|
||||
|
||||
- キーボードショートカット：`ESC` を押してパネルをすばやく戻る/閉じる (#670、@xxk8 に感謝)
|
||||
- プロキシログの簡素化：より明確で読みやすい出力 (#585、@yovinchen に感謝)
|
||||
- 価格エディター UX：統一された `FullScreenPanel` スタイル
|
||||
- 詳細設定レイアウト：Rectifier セクションを Failover の下に移動し、論理的な流れを改善
|
||||
- OpenRouter 互換モード：デフォルトで無効、UI トグルを非表示（煩雑さを軽減）
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### プロキシとフェイルオーバー
|
||||
|
||||
- 自動フェイルオーバーが有効な場合、すぐに P1 に切り替え（次のリクエストを待たずに）
|
||||
|
||||
### プロバイダー管理
|
||||
|
||||
- 保存後にプロバイダー編集ダイアログを再度開いたときにデータが古い問題を修正 (#654、@YangYongAn に感謝)
|
||||
- プリセット切り替え時に baseUrl と apiKey の状態がリセットされない問題を修正
|
||||
- エンドポイント自動選択状態が永続化されない問題を修正 (#611、@yovinchen に感謝)
|
||||
- アイコンカラーが設定されていない場合、デフォルトカラーを自動適用
|
||||
|
||||
### ディープリンク
|
||||
|
||||
- マルチエンドポイントインポートをサポート (#597、@yovinchen に感謝)
|
||||
- `GEMINI_BASE_URL` より `GOOGLE_GEMINI_BASE_URL` を優先
|
||||
|
||||
### MCP
|
||||
|
||||
- WSL ターゲットパスの `cmd /c` ラッパーをスキップ (#592、@cxyfer に感謝)
|
||||
|
||||
### 使用量テンプレート
|
||||
|
||||
- 変数ヒントを追加、検証の問題を修正 (#628、@YangYongAn に感謝)
|
||||
- プロバイダー間での設定漏洩を防止
|
||||
- 使用量ブロックのオフセットがアクションボタンの幅に自動適応 (#613、@yovinchen に感謝)
|
||||
|
||||
### Gemini
|
||||
|
||||
- タイムアウトパラメータを Gemini CLI 形式に変換 (#580、@cxyfer に感謝)
|
||||
|
||||
### UI
|
||||
|
||||
- `FullScreenPanel` での Select ドロップダウンのレンダリング問題を修正
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
- **OpenCode は新しくサポートされたアプリです**：関連機能を使用するには、まず OpenCode CLI をインストールする必要があります。
|
||||
- **グローバルプロキシはすべての送信リクエストに影響します**：使用量クエリ、ヘルスチェックなどのネットワーク操作を含みます。
|
||||
- **Rectifier は実験的機能です**：問題が発生した場合は、詳細設定で無効にできます。
|
||||
|
||||
---
|
||||
|
||||
## 特別な感謝
|
||||
|
||||
@yovinchen @YangYongAn @cxyfer @xxk8 @kkkman22 @Shuimo03 の皆様、このリリースへの貢献に感謝します！
|
||||
@libukai 様、エレガントなフェイルオーバー関連 UI のデザインに感謝します！
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から適切なバージョンをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| システム | 最小バージョン | アーキテクチャ |
|
||||
| -------- | -------------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 10.15 (Catalina) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表参照 | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | ---------------------------------------------------- |
|
||||
| `CC-Switch-v3.10.0-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.10.0-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ書き込みなし |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.10.0-macOS.zip` | **推奨** - 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.10.0-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
> **注意**：作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元を確認できません」という警告が表示される場合があります。一度閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、その後は正常に開けます。
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
|
||||
| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm` |
|
||||
| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` |
|
||||
| Arch Linux / Manjaro | `.AppImage` | 実行権限を追加して直接実行、または AUR を使用 |
|
||||
| その他のディストリビューション / 不明 | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -1,206 +0,0 @@
|
||||
# CC Switch v3.10.0
|
||||
|
||||
> OpenCode 支持、全局代理、Claude Rectifier 与多应用体验增强
|
||||
|
||||
**[English →](release-note-v3.10.0-en.md) | [日本語版 →](release-note-v3.10.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.10.0 新增 OpenCode 支持，成为第四个受管理的 CLI 应用。
|
||||
同时带来全局代理设置、Claude Rectifier（thinking 签名修正器）、健康检查增强、按供应商配置等多项重要功能，并对多应用工作流与终端体验做了全面改进。
|
||||
|
||||
**发布日期**：2026-01-21
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- OpenCode 支持：供应商、MCP 服务器、Skills 全面管理，首次启动自动导入
|
||||
- 全局代理：为出站网络请求统一配置代理
|
||||
- Claude Rectifier：thinking 签名修正器，兼容更多第三方 API
|
||||
- 健康检查增强：可配置提示词、CLI 兼容请求
|
||||
- 按供应商配置：支持供应商特定配置的持久化
|
||||
- 应用可见性控制：自由显示/隐藏应用，托盘菜单同步更新
|
||||
- 终端改进：供应商专属终端按钮、fnm 路径支持、跨平台安全启动
|
||||
- WSL 工具检测：在 WSL 环境检测工具版本，并增加安全加固
|
||||
|
||||
---
|
||||
|
||||
## 主要功能
|
||||
|
||||
### OpenCode 支持（新增第四应用）
|
||||
|
||||
- 完整的 OpenCode 供应商管理：新增、编辑、切换、删除
|
||||
- MCP 服务器管理：与 Claude/Codex/Gemini 统一架构
|
||||
- Skills 支持：OpenCode 也可使用 Skills 功能
|
||||
- 首次启动自动导入：检测到已有 OpenCode 配置时自动导入
|
||||
- 完整国际化：中/英/日三语支持（#695）
|
||||
|
||||
### 全局代理（Global Proxy）
|
||||
|
||||
- 为所有出站网络请求配置统一代理（#596，感谢 @yovinchen）
|
||||
- 支持 HTTP/HTTPS 代理协议
|
||||
- 适用于需要代理访问外部 API 的网络环境
|
||||
|
||||
### Claude Rectifier（Thinking 签名修正器）
|
||||
|
||||
- 自动修正 Claude API 的 thinking 签名（#595，感谢 @yovinchen）
|
||||
- 解决部分第三方 API 网关返回的 thinking 块格式不兼容问题
|
||||
- 在高级设置中可开启/关闭
|
||||
|
||||
### 健康检查增强
|
||||
|
||||
- 可配置自定义提示词（prompt）用于流式健康检查（#623，感谢 @yovinchen）
|
||||
- 支持 CLI 兼容请求格式，更好地模拟真实使用场景
|
||||
- 提升故障检测的准确性
|
||||
|
||||
### 按供应商配置（Per-Provider Config）
|
||||
|
||||
- 支持为每个供应商单独保存配置（#663，感谢 @yovinchen）
|
||||
- 配置持久化：重启后保留供应商专属设置
|
||||
- 适用于不同供应商需要不同配置的场景
|
||||
|
||||
### 应用可见性控制
|
||||
|
||||
- 自由显示/隐藏任意应用（Gemini 默认隐藏）
|
||||
- 托盘菜单自动同步可见性设置
|
||||
- 隐藏的应用不会出现在主界面和托盘菜单中
|
||||
|
||||
### Takeover Compact Mode
|
||||
|
||||
- 当显示 3 个及以上可见应用时，自动使用紧凑布局
|
||||
- 优化多应用场景下的空间利用
|
||||
|
||||
### 终端改进
|
||||
|
||||
- 供应商专属终端按钮：一键在终端中使用当前供应商（#564，感谢 @kkkman22）
|
||||
- `fnm` 路径支持：自动识别 fnm 管理的 Node.js 路径
|
||||
- 跨平台安全启动：改进 Windows/macOS/Linux 的终端启动逻辑
|
||||
|
||||
### WSL 工具检测
|
||||
|
||||
- 在 WSL 环境中检测工具版本（#627，感谢 @yovinchen）
|
||||
- 增加安全加固，防止命令注入风险
|
||||
|
||||
### Skills 预设增强
|
||||
|
||||
- 新增 `baoyu-skills` 预设仓库
|
||||
- 自动补充缺失的默认仓库，确保开箱即用
|
||||
|
||||
---
|
||||
|
||||
## 体验优化
|
||||
|
||||
- 键盘快捷键：按 `ESC` 快速返回/关闭面板（#670，感谢 @xxk8）
|
||||
- 代理日志简化：输出更清晰易读（#585，感谢 @yovinchen）
|
||||
- 定价编辑器 UX：统一使用 `FullScreenPanel` 风格
|
||||
- 高级设置布局：Rectifier 区块移至 Failover 下方，逻辑更顺畅
|
||||
- OpenRouter 兼容模式：默认禁用，UI 开关隐藏（减少干扰）
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 代理与故障切换
|
||||
|
||||
- 启用自动故障切换时立即切换到 P1（而非等待下次请求）
|
||||
|
||||
### 供应商管理
|
||||
|
||||
- 修复供应商编辑对话框保存后重新打开时数据过时的问题（#654，感谢 @YangYongAn）
|
||||
- 修复切换预设时 baseUrl 和 apiKey 状态未重置的问题
|
||||
- 修复端点自动选择状态未持久化的问题（#611，感谢 @yovinchen）
|
||||
- 未设置图标颜色时自动应用默认颜色
|
||||
|
||||
### 深链接
|
||||
|
||||
- 支持多端点导入（#597，感谢 @yovinchen）
|
||||
- 优先使用 `GOOGLE_GEMINI_BASE_URL` 而非 `GEMINI_BASE_URL`
|
||||
|
||||
### MCP
|
||||
|
||||
- WSL 目标路径跳过 `cmd /c` 包裹（#592，感谢 @cxyfer）
|
||||
|
||||
### 用量模板
|
||||
|
||||
- 新增变量提示，修复验证问题（#628，感谢 @YangYongAn）
|
||||
- 防止配置在供应商之间泄漏
|
||||
- 用量区块偏移量根据操作按钮宽度自动适应（#613，感谢 @yovinchen）
|
||||
|
||||
### Gemini
|
||||
|
||||
- 超时参数转换为 Gemini CLI 格式（#580，感谢 @cxyfer）
|
||||
|
||||
### UI
|
||||
|
||||
- 修复 `FullScreenPanel` 中 Select 下拉框渲染问题
|
||||
|
||||
---
|
||||
|
||||
## 说明与注意事项
|
||||
|
||||
- **OpenCode 为新支持的应用**：需要先安装 OpenCode CLI 才能使用相关功能。
|
||||
- **全局代理会影响所有出站请求**：包括用量查询、健康检查等网络操作。
|
||||
- **Rectifier 功能为实验性**：如遇问题可在高级设置中关闭。
|
||||
|
||||
---
|
||||
|
||||
## 特别感谢
|
||||
|
||||
感谢 @yovinchen @YangYongAn @cxyfer @xxk8 @kkkman22 @Shuimo03 为本版本做出的贡献！
|
||||
感谢 @libukai 设计的故障转移相关 UI，非常优雅！
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 系统 | 最低版本 | 架构 |
|
||||
| ------- | ----------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 及以上 | x64 |
|
||||
| macOS | macOS 10.15 (Catalina) 及以上 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 见下表 | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.10.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.10.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.10.0-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
|
||||
| `CC-Switch-v3.10.0-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
|
||||
| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm` |
|
||||
| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` |
|
||||
| Arch Linux / Manjaro | `.AppImage` | 添加执行权限后直接运行，或使用 AUR |
|
||||
| 其他发行版 / 不确定 | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -1,249 +0,0 @@
|
||||
## Major architecture refactoring with enhanced config sync and data protection
|
||||
|
||||
**[中文更新说明 Chinese Documentation →](https://github.com/farion1231/cc-switch/blob/main/docs/release-note-v3.6.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## What's New
|
||||
|
||||
### Edit Mode & Provider Management
|
||||
|
||||
- **Provider Duplication** - Quickly duplicate existing provider configurations to create variants with one click
|
||||
- **Manual Sorting** - Drag and drop to reorder providers, with visual push effect animations. Thanks to @ZyphrZero
|
||||
- **Edit Mode Toggle** - Show/hide drag handles to optimize editing experience
|
||||
|
||||
### Custom Endpoint Management
|
||||
|
||||
- **Multi-Endpoint Configuration** - Support for aggregator providers with multiple API endpoints
|
||||
- **Endpoint Input Visibility** - Shows endpoint field for all non-official providers automatically
|
||||
|
||||
### Usage Query Enhancements
|
||||
|
||||
- **Auto-Refresh Interval** - Configure periodic automatic usage queries with customizable intervals
|
||||
- **Test Script API** - Validate JavaScript usage query scripts before execution
|
||||
- **Enhanced Templates** - Custom blank templates with access token and user ID parameter support
|
||||
Thanks to @Sirhexs
|
||||
|
||||
### Custom Configuration Directory (Cloud Sync)
|
||||
|
||||
- **Customizable Storage Location** - Customize CC Switch's configuration storage directory
|
||||
- **Cloud Sync Support** - Point to cloud sync folders (Dropbox, OneDrive, iCloud Drive, etc.) to enable automatic config synchronization across devices
|
||||
- **Independent Management** - Managed via Tauri Store for better isolation and reliability
|
||||
Thanks to @ZyphrZero
|
||||
|
||||
### Configuration Directory Switching (WSL Support)
|
||||
|
||||
- **Auto-Sync on Directory Change** - When switching Claude/Codex config directories (e.g., WSL environment), automatically sync current provider to the new directory without manual operation
|
||||
- **Post-Change Sync Utility** - Unified `postChangeSync.ts` utility for graceful error handling without blocking main flow
|
||||
- **Import Config Auto-Sync** - Automatically sync after config import to ensure immediate effectiveness
|
||||
- **Smart Conflict Resolution** - Distinguishes "fully successful" and "partially successful" states for precise user feedback
|
||||
|
||||
### Configuration Editor Improvements
|
||||
|
||||
- **JSON Format Button** - One-click JSON formatting in configuration editors
|
||||
- **Real-Time TOML Validation** - Live syntax validation for Codex configuration with error highlighting
|
||||
|
||||
### Load Live Config When Editing
|
||||
|
||||
- **Protect Manual Modifications** - When editing the currently active provider, prioritize displaying the actual effective configuration from live files
|
||||
- **Dual-Source Strategy** - Automatically loads from live config for active provider, SSOT for inactive ones
|
||||
|
||||
### Claude Configuration Data Structure Enhancements
|
||||
|
||||
- **Granular Model Configuration** - Migrated from dual-key to quad-key system for better model tier differentiation
|
||||
- New fields: `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_MODEL`
|
||||
- Replaces legacy `ANTHROPIC_SMALL_FAST_MODEL` with automatic migration
|
||||
- Backend normalizes old configs on first read/write with smart fallback chain
|
||||
- UI expanded from 2 to 4 model input fields with intelligent defaults
|
||||
- **ANTHROPIC_API_KEY Support** - Providers can now use `ANTHROPIC_API_KEY` field in addition to `ANTHROPIC_AUTH_TOKEN`
|
||||
- **Template Variable System** - Support for dynamic configuration replacement (e.g., KAT-Coder's `ENDPOINT_ID` parameter)
|
||||
- **Endpoint Candidates** - Predefined endpoint list for speed testing and endpoint management
|
||||
- **Visual Theme Configuration** - Custom icons and colors for provider cards
|
||||
|
||||
### Updated Provider Models
|
||||
|
||||
- **Kimi k2** - Updated to latest `kimi-k2-thinking` model
|
||||
|
||||
### New Provider Presets
|
||||
|
||||
Added 5 new provider presets:
|
||||
|
||||
- **DMXAPI** - Multi-model aggregation service
|
||||
- **Azure Codex** - Microsoft Azure OpenAI endpoint
|
||||
- **AnyRouter** - None-profit routing service
|
||||
- **AiHubMix** - Multi-model aggregation service
|
||||
- **MiniMax** - Open source AI model provider
|
||||
|
||||
### Partner Promotion Mechanism
|
||||
|
||||
- Support for ecosystem partner promotion (Zhipu GLM Z.ai)
|
||||
- Sponsored banner integration in README
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
### Configuration & Sync
|
||||
|
||||
- **Unified Error Handling** - AppError with internationalized error messages throughout backend
|
||||
- **Fixed apiKeyUrl Priority** - Correct priority order for API key URL resolution
|
||||
- **Fixed MCP Sync Issues** - Resolved sync-to-other-side functionality failures
|
||||
- **Import Config Sync** - Fixed sync issues after configuration import
|
||||
- **Config Error Handling** - Force exit on config error to prevent silent fallback and data loss
|
||||
|
||||
### UI/UX Enhancements
|
||||
|
||||
- **Unique Provider Icons** - Each provider card now has unique icons and color identification
|
||||
- **Unified Border System** - Consistent border design across all components
|
||||
- **Drag Interaction** - Push effect animation and improved drag handle icons
|
||||
- **Enhanced Visual Feedback** - Better current provider visual indication
|
||||
- **Dialog Standardization** - Unified dialog sizes and layout consistency
|
||||
- **Form Improvements** - Optimized model placeholders, simplified provider hints, category-specific hints
|
||||
- **Usage Display Inline** - Usage info moved next to enable button for better space utilization
|
||||
|
||||
### Complete Internationalization
|
||||
|
||||
- **Error Messages i18n** - All backend error messages support Chinese/English
|
||||
- **Tray Menu i18n** - System tray menu fully internationalized
|
||||
- **UI Components i18n** - 100% coverage across all user-facing components
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- Fixed `apiKeyUrl` priority issue
|
||||
- Fixed MCP sync-to-other-side functionality failure
|
||||
- Fixed sync issues after config import
|
||||
- Fixed Codex API Key auto-sync
|
||||
- Fixed endpoint speed test functionality
|
||||
- Fixed provider duplicate insertion position (now inserts next to original)
|
||||
- Fixed custom endpoint preservation in edit mode
|
||||
- Prevent silent fallback and data loss on config error
|
||||
|
||||
### Usage Query
|
||||
|
||||
- Fixed auto-query interval timing issue
|
||||
- Ensured 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
|
||||
|
||||
### Startup Issues
|
||||
|
||||
- Force exit on config error (no silent fallback)
|
||||
- Eliminated code duplication causing initialization errors
|
||||
|
||||
---
|
||||
|
||||
## Architecture Refactoring
|
||||
|
||||
### Backend (Rust) - 5 Phase Refactoring
|
||||
|
||||
1. **Phase 1**: Unified error handling (`AppError` + i18n error messages)
|
||||
2. **Phase 2**: Command layer split by domain (`commands/{provider,mcp,config,settings,plugin,misc}.rs`)
|
||||
3. **Phase 3**: Integration tests and transaction mechanism (config snapshot + failure rollback)
|
||||
4. **Phase 4**: Extracted Service layer (`services/{provider,mcp,config,speedtest}.rs`)
|
||||
5. **Phase 5**: Concurrency optimization (`RwLock` instead of `Mutex`, scoped guard to avoid deadlock)
|
||||
|
||||
### Frontend (React + TypeScript) - 4 Stage Refactoring
|
||||
|
||||
1. **Stage 1**: Test infrastructure (vitest + MSW + @testing-library/react)
|
||||
2. **Stage 2**: Extracted custom hooks (`useProviderActions`, `useMcpActions`, `useSettings`, `useImportExport`, etc.)
|
||||
3. **Stage 3**: Component splitting and business logic extraction
|
||||
4. **Stage 4**: Code cleanup and formatting unification
|
||||
|
||||
### Testing System
|
||||
|
||||
- **Hooks Unit Tests** - 100% coverage for all custom hooks
|
||||
- **Integration Tests** - Coverage for key processes (App, SettingsDialog, MCP Panel)
|
||||
- **MSW Mocking** - Backend API mocking to ensure test independence
|
||||
- **Test Infrastructure** - vitest + MSW + @testing-library/react
|
||||
|
||||
### Code Quality
|
||||
|
||||
- **Unified Parameter Format** - All Tauri commands migrated to camelCase (Tauri 2 specification)
|
||||
- **Semantic Clarity** - `AppType` renamed to `AppId` for better semantics
|
||||
- **Centralized Parsing** - Unified `app` parameter parsing with `FromStr` trait
|
||||
- **DRY Violations Cleanup** - Eliminated code duplication throughout codebase
|
||||
- **Dead Code Removal** - Removed unused `missing_param` helper, deprecated `tauri-api.ts`, redundant `KimiModelSelector`
|
||||
|
||||
---
|
||||
|
||||
## Internal Optimizations (User Transparent)
|
||||
|
||||
### Removed Legacy Migration Logic
|
||||
|
||||
v3.6.0 removed v1 config auto-migration and copy file scanning logic:
|
||||
|
||||
- **Impact**: Improved startup performance, cleaner codebase
|
||||
- **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.0
|
||||
|
||||
### 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**
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### macOS
|
||||
|
||||
**Via Homebrew (Recommended):**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
**Manual Download:**
|
||||
|
||||
- Download `CC-Switch-v3.6.0-macOS.zip` from [Assets](#assets) below
|
||||
|
||||
> **Note**: Due to lack of Apple Developer account, you may see "unidentified developer" warning. Go to System Settings → Privacy & Security → Click "Open Anyway"
|
||||
|
||||
### Windows
|
||||
|
||||
- **Installer**: `CC-Switch-v3.6.0-Windows.msi`
|
||||
- **Portable**: `CC-Switch-v3.6.0-Windows-Portable.zip`
|
||||
|
||||
### Linux
|
||||
|
||||
- **AppImage**: `CC-Switch-v3.6.0-Linux.AppImage`
|
||||
- **Debian**: `CC-Switch-v3.6.0-Linux.deb`
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- [中文文档 (Chinese)](https://github.com/farion1231/cc-switch/blob/main/README_ZH.md)
|
||||
- [English Documentation](https://github.com/farion1231/cc-switch/blob/main/README.md)
|
||||
- [完整更新日志 (Full Changelog)](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Special thanks to **Zhipu AI** for sponsoring this project with their GLM CODING PLAN!
|
||||
|
||||
---
|
||||
|
||||
**Full Changelog**: https://github.com/farion1231/cc-switch/compare/v3.5.1...v3.6.0
|
||||
@@ -1,249 +0,0 @@
|
||||
# CC Switch v3.6.0
|
||||
|
||||
> 全栈架构重构，增强配置同步与数据保护
|
||||
|
||||
**[English Version →](../release-note-v3.6.0.md)**
|
||||
|
||||
---
|
||||
|
||||
## 新增功能
|
||||
|
||||
### 编辑模式与供应商管理
|
||||
|
||||
- **供应商复制功能** - 一键快速复制现有供应商配置，轻松创建变体配置
|
||||
- **手动排序功能** - 通过拖拽对供应商进行重新排序，带有视觉推送效果动画
|
||||
- **编辑模式切换** - 显示/隐藏拖拽手柄，优化编辑体验
|
||||
|
||||
### 自定义端点管理
|
||||
|
||||
- **多端点配置** - 支持聚合类供应商的多 API 端点配置
|
||||
- **端点输入可见性** - 为所有非官方供应商自动显示端点字段
|
||||
|
||||
### 自定义配置目录（云同步）
|
||||
|
||||
- **自定义存储位置** - 自定义 CC Switch 的配置存储目录
|
||||
- **云同步支持** - 指定到云同步文件夹（Dropbox、OneDrive、iCloud Drive、坚果云等）即可实现跨设备配置自动同步
|
||||
- **独立管理** - 通过 Tauri Store 管理，更好的隔离性和可靠性
|
||||
|
||||
### 使用量查询增强
|
||||
|
||||
- **自动刷新间隔** - 配置定时自动使用量查询，支持自定义间隔时间
|
||||
- **测试脚本 API** - 在执行前验证 JavaScript 使用量查询脚本
|
||||
- **增强模板系统** - 自定义空白模板，支持 access token 和 user ID 参数
|
||||
|
||||
### 配置目录切换（WSL 支持）
|
||||
|
||||
- **目录变更自动同步** - 切换 Claude/Codex 配置目录（如 WSL 环境）时，自动同步当前供应商到新目录，无需手动操作
|
||||
- **后置同步工具** - 统一的 `postChangeSync.ts` 工具，优雅处理错误而不阻塞主流程
|
||||
- **导入配置自动同步** - 配置导入后自动同步，确保立即生效
|
||||
- **智能冲突解决** - 区分"完全成功"和"部分成功"状态，提供精确的用户反馈
|
||||
|
||||
### 配置编辑器改进
|
||||
|
||||
- **JSON 格式化按钮** - 配置编辑器中一键 JSON 格式化
|
||||
- **实时 TOML 验证** - Codex 配置的实时语法验证，带有错误高亮
|
||||
|
||||
### 编辑时加载 Live 配置
|
||||
|
||||
- **保护手动修改** - 编辑当前激活的供应商时，优先显示来自 live 文件的实际生效配置
|
||||
- **双源策略** - 活动供应商自动从 live 配置加载，非活动供应商从 SSOT 加载
|
||||
|
||||
### Claude 配置数据结构增强
|
||||
|
||||
- **细粒度模型配置** - 从双键系统升级到四键系统，以匹配官方最新数据结构
|
||||
- 新增字段：`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_MODEL`
|
||||
- 替换旧版 `ANTHROPIC_SMALL_FAST_MODEL`，支持自动迁移
|
||||
- 后端在首次读写时自动规范化旧配置，带有智能回退链
|
||||
- UI 从 2 个模型输入字段扩展到 4 个，具有智能默认值
|
||||
- **ANTHROPIC_API_KEY 支持** - 供应商现可使用 `ANTHROPIC_API_KEY` 字段（除 `ANTHROPIC_AUTH_TOKEN` 外）
|
||||
- **模板变量系统** - 支持动态配置替换（如 KAT-Coder 的 `ENDPOINT_ID` 参数）
|
||||
- **端点候选列表** - 预定义端点列表，用于速度测试和端点管理
|
||||
- **视觉主题配置** - 供应商卡片自定义图标和颜色
|
||||
|
||||
### 供应商模型更新
|
||||
|
||||
- **Kimi k2** - 更新到最新的 `kimi-k2-thinking` 模型
|
||||
|
||||
### 新增供应商预设
|
||||
|
||||
新增 5 个供应商预设：
|
||||
|
||||
- **DMXAPI** - 多模型聚合服务
|
||||
- **Azure Codex** - 微软 Azure OpenAI 端点
|
||||
- **AnyRouter** - API 路由服务
|
||||
- **AiHubMix** - AI 模型集合
|
||||
- **MiniMax** - 国产 AI 模型提供商
|
||||
|
||||
### 合作伙伴推广机制
|
||||
|
||||
- 支持生态合作伙伴推广（智谱 GLM Z.ai）
|
||||
- README 中集成赞助商横幅
|
||||
|
||||
---
|
||||
|
||||
## 改进优化
|
||||
|
||||
### 配置与同步
|
||||
|
||||
- **统一错误处理** - 后端全面使用 AppError 与国际化错误消息
|
||||
- **修复 apiKeyUrl 优先级** - 修正 API key URL 解析的优先级顺序
|
||||
- **修复 MCP 同步问题** - 解决同步到另一端功能失效的问题
|
||||
- **导入配置同步** - 修复配置导入后的同步问题
|
||||
- **配置错误处理** - 配置错误时强制退出，防止静默回退和数据丢失
|
||||
|
||||
### UI/UX 增强
|
||||
|
||||
- **独特的供应商图标** - 每个供应商卡片现在都有独特的图标和颜色识别
|
||||
- **统一边框系统** - 所有组件采用一致的边框设计
|
||||
- **拖拽交互** - 推送效果动画和改进的拖拽手柄图标
|
||||
- **增强视觉反馈** - 更好的当前供应商视觉指示
|
||||
- **对话框标准化** - 统一的对话框尺寸和布局一致性
|
||||
- **表单改进** - 优化模型占位符，简化供应商提示，分类特定提示
|
||||
- **使用量内联显示** - 使用量信息移至启用按钮旁边，更好地利用空间
|
||||
|
||||
### 完整国际化
|
||||
|
||||
- **错误消息国际化** - 所有后端错误消息支持中英文
|
||||
- **托盘菜单国际化** - 系统托盘菜单完全国际化
|
||||
- **UI 组件国际化** - 所有面向用户的组件 100% 覆盖
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 配置管理
|
||||
|
||||
- 修复 `apiKeyUrl` 优先级问题
|
||||
- 修复 MCP 同步到另一端功能失效
|
||||
- 修复配置导入后的同步问题
|
||||
- 修复 Codex API Key 自动同步
|
||||
- 修复端点速度测试功能
|
||||
- 修复供应商复制插入位置（现在插入到原供应商旁边）
|
||||
- 修复编辑模式下自定义端点保留问题
|
||||
- 防止配置错误时的静默回退和数据丢失
|
||||
|
||||
### 使用量查询
|
||||
|
||||
- 修复自动查询间隔时间问题
|
||||
- 确保刷新按钮点击时显示加载动画
|
||||
|
||||
### UI 问题
|
||||
|
||||
- 修复名称冲突错误（`get_init_error` 命令）
|
||||
- 修复保存成功后语言设置回滚
|
||||
- 修复语言切换状态重置（依赖循环）
|
||||
- 修复编辑模式按钮对齐
|
||||
|
||||
### 启动问题
|
||||
|
||||
- 配置错误时强制退出（不再静默回退）
|
||||
- 消除导致初始化错误的代码重复
|
||||
|
||||
---
|
||||
|
||||
## 架构重构
|
||||
|
||||
### 后端（Rust）- 5 阶段重构
|
||||
|
||||
1. **阶段 1**：统一错误处理（`AppError` + 国际化错误消息）
|
||||
2. **阶段 2**：命令层按领域拆分（`commands/{provider,mcp,config,settings,plugin,misc}.rs`）
|
||||
3. **阶段 3**：集成测试和事务机制（配置快照 + 失败回滚）
|
||||
4. **阶段 4**：提取 Service 层（`services/{provider,mcp,config,speedtest}.rs`）
|
||||
5. **阶段 5**：并发优化（`RwLock` 替代 `Mutex`，作用域 guard 避免死锁）
|
||||
|
||||
### 前端（React + TypeScript）- 4 阶段重构
|
||||
|
||||
1. **阶段 1**：测试基础设施（vitest + MSW + @testing-library/react）
|
||||
2. **阶段 2**：提取自定义 hooks（`useProviderActions`、`useMcpActions`、`useSettings`、`useImportExport` 等）
|
||||
3. **阶段 3**：组件拆分和业务逻辑提取
|
||||
4. **阶段 4**：代码清理和格式化统一
|
||||
|
||||
### 测试体系
|
||||
|
||||
- **Hooks 单元测试** - 所有自定义 hooks 100% 覆盖
|
||||
- **集成测试** - 关键流程覆盖（App、SettingsDialog、MCP 面板）
|
||||
- **MSW 模拟** - 后端 API 模拟确保测试独立性
|
||||
- **测试基础设施** - vitest + MSW + @testing-library/react
|
||||
|
||||
### 代码质量
|
||||
|
||||
- **统一参数格式** - 所有 Tauri 命令迁移到 camelCase（Tauri 2 规范）
|
||||
- **语义清晰** - `AppType` 重命名为 `AppId` 以获得更好的语义
|
||||
- **集中解析** - 使用 `FromStr` trait 统一 `app` 参数解析
|
||||
- **DRY 违规清理** - 消除整个代码库中的代码重复
|
||||
- **死代码移除** - 移除未使用的 `missing_param` 辅助函数、废弃的 `tauri-api.ts`、冗余的 `KimiModelSelector`
|
||||
|
||||
---
|
||||
|
||||
## 内部优化（用户无感知）
|
||||
|
||||
### 移除遗留迁移逻辑
|
||||
|
||||
v3.6.0 移除了 v1 配置自动迁移和副本文件扫描逻辑：
|
||||
|
||||
- **影响**：提升启动性能，代码更简洁
|
||||
- **兼容性**：v2 格式配置完全兼容，无需任何操作
|
||||
- **注意**：从 v3.1.0 或更早版本升级的用户，请先升级到 v3.2.x 或 v3.5.x 进行一次性迁移，然后再升级到 v3.6.0
|
||||
|
||||
### 命令参数标准化
|
||||
|
||||
后端统一使用 `app` 参数（取值：`claude` 或 `codex`）：
|
||||
|
||||
- **影响**：代码更规范，错误提示更友好
|
||||
- **兼容性**：前端已完全适配，用户无需关心此变更
|
||||
|
||||
---
|
||||
|
||||
## 依赖更新
|
||||
|
||||
- 更新到 **Tauri 2.8.x**
|
||||
- 更新到 **TailwindCSS 4.x**
|
||||
- 更新到 **TanStack Query v5.90.x**
|
||||
- 保持 **React 18.2.x** 和 **TypeScript 5.3.x**
|
||||
|
||||
---
|
||||
|
||||
## 安装方式
|
||||
|
||||
### macOS
|
||||
|
||||
**通过 Homebrew 安装（推荐）：**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
**手动下载：**
|
||||
|
||||
- 从下方 [Assets](#assets) 下载 `CC-Switch-v3.6.0-macOS.zip`
|
||||
|
||||
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告。请前往"系统设置" → "隐私与安全性" → 点击"仍要打开"
|
||||
|
||||
### Windows
|
||||
|
||||
- **安装包**：`CC-Switch-v3.6.0-Windows.msi`
|
||||
- **便携版**：`CC-Switch-v3.6.0-Windows-Portable.zip`
|
||||
|
||||
### Linux
|
||||
|
||||
- **AppImage**：`CC-Switch-v3.6.0-Linux.AppImage`
|
||||
- **Debian**：`CC-Switch-v3.6.0-Linux.deb`
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
- [中文文档](https://github.com/farion1231/cc-switch/blob/main/README_ZH.md)
|
||||
- [English Documentation](https://github.com/farion1231/cc-switch/blob/main/README.md)
|
||||
- [完整更新日志](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
特别感谢**智谱 AI** 通过 GLM CODING PLAN 赞助本项目！
|
||||
|
||||
---
|
||||
|
||||
**完整变更记录**: https://github.com/farion1231/cc-switch/compare/v3.5.1...v3.6.0
|
||||
@@ -1,391 +0,0 @@
|
||||
# CC Switch v3.6.1
|
||||
|
||||
> Stability improvements and user experience optimization (based on v3.6.0)
|
||||
|
||||
**[中文更新说明 Chinese Documentation →](https://github.com/farion1231/cc-switch/blob/main/docs/release-note-v3.6.1-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 📦 What's New in v3.6.1 (2025-11-10)
|
||||
|
||||
This release focuses on **user experience optimization** and **configuration parsing robustness**, fixing several critical bugs and enhancing the usage query system.
|
||||
|
||||
### ✨ New Features
|
||||
|
||||
#### Usage Query System Enhancements
|
||||
|
||||
- **Credential Decoupling** - Usage queries can now use independent API Key and Base URL, no longer dependent on provider configuration
|
||||
- Support for different query endpoints and authentication methods
|
||||
- Automatically displays credential input fields based on template type
|
||||
- General template: API Key + Base URL
|
||||
- NewAPI template: Base URL + Access Token + User ID
|
||||
- Custom template: Fully customizable
|
||||
- **UI Component Upgrade** - Replaced native checkbox with shadcn/ui Switch component for modern experience
|
||||
- **Form Unification** - Unified use of shadcn/ui Input components, consistent styling with the application
|
||||
- **Password Visibility Toggle** - Added show/hide password functionality (API Key, Access Token)
|
||||
|
||||
#### Form Validation Infrastructure
|
||||
|
||||
- **Common Schema Library** - New JSON/TOML generic validators to reduce code duplication
|
||||
- `jsonConfigSchema`: Generic JSON object validator
|
||||
- `tomlConfigSchema`: Generic TOML format validator
|
||||
- `mcpJsonConfigSchema`: MCP-specific JSON validator
|
||||
- **MCP Conditional Field Validation** - Strict type checking
|
||||
- stdio type requires `command` field
|
||||
- http type requires `url` field
|
||||
|
||||
#### Partner Integration
|
||||
|
||||
- **PackyCode** - New official partner
|
||||
- Added to Claude and Codex provider presets
|
||||
- 10% discount promotion support
|
||||
- New logo and partner identification
|
||||
|
||||
---
|
||||
|
||||
### 🔧 Improvements
|
||||
|
||||
#### User Experience
|
||||
|
||||
- **Drag Sort Sync** - Tray menu order now syncs with drag-and-drop sorting in real-time
|
||||
- **Enhanced Error Notifications** - Provider switch failures now display copyable error messages
|
||||
- **Removed Misleading Placeholders** - Deleted example text from model input fields to avoid user confusion
|
||||
- **Auto-fill Base URL** - All non-official provider categories automatically populate the Base URL input field
|
||||
|
||||
#### Configuration Parsing
|
||||
|
||||
- **CJK Quote Normalization** - Automatically handles IME-input fullwidth quotes to prevent TOML parsing errors
|
||||
- Supports automatic conversion of Chinese quotes (" " ' ') to ASCII quotes
|
||||
- Applied in TOML input handlers
|
||||
- Disabled browser auto-correction in Textarea component
|
||||
- **Preserve Custom Fields** - Editing Codex MCP TOML configuration now preserves unknown fields
|
||||
- Supports extension fields like timeout_ms, retry_count
|
||||
- Forward compatibility with future MCP protocol extensions
|
||||
|
||||
---
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
|
||||
#### Critical Fixes
|
||||
|
||||
- **Fixed usage script panel white screen crash** - FormLabel component missing FormField context caused entire app to crash
|
||||
- Replaced with standalone Label component
|
||||
- Root cause: FormLabel internally calls useFormField() hook which requires FormFieldContext
|
||||
- **Fixed CJK input quote parsing failure** - IME-input fullwidth quotes caused TOML parsing errors
|
||||
- Added textNormalization utility function
|
||||
- Automatically normalizes quotes before parsing
|
||||
- **Fixed drag sort tray desync** (#179) - Tray menu order not updated after drag-and-drop sorting
|
||||
- Automatically calls updateTrayMenu after sorting completes
|
||||
- Ensures UI and tray menu stay consistent
|
||||
- **Fixed MCP custom field loss** - Custom fields silently dropped when editing Codex MCP configuration
|
||||
- Uses spread operator to retain all fields
|
||||
- Preserves unknown fields in normalizeServerConfig
|
||||
|
||||
#### Stability Improvements
|
||||
|
||||
- **Error Isolation** - Tray menu update failures no longer affect main operations
|
||||
- Decoupled tray update errors from main operations
|
||||
- Provides warning when main operation succeeds but tray update fails
|
||||
- **Safe Pattern Matching** - Replaced `unwrap()` with safe pattern matching
|
||||
- Avoids panic-induced app crashes
|
||||
- Tray menu event handling uses match patterns
|
||||
- **Import Config Classification** - Importing from default config now automatically sets category to `custom`
|
||||
- Avoids imported configs being mistaken for official presets
|
||||
- Provides clearer configuration source identification
|
||||
|
||||
---
|
||||
|
||||
### 📊 Technical Statistics
|
||||
|
||||
```
|
||||
Commits: 17 commits
|
||||
Code Changes: 31 files
|
||||
- Additions: 1,163 lines
|
||||
- Deletions: 811 lines
|
||||
- Net Growth: +352 lines
|
||||
Contributors: Jason (16), ZyphrZero (1)
|
||||
```
|
||||
|
||||
**By Module**:
|
||||
- UI/User Interface: 3 commits
|
||||
- Usage Query System: 3 commits
|
||||
- Configuration Parsing: 2 commits
|
||||
- Form Validation: 1 commit
|
||||
- Other Improvements: 8 commits
|
||||
|
||||
---
|
||||
|
||||
### 📥 Installation
|
||||
|
||||
#### macOS
|
||||
|
||||
**Via Homebrew (Recommended):**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
**Manual Download:**
|
||||
|
||||
- Download `CC-Switch-v3.6.1-macOS.zip` from [Assets](#assets) below
|
||||
|
||||
> **Note**: Due to lack of Apple Developer account, you may see "unidentified developer" warning. Go to System Settings → Privacy & Security → Click "Open Anyway"
|
||||
|
||||
#### Windows
|
||||
|
||||
- **Installer**: `CC-Switch-v3.6.1-Windows.msi`
|
||||
- **Portable**: `CC-Switch-v3.6.1-Windows-Portable.zip`
|
||||
|
||||
#### Linux
|
||||
|
||||
- **AppImage**: `CC-Switch-v3.6.1-Linux.AppImage`
|
||||
- **Debian**: `CC-Switch-v3.6.1-Linux.deb`
|
||||
|
||||
---
|
||||
|
||||
### 📚 Documentation
|
||||
|
||||
- [中文文档 (Chinese)](https://github.com/farion1231/cc-switch/blob/main/README_ZH.md)
|
||||
- [English Documentation](https://github.com/farion1231/cc-switch/blob/main/README.md)
|
||||
- [完整更新日志 (Full Changelog)](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
### 🙏 Acknowledgments
|
||||
|
||||
Special thanks to:
|
||||
- **Zhipu AI** - For sponsoring this project with GLM CODING PLAN
|
||||
- **PackyCode** - New official partner
|
||||
- **ZyphrZero** - For contributing tray menu sync fix (#179)
|
||||
|
||||
---
|
||||
|
||||
**Full Changelog**: https://github.com/farion1231/cc-switch/compare/v3.6.0...v3.6.1
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## 📜 v3.6.0 Complete Feature Review
|
||||
|
||||
> Content below is from v3.6.0 (2025-11-07), helping you understand the complete feature set
|
||||
|
||||
<details>
|
||||
<summary><b>Click to expand v3.6.0 detailed content →</b></summary>
|
||||
|
||||
## What's New
|
||||
|
||||
### Edit Mode & Provider Management
|
||||
|
||||
- **Provider Duplication** - Quickly duplicate existing provider configurations to create variants with one click
|
||||
- **Manual Sorting** - Drag and drop to reorder providers, with visual push effect animations. Thanks to @ZyphrZero
|
||||
- **Edit Mode Toggle** - Show/hide drag handles to optimize editing experience
|
||||
|
||||
### Custom Endpoint Management
|
||||
|
||||
- **Multi-Endpoint Configuration** - Support for aggregator providers with multiple API endpoints
|
||||
- **Endpoint Input Visibility** - Shows endpoint field for all non-official providers automatically
|
||||
|
||||
### Usage Query Enhancements
|
||||
|
||||
- **Auto-Refresh Interval** - Configure periodic automatic usage queries with customizable intervals
|
||||
- **Test Script API** - Validate JavaScript usage query scripts before execution
|
||||
- **Enhanced Templates** - Custom blank templates with access token and user ID parameter support
|
||||
Thanks to @Sirhexs
|
||||
|
||||
### Custom Configuration Directory (Cloud Sync)
|
||||
|
||||
- **Customizable Storage Location** - Customize CC Switch's configuration storage directory
|
||||
- **Cloud Sync Support** - Point to cloud sync folders (Dropbox, OneDrive, iCloud Drive, etc.) to enable automatic config synchronization across devices
|
||||
- **Independent Management** - Managed via Tauri Store for better isolation and reliability
|
||||
Thanks to @ZyphrZero
|
||||
|
||||
### Configuration Directory Switching (WSL Support)
|
||||
|
||||
- **Auto-Sync on Directory Change** - When switching Claude/Codex config directories (e.g., WSL environment), automatically sync current provider to the new directory without manual operation
|
||||
- **Post-Change Sync Utility** - Unified `postChangeSync.ts` utility for graceful error handling without blocking main flow
|
||||
- **Import Config Auto-Sync** - Automatically sync after config import to ensure immediate effectiveness
|
||||
- **Smart Conflict Resolution** - Distinguishes "fully successful" and "partially successful" states for precise user feedback
|
||||
|
||||
### Configuration Editor Improvements
|
||||
|
||||
- **JSON Format Button** - One-click JSON formatting in configuration editors
|
||||
- **Real-Time TOML Validation** - Live syntax validation for Codex configuration with error highlighting
|
||||
|
||||
### Load Live Config When Editing
|
||||
|
||||
- **Protect Manual Modifications** - When editing the currently active provider, prioritize displaying the actual effective configuration from live files
|
||||
- **Dual-Source Strategy** - Automatically loads from live config for active provider, SSOT for inactive ones
|
||||
|
||||
### Claude Configuration Data Structure Enhancements
|
||||
|
||||
- **Granular Model Configuration** - Migrated from dual-key to quad-key system for better model tier differentiation
|
||||
- New fields: `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_MODEL`
|
||||
- Replaces legacy `ANTHROPIC_SMALL_FAST_MODEL` with automatic migration
|
||||
- Backend normalizes old configs on first read/write with smart fallback chain
|
||||
- UI expanded from 2 to 4 model input fields with intelligent defaults
|
||||
- **ANTHROPIC_API_KEY Support** - Providers can now use `ANTHROPIC_API_KEY` field in addition to `ANTHROPIC_AUTH_TOKEN`
|
||||
- **Template Variable System** - Support for dynamic configuration replacement (e.g., KAT-Coder's `ENDPOINT_ID` parameter)
|
||||
- **Endpoint Candidates** - Predefined endpoint list for speed testing and endpoint management
|
||||
- **Visual Theme Configuration** - Custom icons and colors for provider cards
|
||||
|
||||
### Updated Provider Models
|
||||
|
||||
- **Kimi k2** - Updated to latest `kimi-k2-thinking` model
|
||||
|
||||
### New Provider Presets
|
||||
|
||||
Added 5 new provider presets:
|
||||
|
||||
- **DMXAPI** - Multi-model aggregation service
|
||||
- **Azure Codex** - Microsoft Azure OpenAI endpoint
|
||||
- **AnyRouter** - None-profit routing service
|
||||
- **AiHubMix** - Multi-model aggregation service
|
||||
- **MiniMax** - Open source AI model provider
|
||||
|
||||
### Partner Promotion Mechanism
|
||||
|
||||
- Support for ecosystem partner promotion (Zhipu GLM Z.ai)
|
||||
- Sponsored banner integration in README
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
### Configuration & Sync
|
||||
|
||||
- **Unified Error Handling** - AppError with internationalized error messages throughout backend
|
||||
- **Fixed apiKeyUrl Priority** - Correct priority order for API key URL resolution
|
||||
- **Fixed MCP Sync Issues** - Resolved sync-to-other-side functionality failures
|
||||
- **Import Config Sync** - Fixed sync issues after configuration import
|
||||
- **Config Error Handling** - Force exit on config error to prevent silent fallback and data loss
|
||||
|
||||
### UI/UX Enhancements
|
||||
|
||||
- **Unique Provider Icons** - Each provider card now has unique icons and color identification
|
||||
- **Unified Border System** - Consistent border design across all components
|
||||
- **Drag Interaction** - Push effect animation and improved drag handle icons
|
||||
- **Enhanced Visual Feedback** - Better current provider visual indication
|
||||
- **Dialog Standardization** - Unified dialog sizes and layout consistency
|
||||
- **Form Improvements** - Optimized model placeholders, simplified provider hints, category-specific hints
|
||||
- **Usage Display Inline** - Usage info moved next to enable button for better space utilization
|
||||
|
||||
### Complete Internationalization
|
||||
|
||||
- **Error Messages i18n** - All backend error messages support Chinese/English
|
||||
- **Tray Menu i18n** - System tray menu fully internationalized
|
||||
- **UI Components i18n** - 100% coverage across all user-facing components
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- Fixed `apiKeyUrl` priority issue
|
||||
- Fixed MCP sync-to-other-side functionality failure
|
||||
- Fixed sync issues after config import
|
||||
- Fixed Codex API Key auto-sync
|
||||
- Fixed endpoint speed test functionality
|
||||
- Fixed provider duplicate insertion position (now inserts next to original)
|
||||
- Fixed custom endpoint preservation in edit mode
|
||||
- Prevent silent fallback and data loss on config error
|
||||
|
||||
### Usage Query
|
||||
|
||||
- Fixed auto-query interval timing issue
|
||||
- Ensured 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
|
||||
|
||||
### Startup Issues
|
||||
|
||||
- Force exit on config error (no silent fallback)
|
||||
- Eliminated code duplication causing initialization errors
|
||||
|
||||
---
|
||||
|
||||
## Architecture Refactoring
|
||||
|
||||
### Backend (Rust) - 5 Phase Refactoring
|
||||
|
||||
1. **Phase 1**: Unified error handling (`AppError` + i18n error messages)
|
||||
2. **Phase 2**: Command layer split by domain (`commands/{provider,mcp,config,settings,plugin,misc}.rs`)
|
||||
3. **Phase 3**: Integration tests and transaction mechanism (config snapshot + failure rollback)
|
||||
4. **Phase 4**: Extracted Service layer (`services/{provider,mcp,config,speedtest}.rs`)
|
||||
5. **Phase 5**: Concurrency optimization (`RwLock` instead of `Mutex`, scoped guard to avoid deadlock)
|
||||
|
||||
### Frontend (React + TypeScript) - 4 Stage Refactoring
|
||||
|
||||
1. **Stage 1**: Test infrastructure (vitest + MSW + @testing-library/react)
|
||||
2. **Stage 2**: Extracted custom hooks (`useProviderActions`, `useMcpActions`, `useSettings`, `useImportExport`, etc.)
|
||||
3. **Stage 3**: Component splitting and business logic extraction
|
||||
4. **Stage 4**: Code cleanup and formatting unification
|
||||
|
||||
### Testing System
|
||||
|
||||
- **Hooks Unit Tests** - 100% coverage for all custom hooks
|
||||
- **Integration Tests** - Coverage for key processes (App, SettingsDialog, MCP Panel)
|
||||
- **MSW Mocking** - Backend API mocking to ensure test independence
|
||||
- **Test Infrastructure** - vitest + MSW + @testing-library/react
|
||||
|
||||
### Code Quality
|
||||
|
||||
- **Unified Parameter Format** - All Tauri commands migrated to camelCase (Tauri 2 specification)
|
||||
- **Semantic Clarity** - `AppType` renamed to `AppId` for better semantics
|
||||
- **Centralized Parsing** - Unified `app` parameter parsing with `FromStr` trait
|
||||
- **DRY Violations Cleanup** - Eliminated code duplication throughout codebase
|
||||
- **Dead Code Removal** - Removed unused `missing_param` helper, deprecated `tauri-api.ts`, redundant `KimiModelSelector`
|
||||
|
||||
---
|
||||
|
||||
## Internal Optimizations (User Transparent)
|
||||
|
||||
### Removed Legacy Migration Logic
|
||||
|
||||
v3.6.0 removed v1 config auto-migration and copy file scanning logic:
|
||||
|
||||
- **Impact**: Improved startup performance, cleaner codebase
|
||||
- **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.0
|
||||
|
||||
### 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**
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🌟 About CC Switch
|
||||
|
||||
CC Switch is a cross-platform desktop application for managing and switching between different provider configurations for Claude Code and Codex. Built with Tauri 2.0 + React 18 + TypeScript, supporting Windows, macOS, and Linux.
|
||||
|
||||
**Core Features**:
|
||||
- 🔄 One-click switching between multiple AI providers
|
||||
- 📦 Support for both Claude Code and Codex applications
|
||||
- 🎨 Modern UI with complete Chinese/English internationalization
|
||||
- 🔐 Local storage, secure and reliable data
|
||||
- ☁️ Support for cloud sync configurations
|
||||
- 🧩 Unified MCP server management
|
||||
|
||||
---
|
||||
|
||||
**Project Repository**: https://github.com/farion1231/cc-switch
|
||||
@@ -1,389 +0,0 @@
|
||||
# CC Switch v3.6.1
|
||||
|
||||
> 稳定性提升与用户体验优化（基于 v3.6.0）
|
||||
|
||||
**[English Version →](../release-note-v3.6.1.md)**
|
||||
|
||||
---
|
||||
|
||||
## 📦 v3.6.1 新增内容 (2025-11-10)
|
||||
|
||||
本次更新主要聚焦于**用户体验优化**和**配置解析健壮性**，修复了多个关键 Bug，并增强了用量查询系统。
|
||||
|
||||
### ✨ 新增功能
|
||||
|
||||
#### 用量查询系统增强
|
||||
|
||||
- **凭证解耦** - 用量查询可使用独立的 API Key 和 Base URL，不再依赖供应商配置
|
||||
- 支持不同的查询端点和认证方式
|
||||
- 根据模板类型自动显示对应的凭证输入框
|
||||
- General 模板：API Key + Base URL
|
||||
- NewAPI 模板：Base URL + Access Token + User ID
|
||||
- Custom 模板：完全自定义
|
||||
- **UI 组件升级** - 使用 shadcn/ui Switch 替代原生 checkbox，体验更现代
|
||||
- **表单统一化** - 统一使用 shadcn/ui 输入组件，样式与应用保持一致
|
||||
- **密码显示切换** - 添加查看/隐藏密码功能（API Key、Access Token）
|
||||
|
||||
#### 表单验证基础设施
|
||||
|
||||
- **通用 Schema 库** - 新增 JSON/TOML 通用验证器，减少重复代码
|
||||
- `jsonConfigSchema`：通用 JSON 对象验证器
|
||||
- `tomlConfigSchema`：通用 TOML 格式验证器
|
||||
- `mcpJsonConfigSchema`：MCP 专用 JSON 验证器
|
||||
- **MCP 条件字段验证** - 严格的类型检查
|
||||
- stdio 类型强制要求 `command` 字段
|
||||
- http 类型强制要求 `url` 字段
|
||||
|
||||
#### 合作伙伴集成
|
||||
|
||||
- **PackyCode** - 新增官方合作伙伴
|
||||
- 添加到 Claude 和 Codex 供应商预设
|
||||
- 支持 10% 折扣优惠（促销信息集成）
|
||||
- 新增 Logo 和合作伙伴标识
|
||||
|
||||
---
|
||||
|
||||
### 🔧 改进优化
|
||||
|
||||
#### 用户体验
|
||||
|
||||
- **拖拽排序同步** - 托盘菜单顺序实时同步拖拽排序结果
|
||||
- **错误通知增强** - 切换供应商失败时显示可复制的错误信息
|
||||
- **移除误导性占位符** - 删除模型输入框的示例文本，避免用户混淆
|
||||
- **Base URL 自动填充** - 所有非官方供应商类别自动填充 Base URL 输入框
|
||||
|
||||
#### 配置解析
|
||||
|
||||
- **中文引号规范化** - 自动处理 IME 输入的全角引号，防止 TOML 解析错误
|
||||
- 支持中文引号（" " ' '）自动转换为 ASCII 引号
|
||||
- 在 TOML 输入处理器中应用
|
||||
- Textarea 组件禁用浏览器自动纠正
|
||||
- **自定义字段保留** - 编辑 Codex MCP TOML 配置时保留未知字段
|
||||
- 支持 timeout_ms、retry_count 等扩展字段
|
||||
- 向前兼容未来的 MCP 协议扩展
|
||||
|
||||
---
|
||||
|
||||
### 🐛 Bug 修复
|
||||
|
||||
#### 关键修复
|
||||
|
||||
- **修复用量脚本面板白屏崩溃** - FormLabel 组件缺少 FormField context 导致整个应用崩溃
|
||||
- 替换为独立的 Label 组件
|
||||
- 根本原因：FormLabel 内部调用 useFormField() hook 需要 FormFieldContext
|
||||
- **修复中文输入法引号解析失败** - IME 输入的全角引号导致 TOML 解析错误
|
||||
- 新增 textNormalization 工具函数
|
||||
- 在解析前自动规范化引号
|
||||
- **修复拖拽排序托盘不同步** (#179) - 拖拽排序后托盘菜单顺序未更新
|
||||
- 在排序完成后自动调用 updateTrayMenu
|
||||
- 确保 UI 和托盘菜单保持一致
|
||||
- **修复 MCP 自定义字段丢失** - 编辑 Codex MCP 配置时自定义字段被静默丢弃
|
||||
- 使用 spread 操作符保留所有字段
|
||||
- normalizeServerConfig 中保留未知字段
|
||||
|
||||
#### 稳定性改进
|
||||
|
||||
- **错误隔离** - 托盘菜单更新失败不再影响主操作流程
|
||||
- 将托盘更新错误与主操作解耦
|
||||
- 主操作成功但托盘更新失败时给出警告
|
||||
- **安全模式匹配** - 替换 `unwrap()` 为安全的 pattern matching
|
||||
- 避免 panic 导致应用崩溃
|
||||
- 托盘菜单事件处理使用 match 模式
|
||||
- **导入配置分类** - 从默认配置导入时自动设置 category 为 `custom`
|
||||
- 避免导入的配置被误认为官方预设
|
||||
- 提供更清晰的配置来源标识
|
||||
|
||||
---
|
||||
|
||||
### 📊 技术统计
|
||||
|
||||
```
|
||||
提交数: 17 commits
|
||||
代码变更: 31 个文件
|
||||
- 新增: 1,163 行
|
||||
- 删除: 811 行
|
||||
- 净增长: +352 行
|
||||
贡献者: Jason (16), ZyphrZero (1)
|
||||
```
|
||||
|
||||
**按模块分类**：
|
||||
- UI/用户界面：3 commits
|
||||
- 用量查询系统：3 commits
|
||||
- 配置解析：2 commits
|
||||
- 表单验证：1 commit
|
||||
- 其他改进：8 commits
|
||||
|
||||
---
|
||||
|
||||
### 📥 安装方式
|
||||
|
||||
#### macOS
|
||||
|
||||
**通过 Homebrew 安装（推荐）：**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
**手动下载：**
|
||||
|
||||
- 从下方 [Assets](#assets) 下载 `CC-Switch-v3.6.1-macOS.zip`
|
||||
|
||||
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告。请前往"系统设置" → "隐私与安全性" → 点击"仍要打开"
|
||||
|
||||
#### Windows
|
||||
|
||||
- **安装包**：`CC-Switch-v3.6.1-Windows.msi`
|
||||
- **便携版**：`CC-Switch-v3.6.1-Windows-Portable.zip`
|
||||
|
||||
#### Linux
|
||||
|
||||
- **AppImage**：`CC-Switch-v3.6.1-Linux.AppImage`
|
||||
- **Debian**：`CC-Switch-v3.6.1-Linux.deb`
|
||||
|
||||
---
|
||||
|
||||
### 📚 文档
|
||||
|
||||
- [中文文档](https://github.com/farion1231/cc-switch/blob/main/README_ZH.md)
|
||||
- [English Documentation](https://github.com/farion1231/cc-switch/blob/main/README.md)
|
||||
- [完整更新日志](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
### 🙏 致谢
|
||||
|
||||
特别感谢：
|
||||
- **智谱 AI** - 通过 GLM CODING PLAN 赞助本项目
|
||||
- **PackyCode** - 新加入的官方合作伙伴
|
||||
- **ZyphrZero** - 贡献托盘菜单同步修复 (#179)
|
||||
|
||||
---
|
||||
|
||||
**完整变更记录**: https://github.com/farion1231/cc-switch/compare/v3.6.0...v3.6.1
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## 📜 v3.6.0 完整功能回顾
|
||||
|
||||
> 以下内容来自 v3.6.0 (2025-11-07)，帮助您了解完整的功能集
|
||||
|
||||
<details>
|
||||
<summary><b>点击展开 v3.6.0 的详细内容 →</b></summary>
|
||||
|
||||
## 新增功能
|
||||
|
||||
### 编辑模式与供应商管理
|
||||
|
||||
- **供应商复制功能** - 一键快速复制现有供应商配置，轻松创建变体配置
|
||||
- **手动排序功能** - 通过拖拽对供应商进行重新排序，带有视觉推送效果动画
|
||||
- **编辑模式切换** - 显示/隐藏拖拽手柄，优化编辑体验
|
||||
|
||||
### 自定义端点管理
|
||||
|
||||
- **多端点配置** - 支持聚合类供应商的多 API 端点配置
|
||||
- **端点输入可见性** - 为所有非官方供应商自动显示端点字段
|
||||
|
||||
### 自定义配置目录（云同步）
|
||||
|
||||
- **自定义存储位置** - 自定义 CC Switch 的配置存储目录
|
||||
- **云同步支持** - 指定到云同步文件夹（Dropbox、OneDrive、iCloud Drive、坚果云等）即可实现跨设备配置自动同步
|
||||
- **独立管理** - 通过 Tauri Store 管理，更好的隔离性和可靠性
|
||||
|
||||
### 使用量查询增强
|
||||
|
||||
- **自动刷新间隔** - 配置定时自动使用量查询，支持自定义间隔时间
|
||||
- **测试脚本 API** - 在执行前验证 JavaScript 使用量查询脚本
|
||||
- **增强模板系统** - 自定义空白模板，支持 access token 和 user ID 参数
|
||||
|
||||
### 配置目录切换（WSL 支持）
|
||||
|
||||
- **目录变更自动同步** - 切换 Claude/Codex 配置目录（如 WSL 环境）时，自动同步当前供应商到新目录，无需手动操作
|
||||
- **后置同步工具** - 统一的 `postChangeSync.ts` 工具，优雅处理错误而不阻塞主流程
|
||||
- **导入配置自动同步** - 配置导入后自动同步，确保立即生效
|
||||
- **智能冲突解决** - 区分"完全成功"和"部分成功"状态，提供精确的用户反馈
|
||||
|
||||
### 配置编辑器改进
|
||||
|
||||
- **JSON 格式化按钮** - 配置编辑器中一键 JSON 格式化
|
||||
- **实时 TOML 验证** - Codex 配置的实时语法验证，带有错误高亮
|
||||
|
||||
### 编辑时加载 Live 配置
|
||||
|
||||
- **保护手动修改** - 编辑当前激活的供应商时，优先显示来自 live 文件的实际生效配置
|
||||
- **双源策略** - 活动供应商自动从 live 配置加载，非活动供应商从 SSOT 加载
|
||||
|
||||
### Claude 配置数据结构增强
|
||||
|
||||
- **细粒度模型配置** - 从双键系统升级到四键系统，以匹配官方最新数据结构
|
||||
- 新增字段：`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_MODEL`
|
||||
- 替换旧版 `ANTHROPIC_SMALL_FAST_MODEL`，支持自动迁移
|
||||
- 后端在首次读写时自动规范化旧配置，带有智能回退链
|
||||
- UI 从 2 个模型输入字段扩展到 4 个，具有智能默认值
|
||||
- **ANTHROPIC_API_KEY 支持** - 供应商现可使用 `ANTHROPIC_API_KEY` 字段（除 `ANTHROPIC_AUTH_TOKEN` 外）
|
||||
- **模板变量系统** - 支持动态配置替换（如 KAT-Coder 的 `ENDPOINT_ID` 参数）
|
||||
- **端点候选列表** - 预定义端点列表，用于速度测试和端点管理
|
||||
- **视觉主题配置** - 供应商卡片自定义图标和颜色
|
||||
|
||||
### 供应商模型更新
|
||||
|
||||
- **Kimi k2** - 更新到最新的 `kimi-k2-thinking` 模型
|
||||
|
||||
### 新增供应商预设
|
||||
|
||||
新增 5 个供应商预设：
|
||||
|
||||
- **DMXAPI** - 多模型聚合服务
|
||||
- **Azure Codex** - 微软 Azure OpenAI 端点
|
||||
- **AnyRouter** - API 路由服务
|
||||
- **AiHubMix** - AI 模型集合
|
||||
- **MiniMax** - 国产 AI 模型提供商
|
||||
|
||||
### 合作伙伴推广机制
|
||||
|
||||
- 支持生态合作伙伴推广（智谱 GLM Z.ai）
|
||||
- README 中集成赞助商横幅
|
||||
|
||||
---
|
||||
|
||||
## 改进优化
|
||||
|
||||
### 配置与同步
|
||||
|
||||
- **统一错误处理** - 后端全面使用 AppError 与国际化错误消息
|
||||
- **修复 apiKeyUrl 优先级** - 修正 API key URL 解析的优先级顺序
|
||||
- **修复 MCP 同步问题** - 解决同步到另一端功能失效的问题
|
||||
- **导入配置同步** - 修复配置导入后的同步问题
|
||||
- **配置错误处理** - 配置错误时强制退出，防止静默回退和数据丢失
|
||||
|
||||
### UI/UX 增强
|
||||
|
||||
- **独特的供应商图标** - 每个供应商卡片现在都有独特的图标和颜色识别
|
||||
- **统一边框系统** - 所有组件采用一致的边框设计
|
||||
- **拖拽交互** - 推送效果动画和改进的拖拽手柄图标
|
||||
- **增强视觉反馈** - 更好的当前供应商视觉指示
|
||||
- **对话框标准化** - 统一的对话框尺寸和布局一致性
|
||||
- **表单改进** - 优化模型占位符，简化供应商提示，分类特定提示
|
||||
- **使用量内联显示** - 使用量信息移至启用按钮旁边，更好地利用空间
|
||||
|
||||
### 完整国际化
|
||||
|
||||
- **错误消息国际化** - 所有后端错误消息支持中英文
|
||||
- **托盘菜单国际化** - 系统托盘菜单完全国际化
|
||||
- **UI 组件国际化** - 所有面向用户的组件 100% 覆盖
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 配置管理
|
||||
|
||||
- 修复 `apiKeyUrl` 优先级问题
|
||||
- 修复 MCP 同步到另一端功能失效
|
||||
- 修复配置导入后的同步问题
|
||||
- 修复 Codex API Key 自动同步
|
||||
- 修复端点速度测试功能
|
||||
- 修复供应商复制插入位置（现在插入到原供应商旁边）
|
||||
- 修复编辑模式下自定义端点保留问题
|
||||
- 防止配置错误时的静默回退和数据丢失
|
||||
|
||||
### 使用量查询
|
||||
|
||||
- 修复自动查询间隔时间问题
|
||||
- 确保刷新按钮点击时显示加载动画
|
||||
|
||||
### UI 问题
|
||||
|
||||
- 修复名称冲突错误（`get_init_error` 命令）
|
||||
- 修复保存成功后语言设置回滚
|
||||
- 修复语言切换状态重置（依赖循环）
|
||||
- 修复编辑模式按钮对齐
|
||||
|
||||
### 启动问题
|
||||
|
||||
- 配置错误时强制退出（不再静默回退）
|
||||
- 消除导致初始化错误的代码重复
|
||||
|
||||
---
|
||||
|
||||
## 架构重构
|
||||
|
||||
### 后端（Rust）- 5 阶段重构
|
||||
|
||||
1. **阶段 1**：统一错误处理（`AppError` + 国际化错误消息）
|
||||
2. **阶段 2**：命令层按领域拆分（`commands/{provider,mcp,config,settings,plugin,misc}.rs`）
|
||||
3. **阶段 3**：集成测试和事务机制（配置快照 + 失败回滚）
|
||||
4. **阶段 4**：提取 Service 层（`services/{provider,mcp,config,speedtest}.rs`）
|
||||
5. **阶段 5**：并发优化（`RwLock` 替代 `Mutex`，作用域 guard 避免死锁）
|
||||
|
||||
### 前端（React + TypeScript）- 4 阶段重构
|
||||
|
||||
1. **阶段 1**：测试基础设施（vitest + MSW + @testing-library/react）
|
||||
2. **阶段 2**：提取自定义 hooks（`useProviderActions`、`useMcpActions`、`useSettings`、`useImportExport` 等）
|
||||
3. **阶段 3**：组件拆分和业务逻辑提取
|
||||
4. **阶段 4**：代码清理和格式化统一
|
||||
|
||||
### 测试体系
|
||||
|
||||
- **Hooks 单元测试** - 所有自定义 hooks 100% 覆盖
|
||||
- **集成测试** - 关键流程覆盖（App、SettingsDialog、MCP 面板）
|
||||
- **MSW 模拟** - 后端 API 模拟确保测试独立性
|
||||
- **测试基础设施** - vitest + MSW + @testing-library/react
|
||||
|
||||
### 代码质量
|
||||
|
||||
- **统一参数格式** - 所有 Tauri 命令迁移到 camelCase（Tauri 2 规范）
|
||||
- **语义清晰** - `AppType` 重命名为 `AppId` 以获得更好的语义
|
||||
- **集中解析** - 使用 `FromStr` trait 统一 `app` 参数解析
|
||||
- **DRY 违规清理** - 消除整个代码库中的代码重复
|
||||
- **死代码移除** - 移除未使用的 `missing_param` 辅助函数、废弃的 `tauri-api.ts`、冗余的 `KimiModelSelector`
|
||||
|
||||
---
|
||||
|
||||
## 内部优化（用户无感知）
|
||||
|
||||
### 移除遗留迁移逻辑
|
||||
|
||||
v3.6.0 移除了 v1 配置自动迁移和副本文件扫描逻辑：
|
||||
|
||||
- **影响**：提升启动性能，代码更简洁
|
||||
- **兼容性**：v2 格式配置完全兼容，无需任何操作
|
||||
- **注意**：从 v3.1.0 或更早版本升级的用户，请先升级到 v3.2.x 或 v3.5.x 进行一次性迁移，然后再升级到 v3.6.0
|
||||
|
||||
### 命令参数标准化
|
||||
|
||||
后端统一使用 `app` 参数（取值：`claude` 或 `codex`）：
|
||||
|
||||
- **影响**：代码更规范，错误提示更友好
|
||||
- **兼容性**：前端已完全适配，用户无需关心此变更
|
||||
|
||||
---
|
||||
|
||||
## 依赖更新
|
||||
|
||||
- 更新到 **Tauri 2.8.x**
|
||||
- 更新到 **TailwindCSS 4.x**
|
||||
- 更新到 **TanStack Query v5.90.x**
|
||||
- 保持 **React 18.2.x** 和 **TypeScript 5.3.x**
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🌟 关于 CC Switch
|
||||
|
||||
CC Switch 是一个跨平台桌面应用，用于管理和切换 Claude Code 与 Codex 的不同供应商配置。基于 Tauri 2.0 + React 18 + TypeScript 构建，支持 Windows、macOS、Linux。
|
||||
|
||||
**核心特性**：
|
||||
- 🔄 一键切换多个 AI 供应商
|
||||
- 📦 支持 Claude Code 和 Codex 双应用
|
||||
- 🎨 现代化 UI，完整的中英文国际化
|
||||
- 🔐 本地存储，数据安全可靠
|
||||
- ☁️ 支持云同步配置
|
||||
- 🧩 MCP 服务器统一管理
|
||||
|
||||
---
|
||||
|
||||
**项目地址**: https://github.com/farion1231/cc-switch
|
||||
@@ -1,439 +0,0 @@
|
||||
# CC Switch v3.7.0
|
||||
|
||||
> From Provider Switcher to All-in-One AI CLI Management Platform
|
||||
|
||||
**[中文更新说明 Chinese Documentation →](release-note-v3.7.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.7.0 introduces six major features with over 18,000 lines of new code.
|
||||
|
||||
**Release Date**: 2025-11-19
|
||||
**Commits**: 85 from v3.6.0
|
||||
**Code Changes**: 152 files, +18,104 / -3,732 lines
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### Gemini CLI Integration
|
||||
|
||||
Complete support for Google Gemini CLI, becoming the third supported application (Claude Code, Codex, Gemini).
|
||||
|
||||
**Core Capabilities**:
|
||||
|
||||
- **Dual-file configuration** - Support for both `.env` and `settings.json` formats
|
||||
- **Auto-detection** - Automatically detect `GOOGLE_GEMINI_BASE_URL`, `GEMINI_MODEL`, etc.
|
||||
- **Full MCP support** - Complete MCP server management for Gemini
|
||||
- **Deep link integration** - Import via `ccswitch://` protocol
|
||||
- **System tray** - Quick-switch from tray menu
|
||||
|
||||
**Provider Presets**:
|
||||
|
||||
- **Google Official** - OAuth authentication support
|
||||
- **PackyCode** - Partner integration
|
||||
- **Custom** - Full customization support
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- New backend modules: `gemini_config.rs` (20KB), `gemini_mcp.rs`
|
||||
- Form synchronization with environment editor
|
||||
- Dual-file atomic writes
|
||||
|
||||
---
|
||||
|
||||
### MCP v3.7.0 Unified Architecture
|
||||
|
||||
Complete refactoring of MCP management system for cross-application unification.
|
||||
|
||||
**Architecture Improvements**:
|
||||
|
||||
- **Unified panel** - Single interface for Claude/Codex/Gemini MCP servers
|
||||
- **SSE transport** - New Server-Sent Events support
|
||||
- **Smart parser** - Fault-tolerant JSON parsing
|
||||
- **Format correction** - Auto-fix Codex `[mcp_servers]` format
|
||||
- **Extended fields** - Preserve custom TOML fields
|
||||
|
||||
**User Experience**:
|
||||
|
||||
- Default app selection in forms
|
||||
- JSON formatter for validation
|
||||
- Improved visual hierarchy
|
||||
- Better error messages
|
||||
|
||||
**Import/Export**:
|
||||
|
||||
- Unified import from all three apps
|
||||
- Bidirectional synchronization
|
||||
- State preservation
|
||||
|
||||
---
|
||||
|
||||
### Claude Skills Management System
|
||||
|
||||
**Approximately 2,000 lines of code** - A complete skill ecosystem platform.
|
||||
|
||||
**GitHub Integration**:
|
||||
|
||||
- Auto-scan skills from GitHub repositories
|
||||
- Pre-configured repos:
|
||||
- `ComposioHQ/awesome-claude-skills` - Curated collection
|
||||
- `anthropics/skills` - Official Anthropic skills
|
||||
- `cexll/myclaude` - Community contributions
|
||||
- Add custom repositories
|
||||
- Subdirectory scanning support (`skillsPath`)
|
||||
|
||||
**Lifecycle Management**:
|
||||
|
||||
- **Discover** - Auto-detect `SKILL.md` files
|
||||
- **Install** - One-click to `~/.claude/skills/`
|
||||
- **Uninstall** - Safe removal with tracking
|
||||
- **Update** - Check for updates (infrastructure ready)
|
||||
|
||||
**Technical Architecture**:
|
||||
|
||||
- **Backend**: `SkillService` (526 lines) with GitHub API integration
|
||||
- **Frontend**: SkillsPage, SkillCard, RepoManager
|
||||
- **UI Components**: Badge, Card, Table (shadcn/ui)
|
||||
- **State**: Persistent storage in `skills.json`
|
||||
- **i18n**: 47+ translation keys
|
||||
|
||||
---
|
||||
|
||||
### Prompts Management System
|
||||
|
||||
**Approximately 1,300 lines of code** - Complete system prompt management.
|
||||
|
||||
**Multi-Preset Management**:
|
||||
|
||||
- Create unlimited prompt presets
|
||||
- Quick switch between presets
|
||||
- One active prompt at a time
|
||||
- Delete protection for active prompts
|
||||
|
||||
**Cross-App Support**:
|
||||
|
||||
- **Claude**: `~/.claude/CLAUDE.md`
|
||||
- **Codex**: `~/.codex/AGENTS.md`
|
||||
- **Gemini**: `~/.gemini/GEMINI.md`
|
||||
|
||||
**Markdown Editor**:
|
||||
|
||||
- Full-featured CodeMirror 6 integration
|
||||
- Syntax highlighting
|
||||
- Dark theme (One Dark)
|
||||
- Real-time preview
|
||||
|
||||
**Smart Synchronization**:
|
||||
|
||||
- **Auto-write** - Immediately write to live files
|
||||
- **Backfill protection** - Save current content before switching
|
||||
- **Auto-import** - Import from live files on first launch
|
||||
- **Modification protection** - Preserve manual modifications
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- **Backend**: `PromptService` (213 lines)
|
||||
- **Frontend**: PromptPanel (177), PromptFormModal (160), MarkdownEditor (159)
|
||||
- **Hooks**: usePromptActions (152 lines)
|
||||
- **i18n**: 41+ translation keys
|
||||
|
||||
---
|
||||
|
||||
### Deep Link Protocol (ccswitch://)
|
||||
|
||||
One-click provider configuration import via URL scheme.
|
||||
|
||||
**Features**:
|
||||
|
||||
- Protocol registration on all platforms
|
||||
- Import from shared links
|
||||
- Lifecycle integration
|
||||
- Security validation
|
||||
|
||||
---
|
||||
|
||||
### Environment Variable Conflict Detection
|
||||
|
||||
Intelligent detection and management of configuration conflicts.
|
||||
|
||||
**Detection Scope**:
|
||||
|
||||
- **Claude & Codex** - Cross-app conflicts
|
||||
- **Gemini** - Auto-discovery
|
||||
- **MCP** - Server configuration conflicts
|
||||
|
||||
**Management Features**:
|
||||
|
||||
- Visual conflict indicators
|
||||
- Resolution suggestions
|
||||
- Override warnings
|
||||
- Backup before changes
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
### Provider Management
|
||||
|
||||
**New Presets**:
|
||||
|
||||
- **DouBaoSeed** - ByteDance's DouBao
|
||||
- **Kimi For Coding** - Moonshot AI
|
||||
- **BaiLing** - BaiLing AI
|
||||
- **Removed AnyRouter** - To avoid confusion
|
||||
|
||||
**Enhancements**:
|
||||
|
||||
- Model name configuration for Codex and Gemini
|
||||
- Provider notes field for organization
|
||||
- Enhanced preset metadata
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- **Common config migration** - From localStorage to `config.json`
|
||||
- **Unified persistence** - Shared across all apps
|
||||
- **Auto-import** - First launch configuration import
|
||||
- **Backfill priority** - Correct handling of live files
|
||||
|
||||
### UI/UX Improvements
|
||||
|
||||
**Design System**:
|
||||
|
||||
- **macOS native** - System-aligned color scheme
|
||||
- **Window centering** - Default centered position
|
||||
- **Visual polish** - Improved spacing and hierarchy
|
||||
|
||||
**Interactions**:
|
||||
|
||||
- **Password input** - Fixed Edge/IE reveal buttons
|
||||
- **URL overflow** - Fixed card overflow
|
||||
- **Error copying** - Copy-to-clipboard errors
|
||||
- **Tray sync** - Real-time drag-and-drop sync
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Critical Fixes
|
||||
|
||||
- **Usage script validation** - Boundary checks
|
||||
- **Gemini validation** - Relaxed constraints
|
||||
- **TOML parsing** - CJK quote handling
|
||||
- **MCP fields** - Custom field preservation
|
||||
- **White screen** - FormLabel crash fix
|
||||
|
||||
### Stability
|
||||
|
||||
- **Tray safety** - Pattern matching instead of unwrap
|
||||
- **Error isolation** - Tray failures don't block operations
|
||||
- **Import classification** - Correct category assignment
|
||||
|
||||
### UI Fixes
|
||||
|
||||
- **Model placeholders** - Removed misleading hints
|
||||
- **Base URL** - Auto-fill for third-party providers
|
||||
- **Drag sort** - Tray menu synchronization
|
||||
|
||||
---
|
||||
|
||||
## Technical Improvements
|
||||
|
||||
### Architecture
|
||||
|
||||
**MCP v3.7.0**:
|
||||
|
||||
- Removed legacy code (~1,000 lines)
|
||||
- Unified initialization structure
|
||||
- Backward compatibility maintained
|
||||
- Comprehensive code formatting
|
||||
|
||||
**Platform Compatibility**:
|
||||
|
||||
- Windows winreg API fix (v0.52)
|
||||
- Safe pattern matching (no `unwrap()`)
|
||||
- Cross-platform tray handling
|
||||
|
||||
### Configuration
|
||||
|
||||
**Synchronization**:
|
||||
|
||||
- MCP sync across all apps
|
||||
- Gemini form-editor sync
|
||||
- Dual-file reading (.env + settings.json)
|
||||
|
||||
**Validation**:
|
||||
|
||||
- Input boundary checks
|
||||
- TOML quote normalization (CJK)
|
||||
- Custom field preservation
|
||||
- Enhanced error messages
|
||||
|
||||
### Code Quality
|
||||
|
||||
**Type Safety**:
|
||||
|
||||
- Complete TypeScript coverage
|
||||
- Rust type refinements
|
||||
- API contract validation
|
||||
|
||||
**Testing**:
|
||||
|
||||
- Simplified assertions
|
||||
- Better test coverage
|
||||
- Integration test updates
|
||||
|
||||
**Dependencies**:
|
||||
|
||||
- Tauri 2.8.x
|
||||
- Rust: `anyhow`, `zip`, `serde_yaml`, `tempfile`
|
||||
- Frontend: CodeMirror 6 packages
|
||||
- winreg 0.52 (Windows)
|
||||
|
||||
---
|
||||
|
||||
## Technical Statistics
|
||||
|
||||
```
|
||||
Total Changes:
|
||||
- Commits: 85
|
||||
- Files: 152 changed
|
||||
- Additions: +18,104 lines
|
||||
- Deletions: -3,732 lines
|
||||
|
||||
New Modules:
|
||||
- Skills Management: 2,034 lines (21 files)
|
||||
- Prompts Management: 1,302 lines (20 files)
|
||||
- Gemini Integration: ~1,000 lines
|
||||
- MCP Refactor: ~3,000 lines refactored
|
||||
|
||||
Code Distribution:
|
||||
- Backend (Rust): ~4,500 lines new
|
||||
- Frontend (React): ~3,000 lines new
|
||||
- Configuration: ~1,500 lines refactored
|
||||
- Tests: ~500 lines
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Strategic Positioning
|
||||
|
||||
### From Tool to Platform
|
||||
|
||||
v3.7.0 represents a shift in CC Switch's positioning:
|
||||
|
||||
| Aspect | v3.6 | v3.7.0 |
|
||||
| ----------------- | ------------------------ | ---------------------------- |
|
||||
| **Identity** | Provider Switcher | AI CLI Management Platform |
|
||||
| **Scope** | Configuration Management | Ecosystem Management |
|
||||
| **Applications** | Claude + Codex | Claude + Codex + Gemini |
|
||||
| **Capabilities** | Switch configs | Extend capabilities (Skills) |
|
||||
| **Customization** | Manual editing | Visual management (Prompts) |
|
||||
| **Integration** | Isolated apps | Unified management (MCP) |
|
||||
|
||||
### Six Pillars of AI CLI Management
|
||||
|
||||
1. **Configuration Management** - Provider switching and management
|
||||
2. **Capability Extension** - Skills installation and lifecycle
|
||||
3. **Behavior Customization** - System prompt presets
|
||||
4. **Ecosystem Integration** - Deep links and sharing
|
||||
5. **Multi-AI Support** - Claude/Codex/Gemini
|
||||
6. **Intelligent Detection** - Conflict prevention
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **Windows**: Windows 10+
|
||||
- **macOS**: macOS 10.15 (Catalina)+
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### Download Links
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download:
|
||||
|
||||
- **Windows**: `CC-Switch-v3.7.0-Windows.msi` or `-Portable.zip`
|
||||
- **macOS**: `CC-Switch-v3.7.0-macOS.tar.gz` or `.zip`
|
||||
- **Linux**: `CC-Switch-v3.7.0-Linux.AppImage` or `.deb`
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
### From v3.6.x
|
||||
|
||||
**Automatic migration** - No action required, configs are fully compatible
|
||||
|
||||
### From v3.1.x or Earlier
|
||||
|
||||
**Two-step migration required**:
|
||||
|
||||
1. First upgrade to v3.2.x (performs one-time migration)
|
||||
2. Then upgrade to v3.7.0
|
||||
|
||||
### New Features
|
||||
|
||||
- **Skills**: No migration needed, start fresh
|
||||
- **Prompts**: Auto-import from live files on first launch
|
||||
- **Gemini**: Install Gemini CLI separately if needed
|
||||
- **MCP v3.7.0**: Backward compatible with previous configs
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
### Contributors
|
||||
|
||||
Thanks to all contributors who made this release possible:
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - Skills & Prompts & Gemini integration implementation
|
||||
- [@farion1231](https://github.com/farion1231) - From developer to issue responder
|
||||
- Community members for testing and feedback
|
||||
|
||||
### Sponsors
|
||||
|
||||
**Z.ai** - GLM CODING PLAN sponsor
|
||||
[Get 10% OFF with this link](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API relay service partner
|
||||
[Register with "cc-switch" code for 10% discount](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
---
|
||||
|
||||
## Feedback & Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **Documentation**: [README](../README.md)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
**v3.8.0 Preview** (Tentative):
|
||||
|
||||
- Local proxy functionality
|
||||
|
||||
Stay tuned for more updates!
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -1,435 +0,0 @@
|
||||
# CC Switch v3.7.0
|
||||
|
||||
> 从供应商切换器到 AI CLI 一体化管理平台
|
||||
|
||||
**[English Version →](release-note-v3.7.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.7.0 新增六大核心功能，新增超过 18,000 行代码。
|
||||
|
||||
**发布日期**：2025-11-19
|
||||
**提交数量**：从 v3.6.0 开始 85 个提交
|
||||
**代码变更**：152 个文件，+18,104 / -3,732 行
|
||||
|
||||
---
|
||||
|
||||
## 新增功能
|
||||
|
||||
### Gemini CLI 集成
|
||||
|
||||
完整支持 Google Gemini CLI，成为第三个支持的应用（Claude Code、Codex、Gemini）。
|
||||
|
||||
**核心能力**：
|
||||
|
||||
- **双文件配置** - 同时支持 `.env` 和 `settings.json` 格式
|
||||
- **自动检测** - 自动检测 `GOOGLE_GEMINI_BASE_URL`、`GEMINI_MODEL` 等环境变量
|
||||
- **完整 MCP 支持** - 为 Gemini 提供完整的 MCP 服务器管理
|
||||
- **深度链接集成** - 通过 `ccswitch://` 协议导入配置
|
||||
- **系统托盘** - 从托盘菜单快速切换
|
||||
|
||||
**供应商预设**：
|
||||
|
||||
- **Google Official** - 支持 OAuth 认证
|
||||
- **PackyCode** - 合作伙伴集成
|
||||
- **自定义** - 完全自定义支持
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- 新增后端模块：`gemini_config.rs`（20KB）、`gemini_mcp.rs`
|
||||
- 表单与环境编辑器同步
|
||||
- 双文件原子写入
|
||||
|
||||
---
|
||||
|
||||
### MCP v3.7.0 统一架构
|
||||
|
||||
MCP 管理系统完整重构，实现跨应用统一管理。
|
||||
|
||||
**架构改进**：
|
||||
|
||||
- **统一管理面板** - 单一界面管理 Claude/Codex/Gemini MCP 服务器
|
||||
- **SSE 传输类型** - 新增 Server-Sent Events 支持
|
||||
- **智能解析器** - 容错性 JSON 解析
|
||||
- **格式修正** - 自动修复 Codex `[mcp_servers]` 格式
|
||||
- **扩展字段** - 保留自定义 TOML 字段
|
||||
|
||||
**用户体验**：
|
||||
|
||||
- 表单中的默认应用选择
|
||||
- JSON 格式化器用于验证
|
||||
- 改进的视觉层次
|
||||
- 更好的错误消息
|
||||
|
||||
**导入/导出**：
|
||||
|
||||
- 统一从三个应用导入
|
||||
- 双向同步
|
||||
- 状态保持
|
||||
|
||||
---
|
||||
|
||||
### Claude Skills 管理系统
|
||||
|
||||
**约 2,000 行代码** - 完整的技能生态平台。
|
||||
|
||||
**GitHub 集成**：
|
||||
|
||||
- 从 GitHub 仓库自动扫描技能
|
||||
- 预配置仓库：
|
||||
- `ComposioHQ/awesome-claude-skills` - 精选集合
|
||||
- `anthropics/skills` - Anthropic 官方技能
|
||||
- `cexll/myclaude` - 社区贡献
|
||||
- 添加自定义仓库
|
||||
- 子目录扫描支持（`skillsPath`）
|
||||
|
||||
**生命周期管理**：
|
||||
|
||||
- **发现** - 自动检测 `SKILL.md` 文件
|
||||
- **安装** - 一键安装到 `~/.claude/skills/`
|
||||
- **卸载** - 安全移除并跟踪状态
|
||||
- **更新** - 检查更新（基础设施已就绪）
|
||||
|
||||
**技术架构**：
|
||||
|
||||
- **后端**：`SkillService`（526 行）集成 GitHub API
|
||||
- **前端**：SkillsPage、SkillCard、RepoManager
|
||||
- **UI 组件**：Badge、Card、Table（shadcn/ui）
|
||||
- **状态**：持久化存储在 `skills.json`
|
||||
- **国际化**：47+ 个翻译键
|
||||
|
||||
---
|
||||
|
||||
### Prompts 管理系统
|
||||
|
||||
**约 1,300 行代码** - 完整的系统提示词管理。
|
||||
|
||||
**多预设管理**：
|
||||
|
||||
- 创建无限数量的提示词预设
|
||||
- 快速在预设间切换
|
||||
- 同时只能激活一个提示词
|
||||
- 活动提示词删除保护
|
||||
|
||||
**跨应用支持**：
|
||||
|
||||
- **Claude**：`~/.claude/CLAUDE.md`
|
||||
- **Codex**：`~/.codex/AGENTS.md`
|
||||
- **Gemini**：`~/.gemini/GEMINI.md`
|
||||
|
||||
**Markdown 编辑器**：
|
||||
|
||||
- 完整的 CodeMirror 6 集成
|
||||
- 语法高亮
|
||||
- 暗色主题（One Dark）
|
||||
- 实时预览
|
||||
|
||||
**智能同步**：
|
||||
|
||||
- **自动写入** - 立即写入 live 文件
|
||||
- **回填保护** - 切换前保存当前内容
|
||||
- **自动导入** - 首次启动从 live 文件导入
|
||||
- **修改保护** - 保留手动修改
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- **后端**：`PromptService`（213 行）
|
||||
- **前端**：PromptPanel（177）、PromptFormModal（160）、MarkdownEditor（159）
|
||||
- **Hooks**：usePromptActions（152 行）
|
||||
- **国际化**：41+ 个翻译键
|
||||
|
||||
---
|
||||
|
||||
### 深度链接协议（ccswitch://）
|
||||
|
||||
通过 URL 方案一键导入供应商配置。
|
||||
|
||||
**功能特性**：
|
||||
|
||||
- 所有平台的协议注册
|
||||
- 从共享链接导入
|
||||
- 生命周期集成
|
||||
- 安全验证
|
||||
|
||||
---
|
||||
|
||||
### 环境变量冲突检测
|
||||
|
||||
智能检测和管理配置冲突。
|
||||
|
||||
**检测范围**：
|
||||
|
||||
- **Claude & Codex** - 跨应用冲突
|
||||
- **Gemini** - 自动发现
|
||||
- **MCP** - 服务器配置冲突
|
||||
|
||||
**管理功能**：
|
||||
|
||||
- 可视化冲突指示器
|
||||
- 解决建议
|
||||
- 覆盖警告
|
||||
- 更改前备份
|
||||
|
||||
---
|
||||
|
||||
## 改进优化
|
||||
|
||||
### 供应商管理
|
||||
|
||||
**新增预设**：
|
||||
|
||||
- **DouBaoSeed** - 字节跳动的豆包
|
||||
- **Kimi For Coding** - 月之暗面
|
||||
- **BaiLing** - 百灵 AI
|
||||
- **移除 AnyRouter** - 避免误导
|
||||
|
||||
**增强功能**：
|
||||
|
||||
- Codex 和 Gemini 的模型名称配置
|
||||
- 供应商备注字段用于组织
|
||||
- 增强的预设元数据
|
||||
|
||||
### 配置管理
|
||||
|
||||
- **通用配置迁移** - 从 localStorage 迁移到 `config.json`
|
||||
- **统一持久化** - 跨所有应用共享
|
||||
- **自动导入** - 首次启动配置导入
|
||||
- **回填优先级** - 正确处理 live 文件
|
||||
|
||||
### UI/UX 改进
|
||||
|
||||
**设计系统**：
|
||||
|
||||
- **macOS 原生** - 与系统对齐的配色方案
|
||||
- **窗口居中** - 默认居中位置
|
||||
- **视觉优化** - 改进的间距和层次
|
||||
|
||||
**交互优化**：
|
||||
|
||||
- **密码输入** - 修复 Edge/IE 显示按钮
|
||||
- **URL 溢出** - 修复卡片溢出
|
||||
- **错误复制** - 可复制到剪贴板的错误
|
||||
- **托盘同步** - 实时拖放同步
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 关键修复
|
||||
|
||||
- **用量脚本验证** - 边界检查
|
||||
- **Gemini 验证** - 放宽约束
|
||||
- **TOML 解析** - CJK 引号处理
|
||||
- **MCP 字段** - 自定义字段保留
|
||||
- **白屏** - FormLabel 崩溃修复
|
||||
|
||||
### 稳定性
|
||||
|
||||
- **托盘安全** - 模式匹配替代 unwrap
|
||||
- **错误隔离** - 托盘失败不阻塞操作
|
||||
- **导入分类** - 正确的类别分配
|
||||
|
||||
### UI 修复
|
||||
|
||||
- **模型占位符** - 移除误导性提示
|
||||
- **Base URL** - 第三方供应商自动填充
|
||||
- **拖拽排序** - 托盘菜单同步
|
||||
|
||||
---
|
||||
|
||||
## 技术改进
|
||||
|
||||
### 架构
|
||||
|
||||
**MCP v3.7.0**：
|
||||
|
||||
- 移除遗留代码（约 1,000 行）
|
||||
- 统一初始化结构
|
||||
- 保持向后兼容性
|
||||
- 全面的代码格式化
|
||||
|
||||
**平台兼容性**：
|
||||
|
||||
- Windows winreg API 修复（v0.52）
|
||||
- 安全模式匹配（无 `unwrap()`）
|
||||
- 跨平台托盘处理
|
||||
|
||||
### 配置
|
||||
|
||||
**同步机制**：
|
||||
|
||||
- 跨所有应用的 MCP 同步
|
||||
- Gemini 表单-编辑器同步
|
||||
- 双文件读取（.env + settings.json）
|
||||
|
||||
**验证增强**：
|
||||
|
||||
- 输入边界检查
|
||||
- TOML 引号规范化（CJK）
|
||||
- 自定义字段保留
|
||||
- 增强的错误消息
|
||||
|
||||
### 代码质量
|
||||
|
||||
**类型安全**：
|
||||
|
||||
- 完整的 TypeScript 覆盖
|
||||
- Rust 类型改进
|
||||
- API 契约验证
|
||||
|
||||
**测试**：
|
||||
|
||||
- 简化的断言
|
||||
- 更好的测试覆盖
|
||||
- 集成测试更新
|
||||
|
||||
**依赖项**：
|
||||
|
||||
- Tauri 2.8.x
|
||||
- Rust：`anyhow`、`zip`、`serde_yaml`、`tempfile`
|
||||
- 前端：CodeMirror 6 包
|
||||
- winreg 0.52（Windows）
|
||||
|
||||
---
|
||||
|
||||
## 技术统计
|
||||
|
||||
```
|
||||
总体变更：
|
||||
- 提交数：85
|
||||
- 文件数：152 个文件变更
|
||||
- 新增：+18,104 行
|
||||
- 删除：-3,732 行
|
||||
|
||||
新增模块：
|
||||
- Skills 管理：2,034 行（21 个文件）
|
||||
- Prompts 管理：1,302 行（20 个文件）
|
||||
- Gemini 集成：约 1,000 行
|
||||
- MCP 重构：约 3,000 行重构
|
||||
|
||||
代码分布：
|
||||
- 后端（Rust）：约 4,500 行新增
|
||||
- 前端（React）：约 3,000 行新增
|
||||
- 配置：约 1,500 行重构
|
||||
- 测试：约 500 行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 战略定位
|
||||
|
||||
### 从工具到平台
|
||||
|
||||
v3.7.0 代表了 CC Switch 定位的转变：
|
||||
|
||||
| 方面 | v3.6 | v3.7.0 |
|
||||
| -------- | -------------- | ----------------------- |
|
||||
| **身份** | 供应商切换器 | AI CLI 管理平台 |
|
||||
| **范围** | 配置管理 | 生态系统管理 |
|
||||
| **应用** | Claude + Codex | Claude + Codex + Gemini |
|
||||
| **能力** | 切换配置 | 扩展能力（Skills） |
|
||||
| **定制** | 手动编辑 | 可视化管理（Prompts） |
|
||||
| **集成** | 孤立应用 | 统一管理（MCP） |
|
||||
|
||||
### AI CLI 管理六大支柱
|
||||
|
||||
1. **配置管理** - 供应商切换和管理
|
||||
2. **能力扩展** - Skills 安装和生命周期
|
||||
3. **行为定制** - 系统提示词预设
|
||||
4. **生态集成** - 深度链接和共享
|
||||
5. **多 AI 支持** - Claude/Codex/Gemini
|
||||
6. **智能检测** - 冲突预防
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
### 系统要求
|
||||
|
||||
- **Windows**：Windows 10+
|
||||
- **macOS**：macOS 10.15（Catalina）+
|
||||
- **Linux**：Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### 下载链接
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载：
|
||||
|
||||
- **Windows**：`CC-Switch-v3.7.0-Windows.msi` 或 `-Portable.zip`
|
||||
- **macOS**：`CC-Switch-v3.7.0-macOS.tar.gz` 或 `.zip`
|
||||
- **Linux**：`CC-Switch-v3.7.0-Linux.AppImage` 或 `.deb`
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 迁移说明
|
||||
|
||||
### 从 v3.6.x 升级
|
||||
|
||||
**自动迁移** - 无需任何操作，配置完全兼容
|
||||
|
||||
### 从 v3.1.x 或更早版本升级
|
||||
|
||||
**需要两步迁移**：
|
||||
|
||||
1. 首先升级到 v3.2.x（执行一次性迁移）
|
||||
2. 然后升级到 v3.7.0
|
||||
|
||||
### 新功能
|
||||
|
||||
- **Skills**：无需迁移，全新开始
|
||||
- **Prompts**：首次启动时从 live 文件自动导入
|
||||
- **Gemini**：需要单独安装 Gemini CLI
|
||||
- **MCP v3.7.0**：与之前的配置向后兼容
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
### 贡献者
|
||||
|
||||
感谢所有让这个版本成为可能的贡献者：
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - Skills & Prompts & Geimini 集成实现
|
||||
- [@farion1231](https://github.com/farion1231) - 从开发沦为 issue 回复机
|
||||
- 社区成员的测试和反馈
|
||||
|
||||
### 赞助商
|
||||
|
||||
**Z.ai** - GLM CODING PLAN 赞助商
|
||||
[通过此链接获得 10% 折扣](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API 中继服务合作伙伴
|
||||
[使用 "cc-switch" 代码注册可享受 10% 折扣](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
---
|
||||
|
||||
## 反馈与支持
|
||||
|
||||
- **问题反馈**：[GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **讨论**：[GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **文档**：[README](../README_ZH.md)
|
||||
- **更新日志**：[CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 未来展望
|
||||
|
||||
**v3.8.0 预览**（暂定）：
|
||||
|
||||
- 本地代理功能
|
||||
|
||||
敬请期待更多更新！
|
||||
@@ -1,481 +0,0 @@
|
||||
# CC Switch v3.7.1
|
||||
|
||||
> Stability Enhancements and User Experience Improvements
|
||||
|
||||
**[中文更新说明 Chinese Documentation →](release-note-v3.7.1-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## v3.7.1 Updates
|
||||
|
||||
**Release Date**: 2025-11-22
|
||||
**Code Changes**: 17 files, +524 / -81 lines
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- **Fix Third-Party Skills Installation Failure** (#268)
|
||||
Fixed installation issues for skills repositories with custom subdirectories, now supports repos like `ComposioHQ/awesome-claude-skills` with subdirectories
|
||||
|
||||
- **Fix Gemini Configuration Persistence Issue**
|
||||
Resolved the issue where settings.json edits in Gemini form were lost when switching providers
|
||||
|
||||
- **Prevent Dialogs from Closing on Overlay Click**
|
||||
Added protection against clicking overlay/backdrop, preventing accidental form data loss across all 11 dialog components
|
||||
|
||||
### New Features
|
||||
|
||||
- **Gemini Configuration Directory Support** (#255)
|
||||
Added Gemini configuration directory option in settings, supports customizing `~/.gemini/` path
|
||||
|
||||
- **ArchLinux Installation Support** (#259)
|
||||
Added AUR installation method: `paru -S cc-switch-bin`
|
||||
|
||||
### Improvements
|
||||
|
||||
- **Skills Error Message i18n Enhancement**
|
||||
Added 28+ detailed error messages (English & Chinese) with specific resolution suggestions, extended download timeout from 15s to 60s
|
||||
|
||||
- **Code Formatting**
|
||||
Applied unified Rust and TypeScript code formatting standards
|
||||
|
||||
### Download
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the latest version
|
||||
|
||||
---
|
||||
|
||||
## v3.7.0 Complete Release Notes
|
||||
|
||||
> From Provider Switcher to All-in-One AI CLI Management Platform
|
||||
|
||||
**Release Date**: 2025-11-19
|
||||
**Commits**: 85 from v3.6.0
|
||||
**Code Changes**: 152 files, +18,104 / -3,732 lines
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### Gemini CLI Integration
|
||||
|
||||
Complete support for Google Gemini CLI, becoming the third supported application (Claude Code, Codex, Gemini).
|
||||
|
||||
**Core Capabilities**:
|
||||
|
||||
- **Dual-file configuration** - Support for both `.env` and `settings.json` formats
|
||||
- **Auto-detection** - Automatically detect `GOOGLE_GEMINI_BASE_URL`, `GEMINI_MODEL`, etc.
|
||||
- **Full MCP support** - Complete MCP server management for Gemini
|
||||
- **Deep link integration** - Import via `ccswitch://` protocol
|
||||
- **System tray** - Quick-switch from tray menu
|
||||
|
||||
**Provider Presets**:
|
||||
|
||||
- **Google Official** - OAuth authentication support
|
||||
- **PackyCode** - Partner integration
|
||||
- **Custom** - Full customization support
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- New backend modules: `gemini_config.rs` (20KB), `gemini_mcp.rs`
|
||||
- Form synchronization with environment editor
|
||||
- Dual-file atomic writes
|
||||
|
||||
---
|
||||
|
||||
### MCP v3.7.0 Unified Architecture
|
||||
|
||||
Complete refactoring of MCP management system for cross-application unification.
|
||||
|
||||
**Architecture Improvements**:
|
||||
|
||||
- **Unified panel** - Single interface for Claude/Codex/Gemini MCP servers
|
||||
- **SSE transport** - New Server-Sent Events support
|
||||
- **Smart parser** - Fault-tolerant JSON parsing
|
||||
- **Format correction** - Auto-fix Codex `[mcp_servers]` format
|
||||
- **Extended fields** - Preserve custom TOML fields
|
||||
|
||||
**User Experience**:
|
||||
|
||||
- Default app selection in forms
|
||||
- JSON formatter for validation
|
||||
- Improved visual hierarchy
|
||||
- Better error messages
|
||||
|
||||
**Import/Export**:
|
||||
|
||||
- Unified import from all three apps
|
||||
- Bidirectional synchronization
|
||||
- State preservation
|
||||
|
||||
---
|
||||
|
||||
### Claude Skills Management System
|
||||
|
||||
**Approximately 2,000 lines of code** - A complete skill ecosystem platform.
|
||||
|
||||
**GitHub Integration**:
|
||||
|
||||
- Auto-scan skills from GitHub repositories
|
||||
- Pre-configured repos:
|
||||
- `ComposioHQ/awesome-claude-skills` - Curated collection
|
||||
- `anthropics/skills` - Official Anthropic skills
|
||||
- `cexll/myclaude` - Community contributions
|
||||
- Add custom repositories
|
||||
- Subdirectory scanning support (`skillsPath`)
|
||||
|
||||
**Lifecycle Management**:
|
||||
|
||||
- **Discover** - Auto-detect `SKILL.md` files
|
||||
- **Install** - One-click to `~/.claude/skills/`
|
||||
- **Uninstall** - Safe removal with tracking
|
||||
- **Update** - Check for updates (infrastructure ready)
|
||||
|
||||
**Technical Architecture**:
|
||||
|
||||
- **Backend**: `SkillService` (526 lines) with GitHub API integration
|
||||
- **Frontend**: SkillsPage, SkillCard, RepoManager
|
||||
- **UI Components**: Badge, Card, Table (shadcn/ui)
|
||||
- **State**: Persistent storage in `config.json`
|
||||
- **i18n**: 47+ translation keys
|
||||
|
||||
---
|
||||
|
||||
### Prompts Management System
|
||||
|
||||
**Approximately 1,300 lines of code** - Complete system prompt management.
|
||||
|
||||
**Multi-Preset Management**:
|
||||
|
||||
- Create unlimited prompt presets
|
||||
- Quick switch between presets
|
||||
- One active prompt at a time
|
||||
- Delete protection for active prompts
|
||||
|
||||
**Cross-App Support**:
|
||||
|
||||
- **Claude**: `~/.claude/CLAUDE.md`
|
||||
- **Codex**: `~/.codex/AGENTS.md`
|
||||
- **Gemini**: `~/.gemini/GEMINI.md`
|
||||
|
||||
**Markdown Editor**:
|
||||
|
||||
- Full-featured CodeMirror 6 integration
|
||||
- Syntax highlighting
|
||||
- Dark theme (One Dark)
|
||||
- Real-time preview
|
||||
|
||||
**Smart Synchronization**:
|
||||
|
||||
- **Auto-write** - Immediately write to live files
|
||||
- **Backfill protection** - Save current content before switching
|
||||
- **Auto-import** - Import from live files on first launch
|
||||
- **Modification protection** - Preserve manual modifications
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- **Backend**: `PromptService` (213 lines)
|
||||
- **Frontend**: PromptPanel (177), PromptFormModal (160), MarkdownEditor (159)
|
||||
- **Hooks**: usePromptActions (152 lines)
|
||||
- **i18n**: 41+ translation keys
|
||||
|
||||
---
|
||||
|
||||
### Deep Link Protocol (ccswitch://)
|
||||
|
||||
One-click provider configuration import via URL scheme.
|
||||
|
||||
**Features**:
|
||||
|
||||
- Protocol registration on all platforms
|
||||
- Import from shared links
|
||||
- Lifecycle integration
|
||||
- Security validation
|
||||
|
||||
---
|
||||
|
||||
### Environment Variable Conflict Detection
|
||||
|
||||
Intelligent detection and management of configuration conflicts.
|
||||
|
||||
**Detection Scope**:
|
||||
|
||||
- **Claude & Codex** - Cross-app conflicts
|
||||
- **Gemini** - Auto-discovery
|
||||
- **MCP** - Server configuration conflicts
|
||||
|
||||
**Management Features**:
|
||||
|
||||
- Visual conflict indicators
|
||||
- Resolution suggestions
|
||||
- Override warnings
|
||||
- Backup before changes
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
### Provider Management
|
||||
|
||||
**New Presets**:
|
||||
|
||||
- **DouBaoSeed** - ByteDance's DouBao
|
||||
- **Kimi For Coding** - Moonshot AI
|
||||
- **BaiLing** - BaiLing AI
|
||||
- **Removed AnyRouter** - To avoid confusion
|
||||
|
||||
**Enhancements**:
|
||||
|
||||
- Model name configuration for Codex and Gemini
|
||||
- Provider notes field for organization
|
||||
- Enhanced preset metadata
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- **Common config migration** - From localStorage to `config.json`
|
||||
- **Unified persistence** - Shared across all apps
|
||||
- **Auto-import** - First launch configuration import
|
||||
- **Backfill priority** - Correct handling of live files
|
||||
|
||||
### UI/UX Improvements
|
||||
|
||||
**Design System**:
|
||||
|
||||
- **macOS native** - System-aligned color scheme
|
||||
- **Window centering** - Default centered position
|
||||
- **Visual polish** - Improved spacing and hierarchy
|
||||
|
||||
**Interactions**:
|
||||
|
||||
- **Password input** - Fixed Edge/IE reveal buttons
|
||||
- **URL overflow** - Fixed card overflow
|
||||
- **Error copying** - Copy-to-clipboard errors
|
||||
- **Tray sync** - Real-time drag-and-drop sync
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Critical Fixes
|
||||
|
||||
- **Usage script validation** - Boundary checks
|
||||
- **Gemini validation** - Relaxed constraints
|
||||
- **TOML parsing** - CJK quote handling
|
||||
- **MCP fields** - Custom field preservation
|
||||
- **White screen** - FormLabel crash fix
|
||||
|
||||
### Stability
|
||||
|
||||
- **Tray safety** - Pattern matching instead of unwrap
|
||||
- **Error isolation** - Tray failures don't block operations
|
||||
- **Import classification** - Correct category assignment
|
||||
|
||||
### UI Fixes
|
||||
|
||||
- **Model placeholders** - Removed misleading hints
|
||||
- **Base URL** - Auto-fill for third-party providers
|
||||
- **Drag sort** - Tray menu synchronization
|
||||
|
||||
---
|
||||
|
||||
## Technical Improvements
|
||||
|
||||
### Architecture
|
||||
|
||||
**MCP v3.7.0**:
|
||||
|
||||
- Removed legacy code (~1,000 lines)
|
||||
- Unified initialization structure
|
||||
- Backward compatibility maintained
|
||||
- Comprehensive code formatting
|
||||
|
||||
**Platform Compatibility**:
|
||||
|
||||
- Windows winreg API fix (v0.52)
|
||||
- Safe pattern matching (no `unwrap()`)
|
||||
- Cross-platform tray handling
|
||||
|
||||
### Configuration
|
||||
|
||||
**Synchronization**:
|
||||
|
||||
- MCP sync across all apps
|
||||
- Gemini form-editor sync
|
||||
- Dual-file reading (.env + settings.json)
|
||||
|
||||
**Validation**:
|
||||
|
||||
- Input boundary checks
|
||||
- TOML quote normalization (CJK)
|
||||
- Custom field preservation
|
||||
- Enhanced error messages
|
||||
|
||||
### Code Quality
|
||||
|
||||
**Type Safety**:
|
||||
|
||||
- Complete TypeScript coverage
|
||||
- Rust type refinements
|
||||
- API contract validation
|
||||
|
||||
**Testing**:
|
||||
|
||||
- Simplified assertions
|
||||
- Better test coverage
|
||||
- Integration test updates
|
||||
|
||||
**Dependencies**:
|
||||
|
||||
- Tauri 2.8.x
|
||||
- Rust: `anyhow`, `zip`, `serde_yaml`, `tempfile`
|
||||
- Frontend: CodeMirror 6 packages
|
||||
- winreg 0.52 (Windows)
|
||||
|
||||
---
|
||||
|
||||
## Technical Statistics
|
||||
|
||||
```
|
||||
Total Changes:
|
||||
- Commits: 85
|
||||
- Files: 152 changed
|
||||
- Additions: +18,104 lines
|
||||
- Deletions: -3,732 lines
|
||||
|
||||
New Modules:
|
||||
- Skills Management: 2,034 lines (21 files)
|
||||
- Prompts Management: 1,302 lines (20 files)
|
||||
- Gemini Integration: ~1,000 lines
|
||||
- MCP Refactor: ~3,000 lines refactored
|
||||
|
||||
Code Distribution:
|
||||
- Backend (Rust): ~4,500 lines new
|
||||
- Frontend (React): ~3,000 lines new
|
||||
- Configuration: ~1,500 lines refactored
|
||||
- Tests: ~500 lines
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Strategic Positioning
|
||||
|
||||
### From Tool to Platform
|
||||
|
||||
v3.7.0 represents a shift in CC Switch's positioning:
|
||||
|
||||
| Aspect | v3.6 | v3.7.0 |
|
||||
| ----------------- | ------------------------ | ---------------------------- |
|
||||
| **Identity** | Provider Switcher | AI CLI Management Platform |
|
||||
| **Scope** | Configuration Management | Ecosystem Management |
|
||||
| **Applications** | Claude + Codex | Claude + Codex + Gemini |
|
||||
| **Capabilities** | Switch configs | Extend capabilities (Skills) |
|
||||
| **Customization** | Manual editing | Visual management (Prompts) |
|
||||
| **Integration** | Isolated apps | Unified management (MCP) |
|
||||
|
||||
### Six Pillars of AI CLI Management
|
||||
|
||||
1. **Configuration Management** - Provider switching and management
|
||||
2. **Capability Extension** - Skills installation and lifecycle
|
||||
3. **Behavior Customization** - System prompt presets
|
||||
4. **Ecosystem Integration** - Deep links and sharing
|
||||
5. **Multi-AI Support** - Claude/Codex/Gemini
|
||||
6. **Intelligent Detection** - Conflict prevention
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **Windows**: Windows 10+
|
||||
- **macOS**: macOS 10.15 (Catalina)+
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ / ArchLinux
|
||||
|
||||
### Download Links
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download:
|
||||
|
||||
- **Windows**: `CC-Switch-Windows.msi` or `-Portable.zip`
|
||||
- **macOS**: `CC-Switch-macOS.tar.gz` or `.zip`
|
||||
- **Linux**: `CC-Switch-Linux.AppImage` or `.deb`
|
||||
- **ArchLinux**: `paru -S cc-switch-bin`
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
### From v3.6.x
|
||||
|
||||
**Automatic migration** - No action required, configs are fully compatible
|
||||
|
||||
### From v3.1.x or Earlier
|
||||
|
||||
**Two-step migration required**:
|
||||
|
||||
1. First upgrade to v3.2.x (performs one-time migration)
|
||||
2. Then upgrade to v3.7.0
|
||||
|
||||
### New Features
|
||||
|
||||
- **Skills**: No migration needed, start fresh
|
||||
- **Prompts**: Auto-import from live files on first launch
|
||||
- **Gemini**: Install Gemini CLI separately if needed
|
||||
- **MCP v3.7.0**: Backward compatible with previous configs
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
### Contributors
|
||||
|
||||
Thanks to all contributors who made this release possible:
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - Skills & Prompts & Gemini integration implementation
|
||||
- [@farion1231](https://github.com/farion1231) - From developer to issue responder
|
||||
- Community members for testing and feedback
|
||||
|
||||
### Sponsors
|
||||
|
||||
**Z.ai** - GLM CODING PLAN sponsor
|
||||
[Get 10% OFF with this link](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API relay service partner
|
||||
[Register with "cc-switch" code for 10% discount](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**ShanDianShuo** - Local-first AI voice input
|
||||
[Free download](https://shandianshuo.cn) for Mac/Win
|
||||
|
||||
---
|
||||
|
||||
## Feedback & Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **Documentation**: [README](../README.md)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
**v3.8.0 Preview** (Tentative):
|
||||
|
||||
- Local proxy functionality
|
||||
|
||||
Stay tuned for more updates!
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -1,481 +0,0 @@
|
||||
# CC Switch v3.7.1
|
||||
|
||||
> 稳定性增强与用户体验改进
|
||||
|
||||
**[English Version →](release-note-v3.7.1-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## v3.7.1 更新内容
|
||||
|
||||
**发布日期**：2025-11-22
|
||||
**代码变更**：17 个文件，+524 / -81 行
|
||||
|
||||
### Bug 修复
|
||||
|
||||
- **修复 Skills 第三方仓库安装失败** (#268)
|
||||
修复使用自定义子目录的 skills 仓库无法安装的问题，支持类似 `ComposioHQ/awesome-claude-skills` 这样带子目录的仓库
|
||||
|
||||
- **修复 Gemini 配置持久化问题**
|
||||
解决在 Gemini 表单中编辑 settings.json 后，切换供应商时修改丢失的问题
|
||||
|
||||
- **防止对话框意外关闭**
|
||||
添加点击遮罩时的保护，避免误操作导致表单数据丢失，影响所有 11 个对话框组件
|
||||
|
||||
### 新增功能
|
||||
|
||||
- **Gemini 配置目录支持** (#255)
|
||||
在设置中添加 Gemini 配置目录选项，支持自定义 `~/.gemini/` 路径
|
||||
|
||||
- **ArchLinux 安装支持** (#259)
|
||||
添加 AUR 安装方式：`paru -S cc-switch-bin`
|
||||
|
||||
### 改进
|
||||
|
||||
- **Skills 错误消息国际化增强**
|
||||
新增 28+ 条详细错误消息（中英文），提供具体的解决建议，下载超时从 15 秒延长到 60 秒
|
||||
|
||||
- **代码格式化**
|
||||
应用统一的 Rust 和 TypeScript 代码格式化标准
|
||||
|
||||
### 下载
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载最新版本
|
||||
|
||||
---
|
||||
|
||||
## v3.7.0 完整更新说明
|
||||
|
||||
> 从供应商切换器到 AI CLI 一体化管理平台
|
||||
|
||||
**发布日期**：2025-11-19
|
||||
**提交数量**：从 v3.6.0 开始 85 个提交
|
||||
**代码变更**：152 个文件，+18,104 / -3,732 行
|
||||
|
||||
---
|
||||
|
||||
## 新增功能
|
||||
|
||||
### Gemini CLI 集成
|
||||
|
||||
完整支持 Google Gemini CLI，成为第三个支持的应用（Claude Code、Codex、Gemini）。
|
||||
|
||||
**核心能力**：
|
||||
|
||||
- **双文件配置** - 同时支持 `.env` 和 `settings.json` 格式
|
||||
- **自动检测** - 自动检测 `GOOGLE_GEMINI_BASE_URL`、`GEMINI_MODEL` 等环境变量
|
||||
- **完整 MCP 支持** - 为 Gemini 提供完整的 MCP 服务器管理
|
||||
- **深度链接集成** - 通过 `ccswitch://` 协议导入配置
|
||||
- **系统托盘** - 从托盘菜单快速切换
|
||||
|
||||
**供应商预设**：
|
||||
|
||||
- **Google Official** - 支持 OAuth 认证
|
||||
- **PackyCode** - 合作伙伴集成
|
||||
- **自定义** - 完全自定义支持
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- 新增后端模块：`gemini_config.rs`（20KB）、`gemini_mcp.rs`
|
||||
- 表单与环境编辑器同步
|
||||
- 双文件原子写入
|
||||
|
||||
---
|
||||
|
||||
### MCP v3.7.0 统一架构
|
||||
|
||||
MCP 管理系统完整重构，实现跨应用统一管理。
|
||||
|
||||
**架构改进**：
|
||||
|
||||
- **统一管理面板** - 单一界面管理 Claude/Codex/Gemini MCP 服务器
|
||||
- **SSE 传输类型** - 新增 Server-Sent Events 支持
|
||||
- **智能解析器** - 容错性 JSON 解析
|
||||
- **格式修正** - 自动修复 Codex `[mcp_servers]` 格式
|
||||
- **扩展字段** - 保留自定义 TOML 字段
|
||||
|
||||
**用户体验**：
|
||||
|
||||
- 表单中的默认应用选择
|
||||
- JSON 格式化器用于验证
|
||||
- 改进的视觉层次
|
||||
- 更好的错误消息
|
||||
|
||||
**导入/导出**：
|
||||
|
||||
- 统一从三个应用导入
|
||||
- 双向同步
|
||||
- 状态保持
|
||||
|
||||
---
|
||||
|
||||
### Claude Skills 管理系统
|
||||
|
||||
**约 2,000 行代码** - 完整的技能生态平台。
|
||||
|
||||
**GitHub 集成**：
|
||||
|
||||
- 从 GitHub 仓库自动扫描技能
|
||||
- 预配置仓库：
|
||||
- `ComposioHQ/awesome-claude-skills` - 精选集合
|
||||
- `anthropics/skills` - Anthropic 官方技能
|
||||
- `cexll/myclaude` - 社区贡献
|
||||
- 添加自定义仓库
|
||||
- 子目录扫描支持（`skillsPath`）
|
||||
|
||||
**生命周期管理**：
|
||||
|
||||
- **发现** - 自动检测 `SKILL.md` 文件
|
||||
- **安装** - 一键安装到 `~/.claude/skills/`
|
||||
- **卸载** - 安全移除并跟踪状态
|
||||
- **更新** - 检查更新（基础设施已就绪）
|
||||
|
||||
**技术架构**：
|
||||
|
||||
- **后端**：`SkillService`（526 行）集成 GitHub API
|
||||
- **前端**：SkillsPage、SkillCard、RepoManager
|
||||
- **UI 组件**：Badge、Card、Table（shadcn/ui）
|
||||
- **状态**：持久化存储在 `config.json`
|
||||
- **国际化**：47+ 个翻译键
|
||||
|
||||
---
|
||||
|
||||
### Prompts 管理系统
|
||||
|
||||
**约 1,300 行代码** - 完整的系统提示词管理。
|
||||
|
||||
**多预设管理**：
|
||||
|
||||
- 创建无限数量的提示词预设
|
||||
- 快速在预设间切换
|
||||
- 同时只能激活一个提示词
|
||||
- 活动提示词删除保护
|
||||
|
||||
**跨应用支持**：
|
||||
|
||||
- **Claude**：`~/.claude/CLAUDE.md`
|
||||
- **Codex**：`~/.codex/AGENTS.md`
|
||||
- **Gemini**：`~/.gemini/GEMINI.md`
|
||||
|
||||
**Markdown 编辑器**：
|
||||
|
||||
- 完整的 CodeMirror 6 集成
|
||||
- 语法高亮
|
||||
- 暗色主题（One Dark）
|
||||
- 实时预览
|
||||
|
||||
**智能同步**：
|
||||
|
||||
- **自动写入** - 立即写入 live 文件
|
||||
- **回填保护** - 切换前保存当前内容
|
||||
- **自动导入** - 首次启动从 live 文件导入
|
||||
- **修改保护** - 保留手动修改
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- **后端**：`PromptService`（213 行）
|
||||
- **前端**：PromptPanel（177）、PromptFormModal（160）、MarkdownEditor（159）
|
||||
- **Hooks**：usePromptActions（152 行）
|
||||
- **国际化**：41+ 个翻译键
|
||||
|
||||
---
|
||||
|
||||
### 深度链接协议（ccswitch://）
|
||||
|
||||
通过 URL 方案一键导入供应商配置。
|
||||
|
||||
**功能特性**：
|
||||
|
||||
- 所有平台的协议注册
|
||||
- 从共享链接导入
|
||||
- 生命周期集成
|
||||
- 安全验证
|
||||
|
||||
---
|
||||
|
||||
### 环境变量冲突检测
|
||||
|
||||
智能检测和管理配置冲突。
|
||||
|
||||
**检测范围**：
|
||||
|
||||
- **Claude & Codex** - 跨应用冲突
|
||||
- **Gemini** - 自动发现
|
||||
- **MCP** - 服务器配置冲突
|
||||
|
||||
**管理功能**：
|
||||
|
||||
- 可视化冲突指示器
|
||||
- 解决建议
|
||||
- 覆盖警告
|
||||
- 更改前备份
|
||||
|
||||
---
|
||||
|
||||
## 改进优化
|
||||
|
||||
### 供应商管理
|
||||
|
||||
**新增预设**：
|
||||
|
||||
- **DouBaoSeed** - 字节跳动的豆包
|
||||
- **Kimi For Coding** - 月之暗面
|
||||
- **BaiLing** - 百灵 AI
|
||||
- **移除 AnyRouter** - 避免误导
|
||||
|
||||
**增强功能**：
|
||||
|
||||
- Codex 和 Gemini 的模型名称配置
|
||||
- 供应商备注字段用于组织
|
||||
- 增强的预设元数据
|
||||
|
||||
### 配置管理
|
||||
|
||||
- **通用配置迁移** - 从 localStorage 迁移到 `config.json`
|
||||
- **统一持久化** - 跨所有应用共享
|
||||
- **自动导入** - 首次启动配置导入
|
||||
- **回填优先级** - 正确处理 live 文件
|
||||
|
||||
### UI/UX 改进
|
||||
|
||||
**设计系统**：
|
||||
|
||||
- **macOS 原生** - 与系统对齐的配色方案
|
||||
- **窗口居中** - 默认居中位置
|
||||
- **视觉优化** - 改进的间距和层次
|
||||
|
||||
**交互优化**：
|
||||
|
||||
- **密码输入** - 修复 Edge/IE 显示按钮
|
||||
- **URL 溢出** - 修复卡片溢出
|
||||
- **错误复制** - 可复制到剪贴板的错误
|
||||
- **托盘同步** - 实时拖放同步
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 关键修复
|
||||
|
||||
- **用量脚本验证** - 边界检查
|
||||
- **Gemini 验证** - 放宽约束
|
||||
- **TOML 解析** - CJK 引号处理
|
||||
- **MCP 字段** - 自定义字段保留
|
||||
- **白屏** - FormLabel 崩溃修复
|
||||
|
||||
### 稳定性
|
||||
|
||||
- **托盘安全** - 模式匹配替代 unwrap
|
||||
- **错误隔离** - 托盘失败不阻塞操作
|
||||
- **导入分类** - 正确的类别分配
|
||||
|
||||
### UI 修复
|
||||
|
||||
- **模型占位符** - 移除误导性提示
|
||||
- **Base URL** - 第三方供应商自动填充
|
||||
- **拖拽排序** - 托盘菜单同步
|
||||
|
||||
---
|
||||
|
||||
## 技术改进
|
||||
|
||||
### 架构
|
||||
|
||||
**MCP v3.7.0**：
|
||||
|
||||
- 移除遗留代码（约 1,000 行）
|
||||
- 统一初始化结构
|
||||
- 保持向后兼容性
|
||||
- 全面的代码格式化
|
||||
|
||||
**平台兼容性**：
|
||||
|
||||
- Windows winreg API 修复（v0.52）
|
||||
- 安全模式匹配（无 `unwrap()`）
|
||||
- 跨平台托盘处理
|
||||
|
||||
### 配置
|
||||
|
||||
**同步机制**：
|
||||
|
||||
- 跨所有应用的 MCP 同步
|
||||
- Gemini 表单-编辑器同步
|
||||
- 双文件读取（.env + settings.json）
|
||||
|
||||
**验证增强**：
|
||||
|
||||
- 输入边界检查
|
||||
- TOML 引号规范化（CJK）
|
||||
- 自定义字段保留
|
||||
- 增强的错误消息
|
||||
|
||||
### 代码质量
|
||||
|
||||
**类型安全**：
|
||||
|
||||
- 完整的 TypeScript 覆盖
|
||||
- Rust 类型改进
|
||||
- API 契约验证
|
||||
|
||||
**测试**：
|
||||
|
||||
- 简化的断言
|
||||
- 更好的测试覆盖
|
||||
- 集成测试更新
|
||||
|
||||
**依赖项**：
|
||||
|
||||
- Tauri 2.8.x
|
||||
- Rust：`anyhow`、`zip`、`serde_yaml`、`tempfile`
|
||||
- 前端：CodeMirror 6 包
|
||||
- winreg 0.52（Windows）
|
||||
|
||||
---
|
||||
|
||||
## 技术统计
|
||||
|
||||
```
|
||||
总体变更：
|
||||
- 提交数：85
|
||||
- 文件数：152 个文件变更
|
||||
- 新增：+18,104 行
|
||||
- 删除：-3,732 行
|
||||
|
||||
新增模块：
|
||||
- Skills 管理：2,034 行（21 个文件）
|
||||
- Prompts 管理：1,302 行（20 个文件）
|
||||
- Gemini 集成：约 1,000 行
|
||||
- MCP 重构：约 3,000 行重构
|
||||
|
||||
代码分布：
|
||||
- 后端（Rust）：约 4,500 行新增
|
||||
- 前端（React）：约 3,000 行新增
|
||||
- 配置：约 1,500 行重构
|
||||
- 测试：约 500 行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 战略定位
|
||||
|
||||
### 从工具到平台
|
||||
|
||||
v3.7.0 代表了 CC Switch 定位的转变：
|
||||
|
||||
| 方面 | v3.6 | v3.7.0 |
|
||||
| -------- | -------------- | ----------------------- |
|
||||
| **身份** | 供应商切换器 | AI CLI 管理平台 |
|
||||
| **范围** | 配置管理 | 生态系统管理 |
|
||||
| **应用** | Claude + Codex | Claude + Codex + Gemini |
|
||||
| **能力** | 切换配置 | 扩展能力（Skills） |
|
||||
| **定制** | 手动编辑 | 可视化管理（Prompts） |
|
||||
| **集成** | 孤立应用 | 统一管理（MCP） |
|
||||
|
||||
### AI CLI 管理六大支柱
|
||||
|
||||
1. **配置管理** - 供应商切换和管理
|
||||
2. **能力扩展** - Skills 安装和生命周期
|
||||
3. **行为定制** - 系统提示词预设
|
||||
4. **生态集成** - 深度链接和共享
|
||||
5. **多 AI 支持** - Claude/Codex/Gemini
|
||||
6. **智能检测** - 冲突预防
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
### 系统要求
|
||||
|
||||
- **Windows**：Windows 10+
|
||||
- **macOS**：macOS 10.15（Catalina）+
|
||||
- **Linux**：Ubuntu 22.04+ / Debian 11+ / Fedora 34+ / ArchLinux
|
||||
|
||||
### 下载链接
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载：
|
||||
|
||||
- **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`
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 迁移说明
|
||||
|
||||
### 从 v3.6.x 升级
|
||||
|
||||
**自动迁移** - 无需任何操作，配置完全兼容
|
||||
|
||||
### 从 v3.1.x 或更早版本升级
|
||||
|
||||
**需要两步迁移**：
|
||||
|
||||
1. 首先升级到 v3.2.x（执行一次性迁移）
|
||||
2. 然后升级到 v3.7.0
|
||||
|
||||
### 新功能
|
||||
|
||||
- **Skills**：无需迁移，全新开始
|
||||
- **Prompts**：首次启动时从 live 文件自动导入
|
||||
- **Gemini**：需要单独安装 Gemini CLI
|
||||
- **MCP v3.7.0**：与之前的配置向后兼容
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
### 贡献者
|
||||
|
||||
感谢所有让这个版本成为可能的贡献者：
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - Skills & Prompts & Gemini 集成实现
|
||||
- [@farion1231](https://github.com/farion1231) - 从开发沦为 issue 回复机
|
||||
- 社区成员的测试和反馈
|
||||
|
||||
### 赞助商
|
||||
|
||||
**智谱AI** - GLM CODING PLAN 赞助商
|
||||
[使用此链接购买可享九折优惠](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII)
|
||||
|
||||
**PackyCode** - API 中转服务合作伙伴
|
||||
[使用 "cc-switch" 优惠码注册享 9 折优惠](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**闪电说** - 本地优先的 AI 语音输入法
|
||||
[免费下载](https://shandianshuo.cn) Mac/Win 双平台
|
||||
|
||||
---
|
||||
|
||||
## 反馈与支持
|
||||
|
||||
- **问题反馈**：[GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **讨论**：[GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **文档**：[README](../README_ZH.md)
|
||||
- **更新日志**：[CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 未来展望
|
||||
|
||||
**v3.8.0 预览**（暂定）：
|
||||
|
||||
- 本地代理功能
|
||||
|
||||
敬请期待更多更新！
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -1,369 +0,0 @@
|
||||
# CC Switch v3.8.0
|
||||
|
||||
> Persistence Architecture Upgrade, Laying the Foundation for Cloud Sync
|
||||
|
||||
**[中文版 →](release-note-v3.8.0-zh.md) | [日本語版 →](release-note-v3.8.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.8.0 is a major architectural upgrade that restructures the data persistence layer and user interface, laying the foundation for future cloud sync and local proxy features.
|
||||
|
||||
**Release Date**: 2025-11-28
|
||||
**Commits**: 51 commits since v3.7.1
|
||||
**Code Changes**: 207 files, +17,297 / -6,870 lines
|
||||
|
||||
---
|
||||
|
||||
## Major Updates
|
||||
|
||||
### Persistence Architecture Upgrade
|
||||
|
||||
Migrated from single JSON file storage to SQLite + JSON dual-layer architecture for hierarchical data management.
|
||||
|
||||
**Architecture Changes**:
|
||||
|
||||
```
|
||||
v3.7.x (Old) v3.8.0 (New)
|
||||
┌─────────────────┐ ┌─────────────────────────────────┐
|
||||
│ config.json │ │ SQLite (Syncable Data) │
|
||||
│ ┌───────────┐ │ │ ├─ providers Provider cfg │
|
||||
│ │ providers │ │ │ ├─ mcp_servers MCP servers │
|
||||
│ │ mcp │ │ ──> │ ├─ prompts Prompts │
|
||||
│ │ prompts │ │ │ ├─ skills Skills │
|
||||
│ │ settings │ │ │ └─ settings General cfg │
|
||||
│ └───────────┘ │ ├─────────────────────────────────┤
|
||||
└─────────────────┘ │ JSON (Device-level Data) │
|
||||
│ └─ settings.json Local settings│
|
||||
│ ├─ Window position │
|
||||
│ ├─ Path overrides │
|
||||
│ └─ Current provider ID │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Dual-layer Structure Design**:
|
||||
|
||||
| Layer | Storage | Data Types | Sync Strategy |
|
||||
| ---------- | ------- | ------------------------------- | --------------- |
|
||||
| Cloud Sync | SQLite | Providers, MCP, Prompts, Skills | Future syncable |
|
||||
| Device | JSON | Window state, local paths | Stays local |
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- **Schema Version Management** - Supports database structure upgrade migrations
|
||||
- **SQL Import/Export** - `backup.rs` supports SQL dump for cloud storage
|
||||
- **Transaction Support** - SQLite native transactions ensure data consistency
|
||||
- **Auto Migration** - Automatically migrates from `config.json` on first launch
|
||||
|
||||
**Modular Refactoring**:
|
||||
|
||||
```
|
||||
database/
|
||||
├── mod.rs Core Database struct and initialization
|
||||
├── schema.rs Table definitions, schema version migrations
|
||||
├── backup.rs SQL import/export, binary snapshot backup
|
||||
├── migration.rs JSON → SQLite data migration engine
|
||||
└── dao/ Data Access Object layer
|
||||
├── providers.rs Provider CRUD
|
||||
├── mcp.rs MCP server CRUD
|
||||
├── prompts.rs Prompts CRUD
|
||||
├── skills.rs Skills CRUD
|
||||
└── settings.rs Key-value settings storage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Brand New User Interface
|
||||
|
||||
Completely redesigned UI providing a more modern visual experience.
|
||||
|
||||
**Visual Improvements**:
|
||||
|
||||
- Redesigned interface layout
|
||||
- Unified component styles
|
||||
- Smoother transition animations
|
||||
- Optimized visual hierarchy
|
||||
|
||||
**Interaction Enhancements**:
|
||||
|
||||
- Redesigned header toolbar
|
||||
- Unified ConfirmDialog styling
|
||||
- Disabled overscroll bounce effect on main view
|
||||
- Improved form validation feedback
|
||||
|
||||
**Compatibility Adjustments**:
|
||||
|
||||
- Downgraded Tailwind CSS from v4 to v3.4 for better browser compatibility
|
||||
|
||||
---
|
||||
|
||||
### Japanese Language Support
|
||||
|
||||
Added Japanese interface support, expanding internationalization to three languages.
|
||||
|
||||
**Supported Languages**:
|
||||
|
||||
- Simplified Chinese
|
||||
- English
|
||||
- Japanese (New)
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### Skills Recursive Scanning
|
||||
|
||||
Skills management system now supports recursive scanning of repository directories, automatically discovering nested skill files.
|
||||
|
||||
**Improvements**:
|
||||
|
||||
- Support for multi-level directory structures
|
||||
- Automatic discovery of all `SKILL.md` files
|
||||
- Allow same-named skills from different repositories (using full path for deduplication)
|
||||
|
||||
---
|
||||
|
||||
### Provider Icon Configuration
|
||||
|
||||
Provider presets now support custom icon configuration.
|
||||
|
||||
**Features**:
|
||||
|
||||
- Preset providers include default icons
|
||||
- Icon settings preserved when duplicating providers
|
||||
- Custom icon colors
|
||||
|
||||
---
|
||||
|
||||
### Enhanced Form Validation
|
||||
|
||||
Provider forms now include required field validation with friendlier error messages.
|
||||
|
||||
**Improvements**:
|
||||
|
||||
- Real-time validation for required fields
|
||||
- Unified Toast notifications for validation errors
|
||||
- Clearer error messages
|
||||
|
||||
---
|
||||
|
||||
### Auto Launch on Startup
|
||||
|
||||
Added auto-launch functionality supporting Windows, macOS, and Linux platforms.
|
||||
|
||||
**Features**:
|
||||
|
||||
- One-click enable/disable in settings
|
||||
- Implemented using platform-native APIs
|
||||
- Windows uses Registry, macOS uses LaunchAgent, Linux uses XDG autostart
|
||||
|
||||
---
|
||||
|
||||
### New Provider Presets
|
||||
|
||||
- **MiniMax** - Official partner
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Critical Fixes
|
||||
|
||||
**Custom Endpoints Lost Issue**
|
||||
|
||||
Fixed an issue where custom request URLs were unexpectedly lost when updating providers.
|
||||
|
||||
- Root Cause: `INSERT OR REPLACE` executes `DELETE + INSERT` under the hood in SQLite, triggering foreign key cascade deletion
|
||||
- Fix: Changed to use `UPDATE` statement for existing providers
|
||||
|
||||
**Gemini Configuration Issues**
|
||||
|
||||
- Fixed custom provider environment variables not correctly written to `.env` file
|
||||
- Fixed security auth config incorrectly written to other config files
|
||||
|
||||
**Provider Validation Issues**
|
||||
|
||||
- Fixed validation error when current provider ID doesn't exist
|
||||
- Fixed icon fields lost when duplicating providers
|
||||
|
||||
### Platform Compatibility
|
||||
|
||||
**Linux**
|
||||
|
||||
- Resolved WebKitGTK DMA-BUF rendering issue
|
||||
- Preserve user `.desktop` file customizations
|
||||
|
||||
### Other Fixes
|
||||
|
||||
- Fixed redundant usage queries when switching apps
|
||||
- Fixed DMXAPI preset using wrong auth token field
|
||||
- Fixed missing translation keys in deeplink components
|
||||
- Fixed usage script template initialization logic
|
||||
|
||||
---
|
||||
|
||||
## Technical Improvements
|
||||
|
||||
### Architecture Refactoring
|
||||
|
||||
**Provider Service Modularization**:
|
||||
|
||||
```
|
||||
services/provider/
|
||||
├── mod.rs Core service - add/update/delete/switch/validate
|
||||
├── live.rs Live config file operations
|
||||
├── gemini_auth.rs Gemini auth type detection
|
||||
├── endpoints.rs Custom endpoint management
|
||||
└── usage.rs Usage script execution
|
||||
```
|
||||
|
||||
**Deeplink Modularization**:
|
||||
|
||||
```
|
||||
deeplink/
|
||||
├── mod.rs Module exports
|
||||
├── parser.rs URL parsing
|
||||
├── provider.rs Provider import logic
|
||||
├── mcp.rs MCP import logic
|
||||
├── prompt.rs Prompt import
|
||||
├── skill.rs Skills import
|
||||
└── utils.rs Utility functions
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
**Cleanup**:
|
||||
|
||||
- Removed legacy JSON-era import/export dead code
|
||||
- Removed unused MCP type exports
|
||||
- Unified error handling approach
|
||||
|
||||
**Test Updates**:
|
||||
|
||||
- Migrated tests to SQLite database architecture
|
||||
- Updated component tests to match current implementation
|
||||
- Fixed MSW handlers to adapt to new API
|
||||
|
||||
---
|
||||
|
||||
## Technical Statistics
|
||||
|
||||
```
|
||||
Overall Changes:
|
||||
- Commits: 51
|
||||
- Files: 207 files changed
|
||||
- Additions: +17,297 lines
|
||||
- Deletions: -6,870 lines
|
||||
- Net: +10,427 lines
|
||||
|
||||
Commit Type Distribution:
|
||||
- fix: 25 (Bug fixes)
|
||||
- refactor: 11 (Code refactoring)
|
||||
- feat: 9 (New features)
|
||||
- test: 1 (Testing)
|
||||
- other: 5
|
||||
|
||||
Change Area Distribution:
|
||||
- Frontend source: 112 files
|
||||
- Rust backend: 63 files
|
||||
- Test files: 20 files
|
||||
- i18n files: 3 files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Upgrading from v3.7.x
|
||||
|
||||
**Auto Migration** - Executes automatically on first launch:
|
||||
|
||||
1. Detects if `config.json` exists
|
||||
2. Migrates all data to SQLite within a transaction
|
||||
3. Migrates device-level settings to `settings.json`
|
||||
4. Shows migration success notification
|
||||
|
||||
**Data Safety**:
|
||||
|
||||
- Original `config.json` file is preserved (not deleted)
|
||||
- Error dialog displayed on migration failure, `config.json` preserved
|
||||
- Supports Dry-run mode to verify migration logic
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **Windows**: Windows 10+
|
||||
- **macOS**: macOS 10.15 (Catalina)+
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### Download Links
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download:
|
||||
|
||||
- **Windows**: `CC-Switch-v3.8.0-Windows.msi` or `-Portable.zip`
|
||||
- **macOS**: `CC-Switch-v3.8.0-macOS.tar.gz` or `.zip`
|
||||
- **Linux**: `CC-Switch-v3.8.0-Linux.AppImage` or `.deb`
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
### Contributors
|
||||
|
||||
Thanks to all contributors who made this release possible:
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - UI and database refactoring
|
||||
- [@farion1231](https://github.com/farion1231) - Bug fixes and feature enhancements
|
||||
- Community members for testing and feedback
|
||||
|
||||
### Sponsors
|
||||
|
||||
**Zhipu AI** - GLM CODING PLAN Sponsor
|
||||
[Get 10% off with this link](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API Relay Service Partner
|
||||
[Use code "cc-switch" for 10% off registration](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**ShandianShuo** - Local-first AI Voice Input
|
||||
[Free download](https://shandianshuo.cn) for Mac/Windows
|
||||
|
||||
**MiniMax** - MiniMax M2 CODING PLAN Sponsor
|
||||
[Black Friday sale, plans starting at $2](https://platform.minimax.io/subscribe/coding-plan)
|
||||
|
||||
---
|
||||
|
||||
## Feedback & Support
|
||||
|
||||
- **Issue Reports**: [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **Documentation**: [README](../README.md)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
**v3.9.0 Preview** (Tentative):
|
||||
|
||||
- Local proxy feature
|
||||
|
||||
Stay tuned for more updates!
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -1,315 +0,0 @@
|
||||
# CC Switch v3.8.0
|
||||
|
||||
> 永続化アーキテクチャを刷新し、クラウド同期の土台を構築
|
||||
|
||||
**[English →](release-note-v3.8.0-en.md) | [中文版 →](release-note-v3.8.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.8.0 はデータ永続化レイヤーと UI を大幅に作り替え、今後のクラウド同期やローカルプロキシ機能に向けた基盤を整えたメジャーアップデートです。
|
||||
|
||||
**リリース日**: 2025-11-28
|
||||
**コミット数**: v3.7.1 以降 51 commits
|
||||
**変更量**: 207 files, +17,297 / -6,870 lines
|
||||
|
||||
---
|
||||
|
||||
## 主要アップデート
|
||||
|
||||
### 永続化アーキテクチャの刷新
|
||||
|
||||
単一の JSON 保存から、階層化された SQLite + JSON の二層構造へ移行。
|
||||
|
||||
**アーキテクチャ変更**:
|
||||
|
||||
```
|
||||
v3.7.x (旧) v3.8.0 (新)
|
||||
┌─────────────────┐ ┌─────────────────────────────────┐
|
||||
│ config.json │ │ SQLite (同期対象データ) │
|
||||
│ ┌───────────┐ │ │ ├─ providers プロバイダ設定 │
|
||||
│ │ providers │ │ │ ├─ mcp_servers MCP サーバー │
|
||||
│ │ mcp │ │ ──> │ ├─ prompts プロンプト │
|
||||
│ │ prompts │ │ │ ├─ skills Skills │
|
||||
│ │ settings │ │ │ └─ settings 汎用設定 │
|
||||
│ └───────────┘ │ ├─────────────────────────────────┤
|
||||
└─────────────────┘ │ JSON (デバイス固有データ) │
|
||||
│ └─ settings.json ローカル設定 │
|
||||
│ ├─ ウィンドウ位置 │
|
||||
│ ├─ パスの上書き │
|
||||
│ └─ 現在のプロバイダ ID │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**二層構造の設計**:
|
||||
|
||||
| レイヤー | ストレージ | データ種別 | 同期戦略 |
|
||||
| -------- | ---------- | ----------------------------------- | ---------------- |
|
||||
| クラウド | SQLite | Providers, MCP, Prompts, Skills | 将来同期対象 |
|
||||
| デバイス | JSON | ウィンドウ状態、ローカルパス | ローカル保持 |
|
||||
|
||||
**実装ポイント**:
|
||||
|
||||
- **スキーマバージョン管理**: DB 構造のマイグレーションに対応
|
||||
- **SQL インポート/エクスポート**: `backup.rs` が SQL ダンプをサポート
|
||||
- **トランザクション対応**: SQLite ネイティブで整合性を確保
|
||||
- **自動マイグレーション**: 初回起動で `config.json` から自動移行
|
||||
|
||||
**モジュール分割**:
|
||||
|
||||
```
|
||||
database/
|
||||
├── mod.rs Database 構造体と初期化
|
||||
├── schema.rs テーブル定義とスキーマ移行
|
||||
├── backup.rs SQL インポート/エクスポートとスナップショット
|
||||
├── migration.rs JSON → SQLite 変換エンジン
|
||||
└── dao/ DAO レイヤー
|
||||
├── providers.rs プロバイダ CRUD
|
||||
├── mcp.rs MCP CRUD
|
||||
├── prompts.rs プロンプト CRUD
|
||||
├── skills.rs Skills CRUD
|
||||
└── settings.rs 設定 Key-Value 保存
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 新しいユーザーインターフェース
|
||||
|
||||
よりモダンな見た目と操作感に再設計。
|
||||
|
||||
- レイアウト全面刷新、コンポーネントスタイルを統一
|
||||
- トランジションを滑らかにし、視覚的階層を最適化
|
||||
- メインビューのオーバースクロールバウンスを無効化
|
||||
- ブラウザ互換性向上のため Tailwind CSS を v4→v3.4 にダウングレード
|
||||
|
||||
---
|
||||
|
||||
### 日語化
|
||||
|
||||
UI が日本語に対応し、国際化が 3 言語（中/英/日）へ拡大。
|
||||
|
||||
---
|
||||
|
||||
## 新機能
|
||||
|
||||
### Skills 递帰スキャン
|
||||
|
||||
Skills 管理がリポジトリを再帰的に走査し、ネストされた `SKILL.md` を自動検出。
|
||||
|
||||
- 複数階層のディレクトリに対応
|
||||
- すべての `SKILL.md` を自動発見
|
||||
- パスをキーにした重複排除で同名スキルを許容
|
||||
|
||||
### プロバイダアイコン設定
|
||||
|
||||
プリセットがデフォルトアイコンを持ち、複製してもアイコンを保持。カスタム色も設定可能。
|
||||
|
||||
### フォームバリデーション強化
|
||||
|
||||
必須項目にリアルタイム検証と分かりやすいエラーメッセージを追加し、トースト通知を統一。
|
||||
|
||||
### 自動起動
|
||||
|
||||
Windows/macOS/Linux で自動起動をサポート。
|
||||
|
||||
- 設定画面からワンクリックで ON/OFF
|
||||
- Registry / LaunchAgent / XDG autostart を使用
|
||||
|
||||
### 新プロバイダプリセット
|
||||
|
||||
- **MiniMax** - 公式パートナー
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### 重要修正
|
||||
|
||||
**カスタムエンドポイント消失**
|
||||
|
||||
- 原因: SQLite の `INSERT OR REPLACE` が内部で `DELETE + INSERT` を実行し、外部キーのカスケード削除が発生
|
||||
- 対応: 既存プロバイダ更新を `UPDATE` に変更
|
||||
|
||||
**Gemini 設定**
|
||||
|
||||
- カスタム環境変数が `.env` に正しく書き込まれない問題を修正
|
||||
- 認証設定が他ファイルに誤って書き込まれる問題を修正
|
||||
|
||||
**プロバイダ検証**
|
||||
|
||||
- 現在プロバイダ ID が欠落している場合のバリデーションエラーを修正
|
||||
- 複製時にアイコンフィールドが失われる問題を修正
|
||||
|
||||
### プラットフォーム互換性
|
||||
|
||||
**Linux**
|
||||
|
||||
- WebKitGTK の DMA-BUF 描画問題を解消
|
||||
- ユーザーの `.desktop` カスタマイズを保持
|
||||
|
||||
### その他修正
|
||||
|
||||
- アプリ切り替え時の不要な使用量クエリを削減
|
||||
- DMXAPI プリセットの誤ったトークンフィールドを修正
|
||||
- Deeplink コンポーネントの欠損翻訳キーを補完
|
||||
- 使用量スクリプトテンプレート初期化を修正
|
||||
|
||||
---
|
||||
|
||||
## 技術的改善
|
||||
|
||||
### アーキテクチャ再編
|
||||
|
||||
**Provider Service のモジュール化**:
|
||||
|
||||
```
|
||||
services/provider/
|
||||
├── mod.rs 追加/更新/削除/切替/検証の中核
|
||||
├── live.rs ライブ設定ファイル操作
|
||||
├── gemini_auth.rs Gemini 認証タイプ検出
|
||||
├── endpoints.rs カスタムエンドポイント管理
|
||||
└── usage.rs 使用量スクリプト実行
|
||||
```
|
||||
|
||||
**Deeplink のモジュール化**:
|
||||
|
||||
```
|
||||
deeplink/
|
||||
├── mod.rs エクスポート
|
||||
├── parser.rs URL パース
|
||||
├── provider.rs プロバイダ取り込み
|
||||
├── mcp.rs MCP 取り込み
|
||||
├── prompt.rs プロンプト取り込み
|
||||
├── skill.rs Skills 取り込み
|
||||
└── utils.rs ユーティリティ
|
||||
```
|
||||
|
||||
### コード品質
|
||||
|
||||
- レガシーな JSON 時代のインポート/エクスポート死蔵コードを削除
|
||||
- 使われていない MCP 型を削除し、エラーハンドリングを統一
|
||||
- テストを SQLite バックエンドに移行し、MSW ハンドラを最新 API に合わせて更新
|
||||
|
||||
---
|
||||
|
||||
## 技術統計
|
||||
|
||||
```
|
||||
全体変更:
|
||||
- コミット: 51
|
||||
- 変更ファイル: 207
|
||||
- 追加: +17,297 行
|
||||
- 削除: -6,870 行
|
||||
- 純増: +10,427 行
|
||||
|
||||
コミット種別:
|
||||
- fix: 25
|
||||
- refactor: 11
|
||||
- feat: 9
|
||||
- test: 1
|
||||
- other: 5
|
||||
|
||||
変更箇所:
|
||||
- フロントエンド: 112 files
|
||||
- Rust バックエンド: 63 files
|
||||
- テスト: 20 files
|
||||
- i18n: 3 files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## マイグレーションガイド
|
||||
|
||||
### v3.7.x からのアップグレード
|
||||
|
||||
**自動マイグレーション**（初回起動時）:
|
||||
|
||||
1. `config.json` の存在を検出
|
||||
2. 全データをトランザクションで SQLite に移行
|
||||
3. デバイス設定を `settings.json` へ移行
|
||||
4. 移行成功の通知を表示
|
||||
|
||||
**データ保護**:
|
||||
|
||||
- 元の `config.json` は保持（削除しない）
|
||||
- 失敗時はエラーダイアログを表示し、`config.json` を温存
|
||||
- Dry-run モードで検証可能
|
||||
|
||||
---
|
||||
|
||||
## ダウンロード & インストール
|
||||
|
||||
### システム要件
|
||||
|
||||
- **Windows**: Windows 10+
|
||||
- **macOS**: macOS 10.15 (Catalina)+
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### ダウンロード
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から入手:
|
||||
|
||||
- **Windows**: `CC-Switch-v3.8.0-Windows.msi` または `-Portable.zip`
|
||||
- **macOS**: `CC-Switch-v3.8.0-macOS.tar.gz` または `.zip`
|
||||
- **Linux**: `CC-Switch-v3.8.0-Linux.AppImage` または `.deb`
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
アップデート:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 謝辞
|
||||
|
||||
### コントリビューター
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - UI とデータベースリファクタ
|
||||
- [@farion1231](https://github.com/farion1231) - バグ修正と機能拡張
|
||||
- コミュニティの皆さん - テストとフィードバック
|
||||
|
||||
### スポンサー
|
||||
|
||||
**Zhipu AI** - GLM CODING PLAN スポンサー
|
||||
[10% オフリンク](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API リレーサービスパートナー
|
||||
[登録時に「cc-switch」で 10% オフ](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**ShandianShuo** - ローカルファースト音声入力
|
||||
[Mac/Windows 無料ダウンロード](https://shandianshuo.cn)
|
||||
|
||||
**MiniMax** - MiniMax M2 CODING PLAN スポンサー
|
||||
[ブラックフライデーセール中、$2 から](https://platform.minimax.io/subscribe/coding-plan)
|
||||
|
||||
---
|
||||
|
||||
## フィードバック & サポート
|
||||
|
||||
- **Issue**: [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **ドキュメント**: [README](../README.md)
|
||||
- **更新履歴**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 今後のロードマップ
|
||||
|
||||
**v3.9.0 予告（予定）**:
|
||||
|
||||
- ローカルプロキシ機能
|
||||
|
||||
続報にご期待ください！
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -1,369 +0,0 @@
|
||||
# CC Switch v3.8.0
|
||||
|
||||
> 持久化架构升级，为云同步奠定基础
|
||||
|
||||
**[English Version →](release-note-v3.8.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.8.0 是一次重大的架构升级版本，重构了数据持久化层和用户界面，为未来的云同步和本地代理功能奠定基础。
|
||||
|
||||
**发布日期**：2025-11-28
|
||||
**提交数量**：从 v3.7.1 开始 51 个提交
|
||||
**代码变更**：207 个文件，+17,297 / -6,870 行
|
||||
|
||||
---
|
||||
|
||||
## 重大更新
|
||||
|
||||
### 持久化架构升级
|
||||
|
||||
从单一 JSON 文件存储迁移到 SQLite + JSON 双层架构，实现数据分层管理。
|
||||
|
||||
**架构变更**：
|
||||
|
||||
```
|
||||
v3.7.x (旧) v3.8.0 (新)
|
||||
┌─────────────────┐ ┌─────────────────────────────────┐
|
||||
│ config.json │ │ SQLite (可同步数据) │
|
||||
│ ┌───────────┐ │ │ ├─ providers 供应商配置 │
|
||||
│ │ providers │ │ │ ├─ mcp_servers MCP 服务器 │
|
||||
│ │ mcp │ │ ──> │ ├─ prompts 提示词 │
|
||||
│ │ prompts │ │ │ ├─ skills 技能 │
|
||||
│ │ settings │ │ │ └─ settings 通用设置 │
|
||||
│ └───────────┘ │ ├─────────────────────────────────┤
|
||||
└─────────────────┘ │ JSON (设备级数据) │
|
||||
│ └─ settings.json 本地设置 │
|
||||
│ ├─ 窗口位置 │
|
||||
│ ├─ 路径覆盖 │
|
||||
│ └─ 当前选中供应商 ID │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**双层结构设计**：
|
||||
|
||||
| 层级 | 存储方式 | 数据类型 | 同步策略 |
|
||||
| -------- | -------- | ---------------------------- | ---------- |
|
||||
| 云同步层 | SQLite | 供应商、MCP、Prompts、Skills | 未来可同步 |
|
||||
| 设备层 | JSON | 窗口状态、本地路径、当前选择 | 保持本地 |
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- **Schema 版本管理** - 支持数据库结构升级迁移
|
||||
- **SQL 导入导出** - `backup.rs` 支持 SQL dump，便于云端存储
|
||||
- **事务支持** - SQLite 原生事务保证数据一致性
|
||||
- **自动迁移** - 首次启动自动从 `config.json` 迁移数据
|
||||
|
||||
**模块化重构**：
|
||||
|
||||
```
|
||||
database/
|
||||
├── mod.rs 核心 Database 结构体和初始化
|
||||
├── schema.rs 表结构定义、Schema 版本迁移
|
||||
├── backup.rs SQL 导入导出、二进制快照备份
|
||||
├── migration.rs JSON → SQLite 数据迁移引擎
|
||||
└── dao/ 数据访问对象层
|
||||
├── providers.rs 供应商 CRUD
|
||||
├── mcp.rs MCP 服务器 CRUD
|
||||
├── prompts.rs 提示词 CRUD
|
||||
├── skills.rs Skills CRUD
|
||||
└── settings.rs 键值对设置存储
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 全新用户界面
|
||||
|
||||
完整重构的 UI 设计，提供更现代化的视觉体验。
|
||||
|
||||
**视觉改进**：
|
||||
|
||||
- 重新设计的界面布局
|
||||
- 统一的组件样式
|
||||
- 更流畅的过渡动画
|
||||
- 优化的视觉层次
|
||||
|
||||
**交互优化**：
|
||||
|
||||
- Header toolbar 重新设计
|
||||
- ConfirmDialog 样式统一
|
||||
- 禁用主视图 overscroll 弹跳效果
|
||||
- 改进的表单验证反馈
|
||||
|
||||
**兼容性调整**：
|
||||
|
||||
- Tailwind CSS 从 v4 降级到 v3.4，提升浏览器兼容性
|
||||
|
||||
---
|
||||
|
||||
### 日语支持
|
||||
|
||||
新增日语（日本語）界面支持，国际化语言扩展到三种。
|
||||
|
||||
**支持语言**：
|
||||
|
||||
- 简体中文
|
||||
- English
|
||||
- 日本語（新增）
|
||||
|
||||
---
|
||||
|
||||
## 新增功能
|
||||
|
||||
### Skills 递归扫描
|
||||
|
||||
Skills 管理系统支持递归扫描仓库目录，自动发现嵌套的技能文件。
|
||||
|
||||
**改进内容**：
|
||||
|
||||
- 支持多层目录结构
|
||||
- 自动发现所有 `SKILL.md` 文件
|
||||
- 允许不同仓库的同名技能（使用完整路径去重）
|
||||
|
||||
---
|
||||
|
||||
### 供应商图标配置
|
||||
|
||||
供应商预设支持自定义图标配置。
|
||||
|
||||
**功能特性**：
|
||||
|
||||
- 预设供应商包含默认图标
|
||||
- 复制供应商时保留图标设置
|
||||
- 图标颜色自定义
|
||||
|
||||
---
|
||||
|
||||
### 表单验证增强
|
||||
|
||||
供应商表单新增必填字段验证，提供更友好的错误提示。
|
||||
|
||||
**改进内容**：
|
||||
|
||||
- 必填字段实时校验
|
||||
- 统一使用 Toast 通知显示验证错误
|
||||
- 更清晰的错误信息
|
||||
|
||||
---
|
||||
|
||||
### 开机自启
|
||||
|
||||
新增开机自动启动功能，支持 Windows、macOS 和 Linux 三个平台。
|
||||
|
||||
**功能特性**：
|
||||
|
||||
- 在设置中一键开启/关闭
|
||||
- 使用平台原生 API 实现
|
||||
- Windows 使用注册表、macOS 使用 LaunchAgent、Linux 使用 XDG autostart
|
||||
|
||||
---
|
||||
|
||||
### 新增供应商预设
|
||||
|
||||
- **MiniMax** - 官方合作伙伴
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 关键修复
|
||||
|
||||
**自定义端点丢失问题**
|
||||
|
||||
修复更新供应商时自定义请求地址意外丢失的问题。
|
||||
|
||||
- 根因：`INSERT OR REPLACE` 在 SQLite 底层执行 `DELETE + INSERT`，触发外键级联删除
|
||||
- 修复：改用 `UPDATE` 语句更新已存在的供应商
|
||||
|
||||
**Gemini 配置问题**
|
||||
|
||||
- 修复自定义供应商环境变量未正确写入 `.env` 文件
|
||||
- 修复安全认证配置错误写入到其他配置文件
|
||||
|
||||
**供应商验证问题**
|
||||
|
||||
- 修复当前供应商 ID 不存在时的验证错误
|
||||
- 修复供应商复制时图标字段丢失
|
||||
|
||||
### 平台兼容性
|
||||
|
||||
**Linux**
|
||||
|
||||
- 解决 WebKitGTK DMA-BUF 渲染问题
|
||||
- 保留用户 `.desktop` 文件自定义
|
||||
|
||||
### 其他修复
|
||||
|
||||
- 修复切换应用时的冗余用量查询
|
||||
- 修复 DMXAPI 预设使用错误的认证令牌字段
|
||||
- 修复深链接组件缺少翻译键
|
||||
- 修复用量脚本模板初始化逻辑
|
||||
|
||||
---
|
||||
|
||||
## 技术改进
|
||||
|
||||
### 架构重构
|
||||
|
||||
**供应商服务模块化**：
|
||||
|
||||
```
|
||||
services/provider/
|
||||
├── mod.rs 核心服务 - add/update/delete/switch/validate
|
||||
├── live.rs Live 配置文件操作
|
||||
├── gemini_auth.rs Gemini 认证类型检测
|
||||
├── endpoints.rs 自定义端点管理
|
||||
└── usage.rs 用量脚本执行
|
||||
```
|
||||
|
||||
**深链接模块化**：
|
||||
|
||||
```
|
||||
deeplink/
|
||||
├── mod.rs 模块导出
|
||||
├── parser.rs URL 解析
|
||||
├── provider.rs 供应商导入逻辑
|
||||
├── mcp.rs MCP 导入逻辑
|
||||
├── prompt.rs 提示词导入
|
||||
├── skill.rs Skills 导入
|
||||
└── utils.rs 工具函数
|
||||
```
|
||||
|
||||
### 代码质量
|
||||
|
||||
**清理工作**：
|
||||
|
||||
- 移除 JSON 时代遗留的导入导出死代码
|
||||
- 移除未使用的 MCP 类型导出
|
||||
- 统一错误处理方式
|
||||
|
||||
**测试更新**：
|
||||
|
||||
- 迁移测试到 SQLite 数据库架构
|
||||
- 更新组件测试匹配当前实现
|
||||
- 修复 MSW handlers 适配新 API
|
||||
|
||||
---
|
||||
|
||||
## 技术统计
|
||||
|
||||
```
|
||||
总体变更：
|
||||
- 提交数：51
|
||||
- 文件数：207 个文件变更
|
||||
- 新增：+17,297 行
|
||||
- 删除：-6,870 行
|
||||
- 净增：+10,427 行
|
||||
|
||||
提交类型分布：
|
||||
- fix：25 个（Bug 修复）
|
||||
- refactor：11 个（代码重构）
|
||||
- feat：9 个（新功能）
|
||||
- test：1 个（测试）
|
||||
- 其他：5 个
|
||||
|
||||
改动区域分布：
|
||||
- 前端源码：112 个文件
|
||||
- Rust 后端：63 个文件
|
||||
- 测试文件：20 个文件
|
||||
- 国际化文件：3 个文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 迁移说明
|
||||
|
||||
### 从 v3.7.x 升级
|
||||
|
||||
**自动迁移** - 首次启动时自动执行：
|
||||
|
||||
1. 检测 `config.json` 是否存在
|
||||
2. 在事务中迁移所有数据到 SQLite
|
||||
3. 设备级设置迁移到 `settings.json`
|
||||
4. 显示迁移成功通知
|
||||
|
||||
**数据安全**：
|
||||
|
||||
- 原 `config.json` 文件保留不删除
|
||||
- 迁移失败时显示错误对话框，保留`config.json`
|
||||
- 支持 Dry-run 模式验证迁移逻辑
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
### 系统要求
|
||||
|
||||
- **Windows**：Windows 10+
|
||||
- **macOS**：macOS 10.15（Catalina）+
|
||||
- **Linux**：Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### 下载链接
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载：
|
||||
|
||||
- **Windows**：`CC-Switch-v3.8.0-Windows.msi` 或 `-Portable.zip`
|
||||
- **macOS**：`CC-Switch-v3.8.0-macOS.tar.gz` 或 `.zip`
|
||||
- **Linux**：`CC-Switch-v3.8.0-Linux.AppImage` 或 `.deb`
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
## 致谢
|
||||
|
||||
### 贡献者
|
||||
|
||||
感谢所有让这个版本成为可能的贡献者：
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - UI 和数据库重构
|
||||
- [@farion1231](https://github.com/farion1231) - BUG 修复和功能增强
|
||||
- 社区成员的测试和反馈
|
||||
|
||||
### 赞助商
|
||||
|
||||
**智谱AI** - GLM CODING PLAN 赞助商
|
||||
[使用此链接购买可享九折优惠](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII)
|
||||
|
||||
**PackyCode** - API 中转服务合作伙伴
|
||||
[使用 "cc-switch" 优惠码注册享 9 折优惠](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**闪电说** - 本地优先的 AI 语音输入法
|
||||
[免费下载](https://shandianshuo.cn) Mac/Win 双平台
|
||||
|
||||
**MiniMax** - MiniMax M2 CODING PLAN 赞助商
|
||||
[黑五优惠进行中，套餐9.9元起](https://platform.minimaxi.com/subscribe/coding-plan)
|
||||
|
||||
---
|
||||
|
||||
## 反馈与支持
|
||||
|
||||
- **问题反馈**：[GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **讨论**：[GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **文档**：[README](../README_ZH.md)
|
||||
- **更新日志**：[CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 未来展望
|
||||
|
||||
**v3.9.0 预览**（暂定）：
|
||||
|
||||
- 本地代理功能
|
||||
|
||||
敬请期待更多更新！
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -1,188 +0,0 @@
|
||||
# CC Switch v3.9.0
|
||||
|
||||
> Local API Proxy, Auto Failover, Universal Provider, and a more complete multi-app workflow
|
||||
|
||||
**[中文版 →](release-note-v3.9.0-zh.md) | [日本語版 →](release-note-v3.9.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.9.0 is the stable release of the v3.9 beta series (`3.9.0-1`, `3.9.0-2`, `3.9.0-3`).
|
||||
It introduces a local API proxy with per-app takeover, automatic failover, universal providers, and many stability and UX improvements across Claude Code, Codex, and Gemini CLI.
|
||||
|
||||
**Release Date**: 2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- Local API Proxy for Claude Code / Codex / Gemini CLI
|
||||
- Auto Failover with circuit breaker and per-app failover queues
|
||||
- Universal Provider: one shared config synced across apps (ideal for API gateways like NewAPI)
|
||||
- Skills improvements: multi-app support, unified management with SSOT + React Query
|
||||
- Common config snippets: extract reusable snippets from the editor or the current provider
|
||||
- MCP import: import MCP servers from installed apps
|
||||
- Usage improvements: auto-refresh, cache hit/creation metrics, and timezone fixes
|
||||
- Linux packaging: RPM and Flatpak artifacts
|
||||
|
||||
---
|
||||
|
||||
## Major Features
|
||||
|
||||
### Local API Proxy
|
||||
|
||||
- Runs a local high-performance HTTP proxy server (Axum-based)
|
||||
- Supports Claude Code, Codex, and Gemini CLI with a unified proxy
|
||||
- Per-app takeover: you can independently decide which app routes through the proxy
|
||||
- Live config takeover: backs up and redirects the CLI live config to the local proxy when takeover is enabled
|
||||
- Monitoring: request logging and usage statistics for easier debugging and cost tracking
|
||||
- Error request logging: keep detailed logs for failed proxy requests to simplify debugging (#401, thanks @yovinchen)
|
||||
|
||||
### Auto Failover (Circuit Breaker)
|
||||
|
||||
- Automatically detects provider failures and triggers protection (circuit breaker)
|
||||
- Automatically switches to a backup provider when the current one is unhealthy
|
||||
- Tracks provider health in real time, and keeps independent failover queues per app
|
||||
- When failover is disabled, timeout/retry related settings no longer affect normal request flow
|
||||
|
||||
### Skills Management
|
||||
|
||||
- Multi-app Skills support for Claude Code and Codex, with smoother migration from older skill layouts (#365, #378, thanks @yovinchen)
|
||||
- Unified Skills management architecture (SSOT + React Query) for more consistent state and refresh behavior
|
||||
- Better discovery UX and performance:
|
||||
- Skip hidden directories during discovery
|
||||
- Faster discovery with long-lived caching for discoverable skills
|
||||
- Clear loading indicators and more discoverable header actions (import/refresh)
|
||||
- Fix wrong skill repo branch (#505, thanks @kjasn)
|
||||
|
||||
### Universal Provider
|
||||
|
||||
- Add a shared provider configuration that can sync to Claude/Codex/Gemini (#348, thanks @Calcium-Ion)
|
||||
- Designed for API gateways that support multiple protocols (e.g., NewAPI)
|
||||
- Allows per-app default model mapping under a single provider
|
||||
|
||||
### Common Config Snippets (Claude/Codex/Gemini)
|
||||
|
||||
- Maintain a reusable "common config" snippet and merge/append it into providers that enable it
|
||||
- New extraction workflow:
|
||||
- Extract from the editor content (what you are currently editing)
|
||||
- Or extract from the current active provider when the editor content is not provided
|
||||
- Codex extraction is safer:
|
||||
- Removes provider-specific sections like `model_provider`, `model`, and the entire `model_providers` table
|
||||
- Preserves `base_url` under `[mcp_servers.*]` so MCP configs are not accidentally broken
|
||||
|
||||
### MCP Management
|
||||
|
||||
- Import MCP servers from installed apps
|
||||
- Improve robustness: skip sync when the target CLI app is not installed; handle invalid Codex `config.toml` gracefully (#461, thanks @majiayu000)
|
||||
- Windows compatibility: wrap npx/npm commands with `cmd /c` for MCP export
|
||||
|
||||
### Usage & Pricing
|
||||
|
||||
- Usage & pricing improvements: auto-refresh, cache hit/creation metrics, timezone handling fixes, and refreshed built-in pricing table (#508, thanks @yovinchen)
|
||||
- DeepLink support: import usage query configuration via deeplink (#400, thanks @qyinter)
|
||||
- Model extraction for usage statistics (#455, thanks @yovinchen)
|
||||
- Usage query credentials can fall back to provider config (#360, thanks @Sirhexs)
|
||||
|
||||
---
|
||||
|
||||
## UX Improvements
|
||||
|
||||
- Provider search filter: quickly find providers by name (#435, thanks @TinsFox)
|
||||
- Provider icon colors: customize provider icon colors for quicker visual identification (#385, thanks @yovinchen)
|
||||
- Keyboard shortcut: `Cmd/Ctrl + ,` opens Settings (#436, thanks @TinsFox)
|
||||
- Skip Claude Code first-run confirmation dialog (optional)
|
||||
- Closable toasts: close buttons for switch toast and all success toasts (#350, thanks @ForteScarlet)
|
||||
- Update badge navigation: clicking the update badge opens the About tab
|
||||
- Settings page tab style improvements (#342, thanks @wenyuanw)
|
||||
- Smoother transitions: fade transitions for app/view switching and exit animations for panels
|
||||
- Proxy takeover active theme: apply an emerald theme while takeover is active
|
||||
- Dark mode readability improvements for forms and labels
|
||||
- Better window dragging area for full-screen panels (#525, thanks @zerob13)
|
||||
|
||||
---
|
||||
|
||||
## Platform Notes
|
||||
|
||||
### Windows
|
||||
|
||||
- Prevent terminal windows from appearing during version checks
|
||||
- Improve window sizing defaults (minimum width/height)
|
||||
- Fix black screen on startup by using the system titlebar
|
||||
- Add a fallback for `crypto.randomUUID()` on older WebViews
|
||||
|
||||
### macOS
|
||||
|
||||
- Use `.app` bundle path for autostart to avoid terminal window popups (#462, thanks @majiayu000)
|
||||
- Improve tray/icon behavior and header alignment
|
||||
|
||||
---
|
||||
|
||||
## Packaging
|
||||
|
||||
- Linux: RPM and Flatpak packaging targets are now available for building release artifacts
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Security improvements for the JavaScript executor and usage script execution (#151, thanks @luojiyin1987).
|
||||
- SQL import is restricted to CC Switch exported backups to reduce the risk of importing unsafe or incompatible SQL dumps.
|
||||
- Proxy takeover modifies CLI live configs; CC Switch will back up the live config before redirecting it to the local proxy. If you want to revert, disable takeover/stop the proxy and restore from the backup when needed.
|
||||
|
||||
## Special Thanks
|
||||
|
||||
Special thanks to @xunyu @deijing @su-fen for their support and contributions. This release wouldn't be possible without you!
|
||||
|
||||
## Download & Installation
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| System | Minimum Version | Architecture |
|
||||
| ------- | ------------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 or later | x64 |
|
||||
| macOS | macOS 10.15 (Catalina) or later | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| --------------------------------------- | -------------------------------------------------- |
|
||||
| `CC-Switch-v3.9.0-Windows.msi` | **Recommended** - MSI installer with auto-update support |
|
||||
| `CC-Switch-v3.9.0-Windows-Portable.zip` | Portable version, no installation required |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| ------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.9.0-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.9.0-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> **Note**: Since the author does not have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Close the app, then go to "System Settings" → "Privacy & Security" → click "Open Anyway", and it will open normally afterwards.
|
||||
|
||||
### Homebrew (MacOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
| Distribution | Recommended Format | Installation |
|
||||
| --------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
|
||||
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
|
||||
| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm` |
|
||||
| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` |
|
||||
| Arch Linux / Manjaro | `.AppImage` | Make executable and run directly, or use AUR |
|
||||
| Other distros / Unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
| Sandboxed installation | `.flatpak` | `flatpak install CC-Switch-*.flatpak` |
|
||||
@@ -1,188 +0,0 @@
|
||||
# CC Switch v3.9.0
|
||||
|
||||
> ローカル API プロキシ、自動フェイルオーバー、Universal Provider、多アプリ対応の強化
|
||||
|
||||
**[English →](release-note-v3.9.0-en.md) | [中文版 →](release-note-v3.9.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.9.0 は v3.9 ベータ（`3.9.0-1`、`3.9.0-2`、`3.9.0-3`）の安定版です。
|
||||
ローカル API プロキシ（アプリ別テイクオーバー対応）、自動フェイルオーバー、Universal Provider を追加し、Claude Code / Codex / Gemini CLI の安定性と操作性を大きく改善しました。
|
||||
|
||||
**リリース日**：2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- ローカル API プロキシ：Claude Code / Codex / Gemini CLI を統一的にプロキシ
|
||||
- 自動フェイルオーバー：サーキットブレーカーとアプリ別のフェイルオーバーキュー
|
||||
- Universal Provider：1つの設定を複数アプリへ同期（NewAPI などのゲートウェイ向け）
|
||||
- Skills の改善：マルチアプリ対応、SSOT + React Query による管理の統一
|
||||
- 共通設定スニペット：エディタ内容または現在のプロバイダから抽出
|
||||
- MCP インポート：インストール済みアプリから MCP servers を取り込み
|
||||
- 使用量の改善：自動更新、キャッシュ指標、タイムゾーン修正
|
||||
- Linux パッケージ：RPM / Flatpak の成果物を追加
|
||||
|
||||
---
|
||||
|
||||
## 主要機能
|
||||
|
||||
### ローカル API プロキシ（Local API Proxy）
|
||||
|
||||
- ローカルで高性能な HTTP プロキシサーバーを起動（Axum ベース）
|
||||
- Claude Code / Codex / Gemini CLI の API リクエストを統一的に扱う
|
||||
- アプリ別テイクオーバー：アプリごとにプロキシ経由にするかを個別に切り替え可能
|
||||
- Live 設定テイクオーバー：有効化時に CLI の live 設定をバックアップし、ローカルプロキシへリダイレクト
|
||||
- 監視：リクエストログと使用量統計でデバッグとコスト把握を支援
|
||||
- エラーリクエストのログ：失敗したプロキシリクエストも詳細に記録してデバッグを容易に（#401、@yovinchen に感謝）
|
||||
|
||||
### 自動フェイルオーバー（Auto Failover / サーキットブレーカー）
|
||||
|
||||
- 障害を検知して保護（サーキットブレーカー）を自動で発動
|
||||
- 現在のプロバイダが不調な場合、バックアッププロバイダへ自動切り替え
|
||||
- アプリごとに独立したフェイルオーバーキューとヘルス状態を管理
|
||||
- フェイルオーバーを無効化している場合、タイムアウト/リトライ関連の設定は通常フローに影響しません
|
||||
|
||||
### Skills 管理
|
||||
|
||||
- Claude Code と Codex の Skills をマルチアプリで利用可能にし、旧レイアウトからの移行もよりスムーズに（#365、#378、@yovinchen に感謝）
|
||||
- SSOT + React Query による Skills 管理の統一で、状態の一貫性と更新挙動を改善
|
||||
- Discovery の体験と性能を改善：
|
||||
- スキャン時に隠しディレクトリをスキップ
|
||||
- Discoverable skills に長寿命キャッシュを適用して高速化
|
||||
- ローディング表示の改善と、インポート/更新などの操作導線を整理
|
||||
- Skills リポジトリのブランチ設定を修正（#505、@kjasn に感謝）
|
||||
|
||||
### Universal Provider
|
||||
|
||||
- 複数アプリで共有できるプロバイダ設定を追加（Claude/Codex/Gemini へ同期）（#348、@Calcium-Ion に感謝）
|
||||
- NewAPI のような複数プロトコル対応の API ゲートウェイを想定
|
||||
- 1つのプロバイダ内でアプリ別にデフォルトモデルを割り当て可能
|
||||
|
||||
### 共通設定スニペット（Claude/Codex/Gemini）
|
||||
|
||||
- 「共通設定スニペット」を保持し、有効化したプロバイダへマージ/追記
|
||||
- 新しい抽出フロー：
|
||||
- エディタの現在内容から抽出（編集している内容）
|
||||
- エディタ内容がない場合は、現在アクティブなプロバイダから抽出
|
||||
- Codex の抽出はより安全：
|
||||
- `model_provider`、`model`、および `model_providers` テーブル全体など、プロバイダ固有の設定を除去
|
||||
- `[mcp_servers.*]` 配下の `base_url` は保持し、MCP 設定を壊しにくくしています
|
||||
|
||||
### MCP 管理
|
||||
|
||||
- インストール済みアプリから MCP servers をインポート
|
||||
- 安定性向上：対象 CLI が未インストールなら同期をスキップし、無効な Codex `config.toml` も適切に扱います（#461、@majiayu000 に感謝）
|
||||
- Windows 互換性：MCP エクスポート時の npx/npm 呼び出しを `cmd /c` でラップ
|
||||
|
||||
### 使用量と価格データ
|
||||
|
||||
- 使用量/価格の改善：自動更新、キャッシュ指標、タイムゾーン修正、内蔵価格テーブル更新（#508、@yovinchen に感謝）
|
||||
- DeepLink 対応：deeplink から使用量クエリ設定をインポート（#400、@qyinter に感謝）
|
||||
- 使用量統計からモデル情報を抽出（#455、@yovinchen に感謝）
|
||||
- 使用量クエリ資格情報はプロバイダ設定へフォールバック可能（#360、@Sirhexs に感謝）
|
||||
|
||||
---
|
||||
|
||||
## 使い勝手の改善
|
||||
|
||||
- プロバイダ検索フィルター（名前で素早く検索）（#435、@TinsFox に感謝）
|
||||
- プロバイダのアイコン色：アイコンに任意の色を設定して見分けやすく（#385、@yovinchen に感謝）
|
||||
- ショートカット：`Cmd/Ctrl + ,` で設定を開く（#436、@TinsFox に感謝）
|
||||
- Claude Code の初回確認ダイアログをスキップ可能（任意）
|
||||
- トースト通知のクローズボタン：切り替え通知と成功通知を閉じられるように（#350、@ForteScarlet に感謝）
|
||||
- 更新バッジをクリックすると About タブへ移動
|
||||
- 設定ページのタブスタイル改善（#342、@wenyuanw に感謝）
|
||||
- アプリ/ビュー切り替えのフェードとパネル終了アニメーション
|
||||
- プロキシテイクオーバー中はエメラルド系テーマを適用して状態を分かりやすく
|
||||
- ダークモードの視認性改善
|
||||
- FullScreenPanel のウィンドウドラッグ領域を改善（#525、@zerob13 に感謝）
|
||||
|
||||
---
|
||||
|
||||
## プラットフォーム別メモ
|
||||
|
||||
### Windows
|
||||
|
||||
- バージョンチェック時にターミナルが表示されないよう改善
|
||||
- ウィンドウ最小サイズのデフォルトを調整
|
||||
- 起動時の黒画面を避けるため、システムタイトルバー方式を採用
|
||||
- 古い WebView 向けに `crypto.randomUUID()` のフォールバックを追加
|
||||
|
||||
### macOS
|
||||
|
||||
- 自動起動で `.app` バンドルパスを使用し、ターミナル表示を回避（#462、@majiayu000 に感謝）
|
||||
- トレイとヘッダー周りの体験を改善
|
||||
|
||||
---
|
||||
|
||||
## パッケージ
|
||||
|
||||
- Linux：RPM と Flatpak のパッケージングを追加し、リリース成果物の生成に対応
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
- セキュリティ強化：JavaScript 実行器と使用量スクリプト実行に関するセキュリティ問題を修正（#151、@luojiyin1987 に感謝）。
|
||||
- SQL インポートは CC Switch がエクスポートしたバックアップのみに制限されます（安全性のため）。
|
||||
- プロキシのテイクオーバーは CLI の live 設定を変更します。CC Switch はリダイレクト前に live 設定をバックアップします。元に戻す場合はテイクオーバー無効化/プロキシ停止を行い、必要に応じてバックアップから復元してください。
|
||||
|
||||
## 特別な謝辞
|
||||
|
||||
@xunyu @deijing @su-fen の皆様のサポートと貢献に特別な感謝を申し上げます。皆様なしではこのリリースは実現しませんでした！
|
||||
|
||||
## ダウンロード & インストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から該当するバージョンをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| システム | 最低バージョン | アーキテクチャ |
|
||||
| -------- | ----------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 10.15 (Catalina) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表参照 | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| --------------------------------------- | -------------------------------------------- |
|
||||
| `CC-Switch-v3.9.0-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.9.0-Windows-Portable.zip` | ポータブル版、インストール不要 |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.9.0-macOS.zip` | **推奨** - 解凍して Applications へドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.9.0-macOS.tar.gz` | Homebrew インストールおよび自動更新用 |
|
||||
|
||||
> **注意**: 作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元が未確認」という警告が表示される場合があります。アプリを閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、正常に開けるようになります。
|
||||
|
||||
### Homebrew (MacOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
アップデート:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | ------------------------------------------------------------------------------ |
|
||||
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
|
||||
| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm` |
|
||||
| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` |
|
||||
| Arch Linux / Manjaro | `.AppImage` | 実行権限を付与して直接実行、または AUR を使用 |
|
||||
| その他 / 不明 | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
| サンドボックスで実行したい場合 | `.flatpak` | `flatpak install CC-Switch-*.flatpak` |
|
||||
@@ -1,188 +0,0 @@
|
||||
# CC Switch v3.9.0
|
||||
|
||||
> 本地 API 代理、自动故障切换、统一供应商与多应用工作流增强
|
||||
|
||||
**[English →](release-note-v3.9.0-en.md) | [日本語版 →](release-note-v3.9.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.9.0 是 v3.9 测试版序列（`3.9.0-1`、`3.9.0-2`、`3.9.0-3`）的稳定版。
|
||||
本次更新带来本地 API 代理（支持按应用接管）、自动故障切换、统一供应商（Universal Provider），并对 Claude Code / Codex / Gemini CLI 的稳定性与使用体验做了大量改进。
|
||||
|
||||
**发布日期**：2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- 本地 API 代理：Claude Code / Codex / Gemini CLI 统一接入
|
||||
- 自动故障切换：熔断保护 + 每个应用独立的 failover 队列
|
||||
- 统一供应商：一份配置可同步到多个应用（适合 NewAPI 等网关）
|
||||
- Skills 相关增强：支持多应用、管理架构统一（SSOT + React Query）
|
||||
- 通用配置片段：支持从编辑器内容或当前供应商提取可复用片段
|
||||
- MCP 导入：支持从已安装应用导入 MCP servers
|
||||
- 用量增强：自动刷新、缓存命中/创建指标、时区修复
|
||||
- Linux 打包：新增 RPM 与 Flatpak 制品
|
||||
|
||||
---
|
||||
|
||||
## 主要功能
|
||||
|
||||
### 本地 API 代理（Local API Proxy）
|
||||
|
||||
- 运行一个本地高性能 HTTP 代理服务（基于 Axum）
|
||||
- 统一代理 Claude Code、Codex、Gemini CLI 的 API 请求
|
||||
- 按应用接管：你可以分别控制每个应用是否走本地代理
|
||||
- Live 配置接管：启用接管时，会备份并重定向 CLI 的 live 配置到本地代理
|
||||
- 监控能力：记录请求日志与用量统计，便于排错与成本分析
|
||||
- 错误请求日志：代理会记录失败请求的详细信息，便于定位问题（#401，感谢 @yovinchen）
|
||||
|
||||
### 自动故障切换（Auto Failover / 熔断）
|
||||
|
||||
- 自动检测供应商异常并触发熔断保护
|
||||
- 当前供应商不可用时自动切换到备用供应商
|
||||
- 每个应用维护独立的 failover 队列，并实时追踪健康状态
|
||||
- 当关闭故障切换时，超时/重试相关配置不会影响正常请求流程
|
||||
|
||||
### Skills 管理
|
||||
|
||||
- Skills 支持 Claude Code 与 Codex 多应用使用，并提供旧结构到新结构的平滑迁移（#365、#378，感谢 @yovinchen）
|
||||
- Skills 管理架构统一（SSOT + React Query），状态刷新与数据一致性更稳定
|
||||
- 发现（Discovery）体验与性能改进：
|
||||
- 扫描时跳过隐藏目录
|
||||
- Discoverable skills 使用长生命周期缓存提升性能
|
||||
- 增加加载状态提示，导入/刷新等操作入口更显眼
|
||||
- 修复 Skills 仓库分支配置错误（#505，感谢 @kjasn）
|
||||
|
||||
### 统一供应商（Universal Provider）
|
||||
|
||||
- 新增“跨应用共享”的供应商配置，可同步到 Claude/Codex/Gemini（#348，感谢 @Calcium-Ion）
|
||||
- 适配支持多协议的 API 网关（例如 NewAPI）
|
||||
- 同一个供应商下可按应用分别设置默认模型映射
|
||||
|
||||
### 通用配置片段（Claude/Codex/Gemini）
|
||||
|
||||
- 维护一段“通用配置片段”，并将其合并/追加到启用该功能的供应商配置中
|
||||
- 新增“提取通用配置片段”工作流：
|
||||
- 优先从编辑器当前内容提取（你正在编辑的内容）
|
||||
- 若未提供编辑器内容，则从当前激活的供应商提取
|
||||
- Codex 场景提取更安全：
|
||||
- 自动移除 `model_provider`、`model` 以及整个 `model_providers` 表等供应商相关内容
|
||||
- 会保留 `[mcp_servers.*]` 下的 `base_url`，避免误伤 MCP 配置
|
||||
|
||||
### MCP 管理
|
||||
|
||||
- 支持从已安装应用导入 MCP servers
|
||||
- 同步更稳健：目标 CLI 未安装则跳过；无效的 Codex `config.toml` 可更优雅处理（#461，感谢 @majiayu000）
|
||||
- Windows 兼容性：MCP 导出相关的 npx/npm 调用使用 `cmd /c` 包裹
|
||||
|
||||
### 用量与计费数据
|
||||
|
||||
- 用量与计费增强：自动刷新、缓存命中/创建指标、时区修复，以及内置价格表更新（#508，感谢 @yovinchen）
|
||||
- 深链支持：可通过 deeplink 导入用量查询配置（#400，感谢 @qyinter）
|
||||
- 用量统计支持提取模型信息（#455，感谢 @yovinchen）
|
||||
- 用量查询凭证支持从供应商配置回退（#360，感谢 @Sirhexs）
|
||||
|
||||
---
|
||||
|
||||
## 体验优化
|
||||
|
||||
- 供应商搜索过滤：按名称快速查找（#435，感谢 @TinsFox）
|
||||
- 供应商图标颜色：支持为供应商图标设置自定义颜色，便于快速区分（#385，感谢 @yovinchen）
|
||||
- 快捷键：`Cmd/Ctrl + ,` 打开设置（#436，感谢 @TinsFox）
|
||||
- 可跳过 Claude Code 首次确认弹窗（可选）
|
||||
- Toast 通知可关闭：切换提示与成功提示都支持关闭按钮（#350，感谢 @ForteScarlet）
|
||||
- 点击更新徽章会自动跳转到 About 标签页
|
||||
- 设置页 Tab 样式改进（#342，感谢 @wenyuanw）
|
||||
- 更顺滑的切换动效：应用/视图淡入淡出与面板退出动画
|
||||
- 代理接管激活时应用翡翠绿主题，便于一眼识别当前状态
|
||||
- 深色模式可读性增强（表单与标签对比度等）
|
||||
- FullScreenPanel 的窗口拖拽区域优化（#525，感谢 @zerob13）
|
||||
|
||||
---
|
||||
|
||||
## 平台说明
|
||||
|
||||
### Windows
|
||||
|
||||
- 版本检查不再弹出终端窗口
|
||||
- 改进窗口尺寸默认值（最小宽高）
|
||||
- 修复部分设备启动黑屏问题（使用系统标题栏方案）
|
||||
- 兼容旧 WebView：为 `crypto.randomUUID()` 增加降级方案
|
||||
|
||||
### macOS
|
||||
|
||||
- 自启动使用 `.app bundle` 路径，避免弹出终端窗口（#462，感谢 @majiayu000）
|
||||
- 托盘与标题栏相关体验优化
|
||||
|
||||
---
|
||||
|
||||
## 打包
|
||||
|
||||
- Linux：新增 RPM 与 Flatpak 打包目标，用于生成发布制品
|
||||
|
||||
---
|
||||
|
||||
## 说明与注意事项
|
||||
|
||||
- 安全增强：修复 JavaScript 执行器与用量脚本相关的安全问题（#151，感谢 @luojiyin1987）。
|
||||
- 为降低导入风险，SQL 导入被限制为仅允许导入 CC Switch 自己导出的备份。
|
||||
- Proxy 接管会修改 CLI 的 live 配置；CC Switch 会在重定向前自动备份 live 配置。如需回退，可关闭接管/停止代理，并在必要时从备份恢复。
|
||||
|
||||
## 特别感谢
|
||||
|
||||
特别感谢 @xunyu @deijing @su-fen 做出的支持和贡献，没有你们就没有这个版本！
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 系统 | 最低版本 | 架构 |
|
||||
| ------- | ----------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 及以上 | x64 |
|
||||
| macOS | macOS 10.15 (Catalina) 及以上 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 见下表 | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| --------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.9.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.9.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.9.0-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
|
||||
| `CC-Switch-v3.9.0-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开
|
||||
|
||||
### Homebrew（MacOS）
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
|
||||
| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm` |
|
||||
| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` |
|
||||
| Arch Linux / Manjaro | `.AppImage` | 添加执行权限后直接运行，或使用 AUR |
|
||||
| 其他发行版 / 不确定 | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
| 沙箱隔离需求 | `.flatpak` | `flatpak install CC-Switch-*.flatpak` |
|
||||
+5
-7
@@ -1,10 +1,8 @@
|
||||
- 自动升级自定义路径 ✅
|
||||
- win 绿色版报毒问题 ✅
|
||||
- mcp 管理器 ✅
|
||||
- i18n ✅
|
||||
- gemini cli
|
||||
- homebrew 支持 ✅
|
||||
- memory 管理
|
||||
- codex 更多预设供应商
|
||||
- 云同步
|
||||
- 本地代理
|
||||
- mcp 管理器
|
||||
- i18n
|
||||
- gemini cli
|
||||
- homebrew 支持
|
||||
- 自定义 vscode 路径
|
||||
|
||||
@@ -1,64 +0,0 @@
|
||||
# 1.1 软件介绍
|
||||
|
||||
## 什么是 CC Switch
|
||||
|
||||
CC Switch 是一款跨平台桌面应用，专为使用 AI 编程工具的开发者设计。它帮助你统一管理 **Claude Code**、**Codex**、**Gemini CLI**、**OpenCode** 四大 AI 编程工具的配置。
|
||||
|
||||
## 解决什么问题
|
||||
|
||||
在日常开发中，你可能会遇到这些痛点：
|
||||
|
||||
- **多供应商切换麻烦**：使用不同的 API 供应商（官方、中转服务商），需要手动修改配置文件
|
||||
- **配置分散难管理**：Claude、Codex、Gemini、OpenCode 各有独立的配置文件，格式不同
|
||||
- **无法监控用量**：不知道 API 调用了多少次，花了多少钱
|
||||
- **服务不稳定**：单一供应商出问题时，整个工作流中断
|
||||
|
||||
CC Switch 通过统一的界面解决这些问题。
|
||||
|
||||
## 核心功能
|
||||
|
||||
### 供应商管理
|
||||
- 一键切换多个 API 供应商配置
|
||||
- 支持预设模板，快速添加常用供应商
|
||||
- 统一供应商功能，跨应用共享配置
|
||||
- 用量查询与余额显示
|
||||
- 端点速度测试
|
||||
|
||||
### 扩展功能
|
||||
- **MCP 服务器**：管理 Model Context Protocol 服务器，扩展 AI 能力
|
||||
- **Prompts**：管理系统提示词预设，快速切换不同场景
|
||||
- **Skills**：安装和管理技能扩展
|
||||
|
||||
### 代理与高可用
|
||||
- 本地代理服务，记录请求日志和用量统计
|
||||
- 自动故障转移，主供应商失败时自动切换备用
|
||||
- 熔断器机制，防止频繁重试失败的供应商
|
||||
- 详细的 Token 用量追踪与成本估算
|
||||
|
||||
## 支持的应用
|
||||
|
||||
| 应用 | 说明 |
|
||||
|------|------|
|
||||
| **Claude Code** | Anthropic 官方的 AI 编程助手 |
|
||||
| **Codex** | OpenAI 的代码生成工具 |
|
||||
| **Gemini CLI** | Google 的 AI 命令行工具 |
|
||||
| **OpenCode** | 开源 AI 编程终端工具 |
|
||||
|
||||
## 支持的平台
|
||||
|
||||
- **Windows** 10 及以上
|
||||
- **macOS** 10.15 (Catalina) 及以上
|
||||
- **Linux** Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
## 技术架构
|
||||
|
||||
CC Switch 使用现代化的技术栈构建：
|
||||
|
||||
- **前端**：React 18 + TypeScript + Tailwind CSS
|
||||
- **后端**：Tauri 2 + Rust
|
||||
- **数据存储**：SQLite（供应商、MCP、Prompts）+ JSON（设备设置）
|
||||
|
||||
这种架构确保了：
|
||||
- 跨平台一致的体验
|
||||
- 原生级别的性能
|
||||
- 安全的本地数据存储
|
||||
@@ -1,243 +0,0 @@
|
||||
# 1.2 安装指南
|
||||
|
||||
## 前置要求
|
||||
|
||||
### 安装 Node.js
|
||||
|
||||
CC Switch 管理的 CLI 工具（Claude Code、Codex、Gemini CLI）需要 Node.js 环境。
|
||||
|
||||
**推荐版本**：Node.js 18 LTS 或更高版本
|
||||
|
||||
#### Windows
|
||||
|
||||
1. 访问 [Node.js 官网](https://nodejs.org/)
|
||||
|
||||
2. 下载 LTS 版本安装包
|
||||
|
||||
3. 运行安装程序，按提示完成安装
|
||||
|
||||
4. 验证安装：
|
||||
|
||||
```bash
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
#### macOS
|
||||
|
||||
```bash
|
||||
# 使用 Homebrew 安装
|
||||
brew install node
|
||||
|
||||
# 或使用 nvm（推荐）
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
nvm install --lts
|
||||
```
|
||||
|
||||
#### Linux
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# 或使用 nvm
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
nvm install --lts
|
||||
```
|
||||
|
||||
### 安装 CLI 工具
|
||||
|
||||
#### Claude Code
|
||||
|
||||
**方式一：Homebrew（macOS 推荐）**
|
||||
|
||||
```bash
|
||||
brew install claude-code
|
||||
```
|
||||
|
||||
**方式二：npm**
|
||||
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# 国内用户如下载慢，使用镜像源
|
||||
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
|
||||
```
|
||||
|
||||
#### Codex
|
||||
|
||||
**方式一：Homebrew（macOS 推荐）**
|
||||
|
||||
```bash
|
||||
brew install codex
|
||||
```
|
||||
|
||||
**方式二：npm**
|
||||
|
||||
```bash
|
||||
npm install -g @openai/codex
|
||||
|
||||
# 国内用户如下载慢，使用镜像源
|
||||
npm install -g @openai/codex --registry=https://registry.npmmirror.com
|
||||
```
|
||||
|
||||
#### Gemini CLI
|
||||
|
||||
**方式一：Homebrew（macOS 推荐）**
|
||||
|
||||
```bash
|
||||
brew install gemini-cli
|
||||
```
|
||||
|
||||
**方式二：npm**
|
||||
|
||||
```bash
|
||||
npm install -g @google/gemini-cli
|
||||
|
||||
# 国内用户如下载慢，使用镜像源
|
||||
npm install -g @google/gemini-cli --registry=https://registry.npmmirror.com
|
||||
```
|
||||
|
||||
> 💡 **提示**：如果经常遇到下载慢的问题，可以全局设置镜像源：
|
||||
> ```bash
|
||||
> npm config set registry https://registry.npmmirror.com
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
## Windows
|
||||
|
||||
### 安装包方式
|
||||
|
||||
1. 访问 [Releases 页面](https://github.com/farion1231/cc-switch/releases)
|
||||
2. 下载 `CC-Switch-v{版本号}-Windows.msi`
|
||||
3. 双击运行安装程序
|
||||
4. 按提示完成安装
|
||||
|
||||
### 绿色版（免安装）
|
||||
|
||||
1. 下载 `CC-Switch-v{版本号}-Windows-Portable.zip`
|
||||
2. 解压到任意目录
|
||||
3. 运行 `CC-Switch.exe`
|
||||
|
||||
## macOS
|
||||
|
||||
### 方式一：Homebrew（推荐）
|
||||
|
||||
```bash
|
||||
# 添加 tap
|
||||
brew tap farion1231/ccswitch
|
||||
|
||||
# 安装
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新到最新版本：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### 方式二：手动下载
|
||||
|
||||
1. 下载 `CC-Switch-v{版本号}-macOS.zip`
|
||||
2. 解压得到 `CC Switch.app`
|
||||
3. 拖动到「应用程序」文件夹
|
||||
|
||||
### 首次打开提示
|
||||
|
||||
由于开发者没有 Apple 开发者账号，首次打开可能出现「未知开发者」警告：
|
||||
|
||||
**推荐解决方法**：
|
||||
打开终端执行以下命令：
|
||||
```bash
|
||||
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
|
||||
```
|
||||
|
||||
**备选解决方法（通过系统设置）**：
|
||||
1. 关闭警告弹窗
|
||||
2. 打开「系统设置」→「隐私与安全性」
|
||||
3. 找到 CC Switch 相关提示，点击「仍要打开」
|
||||
4. 再次打开应用即可正常使用
|
||||
|
||||
## Linux
|
||||
|
||||
### ArchLinux
|
||||
|
||||
使用 AUR 助手安装：
|
||||
|
||||
```bash
|
||||
# 使用 paru
|
||||
paru -S cc-switch-bin
|
||||
|
||||
# 或使用 yay
|
||||
yay -S cc-switch-bin
|
||||
```
|
||||
|
||||
### Debian / Ubuntu
|
||||
|
||||
1. 下载 `CC-Switch-v{版本号}-Linux.deb`
|
||||
2. 安装：
|
||||
|
||||
```bash
|
||||
sudo dpkg -i CC-Switch-v{版本号}-Linux.deb
|
||||
|
||||
# 如果有依赖问题
|
||||
sudo apt-get install -f
|
||||
```
|
||||
|
||||
### AppImage（通用）
|
||||
|
||||
1. 下载 `CC-Switch-v{版本号}-Linux.AppImage`
|
||||
2. 添加执行权限：
|
||||
|
||||
```bash
|
||||
chmod +x CC-Switch-v{版本号}-Linux.AppImage
|
||||
```
|
||||
|
||||
3. 运行：
|
||||
|
||||
```bash
|
||||
./CC-Switch-v{版本号}-Linux.AppImage
|
||||
```
|
||||
|
||||
## 验证安装
|
||||
|
||||
安装完成后，启动 CC Switch：
|
||||
|
||||
1. 应用窗口正常显示
|
||||
2. 系统托盘出现 CC Switch 图标
|
||||
3. 能够切换 Claude / Codex / Gemini 三个应用
|
||||
|
||||
## 自动更新
|
||||
|
||||
CC Switch 内置自动更新功能：
|
||||
|
||||
- 启动时自动检查更新
|
||||
- 有新版本时在界面显示更新提示
|
||||
- 点击即可下载并安装
|
||||
|
||||
也可以在「设置 → 关于」中手动检查更新。
|
||||
|
||||
## 卸载
|
||||
|
||||
### Windows
|
||||
|
||||
- 通过「设置 → 应用」卸载
|
||||
- 或运行安装目录下的卸载程序
|
||||
|
||||
### macOS
|
||||
|
||||
- 将 `CC Switch.app` 移到废纸篓
|
||||
- 可选：删除配置目录 `~/.cc-switch/`
|
||||
|
||||
### Linux
|
||||
|
||||
```bash
|
||||
# Debian/Ubuntu
|
||||
sudo apt remove cc-switch
|
||||
|
||||
# ArchLinux
|
||||
paru -R cc-switch-bin
|
||||
```
|
||||
@@ -1,169 +0,0 @@
|
||||
# 1.3 界面概览
|
||||
|
||||
## 主界面布局
|
||||
|
||||
|
||||
|
||||
## 顶部导航栏
|
||||
|
||||
| 序号 | 元素 | 功能说明 |
|
||||
|------|------|----------|
|
||||
| ① | Logo | 点击访问 GitHub 项目页 |
|
||||
| ② | 设置按钮 | 打开设置页面（快捷键 `Cmd/Ctrl + ,`） |
|
||||
| ③ | 代理开关 | 启动/停止本地代理服务 |
|
||||
| ④ | 应用切换器 | 切换 Claude / Codex / Gemini / OpenCode |
|
||||
| ⑤ | 功能区 | Skills / Prompts / MCP 入口 |
|
||||
| ⑥ | 添加按钮 | 添加新供应商 |
|
||||
|
||||
### 应用切换器
|
||||
|
||||
点击下拉菜单切换当前管理的应用：
|
||||
|
||||
- **Claude** - 管理 Claude Code 配置
|
||||
- **Codex** - 管理 Codex 配置
|
||||
- **Gemini** - 管理 Gemini CLI 配置
|
||||
- **OpenCode** - 管理 OpenCode 配置
|
||||
|
||||
切换后，供应商列表会显示对应应用的配置。
|
||||
|
||||
### 功能区按钮
|
||||
|
||||
| 按钮 | 功能 | 可见条件 |
|
||||
|------|------|----------|
|
||||
| Skills | 技能扩展管理 | 始终可见 |
|
||||
| Prompts | 系统提示词管理 | 始终可见 |
|
||||
| MCP | MCP 服务器管理 | 始终可见 |
|
||||
|
||||
## 供应商卡片
|
||||
|
||||
每个供应商以卡片形式展示，从左到右依次包含以下元素：
|
||||
|
||||
### 卡片元素（从左到右）
|
||||
|
||||
| 序号 | 元素 | 图标 | 功能说明 |
|
||||
|------|------|------|----------|
|
||||
| ① | 拖拽手柄 | ≡ | 按住上下拖动调整供应商顺序 |
|
||||
| ② | 供应商图标 | 🔷 | 显示供应商品牌图标，可自定义颜色 |
|
||||
| ③ | 供应商信息 | - | 名称、备注/端点地址（可点击打开官网） |
|
||||
| ④ | 用量信息 | - | 显示剩余额度，多套餐时显示套餐数量 |
|
||||
| ⑤ | 启用按钮 | ▶ | 切换为当前使用的供应商 |
|
||||
| ⑥ | 编辑按钮 | ✏️ | 编辑供应商配置 |
|
||||
| ⑦ | 复制按钮 | 📋 | 复制供应商（创建副本） |
|
||||
| ⑧ | 测速按钮 | 🧪 | 测试模型可用性和响应速度 |
|
||||
| ⑨ | 用量查询 | 📊 | 配置用量查询脚本 |
|
||||
| ⑩ | 删除按钮 | 🗑️ | 删除供应商（当前启用时禁用） |
|
||||
|
||||
> 💡 **提示**：操作按钮区域（⑤-⑩）在鼠标悬停时显示，平时隐藏以保持界面简洁。
|
||||
|
||||
### 按钮详细说明
|
||||
|
||||
| 按钮 | 状态变化 | 说明 |
|
||||
|------|----------|------|
|
||||
| **启用** | 已启用时显示 ✓ 并禁用 | 故障转移模式下变为「加入/已加入」 |
|
||||
| **编辑** | 始终可用 | 打开编辑面板修改配置 |
|
||||
| **复制** | 始终可用 | 创建供应商副本，名称后缀 `copy` |
|
||||
| **测速** | 测试中显示加载动画 | 仅代理服务运行时可用 |
|
||||
| **用量查询** | 始终可用 | 配置自定义用量查询脚本 |
|
||||
| **删除** | 当前启用时半透明禁用 | 需先切换到其他供应商才能删除 |
|
||||
|
||||
### 卡片状态
|
||||
|
||||
| 状态 | 边框颜色 | 说明 |
|
||||
|------|----------|------|
|
||||
| **当前启用** | 🔵 蓝色边框 | 普通模式下当前使用的供应商 |
|
||||
| **代理活跃** | 🟢 绿色边框 | 代理接管模式下实际使用的供应商 |
|
||||
| **普通状态** | 默认边框 | 未启用的供应商 |
|
||||
| **故障转移中** | 显示优先级徽章 | 如 P1、P2 表示故障转移优先级 |
|
||||
|
||||
### 健康状态徽章
|
||||
|
||||
在代理模式下，加入故障转移队列的供应商会显示健康状态：
|
||||
|
||||
| 徽章 | 颜色 | 说明 |
|
||||
|------|------|------|
|
||||
| 健康 | 🟢 绿色 | 连续失败 0 次 |
|
||||
| 警告 | 🟡 黄色 | 连续失败 1-2 次 |
|
||||
| 不健康 | 🔴 红色 | 连续失败 ≥3 次，可能触发熔断 |
|
||||
|
||||
|
||||
## 系统托盘
|
||||
|
||||
CC Switch 在系统托盘显示图标，提供快速操作入口。
|
||||
|
||||
### 托盘菜单结构
|
||||
|
||||
|
||||
|
||||
### 菜单功能
|
||||
|
||||
| 菜单项 | 功能 |
|
||||
|--------|------|
|
||||
| 打开主界面 | 显示主窗口并聚焦 |
|
||||
| 应用分组 | 按 Claude/Codex/Gemini/OpenCode 分组显示供应商 |
|
||||
| 供应商列表 | 点击切换，当前启用的显示勾选标记 |
|
||||
| 退出 | 完全退出应用 |
|
||||
|
||||
### 多语言支持
|
||||
|
||||
托盘菜单支持三种语言，根据设置自动切换：
|
||||
|
||||
| 语言 | 打开主界面 | 退出 |
|
||||
|------|-----------|------|
|
||||
| 中文 | 打开主界面 | 退出 |
|
||||
| English | Open main window | Quit |
|
||||
| 日本語 | メインウィンドウを開く | 終了 |
|
||||
|
||||
### 使用场景
|
||||
|
||||
托盘切换供应商无需打开主界面，适合：
|
||||
|
||||
- 频繁切换供应商
|
||||
- 主窗口最小化时快速操作
|
||||
- 后台运行时管理配置
|
||||
|
||||
## 设置页面
|
||||
|
||||
设置页面分为多个 Tab：
|
||||
|
||||
### 通用 Tab
|
||||
|
||||
- 语言设置（中文/English/日本語）
|
||||
- 主题设置（跟随系统/浅色/深色）
|
||||
- 窗口行为（开机自启、关闭行为）
|
||||
|
||||
### 高级 Tab
|
||||
|
||||
- 配置目录设置
|
||||
- 代理服务配置
|
||||
- 故障转移设置
|
||||
- 定价配置
|
||||
- 数据导入导出
|
||||
|
||||
### 用量 Tab
|
||||
|
||||
- 请求统计概览
|
||||
- 趋势图表
|
||||
- 请求日志
|
||||
- 供应商/模型统计
|
||||
|
||||
### 关于 Tab
|
||||
|
||||
- 版本信息
|
||||
- 更新检查
|
||||
- 开源协议
|
||||
|
||||
## 快捷键
|
||||
|
||||
| 快捷键 | 功能 |
|
||||
|--------|------|
|
||||
| `Cmd/Ctrl + ,` | 打开设置 |
|
||||
| `Cmd/Ctrl + F` | 搜索供应商 |
|
||||
| `Esc` | 关闭弹窗/搜索 |
|
||||
|
||||
## 搜索功能
|
||||
|
||||
按 `Cmd/Ctrl + F` 打开搜索框：
|
||||
|
||||
- 支持按名称、备注、URL 搜索
|
||||
- 实时过滤供应商列表
|
||||
- 按 `Esc` 关闭搜索
|
||||
@@ -1,92 +0,0 @@
|
||||
# 1.4 快速上手
|
||||
|
||||
本节帮助你在 5 分钟内完成首次配置。
|
||||
|
||||
## 第一步：添加供应商
|
||||
|
||||
1. 点击主界面右上角的 **+** 按钮
|
||||
2. 在「预设」下拉框中选择你的供应商
|
||||
- 常用预设：智谱 GLM、MiniMax、DeepSeek、Kimi、PackyCode
|
||||
- 或选择「自定义」手动配置
|
||||
3. 填写 **API Key**
|
||||
4. 点击「添加」
|
||||
|
||||
|
||||
|
||||
> 💡 **提示**：预设会自动填充端点地址，你只需要填写 API Key。
|
||||
|
||||
## 第二步：切换供应商
|
||||
|
||||
添加完成后，供应商会出现在列表中。
|
||||
|
||||
**方式一：主界面切换**
|
||||
- 点击供应商卡片的「启用」按钮
|
||||
|
||||
**方式二：托盘快速切换**
|
||||
- 右键系统托盘图标
|
||||
- 直接点击供应商名称
|
||||
|
||||
## 第三步：生效方式
|
||||
|
||||
切换供应商后，各 CLI 工具的生效方式不同：
|
||||
|
||||
| 应用 | 生效方式 |
|
||||
|------|----------|
|
||||
| Claude Code | ✅ 即时生效（支持热重载） |
|
||||
| Codex | 需关闭并重新打开终端 |
|
||||
| Gemini | ✅ 即时生效（每次请求重新读取配置） |
|
||||
|
||||
### Claude Code 首次安装提示
|
||||
|
||||
如果 Claude Code 首次启动时提示需要**登录**或显示初始化引导，请在 CC Switch 中开启「跳过 Claude Code 初次安装确认」选项：
|
||||
|
||||
1. 打开 CC Switch「设置 → 通用」
|
||||
2. 开启「跳过 Claude Code 初次安装确认」开关
|
||||
3. 重新启动 Claude Code
|
||||
|
||||
|
||||
|
||||
> ⚠️ **注意**：此选项会写入 `~/.claude/settings.json` 的 `skipIntroduction` 字段，跳过官方的新手引导流程。
|
||||
|
||||
## 验证配置
|
||||
|
||||
重启后，启动对应的 CLI 工具并输入简单的问题进行测试：
|
||||
|
||||
```bash
|
||||
# Claude Code - 启动后输入测试问题
|
||||
claude
|
||||
> 你好，请简单介绍一下自己
|
||||
|
||||
# Codex - 启动后输入测试问题
|
||||
codex
|
||||
> 你好，请简单介绍一下自己
|
||||
|
||||
# Gemini - 启动后输入测试问题
|
||||
gemini
|
||||
> 你好，请简单介绍一下自己
|
||||
```
|
||||
|
||||
如果 AI 能正常回复，说明配置成功。
|
||||
|
||||
## 下一步
|
||||
|
||||
恭喜！你已经完成了基础配置。接下来可以：
|
||||
|
||||
- [添加更多供应商](../2-providers/2.1-add.md) - 配置多个供应商方便切换
|
||||
- [配置 MCP 服务器](../3-extensions/3.1-mcp.md) - 扩展 AI 工具的能力
|
||||
- [设置系统提示词](../3-extensions/3.2-prompts.md) - 自定义 AI 的行为
|
||||
- [开启代理服务](../4-proxy/4.1-service.md) - 监控用量和自动故障转移
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 切换后不生效？
|
||||
|
||||
确保重启了终端或 CLI 工具。配置文件在切换时已经更新，但运行中的程序不会自动重新加载。
|
||||
|
||||
### 找不到预设？
|
||||
|
||||
如果你的供应商不在预设列表中，选择「自定义」手动配置。参考 [添加供应商](../2-providers/2.1-add.md) 了解配置格式。
|
||||
|
||||
### 如何恢复官方登录？
|
||||
|
||||
选择「官方登录」预设（Claude/Codex）或「Google 官方」预设（Gemini），重启客户端后按登录流程操作。
|
||||
@@ -1,134 +0,0 @@
|
||||
# 1.5 个性化配置
|
||||
|
||||
本节介绍如何根据个人偏好配置 CC Switch。
|
||||
|
||||
## 打开设置
|
||||
|
||||
- 点击左上角 **⚙️** 按钮
|
||||
- 或使用快捷键 `Cmd/Ctrl + ,`
|
||||
|
||||
## 语言设置
|
||||
|
||||
CC Switch 支持三种语言：
|
||||
|
||||
| 语言 | 说明 |
|
||||
|------|------|
|
||||
| 简体中文 | 默认语言 |
|
||||
| English | 英文界面 |
|
||||
| 日本語 | 日文界面 |
|
||||
|
||||
切换语言后立即生效，无需重启。
|
||||
|
||||
## 主题设置
|
||||
|
||||
| 选项 | 说明 |
|
||||
|------|------|
|
||||
| 跟随系统 | 自动匹配系统的深色/浅色模式 |
|
||||
| 浅色 | 始终使用浅色主题 |
|
||||
| 深色 | 始终使用深色主题 |
|
||||
|
||||
## 窗口行为
|
||||
|
||||
### 开机自启
|
||||
|
||||
开启后，系统启动时自动运行 CC Switch。
|
||||
|
||||
- **Windows**：通过注册表实现
|
||||
- **macOS**：通过 LaunchAgent 实现
|
||||
- **Linux**：通过 XDG autostart 实现
|
||||
|
||||
### 关闭行为
|
||||
|
||||
| 选项 | 说明 |
|
||||
|------|------|
|
||||
| 最小化到托盘 | 点击关闭按钮时隐藏到系统托盘 |
|
||||
| 直接退出 | 点击关闭按钮时完全退出应用 |
|
||||
|
||||
推荐使用「最小化到托盘」，方便通过托盘快速切换供应商。
|
||||
|
||||
### Claude 插件集成
|
||||
|
||||
开启后，CC Switch 在切换供应商时会自动同步配置到 VS Code 中的 Claude Code 插件（写入 `~/.claude/config.json` 的 `primaryApiKey`）。
|
||||
|
||||
> 💡 **使用场景**：如果你同时使用 Claude Code CLI 和 VS Code 插件，开启此选项可以保持两者配置一致。
|
||||
|
||||
### 跳过 Claude 引导
|
||||
|
||||
开启后，跳过 Claude Code 的新手引导流程，适合已熟悉 Claude Code 的用户。
|
||||
|
||||
> ⚠️ **注意**：此选项会写入 `~/.claude/settings.json` 的 `skipIntroduction` 字段。
|
||||
|
||||
## 目录配置
|
||||
|
||||
### 应用配置目录
|
||||
|
||||
CC Switch 自身数据的存储位置，默认为 `~/.cc-switch/`。
|
||||
|
||||
### CLI 工具目录
|
||||
|
||||
可以自定义各 CLI 工具的配置目录：
|
||||
|
||||
| 配置 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| Claude 目录 | `~/.claude/` | Claude Code 配置目录 |
|
||||
| Codex 目录 | `~/.codex/` | Codex 配置目录 |
|
||||
| Gemini 目录 | `~/.gemini/` | Gemini CLI 配置目录 |
|
||||
|
||||
> ⚠️ **注意**：修改目录后需要重启应用，且对应的 CLI 工具也需要配置相同的目录。
|
||||
|
||||
## 数据管理
|
||||
|
||||
### 导出配置
|
||||
|
||||
点击「导出」按钮，保存包含以下内容的备份文件：
|
||||
|
||||
- 所有供应商配置
|
||||
- MCP 服务器配置
|
||||
- Prompts 预设
|
||||
- 应用设置
|
||||
|
||||
备份文件格式为 JSON，可以用文本编辑器查看。
|
||||
|
||||
### 导入配置
|
||||
|
||||
1. 点击「选择文件」
|
||||
2. 选择之前导出的备份文件
|
||||
3. 点击「导入」
|
||||
4. 确认覆盖现有配置
|
||||
|
||||
> ⚠️ **注意**：导入会覆盖现有配置，建议先导出当前配置作为备份。
|
||||
|
||||
## 关于页面
|
||||
|
||||
设置 → 关于 Tab
|
||||
|
||||
### 版本信息
|
||||
|
||||
显示当前 CC Switch 版本号，支持：
|
||||
- 查看发布说明
|
||||
- 检查更新
|
||||
- 下载并安装新版本
|
||||
|
||||
### 本地环境检查
|
||||
|
||||
自动检测已安装的 CLI 工具版本：
|
||||
|
||||
| 工具 | 检测内容 |
|
||||
|------|----------|
|
||||
| Claude | 当前版本、最新版本 |
|
||||
| Codex | 当前版本、最新版本 |
|
||||
| Gemini | 当前版本、最新版本 |
|
||||
|
||||
点击「刷新」按钮可重新检测。
|
||||
|
||||
### 一键安装命令
|
||||
|
||||
提供快速安装/更新 CLI 工具的命令：
|
||||
|
||||
```bash
|
||||
npm i -g @anthropic-ai/claude-code@latest
|
||||
npm i -g @openai/codex@latest
|
||||
npm i -g @google/gemini-cli@latest
|
||||
```
|
||||
|
||||
点击「复制」按钮可复制到剪贴板。
|
||||
@@ -1,320 +0,0 @@
|
||||
# 2.1 添加供应商
|
||||
|
||||
## 打开添加面板
|
||||
|
||||
点击主界面右上角的 **+** 按钮，打开添加供应商面板。
|
||||
|
||||
面板分为两个 Tab：
|
||||
- **应用专属供应商**：仅用于当前选中的应用（Claude/Codex/Gemini/OpenCode）
|
||||
- **统一供应商**：跨应用共享的配置
|
||||
|
||||
## 使用预设添加
|
||||
|
||||
预设是预先配置好的供应商模板，只需填写 API Key 即可使用。
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 在「预设」下拉框中选择供应商
|
||||
2. 名称和端点会自动填充
|
||||
3. 填写你的 **API Key**
|
||||
4. （可选）填写备注
|
||||
5. 点击「添加」
|
||||
|
||||
### 常用预设
|
||||
|
||||
#### Claude 预设
|
||||
|
||||
| 预设名称 | 说明 |
|
||||
|----------|------|
|
||||
| Claude 官方 | 使用 Anthropic 官方账号登录 |
|
||||
| DeepSeek | DeepSeek 模型 |
|
||||
| 智谱 GLM | 智谱 AI 的 GLM 模型 |
|
||||
| 智谱 GLM en | 智谱 AI（英文版） |
|
||||
| 百炼 | 阿里云百炼（通义千问） |
|
||||
| Kimi | Moonshot Kimi 模型 |
|
||||
| Kimi For Coding | Kimi 编程专用模型 |
|
||||
| ModelScope | 魔搭社区 |
|
||||
| KAT-Coder | KAT-Coder 模型 |
|
||||
| Longcat | Longcat AI |
|
||||
| MiniMax | MiniMax 模型 |
|
||||
| MiniMax en | MiniMax（英文版） |
|
||||
| DouBaoSeed | 豆包 Seed 模型 |
|
||||
| BaiLing | 百灵 AI |
|
||||
| AiHubMix | AiHubMix 聚合服务 |
|
||||
| SiliconFlow | 硅基流动 |
|
||||
| SiliconFlow en | 硅基流动（英文版） |
|
||||
| DMXAPI | DMXAPI 中转服务 |
|
||||
| PackyCode | PackyCode 中转服务 ⭐ |
|
||||
| Cubence | Cubence 服务 |
|
||||
| AIGoCode | AIGoCode 服务 |
|
||||
| RightCode | RightCode 服务 |
|
||||
| AICodeMirror | AICodeMirror 服务 |
|
||||
| OpenRouter | 聚合路由服务 |
|
||||
| Nvidia | Nvidia AI 服务 |
|
||||
| Xiaomi MiMo | 小米 MiMo 模型 |
|
||||
|
||||
> ⭐ 标注为官方合作伙伴。预设列表可能随版本更新，以应用内实际显示为准。
|
||||
|
||||
#### Codex 预设
|
||||
|
||||
| 预设名称 | 说明 |
|
||||
|----------|------|
|
||||
| OpenAI 官方 | 使用 OpenAI 官方账号登录 |
|
||||
| Azure OpenAI | Azure OpenAI 服务 |
|
||||
| AiHubMix | AiHubMix 聚合服务 |
|
||||
| DMXAPI | DMXAPI 中转服务 |
|
||||
| PackyCode | PackyCode 中转服务 |
|
||||
| Cubence | Cubence 服务 |
|
||||
| AIGoCode | AIGoCode 服务 |
|
||||
| RightCode | RightCode 服务 |
|
||||
| AICodeMirror | AICodeMirror 服务 |
|
||||
| OpenRouter | 聚合路由服务 |
|
||||
|
||||
#### Gemini 预设
|
||||
|
||||
| 预设名称 | 说明 |
|
||||
|----------|------|
|
||||
| Google 官方 | 使用 Google OAuth 登录 |
|
||||
| PackyCode | PackyCode 中转服务 |
|
||||
| Cubence | Cubence 服务 |
|
||||
| AIGoCode | AIGoCode 服务 |
|
||||
| AICodeMirror | AICodeMirror 服务 |
|
||||
| OpenRouter | 聚合路由服务 |
|
||||
| 自定义 | 手动配置所有参数 |
|
||||
|
||||
#### OpenCode 预设
|
||||
|
||||
| 预设名称 | 说明 |
|
||||
|----------|------|
|
||||
| DeepSeek | DeepSeek 模型 |
|
||||
| 智谱 GLM | 智谱 AI 的 GLM 模型 |
|
||||
| 智谱 GLM en | 智谱 AI（英文版） |
|
||||
| 百炼 | 阿里云百炼 |
|
||||
| Kimi k2.5 | Moonshot Kimi-k2.5 模型 |
|
||||
| Kimi For Coding | Kimi 编程专用模型 |
|
||||
| ModelScope | 魔搭社区 |
|
||||
| KAT-Coder | KAT-Coder 模型 |
|
||||
| Longcat | Longcat AI |
|
||||
| MiniMax | MiniMax 模型 |
|
||||
| MiniMax en | MiniMax（英文版） |
|
||||
| DouBaoSeed | 豆包 Seed 模型 |
|
||||
| BaiLing | 百灵 AI |
|
||||
| Xiaomi MiMo | 小米 MiMo 模型 |
|
||||
| AiHubMix | AiHubMix 聚合服务 |
|
||||
| DMXAPI | DMXAPI 中转服务 |
|
||||
| OpenRouter | 聚合路由服务 |
|
||||
| Nvidia | Nvidia AI 服务 |
|
||||
| PackyCode | PackyCode 中转服务 |
|
||||
| Cubence | Cubence 服务 |
|
||||
| AIGoCode | AIGoCode 服务 |
|
||||
| RightCode | RightCode 服务 |
|
||||
| AICodeMirror | AICodeMirror 服务 |
|
||||
| OpenAI Compatible | OpenAI 兼容接口 |
|
||||
| Oh My OpenCode | Oh My OpenCode 服务 |
|
||||
|
||||
> 💡 预设列表持续更新中，以应用内实际显示为准。
|
||||
|
||||
## 自定义配置
|
||||
|
||||
选择「自定义」预设后，需要手动编辑 JSON 配置。
|
||||
|
||||
### Claude 配置格式
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": "your-api-key",
|
||||
"ANTHROPIC_BASE_URL": "https://api.example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `ANTHROPIC_API_KEY` | 是 | API 密钥 |
|
||||
| `ANTHROPIC_BASE_URL` | 否 | 自定义端点地址 |
|
||||
| `ANTHROPIC_AUTH_TOKEN` | 否 | 替代 API_KEY 的认证方式 |
|
||||
|
||||
### Codex 配置格式
|
||||
|
||||
Codex 使用两个配置文件：
|
||||
|
||||
**1. auth.json**（`~/.codex/auth.json`）- 存储 API 密钥：
|
||||
|
||||
```json
|
||||
{
|
||||
"OPENAI_API_KEY": "your-api-key"
|
||||
}
|
||||
```
|
||||
|
||||
**2. config.toml**（`~/.codex/config.toml`）- 存储模型和端点配置：
|
||||
|
||||
```toml
|
||||
# 基础配置
|
||||
model_provider = "custom"
|
||||
model = "gpt-5.2"
|
||||
model_reasoning_effort = "high"
|
||||
disable_response_storage = true
|
||||
|
||||
# 自定义供应商配置
|
||||
[model_providers.custom]
|
||||
name = "custom"
|
||||
base_url = "https://api.example.com/v1"
|
||||
wire_api = "responses"
|
||||
requires_openai_auth = true
|
||||
```
|
||||
|
||||
**auth.json 字段说明**：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `OPENAI_API_KEY` | 是 | API 密钥 |
|
||||
|
||||
**config.toml 字段说明**：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `model_provider` | 是 | 模型提供商名称（需与 `[model_providers.xxx]` 匹配） |
|
||||
| `model` | 是 | 使用的模型（如 `gpt-5.2`、`gpt-4o`） |
|
||||
| `model_reasoning_effort` | 否 | 推理强度：`low` / `medium` / `high` |
|
||||
| `disable_response_storage` | 否 | 是否禁用响应存储 |
|
||||
| `base_url` | 是 | API 端点地址 |
|
||||
| `wire_api` | 否 | API 协议类型（通常为 `responses`） |
|
||||
| `requires_openai_auth` | 否 | 是否使用 OpenAI 认证方式 |
|
||||
|
||||
|
||||
### Gemini 配置格式
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-api-key",
|
||||
"GOOGLE_GEMINI_BASE_URL": "https://api.example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `GEMINI_API_KEY` | 是 | API 密钥 |
|
||||
| `GOOGLE_GEMINI_BASE_URL` | 否 | 自定义端点地址 |
|
||||
| `GEMINI_MODEL` | 否 | 指定模型 |
|
||||
|
||||
> 💡 认证类型由 CC Switch 自动检测（PackyCode API 代理 / Google OAuth / 通用 API Key），无需手动配置。
|
||||
|
||||
## 统一供应商
|
||||
|
||||
统一供应商可以跨 Claude/Codex/Gemini/OpenCode 共享配置，适用于支持多种 API 格式的中转服务。
|
||||
|
||||
### 创建统一供应商
|
||||
|
||||
1. 切换到「统一供应商」Tab
|
||||
2. 点击「添加统一供应商」
|
||||
3. 填写通用配置：
|
||||
- 名称
|
||||
- API Key
|
||||
- 端点地址
|
||||
4. 勾选要同步的应用（Claude/Codex/Gemini/OpenCode）
|
||||
5. 保存
|
||||
|
||||
### 同步机制
|
||||
|
||||
统一供应商会自动同步到勾选的应用：
|
||||
|
||||
- 修改统一供应商后，所有关联应用的配置同步更新
|
||||
- 删除统一供应商后，关联的应用配置也会删除
|
||||
|
||||
### 保存并同步
|
||||
|
||||
编辑统一供应商时，可以选择：
|
||||
|
||||
| 操作 | 说明 |
|
||||
|------|------|
|
||||
| 保存 | 仅保存配置，不立即同步 |
|
||||
| 保存并同步 | 保存配置并立即同步到所有启用的应用 |
|
||||
|
||||
### 手动同步
|
||||
|
||||
如果需要手动触发同步：
|
||||
|
||||
1. 在统一供应商卡片上点击「同步」按钮
|
||||
2. 确认同步操作
|
||||
3. 配置会覆盖各应用中关联的供应商
|
||||
|
||||
## 导入供应商
|
||||
|
||||
CC Switch 支持两种方式导入供应商配置：
|
||||
|
||||
### 方式一：深度链接导入
|
||||
|
||||
通过 `ccswitch://` 协议链接一键导入：
|
||||
|
||||
1. 点击或访问深度链接
|
||||
2. CC Switch 自动打开并显示导入确认
|
||||
3. 预览配置信息
|
||||
4. 点击「确认导入」
|
||||
|
||||
**获取深度链接**：
|
||||
- 从他人分享获取
|
||||
- 使用 [在线生成工具](https://farion1231.github.io/cc-switch/deplink.html) 创建
|
||||
|
||||
### 方式二：数据库备份导入
|
||||
|
||||
从 SQL 备份文件批量导入：
|
||||
|
||||
1. 打开「设置 → 高级 → 数据管理」
|
||||
2. 点击「选择文件」
|
||||
3. 选择之前导出的 `.sql` 备份文件
|
||||
4. 点击「导入」
|
||||
5. 确认覆盖现有配置
|
||||
|
||||
**导入内容**：
|
||||
- 所有供应商配置
|
||||
- MCP 服务器配置
|
||||
- Prompts 预设
|
||||
- 用量日志
|
||||
|
||||
> ⚠️ **注意**：导入会覆盖现有数据库，建议先导出当前配置作为备份。导出的文件名格式为 `cc-switch-export-{时间戳}.sql`。
|
||||
|
||||
## 高级选项
|
||||
|
||||
### 自定义图标
|
||||
|
||||
点击名称左侧的图标区域，可以：
|
||||
|
||||
- 选择预设图标
|
||||
- 自定义图标颜色
|
||||
|
||||
### 网站链接
|
||||
|
||||
填写供应商的官网或控制台地址，方便快速访问：
|
||||
|
||||
- 点击供应商卡片的链接图标可直接打开
|
||||
- 用于查看余额、获取 API Key 等
|
||||
|
||||
### 备注
|
||||
|
||||
添加备注信息，如：
|
||||
|
||||
- 账号用途（个人/工作）
|
||||
- 套餐信息
|
||||
- 到期时间
|
||||
|
||||
备注会显示在供应商卡片上，也支持搜索。
|
||||
|
||||
### 端点测速
|
||||
|
||||
添加供应商后，可以对 API 端点进行速度测试：
|
||||
|
||||
1. 点击供应商卡片的「测速」按钮
|
||||
2. 在测速面板中添加多个端点 URL
|
||||
3. 点击「测速」执行测试
|
||||
4. 选择延迟最低的端点
|
||||
|
||||
**测速结果**：
|
||||
- 🟢 绿色：延迟 < 500ms（优秀）
|
||||
- 🟡 黄色：延迟 500-1000ms（一般）
|
||||
- 🔴 红色：延迟 > 1000ms（较慢）
|
||||
|
||||
|
||||
|
||||
@@ -1,111 +0,0 @@
|
||||
# 2.2 切换供应商
|
||||
|
||||
## 主界面切换
|
||||
|
||||
在供应商列表中，点击目标供应商卡片的「启用」按钮。
|
||||
|
||||
### 切换流程
|
||||
|
||||
1. 点击「启用」按钮
|
||||
2. CC Switch 更新配置文件
|
||||
3. 卡片状态变为「当前启用」
|
||||
4. Claude/Gemini 即时生效，Codex 需重启终端
|
||||
|
||||
### 状态指示
|
||||
|
||||
| 状态 | 显示 | 说明 |
|
||||
|------|------|------|
|
||||
| 当前启用 | 蓝色边框 + 标签 | 配置文件中的当前供应商 |
|
||||
| 代理活跃 | 绿色边框 | 代理模式下实际使用的供应商 |
|
||||
| 普通 | 默认样式 | 未启用的供应商 |
|
||||
|
||||
## 托盘快速切换
|
||||
|
||||
通过系统托盘可以快速切换，无需打开主界面。
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 右键点击系统托盘的 CC Switch 图标
|
||||
2. 在菜单中找到对应应用（Claude/Codex/Gemini/OpenCode）
|
||||
3. 点击要切换的供应商名称
|
||||
4. 切换完成，托盘会短暂提示
|
||||
|
||||
### 托盘菜单结构
|
||||
|
||||
|
||||
|
||||
## 生效方式
|
||||
|
||||
### Claude Code
|
||||
|
||||
**切换后即时生效**，无需重启。
|
||||
|
||||
Claude Code 支持热重载，会自动检测配置文件变更并重新加载。
|
||||
|
||||
### Codex
|
||||
|
||||
切换后需要重启：
|
||||
- 关闭当前终端窗口
|
||||
- 重新打开终端
|
||||
|
||||
### Gemini CLI
|
||||
|
||||
**切换后即时生效**，无需重启。
|
||||
|
||||
Gemini CLI 每次请求都会重新读取 `.env` 文件。
|
||||
|
||||
## 配置文件变更
|
||||
|
||||
切换供应商时，CC Switch 会修改以下文件：
|
||||
|
||||
### Claude
|
||||
|
||||
```
|
||||
~/.claude/settings.json
|
||||
```
|
||||
|
||||
修改内容：
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": "新的 API Key",
|
||||
"ANTHROPIC_BASE_URL": "新的端点"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Codex
|
||||
|
||||
```
|
||||
~/.codex/auth.json
|
||||
~/.codex/config.toml（如有额外配置）
|
||||
```
|
||||
|
||||
### Gemini
|
||||
|
||||
```
|
||||
~/.gemini/.env
|
||||
~/.gemini/settings.json
|
||||
```
|
||||
|
||||
## 切换失败处理
|
||||
|
||||
如果切换失败，可能的原因：
|
||||
|
||||
### 配置文件被锁定
|
||||
|
||||
其他程序正在使用配置文件。
|
||||
|
||||
**解决方法**：关闭正在运行的 CLI 工具，再尝试切换。
|
||||
|
||||
### 权限不足
|
||||
|
||||
没有写入配置文件的权限。
|
||||
|
||||
**解决方法**：检查配置目录的权限设置。
|
||||
|
||||
### 配置格式错误
|
||||
|
||||
供应商配置的 JSON 格式有误。
|
||||
|
||||
**解决方法**：编辑供应商，检查并修复 JSON 格式。
|
||||
@@ -1,145 +0,0 @@
|
||||
# 2.3 编辑供应商
|
||||
|
||||
## 打开编辑面板
|
||||
|
||||
1. 找到要编辑的供应商卡片
|
||||
2. 鼠标悬停在卡片上，显示操作按钮
|
||||
3. 点击「编辑」按钮
|
||||
|
||||
## 可编辑内容
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 名称 | 供应商显示名称 |
|
||||
| 备注 | 附加说明信息 |
|
||||
| 网站链接 | 供应商官网或控制台地址 |
|
||||
| 图标 | 自定义图标和颜色 |
|
||||
|
||||
### 图标自定义
|
||||
|
||||
CC Switch 提供丰富的图标自定义功能：
|
||||
|
||||
#### 图标选择器
|
||||
|
||||
1. 点击图标区域打开图标选择器
|
||||
2. 使用搜索框按名称搜索图标
|
||||
3. 点击选择想要的图标
|
||||
|
||||
图标库包含常见的 AI 服务商和技术图标，支持：
|
||||
- 按名称模糊搜索
|
||||
- 显示图标名称提示
|
||||
- 实时预览选中效果
|
||||
|
||||
|
||||
|
||||
### 配置信息
|
||||
|
||||
JSON 格式的配置内容，包括：
|
||||
|
||||
- API Key
|
||||
- 端点地址
|
||||
- 其他环境变量
|
||||
|
||||
### 编辑当前启用的供应商
|
||||
|
||||
编辑当前启用的供应商时，有特殊的「回填」机制：
|
||||
|
||||
1. 打开编辑面板时，会从 live 配置文件读取最新内容
|
||||
2. 如果你在 CLI 工具中手动修改过配置，这些修改会被同步回来
|
||||
3. 保存后，修改会写入 live 配置文件
|
||||
|
||||
这确保了 CC Switch 和 CLI 工具的配置始终同步。
|
||||
|
||||
## 修改 API Key
|
||||
|
||||
编辑供应商时，可以直接在 **API Key** 输入框中修改：
|
||||
|
||||
1. 点击供应商卡片的「编辑」按钮
|
||||
2. 在「API Key」输入框中输入新的密钥
|
||||
3. 点击「保存」
|
||||
|
||||
> 💡 **提示**：API Key 输入框支持显示/隐藏切换，点击右侧的眼睛图标可查看完整密钥。
|
||||
|
||||
## 修改端点地址
|
||||
|
||||
编辑供应商时，可以直接在 **端点地址** 输入框中修改：
|
||||
|
||||
1. 点击供应商卡片的「编辑」按钮
|
||||
2. 在「端点地址」输入框中输入新的 URL
|
||||
3. 点击「保存」
|
||||
|
||||
### 端点地址格式
|
||||
|
||||
| 应用 | 格式示例 |
|
||||
|------|----------|
|
||||
| Claude | `https://api.example.com` |
|
||||
| Codex | `https://api.example.com/v1` |
|
||||
| Gemini | `https://api.example.com` |
|
||||
|
||||
## 添加自定义端点
|
||||
|
||||
供应商可以配置多个端点，用于：
|
||||
|
||||
- 速度测试时测试多个地址
|
||||
- 故障转移时的备用端点
|
||||
|
||||
### 自动收集
|
||||
|
||||
添加供应商时，CC Switch 会自动从配置中提取端点地址。
|
||||
|
||||
### 手动添加
|
||||
|
||||
编辑供应商时，在「端点管理」区域可以：
|
||||
|
||||
- 添加新端点
|
||||
- 删除现有端点
|
||||
- 设置默认端点
|
||||
|
||||
## JSON 编辑器
|
||||
|
||||
配置使用 JSON 格式，编辑器提供：
|
||||
|
||||
- 语法高亮
|
||||
- 格式校验
|
||||
- 错误提示
|
||||
|
||||
### 常见错误
|
||||
|
||||
**缺少引号**：
|
||||
```json
|
||||
// ❌ 错误
|
||||
{ env: { KEY: "value" } }
|
||||
|
||||
// ✅ 正确
|
||||
{ "env": { "KEY": "value" } }
|
||||
```
|
||||
|
||||
**多余逗号**：
|
||||
```json
|
||||
// ❌ 错误
|
||||
{ "env": { "KEY": "value", } }
|
||||
|
||||
// ✅ 正确
|
||||
{ "env": { "KEY": "value" } }
|
||||
```
|
||||
|
||||
**未闭合括号**：
|
||||
```json
|
||||
// ❌ 错误
|
||||
{ "env": { "KEY": "value" }
|
||||
|
||||
// ✅ 正确
|
||||
{ "env": { "KEY": "value" } }
|
||||
```
|
||||
|
||||
## 保存与生效
|
||||
|
||||
1. 点击「保存」按钮
|
||||
2. 如果是当前启用的供应商，配置立即写入 live 文件
|
||||
3. 重启 CLI 工具生效
|
||||
|
||||
## 取消编辑
|
||||
|
||||
点击「取消」或按 `Esc` 键关闭编辑面板，所有修改都不会保存。
|
||||
@@ -1,76 +0,0 @@
|
||||
# 2.4 排序与复制
|
||||
|
||||
## 拖拽排序
|
||||
|
||||
通过拖拽调整供应商的显示顺序。
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 将鼠标移到供应商卡片左侧的 **≡** 拖拽手柄
|
||||
2. 按住鼠标左键
|
||||
3. 上下拖动到目标位置
|
||||
4. 松开鼠标完成排序
|
||||
|
||||
### 排序用途
|
||||
|
||||
- **常用优先**：将常用的供应商放在列表顶部
|
||||
- **故障转移顺序**：排序会影响故障转移队列的默认顺序
|
||||
|
||||
## 复制供应商
|
||||
|
||||
快速创建供应商的副本，适用于：
|
||||
|
||||
- 基于现有配置创建变体
|
||||
- 备份当前配置
|
||||
- 创建测试用配置
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 鼠标悬停在供应商卡片上，显示操作按钮
|
||||
2. 点击「复制」按钮
|
||||
3. 自动创建副本，名称后缀 `copy`
|
||||
4. 编辑副本修改配置
|
||||
|
||||
### 复制内容
|
||||
|
||||
复制会创建完整的副本，包括：
|
||||
|
||||
| 内容 | 是否复制 |
|
||||
|------|----------|
|
||||
| 名称 | ✅ 复制（添加 `copy` 后缀） |
|
||||
| 配置 | ✅ 完整复制 |
|
||||
| 备注 | ✅ 复制 |
|
||||
| 网站链接 | ✅ 复制 |
|
||||
| 图标 | ✅ 复制 |
|
||||
| 端点列表 | ✅ 复制 |
|
||||
| 排序位置 | ✅ 插入到原供应商下方 |
|
||||
|
||||
### 复制后编辑
|
||||
|
||||
复制完成后，通常需要修改：
|
||||
|
||||
1. **名称**：改为有意义的名称
|
||||
2. **API Key**：如果是不同账号
|
||||
3. **端点**：如果是不同服务
|
||||
|
||||
## 删除供应商
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 鼠标悬停在供应商卡片上，显示操作按钮
|
||||
2. 点击「删除」按钮
|
||||
3. 确认删除
|
||||
|
||||
### 删除确认
|
||||
|
||||
删除前会弹出确认对话框，显示：
|
||||
|
||||
- 供应商名称
|
||||
- 删除后无法恢复的提示
|
||||
|
||||
### 删除限制
|
||||
|
||||
- **当前启用的供应商**：可以删除，但建议先切换到其他供应商
|
||||
- **统一供应商**：删除后，关联的应用配置也会被删除
|
||||
|
||||
|
||||
@@ -1,181 +0,0 @@
|
||||
# 2.5 用量查询
|
||||
|
||||
## 功能说明
|
||||
|
||||
用量查询功能允许你配置自定义脚本，实时查询供应商的剩余额度、已用量等信息。
|
||||
|
||||
**使用场景**：
|
||||
- 查看 API 账户剩余余额
|
||||
- 监控套餐使用情况
|
||||
- 多套餐额度汇总显示
|
||||
|
||||
## 打开配置
|
||||
|
||||
1. 鼠标悬停在供应商卡片上，显示操作按钮
|
||||
2. 点击「用量查询」按钮（📊 图标）
|
||||
3. 打开用量查询配置面板
|
||||
|
||||
## 启用用量查询
|
||||
|
||||
在配置面板顶部，开启「启用用量查询」开关。
|
||||
|
||||
## 预设模板
|
||||
|
||||
CC Switch 提供三种预设模板：
|
||||
|
||||
### 自定义模板
|
||||
|
||||
完全自定义请求和提取逻辑，适用于特殊 API 格式。
|
||||
|
||||
### 通用模板
|
||||
|
||||
适用于大多数标准 API 格式的供应商：
|
||||
|
||||
```javascript
|
||||
({
|
||||
request: {
|
||||
url: "{{baseUrl}}/user/balance",
|
||||
method: "GET",
|
||||
headers: {
|
||||
"Authorization": "Bearer {{apiKey}}",
|
||||
"User-Agent": "cc-switch/1.0"
|
||||
}
|
||||
},
|
||||
extractor: function(response) {
|
||||
return {
|
||||
isValid: response.is_active || true,
|
||||
remaining: response.balance,
|
||||
unit: "USD"
|
||||
};
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
**配置参数**：
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| API Key | 用于认证的密钥（可选，留空则使用供应商配置的 Key） |
|
||||
| Base URL | API 基础地址（可选，留空则使用供应商端点） |
|
||||
|
||||
### New API 模板
|
||||
|
||||
专为 New API 类型的中转服务设计：
|
||||
|
||||
```javascript
|
||||
({
|
||||
request: {
|
||||
url: "{{baseUrl}}/api/user/self",
|
||||
method: "GET",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"Authorization": "Bearer {{accessToken}}",
|
||||
"New-Api-User": "{{userId}}"
|
||||
},
|
||||
},
|
||||
extractor: function (response) {
|
||||
if (response.success && response.data) {
|
||||
return {
|
||||
planName: response.data.group || "默认套餐",
|
||||
remaining: response.data.quota / 500000,
|
||||
used: response.data.used_quota / 500000,
|
||||
total: (response.data.quota + response.data.used_quota) / 500000,
|
||||
unit: "USD",
|
||||
};
|
||||
}
|
||||
return {
|
||||
isValid: false,
|
||||
invalidMessage: response.message || "查询失败"
|
||||
};
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**配置参数**：
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| Base URL | New API 服务地址 |
|
||||
| Access Token | 访问令牌 |
|
||||
| User ID | 用户 ID |
|
||||
|
||||
## 通用配置
|
||||
|
||||
### 超时时间
|
||||
|
||||
请求超时时间（秒），默认 10 秒。
|
||||
|
||||
### 自动查询间隔
|
||||
|
||||
自动刷新用量数据的间隔（分钟）：
|
||||
- 设为 `0` 表示禁用自动查询
|
||||
- 范围：0-1440 分钟（最长 24 小时）
|
||||
- 仅当供应商处于「当前启用」状态时生效
|
||||
|
||||
## 提取器返回格式
|
||||
|
||||
提取器函数需要返回包含以下字段的对象：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `isValid` | boolean | 否 | 账户是否有效，默认 true |
|
||||
| `invalidMessage` | string | 否 | 无效时的提示信息 |
|
||||
| `remaining` | number | 是 | 剩余额度 |
|
||||
| `unit` | string | 是 | 单位（如 USD、CNY、次） |
|
||||
| `planName` | string | 否 | 套餐名称（支持多套餐） |
|
||||
| `total` | number | 否 | 总额度 |
|
||||
| `used` | number | 否 | 已使用额度 |
|
||||
| `extra` | object | 否 | 额外信息 |
|
||||
|
||||
## 测试脚本
|
||||
|
||||
配置完成后，点击「测试脚本」按钮验证：
|
||||
|
||||
1. 发送请求到配置的 URL
|
||||
2. 执行提取器函数
|
||||
3. 显示返回结果或错误信息
|
||||
|
||||
## 显示效果
|
||||
|
||||
配置成功后，供应商卡片上会显示：
|
||||
|
||||
- **单套餐**：直接显示剩余额度
|
||||
- **多套餐**：显示套餐数量，点击展开查看详情
|
||||
|
||||
## 变量占位符
|
||||
|
||||
脚本中可使用以下占位符，运行时自动替换：
|
||||
|
||||
| 占位符 | 说明 |
|
||||
|--------|------|
|
||||
| `{{apiKey}}` | 配置的 API Key |
|
||||
| `{{baseUrl}}` | 配置的 Base URL |
|
||||
| `{{accessToken}}` | 配置的 Access Token（New API） |
|
||||
| `{{userId}}` | 配置的 User ID（New API） |
|
||||
|
||||
## 常见供应商配置示例
|
||||
|
||||
### 故障排除
|
||||
|
||||
### 查询失败
|
||||
|
||||
**检查**：
|
||||
1. API Key 是否正确
|
||||
2. Base URL 是否正确
|
||||
3. 网络是否可访问
|
||||
4. 超时时间是否足够
|
||||
|
||||
### 返回数据为空
|
||||
|
||||
**检查**：
|
||||
1. 提取器函数是否有 `return` 语句
|
||||
2. 响应数据结构是否与提取器匹配
|
||||
3. 使用「测试脚本」查看原始响应
|
||||
|
||||
### 格式化失败
|
||||
|
||||
脚本语法错误时，点击「格式化」按钮会提示错误位置。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 用量查询会消耗少量 API 请求配额
|
||||
- 建议设置合理的自动查询间隔，避免频繁请求
|
||||
- 敏感信息（API Key、Token）会安全存储在本地
|
||||
@@ -1,207 +0,0 @@
|
||||
# 3.1 MCP 服务器管理
|
||||
|
||||
## 什么是 MCP
|
||||
|
||||
MCP (Model Context Protocol) 是一种协议，允许 AI 工具访问外部数据源和工具。通过 MCP 服务器，你可以让 AI：
|
||||
|
||||
- 访问文件系统
|
||||
- 执行网络请求
|
||||
- 查询数据库
|
||||
- 调用外部 API
|
||||
|
||||
## 打开 MCP 面板
|
||||
|
||||
点击顶部导航栏的 **MCP** 按钮。
|
||||
|
||||
## 面板概览
|
||||
|
||||
|
||||
|
||||
## 添加 MCP 服务器
|
||||
|
||||
### 使用预设模板
|
||||
|
||||
1. 点击右上角 **+** 按钮
|
||||
2. 在「预设」下拉框中选择模板
|
||||
3. 根据需要修改配置
|
||||
4. 点击「保存」
|
||||
|
||||
|
||||
|
||||
### 常用预设
|
||||
|
||||
| 预设 | 包名 | 功能说明 |
|
||||
|------|------|----------|
|
||||
| fetch | mcp-server-fetch | HTTP 请求工具，让 AI 能够获取网页内容 |
|
||||
| time | @modelcontextprotocol/server-time | 时间工具，提供当前时间信息 |
|
||||
| memory | @modelcontextprotocol/server-memory | 记忆工具，让 AI 能够存储和检索信息 |
|
||||
| sequential-thinking | @modelcontextprotocol/server-sequential-thinking | 思维链工具，增强 AI 推理能力 |
|
||||
| context7 | @upstash/context7-mcp | 文档搜索工具，查询技术文档 |
|
||||
|
||||
### 自定义配置
|
||||
|
||||
选择「自定义」后，需要填写：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| 服务器 ID | 是 | 唯一标识符 |
|
||||
| 名称 | 否 | 显示名称 |
|
||||
| 描述 | 否 | 功能说明 |
|
||||
| 传输类型 | 是 | stdio / http / sse |
|
||||
| 命令 | 是* | stdio 类型必填 |
|
||||
| 参数 | 否 | 命令行参数 |
|
||||
| URL | 是* | http/sse 类型必填 |
|
||||
| Headers | 否 | http/sse 类型的请求头 |
|
||||
| 环境变量 | 否 | 传递给服务器的环境变量 |
|
||||
|
||||
## 传输类型
|
||||
|
||||
### stdio（标准输入输出）
|
||||
|
||||
最常用的类型，通过启动本地进程通信。
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"],
|
||||
"env": {}
|
||||
}
|
||||
```
|
||||
|
||||
**要求**：
|
||||
- 需要安装对应的命令（如 `uvx`、`npx`）
|
||||
- 服务器程序需要在 PATH 中
|
||||
|
||||
### http
|
||||
|
||||
通过 HTTP 协议与远程服务器通信。
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "http://localhost:8080/mcp"
|
||||
}
|
||||
```
|
||||
|
||||
### sse（Server-Sent Events）
|
||||
|
||||
通过 SSE 协议与服务器通信，支持实时推送。
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "http://localhost:8080/sse"
|
||||
}
|
||||
```
|
||||
|
||||
## 应用绑定
|
||||
|
||||
每个 MCP 服务器可以独立控制启用的应用。
|
||||
|
||||
### 开关说明
|
||||
|
||||
| 开关 | 作用 | 配置文件路径 |
|
||||
|------|------|--------------|
|
||||
| Claude | 同步到 Claude Code | `~/.claude.json` 的 `mcpServers` |
|
||||
| Codex | 同步到 Codex | `~/.codex/config.toml` 的 `[mcp_servers]` |
|
||||
| Gemini | 同步到 Gemini CLI | `~/.gemini/settings.json` 的 `mcpServers` |
|
||||
| OpenCode | 同步到 OpenCode | `~/.opencode/config.json` 的 `mcpServers` |
|
||||
|
||||
### 开关实现机制
|
||||
|
||||
当开启某个应用的开关时，CC Switch 会：
|
||||
|
||||
1. **更新数据库**：将服务器的 `apps.claude/codex/gemini/opencode` 状态设为 `true`
|
||||
2. **同步到 Live 配置**：将服务器配置写入对应应用的配置文件
|
||||
3. **即时生效**：下次启动 CLI 工具时自动加载新的 MCP 服务器
|
||||
|
||||
当关闭某个应用的开关时，CC Switch 会：
|
||||
|
||||
1. **更新数据库**：将对应应用状态设为 `false`
|
||||
2. **从 Live 配置移除**：从应用配置文件中删除该服务器
|
||||
3. **即时生效**：下次启动 CLI 工具时不再加载该 MCP 服务器
|
||||
|
||||
### 同步条件
|
||||
|
||||
MCP 服务器同步仅在对应应用已安装时执行：
|
||||
|
||||
- **Claude**：需存在 `~/.claude/` 目录或 `~/.claude.json` 文件
|
||||
- **Codex**：需存在 `~/.codex/` 目录
|
||||
- **Gemini**：需存在 `~/.gemini/` 目录
|
||||
- **OpenCode**：需存在 `~/.opencode/` 目录
|
||||
|
||||
> 💡 **提示**：如果某个 CLI 工具未安装，开启对应开关不会报错，但配置不会写入。
|
||||
|
||||
关闭开关后，配置会从文件中移除。
|
||||
|
||||
## 编辑服务器
|
||||
|
||||
1. 点击服务器行右侧的「编辑」按钮
|
||||
2. 修改配置
|
||||
3. 点击「保存」
|
||||
|
||||
修改会立即同步到已启用的应用配置文件。
|
||||
|
||||
## 删除服务器
|
||||
|
||||
1. 点击服务器行右侧的「删除」按钮
|
||||
2. 确认删除
|
||||
|
||||
删除后，配置会从所有应用的配置文件中移除。
|
||||
|
||||
## 导入现有配置
|
||||
|
||||
如果你已经在 CLI 工具中配置了 MCP 服务器，可以导入到 CC Switch：
|
||||
|
||||
1. 点击「导入」按钮
|
||||
2. 选择要导入的应用（Claude/Codex/Gemini/OpenCode）
|
||||
3. CC Switch 会读取现有配置并导入
|
||||
|
||||
## 配置文件格式
|
||||
|
||||
### Claude (`~/.claude.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Codex (`~/.codex/config.toml`)
|
||||
|
||||
```toml
|
||||
[mcp_servers.mcp-fetch]
|
||||
command = "uvx"
|
||||
args = ["mcp-server-fetch"]
|
||||
```
|
||||
|
||||
### Gemini (`~/.gemini/settings.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 服务器启动失败
|
||||
|
||||
检查：
|
||||
- 命令是否正确安装（如 `uvx`）
|
||||
- 命令是否在 PATH 中
|
||||
- 参数是否正确
|
||||
|
||||
### 配置不生效
|
||||
|
||||
确保：
|
||||
- 对应应用的开关已开启
|
||||
- 重启了 CLI 工具
|
||||
@@ -1,158 +0,0 @@
|
||||
# 3.2 Prompts 提示词管理
|
||||
|
||||
## 功能说明
|
||||
|
||||
Prompts 功能用于管理系统提示词预设。系统提示词会影响 AI 的行为和回复风格。
|
||||
|
||||
通过 CC Switch，你可以：
|
||||
|
||||
- 创建多个提示词预设
|
||||
- 快速切换不同场景的提示词
|
||||
- 跨设备同步提示词配置
|
||||
|
||||
## 打开 Prompts 面板
|
||||
|
||||
点击顶部导航栏的 **Prompts** 按钮。
|
||||
|
||||
## 面板概览
|
||||
|
||||
|
||||
|
||||
## 创建预设
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 点击右上角 **+** 按钮
|
||||
2. 输入预设名称
|
||||
3. 在 Markdown 编辑器中编写提示词
|
||||
4. 点击「保存」
|
||||
|
||||
### Markdown 编辑器
|
||||
|
||||
编辑器提供：
|
||||
|
||||
- 语法高亮
|
||||
- 实时预览
|
||||
- 常用格式快捷键
|
||||
|
||||
### 提示词编写建议
|
||||
|
||||
**结构化格式**：
|
||||
|
||||
```markdown
|
||||
# 角色定义
|
||||
|
||||
你是一个专业的代码审查专家。
|
||||
|
||||
## 核心能力
|
||||
|
||||
- 代码质量分析
|
||||
- 性能优化建议
|
||||
- 安全漏洞检测
|
||||
|
||||
## 回复风格
|
||||
|
||||
- 简洁明了
|
||||
- 提供具体示例
|
||||
- 给出改进建议
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 不要修改业务逻辑
|
||||
- 保持代码风格一致
|
||||
```
|
||||
|
||||
## 激活预设
|
||||
|
||||
### 操作方式
|
||||
|
||||
点击预设项的开关按钮，切换启用状态。
|
||||
|
||||
### 单一激活
|
||||
|
||||
同一时间只能激活一个预设。激活新预设时，之前的预设会自动停用。
|
||||
|
||||
### 同步目标
|
||||
|
||||
激活后，提示词会写入对应应用的文件：
|
||||
|
||||
| 应用 | 文件路径 |
|
||||
|------|----------|
|
||||
| Claude | `~/.claude/CLAUDE.md` |
|
||||
| Codex | `~/.codex/AGENTS.md` |
|
||||
| Gemini | `~/.gemini/GEMINI.md` |
|
||||
| OpenCode | `~/.opencode/AGENTS.md` |
|
||||
|
||||
## 编辑预设
|
||||
|
||||
1. 点击预设项的「编辑」按钮
|
||||
2. 修改名称或内容
|
||||
3. 点击「保存」
|
||||
|
||||
如果编辑的是当前激活的预设，保存后会立即同步到配置文件。
|
||||
|
||||
## 删除预设
|
||||
|
||||
1. 点击预设项的「删除」按钮
|
||||
2. 确认删除
|
||||
|
||||
已启用的预设不允许删除，需先停用后再删除。
|
||||
|
||||
## 智能回填
|
||||
|
||||
CC Switch 提供智能回填保护机制，确保你的手动修改不会丢失。
|
||||
|
||||
### 工作原理
|
||||
|
||||
1. 切换预设前，自动读取当前配置文件内容
|
||||
2. 比较文件内容与数据库中的预设
|
||||
3. 如果内容不同，说明用户手动修改过
|
||||
4. 将手动修改的内容保存到当前预设
|
||||
5. 然后再切换到新预设
|
||||
|
||||
### 保护场景
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|----------|
|
||||
| CLI 中直接编辑 `CLAUDE.md` | 修改自动保存到当前预设 |
|
||||
| 外部编辑器修改配置文件 | 修改自动保存到当前预设 |
|
||||
| 切换到其他预设 | 先保存当前修改，再切换 |
|
||||
|
||||
### 技术细节
|
||||
|
||||
回填机制在以下时机触发：
|
||||
|
||||
- **切换预设时**：保存当前 live 文件内容到当前预设
|
||||
- **编辑当前预设时**：从 live 文件读取最新内容
|
||||
- **首次启动时**：自动导入现有 live 文件内容
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 回填仅在切换到不同预设时触发
|
||||
- 如果当前没有激活的预设，不会触发回填
|
||||
- 回填失败不会影响切换流程
|
||||
|
||||
## 跨应用使用
|
||||
|
||||
Prompts 是按应用分开管理的：
|
||||
|
||||
- 切换到 Claude 时，显示 Claude 的预设
|
||||
- 切换到 Codex 时，显示 Codex 的预设
|
||||
- 切换到 Gemini 时，显示 Gemini 的预设
|
||||
- 切换到 OpenCode 时，显示 OpenCode 的预设
|
||||
|
||||
如需在多个应用使用相同的提示词，需要分别创建。
|
||||
|
||||
## 导入导出
|
||||
|
||||
### 通过深度链接分享
|
||||
|
||||
可以生成深度链接分享预设：
|
||||
|
||||
```
|
||||
ccswitch://import/prompt?data=<base64编码的预设>
|
||||
```
|
||||
|
||||
### 通过配置导出
|
||||
|
||||
导出配置时会包含所有预设，导入后可恢复。
|
||||
@@ -1,199 +0,0 @@
|
||||
# 3.3 Skills 技能管理
|
||||
|
||||
## 功能说明
|
||||
|
||||
Skills 是可复用的能力扩展，让 AI 工具获得特定领域的专业能力。
|
||||
|
||||
技能以文件夹形式存在，包含：
|
||||
- 提示词模板
|
||||
- 工具定义
|
||||
- 示例代码
|
||||
|
||||
## 支持的应用
|
||||
|
||||
Skills 功能支持所有四种应用：
|
||||
- **Claude Code**
|
||||
- **Codex**
|
||||
- **Gemini CLI**
|
||||
- **OpenCode**
|
||||
|
||||
## 打开 Skills 页面
|
||||
|
||||
点击顶部导航栏的 **Skills** 按钮。
|
||||
|
||||
> 注意：Skills 按钮在所有应用模式下均可见。
|
||||
|
||||
## 页面概览
|
||||
|
||||
|
||||
|
||||
## 发现技能
|
||||
|
||||
### 预配置仓库
|
||||
|
||||
CC Switch 预配置了以下 GitHub 仓库：
|
||||
|
||||
| 仓库 | 说明 |
|
||||
|------|------|
|
||||
| Anthropic 官方 | Anthropic 提供的官方技能 |
|
||||
| ComposioHQ | 社区维护的技能集合 |
|
||||
| 社区精选 | 精选的高质量技能 |
|
||||
|
||||
|
||||
|
||||
### 搜索过滤
|
||||
|
||||
CC Switch 提供强大的搜索和过滤功能：
|
||||
|
||||
#### 搜索框
|
||||
|
||||
- 支持按技能名称搜索
|
||||
- 支持按技能描述搜索
|
||||
- 支持按目录名称搜索
|
||||
- 实时过滤，输入即搜索
|
||||
|
||||
#### 状态过滤
|
||||
|
||||
使用下拉菜单按安装状态过滤：
|
||||
|
||||
| 选项 | 说明 |
|
||||
|------|------|
|
||||
| 全部 | 显示所有技能 |
|
||||
| 已安装 | 仅显示已安装的技能 |
|
||||
| 未安装 | 仅显示未安装的技能 |
|
||||
|
||||
|
||||
|
||||
#### 组合使用
|
||||
|
||||
搜索和过滤可以组合使用：
|
||||
- 先选择「已安装」过滤
|
||||
- 再输入关键词搜索
|
||||
- 结果显示匹配数量
|
||||
|
||||
### 刷新列表
|
||||
|
||||
点击「刷新」按钮重新扫描仓库，获取最新技能。
|
||||
|
||||
## 安装技能
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 找到要安装的技能卡片
|
||||
2. 点击「安装」按钮
|
||||
3. 等待安装完成
|
||||
|
||||
### 安装位置
|
||||
|
||||
| 应用 | 安装目录 |
|
||||
|------|----------|
|
||||
| Claude | `~/.claude/skills/` |
|
||||
| Codex | `~/.codex/skills/` |
|
||||
| Gemini | `~/.gemini/skills/` |
|
||||
| OpenCode | `~/.opencode/skills/` |
|
||||
|
||||
### 安装内容
|
||||
|
||||
安装会将技能文件夹复制到本地：
|
||||
|
||||
```
|
||||
~/.claude/skills/
|
||||
└── skill-name/
|
||||
├── README.md
|
||||
├── prompt.md
|
||||
└── tools/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 卸载技能
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 找到已安装的技能卡片
|
||||
2. 点击「卸载」按钮
|
||||
3. 确认卸载
|
||||
|
||||
### 卸载效果
|
||||
|
||||
- 删除本地技能文件夹
|
||||
- 更新安装状态
|
||||
|
||||
## 仓库管理
|
||||
|
||||
### 打开仓库管理
|
||||
|
||||
点击页面顶部的「仓库管理」按钮。
|
||||
|
||||
### 添加自定义仓库
|
||||
|
||||
1. 点击「添加仓库」
|
||||
2. 填写仓库信息：
|
||||
- Owner：GitHub 用户名或组织名
|
||||
- Name：仓库名称
|
||||
- Branch：分支名（默认 main）
|
||||
- Subdirectory：技能所在子目录（可选）
|
||||
3. 点击「添加」
|
||||
|
||||
### 仓库格式
|
||||
|
||||
```
|
||||
https://github.com/{owner}/{name}/tree/{branch}/{subdirectory}
|
||||
```
|
||||
|
||||
示例：
|
||||
```
|
||||
Owner: anthropics
|
||||
Name: claude-skills
|
||||
Branch: main
|
||||
Subdirectory: skills
|
||||
```
|
||||
|
||||
### 删除仓库
|
||||
|
||||
1. 在仓库列表中找到要删除的仓库
|
||||
2. 点击「删除」按钮
|
||||
3. 确认删除
|
||||
|
||||
删除仓库后，该仓库的技能不会从列表中消失，但无法再更新。
|
||||
|
||||
## 技能卡片信息
|
||||
|
||||
每个技能卡片显示：
|
||||
|
||||
| 信息 | 说明 |
|
||||
|------|------|
|
||||
| 名称 | 技能名称 |
|
||||
| 描述 | 功能说明 |
|
||||
| 来源 | 所属仓库 |
|
||||
| 状态 | 已安装 / 未安装 |
|
||||
|
||||
## 技能更新
|
||||
|
||||
目前不支持自动更新。如需更新技能：
|
||||
|
||||
1. 卸载现有技能
|
||||
2. 刷新列表
|
||||
3. 重新安装
|
||||
|
||||
### 技能列表为空
|
||||
|
||||
可能原因：
|
||||
- 网络问题，无法访问 GitHub
|
||||
- 仓库配置错误
|
||||
|
||||
解决方法：
|
||||
- 检查网络连接
|
||||
- 点击「刷新」重试
|
||||
- 检查仓库配置
|
||||
|
||||
### 安装失败
|
||||
|
||||
可能原因：
|
||||
- 网络问题
|
||||
- 磁盘空间不足
|
||||
- 权限问题
|
||||
|
||||
解决方法：
|
||||
- 检查网络连接
|
||||
- 检查磁盘空间
|
||||
- 检查目录权限
|
||||
@@ -1,222 +0,0 @@
|
||||
# 4.1 代理服务
|
||||
|
||||
## 功能说明
|
||||
|
||||
代理服务在本地启动一个 HTTP 代理，所有 API 请求都通过代理转发。
|
||||
|
||||
**主要用途**：
|
||||
- 记录请求日志
|
||||
- 统计 API 用量
|
||||
- 支持故障转移
|
||||
- 集中管理多个应用的请求
|
||||
|
||||
## 启动代理
|
||||
|
||||
### 方式一：主界面开关
|
||||
|
||||
点击主界面顶部的 **代理开关** 按钮。
|
||||
|
||||
开关状态：
|
||||
- 🔴 白色：代理未运行
|
||||
- 🟢 绿色：代理运行中
|
||||
|
||||
|
||||
|
||||
### 方式二：设置页面
|
||||
|
||||
1. 打开「设置 → 高级 → 代理服务」
|
||||
2. 点击右上角的开关
|
||||
|
||||
|
||||
|
||||
## 代理配置
|
||||
|
||||
### 基础配置
|
||||
|
||||
| 配置项 | 说明 | 默认值 |
|
||||
|--------|------|--------|
|
||||
| 监听地址 | 代理绑定的 IP 地址 | `127.0.0.1` |
|
||||
| 监听端口 | 代理监听的端口 | `15721` |
|
||||
| 启用日志 | 是否记录请求日志 | 开启 |
|
||||
|
||||
### 修改配置
|
||||
|
||||
1. **停止代理服务**（必须先停止）
|
||||
2. 修改监听地址或端口
|
||||
3. 点击「保存」
|
||||
4. 重新启动代理
|
||||
|
||||
> ⚠️ 修改地址/端口需要先停止代理服务
|
||||
|
||||
### 监听地址说明
|
||||
|
||||
| 地址 | 说明 |
|
||||
|------|------|
|
||||
| `127.0.0.1` | 仅本机可访问（推荐） |
|
||||
| `0.0.0.0` | 允许局域网访问 |
|
||||
|
||||
## 运行状态
|
||||
|
||||
代理运行时，面板显示以下信息：
|
||||
|
||||
### 服务地址
|
||||
|
||||
```
|
||||
http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
点击「复制」按钮可复制地址。
|
||||
|
||||
### 当前供应商
|
||||
|
||||
显示各应用当前使用的供应商：
|
||||
|
||||
```
|
||||
Claude: PackyCode
|
||||
Codex: AIGoCode
|
||||
Gemini: Google 官方
|
||||
```
|
||||
|
||||
### 统计数据
|
||||
|
||||
| 指标 | 说明 |
|
||||
|------|------|
|
||||
| 活跃连接 | 当前正在处理的请求数 |
|
||||
| 总请求数 | 启动以来的总请求数 |
|
||||
| 成功率 | 请求成功的百分比（>90% 绿色，≤90% 黄色） |
|
||||
| 运行时间 | 代理已运行的时长 |
|
||||
|
||||
### 故障转移队列
|
||||
|
||||
代理面板会按应用类型显示故障转移队列：
|
||||
|
||||
```
|
||||
Claude
|
||||
├── 1. PackyCode [当前使用] ●
|
||||
├── 2. AIGoCode ●
|
||||
└── 3. 备用供应商 ○
|
||||
|
||||
Codex
|
||||
├── 1. AIGoCode [当前使用] ●
|
||||
└── 2. 备用供应商 ●
|
||||
```
|
||||
|
||||
队列说明：
|
||||
- 数字表示优先级顺序
|
||||
- 「当前使用」标签表示正在使用的供应商
|
||||
- 健康徽章显示供应商状态：
|
||||
- 🟢 绿色：健康（连续失败 0 次）
|
||||
- 🟡 黄色：降级（连续失败 1-2 次）
|
||||
- 🔴 红色：不健康（连续失败 ≥3 次）
|
||||
|
||||
## 工作原理
|
||||
|
||||
### 请求流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as CLI 工具 (Claude)
|
||||
participant Proxy as 本地代理 (CC Switch)
|
||||
participant API as API 供应商 (Anthropic)
|
||||
participant DB as 数据存储 (Logger)
|
||||
|
||||
CLI->>Proxy: 发送 API 请求
|
||||
Proxy->>DB: 记录请求日志/统计用量
|
||||
Proxy->>API: 转发请求
|
||||
API-->>Proxy: 返回响应
|
||||
Proxy-->>CLI: 返回响应
|
||||
```
|
||||
|
||||
### 配置修改
|
||||
|
||||
启动代理并开启应用接管后，CC Switch 会修改应用配置：
|
||||
|
||||
**Claude**：
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex**：
|
||||
```toml
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini**：
|
||||
```
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
## 停止代理
|
||||
|
||||
### 方式一：主界面开关
|
||||
|
||||
点击代理开关按钮关闭。
|
||||
|
||||
### 方式二：设置页面
|
||||
|
||||
在代理服务面板中关闭开关。
|
||||
|
||||
### 停止后的处理
|
||||
|
||||
停止代理时，CC Switch 会：
|
||||
|
||||
1. 恢复应用配置到原始状态
|
||||
2. 保存请求日志
|
||||
3. 关闭所有连接
|
||||
|
||||
## 日志记录
|
||||
|
||||
### 开启日志
|
||||
|
||||
在代理面板中开启「启用日志」开关。
|
||||
|
||||
### 日志内容
|
||||
|
||||
每条请求记录包含：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 时间 | 请求时间 |
|
||||
| 应用 | Claude/Codex/Gemini/OpenCode |
|
||||
| 供应商 | 使用的供应商 |
|
||||
| 模型 | 请求的模型 |
|
||||
| Token | 输入/输出 token 数 |
|
||||
| 延迟 | 请求耗时 |
|
||||
| 状态 | 成功/失败 |
|
||||
|
||||
### 查看日志
|
||||
|
||||
在「设置 → 用量」Tab 中查看请求日志。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 端口被占用
|
||||
|
||||
错误信息：`Address already in use`
|
||||
|
||||
解决方法：
|
||||
1. 更换端口（如 5001）
|
||||
2. 或关闭占用端口的程序
|
||||
|
||||
### 代理启动失败
|
||||
|
||||
检查：
|
||||
- 端口是否被占用
|
||||
- 是否有足够权限
|
||||
- 防火墙是否阻止
|
||||
|
||||
### 请求超时
|
||||
|
||||
可能原因：
|
||||
- 网络问题
|
||||
- 供应商服务器问题
|
||||
- 代理配置错误
|
||||
|
||||
解决方法：
|
||||
- 检查网络连接
|
||||
- 尝试直接访问供应商 API
|
||||
- 检查供应商配置
|
||||
@@ -1,196 +0,0 @@
|
||||
# 4.2 应用接管
|
||||
|
||||
## 功能说明
|
||||
|
||||
应用接管是指让 CC Switch 代理接管特定应用的 API 请求。
|
||||
|
||||
开启接管后：
|
||||
- 应用的 API 请求会通过本地代理转发
|
||||
- 可以记录请求日志和统计用量
|
||||
- 可以使用故障转移功能
|
||||
|
||||
## 前提条件
|
||||
|
||||
使用应用接管功能前，需要先启动代理服务。
|
||||
|
||||
## 开启接管
|
||||
|
||||
### 操作位置
|
||||
|
||||
设置 → 高级 → 代理服务 → 应用接管区域
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 确保代理服务已启动
|
||||
2. 找到「应用接管」区域
|
||||
3. 为需要的应用开启开关
|
||||
|
||||
### 接管开关
|
||||
|
||||
| 开关 | 作用 |
|
||||
|------|------|
|
||||
| Claude 接管 | 接管 Claude Code 的请求 |
|
||||
| Codex 接管 | 接管 Codex 的请求 |
|
||||
| Gemini 接管 | 接管 Gemini CLI 的请求 |
|
||||
| OpenCode 接管 | 接管 OpenCode 的请求 |
|
||||
|
||||
可以同时开启多个应用的接管。
|
||||
|
||||
## 接管原理
|
||||
|
||||
### 配置修改
|
||||
|
||||
开启接管后，CC Switch 会修改应用的配置文件，将 API 端点指向本地代理。
|
||||
|
||||
**Claude 配置变更**：
|
||||
|
||||
```json
|
||||
// 接管前
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
|
||||
}
|
||||
}
|
||||
|
||||
// 接管后
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex 配置变更**：
|
||||
|
||||
```toml
|
||||
# 接管前
|
||||
base_url = "https://api.openai.com/v1"
|
||||
|
||||
# 接管后
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini 配置变更**：
|
||||
|
||||
```bash
|
||||
# 接管前
|
||||
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
|
||||
# 接管后
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
### 请求转发
|
||||
|
||||
代理收到请求后：
|
||||
|
||||
1. 识别请求来源（Claude/Codex/Gemini/OpenCode）
|
||||
2. 查找该应用当前启用的供应商
|
||||
3. 将请求转发到供应商的实际端点
|
||||
4. 记录请求日志
|
||||
5. 返回响应给应用
|
||||
|
||||
## 接管状态指示
|
||||
|
||||
### 主界面指示
|
||||
|
||||
开启接管后，主界面会有以下变化：
|
||||
|
||||
- **代理 Logo 颜色**：从无色变为绿色
|
||||
- **供应商卡片**：当前活跃的供应商显示绿色边框
|
||||
|
||||
### 供应商卡片状态
|
||||
|
||||
| 状态 | 边框颜色 | 说明 |
|
||||
|------|----------|------|
|
||||
| 当前启用 | 蓝色 | 配置文件中的供应商（非代理模式） |
|
||||
| 代理活跃 | 绿色 | 代理实际使用的供应商 |
|
||||
| 普通 | 默认 | 未使用的供应商 |
|
||||
|
||||
## 关闭接管
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 在代理面板中关闭对应应用的接管开关
|
||||
2. 或直接停止代理服务
|
||||
|
||||
### 配置恢复
|
||||
|
||||
关闭接管时，CC Switch 会：
|
||||
|
||||
1. 将应用配置恢复到接管前的状态
|
||||
2. 保存当前的请求日志
|
||||
|
||||
## 接管与供应商切换
|
||||
|
||||
### 接管模式下切换供应商
|
||||
|
||||
在接管模式下切换供应商：
|
||||
|
||||
1. 在主界面点击供应商的「启用」按钮
|
||||
2. 代理立即使用新供应商转发请求
|
||||
3. **无需重启 CLI 工具**
|
||||
|
||||
这是接管模式的一大优势：切换供应商即时生效。
|
||||
|
||||
### 非接管模式下切换
|
||||
|
||||
在非接管模式下切换供应商：
|
||||
|
||||
1. 修改配置文件
|
||||
2. 需要重启 CLI 工具才能生效
|
||||
|
||||
## 多应用接管
|
||||
|
||||
可以同时接管多个应用，每个应用独立管理：
|
||||
|
||||
- 独立的供应商配置
|
||||
- 独立的故障转移队列
|
||||
- 独立的请求统计
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景一：用量监控
|
||||
|
||||
开启接管 + 日志记录，监控 API 使用情况。
|
||||
|
||||
### 场景二：快速切换
|
||||
|
||||
开启接管后，切换供应商无需重启 CLI 工具。
|
||||
|
||||
### 场景三：故障转移
|
||||
|
||||
开启接管是使用故障转移功能的前提。
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 性能影响
|
||||
|
||||
代理会增加少量延迟（通常 < 10ms），对于大多数场景可以忽略。
|
||||
|
||||
### 网络要求
|
||||
|
||||
接管模式下，CLI 工具需要能够访问本地代理地址。
|
||||
|
||||
### 配置备份
|
||||
|
||||
开启接管前，CC Switch 会备份原始配置，关闭时恢复。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 接管后请求失败
|
||||
|
||||
检查：
|
||||
- 代理服务是否正常运行
|
||||
- 供应商配置是否正确
|
||||
- 网络是否正常
|
||||
|
||||
### 关闭接管后配置未恢复
|
||||
|
||||
可能原因：
|
||||
- 代理异常退出
|
||||
- 配置文件被其他程序修改
|
||||
|
||||
解决方法：
|
||||
- 手动编辑供应商，重新保存
|
||||
- 或重新启用再关闭接管
|
||||
@@ -1,233 +0,0 @@
|
||||
# 4.3 故障转移
|
||||
|
||||
## 功能说明
|
||||
|
||||
故障转移功能在主供应商请求失败时，自动切换到备用供应商，确保服务不中断。
|
||||
|
||||
**适用场景**：
|
||||
- 供应商服务不稳定
|
||||
- 需要高可用性
|
||||
- 长时间运行的任务
|
||||
|
||||
## 前提条件
|
||||
|
||||
使用故障转移功能需要：
|
||||
|
||||
1. ✅ 启动代理服务
|
||||
2. ✅ 开启应用接管
|
||||
3. ✅ 配置故障转移队列
|
||||
4. ✅ 开启自动故障转移
|
||||
|
||||
## 配置故障转移队列
|
||||
|
||||
### 打开配置页面
|
||||
|
||||
设置 → 高级 → 故障转移
|
||||
|
||||
### 选择应用
|
||||
|
||||
页面顶部有四个 Tab：
|
||||
- Claude
|
||||
- Codex
|
||||
- Gemini
|
||||
- OpenCode
|
||||
|
||||
选择要配置的应用。
|
||||
|
||||
### 添加备用供应商
|
||||
|
||||
1. 在「故障转移队列」区域
|
||||
2. 点击「添加供应商」
|
||||
3. 从下拉列表选择供应商
|
||||
4. 供应商会添加到队列末尾
|
||||
|
||||
### 调整优先级
|
||||
|
||||
拖拽供应商调整顺序：
|
||||
- 序号越小，优先级越高
|
||||
- 主供应商失败后，按顺序尝试备用供应商
|
||||
|
||||
### 移除供应商
|
||||
|
||||
点击供应商右侧的「移除」按钮。
|
||||
|
||||
## 主界面快捷操作
|
||||
|
||||
当代理和故障转移都开启时，供应商卡片会显示故障转移开关。
|
||||
|
||||
### 添加到队列
|
||||
|
||||
1. 找到供应商卡片
|
||||
2. 开启故障转移开关
|
||||
3. 供应商自动添加到队列
|
||||
|
||||
### 从队列移除
|
||||
|
||||
1. 关闭供应商卡片的故障转移开关
|
||||
2. 供应商从队列中移除
|
||||
|
||||
## 开启自动故障转移
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 在故障转移配置页面
|
||||
2. 开启「自动故障转移」开关
|
||||
|
||||
### 开关说明
|
||||
|
||||
| 状态 | 行为 |
|
||||
|------|------|
|
||||
| 关闭 | 仅记录失败，不自动切换 |
|
||||
| 开启 | 失败时自动切换到下一个供应商 |
|
||||
|
||||
## 故障转移流程
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start[请求到达代理] --> Send[发送到当前供应商]
|
||||
Send --> CheckSuccess{成功?}
|
||||
CheckSuccess -- 是 --> Return[返回响应]
|
||||
CheckSuccess -- 否 --> LogFail[记录失败]
|
||||
LogFail --> CheckCircuit{检查熔断状态}
|
||||
CheckCircuit -- 熔断 --> Skip[跳过此供应商]
|
||||
CheckCircuit -- 未熔断 --> IncFail[增加失败计数]
|
||||
Skip --> Next{队列中下一个?}
|
||||
IncFail --> Next
|
||||
Next -- 有 --> Switch[切换供应商]
|
||||
Switch --> Retry[重试请求]
|
||||
Retry --> Send
|
||||
Next -- 无 --> Error[返回错误]
|
||||
```
|
||||
|
||||
## 熔断器配置
|
||||
|
||||
熔断器防止频繁重试失败的供应商。
|
||||
|
||||
### 配置项
|
||||
|
||||
不同应用有独立的默认配置。以下为通用默认值，Claude 有独立的宽松配置。
|
||||
|
||||
| 配置 | 说明 | 通用默认值 | Claude 默认值 | 范围 |
|
||||
|------|------|--------|--------|------|
|
||||
| 失败阈值 | 连续失败多少次触发熔断 | 4 | 8 | 1-20 |
|
||||
| 恢复成功阈值 | 半开状态下成功多少次后关闭熔断器 | 2 | 3 | 1-10 |
|
||||
| 恢复等待时间 | 熔断后多久尝试恢复（秒） | 60 | 90 | 0-300 |
|
||||
| 错误率阈值 | 错误率超过此值时打开熔断器 | 60% | 70% | 0-100% |
|
||||
| 最小请求数 | 计算错误率前的最小请求数 | 10 | 15 | 5-100 |
|
||||
|
||||
> 💡 Claude 由于请求耗时较长，默认配置更为宽松，容忍更多失败次数。
|
||||
|
||||
### 超时配置
|
||||
|
||||
| 配置 | 说明 | 通用默认值 | Claude 默认值 | 范围 |
|
||||
|------|------|--------|--------|------|
|
||||
| 流式首字节超时 | 等待首个数据块的最大时间（秒） | 60 | 90 | 1-120 |
|
||||
| 流式静默超时 | 数据块之间的最大间隔（秒） | 120 | 180 | 60-600（填 0 禁用） |
|
||||
| 非流式超时 | 非流式请求的总超时时间（秒） | 600 | 600 | 60-1200 |
|
||||
|
||||
### 重试配置
|
||||
|
||||
| 配置 | 说明 | 通用默认值 | Claude 默认值 | 范围 |
|
||||
|------|------|--------|--------|------|
|
||||
| 最大重试次数 | 请求失败时的重试次数 | 3 | 6 | 0-10 |
|
||||
|
||||
> 💡 Gemini 的默认最大重试次数为 5。
|
||||
|
||||
### 熔断状态
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| 关闭 | 正常状态，允许请求 |
|
||||
| 开启 | 熔断状态，跳过此供应商 |
|
||||
| 半开 | 尝试恢复，发送试探请求 |
|
||||
|
||||
### 状态转换
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Closed: 初始化
|
||||
Closed --> Open: 失败次数 >= 阈值
|
||||
Open --> HalfOpen: 熔断时长到期
|
||||
HalfOpen --> Closed: 试探成功 (>= 恢复阈值)
|
||||
HalfOpen --> Open: 试探失败
|
||||
```
|
||||
|
||||
## 健康状态指示
|
||||
|
||||
### 供应商卡片
|
||||
|
||||
卡片上显示健康状态徽章：
|
||||
|
||||
| 徽章 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 🟢 | 健康 | 连续失败次数为 0 |
|
||||
| 🟡 | 警告 | 有失败但未触发熔断 |
|
||||
| 🔴 | 熔断 | 已触发熔断，暂时跳过 |
|
||||
|
||||
### 队列列表
|
||||
|
||||
故障转移队列中也显示每个供应商的健康状态。
|
||||
|
||||
## 故障转移日志
|
||||
|
||||
每次故障转移会记录：
|
||||
|
||||
| 信息 | 说明 |
|
||||
|------|------|
|
||||
| 时间 | 发生时间 |
|
||||
| 原供应商 | 失败的供应商 |
|
||||
| 新供应商 | 切换到的供应商 |
|
||||
| 失败原因 | 错误信息 |
|
||||
|
||||
在用量统计的请求日志中可以查看。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 队列配置建议
|
||||
|
||||
1. **主供应商**：最稳定、最快的供应商
|
||||
2. **第一备用**：次优选择
|
||||
3. **第二备用**：保底选择
|
||||
|
||||
### 熔断器配置建议
|
||||
|
||||
| 场景 | 失败阈值 | 熔断时长 |
|
||||
|------|----------|----------|
|
||||
| 高可用要求 | 2 | 30 秒 |
|
||||
| 一般场景 | 3 | 60 秒 |
|
||||
| 容忍偶发失败 | 5 | 120 秒 |
|
||||
|
||||
### 监控建议
|
||||
|
||||
定期检查：
|
||||
- 各供应商的健康状态
|
||||
- 故障转移发生频率
|
||||
- 熔断触发情况
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 故障转移没有触发
|
||||
|
||||
检查：
|
||||
1. 代理服务是否运行
|
||||
2. 应用接管是否开启
|
||||
3. 自动故障转移是否开启
|
||||
4. 队列中是否有备用供应商
|
||||
|
||||
### 频繁触发故障转移
|
||||
|
||||
可能原因：
|
||||
- 主供应商不稳定
|
||||
- 网络问题
|
||||
- 配置错误
|
||||
|
||||
解决方法：
|
||||
- 检查主供应商状态
|
||||
- 调整熔断器参数
|
||||
- 考虑更换主供应商
|
||||
|
||||
### 所有供应商都熔断
|
||||
|
||||
等待熔断时长到期后自动恢复，或：
|
||||
1. 手动重启代理服务
|
||||
2. 重置熔断状态
|
||||
@@ -1,291 +0,0 @@
|
||||
# 4.4 用量统计
|
||||
|
||||
## 功能说明
|
||||
|
||||
用量统计功能记录和分析 API 请求数据，帮助你：
|
||||
|
||||
- 了解 API 使用情况
|
||||
- 估算费用支出
|
||||
- 分析使用模式
|
||||
- 排查问题
|
||||
|
||||
## 前提条件
|
||||
|
||||
使用用量统计功能需要：
|
||||
|
||||
1. ✅ 启动代理服务
|
||||
2. ✅ 开启应用接管
|
||||
3. ✅ 开启日志记录
|
||||
|
||||
## 打开用量统计
|
||||
|
||||
设置 → 用量 Tab
|
||||
|
||||
## 统计概览
|
||||
|
||||
### 汇总卡片
|
||||
|
||||
页面顶部显示关键指标：
|
||||
|
||||
| 指标 | 说明 |
|
||||
|------|------|
|
||||
| 总请求数 | 统计周期内的请求总数 |
|
||||
| 总 Token | 输入 + 输出 Token 总数 |
|
||||
| 估算费用 | 基于定价配置计算的费用 |
|
||||
| 成功率 | 成功请求的百分比 |
|
||||
|
||||
### 时间范围
|
||||
|
||||
可选择统计的时间范围：
|
||||
|
||||
| 选项 | 范围 |
|
||||
|------|------|
|
||||
| 今日 | 当天 00:00 至今 |
|
||||
| 最近 7 天 | 过去 7 天 |
|
||||
| 最近 30 天 | 过去 30 天 |
|
||||
|
||||
|
||||
|
||||
## 趋势图表
|
||||
|
||||
### 请求趋势
|
||||
|
||||
折线图展示请求数量的变化趋势：
|
||||
|
||||
- X 轴：时间
|
||||
- Y 轴：请求数量
|
||||
- 可按小时/天查看
|
||||
- 支持缩放和拖拽
|
||||
|
||||
### Token 趋势
|
||||
|
||||
展示 Token 使用量的变化：
|
||||
|
||||
- 输入 Token（蓝色）- 用户发送的 prompt 内容
|
||||
- 输出 Token（绿色）- AI 生成的回复内容
|
||||
- 缓存创建 Token（橙色）- 首次创建缓存消耗的 Token
|
||||
- 缓存命中 Token（紫色）- 复用缓存节省的 Token
|
||||
- 成本（红色虚线，右侧 Y 轴）- 估算费用
|
||||
|
||||
> 💡 **缓存 Token 说明**：Anthropic API 支持 Prompt Caching 功能。缓存创建时收取较高费用（通常为输入价格的 1.25 倍），但后续命中缓存时只收取 0.1 倍的价格，可大幅降低重复请求的成本。
|
||||
|
||||
### 时间粒度
|
||||
|
||||
- **今日**：按小时显示（24 个数据点）
|
||||
- **7 天/30 天**：按天显示
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 详细数据
|
||||
|
||||
页面下方有三个数据 Tab：
|
||||
|
||||
### 请求日志
|
||||
|
||||
每条请求的详细记录：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 时间 | 请求时间 |
|
||||
| 供应商 | 使用的供应商名称 |
|
||||
| 模型 | 请求的模型（计费模型） |
|
||||
| 输入 Token | 输入的 Token 数 |
|
||||
| 输出 Token | 输出的 Token 数 |
|
||||
| 缓存读取 | 缓存命中的 Token 数 |
|
||||
| 缓存创建 | 缓存创建的 Token 数 |
|
||||
| 总费用 | 估算费用（美元） |
|
||||
| 耗时信息 | 请求耗时、首 Token 时间、流式/非流式 |
|
||||
| 状态 | HTTP 状态码 |
|
||||
|
||||
#### 耗时信息说明
|
||||
|
||||
耗时信息列显示多个徽章：
|
||||
|
||||
| 徽章 | 说明 | 颜色规则 |
|
||||
|------|------|----------|
|
||||
| 总耗时 | 请求总时长（秒） | ≤5s 绿色，≤120s 橙色，>120s 红色 |
|
||||
| 首 Token | 流式请求首个 Token 时间 | ≤5s 绿色，≤120s 橙色，>120s 红色 |
|
||||
| 流式/非流式 | 请求类型 | 流式蓝色，非流式紫色 |
|
||||
|
||||
#### 查看详情
|
||||
|
||||
点击请求行可查看详细信息：
|
||||
|
||||
- 完整的请求参数
|
||||
- 响应内容摘要
|
||||
- 错误信息（如果失败）
|
||||
|
||||
#### 筛选日志
|
||||
|
||||
支持按以下条件筛选：
|
||||
|
||||
| 筛选项 | 选项 |
|
||||
|--------|------|
|
||||
| 应用类型 | 全部 / Claude / Codex / Gemini / OpenCode |
|
||||
| 状态码 | 全部 / 200 / 400 / 401 / 429 / 500 |
|
||||
| 供应商 | 文本搜索 |
|
||||
| 模型 | 文本搜索 |
|
||||
| 时间范围 | 开始时间 - 结束时间（日期时间选择器） |
|
||||
|
||||
操作按钮：
|
||||
- **搜索**：应用筛选条件
|
||||
- **重置**：恢复默认（过去 24 小时）
|
||||
- **刷新**：重新加载数据
|
||||
|
||||
|
||||
|
||||
### 供应商统计
|
||||
|
||||
按供应商分组的统计数据：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 供应商 | 供应商名称 |
|
||||
| 请求数 | 该供应商的请求总数 |
|
||||
| 成功数 | 成功的请求数 |
|
||||
| 失败数 | 失败的请求数 |
|
||||
| 成功率 | 成功百分比 |
|
||||
| 总 Token | Token 使用总量 |
|
||||
| 估算费用 | 该供应商的费用 |
|
||||
|
||||
|
||||
|
||||
### 模型统计
|
||||
|
||||
按模型分组的统计数据：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 模型 | 模型名称 |
|
||||
| 请求数 | 该模型的请求总数 |
|
||||
| 输入 Token | 输入 Token 总量 |
|
||||
| 输出 Token | 输出 Token 总量 |
|
||||
| 平均延迟 | 平均响应时间 |
|
||||
| 估算费用 | 该模型的费用 |
|
||||
|
||||
|
||||
|
||||
## 定价配置
|
||||
|
||||
### 打开定价配置
|
||||
|
||||
设置 → 高级 → 定价配置
|
||||
|
||||
### 配置模型价格
|
||||
|
||||
为每个模型设置价格（每百万 Token）：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 模型 ID | 模型标识符（如 claude-3-sonnet） |
|
||||
| 显示名称 | 自定义显示名称 |
|
||||
| 输入价格 | 每百万输入 Token 的价格 |
|
||||
| 输出价格 | 每百万输出 Token 的价格 |
|
||||
| 缓存读取价格 | 每百万缓存命中 Token 的价格 |
|
||||
| 缓存创建价格 | 每百万缓存创建 Token 的价格 |
|
||||
|
||||
### 操作
|
||||
|
||||
- **添加**：点击「添加」按钮新增模型定价
|
||||
- **编辑**：点击行末的编辑图标修改
|
||||
- **删除**：点击行末的删除图标移除
|
||||
|
||||
|
||||
|
||||
### 预设价格
|
||||
|
||||
CC Switch 预设了常用模型的官方价格（每百万 Token）：
|
||||
|
||||
**Claude 系列（美元）**：
|
||||
|
||||
| 模型 | 输入 | 输出 | 缓存读取 | 缓存创建 |
|
||||
|------|------|------|----------|----------|
|
||||
| **Claude 4.5 系列** | | | | |
|
||||
| claude-opus-4-5 | $5 | $25 | $0.50 | $6.25 |
|
||||
| claude-sonnet-4-5 | $3 | $15 | $0.30 | $3.75 |
|
||||
| claude-haiku-4-5 | $1 | $5 | $0.10 | $1.25 |
|
||||
| **Claude 4 系列** | | | | |
|
||||
| claude-opus-4 | $15 | $75 | $1.50 | $18.75 |
|
||||
| claude-opus-4-1 | $15 | $75 | $1.50 | $18.75 |
|
||||
| claude-sonnet-4 | $3 | $15 | $0.30 | $3.75 |
|
||||
| **Claude 3.5 系列** | | | | |
|
||||
| claude-3-5-sonnet | $3 | $15 | $0.30 | $3.75 |
|
||||
| claude-3-5-haiku | $0.80 | $4 | $0.08 | $1.00 |
|
||||
|
||||
**OpenAI 系列 / Codex（美元）**：
|
||||
|
||||
| 模型 | 输入 | 输出 | 缓存读取 |
|
||||
|------|------|------|----------|
|
||||
| **GPT-5.2 系列** | | | |
|
||||
| gpt-5.2 | $1.75 | $14 | $0.175 |
|
||||
| **GPT-5.1 系列** | | | |
|
||||
| gpt-5.1 | $1.25 | $10 | $0.125 |
|
||||
| **GPT-5 系列** | | | |
|
||||
| gpt-5 | $1.25 | $10 | $0.125 |
|
||||
|
||||
> 注：Codex 预设包含了 low/medium/high 等变体，价格与基础模型一致。
|
||||
|
||||
**Gemini 系列（美元）**：
|
||||
|
||||
| 模型 | 输入 | 输出 | 缓存读取 |
|
||||
|------|------|------|----------|
|
||||
| **Gemini 3 系列** | | | |
|
||||
| gemini-3-pro-preview | $2 | $12 | $0.20 |
|
||||
| gemini-3-flash-preview | $0.50 | $3 | $0.05 |
|
||||
| **Gemini 2.5 系列** | | | |
|
||||
| gemini-2.5-pro | $1.25 | $10 | $0.125 |
|
||||
| gemini-2.5-flash | $0.30 | $2.50 | $0.03 |
|
||||
|
||||
**中国厂商模型（人民币）**：
|
||||
|
||||
| 模型 | 输入 | 输出 | 缓存读取 |
|
||||
|------|------|------|----------|
|
||||
| **DeepSeek** | | | |
|
||||
| deepseek-v3.2 | ¥2.00 | ¥3.00 | ¥0.40 |
|
||||
| deepseek-v3.1 | ¥4.00 | ¥12.00 | ¥0.80 |
|
||||
| deepseek-v3 | ¥2.00 | ¥8.00 | ¥0.40 |
|
||||
| **Kimi (月之暗面)** | | | |
|
||||
| kimi-k2-thinking | ¥4.00 | ¥16.00 | ¥1.00 |
|
||||
| kimi-k2 | ¥4.00 | ¥16.00 | ¥1.00 |
|
||||
| kimi-k2-turbo | ¥8.00 | ¥58.00 | ¥1.00 |
|
||||
| **MiniMax** | | | |
|
||||
| minimax-m2.1 | ¥2.10 | ¥8.40 | ¥0.21 |
|
||||
| minimax-m2.1-lightning | ¥2.10 | ¥16.80 | ¥0.21 |
|
||||
| **其他** | | | |
|
||||
| glm-4.7 | ¥2.00 | ¥8.00 | ¥0.40 |
|
||||
| doubao-seed-code | ¥1.20 | ¥8.00 | ¥0.24 |
|
||||
| mimo-v2-flash | 免费 | 免费 | - |
|
||||
|
||||
### 自定义价格
|
||||
|
||||
如果使用中转服务，价格可能不同：
|
||||
|
||||
1. 点击「编辑」按钮
|
||||
2. 修改价格
|
||||
3. 保存
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 统计数据为空
|
||||
|
||||
检查：
|
||||
- 代理服务是否运行
|
||||
- 应用接管是否开启
|
||||
- 日志记录是否开启
|
||||
- 是否有请求通过代理
|
||||
|
||||
### 费用估算不准确
|
||||
|
||||
可能原因：
|
||||
- 定价配置与实际不符
|
||||
- 使用了中转服务的特殊定价
|
||||
|
||||
解决方法：
|
||||
- 更新定价配置
|
||||
- 参考供应商的实际账单
|
||||
|
||||
### Token 数量与供应商不一致
|
||||
|
||||
CC Switch 使用自己的方式估算 Token 数，可能与供应商的计算方式略有差异。以供应商账单为准。
|
||||
@@ -1,156 +0,0 @@
|
||||
# 4.5 模型检查
|
||||
|
||||
## 功能说明
|
||||
|
||||
模型检查功能用于验证供应商配置的模型是否可用，通过发送实际的 API 请求来测试：
|
||||
|
||||
- 模型是否存在
|
||||
- API Key 是否有效
|
||||
- 端点是否正常响应
|
||||
- 响应延迟是否正常
|
||||
|
||||
## 打开配置
|
||||
|
||||
设置 → 高级 → 模型测试
|
||||
|
||||
## 测试模型配置
|
||||
|
||||
为每个应用配置用于测试的模型：
|
||||
|
||||
| 应用 | 配置项 | 默认值 | 说明 |
|
||||
|------|--------|--------|------|
|
||||
| Claude | Claude 模型 | 系统默认 | 建议使用 Haiku 系列（成本低、速度快） |
|
||||
| Codex | Codex 模型 | 系统默认 | 建议使用 mini 系列 |
|
||||
| Gemini | Gemini 模型 | 系统默认 | 建议使用 Flash 系列 |
|
||||
|
||||
### 模型选择建议
|
||||
|
||||
选择测试模型时考虑：
|
||||
|
||||
1. **成本**：选择价格较低的模型（如 Haiku、Mini、Flash）
|
||||
2. **速度**：选择响应快的模型
|
||||
3. **可用性**：选择供应商支持的模型
|
||||
|
||||
## 检查参数配置
|
||||
|
||||
### 超时时间
|
||||
|
||||
| 参数 | 说明 | 默认值 | 范围 |
|
||||
|------|------|--------|------|
|
||||
| 超时时间 | 单次请求超时 | 45 秒 | 10-120 秒 |
|
||||
|
||||
设置过短可能导致误判，设置过长会延迟故障检测。
|
||||
|
||||
### 重试次数
|
||||
|
||||
| 参数 | 说明 | 默认值 | 范围 |
|
||||
|------|------|--------|------|
|
||||
| 最大重试 | 失败后重试次数 | 2 次 | 0-5 次 |
|
||||
|
||||
网络不稳定时建议增加重试次数。
|
||||
|
||||
### 降级阈值
|
||||
|
||||
| 参数 | 说明 | 默认值 | 范围 |
|
||||
|------|------|--------|------|
|
||||
| 降级阈值 | 响应超过此时间标记为降级 | 6000ms | 1000-30000ms |
|
||||
|
||||
超过阈值的供应商会被标记为「降级」状态，但仍可使用。
|
||||
|
||||
## 执行模型检查
|
||||
|
||||
### 手动测试
|
||||
|
||||
在供应商卡片上点击「测试」按钮：
|
||||
|
||||
1. 发送测试请求到配置的端点
|
||||
2. 使用配置的测试模型
|
||||
3. 等待响应或超时
|
||||
4. 显示测试结果
|
||||
|
||||
### 测试内容
|
||||
|
||||
测试请求会：
|
||||
- 发送简短的 prompt（如 "Hi"）
|
||||
- 限制最大输出 token（通常 10-50）
|
||||
- 使用流式响应检测首字节时间
|
||||
|
||||
## 测试结果
|
||||
|
||||
### 健康状态
|
||||
|
||||
| 状态 | 图标 | 说明 |
|
||||
|------|------|------|
|
||||
| 健康 | 🟢 | 响应正常，延迟在阈值内 |
|
||||
| 降级 | 🟡 | 响应正常，但延迟超过阈值 |
|
||||
| 不可用 | 🔴 | 请求失败或超时 |
|
||||
|
||||
### 结果信息
|
||||
|
||||
测试完成后显示：
|
||||
- 响应延迟（毫秒）
|
||||
- 首字节时间（TTFB）
|
||||
- 错误信息（如果失败）
|
||||
|
||||
## 与故障转移集成
|
||||
|
||||
模型检查与故障转移功能配合使用：
|
||||
|
||||
### 健康检查
|
||||
|
||||
开启代理服务后，系统会定期对故障转移队列中的供应商执行健康检查：
|
||||
|
||||
1. 使用配置的测试模型发送请求
|
||||
2. 根据响应更新健康状态
|
||||
3. 不健康的供应商会被暂时跳过
|
||||
|
||||
### 熔断恢复
|
||||
|
||||
当供应商从熔断状态恢复时：
|
||||
|
||||
1. 执行模型检查验证可用性
|
||||
2. 检查通过后恢复正常状态
|
||||
3. 检查失败则继续熔断
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 测试失败但实际可用
|
||||
|
||||
**可能原因**：
|
||||
- 测试模型与实际使用的模型不同
|
||||
- 供应商不支持配置的测试模型
|
||||
|
||||
**解决方法**：
|
||||
- 修改测试模型为供应商支持的模型
|
||||
- 检查供应商的模型列表
|
||||
|
||||
### 延迟过高
|
||||
|
||||
**可能原因**：
|
||||
- 网络延迟
|
||||
- 供应商服务器负载高
|
||||
- 模型响应慢
|
||||
|
||||
**解决方法**：
|
||||
- 使用更快的测试模型
|
||||
- 调整降级阈值
|
||||
- 考虑使用镜像端点
|
||||
|
||||
### 频繁超时
|
||||
|
||||
**可能原因**：
|
||||
- 超时时间设置过短
|
||||
- 网络不稳定
|
||||
- 供应商服务不稳定
|
||||
|
||||
**解决方法**：
|
||||
- 增加超时时间
|
||||
- 增加重试次数
|
||||
- 检查网络连接
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 模型检查会消耗少量 API 配额
|
||||
- 建议使用低成本模型进行测试
|
||||
- 测试频率不宜过高，避免浪费配额
|
||||
- 不同供应商支持的模型可能不同
|
||||
@@ -1,278 +0,0 @@
|
||||
# 5.1 配置文件说明
|
||||
|
||||
## CC Switch 数据存储
|
||||
|
||||
### 存储目录
|
||||
|
||||
默认位置：`~/.cc-switch/`
|
||||
|
||||
可在设置中自定义位置（用于云同步）。
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
~/.cc-switch/
|
||||
├── cc-switch.db # SQLite 数据库
|
||||
├── settings.json # 设备级设置
|
||||
└── backups/ # 自动备份
|
||||
├── backup-20251230-120000.json
|
||||
├── backup-20251229-180000.json
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 数据库内容
|
||||
|
||||
`cc-switch.db` 是 SQLite 数据库，存储：
|
||||
|
||||
| 表 | 内容 |
|
||||
|-----|------|
|
||||
| providers | 供应商配置 |
|
||||
| provider_endpoints | 供应商端点候选列表 |
|
||||
| mcp_servers | MCP 服务器配置 |
|
||||
| prompts | 提示词预设 |
|
||||
| skills | 技能安装状态 |
|
||||
| skill_repos | 技能仓库配置 |
|
||||
| proxy_config | 代理配置 |
|
||||
| proxy_request_logs | 代理请求日志 |
|
||||
| provider_health | 供应商健康状态 |
|
||||
| model_pricing | 模型定价 |
|
||||
| settings | 应用设置 |
|
||||
|
||||
### 设备设置
|
||||
|
||||
`settings.json` 存储设备级设置：
|
||||
|
||||
```json
|
||||
{
|
||||
"language": "zh",
|
||||
"theme": "system",
|
||||
"windowBehavior": "minimize",
|
||||
"autoStart": false,
|
||||
"claudeConfigDir": null,
|
||||
"codexConfigDir": null,
|
||||
"geminiConfigDir": null,
|
||||
"opencodeConfigDir": null
|
||||
}
|
||||
```
|
||||
|
||||
这些设置不会跨设备同步。
|
||||
|
||||
### 自动备份
|
||||
|
||||
`backups/` 目录存储自动备份：
|
||||
|
||||
- 每次导入配置前自动创建
|
||||
- 保留最近 10 个备份
|
||||
- 文件名包含时间戳
|
||||
|
||||
## Claude Code 配置
|
||||
|
||||
### 配置目录
|
||||
|
||||
默认：`~/.claude/`
|
||||
|
||||
### 主要文件
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
├── settings.json # 主配置文件
|
||||
├── CLAUDE.md # 系统提示词
|
||||
└── skills/ # 技能目录
|
||||
└── ...
|
||||
```
|
||||
|
||||
### settings.json
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": "sk-xxx",
|
||||
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
|
||||
},
|
||||
"permissions": {
|
||||
"allow_file_access": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `env.ANTHROPIC_API_KEY` | API 密钥 |
|
||||
| `env.ANTHROPIC_BASE_URL` | API 端点（可选） |
|
||||
| `env.ANTHROPIC_AUTH_TOKEN` | 替代认证方式 |
|
||||
|
||||
### MCP 配置
|
||||
|
||||
MCP 服务器配置在 `~/.claude.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Codex 配置
|
||||
|
||||
### 配置目录
|
||||
|
||||
默认：`~/.codex/`
|
||||
|
||||
### 主要文件
|
||||
|
||||
```
|
||||
~/.codex/
|
||||
├── auth.json # 认证配置
|
||||
├── config.toml # 主配置 + MCP
|
||||
└── AGENTS.md # 系统提示词
|
||||
```
|
||||
|
||||
### auth.json
|
||||
|
||||
```json
|
||||
{
|
||||
"OPENAI_API_KEY": "sk-xxx"
|
||||
}
|
||||
```
|
||||
|
||||
### config.toml
|
||||
|
||||
```toml
|
||||
# 基础配置
|
||||
base_url = "https://api.openai.com/v1"
|
||||
model = "gpt-4"
|
||||
|
||||
# MCP 服务器
|
||||
[mcp_servers.mcp-fetch]
|
||||
command = "uvx"
|
||||
args = ["mcp-server-fetch"]
|
||||
```
|
||||
|
||||
## Gemini CLI 配置
|
||||
|
||||
### 配置目录
|
||||
|
||||
默认：`~/.gemini/`
|
||||
|
||||
### 主要文件
|
||||
|
||||
```
|
||||
~/.gemini/
|
||||
├── .env # 环境变量（API Key）
|
||||
├── settings.json # 主配置 + MCP
|
||||
└── GEMINI.md # 系统提示词
|
||||
```
|
||||
|
||||
### .env
|
||||
|
||||
```bash
|
||||
GEMINI_API_KEY=xxx
|
||||
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
GEMINI_MODEL=gemini-pro
|
||||
```
|
||||
|
||||
### settings.json
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `mcpServers` | MCP 服务器配置 |
|
||||
|
||||
## OpenCode 配置
|
||||
|
||||
### 配置目录
|
||||
|
||||
默认：`~/.opencode/`
|
||||
|
||||
### 主要文件
|
||||
|
||||
```
|
||||
~/.opencode/
|
||||
├── config.json # 主配置文件
|
||||
├── AGENTS.md # 系统提示词
|
||||
└── skills/ # 技能目录
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 配置优先级
|
||||
|
||||
CC Switch 修改配置时的优先级：
|
||||
|
||||
1. **CC Switch 数据库** - 单一事实源 (SSOT)
|
||||
2. **Live 配置文件** - 切换供应商时写入
|
||||
3. **回填机制** - 编辑当前供应商时从 Live 文件读取
|
||||
|
||||
## 手动编辑配置
|
||||
|
||||
### 可以手动编辑
|
||||
|
||||
- CLI 工具的配置文件（会被 CC Switch 回填）
|
||||
- CC Switch 的 `settings.json`
|
||||
|
||||
### 不建议手动编辑
|
||||
|
||||
- `cc-switch.db` 数据库文件
|
||||
- 备份文件
|
||||
|
||||
### 编辑后同步
|
||||
|
||||
如果手动编辑了 CLI 工具的配置：
|
||||
|
||||
1. 打开 CC Switch
|
||||
2. 编辑对应的供应商
|
||||
3. 会看到手动修改的内容已回填
|
||||
4. 保存以同步到数据库
|
||||
|
||||
## 配置迁移
|
||||
|
||||
### 从旧版本迁移
|
||||
|
||||
CC Switch v3.7.0 从 JSON 文件迁移到 SQLite：
|
||||
|
||||
- 首次启动自动迁移
|
||||
- 迁移成功后显示提示
|
||||
- 旧配置文件保留作为备份
|
||||
|
||||
### 跨设备迁移
|
||||
|
||||
1. 在源设备导出配置
|
||||
2. 在目标设备导入配置
|
||||
3. 或使用云同步功能
|
||||
|
||||
## 配置备份建议
|
||||
|
||||
### 定期备份
|
||||
|
||||
建议定期导出配置：
|
||||
|
||||
1. 设置 → 高级 → 数据管理
|
||||
2. 点击「导出」
|
||||
3. 保存到安全位置
|
||||
|
||||
### 备份内容
|
||||
|
||||
导出文件包含：
|
||||
|
||||
- 所有供应商配置
|
||||
- MCP 服务器配置
|
||||
- Prompts 预设
|
||||
- 应用设置
|
||||
|
||||
### 不包含的内容
|
||||
|
||||
- 用量日志（数据量大）
|
||||
- 设备级设置（不适合跨设备）
|
||||
@@ -1,220 +0,0 @@
|
||||
# 5.2 常见问题 FAQ
|
||||
|
||||
## 安装问题
|
||||
|
||||
### macOS 提示「未知开发者」
|
||||
|
||||
**问题**：首次打开时提示「无法打开，因为它来自身份不明的开发者」
|
||||
|
||||
**解决方法一**：通过系统设置
|
||||
1. 关闭警告弹窗
|
||||
2. 打开「系统设置」→「隐私与安全性」
|
||||
3. 找到 CC Switch 相关提示
|
||||
4. 点击「仍要打开」
|
||||
5. 再次打开应用
|
||||
|
||||
**解决方法二**：通过终端命令（推荐）
|
||||
```bash
|
||||
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
|
||||
```
|
||||
|
||||
执行后即可正常打开应用。
|
||||
|
||||
### Windows 安装后无法启动
|
||||
|
||||
**可能原因**：
|
||||
- 缺少 WebView2 运行时
|
||||
- 杀毒软件拦截
|
||||
|
||||
**解决方法**：
|
||||
1. 安装 [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
|
||||
2. 将 CC Switch 添加到杀毒软件白名单
|
||||
|
||||
### Linux 启动报错
|
||||
|
||||
**问题**：AppImage 无法启动
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 添加执行权限
|
||||
chmod +x CC-Switch-*.AppImage
|
||||
|
||||
# 如果仍然失败，尝试
|
||||
./CC-Switch-*.AppImage --no-sandbox
|
||||
```
|
||||
|
||||
## 供应商问题
|
||||
|
||||
### 切换供应商后不生效
|
||||
|
||||
**原因**：CLI 工具需要重新加载配置
|
||||
|
||||
**解决方法**：
|
||||
- Claude Code：关闭并重新打开终端，或重启 IDE
|
||||
- Codex：关闭并重新打开终端
|
||||
- Gemini：托盘切换可即时生效，无需重启
|
||||
|
||||
### API Key 无效
|
||||
|
||||
**检查步骤**：
|
||||
1. 确认 API Key 正确复制（无多余空格）
|
||||
2. 确认 API Key 未过期
|
||||
3. 确认端点地址正确
|
||||
4. 使用速度测试验证连接
|
||||
|
||||
### 如何恢复官方登录
|
||||
|
||||
**操作步骤**：
|
||||
1. 选择「官方登录」预设（Claude/Codex）或「Google 官方」预设（Gemini）
|
||||
2. 点击「启用」
|
||||
3. 重启对应的 CLI 工具
|
||||
4. 按照 CLI 工具的登录流程操作
|
||||
|
||||
## 代理问题
|
||||
|
||||
### 代理服务启动失败
|
||||
|
||||
**可能原因**：端口被占用
|
||||
|
||||
**解决方法**：
|
||||
1. 检查端口占用：
|
||||
```bash
|
||||
# macOS/Linux
|
||||
lsof -i :49152
|
||||
|
||||
# Windows
|
||||
netstat -ano | findstr :49152
|
||||
```
|
||||
2. 关闭占用端口的程序
|
||||
3. 或尝试修改配置恢复默认端口：
|
||||
- 打开「设置 → 代理服务」
|
||||
- 点击「恢复默认」按钮
|
||||
|
||||
### 代理模式下请求超时
|
||||
|
||||
**可能原因**：
|
||||
- 网络问题
|
||||
- 供应商服务器问题
|
||||
- 代理配置错误
|
||||
|
||||
**解决方法**：
|
||||
1. 检查网络连接
|
||||
2. 尝试直接访问供应商 API（关闭代理）
|
||||
3. 检查供应商配置是否正确
|
||||
|
||||
### 关闭代理后配置未恢复
|
||||
|
||||
**可能原因**：代理异常退出
|
||||
|
||||
**解决方法**：
|
||||
1. 编辑当前供应商
|
||||
2. 检查端点地址是否正确
|
||||
3. 保存以更新配置
|
||||
|
||||
## 故障转移问题
|
||||
|
||||
### 故障转移没有触发
|
||||
|
||||
**检查清单**：
|
||||
- [ ] 代理服务是否运行
|
||||
- [ ] 应用接管是否开启
|
||||
- [ ] 自动故障转移是否开启
|
||||
- [ ] 队列中是否有备用供应商
|
||||
|
||||
### 频繁触发故障转移
|
||||
|
||||
**可能原因**：
|
||||
- 主供应商不稳定
|
||||
- 熔断器阈值设置过低
|
||||
|
||||
**解决方法**：
|
||||
1. 检查主供应商状态
|
||||
2. 调高失败阈值（如从 3 改为 5）
|
||||
3. 考虑更换主供应商
|
||||
|
||||
### 所有供应商都熔断了
|
||||
|
||||
**解决方法**：
|
||||
1. 等待熔断时长到期（默认 60 秒）
|
||||
2. 或重启代理服务重置状态
|
||||
|
||||
## 数据问题
|
||||
|
||||
### 配置丢失
|
||||
|
||||
**可能原因**：
|
||||
- 配置目录被删除
|
||||
- 数据库损坏
|
||||
|
||||
**解决方法**：
|
||||
1. 检查 `~/.cc-switch/` 目录是否存在
|
||||
2. 从备份恢复：`~/.cc-switch/backups/`
|
||||
3. 或从之前导出的配置文件导入
|
||||
|
||||
### 导入配置失败
|
||||
|
||||
**可能原因**：
|
||||
- 文件格式错误
|
||||
- 版本不兼容
|
||||
|
||||
**解决方法**：
|
||||
1. 确认文件是 CC Switch 导出的 JSON 文件
|
||||
2. 检查文件内容是否完整
|
||||
3. 尝试用文本编辑器打开检查格式
|
||||
|
||||
### 用量统计数据为空
|
||||
|
||||
**检查清单**：
|
||||
- [ ] 代理服务是否运行
|
||||
- [ ] 应用接管是否开启
|
||||
- [ ] 日志记录是否开启
|
||||
- [ ] 是否有请求通过代理
|
||||
|
||||
## 其他问题
|
||||
|
||||
### 托盘图标不显示
|
||||
|
||||
**macOS**：
|
||||
- 检查系统设置中的菜单栏图标设置
|
||||
|
||||
**Windows**：
|
||||
- 检查任务栏设置，确保 CC Switch 图标未被隐藏
|
||||
|
||||
**Linux**：
|
||||
- 需要安装系统托盘支持（如 `libappindicator`）
|
||||
|
||||
### 界面显示异常
|
||||
|
||||
**解决方法**：
|
||||
1. 尝试切换主题（浅色/深色）
|
||||
2. 重启应用
|
||||
3. 删除 `~/.cc-switch/settings.json` 重置设置
|
||||
|
||||
### 更新失败
|
||||
|
||||
**解决方法**：
|
||||
1. 检查网络连接
|
||||
2. 手动下载最新版本安装
|
||||
3. 如使用 Homebrew：`brew upgrade --cask cc-switch`
|
||||
|
||||
## 获取帮助
|
||||
|
||||
### 提交 Issue
|
||||
|
||||
如果以上方法都无法解决问题：
|
||||
|
||||
1. 访问 [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
2. 搜索是否有类似问题
|
||||
3. 如果没有，创建新 Issue
|
||||
4. 提供以下信息：
|
||||
- 操作系统和版本
|
||||
- CC Switch 版本
|
||||
- 问题描述和复现步骤
|
||||
- 错误信息（如有）
|
||||
|
||||
### 日志文件
|
||||
|
||||
提交 Issue 时可附上日志文件：
|
||||
|
||||
- macOS/Linux：`~/.cc-switch/logs/`
|
||||
- Windows：`%APPDATA%\cc-switch\logs\`
|
||||
@@ -1,256 +0,0 @@
|
||||
# 5.3 深度链接协议
|
||||
|
||||
## 功能说明
|
||||
|
||||
CC Switch 支持 `ccswitch://` 深度链接协议，可以通过链接一键导入配置。
|
||||
|
||||
**使用场景**：
|
||||
- 团队共享配置
|
||||
- 教程中的一键配置
|
||||
- 跨设备快速同步
|
||||
|
||||
## 在线生成工具
|
||||
|
||||
CC Switch 提供在线深度链接生成工具：
|
||||
|
||||
**访问地址**：[https://farion1231.github.io/cc-switch/deplink.html](https://farion1231.github.io/cc-switch/deplink.html)
|
||||
|
||||
### 使用方法
|
||||
|
||||
1. 打开上述网页
|
||||
2. 选择导入类型（供应商/MCP/Prompt）
|
||||
3. 填写配置信息
|
||||
4. 点击「生成链接」
|
||||
5. 复制生成的深度链接
|
||||
6. 分享给他人或在其他设备使用
|
||||
|
||||
## 协议格式
|
||||
|
||||
### V1 协议
|
||||
|
||||
使用 URL 参数格式，易读易生成：
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource={type}&app={app}&name={name}&...
|
||||
```
|
||||
|
||||
**通用参数**：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `resource` | 是 | 资源类型：`provider` / `mcp` / `prompt` / `skill` |
|
||||
| `app` | 是 | 应用类型：`claude` / `codex` / `gemini` / `opencode` |
|
||||
| `name` | 是 | 名称 |
|
||||
|
||||
**供应商参数**（resource=provider）：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `endpoint` | 否 | API 端点地址（支持逗号分隔多个 URL） |
|
||||
| `apiKey` | 否 | API 密钥 |
|
||||
| `homepage` | 否 | 供应商官网 |
|
||||
| `model` | 否 | 默认模型 |
|
||||
| `haikuModel` | 否 | Haiku 模型（仅 Claude） |
|
||||
| `sonnetModel` | 否 | Sonnet 模型（仅 Claude） |
|
||||
| `opusModel` | 否 | Opus 模型（仅 Claude） |
|
||||
| `notes` | 否 | 备注 |
|
||||
| `icon` | 否 | 图标 |
|
||||
| `config` | 否 | Base64 编码的配置内容 |
|
||||
| `configFormat` | 否 | 配置格式：`json` / `toml` |
|
||||
| `configUrl` | 否 | 远程配置 URL |
|
||||
| `enabled` | 否 | 是否启用（布尔值） |
|
||||
| `usageScript` | 否 | 用量查询脚本 |
|
||||
| `usageEnabled` | 否 | 是否启用用量查询（默认 true） |
|
||||
| `usageApiKey` | 否 | 用量查询专用 API Key |
|
||||
| `usageBaseUrl` | 否 | 用量查询专用地址 |
|
||||
| `usageAccessToken` | 否 | 用量查询访问令牌 |
|
||||
| `usageUserId` | 否 | 用量查询用户 ID |
|
||||
| `usageAutoInterval` | 否 | 自动查询间隔（分钟） |
|
||||
|
||||
**提示词参数**（resource=prompt）：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `content` | 是 | 提示词内容 |
|
||||
| `description` | 否 | 描述 |
|
||||
| `enabled` | 否 | 是否启用（布尔值） |
|
||||
|
||||
**MCP 参数**（resource=mcp）：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `apps` | 是 | 应用列表（逗号分隔，如 `claude,codex,gemini`） |
|
||||
| `config` | 是 | MCP 服务器配置（JSON 格式） |
|
||||
| `enabled` | 否 | 是否启用（布尔值） |
|
||||
|
||||
**Skill 参数**（resource=skill）：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `repo` | 是 | 仓库（格式：`owner/name`） |
|
||||
| `directory` | 否 | 目录路径 |
|
||||
| `branch` | 否 | Git 分支 |
|
||||
|
||||
**示例**：
|
||||
```
|
||||
ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx
|
||||
```
|
||||
|
||||
## 导入类型示例
|
||||
|
||||
### 导入供应商
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx
|
||||
```
|
||||
|
||||
### 导入 MCP 服务器
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=mcp&apps=claude,codex&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D&name=mcp-fetch
|
||||
```
|
||||
|
||||
### 导入 Prompt 预设
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=prompt&app=claude&name=%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5&content=%23%20%E8%A7%92%E8%89%B2%0A%E4%BD%A0%E6%98%AF%E4%B8%80%E4%B8%AA%E4%B8%93%E4%B8%9A%E7%9A%84%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5%E4%B8%93%E5%AE%B6
|
||||
```
|
||||
|
||||
### 导入 Skill
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main
|
||||
```
|
||||
|
||||
## 生成深度链接
|
||||
|
||||
### 手动生成
|
||||
|
||||
1. 准备参数
|
||||
2. 按 V1 协议格式拼接 URL
|
||||
3. URL 编码特殊字符
|
||||
|
||||
**示例**：
|
||||
|
||||
```javascript
|
||||
const params = new URLSearchParams({
|
||||
resource: 'provider',
|
||||
app: 'claude',
|
||||
name: 'My Provider',
|
||||
endpoint: 'https://api.example.com',
|
||||
apiKey: 'sk-xxx'
|
||||
});
|
||||
|
||||
const url = `ccswitch://v1/import?${params.toString()}`;
|
||||
```
|
||||
|
||||
### 在线工具
|
||||
|
||||
使用 CC Switch 官方提供的在线深度链接生成工具更方便。
|
||||
|
||||
## 使用深度链接
|
||||
|
||||
### 点击链接
|
||||
|
||||
在浏览器或其他应用中点击深度链接：
|
||||
|
||||
1. 系统会询问是否打开 CC Switch
|
||||
2. 确认后 CC Switch 打开
|
||||
3. 显示导入确认对话框
|
||||
4. 确认导入
|
||||
|
||||
### 导入确认
|
||||
|
||||
导入前会显示确认对话框，包含：
|
||||
|
||||
- 导入类型
|
||||
- 配置预览
|
||||
- 确认/取消按钮
|
||||
|
||||
**安全提示**：只导入来自可信来源的配置。
|
||||
|
||||
## 协议注册
|
||||
|
||||
### 自动注册
|
||||
|
||||
CC Switch 安装时会自动注册 `ccswitch://` 协议。
|
||||
|
||||
### 手动注册
|
||||
|
||||
如果协议未正确注册：
|
||||
|
||||
**macOS**：
|
||||
重新安装应用，或运行：
|
||||
```bash
|
||||
/usr/bin/open -a "CC Switch" --args --register-protocol
|
||||
```
|
||||
|
||||
**Windows**：
|
||||
重新安装应用，或检查注册表：
|
||||
```
|
||||
HKEY_CLASSES_ROOT\ccswitch
|
||||
```
|
||||
|
||||
**Linux**：
|
||||
检查 `.desktop` 文件中的 `MimeType` 配置。
|
||||
|
||||
## 安全考虑
|
||||
|
||||
### 敏感信息
|
||||
|
||||
深度链接中可能包含敏感信息（如 API Key）：
|
||||
|
||||
- 不要在公开场合分享包含 API Key 的链接
|
||||
- 分享前移除或替换敏感信息
|
||||
- 使用安全渠道传输链接
|
||||
|
||||
### 验证来源
|
||||
|
||||
导入前 CC Switch 会：
|
||||
|
||||
1. 验证数据格式
|
||||
2. 显示配置预览
|
||||
3. 要求用户确认
|
||||
|
||||
### 恶意链接防护
|
||||
|
||||
CC Switch 会检查：
|
||||
|
||||
- 数据格式是否合法
|
||||
- 必填字段是否完整
|
||||
- 配置值是否在合理范围
|
||||
|
||||
## 示例链接
|
||||
|
||||
### 示例：导入 Claude 供应商
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=provider&app=claude&name=Test%20Provider&apiKey=sk-xxx&endpoint=https%3A%2F%2Fapi.example.com
|
||||
```
|
||||
|
||||
### 示例：导入 MCP 服务器
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=mcp&name=mcp-fetch&apps=claude,codex,gemini&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 链接无法打开
|
||||
|
||||
**检查**：
|
||||
1. CC Switch 是否已安装
|
||||
2. 协议是否正确注册
|
||||
3. 链接格式是否正确
|
||||
|
||||
### 导入失败
|
||||
|
||||
**可能原因**：
|
||||
- Base64 编码错误
|
||||
- JSON 格式错误
|
||||
- 缺少必填字段
|
||||
|
||||
**解决方法**：
|
||||
1. 检查原始 JSON 格式
|
||||
2. 重新进行 Base64 编码
|
||||
3. 确保所有必填字段都存在
|
||||
@@ -1,108 +0,0 @@
|
||||
# 5.4 环境变量冲突
|
||||
|
||||
## 功能说明
|
||||
|
||||
CC Switch 会自动检测系统环境变量与应用配置的冲突，避免配置被意外覆盖。
|
||||
|
||||
**检测的环境变量**：
|
||||
- `ANTHROPIC_API_KEY` - Claude API 密钥
|
||||
- `ANTHROPIC_BASE_URL` - Claude API 端点
|
||||
- `OPENAI_API_KEY` - OpenAI API 密钥
|
||||
- `GEMINI_API_KEY` - Gemini API 密钥
|
||||
- 其他相关环境变量
|
||||
|
||||
## 冲突警告
|
||||
|
||||
当检测到冲突时，界面顶部会显示黄色警告横幅：
|
||||
|
||||
```
|
||||
⚠️ 检测到环境变量冲突
|
||||
发现 X 个环境变量可能与 CC Switch 配置冲突
|
||||
[展开] [关闭]
|
||||
```
|
||||
|
||||
## 查看冲突详情
|
||||
|
||||
点击「展开」按钮查看详细信息：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 变量名 | 环境变量名称 |
|
||||
| 变量值 | 当前设置的值 |
|
||||
| 来源 | 变量的来源位置 |
|
||||
|
||||
### 来源类型
|
||||
|
||||
| 来源 | 说明 |
|
||||
|------|------|
|
||||
| 用户注册表 | Windows 用户级环境变量 |
|
||||
| 系统注册表 | Windows 系统级环境变量 |
|
||||
| Shell 配置 | macOS/Linux 的 shell 配置文件 |
|
||||
| 系统环境 | 系统级环境变量 |
|
||||
|
||||
## 处理冲突
|
||||
|
||||
### 选择要删除的变量
|
||||
|
||||
1. 勾选要删除的环境变量
|
||||
2. 或点击「全选」选择所有冲突变量
|
||||
|
||||
### 删除变量
|
||||
|
||||
1. 点击「删除选中」按钮
|
||||
2. 确认删除操作
|
||||
3. CC Switch 会自动备份并删除选中的变量
|
||||
|
||||
### 自动备份
|
||||
|
||||
删除前会自动备份：
|
||||
|
||||
- 备份位置：`~/.cc-switch/env-backups/`
|
||||
- 备份格式：JSON 文件
|
||||
- 包含变量名、值、来源等信息
|
||||
|
||||
## 忽略警告
|
||||
|
||||
如果确认冲突不影响使用，可以：
|
||||
|
||||
1. 点击警告横幅右侧的「关闭」按钮
|
||||
2. 警告会暂时隐藏
|
||||
3. 下次启动时会重新检测
|
||||
|
||||
## 手动处理
|
||||
|
||||
如果不想通过 CC Switch 删除，可以手动处理：
|
||||
|
||||
### Windows
|
||||
|
||||
1. 打开「系统属性 → 高级 → 环境变量」
|
||||
2. 在用户变量或系统变量中找到冲突变量
|
||||
3. 删除或修改变量
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
1. 编辑 shell 配置文件（如 `~/.zshrc`、`~/.bashrc`）
|
||||
2. 删除或注释掉相关的 `export` 语句
|
||||
3. 重新加载配置：`source ~/.zshrc`
|
||||
|
||||
## 为什么会冲突
|
||||
|
||||
环境变量的优先级通常高于配置文件，可能导致：
|
||||
|
||||
- CC Switch 设置的供应商配置被覆盖
|
||||
- API 请求发送到错误的端点
|
||||
- 使用错误的 API 密钥
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **使用 CC Switch 管理配置**：避免在系统环境变量中设置 API 密钥
|
||||
2. **定期检查**：关注冲突警告，及时处理
|
||||
3. **备份重要变量**：删除前确认已备份
|
||||
|
||||
## 恢复已删除的变量
|
||||
|
||||
如果误删了环境变量：
|
||||
|
||||
1. 找到备份文件：`~/.cc-switch/env-backups/`
|
||||
2. 打开对应的 JSON 文件
|
||||
3. 手动恢复变量到系统环境
|
||||
@@ -1,111 +0,0 @@
|
||||
# CC Switch 用户手册
|
||||
|
||||
> Claude Code / Codex / Gemini CLI / OpenCode 全方位辅助工具
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
📚 CC Switch 用户手册
|
||||
│
|
||||
├── 1. 快速入门
|
||||
│ ├── 1.1 软件介绍
|
||||
│ ├── 1.2 安装指南
|
||||
│ ├── 1.3 界面概览
|
||||
│ ├── 1.4 快速上手
|
||||
│ └── 1.5 个性化配置
|
||||
│
|
||||
├── 2. 供应商管理
|
||||
│ ├── 2.1 添加供应商
|
||||
│ ├── 2.2 切换供应商
|
||||
│ ├── 2.3 编辑供应商
|
||||
│ ├── 2.4 排序与复制
|
||||
│ └── 2.5 用量查询
|
||||
│
|
||||
├── 3. 扩展功能
|
||||
│ ├── 3.1 MCP 服务器管理
|
||||
│ ├── 3.2 Prompts 提示词管理
|
||||
│ └── 3.3 Skills 技能管理
|
||||
│
|
||||
├── 4. 代理与高可用
|
||||
│ ├── 4.1 代理服务
|
||||
│ ├── 4.2 应用接管
|
||||
│ ├── 4.3 故障转移
|
||||
│ ├── 4.4 用量统计
|
||||
│ └── 4.5 模型检查
|
||||
│
|
||||
└── 5. 常见问题
|
||||
├── 5.1 配置文件说明
|
||||
├── 5.2 FAQ
|
||||
├── 5.3 深度链接协议
|
||||
└── 5.4 环境变量冲突
|
||||
```
|
||||
|
||||
## 文件列表
|
||||
|
||||
### 1. 快速入门
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| [1.1-introduction.md](./1-getting-started/1.1-introduction.md) | 软件介绍、核心功能、支持平台 |
|
||||
| [1.2-installation.md](./1-getting-started/1.2-installation.md) | Windows/macOS/Linux 安装指南 |
|
||||
| [1.3-interface.md](./1-getting-started/1.3-interface.md) | 界面布局、导航栏、供应商卡片说明 |
|
||||
| [1.4-quickstart.md](./1-getting-started/1.4-quickstart.md) | 5 分钟快速上手教程 |
|
||||
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | 语言、主题、目录、云同步配置 |
|
||||
|
||||
### 2. 供应商管理
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| [2.1-add.md](./2-providers/2.1-add.md) | 使用预设、自定义配置、统一供应商 |
|
||||
| [2.2-switch.md](./2-providers/2.2-switch.md) | 主界面切换、托盘切换、生效方式 |
|
||||
| [2.3-edit.md](./2-providers/2.3-edit.md) | 编辑配置、修改 API Key、回填机制 |
|
||||
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | 拖拽排序、复制供应商、删除 |
|
||||
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | 用量查询、剩余额度、多套餐显示 |
|
||||
|
||||
### 3. 扩展功能
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP 协议、添加服务器、应用绑定 |
|
||||
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | 创建预设、激活切换、智能回填 |
|
||||
| [3.3-skills.md](./3-extensions/3.3-skills.md) | 发现技能、安装卸载、仓库管理 |
|
||||
|
||||
### 4. 代理与高可用
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| [4.1-service.md](./4-proxy/4.1-service.md) | 启动代理、配置项、运行状态 |
|
||||
| [4.2-takeover.md](./4-proxy/4.2-takeover.md) | 应用接管、配置修改、状态指示 |
|
||||
| [4.3-failover.md](./4-proxy/4.3-failover.md) | 故障转移队列、熔断器、健康状态 |
|
||||
| [4.4-usage.md](./4-proxy/4.4-usage.md) | 用量统计、趋势图表、定价配置 |
|
||||
| [4.5-model-test.md](./4-proxy/4.5-model-test.md) | 模型检查、健康检测、延迟测试 |
|
||||
|
||||
### 5. 常见问题
|
||||
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| [5.1-config-files.md](./5-faq/5.1-config-files.md) | CC Switch 存储、CLI 配置文件格式 |
|
||||
| [5.2-questions.md](./5-faq/5.2-questions.md) | 常见问题解答 |
|
||||
| [5.3-deeplink.md](./5-faq/5.3-deeplink.md) | 深度链接协议、生成和使用方法 |
|
||||
| [5.4-env-conflict.md](./5-faq/5.4-env-conflict.md) | 环境变量冲突检测与处理 |
|
||||
|
||||
## 快速链接
|
||||
|
||||
- **新用户**：从 [1.1 软件介绍](./1-getting-started/1.1-introduction.md) 开始
|
||||
- **安装问题**：查看 [1.2 安装指南](./1-getting-started/1.2-installation.md)
|
||||
- **配置供应商**：查看 [2.1 添加供应商](./2-providers/2.1-add.md)
|
||||
- **使用代理**：查看 [4.1 代理服务](./4-proxy/4.1-service.md)
|
||||
- **遇到问题**：查看 [5.2 FAQ](./5-faq/5.2-questions.md)
|
||||
|
||||
## 版本信息
|
||||
|
||||
- 文档版本：v3.10.3
|
||||
- 最后更新：2026-02-09
|
||||
- 适用于 CC Switch v3.10.0+
|
||||
|
||||
## 贡献
|
||||
|
||||
欢迎提交 Issue 或 PR 改进文档：
|
||||
|
||||
- [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- [GitHub Repository](https://github.com/farion1231/cc-switch)
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 395 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 237 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 190 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 286 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 425 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 148 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 135 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 164 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 152 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 160 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 176 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 611 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 166 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 415 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 290 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 140 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 192 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 159 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 157 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 218 KiB |
@@ -1,863 +0,0 @@
|
||||
# v3.7.0 统一 MCP 管理重构计划
|
||||
|
||||
## 📋 项目概述
|
||||
|
||||
**目标**：将原有的按应用分离的 MCP 管理（Claude/Codex/Gemini 各自独立管理）重构为统一管理面板，每个 MCP 服务器通过多选框控制应用到哪些客户端。
|
||||
|
||||
**版本**：v3.6.2 → v3.7.0
|
||||
|
||||
**开始时间**：2025-11-14
|
||||
|
||||
---
|
||||
|
||||
## 🎯 核心需求
|
||||
|
||||
### 原有架构（v3.6.x）
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Claude面板 │ │ Codex面板 │ │ Gemini面板 │
|
||||
│ MCP管理 │ │ MCP管理 │ │ MCP管理 │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
↓ ↓ ↓
|
||||
mcp.claude mcp.codex mcp.gemini
|
||||
{servers} {servers} {servers}
|
||||
```
|
||||
|
||||
### 新架构（v3.7.0）
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────┐
|
||||
│ 统一 MCP 管理面板 │
|
||||
│ ┌────────┬────────┬────────┬────┐ │
|
||||
│ │ 服务器 │ Claude │ Codex │Gem │ │
|
||||
│ ├────────┼────────┼────────┼────┤ │
|
||||
│ │ mcp-1 │ ✓ │ ✓ │ │ │
|
||||
│ │ mcp-2 │ ✓ │ │ ✓ │ │
|
||||
│ └────────┴────────┴────────┴────┘ │
|
||||
└───────────────────────────────────────┘
|
||||
↓
|
||||
mcp.servers
|
||||
{
|
||||
"mcp-1": {
|
||||
apps: {claude: true, codex: true, gemini: false}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📐 技术架构
|
||||
|
||||
### 数据结构设计
|
||||
|
||||
#### 新增：McpApps（应用启用状态）
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
|
||||
pub struct McpApps {
|
||||
pub claude: bool,
|
||||
pub codex: bool,
|
||||
pub gemini: bool,
|
||||
}
|
||||
```
|
||||
|
||||
#### 更新：McpServer（统一服务器定义）
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct McpServer {
|
||||
pub id: String,
|
||||
pub name: String,
|
||||
pub server: serde_json::Value, // 连接配置（stdio/http）
|
||||
pub apps: McpApps, // 新增：标记应用到哪些客户端
|
||||
pub description: Option<String>,
|
||||
pub homepage: Option<String>,
|
||||
pub docs: Option<String>,
|
||||
pub tags: Vec<String>,
|
||||
}
|
||||
```
|
||||
|
||||
#### 更新：McpRoot（新旧结构并存）
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
|
||||
pub struct McpRoot {
|
||||
// v3.7.0 新结构
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub servers: Option<HashMap<String, McpServer>>,
|
||||
|
||||
// v3.6.x 旧结构（保留用于迁移）
|
||||
#[serde(default, skip_serializing_if = "McpConfig::is_empty")]
|
||||
pub claude: McpConfig,
|
||||
#[serde(default, skip_serializing_if = "McpConfig::is_empty")]
|
||||
pub codex: McpConfig,
|
||||
#[serde(default, skip_serializing_if = "McpConfig::is_empty")]
|
||||
pub gemini: McpConfig,
|
||||
}
|
||||
```
|
||||
|
||||
### 迁移策略
|
||||
|
||||
```
|
||||
旧配置 (v3.6.x) 新配置 (v3.7.0)
|
||||
───────────────── ─────────────────
|
||||
mcp: mcp:
|
||||
claude: servers:
|
||||
servers: mcp-fetch:
|
||||
mcp-fetch: {...} → id: "mcp-fetch"
|
||||
codex: server: {...}
|
||||
servers: apps:
|
||||
mcp-filesystem: {...} claude: true
|
||||
codex: true
|
||||
gemini: false
|
||||
```
|
||||
|
||||
**迁移逻辑**：
|
||||
1. 检测 `mcp.servers` 是否存在
|
||||
2. 若不存在，从 `mcp.claude/codex/gemini.servers` 收集所有服务器
|
||||
3. 合并同 id 服务器的 apps 字段
|
||||
4. 清空旧结构字段
|
||||
5. 保存配置（自动触发）
|
||||
|
||||
---
|
||||
|
||||
## ✅ 开发进度
|
||||
|
||||
### Phase 1: 后端数据结构与迁移 ✅ 已完成
|
||||
|
||||
#### 1.1 修改数据结构（app_config.rs）✅
|
||||
|
||||
**文件**：`src-tauri/src/app_config.rs`
|
||||
|
||||
**变更**：
|
||||
- ✅ 新增 `McpApps` 结构体（lines 30-62）
|
||||
- ✅ 新增 `McpServer` 结构体（lines 64-79）
|
||||
- ✅ 更新 `McpRoot` 支持新旧结构（lines 81-96）
|
||||
- ✅ 添加辅助方法：`is_enabled_for`, `set_enabled_for`, `enabled_apps`
|
||||
|
||||
**提交**：`c7b235b` - "feat(mcp): implement unified MCP management for v3.7.0"
|
||||
|
||||
#### 1.2 实现迁移逻辑 ✅
|
||||
|
||||
**文件**：`src-tauri/src/app_config.rs`
|
||||
|
||||
**实现**：
|
||||
- ✅ `migrate_mcp_to_unified()` 方法（lines 380-509）
|
||||
- 从旧结构收集所有服务器
|
||||
- 按 id 合并重复服务器
|
||||
- 处理冲突（合并 apps 字段）
|
||||
- 清空旧结构
|
||||
- ✅ 集成到 `MultiAppConfig::load()` 方法（lines 252-257）
|
||||
- 自动检测并执行迁移
|
||||
- 迁移后保存配置
|
||||
|
||||
**提交**：`c7b235b` - "feat(mcp): implement unified MCP management for v3.7.0"
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: 后端服务层重构 ✅ 已完成
|
||||
|
||||
#### 2.1 重写 McpService ✅
|
||||
|
||||
**文件**：`src-tauri/src/services/mcp.rs`
|
||||
|
||||
**新增方法**：
|
||||
- ✅ `get_all_servers()` - 获取所有服务器（lines 13-27）
|
||||
- ✅ `upsert_server()` - 添加/更新服务器（lines 30-52）
|
||||
- ✅ `delete_server()` - 删除服务器（lines 55-75）
|
||||
- ✅ `toggle_app()` - 切换应用启用状态（lines 78-111）
|
||||
- ✅ `sync_all_enabled()` - 同步所有启用的服务器（lines 180-188）
|
||||
|
||||
**兼容层方法**（已废弃）：
|
||||
- ✅ `get_servers()` - 按应用过滤服务器（lines 196-210）
|
||||
- ✅ `set_enabled()` - 委托到 toggle_app（lines 213-222）
|
||||
- ✅ `sync_enabled()` - 同步特定应用（lines 225-236）
|
||||
- ✅ `import_from_claude/codex/gemini()` - 导入包装（lines 239-266）
|
||||
|
||||
**提交**：`c7b235b` - "feat(mcp): implement unified MCP management for v3.7.0"
|
||||
|
||||
#### 2.2 新增同步函数（mcp.rs）✅
|
||||
|
||||
**文件**：`src-tauri/src/mcp.rs`
|
||||
|
||||
**新增函数**（lines 800-965）：
|
||||
- ✅ `json_server_to_toml_table()` - JSON → TOML 转换助手（lines 828-889）
|
||||
- ✅ `sync_single_server_to_claude()` - 同步单个服务器到 Claude（lines 800-814）
|
||||
- ✅ `remove_server_from_claude()` - 从 Claude 移除服务器（lines 817-826）
|
||||
- ✅ `sync_single_server_to_codex()` - 同步单个服务器到 Codex（lines 891-936）
|
||||
- ✅ `remove_server_from_codex()` - 从 Codex 移除服务器（lines 939-965）
|
||||
- ✅ `sync_single_server_to_gemini()` - 同步单个服务器到 Gemini（lines 967-977）
|
||||
- ✅ `remove_server_from_gemini()` - 从 Gemini 移除服务器（lines 980-989）
|
||||
|
||||
**关键修复**：
|
||||
- ✅ 修复 toml_edit 类型转换（使用手动构建而非 serde 转换）
|
||||
- ✅ 修复 get_codex_config_path() 调用（返回 PathBuf 而非 Result）
|
||||
|
||||
**提交**：`c7b235b` - "feat(mcp): implement unified MCP management for v3.7.0"
|
||||
**修复提交**：`7ae2a9f` - "fix(mcp): resolve compilation errors and add backward compatibility"
|
||||
|
||||
#### 2.3 新增 Tauri Commands ✅
|
||||
|
||||
**文件**：`src-tauri/src/commands/mcp.rs`
|
||||
|
||||
**新增命令**（lines 147-196）：
|
||||
- ✅ `get_mcp_servers()` - 获取所有服务器（lines 154-159）
|
||||
- ✅ `upsert_mcp_server()` - 添加/更新服务器（lines 162-168）
|
||||
- ✅ `delete_mcp_server()` - 删除服务器（lines 171-177）
|
||||
- ✅ `toggle_mcp_app()` - 切换应用状态（lines 180-189）
|
||||
- ✅ `sync_all_mcp_servers()` - 同步所有服务器（lines 192-195）
|
||||
|
||||
**更新旧命令**（兼容层）：
|
||||
- ✅ `upsert_mcp_server_in_config()` - 转换为统一结构（lines 68-131）
|
||||
- ✅ `delete_mcp_server_in_config()` - 忽略 app 参数（lines 134-141）
|
||||
|
||||
**提交**：`c7b235b` - "feat(mcp): implement unified MCP management for v3.7.0"
|
||||
**修复提交**：`7ae2a9f` - "fix(mcp): resolve compilation errors and add backward compatibility"
|
||||
|
||||
#### 2.4 注册新命令（lib.rs）✅
|
||||
|
||||
**文件**：`src-tauri/src/lib.rs`
|
||||
|
||||
**变更**：
|
||||
- ✅ 导出 `McpServer` 类型（line 21）
|
||||
- ✅ 导出新增的 mcp 同步函数（lines 26-31）
|
||||
- ✅ 注册 5 个新命令到 invoke_handler（lines 550-555）
|
||||
|
||||
**提交**：`c7b235b` - "feat(mcp): implement unified MCP management for v3.7.0"
|
||||
|
||||
#### 2.5 添加缺失的函数（claude_mcp.rs & gemini_mcp.rs）✅
|
||||
|
||||
**文件**：
|
||||
- `src-tauri/src/claude_mcp.rs` (lines 234-253)
|
||||
- `src-tauri/src/gemini_mcp.rs` (lines 160-179)
|
||||
|
||||
**新增**：
|
||||
- ✅ `read_mcp_servers_map()` - 读取现有 MCP 服务器映射
|
||||
|
||||
**提交**：`7ae2a9f` - "fix(mcp): resolve compilation errors and add backward compatibility"
|
||||
|
||||
#### 2.6 编译验证 ✅
|
||||
|
||||
**状态**：✅ 编译成功
|
||||
- ⚠️ 16 个警告（8 个废弃警告 + 8 个未使用函数警告 - 预期内）
|
||||
- ✅ 0 个错误
|
||||
|
||||
**提交**：`7ae2a9f` - "fix(mcp): resolve compilation errors and add backward compatibility"
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: 前端开发 ⚠️ 部分完成
|
||||
|
||||
#### 3.1 TypeScript 类型定义 ✅
|
||||
|
||||
**文件**：`src/types.ts`
|
||||
|
||||
**变更**：
|
||||
- ✅ 新增 `McpApps` 接口（lines 129-133）
|
||||
- ✅ 更新 `McpServer` 接口（lines 136-149）
|
||||
- 新增 `apps: McpApps` 字段
|
||||
- `name` 改为必填
|
||||
- 标记 `enabled` 为废弃
|
||||
- ✅ 新增 `McpServersMap` 类型别名（line 152）
|
||||
- ✅ 保持向后兼容（保留 `enabled`, `source` 等旧字段）
|
||||
|
||||
**提交**：`ac09551` - "feat(frontend): add unified MCP types and API layer for v3.7.0"
|
||||
|
||||
#### 3.2 API 层更新 ✅
|
||||
|
||||
**文件**：`src/lib/api/mcp.ts`
|
||||
|
||||
**新增方法**（lines 99-141）：
|
||||
- ✅ `getAllServers()` - 获取所有服务器（lines 106-108）
|
||||
- ✅ `upsertUnifiedServer()` - 添加/更新服务器（lines 113-115）
|
||||
- ✅ `deleteUnifiedServer()` - 删除服务器（lines 120-122）
|
||||
- ✅ `toggleApp()` - 切换应用状态（lines 127-133）
|
||||
- ✅ `syncAllServers()` - 同步所有服务器（lines 138-140）
|
||||
|
||||
**导入更新**：
|
||||
- ✅ 导入 `McpServersMap` 类型（line 6）
|
||||
|
||||
**提交**：`ac09551` - "feat(frontend): add unified MCP types and API layer for v3.7.0"
|
||||
|
||||
#### 3.3 React Query Hooks 📝 待开发
|
||||
|
||||
**计划文件**：`src/hooks/useMcp.ts`
|
||||
|
||||
**需要实现的 Hooks**：
|
||||
|
||||
```typescript
|
||||
// 查询 hooks
|
||||
export function useAllMcpServers() {
|
||||
return useQuery({
|
||||
queryKey: ['mcp', 'all'],
|
||||
queryFn: () => mcpApi.getAllServers(),
|
||||
});
|
||||
}
|
||||
|
||||
// 变更 hooks
|
||||
export function useUpsertMcpServer() {
|
||||
const queryClient = useQueryClient();
|
||||
return useMutation({
|
||||
mutationFn: (server: McpServer) => mcpApi.upsertUnifiedServer(server),
|
||||
onSuccess: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ['mcp', 'all'] });
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
export function useToggleMcpApp() {
|
||||
const queryClient = useQueryClient();
|
||||
return useMutation({
|
||||
mutationFn: ({ serverId, app, enabled }: {
|
||||
serverId: string;
|
||||
app: AppId;
|
||||
enabled: boolean;
|
||||
}) => mcpApi.toggleApp(serverId, app, enabled),
|
||||
onSuccess: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ['mcp', 'all'] });
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
export function useDeleteMcpServer() {
|
||||
const queryClient = useQueryClient();
|
||||
return useMutation({
|
||||
mutationFn: (id: string) => mcpApi.deleteUnifiedServer(id),
|
||||
onSuccess: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ['mcp', 'all'] });
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
export function useSyncAllMcpServers() {
|
||||
return useMutation({
|
||||
mutationFn: () => mcpApi.syncAllServers(),
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
**依赖**：
|
||||
- `@tanstack/react-query` (已安装)
|
||||
- `src/lib/api/mcp.ts` (✅ 已完成)
|
||||
- `src/types.ts` (✅ 已完成)
|
||||
|
||||
#### 3.4 统一 MCP 面板组件 📝 待开发
|
||||
|
||||
**计划文件**：`src/components/mcp/UnifiedMcpPanel.tsx`
|
||||
|
||||
**组件结构**：
|
||||
|
||||
```typescript
|
||||
interface UnifiedMcpPanelProps {
|
||||
className?: string;
|
||||
}
|
||||
|
||||
export function UnifiedMcpPanel({ className }: UnifiedMcpPanelProps) {
|
||||
const { t } = useTranslation();
|
||||
const { data: servers, isLoading } = useAllMcpServers();
|
||||
const toggleApp = useToggleMcpApp();
|
||||
const deleteServer = useDeleteMcpServer();
|
||||
const syncAll = useSyncAllMcpServers();
|
||||
|
||||
// 组件实现...
|
||||
}
|
||||
```
|
||||
|
||||
**UI 设计**：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ MCP 服务器管理 ┌──────────┐ │
|
||||
│ │ 添加服务器 │ │
|
||||
│ ┌─────┐ ┌──────────────┐ ┌─────────┐ └──────────┘ │
|
||||
│ │ 搜索 │ │ 导入自...▼ │ │ 同步全部 │ │
|
||||
│ └─────┘ └──────────────┘ └─────────┘ │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────┐ │
|
||||
│ │ 名称 │ Claude │ Codex │ Gemini │操作│ │
|
||||
│ ├─────────────────────────────────────────────┤ │
|
||||
│ │ mcp-fetch │ ✓ │ ✓ │ │ ⚙️ │ │
|
||||
│ │ filesystem │ ✓ │ │ ✓ │ ⚙️ │ │
|
||||
│ │ brave-search │ │ ✓ │ ✓ │ ⚙️ │ │
|
||||
│ └─────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**功能特性**：
|
||||
- 📋 服务器列表展示（名称、描述、标签）
|
||||
- ☑️ 三个复选框控制应用启用状态（Claude/Codex/Gemini）
|
||||
- ➕ 添加新服务器（表单模态框）
|
||||
- ✏️ 编辑服务器（表单模态框）
|
||||
- 🗑️ 删除服务器（确认对话框）
|
||||
- 📥 导入功能（从 Claude/Codex/Gemini 导入）
|
||||
- 🔄 同步全部（手动触发同步到 live 配置）
|
||||
- 🔍 搜索过滤
|
||||
- 🏷️ 标签过滤
|
||||
|
||||
**子组件**：
|
||||
|
||||
1. **McpServerTable** (`McpServerTable.tsx`)
|
||||
- 服务器列表表格
|
||||
- 应用复选框
|
||||
- 操作按钮（编辑、删除）
|
||||
|
||||
2. **McpServerFormModal** (`McpServerFormModal.tsx`)
|
||||
- 添加/编辑表单
|
||||
- stdio/http 类型切换
|
||||
- 应用选择（多选）
|
||||
- 元信息编辑（描述、标签、链接）
|
||||
|
||||
3. **McpImportDialog** (`McpImportDialog.tsx`)
|
||||
- 选择导入来源（Claude/Codex/Gemini）
|
||||
- 服务器预览
|
||||
- 批量导入
|
||||
|
||||
**依赖组件**（来自 shadcn/ui）：
|
||||
- `Table`, `TableBody`, `TableCell`, `TableHead`, `TableHeader`, `TableRow`
|
||||
- `Checkbox`
|
||||
- `Button`
|
||||
- `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`
|
||||
- `Input`, `Textarea`, `Label`
|
||||
- `Select`, `SelectContent`, `SelectItem`, `SelectTrigger`, `SelectValue`
|
||||
- `Badge`
|
||||
- `Tooltip`
|
||||
|
||||
#### 3.5 主界面集成 📝 待开发
|
||||
|
||||
**文件**：`src/App.tsx`
|
||||
|
||||
**变更计划**：
|
||||
|
||||
```typescript
|
||||
// 原有代码（v3.6.x）
|
||||
{currentApp === 'claude' && <ClaudeMcpPanel />}
|
||||
{currentApp === 'codex' && <CodexMcpPanel />}
|
||||
{currentApp === 'gemini' && <GeminiMcpPanel />}
|
||||
|
||||
// 新代码（v3.7.0）
|
||||
<UnifiedMcpPanel />
|
||||
```
|
||||
|
||||
**移除的组件**：
|
||||
- `ClaudeMcpPanel.tsx`
|
||||
- `CodexMcpPanel.tsx`
|
||||
- `GeminiMcpPanel.tsx`
|
||||
|
||||
**注意**：保留旧组件文件备份，以便回滚
|
||||
|
||||
#### 3.6 国际化文本更新 📝 待开发
|
||||
|
||||
**文件**：
|
||||
- `src/locales/zh/translation.json`
|
||||
- `src/locales/en/translation.json`
|
||||
|
||||
**需要添加的翻译键**：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"unifiedPanel": {
|
||||
"title": "MCP 服务器管理 / MCP Server Management",
|
||||
"addServer": "添加服务器 / Add Server",
|
||||
"editServer": "编辑服务器 / Edit Server",
|
||||
"deleteServer": "删除服务器 / Delete Server",
|
||||
"deleteConfirm": "确定要删除此服务器吗？/ Are you sure to delete this server?",
|
||||
"syncAll": "同步全部 / Sync All",
|
||||
"syncAllSuccess": "已同步所有启用的服务器 / All enabled servers synced",
|
||||
"importFrom": "导入自... / Import from...",
|
||||
"search": "搜索服务器... / Search servers...",
|
||||
"noServers": "暂无服务器 / No servers yet",
|
||||
"enabledApps": "启用的应用 / Enabled Apps",
|
||||
"apps": {
|
||||
"claude": "Claude",
|
||||
"codex": "Codex",
|
||||
"gemini": "Gemini"
|
||||
},
|
||||
"form": {
|
||||
"id": "服务器 ID / Server ID",
|
||||
"name": "显示名称 / Display Name",
|
||||
"type": "类型 / Type",
|
||||
"stdio": "本地进程 / Local Process",
|
||||
"http": "远程服务 / Remote Service",
|
||||
"command": "命令 / Command",
|
||||
"args": "参数 / Arguments",
|
||||
"env": "环境变量 / Environment Variables",
|
||||
"cwd": "工作目录 / Working Directory",
|
||||
"url": "URL",
|
||||
"headers": "请求头 / Headers",
|
||||
"description": "描述 / Description",
|
||||
"tags": "标签 / Tags",
|
||||
"homepage": "主页 / Homepage",
|
||||
"docs": "文档 / Documentation",
|
||||
"selectApps": "选择应用 / Select Apps",
|
||||
"selectAppsHint": "勾选此服务器要应用到哪些客户端 / Check which clients this server applies to"
|
||||
},
|
||||
"table": {
|
||||
"name": "名称 / Name",
|
||||
"type": "类型 / Type",
|
||||
"apps": "应用 / Apps",
|
||||
"actions": "操作 / Actions",
|
||||
"edit": "编辑 / Edit",
|
||||
"delete": "删除 / Delete"
|
||||
},
|
||||
"import": {
|
||||
"title": "导入 MCP 服务器 / Import MCP Servers",
|
||||
"fromClaude": "从 Claude 导入 / Import from Claude",
|
||||
"fromCodex": "从 Codex 导入 / Import from Codex",
|
||||
"fromGemini": "从 Gemini 导入 / Import from Gemini",
|
||||
"success": "成功导入 {{count}} 个服务器 / Successfully imported {{count}} server(s)",
|
||||
"noServersFound": "未找到可导入的服务器 / No servers found to import"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 迁移流程
|
||||
|
||||
### 用户体验
|
||||
|
||||
```
|
||||
1. 用户升级到 v3.7.0
|
||||
↓
|
||||
2. 首次启动应用
|
||||
↓
|
||||
3. 后端自动执行迁移
|
||||
- 检测旧结构 (mcp.claude/codex/gemini.servers)
|
||||
- 合并到统一结构 (mcp.servers)
|
||||
- 保存迁移后的配置
|
||||
- 日志记录迁移详情
|
||||
↓
|
||||
4. 前端加载新面板
|
||||
- 显示所有服务器
|
||||
- 三个复选框显示各应用启用状态
|
||||
↓
|
||||
5. 用户无缝使用
|
||||
```
|
||||
|
||||
### 数据完整性保证
|
||||
|
||||
1. **迁移前验证**：
|
||||
- ✅ 校验旧结构合法性
|
||||
- ✅ 记录迁移前状态
|
||||
|
||||
2. **迁移中处理**：
|
||||
- ✅ 合并同 id 服务器的 apps 字段
|
||||
- ✅ 处理 id 冲突（保留第一个，记录警告）
|
||||
- ✅ 保留所有元信息（描述、标签、链接）
|
||||
|
||||
3. **迁移后清理**：
|
||||
- ✅ 清空旧结构（claude/codex/gemini）
|
||||
- ✅ 自动保存新配置
|
||||
- ✅ 日志记录迁移完成
|
||||
|
||||
4. **回滚机制**：
|
||||
- 配置文件有备份（`config.v1.backup.<timestamp>.json`）
|
||||
- 迁移失败时可手动回滚
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试计划
|
||||
|
||||
### 后端测试 ✅ 已验证
|
||||
|
||||
- [x] 编译测试（cargo check）
|
||||
- [x] 数据结构序列化/反序列化
|
||||
- [ ] 迁移逻辑单元测试
|
||||
- [ ] 服务层方法测试
|
||||
- [ ] 同步函数测试
|
||||
|
||||
### 前端测试 ⏳ 待进行
|
||||
|
||||
- [ ] TypeScript 类型检查
|
||||
- [ ] API 调用测试
|
||||
- [ ] 组件渲染测试
|
||||
- [ ] 用户交互测试
|
||||
- [ ] 国际化文本检查
|
||||
|
||||
### 集成测试 ⏳ 待进行
|
||||
|
||||
- [ ] 完整迁移流程测试
|
||||
- [ ] 从空配置启动
|
||||
- [ ] 从 v3.6.x 配置升级
|
||||
- [ ] 多服务器合并场景
|
||||
- [ ] 冲突处理验证
|
||||
- [ ] 多应用同步测试
|
||||
- [ ] 启用单个应用
|
||||
- [ ] 启用多个应用
|
||||
- [ ] 动态切换应用
|
||||
- [ ] 同步到 live 配置验证
|
||||
- [ ] 边界情况测试
|
||||
- [ ] 空服务器列表
|
||||
- [ ] 超长服务器名称
|
||||
- [ ] 特殊字符处理
|
||||
- [ ] 并发操作
|
||||
|
||||
---
|
||||
|
||||
## 📦 交付清单
|
||||
|
||||
### 代码文件
|
||||
|
||||
#### 后端（Rust）✅ 已完成
|
||||
|
||||
- [x] `src-tauri/src/app_config.rs` - 数据结构定义与迁移
|
||||
- [x] `src-tauri/src/services/mcp.rs` - 服务层重构
|
||||
- [x] `src-tauri/src/mcp.rs` - 同步函数实现
|
||||
- [x] `src-tauri/src/commands/mcp.rs` - Tauri 命令
|
||||
- [x] `src-tauri/src/lib.rs` - 命令注册
|
||||
- [x] `src-tauri/src/claude_mcp.rs` - Claude MCP 操作
|
||||
- [x] `src-tauri/src/gemini_mcp.rs` - Gemini MCP 操作
|
||||
|
||||
#### 前端（TypeScript/React）⚠️ 部分完成
|
||||
|
||||
- [x] `src/types.ts` - 类型定义更新
|
||||
- [x] `src/lib/api/mcp.ts` - API 层更新
|
||||
- [ ] `src/hooks/useMcp.ts` - React Query Hooks
|
||||
- [ ] `src/components/mcp/UnifiedMcpPanel.tsx` - 统一面板组件
|
||||
- [ ] `src/components/mcp/McpServerTable.tsx` - 服务器表格
|
||||
- [ ] `src/components/mcp/McpServerFormModal.tsx` - 表单模态框
|
||||
- [ ] `src/components/mcp/McpImportDialog.tsx` - 导入对话框
|
||||
- [ ] `src/App.tsx` - 主界面集成
|
||||
- [ ] `src/locales/zh/translation.json` - 中文翻译
|
||||
- [ ] `src/locales/en/translation.json` - 英文翻译
|
||||
|
||||
### 文档
|
||||
|
||||
- [x] 本重构计划文档 (`docs/v3.7.0-unified-mcp-refactor.md`)
|
||||
- [ ] 用户升级指南 (`docs/upgrade-to-v3.7.0.md`)
|
||||
- [ ] API 变更说明 (`docs/api-changes-v3.7.0.md`)
|
||||
|
||||
### Git 提交记录 ✅
|
||||
|
||||
- [x] `c7b235b` - feat(mcp): implement unified MCP management for v3.7.0
|
||||
- [x] `7ae2a9f` - fix(mcp): resolve compilation errors and add backward compatibility
|
||||
- [x] `ac09551` - feat(frontend): add unified MCP types and API layer for v3.7.0
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步行动
|
||||
|
||||
### 立即任务（优先级 P0）
|
||||
|
||||
1. ⬜ **实现 useMcp Hook**
|
||||
- 文件：`src/hooks/useMcp.ts`
|
||||
- 估时：1-2 小时
|
||||
- 依赖：API 层（已完成）
|
||||
|
||||
2. ⬜ **创建 UnifiedMcpPanel 核心组件**
|
||||
- 文件：`src/components/mcp/UnifiedMcpPanel.tsx`
|
||||
- 估时：3-4 小时
|
||||
- 依赖：useMcp Hook
|
||||
|
||||
3. ⬜ **添加国际化文本**
|
||||
- 文件：`src/locales/{zh,en}/translation.json`
|
||||
- 估时：30 分钟
|
||||
|
||||
4. ⬜ **集成到主界面**
|
||||
- 文件：`src/App.tsx`
|
||||
- 估时：30 分钟
|
||||
- 依赖：UnifiedMcpPanel 组件
|
||||
|
||||
### 次要任务（优先级 P1）
|
||||
|
||||
5. ⬜ **实现子组件**
|
||||
- McpServerTable
|
||||
- McpServerFormModal
|
||||
- McpImportDialog
|
||||
- 估时：4-6 小时
|
||||
|
||||
6. ⬜ **编写测试用例**
|
||||
- 后端单元测试
|
||||
- 前端组件测试
|
||||
- 集成测试
|
||||
- 估时：6-8 小时
|
||||
|
||||
7. ⬜ **编写用户文档**
|
||||
- 升级指南
|
||||
- API 变更说明
|
||||
- 估时：2-3 小时
|
||||
|
||||
### 优化任务（优先级 P2）
|
||||
|
||||
8. ⬜ **性能优化**
|
||||
- 服务器列表虚拟滚动
|
||||
- 批量操作优化
|
||||
- 估时：2-3 小时
|
||||
|
||||
9. ⬜ **用户体验增强**
|
||||
- 添加加载状态
|
||||
- 添加错误提示
|
||||
- 添加操作确认
|
||||
- 估时：2-3 小时
|
||||
|
||||
10. ⬜ **代码清理**
|
||||
- 移除旧的分应用面板组件
|
||||
- 清理废弃代码
|
||||
- 代码格式化
|
||||
- 估时：1-2 小时
|
||||
|
||||
---
|
||||
|
||||
## 💡 技术亮点
|
||||
|
||||
### 1. 平滑迁移机制
|
||||
|
||||
- ✅ 自动检测旧配置并迁移
|
||||
- ✅ 新旧结构并存（过渡期）
|
||||
- ✅ 无需用户手动操作
|
||||
- ✅ 保留所有历史数据
|
||||
|
||||
### 2. 向后兼容
|
||||
|
||||
- ✅ 旧命令继续可用（带废弃警告）
|
||||
- ✅ 前端可增量更新
|
||||
- ✅ 渐进式重构策略
|
||||
|
||||
### 3. 类型安全
|
||||
|
||||
- ✅ Rust 强类型保证数据完整性
|
||||
- ✅ TypeScript 类型定义与后端一致
|
||||
- ✅ serde 序列化/反序列化自动处理
|
||||
|
||||
### 4. 清晰的架构分层
|
||||
|
||||
```
|
||||
Frontend (React)
|
||||
↓ (Tauri IPC)
|
||||
Commands Layer
|
||||
↓
|
||||
Services Layer
|
||||
↓
|
||||
Data Layer (Config + Live Sync)
|
||||
```
|
||||
|
||||
### 5. SSOT 原则
|
||||
|
||||
- 单一配置源：`~/.cc-switch/config.json`
|
||||
- 统一管理：`mcp.servers` 字段
|
||||
- 按需同步：写入各应用 live 配置
|
||||
|
||||
---
|
||||
|
||||
## 📚 参考资源
|
||||
|
||||
### 内部文档
|
||||
|
||||
- [项目 README](../README.md)
|
||||
- [CLAUDE.md](../CLAUDE.md) - Claude Code 工作指南
|
||||
- [架构文档](../CLAUDE.md#架构概述)
|
||||
|
||||
### 相关 Issues/PRs
|
||||
|
||||
- 无（新功能开发）
|
||||
|
||||
### 技术栈文档
|
||||
|
||||
- [Tauri 2.0](https://tauri.app/v1/guides/)
|
||||
- [React 18](https://react.dev/)
|
||||
- [TanStack Query](https://tanstack.com/query/latest)
|
||||
- [shadcn/ui](https://ui.shadcn.com/)
|
||||
- [serde](https://serde.rs/)
|
||||
|
||||
---
|
||||
|
||||
## 📝 变更日志
|
||||
|
||||
### 2025-11-14
|
||||
|
||||
- ✅ 完成后端 Phase 1 & 2（数据结构、服务层、命令层）
|
||||
- ✅ 修复所有编译错误
|
||||
- ✅ 完成前端类型定义和 API 层
|
||||
- ✅ 创建本重构计划文档
|
||||
|
||||
### 待更新...
|
||||
|
||||
---
|
||||
|
||||
## 👥 团队协作
|
||||
|
||||
**开发者**：Claude Code (AI Assistant) + User
|
||||
|
||||
**审查者**：User
|
||||
|
||||
**测试者**：User
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 风险与对策
|
||||
|
||||
### 风险 1：迁移数据丢失
|
||||
|
||||
**概率**：低
|
||||
**影响**：高
|
||||
**对策**：
|
||||
- ✅ 迁移前自动备份配置
|
||||
- ✅ 详细日志记录
|
||||
- ✅ 测试各种边界情况
|
||||
|
||||
### 风险 2：性能问题（大量服务器）
|
||||
|
||||
**概率**：中
|
||||
**影响**：中
|
||||
**对策**：
|
||||
- ⬜ 实现虚拟滚动
|
||||
- ⬜ 分页或懒加载
|
||||
- ⬜ 性能测试
|
||||
|
||||
### 风险 3：兼容性问题
|
||||
|
||||
**概率**：中
|
||||
**影响**：中
|
||||
**对策**：
|
||||
- ✅ 保留旧命令兼容层
|
||||
- ✅ 前端增量更新
|
||||
- ⬜ 多版本测试
|
||||
|
||||
### 风险 4：用户学习成本
|
||||
|
||||
**概率**：低
|
||||
**影响**：低
|
||||
**对策**：
|
||||
- ⬜ 清晰的 UI 设计
|
||||
- ⬜ 详细的升级指南
|
||||
- ⬜ 操作提示和引导
|
||||
|
||||
---
|
||||
|
||||
## 🎉 预期收益
|
||||
|
||||
### 用户体验提升
|
||||
|
||||
- ⭐ **简化操作**：不再需要在不同应用面板切换
|
||||
- ⭐ **统一视图**：一目了然看到所有 MCP 配置
|
||||
- ⭐ **灵活配置**：轻松控制每个 MCP 应用到哪些客户端
|
||||
|
||||
### 代码质量提升
|
||||
|
||||
- ⭐ **架构优化**：统一数据源，消除冗余
|
||||
- ⭐ **维护性**：单一面板组件，代码更简洁
|
||||
- ⭐ **扩展性**：未来添加新应用（如 Cursor）更容易
|
||||
|
||||
### 性能提升
|
||||
|
||||
- ⭐ **减少重复加载**：统一管理减少配置文件读写
|
||||
- ⭐ **更快同步**：批量操作更高效
|
||||
|
||||
---
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
**问题反馈**：[GitHub Issues](https://github.com/jasonyoungyang/cc-switch/issues)
|
||||
|
||||
**功能建议**：[GitHub Discussions](https://github.com/jasonyoungyang/cc-switch/discussions)
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：v1.0
|
||||
**最后更新**：2025-11-14
|
||||
**状态**：🟡 开发中（后端完成 ✅，前端进行中 ⚠️）
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user