feat(generation): 任务编排 service/executor/task_repo + 三个端点真实现（迁移 #151 #152 · Refs #171）

[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 · 迁移自 #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 11, 2026 10:08am

[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 这个对吧？

[johnnyzhang-eng]

是。四个前置里 #172 是硬前置——它的 windup_common/models 是 #152 与本 PR 共同缺的那块（ai_engine/ports 与 strategy/concrete 都 import CharacterCard/ActionSpec，主线上 models/ 只有 .gitkeep，合入即 ImportError）。

建议的顺序与理由：

1. feat(common): 角色卡与动作规格共享 DTO（#152 的前置 · Refs #171） #172 windup_common/models — 2 文件，无依赖，可独立评审
2. feat(framework): Provider 抽象 + 主体抠图 + 视频下载重试（#152 的前置 · Refs #171） #179 windup_framework/providers — 依赖 feat(common): 角色卡与动作规格共享 DTO（#152 的前置 · Refs #171） #172（sufy.py 的类型标注用到）
3. feat(ai_engine): 出帧工具箱 —— 抽帧 / 选帧 / 后处理 / 提示词（Refs #171） #180 ai_engine 叶子（抽帧/选帧/后处理）— 零 windup 依赖，纯 PIL/numpy，其实可与 1、2 并行看
4. feat(ai_engine): 对外契约 + 动作分流 + 入口预检与出参成色（Refs #171 #53） #181 ai_engine ports/strategy/impl — 依赖 1、2、3
5. feat(generation): 任务编排 service/executor/task_repo + 三个端点真实现（迁移 #151 #152 · Refs #171） #182 本 PR，orchestrator + generation API — 依赖以上全部

顺序是 import-linter 分层契约的直接结果，不是我为了拆而拆：executor.py import 了 windup_ai_engine.{impl,ports,strategy.concrete} 与 windup_common.models，四层里主线只有 windup_framework.providers。

#180 可以插队——它零依赖、纯计算、有四段真视频的实测对照，单独看不需要任何上下文。如果想先看一个体量小的，#172 是 2 文件 +228 行。

每个 PR 自身 CI 都是绿的（不靠前置也能过）；前一个合入后我 rebase 下一个，届时各自 diff 只剩本层。

[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]

机器审 6 条 P1 已全部处理，当前 head bfb708d（复审时的 125ab67 已过期两轮）。逐条回复在对应行内评论里，此处只给索引与验证方式。

#	位置	结论	修在
1	executor.py 装配残留已删路线	已修	21c606c
2	/generation/image 的 provider 必抛错	已实现	758fe75（#179）→ bfb708d 同步
3	终态事件名不符 SSE 契约	已修	21c606c
4	EventBus 跨线程投递	已修	21c606c
5	服务端取任意 URL（SSRF）	已修	21c606c
6	付费循环无上界	已修	21c606c

第 2 条是唯一需要新增实现而非改错的：选择把 provider 补齐，而不是把端点藏起来。请求形状与一条已跑通的实现逐字段核对一致，测试全 mock、无付费调用。

验证口径：这批修复的测试全部做过变异测试——故意改坏实现、确认对应用例变红、再还原。过程中逮到自己写的两条摆设测试（一条只读常量字典、一条证不出跨线程 marshal 是必需的），已分别重写与如实降级说明，不留"绿着但什么都没证"的用例。

三处如实说明，不当已验证的结论：

• 文生图 provider 的真实付费调用尚未跑过（需先取得预算批准）。"端点不再必然失败"由形状等价 + mock 覆盖支撑，不是端到端实证。
• 跨线程投递用例只证明能到达，证不出 call_soon_threadsafe 必需；保留它的理由是 asyncio.Queue 的线程安全保证，而非实测复现。
• 视频 provider 的提交一段仍无连接级重试（下载一段有 3 次）。同源问题，但不在本 PR 范围，不夹带；如需一并处理请说一声，我另开。

CI：ruff / import-linter（2 contracts kept）/ pytest 285 passed，本地全绿。

依赖顺序未变：#172 → #179 → #180 → #181 → 本 PR。#180 零依赖（纯 PIL/numpy + 四段真实视频实测），可以插队先看。

[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]

已 force-push：把这条依赖链重排成真正的线性 stack。评审锚点会移位，说明原因。

问题：GitHub 的 MERGEABLE 只计算"对当前 main"，不计算"前面几个先合进去之后"。本地实测按依赖顺序合并：main → #172 → #179 → #180 都干净，合 #181 时 3~4 个文件冲突（matte.py / test_matte_provider.py / test_character_contract.py / quality.py）。

机制：#181 / #182 此前是各自独立基于 main、靠"同步提交"携带前置分片内容的副本。合并 #181 时的共同祖先里没有 matte.py（它属于 #179），于是两边各自"新增"同一个文件 = add/add 冲突 —— 即使一边是严格超集，git 也无法自动合并。所以逐文件对齐内容没用，必须让祖先里真有那些文件。

处理：改成 #172 → #179 → #180 → #181 → #182 的线性 stack，每个分支真正包含前置分支的提交。副作用是那些"同步上游/下游"的提交全部变成冗余，已在重排中丢弃。

内容变化（重排本身不改逻辑，两处例外，均已核对）：

• oneshot.py::_subject_rows 现在正确委托给 _subject.subject_mask（与母版预检共用同一个主体定义）。此前 feat(generation): 任务编排 service/executor/task_repo + 三个端点真实现（迁移 #151 #152 · Refs #171） #182 上带的是重构前的内联版本，属于同步过程中被覆盖，现已回正。
• 4 条提示词构造器断言（build_*(facing="sidee") 必须抛错）此前落在契约测试里、重排时被基座版本覆盖，已补回引入 prompt 模块的那一片（feat(ai_engine): 出帧工具箱 —— 抽帧 / 选帧 / 后处理 / 提示词（Refs #171） #180）——这也是它们本来该在的位置：契约片只测 DTO、不 import 上层包。

验收（重排后逐项跑过）：

• 顺序合并 main → feat(common): 角色卡与动作规格共享 DTO（#152 的前置 · Refs #171） #172 → feat(framework): Provider 抽象 + 主体抠图 + 视频下载重试（#152 的前置 · Refs #171） #179 → feat(ai_engine): 出帧工具箱 —— 抽帧 / 选帧 / 后处理 / 提示词（Refs #171） #180 → feat(ai_engine): 对外契约 + 动作分流 + 入口预检与出参成色（Refs #171 #53） #181 → feat(generation): 任务编排 service/executor/task_repo + 三个端点真实现（迁移 #151 #152 · Refs #171） #182 五步全干净
• 逐分支 CI 原样命令（uv sync --frozen + ruff + import-linter + pytest）全过，测试数 111 → 174 → 247 → 279 → 306 单调递增
• 全合入后应用能启动，app.openapi() 口径 29 条路由，与 main 一字不差（零新增零删除）
• 各分支树与重排前逐文件比对，零文件删除，减少的行全部核对到上面两处

[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 的可行方向尚未实现也未验证，如实说明。

[johnnyzhang-eng]

冲突已解，四个 PR 重排到最新 main。可以按顺序 review / 合并了。

#172 已合入 main，依赖链缩短为：

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

冲突根因：#172 合入后，我这几个分支还带着它的旧提交（squash 前的三个），与 main 上的 squash 版 add/add 冲突；同时 main 合了 #110（SSE adapter）、#194（CORS 顺序）等 10 个提交。已全部重排吸收，两种口径都验过：逐个直接对 main 合干净（GitHub 的判据）、按依赖顺序连合也干净。

---

这次重排里有一处我必须更正的方向错误，涉及 #182 的 SSE。

我上一版删掉了 project_id、改用任务自己的 user_id 做归属校验，并把 EventBus 改成单键。那是错的：主线 #110 里 project_id 正是归属校验的依据（_get_project_or_raise），EventBus 也按 (project_id, task_id) 双键隔离同一 task_id 在不同项目下的流。删掉它会退化主线已有的能力。

本版改为在主线骨架上补齐它的 TODO，具体四条：

1. 归属补成两道。 主线已校验「项目属于当前用户」，缺「任务属于那个项目」。缺这一道，任意已认证用户拿自己的 project_id 配上别人的 task_id 就能订阅到别人的流，而事件体带 result，即最终帧的对象存储 URL。测试用同一用户的两个项目复现，因此排除了「项目归属校验挡住了」这种解释。
2. 终态预检落地（原先是一行 TODO，而 docstring 已经承诺了该行为，实际表现是客户端要先挂满一次心跳超时）。
3. publish 改成同 loop 直接入队、跨 loop 才 call_soon_threadsafe。 一律走 marshal 是错的——那是异步调度，要等 loop 下一次迭代才真入队，于是「publish 完立刻 get_nowait」会拿到空队列，feat(generation): align validated SSE adapter with backend tasks #110 的项目隔离用例正是这么写的。跨 loop 分支保留是因为 executor 在 daemon thread 里跑，而 asyncio.Queue 不是线程安全的。
4. task.project_id 为空时记 warning 并早退，不再 publish 到一个没人听的键上。静默发出去的现象是「任务确实在跑、状态也在落库，但前端进度条一动不动」，日志里一行异常都没有。

CI：ruff / import-linter 2 contracts / pytest 374 passed（已含从 main 吸收的 test_generation_api.py、test_cors_preflight.py 等）。7 条变异全部杀掉，其中包括「publish 一律走异步 marshal」——它会让 #110 的隔离用例变红，正好把第 3 条锁住。

@xiaocheny214 你在 #182 提的那条（project_id 声明未使用 + 缺归属校验）在本版按主线口径处理了，也一并谢过——正是它让我去查主线，才发现自己那版方向反了。

[codecov]

Codecov Report

❌ Patch coverage is 86.17450% with 206 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...app/src/windup_app/server/orchestrator/executor.py	74.76%	53 Missing ⚠️
.../ai_engine/src/windup_ai_engine/slicing/quality.py	39.02%	50 Missing ⚠️
.../ai_engine/src/windup_ai_engine/slicing/extract.py	69.64%	17 Missing ⚠️
...s/app/src/windup_app/server/orchestrator/_fetch.py	46.15%	14 Missing ⚠️
...ine/src/windup_ai_engine/postprocess/rootmotion.py	48.00%	13 Missing ⚠️
.../ai_engine/src/windup_ai_engine/slicing/oneshot.py	88.07%	13 Missing ⚠️
...pp/src/windup_app/server/orchestrator/task_repo.py	84.72%	11 Missing ⚠️
...ai_engine/src/windup_ai_engine/postprocess/pack.py	83.92%	9 Missing ⚠️
.../framework/src/windup_framework/providers/matte.py	93.51%	7 Missing ⚠️
...ngine/src/windup_ai_engine/postprocess/pixelate.py	95.28%	5 Missing ⚠️
... and 10 more

📢 Thoughts on this report? Let us know!