change doc

This commit is contained in:
musistudio
2025-12-28 13:43:25 +08:00
parent aa18a354bb
commit bd55450b1d
33 changed files with 4807 additions and 592 deletions

158
examples/README.md Normal file
View File

@@ -0,0 +1,158 @@
# 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)

View File

@@ -0,0 +1,246 @@
{
"metadata": {
"name": "multi-provider-preset",
"version": "1.0.0",
"description": "示例预设支持多provider选择和动态配置",
"author": "CCR Team",
"keywords": ["example", "multi-provider", "dynamic"],
"ccrVersion": "2.0.0"
},
"schema": [
{
"id": "providerChoice",
"type": "select",
"label": "选择Provider",
"prompt": "请选择要使用的LLM提供商",
"options": {
"type": "static",
"options": [
{
"label": "OpenAI",
"value": "openai",
"description": "使用OpenAI的GPT模型"
},
{
"label": "DeepSeek",
"value": "deepseek",
"description": "使用DeepSeek的高性价比模型"
},
{
"label": "Gemini",
"value": "gemini",
"description": "使用Google的Gemini模型"
}
]
},
"required": true,
"defaultValue": "openai"
},
{
"id": "apiKey",
"type": "password",
"label": "API Key",
"prompt": "请输入您的API Key",
"placeholder": "sk-...",
"required": true,
"when": {
"field": "providerChoice",
"operator": "exists"
}
},
{
"id": "baseUrl",
"type": "input",
"label": "Base URL可选",
"prompt": "自定义API Base URL留空使用默认值",
"required": false,
"when": {
"field": "providerChoice",
"operator": "exists"
}
},
{
"id": "modelChoice",
"type": "select",
"label": "选择模型",
"prompt": "请选择要使用的模型",
"options": {
"type": "static",
"options": [
{
"label": "GPT-4o",
"value": "gpt-4o"
},
{
"label": "GPT-4o-mini",
"value": "gpt-4o-mini"
},
{
"label": "GPT-3.5-turbo",
"value": "gpt-3.5-turbo"
}
]
},
"required": true,
"when": {
"field": "providerChoice",
"operator": "eq",
"value": "openai"
},
"defaultValue": "gpt-4o"
},
{
"id": "deepseekModelChoice",
"type": "select",
"label": "选择模型",
"prompt": "请选择要使用的DeepSeek模型",
"options": {
"type": "static",
"options": [
{
"label": "DeepSeek-V3",
"value": "deepseek-v3"
},
{
"label": "DeepSeek-Chat",
"value": "deepseek-chat"
}
]
},
"required": true,
"when": {
"field": "providerChoice",
"operator": "eq",
"value": "deepseek"
},
"defaultValue": "deepseek-v3"
},
{
"id": "useProxy",
"type": "confirm",
"label": "使用代理",
"prompt": "是否通过代理访问API",
"defaultValue": false
},
{
"id": "proxyUrl",
"type": "input",
"label": "代理URL",
"prompt": "请输入代理地址http://127.0.0.1:7890",
"placeholder": "http://127.0.0.1:7890",
"required": true,
"when": {
"field": "useProxy",
"operator": "eq",
"value": true
}
},
{
"id": "maxTokens",
"type": "number",
"label": "最大Token数",
"prompt": "设置单次请求的最大token数量",
"min": 100,
"max": 128000,
"defaultValue": 4096,
"required": false
},
{
"id": "advancedSettings",
"type": "confirm",
"label": "高级设置",
"prompt": "是否配置高级选项?",
"defaultValue": false
},
{
"id": "temperature",
"type": "number",
"label": "Temperature",
"prompt": "控制生成随机性0-2",
"min": 0,
"max": 2,
"defaultValue": 0.7,
"required": false,
"when": {
"field": "advancedSettings",
"operator": "eq",
"value": true
}
},
{
"id": "features",
"type": "multiselect",
"label": "启用功能",
"prompt": "选择要启用的功能",
"options": {
"type": "static",
"options": [
{
"label": "流式输出",
"value": "stream"
},
{
"label": "工具调用",
"value": "tools"
},
{
"label": "长上下文支持",
"value": "longContext"
}
]
},
"defaultValue": ["stream"],
"required": false
}
],
"template": {
"Providers": [
{
"name": "{{providerChoice}}",
"api_base_url": "{{baseUrl}}",
"api_key": "{{apiKey}}",
"models": ["{{modelChoice}}", "{{deepseekModelChoice}}"]
}
],
"Router": {
"default": "{{providerChoice}}/{{modelChoice}}{{deepseekModelChoice}}"
},
"PROXY_URL": "{{proxyUrl}}",
"API_TIMEOUT_MS": 60000
},
"configMappings": [
{
"target": "Providers[0].name",
"value": "{{providerChoice}}"
},
{
"target": "Providers[0].api_key",
"value": "{{apiKey}}"
},
{
"target": "Providers[0].api_base_url",
"value": "{{baseUrl}}",
"when": {
"field": "baseUrl",
"operator": "exists"
}
},
{
"target": "Router.default",
"value": "{{providerChoice}}/{{modelChoice}}{{deepseekModelChoice}}"
},
{
"target": "PROXY_URL",
"value": "{{proxyUrl}}",
"when": {
"field": "useProxy",
"operator": "eq",
"value": true
}
},
{
"target": "API_TIMEOUT_MS",
"value": 60000
}
]
}

