mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-22 08:59:45 +08:00
bbed2a1fe1
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
257 lines
6.1 KiB
Markdown
257 lines
6.1 KiB
Markdown
# 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` / `openclaw` |
|
||
| `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,opencode`） |
|
||
| `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. 确保所有必填字段都存在
|