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：直接复制到预设目录

# 创建预设目录
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 安装：

ccr preset install ./simple-preset-example.json --name my-preset

Schema 字段类型说明

条件运算符

动态选项类型

static - 静态选项

"options": {
  "type": "static",
  "options": [
    {"label": "选项1", "value": "value1"},
    {"label": "选项2", "value": "value2"}
  ]
}

providers - 从 Providers 配置提取

"options": {
  "type": "providers"
}

自动从 Providers 数组中提取 name 作为选项。

models - 从指定 Provider 的 models 提取

"options": {
  "type": "models",
  "providerField": "{{selectedProvider}}"
}

根据用户选择的 Provider，动态显示该 Provider 的 models。

模板变量

使用 {{变量名}} 语法在 template 中引用用户输入：

"template": {
  "Providers": [
    {
      "name": "{{providerName}}",
      "api_key": "{{apiKey}}"
    }
  ]
}

配置映射

对于复杂的配置需求，使用 configMappings 精确控制值的位置：

"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 配置指南
• 查看类型定义：types.ts