admin/CC-Switch
1
0
Fork 0
mirror of https://github.com/farion1231/cc-switch.git synced 2026-08-01 04:02:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): align user manual with v3.10.3 codebase

Browse Source 
- 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
This commit is contained in:
Jason
2026-02-09 14:57:57 +08:00
parent 11cc4e815b
commit e612410deb
14 changed files with 219 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-manual/5-faq/5.1-config-files.md
+26 -5
View File
@@ -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：
- 首次启动自动迁移
- 迁移成功后显示提示
docs/user-manual/5-faq/5.3-deeplink.md
+56 -111
View File
@@ -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=<base64>
```
数据结构：
```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=<base64>
```
数据结构：
```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=<base64>
```
数据结构：
```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=<base64>
```
数据结构：
```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
```
## 故障排除