diff --git a/README.md b/README.md index 737480ac1..fd3c0205b 100644 --- a/README.md +++ b/README.md @@ -15,16 +15,18 @@ English | [中文](README_ZH.md) | [日本語](README_JA.md) | [Changelog](CHANG ## ❤️Sponsor -[![Zhipu GLM](assets/partners/banners/glm-en.jpg)](https://z.ai/subscribe?ic=8JVLJQFSKB) +[![MiniMax](assets/partners/banners/minimax-en.jpg)](https://bit.ly/3Nue8mA) -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)! +MiniMax M2.1 is an open-source, SOTA model built for real-world development and agentic workflows. It delivers top-tier performance on major coding benchmarks such as SWE, VIBE, and Multi-SWE. Powered by a 10B active / 230B total MoE architecture, M2.1 enables faster inference, easier deployment, and even local execution. It excels at coding, navigating digital environments, and handling long, multi-step tasks at scale. + +[Click](https://bit.ly/3Nue8mA) to get an exclusive 12% off the MiniMax Coding Plan! --- - + @@ -48,6 +50,11 @@ Claude Code / Codex / Gemini official channels at 38% / 2% / 9% of original pric + + + + + diff --git a/README_JA.md b/README_JA.md index 303712258..65396cebf 100644 --- a/README_JA.md +++ b/README_JA.md @@ -15,9 +15,11 @@ ## ❤️スポンサー -[![Zhipu GLM](assets/partners/banners/glm-en.jpg)](https://z.ai/subscribe?ic=8JVLJQFSKB) +[![MiniMax](assets/partners/banners/minimax-en.jpg)](https://bit.ly/3Nue8mA) -本プロジェクトは 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% オフになります！ +MiniMax M2.1 は、実務開発とエージェントワークフロー向けに構築されたオープンソースの最先端モデルです。100 億のアクティブパラメータ / 2,300 億の総パラメータを持つ MoE アーキテクチャにより、高速な推論、簡単なデプロイ、ローカル実行にも対応します。SWE、VIBE、Multi-SWE などの主要コーディングベンチマークでトップクラスの性能を発揮し、コーディング、デジタル環境のナビゲーション、大規模な多段階タスクの処理に優れています。 + +[こちら](https://bit.ly/3Nue8mA)から MiniMax Coding Plan の限定 12% オフを入手！ --- @@ -48,6 +50,11 @@ Claude Code / Codex / Gemini 公式チャンネルが最安で元価格の 38% / + + + + + diff --git a/README_ZH.md b/README_ZH.md index e33a32f39..587365fe1 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -15,16 +15,18 @@ ## ❤️赞助商 -[![智谱 GLM](assets/partners/banners/glm-zh.jpg)](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII) +[![MiniMax](assets/partners/banners/minimax-zh.jpeg)](https://platform.minimaxi.com/subscribe/coding-plan?code=7kYF2VoaCn&source=link) -感谢智谱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)购买可以享受九折优惠。 +MiniMax M2.x 系列模型是面向实际开发与智能体工作流打造的编码模型，M2.1 基于 100 亿激活 / 2300 亿总参的混合专家架构打造，推理更快、部署更便捷且支持本地运行，在 SWE、VIBE、Multi-SWE 等主流代码评测基准中均表现顶尖，擅长代码开发、数字环境适配及规模化处理长链路多步骤任务。 + +[点击](https://platform.minimaxi.com/subscribe/coding-plan?code=7kYF2VoaCn&source=link)即可领取 MiniMax Coding Plan 专属 88 折优惠！ ---
PackyCodeThanks 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 this link and enter the "cc-switch" promo code during recharge to get 10% off.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 this link and enter the "cc-switch" promo code during first recharge to get 10% off.
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! Register here
RightCodeThank you to Right Code for sponsoring this project! Right Code reliably provides routing services for models such as Claude Code, Codex, and Gemini. It features a highly cost-effective Codex monthly subscription plan and supports quota rollovers—unused quota from one day can be carried over and used the next day. Invoices are available upon top-up. Enterprise and team users can receive dedicated one-on-one support. Right Code also offers an exclusive discount for CC Switch users: register via this link, and with every top-up you will receive pay-as-you-go credit equivalent to 25% of the amount paid.
AICoding 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 this link get 10% off their first top-up!DMXAPI のご支援に感謝します！DMXAPI は 200 社以上の企業ユーザーにグローバル大規模モデル API サービスを提供しています。1 つの API キーで全世界のモデルにアクセス可能。即時請求書発行、同時接続数無制限、最低 $0.15 から、24 時間年中無休のテクニカルサポート。GPT/Claude/Gemini が全て 32% オフ、国内モデルは 20〜50% オフ、Claude Code 専用モデルは 66% オフ実施中！登録はこちら
RightCode本プロジェクトへのご支援として、Right Code にご協賛いただき誠にありがとうございます。Right Code は、Claude Code、Codex、Gemini などのモデルに対応した中継（プロキシ）サービスを安定して提供しています。特に高いコストパフォーマンスを誇る Codex の月額プランを主力としており、未使用分の利用枠を翌日に繰り越して利用できる（繰越対応）点が特長です。チャージ（入金）後に請求書の発行が可能で、企業・チーム向けには専任担当による個別対応も行っています。さらに CC Switch ユーザー向けの特別優待として、こちらのリンクからご登録いただくと、チャージのたびに実支払額の 25% 相当の従量課金クレジットが付与されます。
AICoding AICoding.sh のご支援に感謝します！AICoding.sh —— グローバル AI モデル API 超お得な中継サービス！Claude Code 81% オフ、GPT 99% オフ！数百社の企業に高コストパフォーマンスの AI サービスを提供。Claude Code、GPT、Gemini および国内主要モデルに対応、エンタープライズ級の高同時接続、迅速な請求書発行、24 時間年中無休の専属テクニカルサポート。こちらのリンクから登録した CC Switch ユーザーは、初回チャージ 10% オフ！
- + @@ -49,6 +51,11 @@ Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更 为200多家企业用户提供全球大模型API服务。· 充值即开票 ·当天开票 ·并发不限制 ·1元起充 · 7x24 在线技术辅导，GPT/Claude/Gemini全部6.8折，国内模型5~8折，Claude Code 专属模型3.4折进行中！点击这里注册 + + + + + diff --git a/assets/partners/banners/minimax-en.jpg b/assets/partners/banners/minimax-en.jpg new file mode 100644 index 000000000..381974431 Binary files /dev/null and b/assets/partners/banners/minimax-en.jpg differ diff --git a/assets/partners/banners/minimax-zh.jpeg b/assets/partners/banners/minimax-zh.jpeg new file mode 100644 index 000000000..0bee98460 Binary files /dev/null and b/assets/partners/banners/minimax-zh.jpeg differ diff --git a/assets/partners/logos/rightcode.jpg b/assets/partners/logos/rightcode.jpg new file mode 100644 index 000000000..06ac3a63e Binary files /dev/null and b/assets/partners/logos/rightcode.jpg differ diff --git a/docs/user-manual/1-getting-started/1.1-introduction.md b/docs/user-manual/1-getting-started/1.1-introduction.md new file mode 100644 index 000000000..536662c30 --- /dev/null +++ b/docs/user-manual/1-getting-started/1.1-introduction.md @@ -0,0 +1,64 @@ +# 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（设备设置） + +这种架构确保了： +- 跨平台一致的体验 +- 原生级别的性能 +- 安全的本地数据存储 diff --git a/docs/user-manual/1-getting-started/1.2-installation.md b/docs/user-manual/1-getting-started/1.2-installation.md new file mode 100644 index 000000000..fdda3c5ec --- /dev/null +++ b/docs/user-manual/1-getting-started/1.2-installation.md @@ -0,0 +1,243 @@ +# 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 +``` diff --git a/docs/user-manual/1-getting-started/1.3-interface.md b/docs/user-manual/1-getting-started/1.3-interface.md new file mode 100644 index 000000000..e88afb96e --- /dev/null +++ b/docs/user-manual/1-getting-started/1.3-interface.md @@ -0,0 +1,169 @@ +# 1.3 界面概览 + +## 主界面布局 + +![image-20260108001629138](../assets/image-20260108001629138.png) + +## 顶部导航栏 + +| 序号 | 元素 | 功能说明 | +|------|------|----------| +| ① | 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 在系统托盘显示图标，提供快速操作入口。 + +### 托盘菜单结构 + +![image-20260108002153668](../assets/image-20260108002153668.png) + +### 菜单功能 + +| 菜单项 | 功能 | +|--------|------| +| 打开主界面 | 显示主窗口并聚焦 | +| 应用分组 | 按 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` 关闭搜索 diff --git a/docs/user-manual/1-getting-started/1.4-quickstart.md b/docs/user-manual/1-getting-started/1.4-quickstart.md new file mode 100644 index 000000000..15a7b8e99 --- /dev/null +++ b/docs/user-manual/1-getting-started/1.4-quickstart.md @@ -0,0 +1,92 @@ +# 1.4 快速上手 + +本节帮助你在 5 分钟内完成首次配置。 + +## 第一步：添加供应商 + +1. 点击主界面右上角的 **+** 按钮 +2. 在「预设」下拉框中选择你的供应商 + - 常用预设：智谱 GLM、MiniMax、DeepSeek、Kimi、PackyCode + - 或选择「自定义」手动配置 +3. 填写 **API Key** +4. 点击「添加」 + +![image-20260108002807657](../assets/image-20260108002807657.png) + +> 💡 **提示**：预设会自动填充端点地址，你只需要填写 API Key。 + +## 第二步：切换供应商 + +添加完成后，供应商会出现在列表中。 + +**方式一：主界面切换** +- 点击供应商卡片的「启用」按钮 + +**方式二：托盘快速切换** +- 右键系统托盘图标 +- 直接点击供应商名称 + +## 第三步：生效方式 + +切换供应商后，各 CLI 工具的生效方式不同： + +| 应用 | 生效方式 | +|------|----------| +| Claude Code | ✅ 即时生效（支持热重载） | +| Codex | 需关闭并重新打开终端 | +| Gemini | ✅ 即时生效（每次请求重新读取配置） | + +### Claude Code 首次安装提示 + +如果 Claude Code 首次启动时提示需要**登录**或显示初始化引导，请在 CC Switch 中开启「跳过 Claude Code 初次安装确认」选项： + +1. 打开 CC Switch「设置 → 通用」 +2. 开启「跳过 Claude Code 初次安装确认」开关 +3. 重新启动 Claude Code + +![image-20260108002626389](../assets/image-20260108002626389.png) + +> ⚠️ **注意**：此选项会写入 `~/.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），重启客户端后按登录流程操作。 diff --git a/docs/user-manual/1-getting-started/1.5-settings.md b/docs/user-manual/1-getting-started/1.5-settings.md new file mode 100644 index 000000000..9c73e8aca --- /dev/null +++ b/docs/user-manual/1-getting-started/1.5-settings.md @@ -0,0 +1,134 @@ +# 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 +``` + +点击「复制」按钮可复制到剪贴板。 diff --git a/docs/user-manual/2-providers/2.1-add.md b/docs/user-manual/2-providers/2.1-add.md new file mode 100644 index 000000000..12425a4d8 --- /dev/null +++ b/docs/user-manual/2-providers/2.1-add.md @@ -0,0 +1,320 @@ +# 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（较慢） + +![image-20260108005327817](../assets/image-20260108005327817.png) + diff --git a/docs/user-manual/2-providers/2.2-switch.md b/docs/user-manual/2-providers/2.2-switch.md new file mode 100644 index 000000000..6e9833512 --- /dev/null +++ b/docs/user-manual/2-providers/2.2-switch.md @@ -0,0 +1,111 @@ +# 2.2 切换供应商 + +## 主界面切换 + +在供应商列表中，点击目标供应商卡片的「启用」按钮。 + +### 切换流程 + +1. 点击「启用」按钮 +2. CC Switch 更新配置文件 +3. 卡片状态变为「当前启用」 +4. Claude/Gemini 即时生效，Codex 需重启终端 + +### 状态指示 + +| 状态 | 显示 | 说明 | +|------|------|------| +| 当前启用 | 蓝色边框 + 标签 | 配置文件中的当前供应商 | +| 代理活跃 | 绿色边框 | 代理模式下实际使用的供应商 | +| 普通 | 默认样式 | 未启用的供应商 | + +## 托盘快速切换 + +通过系统托盘可以快速切换，无需打开主界面。 + +### 操作步骤 + +1. 右键点击系统托盘的 CC Switch 图标 +2. 在菜单中找到对应应用（Claude/Codex/Gemini/OpenCode） +3. 点击要切换的供应商名称 +4. 切换完成，托盘会短暂提示 + +### 托盘菜单结构 + +![image-20260108004348993](../assets/image-20260108004348993.png) + +## 生效方式 + +### 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 格式。 diff --git a/docs/user-manual/2-providers/2.3-edit.md b/docs/user-manual/2-providers/2.3-edit.md new file mode 100644 index 000000000..57c22ad01 --- /dev/null +++ b/docs/user-manual/2-providers/2.3-edit.md @@ -0,0 +1,145 @@ +# 2.3 编辑供应商 + +## 打开编辑面板 + +1. 找到要编辑的供应商卡片 +2. 鼠标悬停在卡片上，显示操作按钮 +3. 点击「编辑」按钮 + +## 可编辑内容 + +### 基本信息 + +| 字段 | 说明 | +|------|------| +| 名称 | 供应商显示名称 | +| 备注 | 附加说明信息 | +| 网站链接 | 供应商官网或控制台地址 | +| 图标 | 自定义图标和颜色 | + +### 图标自定义 + +CC Switch 提供丰富的图标自定义功能： + +#### 图标选择器 + +1. 点击图标区域打开图标选择器 +2. 使用搜索框按名称搜索图标 +3. 点击选择想要的图标 + +图标库包含常见的 AI 服务商和技术图标，支持： +- 按名称模糊搜索 +- 显示图标名称提示 +- 实时预览选中效果 + +![image-20260108004734882](../assets/image-20260108004734882.png) + +### 配置信息 + +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` 键关闭编辑面板，所有修改都不会保存。 diff --git a/docs/user-manual/2-providers/2.4-sort-duplicate.md b/docs/user-manual/2-providers/2.4-sort-duplicate.md new file mode 100644 index 000000000..9e87dae4e --- /dev/null +++ b/docs/user-manual/2-providers/2.4-sort-duplicate.md @@ -0,0 +1,76 @@ +# 2.4 排序与复制 + +## 拖拽排序 + +通过拖拽调整供应商的显示顺序。 + +### 操作步骤 + +1. 将鼠标移到供应商卡片左侧的 **≡** 拖拽手柄 +2. 按住鼠标左键 +3. 上下拖动到目标位置 +4. 松开鼠标完成排序 + +### 排序用途 + +- **常用优先**：将常用的供应商放在列表顶部 +- **故障转移顺序**：排序会影响故障转移队列的默认顺序 + +## 复制供应商 + +快速创建供应商的副本，适用于： + +- 基于现有配置创建变体 +- 备份当前配置 +- 创建测试用配置 + +### 操作步骤 + +1. 鼠标悬停在供应商卡片上，显示操作按钮 +2. 点击「复制」按钮 +3. 自动创建副本，名称后缀 `copy` +4. 编辑副本修改配置 + +### 复制内容 + +复制会创建完整的副本，包括： + +| 内容 | 是否复制 | +|------|----------| +| 名称 | ✅ 复制（添加 `copy` 后缀） | +| 配置 | ✅ 完整复制 | +| 备注 | ✅ 复制 | +| 网站链接 | ✅ 复制 | +| 图标 | ✅ 复制 | +| 端点列表 | ✅ 复制 | +| 排序位置 | ✅ 插入到原供应商下方 | + +### 复制后编辑 + +复制完成后，通常需要修改： + +1. **名称**：改为有意义的名称 +2. **API Key**：如果是不同账号 +3. **端点**：如果是不同服务 + +## 删除供应商 + +### 操作步骤 + +1. 鼠标悬停在供应商卡片上，显示操作按钮 +2. 点击「删除」按钮 +3. 确认删除 + +### 删除确认 + +删除前会弹出确认对话框，显示： + +- 供应商名称 +- 删除后无法恢复的提示 + +### 删除限制 + +- **当前启用的供应商**：可以删除，但建议先切换到其他供应商 +- **统一供应商**：删除后，关联的应用配置也会被删除 + +![image-20260108004946288](../assets/image-20260108004946288.png) diff --git a/docs/user-manual/2-providers/2.5-usage-query.md b/docs/user-manual/2-providers/2.5-usage-query.md new file mode 100644 index 000000000..d811ae92b --- /dev/null +++ b/docs/user-manual/2-providers/2.5-usage-query.md @@ -0,0 +1,181 @@ +# 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）会安全存储在本地 diff --git a/docs/user-manual/3-extensions/3.1-mcp.md b/docs/user-manual/3-extensions/3.1-mcp.md new file mode 100644 index 000000000..8ee7c3cb0 --- /dev/null +++ b/docs/user-manual/3-extensions/3.1-mcp.md @@ -0,0 +1,207 @@ +# 3.1 MCP 服务器管理 + +## 什么是 MCP + +MCP (Model Context Protocol) 是一种协议，允许 AI 工具访问外部数据源和工具。通过 MCP 服务器，你可以让 AI： + +- 访问文件系统 +- 执行网络请求 +- 查询数据库 +- 调用外部 API + +## 打开 MCP 面板 + +点击顶部导航栏的 **MCP** 按钮。 + +## 面板概览 + +![image-20260108005723522](../assets/image-20260108005723522.png) + +## 添加 MCP 服务器 + +### 使用预设模板 + +1. 点击右上角 **+** 按钮 +2. 在「预设」下拉框中选择模板 +3. 根据需要修改配置 +4. 点击「保存」 + +![image-20260108005739731](../assets/image-20260108005739731.png) + +### 常用预设 + +| 预设 | 包名 | 功能说明 | +|------|------|----------| +| 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 工具 diff --git a/docs/user-manual/3-extensions/3.2-prompts.md b/docs/user-manual/3-extensions/3.2-prompts.md new file mode 100644 index 000000000..641822906 --- /dev/null +++ b/docs/user-manual/3-extensions/3.2-prompts.md @@ -0,0 +1,158 @@ +# 3.2 Prompts 提示词管理 + +## 功能说明 + +Prompts 功能用于管理系统提示词预设。系统提示词会影响 AI 的行为和回复风格。 + +通过 CC Switch，你可以： + +- 创建多个提示词预设 +- 快速切换不同场景的提示词 +- 跨设备同步提示词配置 + +## 打开 Prompts 面板 + +点击顶部导航栏的 **Prompts** 按钮。 + +## 面板概览 + +![image-20260108010110382](../assets/image-20260108010110382.png) + +## 创建预设 + +### 操作步骤 + +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= +``` + +### 通过配置导出 + +导出配置时会包含所有预设，导入后可恢复。 diff --git a/docs/user-manual/3-extensions/3.3-skills.md b/docs/user-manual/3-extensions/3.3-skills.md new file mode 100644 index 000000000..4223bc87b --- /dev/null +++ b/docs/user-manual/3-extensions/3.3-skills.md @@ -0,0 +1,199 @@ +# 3.3 Skills 技能管理 + +## 功能说明 + +Skills 是可复用的能力扩展，让 AI 工具获得特定领域的专业能力。 + +技能以文件夹形式存在，包含： +- 提示词模板 +- 工具定义 +- 示例代码 + +## 支持的应用 + +Skills 功能支持所有四种应用： +- **Claude Code** +- **Codex** +- **Gemini CLI** +- **OpenCode** + +## 打开 Skills 页面 + +点击顶部导航栏的 **Skills** 按钮。 + +> 注意：Skills 按钮在所有应用模式下均可见。 + +## 页面概览 + +![image-20260108010253926](../assets/image-20260108010253926.png) + +## 发现技能 + +### 预配置仓库 + +CC Switch 预配置了以下 GitHub 仓库： + +| 仓库 | 说明 | +|------|------| +| Anthropic 官方 | Anthropic 提供的官方技能 | +| ComposioHQ | 社区维护的技能集合 | +| 社区精选 | 精选的高质量技能 | + +![image-20260108010308060](../assets/image-20260108010308060.png) + +### 搜索过滤 + +CC Switch 提供强大的搜索和过滤功能： + +#### 搜索框 + +- 支持按技能名称搜索 +- 支持按技能描述搜索 +- 支持按目录名称搜索 +- 实时过滤，输入即搜索 + +#### 状态过滤 + +使用下拉菜单按安装状态过滤： + +| 选项 | 说明 | +|------|------| +| 全部 | 显示所有技能 | +| 已安装 | 仅显示已安装的技能 | +| 未安装 | 仅显示未安装的技能 | + +![image-20260108010324583](../assets/image-20260108010324583.png) + +#### 组合使用 + +搜索和过滤可以组合使用： +- 先选择「已安装」过滤 +- 再输入关键词搜索 +- 结果显示匹配数量 + +### 刷新列表 + +点击「刷新」按钮重新扫描仓库，获取最新技能。 + +## 安装技能 + +### 操作步骤 + +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 +- 仓库配置错误 + +解决方法： +- 检查网络连接 +- 点击「刷新」重试 +- 检查仓库配置 + +### 安装失败 + +可能原因： +- 网络问题 +- 磁盘空间不足 +- 权限问题 + +解决方法： +- 检查网络连接 +- 检查磁盘空间 +- 检查目录权限 diff --git a/docs/user-manual/4-proxy/4.1-service.md b/docs/user-manual/4-proxy/4.1-service.md new file mode 100644 index 000000000..49666f21d --- /dev/null +++ b/docs/user-manual/4-proxy/4.1-service.md @@ -0,0 +1,222 @@ +# 4.1 代理服务 + +## 功能说明 + +代理服务在本地启动一个 HTTP 代理，所有 API 请求都通过代理转发。 + +**主要用途**： +- 记录请求日志 +- 统计 API 用量 +- 支持故障转移 +- 集中管理多个应用的请求 + +## 启动代理 + +### 方式一：主界面开关 + +点击主界面顶部的 **代理开关** 按钮。 + +开关状态： +- 🔴 白色：代理未运行 +- 🟢 绿色：代理运行中 + +![image-20260108011353927](../assets/image-20260108011353927.png) + +### 方式二：设置页面 + +1. 打开「设置 → 高级 → 代理服务」 +2. 点击右上角的开关 + +![image-20260108011338922](../assets/image-20260108011338922.png) + +## 代理配置 + +### 基础配置 + +| 配置项 | 说明 | 默认值 | +|--------|------|--------| +| 监听地址 | 代理绑定的 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 +- 检查供应商配置 diff --git a/docs/user-manual/4-proxy/4.2-takeover.md b/docs/user-manual/4-proxy/4.2-takeover.md new file mode 100644 index 000000000..67e8afd89 --- /dev/null +++ b/docs/user-manual/4-proxy/4.2-takeover.md @@ -0,0 +1,196 @@ +# 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 会备份原始配置，关闭时恢复。 + +## 常见问题 + +### 接管后请求失败 + +检查： +- 代理服务是否正常运行 +- 供应商配置是否正确 +- 网络是否正常 + +### 关闭接管后配置未恢复 + +可能原因： +- 代理异常退出 +- 配置文件被其他程序修改 + +解决方法： +- 手动编辑供应商，重新保存 +- 或重新启用再关闭接管 diff --git a/docs/user-manual/4-proxy/4.3-failover.md b/docs/user-manual/4-proxy/4.3-failover.md new file mode 100644 index 000000000..484dc24e0 --- /dev/null +++ b/docs/user-manual/4-proxy/4.3-failover.md @@ -0,0 +1,233 @@ +# 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. 重置熔断状态 diff --git a/docs/user-manual/4-proxy/4.4-usage.md b/docs/user-manual/4-proxy/4.4-usage.md new file mode 100644 index 000000000..acf8c095a --- /dev/null +++ b/docs/user-manual/4-proxy/4.4-usage.md @@ -0,0 +1,291 @@ +# 4.4 用量统计 + +## 功能说明 + +用量统计功能记录和分析 API 请求数据，帮助你： + +- 了解 API 使用情况 +- 估算费用支出 +- 分析使用模式 +- 排查问题 + +## 前提条件 + +使用用量统计功能需要： + +1. ✅ 启动代理服务 +2. ✅ 开启应用接管 +3. ✅ 开启日志记录 + +## 打开用量统计 + +设置 → 用量 Tab + +## 统计概览 + +### 汇总卡片 + +页面顶部显示关键指标： + +| 指标 | 说明 | +|------|------| +| 总请求数 | 统计周期内的请求总数 | +| 总 Token | 输入 + 输出 Token 总数 | +| 估算费用 | 基于定价配置计算的费用 | +| 成功率 | 成功请求的百分比 | + +### 时间范围 + +可选择统计的时间范围： + +| 选项 | 范围 | +|------|------| +| 今日 | 当天 00:00 至今 | +| 最近 7 天 | 过去 7 天 | +| 最近 30 天 | 过去 30 天 | + +![image-20260108011730105](../assets/image-20260108011730105.png) + +## 趋势图表 + +### 请求趋势 + +折线图展示请求数量的变化趋势： + +- 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 天**：按天显示 + + + +![image-20260108011742847](../assets/image-20260108011742847.png) + +## 详细数据 + +页面下方有三个数据 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 小时） +- **刷新**：重新加载数据 + +![image-20260108011859974](../assets/image-20260108011859974.png) + +### 供应商统计 + +按供应商分组的统计数据： + +| 字段 | 说明 | +|------|------| +| 供应商 | 供应商名称 | +| 请求数 | 该供应商的请求总数 | +| 成功数 | 成功的请求数 | +| 失败数 | 失败的请求数 | +| 成功率 | 成功百分比 | +| 总 Token | Token 使用总量 | +| 估算费用 | 该供应商的费用 | + +![image-20260108011907928](../assets/image-20260108011907928.png) + +### 模型统计 + +按模型分组的统计数据： + +| 字段 | 说明 | +|------|------| +| 模型 | 模型名称 | +| 请求数 | 该模型的请求总数 | +| 输入 Token | 输入 Token 总量 | +| 输出 Token | 输出 Token 总量 | +| 平均延迟 | 平均响应时间 | +| 估算费用 | 该模型的费用 | + +![image-20260108011915381](../assets/image-20260108011915381.png) + +## 定价配置 + +### 打开定价配置 + +设置 → 高级 → 定价配置 + +### 配置模型价格 + +为每个模型设置价格（每百万 Token）： + +| 字段 | 说明 | +|------|------| +| 模型 ID | 模型标识符（如 claude-3-sonnet） | +| 显示名称 | 自定义显示名称 | +| 输入价格 | 每百万输入 Token 的价格 | +| 输出价格 | 每百万输出 Token 的价格 | +| 缓存读取价格 | 每百万缓存命中 Token 的价格 | +| 缓存创建价格 | 每百万缓存创建 Token 的价格 | + +### 操作 + +- **添加**：点击「添加」按钮新增模型定价 +- **编辑**：点击行末的编辑图标修改 +- **删除**：点击行末的删除图标移除 + +![image-20260108011933565](../assets/image-20260108011933565.png) + +### 预设价格 + +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 数，可能与供应商的计算方式略有差异。以供应商账单为准。 diff --git a/docs/user-manual/4-proxy/4.5-model-test.md b/docs/user-manual/4-proxy/4.5-model-test.md new file mode 100644 index 000000000..b3a98522a --- /dev/null +++ b/docs/user-manual/4-proxy/4.5-model-test.md @@ -0,0 +1,156 @@ +# 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 配额 +- 建议使用低成本模型进行测试 +- 测试频率不宜过高，避免浪费配额 +- 不同供应商支持的模型可能不同 diff --git a/docs/user-manual/5-faq/5.1-config-files.md b/docs/user-manual/5-faq/5.1-config-files.md new file mode 100644 index 000000000..4049a67a6 --- /dev/null +++ b/docs/user-manual/5-faq/5.1-config-files.md @@ -0,0 +1,278 @@ +# 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 预设 +- 应用设置 + +### 不包含的内容 + +- 用量日志（数据量大） +- 设备级设置（不适合跨设备） diff --git a/docs/user-manual/5-faq/5.2-questions.md b/docs/user-manual/5-faq/5.2-questions.md new file mode 100644 index 000000000..83084c979 --- /dev/null +++ b/docs/user-manual/5-faq/5.2-questions.md @@ -0,0 +1,220 @@ +# 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\` diff --git a/docs/user-manual/5-faq/5.3-deeplink.md b/docs/user-manual/5-faq/5.3-deeplink.md new file mode 100644 index 000000000..32057e17a --- /dev/null +++ b/docs/user-manual/5-faq/5.3-deeplink.md @@ -0,0 +1,256 @@ +# 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. 确保所有必填字段都存在 diff --git a/docs/user-manual/5-faq/5.4-env-conflict.md b/docs/user-manual/5-faq/5.4-env-conflict.md new file mode 100644 index 000000000..5b5f07233 --- /dev/null +++ b/docs/user-manual/5-faq/5.4-env-conflict.md @@ -0,0 +1,108 @@ +# 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. 手动恢复变量到系统环境 diff --git a/docs/user-manual/README.md b/docs/user-manual/README.md new file mode 100644 index 000000000..057c292df --- /dev/null +++ b/docs/user-manual/README.md @@ -0,0 +1,111 @@ +# 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) diff --git a/docs/user-manual/assets/image-20260108001629138.png b/docs/user-manual/assets/image-20260108001629138.png new file mode 100644 index 000000000..363bc12c5 Binary files /dev/null and b/docs/user-manual/assets/image-20260108001629138.png differ diff --git a/docs/user-manual/assets/image-20260108002153668.png b/docs/user-manual/assets/image-20260108002153668.png new file mode 100644 index 000000000..aa1936e4b Binary files /dev/null and b/docs/user-manual/assets/image-20260108002153668.png differ diff --git a/docs/user-manual/assets/image-20260108002626389.png b/docs/user-manual/assets/image-20260108002626389.png new file mode 100644 index 000000000..29997215f Binary files /dev/null and b/docs/user-manual/assets/image-20260108002626389.png differ diff --git a/docs/user-manual/assets/image-20260108002807657.png b/docs/user-manual/assets/image-20260108002807657.png new file mode 100644 index 000000000..235a98363 Binary files /dev/null and b/docs/user-manual/assets/image-20260108002807657.png differ diff --git a/docs/user-manual/assets/image-20260108004348993.png b/docs/user-manual/assets/image-20260108004348993.png new file mode 100644 index 000000000..df4bf7f94 Binary files /dev/null and b/docs/user-manual/assets/image-20260108004348993.png differ diff --git a/docs/user-manual/assets/image-20260108004734882.png b/docs/user-manual/assets/image-20260108004734882.png new file mode 100644 index 000000000..9513db871 Binary files /dev/null and b/docs/user-manual/assets/image-20260108004734882.png differ diff --git a/docs/user-manual/assets/image-20260108004946288.png b/docs/user-manual/assets/image-20260108004946288.png new file mode 100644 index 000000000..438fef1d1 Binary files /dev/null and b/docs/user-manual/assets/image-20260108004946288.png differ diff --git a/docs/user-manual/assets/image-20260108005327817.png b/docs/user-manual/assets/image-20260108005327817.png new file mode 100644 index 000000000..a0b587516 Binary files /dev/null and b/docs/user-manual/assets/image-20260108005327817.png differ diff --git a/docs/user-manual/assets/image-20260108005723522.png b/docs/user-manual/assets/image-20260108005723522.png new file mode 100644 index 000000000..1913f6fca Binary files /dev/null and b/docs/user-manual/assets/image-20260108005723522.png differ diff --git a/docs/user-manual/assets/image-20260108005739731.png b/docs/user-manual/assets/image-20260108005739731.png new file mode 100644 index 000000000..699c7304b Binary files /dev/null and b/docs/user-manual/assets/image-20260108005739731.png differ diff --git a/docs/user-manual/assets/image-20260108010110382.png b/docs/user-manual/assets/image-20260108010110382.png new file mode 100644 index 000000000..f25cd1dee Binary files /dev/null and b/docs/user-manual/assets/image-20260108010110382.png differ diff --git a/docs/user-manual/assets/image-20260108010253926.png b/docs/user-manual/assets/image-20260108010253926.png new file mode 100644 index 000000000..1136a53da Binary files /dev/null and b/docs/user-manual/assets/image-20260108010253926.png differ diff --git a/docs/user-manual/assets/image-20260108010308060.png b/docs/user-manual/assets/image-20260108010308060.png new file mode 100644 index 000000000..2bd15f59d Binary files /dev/null and b/docs/user-manual/assets/image-20260108010308060.png differ diff --git a/docs/user-manual/assets/image-20260108010324583.png b/docs/user-manual/assets/image-20260108010324583.png new file mode 100644 index 000000000..30121d16b Binary files /dev/null and b/docs/user-manual/assets/image-20260108010324583.png differ diff --git a/docs/user-manual/assets/image-20260108011338922.png b/docs/user-manual/assets/image-20260108011338922.png new file mode 100644 index 000000000..6a460e9de Binary files /dev/null and b/docs/user-manual/assets/image-20260108011338922.png differ diff --git a/docs/user-manual/assets/image-20260108011353927.png b/docs/user-manual/assets/image-20260108011353927.png new file mode 100644 index 000000000..2c4ca4fbb Binary files /dev/null and b/docs/user-manual/assets/image-20260108011353927.png differ diff --git a/docs/user-manual/assets/image-20260108011730105.png b/docs/user-manual/assets/image-20260108011730105.png new file mode 100644 index 000000000..a68974162 Binary files /dev/null and b/docs/user-manual/assets/image-20260108011730105.png differ diff --git a/docs/user-manual/assets/image-20260108011742847.png b/docs/user-manual/assets/image-20260108011742847.png new file mode 100644 index 000000000..8dcb910b0 Binary files /dev/null and b/docs/user-manual/assets/image-20260108011742847.png differ diff --git a/docs/user-manual/assets/image-20260108011859974.png b/docs/user-manual/assets/image-20260108011859974.png new file mode 100644 index 000000000..bdc00b01c Binary files /dev/null and b/docs/user-manual/assets/image-20260108011859974.png differ diff --git a/docs/user-manual/assets/image-20260108011907928.png b/docs/user-manual/assets/image-20260108011907928.png new file mode 100644 index 000000000..a4104ae69 Binary files /dev/null and b/docs/user-manual/assets/image-20260108011907928.png differ diff --git a/docs/user-manual/assets/image-20260108011915381.png b/docs/user-manual/assets/image-20260108011915381.png new file mode 100644 index 000000000..4064031d5 Binary files /dev/null and b/docs/user-manual/assets/image-20260108011915381.png differ diff --git a/docs/user-manual/assets/image-20260108011933565.png b/docs/user-manual/assets/image-20260108011933565.png new file mode 100644 index 000000000..5bc6dae0a Binary files /dev/null and b/docs/user-manual/assets/image-20260108011933565.png differ diff --git a/src/App.tsx b/src/App.tsx index 997387bb1..162b1b149 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -139,6 +139,13 @@ function App() { } }, [visibleApps, activeApp]); + // Fallback from sessions view when switching to an app without session support + useEffect(() => { + if (currentView === "sessions" && activeApp !== "claude" && activeApp !== "codex") { + setCurrentView("providers"); + } + }, [activeApp, currentView]); + const [editingProvider, setEditingProvider] = useState(null); const [usageProvider, setUsageProvider] = useState(null); const [confirmAction, setConfirmAction] = useState<{ @@ -177,6 +184,7 @@ function App() { const providers = useMemo(() => data?.providers ?? {}, [data]); const currentProviderId = data?.currentProviderId ?? ""; const hasSkillsSupport = true; + const hasSessionSupport = activeApp === "claude" || activeApp === "codex"; const { addProvider, @@ -964,10 +972,16 @@ function App() { variant="ghost" size="sm" onClick={() => setCurrentView("sessions")} - className="text-muted-foreground hover:text-foreground hover:bg-black/5 dark:hover:bg-white/5" + className={cn( + "text-muted-foreground hover:text-foreground hover:bg-black/5 dark:hover:bg-white/5", + "transition-all duration-200 ease-in-out overflow-hidden", + hasSessionSupport + ? "opacity-100 w-8 scale-100 px-2" + : "opacity-0 w-0 scale-75 pointer-events-none px-0 -ml-1", + )} title={t("sessionManager.title")} > - +
PackyCode感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的API中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本软件的用户提供了特别优惠，使用此链接注册并在充值时填写"cc-switch"优惠码，可以享受9折优惠！感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的API中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本软件的用户提供了特别优惠，使用此链接注册并在充值时填写"cc-switch"优惠码，首次充值可以享受9折优惠！
RightCode感谢 Right Code 赞助了本项目！Right Code 稳定提供 Claude Code、Codex、Gemini 等模型的中转服务。主打极高性价比的Codex包月套餐，提供额度转结，套餐当天用不完的额度，第二天还能接着用！充值即可开票，企业、团队用户一对一对接。同时为 CC Switch 的用户提供了特别优惠：通过此链接注册，每次充值均可获得实付金额25%的按量额度！
AICoding 感谢 AICoding.sh 赞助了本项目！AICoding.sh —— 全球大模型 API 超值中转服务！Claude Code 1.9 折，GPT 0.1 折，已为数百家企业提供高性价比 AI 服务。支持 Claude Code、GPT、Gemini 及国内主流模型，企业级高并发、极速开票、7×24 专属技术支持，通过此链接 注册的 CC Switch 用户，首充可享受九折优惠！