View File

@@ -0,0 +1,268 @@
{
"name": "multi-provider-example",
"version": "1.0.0",
"description": "多Provider配置示例 - 支持OpenAI和DeepSeek切换",
"author": "CCR Team",
"keywords": ["openai", "deepseek", "multi-provider"],
"ccrVersion": "2.0.0",
"Providers": [
{
"name": "openai",
"api_base_url": "https://api.openai.com/v1",
"models": ["gpt-4o", "gpt-4o-mini", "gpt-3.5-turbo"]
},
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com",
"models": ["deepseek-v3", "deepseek-chat"]
}
],
"schema": [
{
"id": "primaryProvider",
"type": "select",
"label": "主要Provider",
"prompt": "选择您主要使用的LLM提供商",
"options": {
"type": "providers"
},
"required": true,
"defaultValue": "openai"
},
{
"id": "apiKey",
"type": "password",
"label": "API Key",
"prompt": "请输入您的API Key将从环境变量或安全存储中读取",
"placeholder": "sk-...",
"required": true,
"when": {
"field": "primaryProvider",
"operator": "exists"
}
},
{
"id": "customBaseUrl",
"type": "input",
"label": "自定义Base URL",
"prompt": "如果使用代理或自定义端点请输入Base URL留空使用默认值",
"placeholder": "https://api.openai.com/v1",
"required": false,
"when": {
"field": "primaryProvider",
"operator": "exists"
}
},
{
"id": "defaultModel",
"type": "select",
"label": "默认模型",
"prompt": "选择默认使用的模型",
"options": {
"type": "models",
"providerField": "{{primaryProvider}}"
},
"required": true,
"defaultValue": "gpt-4o",
"when": {
"field": "primaryProvider",
"operator": "eq",
"value": "openai"
}
},
{
"id": "backgroundModel",
"type": "select",
"label": "后台任务模型",
"prompt": "用于后台任务的轻量级模型",
"options": {
"type": "models",
"providerField": "{{primaryProvider}}"
},
"required": false,
"when": {
"field": "primaryProvider",
"operator": "exists"
}
},
{
"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
}
},
{
"id": "maxTokens",
"type": "number",
"label": "最大Token数",
"prompt": "设置单次请求的最大token数量",
"min": 100,
"max": 128000,
"defaultValue": 4096,
"required": false
},
{
"id": "timeout",
"type": "number",
"label": "请求超时(秒)",
"prompt": "API请求超时时间",
"min": 10,
"max": 300,
"defaultValue": 60,
"required": false
},
{
"id": "enableFeatures",
"type": "multiselect",
"label": "启用功能",
"prompt": "选择要启用的功能",
"options": {
"type": "static",
"options": [
{
"label": "流式输出",
"value": "stream",
"description": "实时显示AI响应"
},
{
"label": "工具调用",
"value": "tools",
"description": "启用Function Calling功能"
},
{
"label": "长上下文",
"value": "longContext",
"description": "支持长文本处理"
},
{
"label": "思维链",
"value": "think",
"description": "在思考模式中使用"
}
]
},
"defaultValue": ["stream", "tools"],
"required": false
},
{
"id": "advancedMode",
"type": "confirm",
"label": "高级模式",
"prompt": "启用高级配置选项?",
"defaultValue": false
},
{
"id": "temperature",
"type": "number",
"label": "Temperature",
"prompt": "控制生成随机性0-2值越高越随机",
"min": 0,
"max": 2,
"defaultValue": 0.7,
"required": false,
"when": {
"field": "advancedMode",
"operator": "eq",
"value": true
}
},
{
"id": "logLevel",
"type": "select",
"label": "日志级别",
"prompt": "设置详细的日志级别",
"options": {
"type": "static",
"options": [
{
"label": "错误",
"value": "error"
},
{
"label": "警告",
"value": "warn"
},
{
"label": "信息",
"value": "info"
},
{
"label": "调试",
"value": "debug"
}
]
},
"defaultValue": "info",
"required": false,
"when": {
"field": "advancedMode",
"operator": "eq",
"value": true
}
}
],
"template": {
"Providers": [
{
"name": "{{primaryProvider}}",
"api_base_url": "{{customBaseUrl}}",
"api_key": "{{apiKey}}",
"models": ["{{defaultModel}}", "{{backgroundModel}}"]
}
],
"Router": {
"default": "{{primaryProvider}}/{{defaultModel}}",
"background": "{{backgroundModel}}",
"think": "{{primaryProvider}}/{{defaultModel}}"
},
"PROXY_URL": "{{proxyUrl}}",
"API_TIMEOUT_MS": 60000,
"LOG_LEVEL": "info"
},
"configMappings": [
{
"target": "Providers[0].api_base_url",
"value": "{{customBaseUrl}}",
"when": {
"field": "customBaseUrl",
"operator": "exists"
}
},
{
"target": "PROXY_URL",
"value": "{{proxyUrl}}",
"when": {
"field": "enableProxy",
"operator": "eq",
"value": true
}
},
{
"target": "API_TIMEOUT_MS",
"value": 60000
},
{
"target": "LOG_LEVEL",
"value": "{{logLevel}}",
"when": {
"field": "advancedMode",
"operator": "eq",
"value": true
}
}
]
}

