# Provider 与能力健康状态

状态：v0.1.4 候选契约。

Iris 用持久化证据描述“当前配置是否存在、最近是否实际成功、是否出现明确凭据失败”。它不是后台监控，也不等同于 Host Doctor。

## 四种状态

| 状态 | 颜色 | 含义 |
|---|---|---|
| `unconfigured` | 灰色 | 当前能力没有启用且带凭据的候选模型 |
| `configured` | 蓝色 | 已配置，但没有 7 天内的成功证据；旧证据过期后也回到此状态 |
| `verified` | 绿色 | 该 Provider × Model × Capability 在 7 天内通过显式实测或真实任务成功 |
| `failed` | 暗红色 | 最近的决定性证据是 401、403 或明确的认证/权限失败 |

状态按 `Provider × Model × Capability` 记录，不因同名模型而合并。模型、Key、Base URL、协议或能力模型等关键配置变化会清空相关旧证据；移除模型或能力标签也会移除不再成立的记录。

## 什么会改变状态

显式“模型实测”和正常用户任务都会产生证据。视觉、图片和 TTS 可从模型池逐项实测；视频与转写不会发送空样本探针，应使用真实的视频生成或音频转写任务验证。成功受理、同步完成或视觉成功会刷新绿色及其成功时间。

Iris 不做定时后台探测，也不会为了让图标变绿而产生隐形请求或费用。429/额度限制、网络错误、5xx、内容安全、用户取消和受理未知属于临时或不确定事实：它们可以记录为最近观察，但不会把 7 天内的绿色覆盖成红色。只有明确认证或权限失败才会变暗红；移除 API Key 后回到灰色。

## failover 与泡泡汇总

每项能力按当前有序 failover 候选汇总：

1. 任一路候选为绿色，能力为绿色；
2. 否则任一路为蓝色，能力为蓝色；
3. 只有所有已配置候选都为暗红时，能力才为暗红；
4. 没有候选时为灰色。

主泡泡再按五项能力使用同一保守规则汇总。汇总证据时间只从决定汇总颜色的候选中选择，例如绿色不会显示另一条较新蓝色临时观察的时间。界面同时显示文字和证据时间，不要求用户只凭颜色判断。

## 与诊断的区别

Host Doctor 只检查 DSH、Iris 注册、Host Port、客户端版本和 UI Slot 是否装载；它零网络、零计费，不能证明 API Key 或具体模型可用。Provider 健康来自模型实测和真实业务请求，才回答供应商侧是否近期成功。离线 `dsh-iris doctor` 则检查本地运行时、配置、存储与任务一致性，三者不能互相替代。

健康事实保存在 `$DSH_HOME/iris/v1/providers.json`，状态 API 仅返回脱敏标量。错误说明会移除 Authorization、Key、签名参数、私有路径和已配置的完整 API Key。