change doc

examples/README.md

@@ -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)