故障、冷却与恢复

当某个 API 候选通道（翻译、OCR、上色或渲染的某个编号槽）请求失败时，程序会在进程内为它记录一个状态，并用它决定后续请求是否继续选择这个候选。这里说明失败后的状态机：冷却、不可用、恢复到可用，以及“配置本身有误时恢复后仍会再失败”的原因；同时列出冷却与超时参数。

这里不负责候选通道的添加删除、编号徽标与两种轮换策略（见API 通道与轮询策略），不负责连接测试的对话框流程（见连接测试与模型列表），也不负责普通请求重试的完整参数（见重试、限流与质量）。

配置范围

内容包括的是“候选端点”级别的状态：每个候选由 feature、provider、槽号、地址、模型和密钥指纹共同标识；状态保存在内存中，不写入 .env 或 config.json。
只有限流类错误会进入“冷却中”，只有永久错误会进入“不可用”；其他错误只记录为“失败”，不会阻止该候选被再次选中。
状态机对翻译、OCR、上色和渲染的 API 组同样生效，因为四类消费者都调用同一个轮换入口 run_with_api_candidates。
状态是进程内的：重启程序、修改 Key/Base/Model（状态身份变化）都会让旧状态失效；点击卡片上的“恢复”按钮则主动清除某个候选的状态。

界面状态与操作

打开“API 管理”，某个通道卡片标题下方会出现状态条。状态条只在“冷却中”或“不可用”时出现，普通“失败”不会显示状态条。状态条右侧的“恢复”按钮调用 clear_api_status，只清除当前进程内的失败状态，不修改任何 .env 值。

用“测试当前页”或行内“测试”验证通道；测试成功会把该候选标记为可用，失败则按错误类型进入冷却、不可用或仅失败记录。
冷却中的候选会在冷却到期后自动重新参与候选选择；不可用的候选会一直被排除，直到手动点击“恢复”或修改凭据。
开始翻译前，程序会先做候选可用性检查：如果某个必需功能组的所有候选都不可用，会阻止启动并提示“没有可用的 API 候选”，详情列出对应通道，并建议重新启用对应 Key/通道或使用「测试当前页」确认后再开始。

状态条文案只区分“冷却中”和“不可用”两种；冷却剩余时间不会显示在界面上。

状态机：冷却、不可用、恢复与再失败

stateDiagram-v2
    [*] --> Available: 启动、恢复按钮或修改凭据
    Available --> Requesting: 被轮换策略选中
    Requesting --> Available: 请求成功（状态改写为可用）
    Requesting --> Cooldown: 429、速率限制或 Retry-After
    Requesting --> Unavailable: 402、404、特定 400 或配额计费
    Requesting --> Failed: 网络、5xx 等其他错误
    Failed --> Requesting: 仅记录失败，不阻止后续选择
    Cooldown --> Requesting: cooldown_until 已过，自动重新参与
    Cooldown --> Available: 冷却期间测试成功
    Cooldown --> Unavailable: 冷却期间测试遇到永久错误
    Unavailable --> Available: 点击“恢复”清除状态
    Available --> Unavailable: 配置有误，恢复后再次失败

可用：没有状态记录，或上次请求/测试成功。可参与后续候选选择。
冷却中：状态记录含 cooldown_until；在此时间之前 is_endpoint_unavailable 返回真，候选被跳过。到期后自动重新参与，但状态字段仍写“冷却中”，直到下一次成功才改写为“可用”。
不可用：永久错误；进程内一直被排除，只有 clear_api_status（恢复按钮）、修改凭据或进程重启能解除。
失败记录：其他错误只记录 last_error，不影响后续选择；同一候选在下次请求中仍可能被选中。
请求中：候选被选中并实际发送请求；成功、限流、永久错误或普通错误分别把状态改写为上述状态。

run_with_api_candidates 在一次调用开始时用 iter_api_candidates 生成候选列表：不可用或冷却中的候选从一开始就被过滤，因此状态机主要影响“下一次请求”，而不是正在执行的这一次。

冷却与超时参数

冷却时长没有界面设置项，完全由服务端响应和代码常量决定；界面能配置的只有同一候选上的普通重试次数（cli.attempts）。

“普通重试”（cli.attempts）、“冷却”和“不可用”是三个不同层级：普通重试在同一候选内进行，冷却和不可用决定后续请求是否还会选择该候选。不要把普通重试次数误当成冷却时长。

恢复到可用的条件

恢复方式	触发	效果	说明
冷却到期	`cooldown_until` 已过	候选自动重新参与选择	状态字段仍为“冷却中”，直到下一次成功改写为“可用”
请求/测试成功	`record_api_success`	状态改写为“可用”	任何成功的请求或连接测试都会触发
手动恢复	点击状态条右侧“恢复”（`Restore`）	`clear_api_status` 删除状态记录	只清除状态，不修改 Key/Base/Model
修改凭据	编辑 Key/Base/Model	状态身份变化，旧状态不适用	例如更换密钥后，旧的“不可用”记录不会作用于新密钥
进程重启	程序退出并重启	全部状态清空	`_API_STATUS` 与状态密钥均为进程内随机值

配置本身有误时：恢复后仍会再失败

“恢复”按钮、修改凭据或进程重启只会清除状态记录，不会修复 .env 里的连接信息。如果失败原因是真实的（密钥无效、模型不存在、配额耗尽、计费错误），恢复后再次发起请求仍会得到同样的错误，候选会被再次标记为“不可用”，状态条会重新出现。冷却到期也一样：冷却只是暂时跳过，不代表候选恢复健康；如果服务端仍然限流，候选会再次进入“冷却中”。

flowchart LR
    R["点击恢复\nclear_api_status"] --> A["候选重新参与选择"]
    A --> Q["再次发起请求"]
    Q -->|"配置确实有误（密钥无效 / 模型不存在 / 配额）"| F["相同永久错误"]
    F --> U["再次标记为不可用"]
    U -.->|"状态条再次出现"| R

因此排查顺序是：先确认 Key、地址和模型确实正确，再点击“恢复”并运行“测试当前页”；不要用反复点击“恢复”来代替修配置。

凭据、网络与错误

冷却/不可用状态按 feature:provider 分组独立保存：翻译组冷却不会影响 OCR、上色或渲染组，反之亦然。
状态只影响“候选选择”；它不会改变翻译器实现（translator.translator），也不会被 translator_chain 使用。边界见功能选择器与翻译器串联。
普通重试、HQ/质量重试、区域重试和 API 候选切换是四层不同机制，不要混写；普通重试的完整说明在重试、限流与质量。
测试产生的状态与真实请求共享同一份 _API_STATUS：测试失败会把候选标记为冷却/不可用，之后真实请求也会跳过它（除非点击恢复）。
Web/服务器场景的 _runtime_api_overrides 会把候选固定为单端点 failover，不存在多候选轮换，但该单端点仍会记录冷却/不可用状态；桌面端默认不存在这些覆盖。

故障、冷却与恢复 ​

配置范围 ​

界面状态与操作 ​

状态机：冷却、不可用、恢复与再失败 ​

冷却与超时参数 ​

恢复到可用的条件 ​

配置本身有误时：恢复后仍会再失败 ​

凭据、网络与错误 ​