# 复用 DSH 供应商连接

本文对应 Iris 0.2.7，功能从 0.2.6 起提供；发布状态见 [README](../README.md)。0.2.5 不包含此入口。

DSH 已有兼容媒体服务时，可以在 Iris 工作台引用它的连接，避免再次填写和保存 Base URL/API Key。Iris 保留自己的模型、媒体协议与功能池；宿主连接提供当前地址和凭据。已有手动供应商配置继续使用。

## 工作台操作

1. 打开“添加供应商”，在“连接来源”选择已配置的 DSH 连接。
2. 明确选择该服务实际支持的媒体协议，保存。
3. 发现或添加媒体模型，确认它用于哪些功能。首次配置可同时启用所选功能的自动池，保存即可使用，无需再次逐项分配。

引用连接不会自动发现、实测或生成；只有用户确认的用途和功能策略决定调用范围。已有手工名单或停用状态不会自动改变。DSH 能进行文字对话不证明相同服务支持媒体接口；协议、账号权限和模型能力仍需核对。三种调用方式见 [功能模型池](FUNCTION_MODEL_POOLS.md)。

## 地址、密钥与恢复

Iris 配置只保存 `dshProvider: { provider, settingsNs }`，不保存该连接的普通 Base URL 或密钥。操作期间，DSH 适配层通过公开供应商目录、已脱敏设置描述和凭据接口构造内存副本；不同并发操作的副本隔离，不进入配置持久化。

DSH 的地址或密钥变化影响下一次操作。Iris 供应商列表展示连接来源、地址和可用状态，密钥只显示“由 DSH 管理”。停止使用引用或删除 Iris 供应商不会修改 DSH 原连接。

离线 Doctor 不解析宿主引用，会提示“需由运行中宿主解析”，不会要求再填写同一把密钥。请在 DSH 工作台查看连接状态和功能池候选；候选元数据不代替真实接口权限验证。

原连接停用、移除或无法解析时，该项不可用；显式指定该模型不会换用其他账号。原任务的恢复继续校验提交端点和协议绑定，地址改变时拒绝向新端点观察原任务，不会重新生成。已缓存完整字节的本地补交付沿用现有规则。

## 支持范围

- 需要 DSH 的 `llm.listProviders/listConfigurableProviders`、`settings.describe` 和对应凭据服务。
- 支持配置中的 `apiKeyEnv` 引用、默认 `llm-pi-ai` 实例的 API Key 记录，以及目录明确声明的环境凭据引用。
- OAuth/登录授权、专有签名和自定义请求头不转换为媒体认证；界面显示原因，可继续手动添加适合的媒体供应商。
- 尚不自动处理别名 `llm-pi-ai` 实例的私有记录归属；这类实例可以使用公开的 `apiKeyEnv` 引用。
- 缺少接口的旧宿主保留手动配置。连接复用能力按实际服务检测，不扩大已有宿主版本声明。
- Headless CLI 不读取 DSH 连接。CLI 媒体调用继续使用显式的独立 Provider 配置；含 DSH 引用的条目不能在无宿主进程中解析。

此功能不迁移已有配置、导出宿主密钥或读取其他项目文件；功能策略由用户明确选择，受理后不自动重提和单写者约束继续保留。