feat(generation): 任务编排

[johnnyzhang-eng]

变更内容

这个 PR 直接对应 #151 / #152 里的 orchestrator 部分，按当前 main（efd230e）重新迁移。

主线上 server/orchestrator/ 只有 interface + model，缺 service / executor / task_repo；web/api/generation.py 三个端点是「接口待实现」。本 PR 补齐：

• service.py — 建 PENDING 任务记录
• task_repo.py — 任务持久化 + 状态变更时推 SSE
• executor.py — 后台执行：取母版 → 读项目约束 → 经 ai_engine.ports 生成 → 逐帧上传对象存储 → 更新任务
• web/api/generation.py — POST /image / POST /action / GET /tasks/{id} 三个端点真实现

迁移时按主线现状做的三处调整

1. 接口签名统一到 session-per-call。

主线 orchestrator/interface.py 的三个方法没有 session 参数，而 #176 刚合入的 workflow_run/service.py 用的是「session 首参 + 关键字入参 + 只 flush 不 commit」。两处不一致会让同一个仓里出现两种事务写法，故 orchestrator 跟上已确立的那套；事务边界仍归 windup_framework.db.get_session（成功 commit、异常 rollback）。

2. 保留主线的 SSE 文档与终态关流。

interface.py 的 SSE 契约说明、generation.py 的 _TERMINAL_EVENTS 与终态后 break，都是主线后来加的，比源分支写的「前端轮询 get_task」更准确，原样保留。

终态关流治的是：服务端发完 task_update 就关流但带 retry: 3000，浏览器原生 EventSource 每 3 秒重连、45 秒内 15 次，每次重收同一条 completed。

3. user_id 从 JWT 取，不信客户端。

源分支的请求体里有 user_id: int = Field(gt=0)，客户端可以填别人的 id。改为 request.state.current_user.id，并加项目归属校验——项目不存在或不属于当前用户一律 404，不区分两者，以免泄露他人项目是否存在。

后台执行的两处要紧设计

after_commit 再起线程。 create_task 只 flush，session 要等 handler 返回后才 commit。直接起线程的话，后台 session 可能读不到未提交的任务行，update 静默跳过——任务永远停在 PENDING 且无任何报错。改为注册 after_commit 回调，提交成功后才派发。

executor 挂 app.state，不 import 进 web 层。 import-linter 的分层契约禁止 app.web 直连 ai_engine，而 executor 要调 ai_engine.impl。放进 state 由 bootstrap（唯一装配点）注入，契约与实现两边都成立。

依赖链（为什么不能单独提）

executor.py import 了：

windup_ai_engine.impl / ports / strategy.concrete
windup_common.models
windup_framework.providers          ← 主线唯一已有的
windup_app.server.{media,project,orchestrator}

四层里主线只有 windup_framework.providers。这就是 #152 合入即 ImportError 的同一条根因——ai_engine 那三层还没进主线。

stack 声明：本分支 stack 在 #172 / #179 / #180 / #181 之上，四个合并后 rebase，届时 diff 只剩 orchestrator + generation API 这一层。

关联

Refs #171 · Refs #78(SSE 推送替代前端轮询) · 迁移自 #151 / #152 的 orchestrator 部分

本地验证

uv run ruff check .   All checks passed!
uv run lint-imports   Contracts: 2 kept, 0 broken.
uv run pytest -q      242 passed

含 test_generation_orchestration.py 3 个用例（任务创建 → 后台执行 → 状态更新的串联）。

待对齐

端到端真跑未做。 本 PR 的所有验证都是单测与 mock；一次真实的「提交任务 → i2v 生成 → 上传七牛 → 落库」没有跑过（要花钱，且依赖上游四个 PR 先合）。四个前置合入后可以在部署环境上跑一次冒烟，那时才算这条链路真的通。

