# 功能模型池与调用方式

本文对应 Iris 0.2.7，功能从 0.2.6 起提供；发布状态见 [README](../README.md)。0.2.4/0.2.5 使用 [严格功能名单](FUNCTION_MODEL_ASSIGNMENTS.md)；升级不会自动启用自动池。

## 配好一次即可使用

在工作台添加媒体供应商，或 [引用 DSH 已有连接](DSH_PROVIDER_CONNECTIONS.md)，选择实际支持的媒体协议。在供应商详情填写模型名，勾选它可用于哪些功能，点击“保存模型用途”。

首次配置会推荐勾选“同时启用所选功能的自动池”。保存后，已确认的模型直接进入这些功能的候选，不需要再逐项添加到功能名单。已有配置不会自动改为此模式；启用框会明确说明它会替换所选功能的调用方式。仅保存用途不发起实测或生成，也不代表上游已验证可用。

供应商详情的“模型目录”默认折叠，点击“同步目录”读取最新列表；发现的新条目显示“待确认用途”，确认后才会加入自动池。名称和 DSH 文字连接不证明媒体能力。Music 还需明确绑定 `musicProtocol: gemini-web-music`。

## 目录更新与候选可用性

新自动请求开始前按需检查供应商目录，成功结果缓存 10 分钟，同连接并发读取合并；也可在工作台主动同步。同步只读取目录，不发起模型实测或生成。配置检查、手选请求、停用功能与旧任务查询不会暗中刷新目录。同步失败保留上次完整目录及错误原因，短暂退避 30 秒；坏响应或不完整分页不会覆盖快照。

目录展示同步时间、新条目与“目录未列出”的已配置模型。未列出本身不能证明下线：手工模型、用途和顺序继续保留，新模型仍需确认。混合视频/音频输出不自动获得 TTS 用途，音频理解也不自动获得文件转写用途；可信的明确能力代码优先。

当当前连接在新提交或实测中明确返回模型不存在（模型专属错误码，或精确的 `404 Model not exist.`）时，仅隔离该连接的模型及能力，后续请求跳过它。通用路径 404、参数 400、认证错误、限流与网络错误不按模型消失处理。历史成功保留，可用性单独显示；目录重新列出不自动解除隔离。改变连接或有效图片协议后重新判断，也可在核对目录后单独确认费用进行实测，成功恢复。旧任务的查询、观察与交付仍沿用原绑定，不解除或新增此类阻断。

DSH、Agent 和独立 CLI 共用规则。媒体的候选切换仍遵守受理边界；视觉保留已有操作停止规则，本次已发出的明确模型 404 会隔离后续请求，不因此扩张同一操作的切换条件。当前没有后台定时器、自动付费探针、按目录自动删除模型或自动授权新模型。

## 每个功能有三种调用方式

| 方式 | 候选范围 | 没有合格候选时 |
|---|---|---|
| 自动池 | 已确认用途、连接启用且协议支持的同功能模型，按供应商和模型登记顺序选择 | 显示候选为零及配置缺口，不发起请求 |
| 仅用所选模型 | 只使用手选的有序名单，不补入其他模型 | 提示添加所选模型或切换模式 |
| 停用 | 停止此功能的新调用 | 显式传入模型也不能绕过 |

工作台“功能池与调用方式”展示各功能的候选数，以及未连接、待确认用途、协议不支持或限流等原因。切换自动池先展示影响并确认；切回手选会保留原名单。自动池不是网络连通或上游能力实测的保证。

自动池采用页面内确认，确认前显示“尚未保存”；提交后在该功能旁依次显示“正在保存”“正在更新候选”和“已保存”。保存期间暂时禁用重复切换。若未收到确认，点击“刷新状态”只读取保存结果，不会再次提交；已保存但候选更新失败会分别说明。

更新后，需让 DSH 服务端加载新代码，再刷新页面。仅刷新页面可能形成新界面配旧服务端；此时页面会提示重启 DSH，并暂停策略切换，避免把旧接口的成功响应误认为自动池已启用。

生图和改图共享图片池，视频和 S2V 共享视频池，再按具体输入和协议过滤。看图、OCR、定位和视觉摘要共享视觉池。TTS、Music、转写分别使用自己的池；裁剪、导入、抽帧等本地操作不要求模型。

自动视觉默认不包含宿主资源；需要时明确勾选“使用 DSH 当前视觉模型”。它仍须由宿主声明支持图片输入，独立 CLI 不能执行该资源。

## 顺序选择与安全切换

每个新请求从首个合格候选开始。A 明确未受理时可以继续 B；已知冷却项会跳过。此阶段没有跨请求 A→B→C 的轮转游标。

临时指定模型须在当前允许范围内，本次只调用它，失败不替换。工作台默认保留自动选择，不会把首个候选填成显式参数；Agent 也只应在用户明确指定时传模型参数。

媒体受理未知、已经受理或交付失败时，仍绑定原任务处理，不因池内还有模型就重新生成。池和策略变化只影响新请求，旧任务沿原模型、协议和端点绑定观察或补交付。Music 原有显式 502 重发规则独立保留，每次建立关联新任务，可能增加费用。

## 旧配置与 CLI

旧字符串、数组及对象形式的分配继续按原手选名单解释，缺失或空分配保持零调用；读取不会自动启用或迁移。用户主动切换策略时，旧引用归一化保存，原手工名单保留。无宿主 CLI 仍使用显式私有配置，不解析 DSH 连接引用。

新策略在现有 `assignments` 中按功能保存，例如：

```json
{
  "assignments": {
    "image-gen": {"mode": "auto", "models": ["account::preferred-image"]},
    "music-gen": {"mode": "manual", "models": ["account::music"]},
    "vision": {"mode": "auto", "models": [], "hostVision": false},
    "video-gen": {"mode": "disabled", "models": []}
  }
}
```

`models` 是保留的手工名单，自动模式不以它限制候选。新增模型必须有明确功能标签，发现条目须经用户确认；模型的限流、协议及实际输入约束继续生效。

通过现有 CLI JSON 输入管理，无需增加命令或直接编辑配置：

```bash
dsh-iris models add 'account::image-a' --provider-config /absolute/path/providers.json \
  --input '{"capabilities":["image-gen"],"enableAutomatic":true}'
dsh-iris models caps 'account::image-b' --provider-config /absolute/path/providers.json \
  --input '{"capabilities":["image-gen"]}'
dsh-iris assignments set --provider-config /absolute/path/providers.json \
  --input '{"capability":"image-gen","mode":"auto"}'
dsh-iris assignments set --provider-config /absolute/path/providers.json \
  --input '{"capability":"image-gen","mode":"manual","model_refs":["account::image-b"]}'
dsh-iris assignments set --provider-config /absolute/path/providers.json \
  --input '{"capability":"image-gen","mode":"disabled"}'
dsh-iris capabilities list --provider-config /absolute/path/providers.json
```

`enableAutomatic:true` 是明确修改所选功能策略的动作；省略时只确认用途，已有自动功能会纳入该模型，已有手工/停用功能不变。`assignments clear` 继续清除该功能分配并停止新调用，不表示恢复自动。配置写入沿用唯一私有备份与并发修改检查，见 [CLI 管理](CLI_MANAGEMENT.md)。