mirror of
https://github.com/musistudio/claude-code-router.git
synced 2026-02-19 15:10:49 +08:00
change doc
This commit is contained in:
musistudio
@@ -12,6 +12,216 @@ sidebar_position: 3
|
||||
|
||||
预设是预配置的设置，包括针对特定用例优化的提供商配置、路由规则和转换器。
|
||||
|
||||
## 动态配置系统 (v2.0+)
|
||||
|
||||
CCR 2.0 引入了强大的动态配置系统，支持：
|
||||
|
||||
- **多种输入类型**：选择器、多选、确认框、文本输入、数字输入等
|
||||
- **条件逻辑**：根据用户输入动态显示/隐藏配置项
|
||||
- **变量引用**：配置项之间可以互相引用
|
||||
- **动态选项**：选项列表可以从预设配置或用户输入中动态生成
|
||||
|
||||
### Schema 字段类型
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `password` | 密码输入（隐藏显示） | API Key |
|
||||
| `input` | 单行文本输入 | Base URL |
|
||||
| `number` | 数字输入 | 最大Token数 |
|
||||
| `select` | 单选下拉框 | 选择Provider |
|
||||
| `multiselect` | 多选框 | 启用功能 |
|
||||
| `confirm` | 确认框 | 是否使用代理 |
|
||||
| `editor` | 多行文本编辑器 | 自定义配置 |
|
||||
|
||||
### 条件运算符
|
||||
|
||||
| 运算符 | 说明 | 示例 |
|
||||
|--------|------|------|
|
||||
| `eq` | 等于 | `{"field": "provider", "operator": "eq", "value": "openai"}` |
|
||||
| `ne` | 不等于 | `{"field": "advanced", "operator": "ne", "value": true}` |
|
||||
| `in` | 包含于 | `{"field": "feature", "operator": "in", "value": ["a", "b"]}` |
|
||||
| `nin` | 不包含于 | `{"field": "type", "operator": "nin", "value": ["x", "y"]}` |
|
||||
| `exists` | 字段存在 | `{"field": "apiKey", "operator": "exists"}` |
|
||||
| `gt/lt/gte/lte` | 大于/小于/大于等于/小于等于 | 用于数字比较 |
|
||||
|
||||
### 动态选项类型
|
||||
|
||||
#### static - 静态选项
|
||||
```json
|
||||
"options": {
|
||||
"type": "static",
|
||||
"options": [
|
||||
{"label": "选项1", "value": "value1"},
|
||||
{"label": "选项2", "value": "value2"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### providers - 从 Providers 配置提取
|
||||
```json
|
||||
"options": {
|
||||
"type": "providers"
|
||||
}
|
||||
```
|
||||
自动从 `Providers` 数组中提取 name 作为选项。
|
||||
|
||||
#### models - 从指定 Provider 的 models 提取
|
||||
```json
|
||||
"options": {
|
||||
"type": "models",
|
||||
"providerField": "{{selectedProvider}}"
|
||||
}
|
||||
```
|
||||
根据用户选择的 Provider，动态显示该 Provider 的 models。
|
||||
|
||||
### 模板变量
|
||||
|
||||
使用 `{{变量名}}` 语法在 template 中引用用户输入：
|
||||
|
||||
```json
|
||||
"template": {
|
||||
"Providers": [
|
||||
{
|
||||
"name": "{{providerName}}",
|
||||
"api_key": "{{apiKey}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 配置映射
|
||||
|
||||
对于复杂的配置需求，使用 `configMappings` 精确控制值的位置：
|
||||
|
||||
```json
|
||||
"configMappings": [
|
||||
{
|
||||
"target": "Providers[0].api_key",
|
||||
"value": "{{apiKey}}"
|
||||
},
|
||||
{
|
||||
"target": "PROXY_URL",
|
||||
"value": "{{proxyUrl}}",
|
||||
"when": {
|
||||
"field": "useProxy",
|
||||
"operator": "eq",
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 完整示例
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "multi-provider-example",
|
||||
"version": "1.0.0",
|
||||
"description": "多Provider配置示例 - 支持OpenAI和DeepSeek切换",
|
||||
"author": "CCR Team",
|
||||
"keywords": ["openai", "deepseek", "multi-provider"],
|
||||
"ccrVersion": "2.0.0",
|
||||
"schema": [
|
||||
{
|
||||
"id": "primaryProvider",
|
||||
"type": "select",
|
||||
"label": "主要Provider",
|
||||
"prompt": "选择您主要使用的LLM提供商",
|
||||
"options": {
|
||||
"type": "static",
|
||||
"options": [
|
||||
{
|
||||
"label": "OpenAI",
|
||||
"value": "openai",
|
||||
"description": "使用OpenAI的GPT模型"
|
||||
},
|
||||
{
|
||||
"label": "DeepSeek",
|
||||
"value": "deepseek",
|
||||
"description": "使用DeepSeek的高性价比模型"
|
||||
}
|
||||
]
|
||||
},
|
||||
"required": true,
|
||||
"defaultValue": "openai"
|
||||
},
|
||||
{
|
||||
"id": "apiKey",
|
||||
"type": "password",
|
||||
"label": "API Key",
|
||||
"prompt": "请输入您的API Key",
|
||||
"placeholder": "sk-...",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"id": "defaultModel",
|
||||
"type": "select",
|
||||
"label": "默认模型",
|
||||
"prompt": "选择默认使用的模型",
|
||||
"options": {
|
||||
"type": "static",
|
||||
"options": [
|
||||
{"label": "GPT-4o", "value": "gpt-4o"},
|
||||
{"label": "GPT-4o-mini", "value": "gpt-4o-mini"}
|
||||
]
|
||||
},
|
||||
"required": true,
|
||||
"defaultValue": "gpt-4o",
|
||||
"when": {
|
||||
"field": "primaryProvider",
|
||||
"operator": "eq",
|
||||
"value": "openai"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "enableProxy",
|
||||
"type": "confirm",
|
||||
"label": "启用代理",
|
||||
"prompt": "是否通过代理访问API？",
|
||||
"defaultValue": false
|
||||
},
|
||||
{
|
||||
"id": "proxyUrl",
|
||||
"type": "input",
|
||||
"label": "代理地址",
|
||||
"prompt": "输入代理服务器地址",
|
||||
"placeholder": "http://127.0.0.1:7890",
|
||||
"required": true,
|
||||
"when": {
|
||||
"field": "enableProxy",
|
||||
"operator": "eq",
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
],
|
||||
"template": {
|
||||
"Providers": [
|
||||
{
|
||||
"name": "{{primaryProvider}}",
|
||||
"api_base_url": "https://api.openai.com/v1",
|
||||
"api_key": "{{apiKey}}",
|
||||
"models": ["{{defaultModel}}"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "{{primaryProvider}}/{{defaultModel}}"
|
||||
},
|
||||
"PROXY_URL": "{{proxyUrl}}"
|
||||
},
|
||||
"configMappings": [
|
||||
{
|
||||
"target": "PROXY_URL",
|
||||
"value": "{{proxyUrl}}",
|
||||
"when": {
|
||||
"field": "enableProxy",
|
||||
"operator": "eq",
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 可用预设
|
||||
|
||||
### Development（开发）
|
||||
@@ -66,7 +276,42 @@ ccr preset list
|
||||
|
||||
## 创建自定义预设
|
||||
|
||||
您可以通过保存配置并稍后重新加载来创建自定义预设：
|
||||
创建包含 `schema` 和 `template` 的预设文件：
|
||||
|
||||
```bash
|
||||
# 创建预设目录
|
||||
mkdir -p ~/.claude-code-router/presets/my-preset
|
||||
|
||||
# 创建 manifest.json
|
||||
cat > ~/.claude-code-router/presets/my-preset/manifest.json << 'EOF'
|
||||
{
|
||||
"name": "my-preset",
|
||||
"version": "1.0.0",
|
||||
"description": "我的自定义预设",
|
||||
"schema": [
|
||||
{
|
||||
"id": "apiKey",
|
||||
"type": "password",
|
||||
"label": "API Key",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"template": {
|
||||
"Providers": [
|
||||
{
|
||||
"name": "my-provider",
|
||||
"api_key": "{{apiKey}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
# 应用预设（会提示输入API Key）
|
||||
ccr my-preset
|
||||
```
|
||||
|
||||
您也可以通过保存配置并稍后重新加载来创建自定义预设：
|
||||
|
||||
```bash
|
||||
# 将当前配置保存为预设
|
||||
@@ -116,35 +361,7 @@ ccr preset delete <预设名称>
|
||||
~/.claude-code-router/presets/
|
||||
```
|
||||
|
||||
每个预设都是一个 JSON 文件，包含完整的配置。
|
||||
|
||||
## 预设文件示例
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "development",
|
||||
"description": "针对软件开发优化的配置",
|
||||
"Providers": [
|
||||
{
|
||||
"name": "deepseek",
|
||||
"api_base_url": "https://api.deepseek.com/chat/completions",
|
||||
"api_key": "$DEEPSEEK_API_KEY",
|
||||
"models": ["deepseek-chat", "deepseek-coder"]
|
||||
},
|
||||
{
|
||||
"name": "groq",
|
||||
"api_base_url": "https://api.groq.com/openai/v1/chat/completions",
|
||||
"api_key": "$GROQ_API_KEY",
|
||||
"models": ["llama-3.3-70b-versatile"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "deepseek,deepseek-chat",
|
||||
"background": "groq,llama-3.3-70b-versatile",
|
||||
"think": "deepseek,deepseek-chat"
|
||||
}
|
||||
}
|
||||
```
|
||||
每个预设都是一个目录，包含 `manifest.json` 文件。
|
||||
|
||||
## 导出和导入预设
|
||||
|
||||
@@ -163,10 +380,13 @@ ccr config edit
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **为不同项目创建预设**：为不同的工作流程创建专门的预设
|
||||
2. **版本控制**：将常用预设保存在版本控制中
|
||||
3. **文档化**：为自定义预设添加描述
|
||||
4. **测试**：在应用预设后验证配置
|
||||
1. **使用动态配置**：为需要用户输入的配置项使用schema系统
|
||||
2. **提供默认值**：为非必填项提供合理的默认值
|
||||
3. **条件显示**：使用when条件避免不必要的输入
|
||||
4. **清晰的标签**：为每个字段提供清晰的label和prompt
|
||||
5. **验证输入**：使用validator确保输入的有效性
|
||||
6. **版本控制**：将常用预设保存在版本控制中
|
||||
7. **文档化**：为自定义预设添加描述和版本信息
|
||||
|
||||
## 下一步
|
||||
|
||||
|
||||
Reference in New Issue
Block a user