[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 12, 2026 8:21am

[fennoai]

Review Not Completed

The PR head changed while this review was running: the workspace was locked to 7a4abc07c5a4c2e660bcb7506a69f9f98ed34cbd, but GitHub now reports 125ab672d2fe641e09b8de9864817328b07f28d8. I did not submit findings from the stale diff. Please rerun /review against the current head.

View job run

[huyanxius]

Review Not Completed

The PR head changed while this review was running: the workspace was locked to 7a4abc07c5a4c2e660bcb7506a69f9f98ed34cbd, but GitHub now reports 125ab672d2fe641e09b8de9864817328b07f28d8. I did not submit findings from the stale diff. Please rerun /review against the current head.

View job run

@fennoai /review

[fennoai]

Review completed

Submitted a non-blocking review against efd230e4bed1f4890f467aa7d875ebfeb2e5cce8...125ab672d2fe641e09b8de9864817328b07f28d8 with 7 findings.

Key blockers include stale executor assembly symbols, the unimplemented real image provider, unauthorized SSE subscriptions, mismatched terminal events, unsafe cross-thread queue publication, SSRF-capable reference downloads, and unbounded paid generation counts.

Verification: git diff --check and Python syntax compilation passed. The full test suite was not rerun because uv is unavailable in this runner.

View job run

[fennoai]

Reviewed the fixed range efd230e4bed1f4890f467aa7d875ebfeb2e5cce8...125ab672d2fe641e09b8de9864817328b07f28d8. I found blockers in both real executor paths plus authorization/SSE issues. Static syntax validation and git diff --check passed; the full suite could not be rerun because uv is unavailable in this runner.

Findings without inline locations

• backend/packages/app/src/windup_app/web/api/generation.py:274: [P1] Authorize the SSE subscription before registering it. Unlike GET /tasks/{id}, this path never checks request.state.current_user against the task; the required project_id is unused. Any authenticated user who guesses a task id can receive that task's input, result URLs, and errors when the next update is published. Fetch with get_task_by_user (and return the same 404) before subscribing.

[nighca]

stack 声明：本分支 stack 在 #172 / #179 / #180 / #181 之上，四个合并后 rebase，届时 diff 只剩 orchestrator + generation API 这一层。

是预期先 review 那 4 个，然后再 review 这个对吧？

[vercel]

Deployment failed for project windup with the following error:

The provided GitHub repository does not contain the requested branch or commit reference. Please ensure the repository is not empty.

[johnnyzhang-eng]

自查追加两处（对抗复查自己这批改动时发现的，不是机器审报的）：

一、请求里的 width / height 此前被丢掉。 它们从请求进到 CharacterImageInput、被 _validate_project_size 校验过，然后没有任何人用 —— ImageProvider.gen_image(prompt, refs) 没有尺寸参数，模型出多大就返多大。调用方要 512×512、拿到 1024×1024，而请求被接受了。

性质与本轮删掉的 ActionSpec.fps / loop 完全相同，只是字段在入口侧。更难看的是我今天刚给这两个字段加了 le=2048 上界，等于替一个不履约的字段背书。

模型不吃宽高，所以在编排层落实：复用已有的 _fit_to，加 smooth 参数区分重采样 —— 序列帧是像素画必须 NEAREST（插值会把硬边糊成灰边、引入调色板外的颜色），全彩角色母版用 NEAREST 缩图明显锯齿，走 LANCZOS。

二、同一把 key 下不同网关的模型目录不一样。 实测 GET /v1/models：一个网关 73 个模型、一个图像模型都没有；另一个 134 个、含文生图 provider 的默认模型。配错 AI_BASE_URL 时原始报错只是一条裸 404，读的人无从判断该改配置还是改模型名。现在 400/404 一律翻译成指向 GET {base}/models 的错误。

这条修的是"错误信息不可操作"，不是配置本身 —— 部署侧需要确认所配网关的目录里确实有所用模型，代码管不了这件事。这也让我上一条里"请求形状与已跑通实现逐字段一致"这句话需要收窄：path / body / 鉴权头 / 重试轮数一致是真的，host 不同，而 host 正是会出问题的地方。

顺带：文生图路径改读配置里的 chat_completions_path（它本来就在 AIProviderSettings 里、零消费方，正是本轮在删的那类字段）。

测试 +7，变异测试逐条验过。其中重采样那条第一版拿纯色图作源是无效仪器（纯色下两种重采样产出完全相同），已换成棋盘格。

[johnnyzhang-eng]

交付尺寸这条链的实际机制比我上一条说的更糟，更正如下。

我之前说"项目要 512 时是从 256 上采样，白白糊一次"。复核后不是上采样——_fit_to 用的是 Image.thumbnail，它只缩不放。所以 256 的帧根本没被放大，而是原尺寸居中贴进 512 画布，于是引擎刚对齐好的脚线 0.92 被挪到 0.709（实测）：角色不站在地上，跨动作对齐一并失效。这比"糊一次"严重。

现在把画布尺寸交给引擎，它一次出到项目 sprite 尺寸，这一步整个不存在了。_fit_to 换成 _require_size——尺寸对不上直接报错，不做静默补救。这是 app 层的行为变更：引擎若不按 canvas 出帧，任务会 FAILED 而不是被悄悄缩放救回来。按本仓"不出静默错产物"的口径，这是有意的。

端到端实测（归档真实抠图帧，主体高中位 619px）：

• 不传尺寸 → 交付主体高 159px（与改动前逐字节相同）
• 传 (512,512) → 318px，倍数 2.000
• 传 (384,512) → 主体高与 (512,512) 相同（非方画布按高定标，正确）

预检几何一致性：REJECT_ASPECT 原本不含 cell，方形画布下 128/256/512/1024 的交付占高恒为 0.617~0.621，阈值处恰好 FILL_H/2=0.31——所以方形下一直是对的。但新增的非方画布能力把这条架空了（384×512 上只有 0.2324），因此阈值改为按 REJECT_ASPECT*(cw/ch) 收紧；修复后 8 种画布形状在阈值处的交付占高与 FILL_H/2 最大偏差 0.0025。

顺带修掉一个假绿用例：_SpyGenerator 一直在构造 GeneratedAction(fps=...)，而该字段早已删除——构造直接 TypeError、任务其实被判 FAILED；旧用例只断言构造之前就赋值的 seen_facing，所以一直绿着。

变异测试：pack 8/8、generator 5/5、executor 4/4、master_check 5/5 全部被杀。其中"预检不吃 canvas"这条最初杀不掉，补端到端用例后才杀掉。

未验：没看最终 512 档的成品 GIF（只量了主体高与画布尺寸）；512 档仍是下采样（318 < 619），1024 档已越过源分辨率、收益递减。

[johnnyzhang-eng]

这五个 PR 已达 ready：无待追加改动、CI 通过、AI review 意见全部 resolved。可以开始 review。

依赖顺序（已重排为线性 stack，逐级包含前一片的提交）：

#172 共享契约  →  #179 Provider 与抠图  →  #180 出帧工具箱  →  #181 引擎契约与串联  →  #182 任务编排

#180 零依赖于前两片的业务逻辑（纯 PIL / numpy + 真实视频实测），想先看小的可以从它入手。

本地已验的三项（每次推送后重跑）：

• 按依赖顺序合并 main → #172 → #179 → #180 → #181 → #182 五步全干净
• 逐分支 CI 原样命令全过，测试数 111 → 185 → 266 → 307 → 337 单调递增
• 全部合入后应用可启动，app.openapi() 口径 29 条路由，与 main 一字不差（零新增零删除）

端到端实证：2026-08-11 用这条链路（不是旁路脚本）从零跑通两个全新角色的走路序列帧——文生图出母版 → i2v → 抽帧 → 选帧 → 抠图 → 像素化 → 对齐 → 打包。

---

三条已知缺陷，代码在本批 PR 内，已独立立项跟踪，不在本批修复：

• 提示词库把某个原型角色的装备写死成默认值，导致所有角色被加上斗篷与武器（Refs #171） #195 提示词库把某个原型角色的装备写死成默认值，导致所有角色被加上斗篷与武器
• 逐帧对齐锚在包围盒中心而非躯干中心，延展物摆动把身体反向推走（Refs #171 #21） #196 逐帧对齐锚在包围盒中心而非躯干中心，延展物摆动把身体反向推走（实测头部横摆 24.5px / 包围盒 0.5px）
• 循环选帧取到半个步态周期，末帧接回首帧时左右腿互换（Refs #171） #197 循环选帧取到半个步态周期，末帧接回首帧时左右腿互换

三条都不影响流程成功与 CI，属品相问题。选择独立跟踪而不是塞进本批，是为了不让改动范围与 Issue 脱节；其中 #197 的可行方向尚未实现也未验证，如实说明。

[codecov]

Codecov Report

❌ Patch coverage is 87.37624% with 51 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...app/src/windup_app/server/orchestrator/executor.py	81.42%	39 Missing ⚠️
...pp/src/windup_app/server/orchestrator/task_repo.py	84.72%	11 Missing ⚠️
.../packages/app/src/windup_app/web/api/generation.py	98.07%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[johnnyzhang-eng]

#180 合入后跟着重排，冲突已解，CI 全绿。端点实现不受影响（已核对 generation_service 调用与 _task_to_out 都在）。

[johnnyzhang-eng]

跟着 #181 的进度修复重排了一次（a2f50ca），三个端点和 uv.lock 那几处标记都逐条核对过、没动。等你重看。

[johnnyzhang-eng]

已经是这个写法了：订阅前先读一次终态快照，是终态就直接 yield 那个事件然后 return（generation.py:365-368），不挂心跳。那 30 秒是这次改动之前的行为，已经去掉了，test_generation_stream_auth.py:143 钉住了这条。

fail 那半我做成推 failed 事件而不是抛异常：SSE 的响应头在生成器开跑时已经发出去了，此时抛异常客户端拿到的是一截断掉的流、而不是一个干净的错误码；而订阅方要的恰好是 error_message。

[huyanxius]

LGTM👍

[johnnyzhang-eng]

#181 合入后已重排（--onto 只重放本分支自己的 10 个提交，避开 squash 造成的 add/add 冲突），四条端点标记逐条核过没动，CI 六项全绿。

顺带修了 codecov：重排后 patch 分母变了，掉到 83.91%（目标 84.10%）。去看未覆盖行，最大缺口是 _fetch.py 的 46% —— 而那 14 行正是白名单放行之后的三条防线（不跟重定向 / 声明超限 / Content-Length 撒谎时边读边截），一条都没测过。补了 4 条（MockTransport 不联网），46% → 100%，patch 87.37%。变异测试验过这几条真能咬：分别关掉三条防护，三次都被逮到。

@huyanxius 你那条 CHANGES_REQUESTED 还挂着（端点已接回服务层那次修的），麻烦再看一眼。

good job