# 配置参考

[English](./configuration.md)

所有策略在**设置 → 模型中枢**中配置。模型提供方本身只在 DSH 官方**模型**页面配置；本页只管理路由策略和媒体通道。修改实时生效，并写入 `model-router` 设置命名空间。

## 顶层字段

| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `schemaVersion` | number | `2` | V2 标记，用户确认保存后才持久化 |
| `enabled` | boolean | `true` | 总开关；关闭后不执行规则、不注册工具、不写会话 |
| `matchCase` | boolean | `false` | 关键词是否区分大小写 |
| `rules` | array | `[]` | 有序关键词规则，首次命中即停 |
| `agentSwitch` | object | 关闭、空白名单 | 受控手动切换工具 |
| `mediaProviders` | array | `[]` | 隔离媒体通道，目前只实现 `image_gen` |

## 路由规则

每条规则需要唯一 `id`、启用状态、非空关键词和目标 `provider/model`；`reasoningEffort` 是适配器拥有的可选字符串。规则命中后先通过 DSH 原生目录进行精确校验，再写入会话 `request/header`。校验失败或未命中都不修改会话，默认模型仍由 DSH 管理。

## `agentSwitch`

只有 `enabled: true` 且 `allow` 非空时，才注册 `model_route`。工具只能看到并使用白名单中的精确 provider、model 和 effort 组合，每次执行仍会进行实时校验。

## 媒体通道

| 字段 | 必填 | 说明 |
|---|---|---|
| `id` | 是 | 唯一通道 ID，格式为 `[a-z0-9][a-z0-9._-]*` |
| `name` | 是 | 显示名称 |
| `capabilities` | 是 | 当前只支持 `image_gen` |
| `adapter` | 是 | 当前只支持 `openai-images` |
| `baseUrl` | 是 | OpenAI 兼容 HTTPS 端点；只有 `localhost`、`127.0.0.0/8` 和 `::1` 可使用 HTTP；不得包含用户名、密码、查询参数或锚点 |
| `credential` | 否 | DSH Credential 引用名；留空表示无认证，不发送 Authorization |
| `models` | 是 | 至少一个模型，第一个为默认 |
| `allowedResultHosts` | 否 | 除端点域名外允许下载结果的裸主机名 |
| `priceTier` | 否 | 自由填写的成本说明 |
| `defaultSize` | 否 | 工具没有指定时使用的默认图片尺寸 |

## 生图安全边界

- 提供方请求默认必须使用 HTTPS，本机回环开发地址可使用 HTTP；
- 结果下载只允许 HTTPS、默认端口、端点域名和明确白名单域名；
- 最多跟随三次重定向，每次重新校验；
- 拒绝解析到私网或保留地址，并固定已校验 DNS 结果；
- 图片上限 20 MiB，请求和下载都有超时；
- 只接受 PNG、JPEG、WebP 和 GIF 文件魔数；
- 预览必须位于受管理目录真实路径内，只允许普通图片文件。

## V1 到 V2 迁移

旧设置只在内存中迁移并显示告警，启动时不会自动写回。用户在页面保存后才写入 `schemaVersion: 2` 并删除旧字段。旧媒体通道中 `image_gen` 可以迁移；文字、视觉聊天、fallback 和旧插件 provider ID 需要人工处理，不会静默映射。

## V2 示例

```yaml
model-router:
  schemaVersion: 2
  enabled: true
  matchCase: false
  rules:
    - id: summary-rule
      enabled: true
      keywords: [汇总, summary]
      target:
        provider: deepseek-official
        model: deepseek-v4-flash
  agentSwitch:
    enabled: false
    allow: []
  mediaProviders:
    - id: volcengine-seedream
      name: 豆包 Seedream 5.0 Lite
      capabilities: [image_gen]
      adapter: openai-images
      baseUrl: https://ark.cn-beijing.volces.com/api/v3
      credential: VOLCENGINE_ARK_API_KEY
      models: [doubao-seedream-5-0-lite-260128]
      allowedResultHosts:
        - ark-acg-cn-beijing.tos-cn-beijing.volces.com
      defaultSize: 1920x1920
```

## 恢复旧版本

升级前先在本机备份 DSH 设置。需要恢复时，停止保存设置，恢复迁移前备份，通过已发布 tag 或 `git log` 中确认过的提交检出旧代码，重新安装插件并重启 Web。不要把设置文件附到公开 Issue，因为其中可能包含凭据引用和私有提供方信息。