View File

@@ -0,0 +1,87 @@
{
"name": "simple-openai-preset",
"version": "1.0.0",
"description": "简单的OpenAI配置预设",
"author": "Your Name",
"keywords": ["openai", "simple"],
"schema": [
{
"id": "apiKey",
"type": "password",
"label": "OpenAI API Key",
"prompt": "请输入您的OpenAI API Key",
"placeholder": "sk-...",
"required": true
},
{
"id": "model",
"type": "select",
"label": "选择模型",
"prompt": "选择要使用的GPT模型",
"options": {
"type": "static",
"options": [
{
"label": "GPT-4o (推荐)",
"value": "gpt-4o"
},
{
"label": "GPT-4o-mini (快速)",
"value": "gpt-4o-mini"
},
{
"label": "GPT-3.5 Turbo (经济)",
"value": "gpt-3.5-turbo"
}
]
},
"required": true,
"defaultValue": "gpt-4o"
},
{
"id": "useProxy",
"type": "confirm",
"label": "使用代理",
"prompt": "是否需要通过代理访问OpenAI API",
"defaultValue": false
},
{
"id": "proxyUrl",
"type": "input",
"label": "代理地址",
"prompt": "请输入代理地址",
"placeholder": "http://127.0.0.1:7890",
"required": true,
"when": {
"field": "useProxy",
"operator": "eq",
"value": true
}
}
],
"template": {
"Providers": [
{
"name": "openai",
"api_base_url": "https://api.openai.com/v1",
"api_key": "{{apiKey}}",
"models": ["{{model}}"]
}
],
"Router": {
"default": "openai/{{model}}"
},
"PROXY_URL": "{{proxyUrl}}"
},
"configMappings": [
{
"target": "PROXY_URL",
"value": "{{proxyUrl}}",
"when": {
"field": "useProxy",
"operator": "eq",
"value": true
}
}
]
}