feat(gateway): 图/视频调用经进程内 Gateway 做重试、Fallback 与观测

[xiaocheny214]

Summary

• 把图生图和 i2v 的重试、同家族 Fallback、熔断和结构化 trace 从 sufy.py 抽到 windup_framework.gateway。业务仍只调 ImageProvider.gen_image / VideoProvider.i2v。
• 521/522/523/525 同型号只再打一次、不换型号；520/524 不重试。视频有 job_id 后不再 POST 第二单，仅 failed/cancelled 允许换型号新开。
• 任务失败原因带上 request_id，便于从日志捞 attempt 链。积分扣费仍走现有 QUOTA_*。

Fixes #330

Test plan

• backend/ 下 gateway + sufy + custom_action + executor 等相关测试 167 passed
• 图像 522：同一型号恰好 2 次 POST，不打 fallback 型号
• 图像 429：primary 最多 3 次后走 fallback
• 图像 520：只打 1 次
• 视频 submit 拿到 job_id 后，轮询 429/失败不再开第二单；上游 failed/cancelled 才换型号
• 非法 video_model 仍 4xx
• 失败任务的 error 含 request_id=

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
windup	Ignored	Preview	Aug 19, 2026 4:44am

[codecov]

Codecov Report

❌ Patch coverage is 93.86792% with 39 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...s/framework/src/windup_framework/providers/sufy.py	82.82%	17 Missing ⚠️
...es/framework/src/windup_framework/gateway/video.py	94.73%	7 Missing ⚠️
...es/framework/src/windup_framework/gateway/image.py	94.59%	6 Missing ⚠️
...framework/src/windup_framework/gateway/registry.py	92.10%	3 Missing ⚠️
...app/src/windup_app/server/orchestrator/executor.py	93.54%	2 Missing ⚠️
.../framework/src/windup_framework/config/provider.py	91.66%	1 Missing ⚠️
...framework/src/windup_framework/gateway/classify.py	97.05%	1 Missing ⚠️
...s/framework/src/windup_framework/gateway/policy.py	96.00%	1 Missing ⚠️
...es/framework/src/windup_framework/gateway/trace.py	98.61%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[fennoai]

Review conclusion

整体分层与提交后不重复建单的主路径一致，但视频错误状态仍有两处会扩大重试或污染后续路由：轮询 52x 被 adapter 与 Gateway 双重重试，以及本次请求明确禁止 fallback 时仍提前打开型号熔断。建议修正这两个状态转换后再合入。

验证：完整检查了固定 diff 4103106...19fce6a 的 gateway、Sufy adapter、executor/API 接入与相关测试；git diff --check 通过。当前运行环境缺少 uv 和项目 Python 依赖，未能执行 pytest。

View job run

[fennoai]

[P1] 仅在实际切换型号时打开型号熔断

这里在检查 fallback 是否允许之前就打开了 model:<model> 熔断。对于已经拿到 job_id 的轮询 429/无效响应，下面的保护分支会正确拒绝新建 fallback 单并立即失败，但熔断已经保留 60 秒；下一条独立任务会跳过仍可能正常的 primary，直接向 fallback 型号建单。提交阶段的无效响应也有同样问题。请把熔断更新移到通过 bound_job_id/错误类型保护、确定确实会 break 到下一个型号之后。

[fennoai]

[P2] 避免轮询 52x 在两层各重试一次

_poll_get 已经在一次 follow_job 内对 521/522/523/525 连打两次，而 VideoGateway 收到最终 UNREACHED 后还会按同一策略再次调用 follow_job。因此持续 522 时同一个轮询点实际发出 4 次 GET，而不是描述和策略要求的“只再试一次”；trace 还只记录为一次 Gateway retry，无法反映真实请求数。请让 adapter 保持一次 GET，把唯一的重试预算交给 Gateway，或让 Gateway 知道 adapter 已消费该预算。

[johnnyzhang-eng]

我的 #324 也改 sufy.py——抽了个 ChatCompletionsFace 让出图和判官共用建连和重试，和你这版重叠。你把重试整个移到 Gateway 之后那层就多余了，所以不管哪边先合，我都按你的 AdapterResult 收，不另起一套。

[xiaocheny214]

我的 #324 也改 sufy.py——抽了个 ChatCompletionsFace 让出图和判官共用建连和重试，和你这版重叠。你把重试整个移到 Gateway 之后那层就多余了，所以不管哪边先合，我都按你的 AdapterResult 收，不另起一套。

现按照我的来做吧。咱们把重试的逻辑统一放在gateway做，这样方便后续的链路追踪、熔断、限流等逻辑的引入，以及更换模型路由。这样看起来，重试逻辑也不会太过散乱，你觉得呢？
@johnnyzhang-eng

[johnnyzhang-eng]

同意，重试归 Gateway。#324 没有另起一套：它改的是 sufy.py 里已有那处，把措辞从「图像服务」改成通用、让判官复用同一条建连和退避，你这版落地后删的是同一处，不会留两套。另外 #331 自 08-17 是冲突态没再动过而 #324 已绿，所以我按互不阻塞处理，谁先合我跟谁改。