feat(agc): 图片类生成后台化，生成面板可随时关闭并新增「生成任务」进度面板

- Rust 新增 asset_generation_tasks.rs：图片类生成拆成「提交即返回任务记录 + 后台 spawn 生成」，生成本身仍转调既有 generate_platform_art_asset_with_options_at（不复制生成 / 幂等 / 登记逻辑） - 任务账本落项目内 .agent/runtime/asset-generation-tasks/tasks.json（复用 agent runtime sidecar 原语），阶段文案 phaseDetail 由后端拥有，读取时把上次运行留下的非终态记录收口为「中断失败」，账本上限 50 条 - Rust 新增 IPC start_local_project_asset_generation / list_local_project_asset_generations 并在 main.rs 注册；同步命令 generate_local_project_asset 保留不动 - 新增前端纯模型 resourceCanvasAssetGenerationTaskModel.ts：任务状态机、在途判据、账本恢复、耗时文案 - 新增 resourceCanvasAssetGenerationQueue.ts：本地排队驱动器，第二条不发提交 IPC、前一条终态后自动补发，状态与阶段一律以后端账本为准，账本查不到该任务时按上限停止等待 - 两块生成浮层在提交期间放开 × / 遮罩 / Esc，次按钮在途时改为「后台运行并关闭」（关闭不等于取消请求），图片类面板的在途文案改为渲染后端 phaseDetail - 新增非模态「生成任务」面板（不铺遮罩 / 不做焦点陷阱 / 不进模态遮挡判据），显示状态、后端阶段、已耗时与素材名，已完成条目复用 pendingResourceFocusRef 聚焦链定位素材卡 - index.tsx 宿主接线：任务列表状态与 ref、提交回调不再读面板状态、按项目恢复任务账本、工具栏「生成任务」入口按钮与面板渲染点 - check-config.mjs：把已无前端调用方的同步命令 generate_local_project_asset 登记进 native-only 白名单 - 测试：新增「生成面板提交期间可关闭」「本地排队驱动器」「生成任务面板」三组用例； appSurface 生成载荷断言改为 start_local_project_asset_generation + list 轮询桩 - 文档：入口矩阵补 §4a 与验证命令、V3 验收 S11a 判据、decision-log 记录本次决策
2026-09-14 17:26:04 +08:00
parent 11beb65c36
commit bb7cbae118
16 changed files with 2582 additions and 122 deletions
@@ -6,7 +6,7 @@

 ## 1. 一句话

-功能画布 = 资源栏目页；栏目页左下角渲染一条由栏目 `category` 决定的工具栏，图片类入口走本地 `generate_local_project_asset`，音频入口复用既有无源生成链路，上传复用 `upload_local_asset`；生成 / 上传成功后一律走既有 manifest 刷新与资源定位。
+功能画布 = 资源栏目页；栏目页左下角渲染一条由栏目 `category` 决定的工具栏，图片类入口走本地 `start_local_project_asset_generation`（提交即返回、后台生成），音频入口复用既有无源生成链路，上传复用 `upload_local_asset`；生成 / 上传成功后一律走既有 manifest 刷新与资源定位。

 ## 2. 入口矩阵（事实源）

@@ -31,20 +31,26 @@

 ## 4. 请求载荷映射

