mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-22 17:11:04 +08:00
docs: restructure user manual for i18n and add EN/JA translations
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.
This commit is contained in:
Jason
340
docs/user-manual/zh/5-faq/5.1-config-files.md
Normal file
340
docs/user-manual/zh/5-faq/5.1-config-files.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# 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,
|
||||
"openclawConfigDir": 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/ # 技能目录
|
||||
└── ...
|
||||
```
|
||||
|
||||
## OpenClaw 配置
|
||||
|
||||
### 配置目录
|
||||
|
||||
默认：`~/.openclaw/`
|
||||
|
||||
### 主要文件
|
||||
|
||||
```
|
||||
~/.openclaw/
|
||||
├── openclaw.json # 主配置文件（JSON5 格式）
|
||||
├── AGENTS.md # 系统提示词
|
||||
└── skills/ # 技能目录
|
||||
└── ...
|
||||
```
|
||||
|
||||
### openclaw.json
|
||||
|
||||
OpenClaw 使用 JSON5 格式配置文件，主要包含以下部分：
|
||||
|
||||
```json5
|
||||
{
|
||||
// 模型供应商配置
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
"custom-provider": {
|
||||
baseUrl: "https://api.example.com/v1",
|
||||
apiKey: "your-api-key",
|
||||
api: "openai-completions",
|
||||
models: [{ id: "model-id", name: "Model Name" }]
|
||||
}
|
||||
}
|
||||
},
|
||||
// 环境变量
|
||||
env: {
|
||||
ANTHROPIC_API_KEY: "sk-..."
|
||||
},
|
||||
// Agent 默认模型配置
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "provider/model"
|
||||
}
|
||||
}
|
||||
},
|
||||
// 工具配置
|
||||
tools: {},
|
||||
// 工作区文件配置
|
||||
workspace: {}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `models.providers` | 供应商配置（映射为 CC Switch 的"供应商"） |
|
||||
| `env` | 环境变量配置 |
|
||||
| `agents.defaults` | Agent 默认模型设置 |
|
||||
| `tools` | 工具配置 |
|
||||
| `workspace` | 工作区文件管理 |
|
||||
|
||||
## 配置优先级
|
||||
|
||||
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 预设
|
||||
- 应用设置
|
||||
|
||||
### 不包含的内容
|
||||
|
||||
- 用量日志（数据量大）
|
||||
- 设备级设置（不适合跨设备）
|
||||
220
docs/user-manual/zh/5-faq/5.2-questions.md
Normal file
220
docs/user-manual/zh/5-faq/5.2-questions.md
Normal file
@@ -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\`
|
||||
256
docs/user-manual/zh/5-faq/5.3-deeplink.md
Normal file
256
docs/user-manual/zh/5-faq/5.3-deeplink.md
Normal file
@@ -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` / `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. 确保所有必填字段都存在
|
||||
108
docs/user-manual/zh/5-faq/5.4-env-conflict.md
Normal file
108
docs/user-manual/zh/5-faq/5.4-env-conflict.md
Normal file
@@ -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. 手动恢复变量到系统环境
|
||||
Reference in New Issue
Block a user