# 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. 确保所有必填字段都存在