From e612410debc7cd69f0f87fb116cb2efc2d6fdb0d Mon Sep 17 00:00:00 2001 From: Jason Date: Mon, 9 Feb 2026 14:57:57 +0800 Subject: [PATCH] fix(docs): align user manual with v3.10.3 codebase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add OpenCode as 4th supported app throughout all docs - Fix proxy default port 15762 → 15721 - Update Claude presets (9 → 26), Codex (3 → 10), Gemini (3 → 7) - Add OpenCode presets (25 entries) - Fix timeout defaults and ranges (stream first byte 60s/90s, etc.) - Fix circuit breaker defaults with per-app values (Claude vs general) - Fix Skills support: all 4 apps, not just Claude/Codex - Remove non-existent Gemini authMode field - Fix prompt deletion behavior: enabled prompts cannot be deleted - Remove non-existent Legacy deeplink protocol, use V1 only - Fix DB table names (usage_logs → proxy_request_logs) and add missing tables - Fix migration version v3.8.0 → v3.7.0 - Add missing V1 deeplink parameters (config, configFormat, etc.) - Update doc version v3.9.1 → v3.10.3 - Add claude-opus-4-1 to pricing table - Fix recovery wait time range 10-300 → 0-300 --- .../1-getting-started/1.1-introduction.md | 7 +- .../1-getting-started/1.3-interface.md | 5 +- docs/user-manual/2-providers/2.1-add.md | 92 ++++++++-- docs/user-manual/2-providers/2.2-switch.md | 2 +- docs/user-manual/3-extensions/3.1-mcp.md | 6 +- docs/user-manual/3-extensions/3.2-prompts.md | 4 +- docs/user-manual/3-extensions/3.3-skills.md | 10 +- docs/user-manual/4-proxy/4.1-service.md | 12 +- docs/user-manual/4-proxy/4.2-takeover.md | 9 +- docs/user-manual/4-proxy/4.3-failover.md | 39 ++-- docs/user-manual/4-proxy/4.4-usage.md | 3 +- docs/user-manual/5-faq/5.1-config-files.md | 31 +++- docs/user-manual/5-faq/5.3-deeplink.md | 167 ++++++------------ docs/user-manual/README.md | 8 +- 14 files changed, 219 insertions(+), 176 deletions(-) diff --git a/docs/user-manual/1-getting-started/1.1-introduction.md b/docs/user-manual/1-getting-started/1.1-introduction.md index ef3117d10..536662c30 100644 --- a/docs/user-manual/1-getting-started/1.1-introduction.md +++ b/docs/user-manual/1-getting-started/1.1-introduction.md @@ -2,14 +2,14 @@ ## 什么是 CC Switch -CC Switch 是一款跨平台桌面应用，专为使用 AI 编程工具的开发者设计。它帮助你统一管理 **Claude Code**、**Codex**、**Gemini CLI** 三大 AI 编程工具的配置。 +CC Switch 是一款跨平台桌面应用，专为使用 AI 编程工具的开发者设计。它帮助你统一管理 **Claude Code**、**Codex**、**Gemini CLI**、**OpenCode** 四大 AI 编程工具的配置。 ## 解决什么问题 在日常开发中，你可能会遇到这些痛点： - **多供应商切换麻烦**：使用不同的 API 供应商（官方、中转服务商），需要手动修改配置文件 -- **配置分散难管理**：Claude、Codex、Gemini 各有独立的配置文件，格式不同 +- **配置分散难管理**：Claude、Codex、Gemini、OpenCode 各有独立的配置文件，格式不同 - **无法监控用量**：不知道 API 调用了多少次，花了多少钱 - **服务不稳定**：单一供应商出问题时，整个工作流中断 @@ -27,7 +27,7 @@ CC Switch 通过统一的界面解决这些问题。 ### 扩展功能 - **MCP 服务器**：管理 Model Context Protocol 服务器，扩展 AI 能力 - **Prompts**：管理系统提示词预设，快速切换不同场景 -- **Skills**：安装和管理技能扩展（仅 Claude/Codex） +- **Skills**：安装和管理技能扩展 ### 代理与高可用 - 本地代理服务，记录请求日志和用量统计 @@ -42,6 +42,7 @@ CC Switch 通过统一的界面解决这些问题。 | **Claude Code** | Anthropic 官方的 AI 编程助手 | | **Codex** | OpenAI 的代码生成工具 | | **Gemini CLI** | Google 的 AI 命令行工具 | +| **OpenCode** | 开源 AI 编程终端工具 | ## 支持的平台 diff --git a/docs/user-manual/1-getting-started/1.3-interface.md b/docs/user-manual/1-getting-started/1.3-interface.md index 3d4665438..e88afb96e 100644 --- a/docs/user-manual/1-getting-started/1.3-interface.md +++ b/docs/user-manual/1-getting-started/1.3-interface.md @@ -11,7 +11,7 @@ | ① | Logo | 点击访问 GitHub 项目页 | | ② | 设置按钮 | 打开设置页面（快捷键 `Cmd/Ctrl + ,`） | | ③ | 代理开关 | 启动/停止本地代理服务 | -| ④ | 应用切换器 | 切换 Claude / Codex / Gemini | +| ④ | 应用切换器 | 切换 Claude / Codex / Gemini / OpenCode | | ⑤ | 功能区 | Skills / Prompts / MCP 入口 | | ⑥ | 添加按钮 | 添加新供应商 | @@ -22,6 +22,7 @@ - **Claude** - 管理 Claude Code 配置 - **Codex** - 管理 Codex 配置 - **Gemini** - 管理 Gemini CLI 配置 +- **OpenCode** - 管理 OpenCode 配置 切换后，供应商列表会显示对应应用的配置。 @@ -98,7 +99,7 @@ CC Switch 在系统托盘显示图标，提供快速操作入口。 | 菜单项 | 功能 | |--------|------| | 打开主界面 | 显示主窗口并聚焦 | -| 应用分组 | 按 Claude/Codex/Gemini 分组显示供应商 | +| 应用分组 | 按 Claude/Codex/Gemini/OpenCode 分组显示供应商 | | 供应商列表 | 点击切换，当前启用的显示勾选标记 | | 退出 | 完全退出应用 | diff --git a/docs/user-manual/2-providers/2.1-add.md b/docs/user-manual/2-providers/2.1-add.md index cd7032b29..12425a4d8 100644 --- a/docs/user-manual/2-providers/2.1-add.md +++ b/docs/user-manual/2-providers/2.1-add.md @@ -5,7 +5,7 @@ 点击主界面右上角的 **+** 按钮，打开添加供应商面板。 面板分为两个 Tab： -- **应用专属供应商**：仅用于当前选中的应用（Claude/Codex/Gemini） +- **应用专属供应商**：仅用于当前选中的应用（Claude/Codex/Gemini/OpenCode） - **统一供应商**：跨应用共享的配置 ## 使用预设添加 @@ -26,25 +26,49 @@ | 预设名称 | 说明 | |----------|------| -| 官方登录 | 使用 Anthropic 官方账号登录 | -| DeepSeek | DeepSeek-V3.2 模型 | -| 智谱 GLM | 智谱 AI 的 GLM-4.7 模型 ⭐ | -| Qwen Coder | 通义千问（阿里云百炼） | -| Kimi k2 | Moonshot Kimi-k2 模型 | -| MiniMax | MiniMax-M2.1 模型 ⭐ | +| 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 官方 | 使用 OpenAI 官方账号登录 | +| Azure OpenAI | Azure OpenAI 服务 | +| AiHubMix | AiHubMix 聚合服务 | +| DMXAPI | DMXAPI 中转服务 | | PackyCode | PackyCode 中转服务 | -| 自定义 | 手动配置所有参数 | +| Cubence | Cubence 服务 | +| AIGoCode | AIGoCode 服务 | +| RightCode | RightCode 服务 | +| AICodeMirror | AICodeMirror 服务 | +| OpenRouter | 聚合路由服务 | #### Gemini 预设 @@ -52,8 +76,44 @@ |----------|------| | 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 配置。 @@ -130,8 +190,7 @@ requires_openai_auth = true "env": { "GEMINI_API_KEY": "your-api-key", "GOOGLE_GEMINI_BASE_URL": "https://api.example.com" - }, - "authMode": "api_key" + } } ``` @@ -140,11 +199,12 @@ requires_openai_auth = true | `GEMINI_API_KEY` | 是 | API 密钥 | | `GOOGLE_GEMINI_BASE_URL` | 否 | 自定义端点地址 | | `GEMINI_MODEL` | 否 | 指定模型 | -| `authMode` | 否 | 认证模式：`api_key` 或 `oauth` | + +> 💡 认证类型由 CC Switch 自动检测（PackyCode API 代理 / Google OAuth / 通用 API Key），无需手动配置。 ## 统一供应商 -统一供应商可以跨 Claude/Codex/Gemini 共享配置，适用于支持多种 API 格式的中转服务。 +统一供应商可以跨 Claude/Codex/Gemini/OpenCode 共享配置，适用于支持多种 API 格式的中转服务。 ### 创建统一供应商 @@ -154,7 +214,7 @@ requires_openai_auth = true - 名称 - API Key - 端点地址 -4. 勾选要同步的应用（Claude/Codex/Gemini） +4. 勾选要同步的应用（Claude/Codex/Gemini/OpenCode） 5. 保存 ### 同步机制 diff --git a/docs/user-manual/2-providers/2.2-switch.md b/docs/user-manual/2-providers/2.2-switch.md index 89369d45f..6e9833512 100644 --- a/docs/user-manual/2-providers/2.2-switch.md +++ b/docs/user-manual/2-providers/2.2-switch.md @@ -26,7 +26,7 @@ ### 操作步骤 1. 右键点击系统托盘的 CC Switch 图标 -2. 在菜单中找到对应应用（Claude/Codex/Gemini） +2. 在菜单中找到对应应用（Claude/Codex/Gemini/OpenCode） 3. 点击要切换的供应商名称 4. 切换完成，托盘会短暂提示 diff --git a/docs/user-manual/3-extensions/3.1-mcp.md b/docs/user-manual/3-extensions/3.1-mcp.md index 2850bdffb..8ee7c3cb0 100644 --- a/docs/user-manual/3-extensions/3.1-mcp.md +++ b/docs/user-manual/3-extensions/3.1-mcp.md @@ -103,12 +103,13 @@ MCP (Model Context Protocol) 是一种协议，允许 AI 工具访问外部数 | 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` 状态设为 `true` +1. **更新数据库**：将服务器的 `apps.claude/codex/gemini/opencode` 状态设为 `true` 2. **同步到 Live 配置**：将服务器配置写入对应应用的配置文件 3. **即时生效**：下次启动 CLI 工具时自动加载新的 MCP 服务器 @@ -125,6 +126,7 @@ MCP 服务器同步仅在对应应用已安装时执行： - **Claude**：需存在 `~/.claude/` 目录或 `~/.claude.json` 文件 - **Codex**：需存在 `~/.codex/` 目录 - **Gemini**：需存在 `~/.gemini/` 目录 +- **OpenCode**：需存在 `~/.opencode/` 目录 > 💡 **提示**：如果某个 CLI 工具未安装，开启对应开关不会报错，但配置不会写入。 @@ -150,7 +152,7 @@ MCP 服务器同步仅在对应应用已安装时执行： 如果你已经在 CLI 工具中配置了 MCP 服务器，可以导入到 CC Switch： 1. 点击「导入」按钮 -2. 选择要导入的应用（Claude/Codex/Gemini） +2. 选择要导入的应用（Claude/Codex/Gemini/OpenCode） 3. CC Switch 会读取现有配置并导入 ## 配置文件格式 diff --git a/docs/user-manual/3-extensions/3.2-prompts.md b/docs/user-manual/3-extensions/3.2-prompts.md index 93cbbd535..641822906 100644 --- a/docs/user-manual/3-extensions/3.2-prompts.md +++ b/docs/user-manual/3-extensions/3.2-prompts.md @@ -81,6 +81,7 @@ Prompts 功能用于管理系统提示词预设。系统提示词会影响 AI | Claude | `~/.claude/CLAUDE.md` | | Codex | `~/.codex/AGENTS.md` | | Gemini | `~/.gemini/GEMINI.md` | +| OpenCode | `~/.opencode/AGENTS.md` | ## 编辑预设 @@ -95,7 +96,7 @@ Prompts 功能用于管理系统提示词预设。系统提示词会影响 AI 1. 点击预设项的「删除」按钮 2. 确认删除 -如果删除的是当前激活的预设，配置文件中的内容会被清空。 +已启用的预设不允许删除，需先停用后再删除。 ## 智能回填 @@ -138,6 +139,7 @@ Prompts 是按应用分开管理的： - 切换到 Claude 时，显示 Claude 的预设 - 切换到 Codex 时，显示 Codex 的预设 - 切换到 Gemini 时，显示 Gemini 的预设 +- 切换到 OpenCode 时，显示 OpenCode 的预设 如需在多个应用使用相同的提示词，需要分别创建。 diff --git a/docs/user-manual/3-extensions/3.3-skills.md b/docs/user-manual/3-extensions/3.3-skills.md index c83f09ba8..4223bc87b 100644 --- a/docs/user-manual/3-extensions/3.3-skills.md +++ b/docs/user-manual/3-extensions/3.3-skills.md @@ -11,17 +11,17 @@ Skills 是可复用的能力扩展，让 AI 工具获得特定领域的专业能 ## 支持的应用 -Skills 功能仅支持： +Skills 功能支持所有四种应用： - **Claude Code** - **Codex** - -> 💡 **注意**：Gemini CLI 暂不支持 Skills 功能。后端已预留 Gemini 技能路径 (`~/.gemini/skills/`)，待 Gemini CLI 官方支持后将自动开放。 +- **Gemini CLI** +- **OpenCode** ## 打开 Skills 页面 点击顶部导航栏的 **Skills** 按钮。 -> 注意：只有在 Claude 或 Codex 模式下才能看到 Skills 按钮。 +> 注意：Skills 按钮在所有应用模式下均可见。 ## 页面概览 @@ -89,6 +89,8 @@ CC Switch 提供强大的搜索和过滤功能： |------|----------| | Claude | `~/.claude/skills/` | | Codex | `~/.codex/skills/` | +| Gemini | `~/.gemini/skills/` | +| OpenCode | `~/.opencode/skills/` | ### 安装内容 diff --git a/docs/user-manual/4-proxy/4.1-service.md b/docs/user-manual/4-proxy/4.1-service.md index 325d6710d..49666f21d 100644 --- a/docs/user-manual/4-proxy/4.1-service.md +++ b/docs/user-manual/4-proxy/4.1-service.md @@ -36,7 +36,7 @@ | 配置项 | 说明 | 默认值 | |--------|------|--------| | 监听地址 | 代理绑定的 IP 地址 | `127.0.0.1` | -| 监听端口 | 代理监听的端口 | `15762` | +| 监听端口 | 代理监听的端口 | `15721` | | 启用日志 | 是否记录请求日志 | 开启 | ### 修改配置 @@ -62,7 +62,7 @@ ### 服务地址 ``` -http://127.0.0.1:15762 +http://127.0.0.1:15721 ``` 点击「复制」按钮可复制地址。 @@ -135,19 +135,19 @@ sequenceDiagram ```json { "env": { - "ANTHROPIC_BASE_URL": "http://127.0.0.1:15762" + "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721" } } ``` **Codex**： ```toml -base_url = "http://127.0.0.1:15762/v1" +base_url = "http://127.0.0.1:15721/v1" ``` **Gemini**： ``` -GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15762 +GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721 ``` ## 停止代理 @@ -181,7 +181,7 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15762 | 字段 | 说明 | |------|------| | 时间 | 请求时间 | -| 应用 | Claude/Codex/Gemini | +| 应用 | Claude/Codex/Gemini/OpenCode | | 供应商 | 使用的供应商 | | 模型 | 请求的模型 | | Token | 输入/输出 token 数 | diff --git a/docs/user-manual/4-proxy/4.2-takeover.md b/docs/user-manual/4-proxy/4.2-takeover.md index ab9024916..67e8afd89 100644 --- a/docs/user-manual/4-proxy/4.2-takeover.md +++ b/docs/user-manual/4-proxy/4.2-takeover.md @@ -32,6 +32,7 @@ | Claude 接管 | 接管 Claude Code 的请求 | | Codex 接管 | 接管 Codex 的请求 | | Gemini 接管 | 接管 Gemini CLI 的请求 | +| OpenCode 接管 | 接管 OpenCode 的请求 | 可以同时开启多个应用的接管。 @@ -54,7 +55,7 @@ // 接管后 { "env": { - "ANTHROPIC_BASE_URL": "http://127.0.0.1:" + "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721" } } ``` @@ -66,7 +67,7 @@ base_url = "https://api.openai.com/v1" # 接管后 -base_url = "http://127.0.0.1:5000/v1" +base_url = "http://127.0.0.1:15721/v1" ``` **Gemini 配置变更**： @@ -76,14 +77,14 @@ base_url = "http://127.0.0.1:5000/v1" GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com # 接管后 -GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:5000 +GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721 ``` ### 请求转发 代理收到请求后： -1. 识别请求来源（Claude/Codex/Gemini） +1. 识别请求来源（Claude/Codex/Gemini/OpenCode） 2. 查找该应用当前启用的供应商 3. 将请求转发到供应商的实际端点 4. 记录请求日志 diff --git a/docs/user-manual/4-proxy/4.3-failover.md b/docs/user-manual/4-proxy/4.3-failover.md index 029adec7f..484dc24e0 100644 --- a/docs/user-manual/4-proxy/4.3-failover.md +++ b/docs/user-manual/4-proxy/4.3-failover.md @@ -26,10 +26,11 @@ ### 选择应用 -页面顶部有三个 Tab： +页面顶部有四个 Tab： - Claude - Codex - Gemini +- OpenCode 选择要配置的应用。 @@ -104,27 +105,33 @@ graph TD ### 配置项 -| 配置 | 说明 | 默认值 | 范围 | -|------|------|--------|------| -| 失败阈值 | 连续失败多少次触发熔断 | 5 | 1-20 | -| 恢复成功阈值 | 半开状态下成功多少次后关闭熔断器 | 2 | 1-10 | -| 恢复等待时间 | 熔断后多久尝试恢复（秒） | 60 | 10-300 | -| 错误率阈值 | 错误率超过此值时打开熔断器 | 50% | 0-100% | -| 最小请求数 | 计算错误率前的最小请求数 | 10 | 5-100 | +不同应用有独立的默认配置。以下为通用默认值，Claude 有独立的宽松配置。 + +| 配置 | 说明 | 通用默认值 | Claude 默认值 | 范围 | +|------|------|--------|--------|------| +| 失败阈值 | 连续失败多少次触发熔断 | 4 | 8 | 1-20 | +| 恢复成功阈值 | 半开状态下成功多少次后关闭熔断器 | 2 | 3 | 1-10 | +| 恢复等待时间 | 熔断后多久尝试恢复（秒） | 60 | 90 | 0-300 | +| 错误率阈值 | 错误率超过此值时打开熔断器 | 60% | 70% | 0-100% | +| 最小请求数 | 计算错误率前的最小请求数 | 10 | 15 | 5-100 | + +> 💡 Claude 由于请求耗时较长，默认配置更为宽松，容忍更多失败次数。 ### 超时配置 -| 配置 | 说明 | 默认值 | 范围 | -|------|------|--------|------| -| 流式首字节超时 | 等待首个数据块的最大时间（秒） | 30 | 0-180 | -| 流式静默超时 | 数据块之间的最大间隔（秒） | 60 | 0-600 | -| 非流式超时 | 非流式请求的总超时时间（秒） | 300 | 0-1800 | +| 配置 | 说明 | 通用默认值 | Claude 默认值 | 范围 | +|------|------|--------|--------|------| +| 流式首字节超时 | 等待首个数据块的最大时间（秒） | 60 | 90 | 1-120 | +| 流式静默超时 | 数据块之间的最大间隔（秒） | 120 | 180 | 60-600（填 0 禁用） | +| 非流式超时 | 非流式请求的总超时时间（秒） | 600 | 600 | 60-1200 | ### 重试配置 -| 配置 | 说明 | 默认值 | 范围 | -|------|------|--------|------| -| 最大重试次数 | 请求失败时的重试次数 | 3 | 0-10 | +| 配置 | 说明 | 通用默认值 | Claude 默认值 | 范围 | +|------|------|--------|--------|------| +| 最大重试次数 | 请求失败时的重试次数 | 3 | 6 | 0-10 | + +> 💡 Gemini 的默认最大重试次数为 5。 ### 熔断状态 diff --git a/docs/user-manual/4-proxy/4.4-usage.md b/docs/user-manual/4-proxy/4.4-usage.md index 73266580f..acf8c095a 100644 --- a/docs/user-manual/4-proxy/4.4-usage.md +++ b/docs/user-manual/4-proxy/4.4-usage.md @@ -123,7 +123,7 @@ | 筛选项 | 选项 | |--------|------| -| 应用类型 | 全部 / Claude / Codex / Gemini | +| 应用类型 | 全部 / Claude / Codex / Gemini / OpenCode | | 状态码 | 全部 / 200 / 400 / 401 / 429 / 500 | | 供应商 | 文本搜索 | | 模型 | 文本搜索 | @@ -208,6 +208,7 @@ CC Switch 预设了常用模型的官方价格（每百万 Token）： | 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 | diff --git a/docs/user-manual/5-faq/5.1-config-files.md b/docs/user-manual/5-faq/5.1-config-files.md index a6c2e9783..4049a67a6 100644 --- a/docs/user-manual/5-faq/5.1-config-files.md +++ b/docs/user-manual/5-faq/5.1-config-files.md @@ -27,10 +27,16 @@ | 表 | 内容 | |-----|------| | providers | 供应商配置 | +| provider_endpoints | 供应商端点候选列表 | | mcp_servers | MCP 服务器配置 | | prompts | 提示词预设 | | skills | 技能安装状态 | -| usage_logs | 用量日志 | +| skill_repos | 技能仓库配置 | +| proxy_config | 代理配置 | +| proxy_request_logs | 代理请求日志 | +| provider_health | 供应商健康状态 | +| model_pricing | 模型定价 | +| settings | 应用设置 | ### 设备设置 @@ -44,7 +50,8 @@ "autoStart": false, "claudeConfigDir": null, "codexConfigDir": null, - "geminiConfigDir": null + "geminiConfigDir": null, + "opencodeConfigDir": null } ``` @@ -172,7 +179,6 @@ GEMINI_MODEL=gemini-pro ```json { - "authMode": "api_key", "mcpServers": { "mcp-fetch": { "command": "uvx", @@ -184,9 +190,24 @@ GEMINI_MODEL=gemini-pro | 字段 | 说明 | |------|------| -| `authMode` | 认证模式：`api_key` 或 `oauth` | | `mcpServers` | MCP 服务器配置 | +## OpenCode 配置 + +### 配置目录 + +默认：`~/.opencode/` + +### 主要文件 + +``` +~/.opencode/ +├── config.json # 主配置文件 +├── AGENTS.md # 系统提示词 +└── skills/ # 技能目录 + └── ... +``` + ## 配置优先级 CC Switch 修改配置时的优先级： @@ -220,7 +241,7 @@ CC Switch 修改配置时的优先级： ### 从旧版本迁移 -CC Switch v3.8.0 从 JSON 文件迁移到 SQLite： +CC Switch v3.7.0 从 JSON 文件迁移到 SQLite： - 首次启动自动迁移 - 迁移成功后显示提示 diff --git a/docs/user-manual/5-faq/5.3-deeplink.md b/docs/user-manual/5-faq/5.3-deeplink.md index abb347320..32057e17a 100644 --- a/docs/user-manual/5-faq/5.3-deeplink.md +++ b/docs/user-manual/5-faq/5.3-deeplink.md @@ -26,11 +26,9 @@ CC Switch 提供在线深度链接生成工具： ## 协议格式 -CC Switch 支持两种协议格式： +### V1 协议 -### V1 协议（推荐） - -使用 URL 参数格式，更易读和生成： +使用 URL 参数格式，易读易生成： ``` ccswitch://v1/import?resource={type}&app={app}&name={name}&... @@ -40,155 +38,115 @@ ccswitch://v1/import?resource={type}&app={app}&name={name}&... | 参数 | 必填 | 说明 | |------|------|------| -| `resource` | 是 | 资源类型：`provider` / `mcp` / `prompt` | -| `app` | 是 | 应用类型：`claude` / `codex` / `gemini` | +| `resource` | 是 | 资源类型：`provider` / `mcp` / `prompt` / `skill` | +| `app` | 是 | 应用类型：`claude` / `codex` / `gemini` / `opencode` | | `name` | 是 | 名称 | **供应商参数**（resource=provider）： | 参数 | 必填 | 说明 | |------|------|------| -| `endpoint` | 是 | API 端点地址 | -| `apiKey` | 是 | API 密钥 | +| `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 ``` -### Legacy 协议 - -使用 Base64 编码的 JSON 数据： - -``` -ccswitch://import/{type}?data={base64_encoded_data} -``` - -| 参数 | 说明 | -|------|------| -| `type` | 导入类型：`provider` / `mcp` / `prompt` / `skill` | -| `data` | Base64 编码的配置数据 | - -## 导入类型 +## 导入类型示例 ### 导入供应商 ``` -ccswitch://import/provider?data= -``` - -数据结构： -```json -{ - "name": "供应商名称", - "appId": "claude", - "settingsConfig": { - "env": { - "ANTHROPIC_API_KEY": "sk-xxx", - "ANTHROPIC_BASE_URL": "https://api.example.com" - } - }, - "websiteUrl": "https://example.com", - "icon": "cloud", - "iconColor": "#3b82f6" -} +ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx ``` ### 导入 MCP 服务器 ``` -ccswitch://import/mcp?data= -``` - -数据结构： -```json -{ - "id": "mcp-fetch", - "name": "HTTP Fetch", - "description": "HTTP 请求工具", - "command": "uvx", - "args": ["mcp-server-fetch"], - "transportType": "stdio", - "apps": { - "claude": true, - "codex": true, - "gemini": false - } -} +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://import/prompt?data= -``` - -数据结构： -```json -{ - "name": "代码审查专家", - "content": "# 角色\n\n你是一个专业的代码审查专家...", - "app": "claude" -} +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://import/skill?data= -``` - -数据结构： -```json -{ - "name": "skill-name", - "repoOwner": "owner", - "repoName": "repo", - "repoBranch": "main", - "directory": "skills/skill-name" -} +ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main ``` ## 生成深度链接 ### 手动生成 -1. 准备配置数据（JSON 格式） -2. 将 JSON 转换为 Base64 编码 -3. 拼接成完整 URL +1. 准备参数 +2. 按 V1 协议格式拼接 URL +3. URL 编码特殊字符 **示例**： ```javascript -const config = { - name: "My Provider", - appId: "claude", - settingsConfig: { - env: { - ANTHROPIC_API_KEY: "sk-xxx" - } - } -}; +const params = new URLSearchParams({ + resource: 'provider', + app: 'claude', + name: 'My Provider', + endpoint: 'https://api.example.com', + apiKey: 'sk-xxx' +}); -const base64 = btoa(JSON.stringify(config)); -const url = `ccswitch://import/provider?data=${base64}`; +const url = `ccswitch://v1/import?${params.toString()}`; ``` ### 在线工具 -可以使用在线 Base64 编码工具： -- https://www.base64encode.org/ +使用 CC Switch 官方提供的在线深度链接生成工具更方便。 ## 使用深度链接 @@ -267,26 +225,13 @@ CC Switch 会检查： ### 示例：导入 Claude 供应商 ``` -ccswitch://import/provider?data=eyJuYW1lIjoiVGVzdCBQcm92aWRlciIsImFwcElkIjoiY2xhdWRlIiwic2V0dGluZ3NDb25maWciOnsiZW52Ijp7IkFOVEhST1BJQ19BUElfS0VZIjoic2steHh4In19fQ== -``` - -解码后的数据： -```json -{ - "name": "Test Provider", - "appId": "claude", - "settingsConfig": { - "env": { - "ANTHROPIC_API_KEY": "sk-xxx" - } - } -} +ccswitch://v1/import?resource=provider&app=claude&name=Test%20Provider&apiKey=sk-xxx&endpoint=https%3A%2F%2Fapi.example.com ``` ### 示例：导入 MCP 服务器 ``` -ccswitch://import/mcp?data=eyJpZCI6Im1jcC1mZXRjaCIsIm5hbWUiOiJIVFRQIEZldGNoIiwiY29tbWFuZCI6InV2eCIsImFyZ3MiOlsibWNwLXNlcnZlci1mZXRjaCJdLCJ0cmFuc3BvcnRUeXBlIjoic3RkaW8iLCJhcHBzIjp7ImNsYXVkZSI6dHJ1ZSwiY29kZXgiOnRydWUsImdlbWluaSI6dHJ1ZX19 +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 ``` ## 故障排除 diff --git a/docs/user-manual/README.md b/docs/user-manual/README.md index 163ef70e0..057c292df 100644 --- a/docs/user-manual/README.md +++ b/docs/user-manual/README.md @@ -1,6 +1,6 @@ # CC Switch 用户手册 -> Claude Code / Codex / Gemini CLI 全方位辅助工具 +> Claude Code / Codex / Gemini CLI / OpenCode 全方位辅助工具 ## 目录结构 @@ -99,9 +99,9 @@ ## 版本信息 -- 文档版本：v3.9.1 -- 最后更新：2025-12-30 -- 适用于 CC Switch v3.9.0+ +- 文档版本：v3.10.3 +- 最后更新：2026-02-09 +- 适用于 CC Switch v3.10.0+ ## 贡献