-| 入口                  | IPC                             | 载荷要点                                                                                    |
-| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
-| 生成图片              | `generate_local_project_asset`  | `kind: 'image'`，比例 / 尺寸可调，默认 `1:1 · 1K`                                           |
-| 生成角色形象          | 同上                            | `kind: 'character'`，默认 `1:1 · 1K`                                                        |
-| 生成规范 → 图标规范   | 同上                            | `kind: 'icon-spec'`，固定 `1:1 · 1K`；缺权威规范图时 `outputPath: 'assets/art-spec.png'`    |
-| 生成规范 → 角色规范   | 同上                            | `kind: 'spec'`，固定 `1:1 · 1K`                                                             |
-| 生成规范 → 自定义规范 | 同上                            | `kind: 'spec'`，固定 `1:1 · 1K`                                                             |
-| 生成图标素材          | 同上                            | `kind: 'art-spritesheet'`，默认 `1:1 · 1K`；前置：已登记 `assets/art-spec.png`              |
-| 生成 UI 设计图        | 同上                            | `kind: 'ui-prototype'`，默认 `16:9 · 1K`；前置同上                                          |
-| 生成背景音乐          | `derive_local_project_resource` | `editKind: 'background-music'`、`generationMode: 'create'`、`sourceMediaType: 'audio/mpeg'` |
-| 生成音效              | `derive_local_project_resource` | `editKind: 'sound-effect'`、其余同上                                                        |
-| 上传                  | `upload_local_asset`            | `{ projectPath, fileName, mediaType, bytes }`                                               |
+| 入口                  | IPC                               | 载荷要点                                                                                    |
+| --------------------- | --------------------------------- | ------------------------------------------------------------------------------------------- |
+| 生成图片              | `start_local_project_asset_generation` | `kind: 'image'`，比例 / 尺寸可调，默认 `1:1 · 1K`                                      |
+| 生成角色形象          | 同上                              | `kind: 'character'`，默认 `1:1 · 1K`                                                        |
+| 生成规范 → 图标规范   | 同上                              | `kind: 'icon-spec'`，固定 `1:1 · 1K`；缺权威规范图时 `outputPath: 'assets/art-spec.png'`    |
+| 生成规范 → 角色规范   | 同上                              | `kind: 'spec'`，固定 `1:1 · 1K`                                                             |
+| 生成规范 → 自定义规范 | 同上                              | `kind: 'spec'`，固定 `1:1 · 1K`                                                             |
+| 生成图标素材          | 同上                              | `kind: 'art-spritesheet'`，默认 `1:1 · 1K`；前置：已登记 `assets/art-spec.png`              |
+| 生成 UI 设计图        | 同上                              | `kind: 'ui-prototype'`，默认 `16:9 · 1K`；前置同上                                          |
+| 生成背景音乐          | `derive_local_project_resource`   | `editKind: 'background-music'`、`generationMode: 'create'`、`sourceMediaType: 'audio/mpeg'` |
+| 生成音效              | `derive_local_project_resource`   | `editKind: 'sound-effect'`、其余同上                                                        |
+| 上传                  | `upload_local_asset`              | `{ projectPath, fileName, mediaType, bytes }`                                               |

-`generate_local_project_asset` 的完整参数是 `{ projectPath, kind, prompt, aspectRatio, imageSize, assetName, outputPath }`（Rust `src-tauri/src/commands.rs` 的 `generate_local_project_asset`，返回 `{ id, localPath, absolutePath, manifestPath }`）。
+`start_local_project_asset_generation` 的完整参数是 `{ projectPath, projectId, taskId, kind, prompt, aspectRatio, imageSize, assetName, outputPath }`（Rust `src-tauri/src/asset_generation_tasks.rs`），**提交即返回**一条任务记录（`taskId / status / phaseDetail / assetId / error` 等）；生成在 `tauri::async_runtime::spawn` 出来的后台任务里跑，账本落在项目内 `.agent/runtime/asset-generation-tasks/tasks.json`，进度由 `list_local_project_asset_generations` 读回。截图面板不再「等生成结束」，所以提交期间 × / 遮罩 / Esc /「后台运行并关闭」都能关面板（关闭 ≠ 取消）。
+
+## 4a. 本地排队与「生成任务」面板
+
+- **本地排队**：远端图片类生成共用 single-flight 输出槽（`standalone_platform_art_generation_runtime_context` 按 `outputPath` 派生 `run_id`），并发提交会在远端 POST 之前被拒。所以第二条提交停在**前端本地队列**里（不调用提交 IPC，阶段显示本地排队的「排队中。」），第一条终态后由同一条循环自动补发；判据是「存在 `dispatched && 未终态` 的任务时不派发下一条」。
+- **阶段文案只来自后端**：派发之后面板与任务列表渲染的都是后端账本给的 `phaseDetail`（「排队中。」/「正在生成。」/「生成已完成。」/失败原因），前端不拼阶段、不做百分比。
+- **「生成任务」面板是非模态浮层**：不铺全屏遮罩、不做焦点陷阱，**不参与** `isResourceCanvasFloatingPanelOpen` / `resourceCanvasHostGenerationPanelOpen` 的遮挡判据；入口按钮在 `index.tsx` 工具栏区（`aria-label="生成任务"`）。已完成任务可用「定位到素材」复用既有 `pendingResourceFocusRef` 聚焦链。

 ## 5. 参数口径与复用程度

