mirror of
https://github.com/musistudio/claude-code-router.git
synced 2026-01-30 06:12:06 +00:00
159 lines
3.9 KiB
Markdown
159 lines
3.9 KiB
Markdown
# Preset 示例说明
|
||
|
||
本目录包含 CCR 预设配置的示例文件。
|
||
|
||
## 示例文件
|
||
|
||
### 1. `simple-preset-example.json` - 简单示例
|
||
适合初学者，展示了基本的动态配置功能：
|
||
- 密码输入（API Key）
|
||
- 单选下拉框（选择模型）
|
||
- 确认框（是否使用代理）
|
||
- 条件显示（只有选择使用代理时才显示代理地址输入）
|
||
|
||
**使用场景**：快速配置单个 Provider
|
||
|
||
### 2. `preset-manifest-example.json` - 完整示例
|
||
展示了所有高级功能：
|
||
- 多种输入类型（password, select, confirm, number, multiselect）
|
||
- 动态选项（从 Providers 配置中提取）
|
||
- 复杂条件逻辑（when 条件）
|
||
- 模板变量替换（{{variable}}）
|
||
- 配置映射（configMappings）
|
||
|
||
**使用场景**：生产环境的完整配置
|
||
|
||
### 3. `dynamic-preset-example.json` - 多Provider示例
|
||
展示了如何在多个 Provider 之间切换：
|
||
- Provider 选择器
|
||
- 根据选择的 Provider 动态显示对应的模型选项
|
||
- 代理配置
|
||
- 高级功能开关
|
||
|
||
## 如何使用这些示例
|
||
|
||
### 方法1：直接复制到预设目录
|
||
|
||
```bash
|
||
# 创建预设目录
|
||
mkdir -p ~/.claude-code-router/presets/my-preset
|
||
|
||
# 复制示例文件
|
||
cp simple-preset-example.json ~/.claude-code-router/presets/my-preset/manifest.json
|
||
|
||
# 应用预设
|
||
ccr my-preset
|
||
```
|
||
|
||
### 方法2：修改后使用
|
||
|
||
1. 复制示例文件到本地
|
||
2. 根据需要修改配置
|
||
3. 使用 CLI 安装：
|
||
|
||
```bash
|
||
ccr preset install ./simple-preset-example.json --name my-preset
|
||
```
|
||
|
||
## Schema 字段类型说明
|
||
|
||
| 类型 | 说明 | 适用场景 |
|
||
|------|------|----------|
|
||
| `password` | 密码输入 | API Key、密钥等敏感信息 |
|
||
| `input` | 单行文本 | Base URL、端点地址 |
|
||
| `number` | 数字输入 | 超时时间、Token数量 |
|
||
| `select` | 单选 | Provider选择、模型选择 |
|
||
| `multiselect` | 多选 | 功能开关、标签选择 |
|
||
| `confirm` | 确认框 | 是否启用某功能 |
|
||
| `editor` | 多行文本 | 自定义配置、脚本 |
|
||
|
||
## 条件运算符
|
||
|
||
| 运算符 | 说明 | 示例 |
|
||
|--------|------|------|
|
||
| `eq` | 等于 | 当 provider == "openai" 时显示 |
|
||
| `ne` | 不等于 | 当 mode != "simple" 时显示 |
|
||
| `exists` | 字段存在 | 当 apiKey 有值时显示 |
|
||
| `gt/lt` | 大于/小于 | 当 timeout > 30 时显示 |
|
||
|
||
## 动态选项类型
|
||
|
||
### 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
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
1. **提供默认值**：为非必填项设置合理的 `defaultValue`
|
||
2. **清晰的标签**：使用用户友好的 `label` 和 `prompt`
|
||
3. **条件显示**：使用 `when` 避免显示无关选项
|
||
4. **输入验证**：使用 `validator` 或 `min/max` 确保输入有效
|
||
5. **分组配置**：相关字段使用相同的前缀（如 `proxy*`）
|
||
6. **版本管理**：在 metadata 中记录版本和变更
|
||
|
||
## 更多帮助
|
||
|
||
- 查看完整文档：[Presets 配置指南](../docs/docs/server/advanced/presets.md)
|
||
- 查看类型定义：[types.ts](../packages/shared/src/preset/types.ts)
|