路由暂停、回退与恢复

v0.9.0 用统一路由准入门替代 circuit_breaker。它区分连接/部署不可用与上游明确拒绝，并把暂停绑定到对应 Credential、Credential + model 或 Deployment。一个失效凭据服务多个 Deployment 时，不必让每个目标都重新撞一次同样的拒绝。

配置与尝试预算

以下是需要合并到完整配置的片段，不是独立配置文件：

routing:
  availability_failures: 5
  suspend_for: 30s
  max_suspend_for: 5m
  probe_requests: 1
gateway:
  max_total_attempts: 4
retry:
  max_attempts_per_target: 1

retry.max_attempts_per_target 包含第一次尝试。每个候选都用满次数时，最多能走到 ceil(max_total_attempts / max_attempts_per_target) 个候选；旧的 3 / 2 只能到两个，默认 4 / 1 能到四个。准入前跳过的目标不消耗尝试预算，整个过程仍受 route_total_timeout 限制。已有文件不会自动变成新默认值。

什么会暂停，如何恢复

什么会暂停，如何恢复
原因	默认处理	管理员动作
`invalid_credential`、`subscription_inactive`	一次明确拒绝即暂停 Credential，无自动到期	修复并重新保存凭据，使修订变化；不要靠重启
`subscription_quota_exhausted`	暂停 Credential + model，初始 15 分钟、失败探测逐步延长至 6 小时	检查配额、账单与产品；有上游 `Retry-After` 时遵循它
`rate_limited`	暂停 Credential + model，初始 1 秒、最多 1 分钟	降低压力，等待探测
`entitlement_verification_unavailable`	暂停 Credential，初始 30 秒、最多 5 分钟	排查权益验证服务
未分类的可用性故障	连续 `routing.availability_failures` 次后暂停，使用 `routing.*` 窗口	先查状态、连接和超时配置

只有适配器能从响应确定的原因才进入对应策略，不能把所有 402/403 都解释为配额用尽。凭据暂停不带 Retry-After；有窗口的暂停到期仅允许有限探测，并不保证立即恢复。所有候选均被暂停时返回 503 all_candidates_suspended，对调用方不暴露上游账号和凭据身份。

回退边界

Chat、可移植 Responses/Messages 和 Embeddings 可以在尚未向客户端输出内容时，因明确可重试失败或本次拒绝造成的暂停走向下一个候选。结果不明确的失败不会自动重试或回退；流已经输出字节后也不能换目标。原生 Anthropic Messages / Count Tokens 不继承可移植回退，媒体、Files、Batches、Async 需要单目标，多候选会返回 409 ambiguous_resource_route。

因此暂停机制不等于“任何 5xx 都自动切换”，幂等也不保证最终一定收到答案。应用策略见重试与幂等。

查看与清除暂停

在线从 Console 的 Providers / Routes 暂停面板查看原因、作用域、凭据修订与 clearable。 Admin API 提供 GET /admin/api/v1/route-suspensions；对可清除项使用 DELETE /admin/api/v1/route-suspensions/{scope_id}。scope_id 是返回的 opaque handle，不能自行拼接。清除与 route_suspension.clear 审计一起提交；清除不修复上游原因，下一次拒绝仍可再次暂停。

离线命令需要停止 Halro、取得数据目录锁：

halro route suspensions --config /etc/halro/config.yaml
halro route clear-suspension --config /etc/halro/config.yaml --scope-id RETURNED_SCOPE_ID

把 RETURNED_SCOPE_ID 替换为列表返回的准确值。离线列表只展示持久化的暂停。无期限凭据暂停和超过五分钟的长窗口才持久化；短可用性暂停和探测状态不是跨重启记录。替换凭据仍是处理凭据拒绝的首选动作。

Advisor 与监控

Console 的设置/诊断面板显示确定性结论；离线 halro doctor --config ... 在 findings 中给出同一套配置比较。ok 表示已检查，warn 表示配置组合有问题，unknown 表示缺少运行时证据。它比较响应头超时与总预算、单目标次数与总预算、fallback 扇出、暂停和运行时限制，不调用模型。

监控 halro_route_suspended、halro_route_suspension_transitions_total、 halro_route_probe_admitted_total、halro_provider_failure_reason_total，配置 HalroCredentialUnusable 与 HalroProviderQuotaExhausted 告警。身份信息在 Admin 面板/API 中查询，不从 Metrics 标签或面向调用方的错误中猜测。