TrueGrowth/docs/ASYNC_TASK_PROVIDER_ROUTE_LESSONS.md

异步任务供应商路由经验

更新日期：2026-05-05

背景

图片、视频、音频异步任务都有“提交任务 -> 保存远端任务 ID -> 后续查询状态”的链路。多供应商接入后，提交时使用的供应商不一定等于用户刷新页面后的默认供应商。

这次 HappyHorse 用户反馈的错误是：

• 状态查询失败
• 接口返回“该令牌无权访问模型”
• request id: 202605020707307592757188268d9d67zVDq7SC

根因

异步任务只保存 remoteId 不够。

如果任务恢复查询时只依赖当前 task.params.model、当前默认供应商，或当前全局 API Key，就会出现：

• 提交任务用的是供应商 A 的 key
• 刷新后默认路由切到了供应商 B
• 查询状态时拿供应商 B 的 key 去查供应商 A 的任务
• 服务端返回模型无权限、任务不存在或鉴权失败

这不是 HappyHorse 单模型问题，而是多供应商异步任务的通用一致性问题。

修复规则

1. 异步任务必须绑定创建时路由

任务进入异步轮询阶段时，必须保存轻量 invocationRoute 快照：

• operation: image / video / audio / text
• providerProfileId
• providerType
• modelId
• modelRef
• binding 的协议、请求/响应 schema、提交路径、轮询路径模板

不要保存 API Key。恢复查询时应通过 providerProfileId 找当前配置里的最新 key。

2. 恢复查询必须优先使用任务路由

恢复查询时优先级应是：

1. task.invocationRoute
2. 兼容旧任务的 task.params.modelRef
3. 最后才是 task.params.model 或默认路由

只要任务上存在 providerProfileId，就进入严格模式，不允许静默 fallback 到默认供应商。

3. 严格模式要显式失败

以下情况应直接给出配置错误，而不是换默认 key 继续查：

• 原供应商配置已删除
• 原供应商被停用
• 原供应商 API Key 缺失
• 原供应商 Base URL 缺失
• 原模型 binding 已不可用

这样用户看到的是“原供应商配置不可用”，而不是误导性的“令牌无权访问模型”。

4. 查询路径也属于供应商 binding

视频状态查询不能硬编码一种路径。不同供应商可能需要：

• /videos/{taskId}
• /kling/v1/videos/{action}/{taskId}
• 其他自定义 poll path

轮询路径应来自 binding 的 pollPathTemplate，并支持用任务参数填充 {taskId}、{action} 等占位符。

5. 同步和恢复必须 round-trip

invocationRoute 必须覆盖这些路径：

• IndexedDB 写入与读取
• 内存 task queue 同步
• 外部任务追踪
• fallback executor
• 主线程 resume
• GitHub sync compact / restore
• SW channel 类型

如果某条链路漏掉字段，刷新或远程同步后仍会回到默认供应商查询。

6. 异步图片恢复判定不能只依赖模型白名单

刷新恢复时，只要异步任务已经拿到远端任务 ID，就应该优先恢复轮询，而不是直接标记为“页面刷新中断”。

图片任务尤其容易踩坑：动态供应商模型不一定在内置 ASYNC_IMAGE_MODEL_IDS 白名单里，但任务创建时已经持久化了 invocationRoute.binding。因此恢复判定应满足：

• 任务类型是 image
• 已有 remoteId
• 模型命中内置异步图片白名单，或 invocationRoute.binding 表明它是 openai.async.media / openai.async.image.form

这样页面刷新后，UI 会继续显示生成中并由执行器恢复轮询；只有真正的业务终态失败才进入失败界面。

不要为了隐藏错误去改 UI。失败界面只是任务状态的投影，根因应在任务恢复层修正。

代码落点

• task-invocation-route.ts：创建、解析、严格校验任务路由快照。
• core.types.ts：任务模型增加 invocationRoute。
• task-queue-service.ts：创建任务、外部任务、storage sync 写入路由快照。
• generation-api-service.ts / useTaskExecutor.ts：image/audio/video 恢复查询优先用任务路由，并在严格模式下校验原供应商。
• task-utils.ts：集中判断异步图片任务是否可恢复，避免 storage 和 executor 使用不同条件。
• fallback-executor.ts：fallback 视频恢复查询使用原供应商。
• video-binding-utils.ts：统一视频状态查询路径模板。
• github-sync：远程同步保留 invocationRoute。

验证清单

• 异步任务提交后，storage 中应有 remoteId 和 invocationRoute。
• 刷新页面后恢复 image/audio/video 任务时，请求应命中原 providerProfileId 对应的 key。
• 修改默认供应商后，旧异步任务仍应使用原供应商查询。
• 删除或停用原供应商后，任务应失败为明确配置错误，不应切到默认 key。
• 自定义 pollPathTemplate 的视频供应商应按模板查询状态。
• 动态异步图片模型即使不在内置白名单，只要保存了 async image binding 和 remoteId，刷新后也应继续轮询。

经验规则

• 异步任务的远端 ID 只在原供应商上下文中有意义。
• 多供应商系统里，“模型名”不是稳定路由键；稳定键应包含供应商 ID 和模型 ID。
• 不要把 API Key 持久化进任务；持久化供应商 ID，查询时读取当前 key。
• 新增异步供应商时，必须同时补提交路径、轮询路径、恢复路径和同步路径测试。
• 任何状态恢复逻辑都要警惕静默 fallback，它会把配置问题伪装成模型权限问题。
• UI 失败态不应作为异步中断兜底；先确认任务是否已有可轮询的远端 ID。