@@ -71,12 +77,18 @@
 npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts
 npx vitest run apps/ai-game-creator-shell/tests/resourceCanvasBottomToolbar.test.tsx
 npx vitest run apps/ai-game-creator-shell/tests/resourceCanvasGenerationEntry.test.tsx
+npx vitest run apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationBackgroundClose.test.tsx
+npx vitest run apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationQueue.test.ts
+npx vitest run apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx
 npx vitest run apps/ai-game-creator-shell/tests/projectResourceLiveIntegration.test.tsx
 npm run agc:typecheck
 npm run check:encoding
 git diff --check
+cargo test -p genarrative-ai-game-creator-shell asset_generation_task
 ```

 - 模型层：四个栏目的工具集与顺序、未命中栏目返回空、「所有资源」与 `null` 返回空、二级菜单分流、比例 / 尺寸白名单收窄、前置判据、不可用原因、`outputPath` 策略。
 - 组件层：工具栏渲染与二级菜单开合、不可用入口可点击 + 原因可关闭、上传回调。
- AppSurface 层：进入栏目出现工具栏 / 回总览与展开态消失、每个图片类入口的 `generate_local_project_asset` 载荷、前置缺失可点击说明且零请求、音频入口走 `derive_local_project_resource`、上传走 `upload_local_asset` + 配对读清单、工具栏与右下 Dock 的几何契约。
+- 生成任务层：`resourceCanvasAssetGenerationTaskModel`（状态机 / 在途判据 / 恢复 / 耗时文案）、`resourceCanvasAssetGenerationQueue`（第二条不发提交 IPC、前一条终态后自动补发、失败与账本丢失都能收口）、`ResourceCanvasAssetGenerationTasksPanelView`（非模态、阶段文案来自后端记录、按 `assetId` 定位）、两块生成浮层在提交期间可关闭、「后台运行并关闭」文案。
+- Rust 层：`asset_generation_tasks` 的账本落项目内、排队阶段文案由后端拥有、进程重启把无人推进的记录收口为中断失败、账本上限与 task id 边界。
+- AppSurface 层：进入栏目出现工具栏 / 回总览与展开态消失、每个图片类入口的 `start_local_project_asset_generation` 载荷、前置缺失可点击说明且零请求、音频入口走 `derive_local_project_resource`、上传走 `upload_local_asset` + 配对读清单、生成面板关闭后任务仍在「生成任务」面板且第二条按本地排队补发、工具栏与右下 Dock 的几何契约。
@@ -57,7 +57,7 @@
 | **S15** 删除 | 工具条 / 标签面板「删除」→ 确认弹窗 | 三分支：① 无引用→直接删；② 被引用未勾选→只删素材、版本保留**悬空绑定**、界面不合成幽灵资源卡；③ 勾选→素材与该批版本在**同一次 manifest 写入**内一起删 | L413（版本只追加的唯一例外）、L532–533；#309 C5 | 弹窗 `ariaLabel="确认删除资源"`；被引用时出现 `被 N 个游戏版本使用` + 版本列表 + checkbox `把相关游戏版本一并删除`；无引用时该 body 整块不渲染 | **只摘登记、不删磁盘文件**；读引用命令精确名是 `read_local_project_asset_references` |
 | **S15a** 替换素材（含点选替换） | 选中被**当前版本**绑定的素材 → 工具条「替换素材」→ 候选弹窗（弹窗内可筛可选）；再点 footer「点选替换」→ 弹窗关闭、进入画布点选态 → 在画布上直接点目标素材 | 弹窗确认与点选是**同一条**写入链路（`replace_local_project_version_resource`，载荷逐字一致）：改该版本绑定、不建新版本；点选态下合法目标直接提交并自动退出点选态，非法目标零写入、**留在**点选态并在提示条上说明原因 | PRD §5.3 / §7.8 第 8 条；#309「直接替换」口径 | 点选态判据：候选弹窗 `role="dialog"` 已卸载；画布出现 `.game-resource-canvas-pick-hint`，文案含「在画布上点选要替换成的素材」与「点击空白处不会退出」，并有「取消」按钮；非法目标后提示条仍在且出现 `role="alert"`（「替换素材不兼容：分类不同」/「替换素材与源素材相同」/「替换素材未登记或已被删除」）；点选期间卡片 `aria-pressed` 不变（单击只用于点选）、源素材选中与工具条不因点空白或点非法目标而丢；Esc 退出点选（画布全局 Esc 的清选中不随之触发）；点选态下滚轮平移与缩放照常可用 | 点选只能点**当前画布上可见**的卡：目标在别的栏目时先切栏目（点选会话跨栏目存活，不因「收起资源」或切栏目结束）；空白点击不退出、也不清画布选中 |

-| **S11a** 栏目画布底部工具栏 | 进「UI 交互 / 角色与对象 / 场景与环境 / 音频」任一栏目 → 点左下角工具栏里的入口生成 → 「收起资源」回总览看工具栏消失 | 工具栏只在矩阵四个栏目（功能画布）渲染；图片类入口走 `generate_local_project_asset`，音频入口复用既有无源生成链路，上传复用 `upload_local_asset`；生成 / 上传成功后走既有 manifest 刷新与资源定位 | PRD §3.10、§7.9 | DOM 判据 `[data-resource-bottom-toolbar="<category>"]`（资源总览、「所有资源」展开态、文档、待归类、项目版本都**没有**这个节点）；工具栏是 `.game-resource-book-manager` 的直接子节点（`closest('.game-resource-book-scene')` 为 `null`）；每个入口一次 `generate_local_project_asset`，载荷逐字为 `{ projectPath, kind, prompt, aspectRatio, imageSize, assetName, outputPath }`（`kind` 映射见 PRD §7.9 第 3 条）；写入命令之后有 `get_local_game_project_revision` + `get_local_game_manifest` 的配对读；缺 `assets/art-spec.png` 时「生成图标素材 / 生成 UI 设计图」仍可点击（`aria-disabled="true"` 但**不是**原生 disabled）并给出含该路径的 `role="alert"` 原因、零生成请求；音频入口面板标题即「生成背景音乐」/「生成音效」且没有类型选择器 | ① 本地通道没有 `model` / `specType` / `replaceExisting` 入参：面板不渲染模型选择器，角色规范与自定义规范共用 `spec` 通道（靠 `assetName` 与提示词区分），「图标规范」在项目已有权威规范图时不再指向 `assets/art-spec.png`（否则会被 Rust 的防覆盖校验硬拒）；② 本轮不做生成视频 / 宣发素材 / 生成游戏场景 / 选择工具 / 抓手工具；③ 既有「生成素材」浮层入口只保留生成视频，音频入口只在音频栏目工具栏出现 |
+| **S11a** 栏目画布底部工具栏 | 进「UI 交互 / 角色与对象 / 场景与环境 / 音频」任一栏目 → 点左下角工具栏里的入口生成 → 「收起资源」回总览看工具栏消失 | 工具栏只在矩阵四个栏目（功能画布）渲染；图片类入口走 `start_local_project_asset_generation`（提交即返回、生成在后台跑），音频入口复用既有无源生成链路，上传复用 `upload_local_asset`；生成 / 上传成功后走既有 manifest 刷新与资源定位 | PRD §3.10、§7.9 | DOM 判据 `[data-resource-bottom-toolbar="<category>"]`（资源总览、「所有资源」展开态、文档、待归类、项目版本都**没有**这个节点）；工具栏是 `.game-resource-book-manager` 的直接子节点（`closest('.game-resource-book-scene')` 为 `null`）；每个入口一次 `start_local_project_asset_generation`，载荷逐字为 `{ projectPath, projectId, taskId, kind, prompt, aspectRatio, imageSize, assetName, outputPath }`（`kind` 映射见 PRD §7.9 第 3 条；`taskId` 是前端每次提交新铸的本地任务 id）；该命令提交即返回，之后有 `list_local_project_asset_generations` 轮询与 `get_local_game_project_revision` + `get_local_game_manifest` 的配对读；提交期间点 × / 遮罩 / Esc /「后台运行并关闭」任一都能关面板且请求继续（画布立即恢复可交互），关闭后任务仍出现在「生成任务」面板（入口按钮 `aria-label="生成任务"`，非模态浮层、无 `aria-modal`）并显示后端 `phaseDetail`；第一条未终态时提交第二条 → 第二条显示「排队中。」且生成提交 IPC 次数仍为 1，第一条终态后自动补发（次数变 2）；缺 `assets/art-spec.png` 时「生成图标素材 / 生成 UI 设计图」仍可点击（`aria-disabled="true"` 但**不是**原生 disabled）并给出含该路径的 `role="alert"` 原因、零生成请求；音频入口面板标题即「生成背景音乐」/「生成音效」且没有类型选择器 | ① 本地通道没有 `model` / `specType` / `replaceExisting` 入参：面板不渲染模型选择器，角色规范与自定义规范共用 `spec` 通道（靠 `assetName` 与提示词区分），「图标规范」在项目已有权威规范图时不再指向 `assets/art-spec.png`（否则会被 Rust 的防覆盖校验硬拒）；② 本轮不做生成视频 / 宣发素材 / 生成游戏场景 / 选择工具 / 抓手工具；③ 既有「生成素材」浮层入口只保留生成视频，音频入口只在音频栏目工具栏出现 |

 ### D 阶段 · 版本与运行

@@ -238,7 +238,7 @@ api-server 是否本次重启：□ 是  □ 否
 ### 7.3 已知未做 / 已取消（不要报成缺陷）

 1. **C6 的候选素材 / 替换关系 / 替换队列 / Agent 审核 / 批量提交整条取消**（#309）。PRD §5.3 的 `ProjectVersionResourceReplacement` 与 §3.2 的「创建下一迭代版本」**当前不实现**（2026-09-11 用户 DDL 口径「替换这块先做成直接替换」），但**保留为未来合同**：今天的实现是「改该版本的绑定，不建新版本」，验收见 PRD §7.8。
-2. **画布生成入口分为两条**（2026-09-13 起）：既有「生成素材」浮层入口只保留视频；音频（背景音乐 / 音效）与图片类（生成图片 / 生成规范 / 生成角色形象 / 生成图标素材 / 生成 UI 设计图）改由栏目画布左下角的底部工具栏承载，走本地 `generate_local_project_asset`。工具栏之外的其它无源生成类型仍会直接报"当前资源类型不支持无源生成"，这是设计而非缺陷。见 PRD §3.10 / §7.9 与下面的 S11a。
+2. **画布生成入口分为两条**（2026-09-13 起）：既有「生成素材」浮层入口只保留视频；音频（背景音乐 / 音效）与图片类（生成图片 / 生成规范 / 生成角色形象 / 生成图标素材 / 生成 UI 设计图）改由栏目画布左下角的底部工具栏承载，走本地 `start_local_project_asset_generation`（提交即返回、生成在后台跑完写回项目，任务账本在项目内 `.agent/runtime/asset-generation-tasks/`）。工具栏之外的其它无源生成类型仍会直接报"当前资源类型不支持无源生成"，这是设计而非缺陷。见 PRD §3.10 / §7.9 与下面的 S11a。
 3. **工具条 7 个动作按 opt-in 不渲染**：重绘 / 裁剪扩图 / 去背景 / 像素完美 / 切图集 / 提取 UI 素材 / 角色动画；只有 `快速编辑` 与 `下载` 真渲染（宿主另附加 `UI 编辑器` / `编辑标签` / `重命名`，以及**只在素材被当前版本绑定时**出现的 `替换素材`）。
 4. **C7 只做记录层 + UI 层**：切换版本即重载当前预览；版本化资源解析机制未实现。资源替换同样不做运行时资源重映射：改绑定只改「这个版本用哪些素材」的记录，运行画面要按游戏自身引用的资源路径渲染。
 5. **「首轮进度投影」无编码级判据**，可见性由底部 Agent 状态栏承载。