Merge branch 'feat/agc-generation-task-progress' into fix/agc-canvas-acceptance-batch
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# AI 游戏创作项目开发工作台 PRD
|
||||
|
||||
更新时间：`2026-09-13`（新增功能画布底部工具栏入口矩阵 §3.10 / §7.9；右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，以及资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变）
|
||||
更新时间：`2026-09-14`（同步功能画布图片类生成后台化的当前事实：入口 IPC 改为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板，见 §3.10 / §7.9；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变）
|
||||
|
||||
## 1. 产品定位
|
||||
|
||||
@@ -142,7 +142,7 @@
|
||||
|
||||
### 3.10 功能画布底部工具栏（入口矩阵）
|
||||
|
||||
实现状态（2026-09-13）：功能画布 = 资源栏目页（`resourceBookState.view === 'child'`）。栏目页左下角的底部工具栏按 manifest 资产的**功能分类** `category` 分流，矩阵由用户 2026-09-13 拍板，工具项顺序即下表顺序（最右一项为「上传」）。
|
||||
实现状态（2026-09-13；2026-09-14 图片类生成后台化：提交即返回 + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板）：功能画布 = 资源栏目页（`resourceBookState.view === 'child'`）。栏目页左下角的底部工具栏按 manifest 资产的**功能分类** `category` 分流，矩阵由用户 2026-09-13 拍板，工具项顺序即下表顺序（最右一项为「上传」）。
|
||||
|
||||
| 栏目 | 工具栏里的生成入口 |
|
||||
| --- | --- |
|
||||
@@ -154,11 +154,12 @@
|
||||
|
||||
- 位置与层级：画布左下角（`left: 14px; bottom: 14px; z-index: 40`）。右下角是既有的缩放 / 撤销 Dock（`right: 14px; bottom: 14px`），左下角是画布上唯一两者都不占的稳定空位。工具栏是管理区 `.game-resource-book-manager` 的**直接子节点**、与画本场景并列，不进带 `scale()` 的场景层；二级菜单与「入口不可用原因」都贴着工具栏上沿弹出，不做内嵌内容。
|
||||
- 外壳用共享 chrome（`packages/image-canvas-react` 的 `CanvasToolbar / CanvasToolbarGroup / CanvasChromeButton`），样式落在 AGC 的 `resourceCanvasChrome.css`；共享包只承接通用表现，不含业务规则。
|
||||
- 接线：图片类入口走本地 IPC `generate_local_project_asset`（`kind` ∈ `image / character / spec / icon-spec / ui-prototype / art-spritesheet`）；音频入口复用既有的无源生成链路 `derive_local_project_resource`（`generationMode: 'create'`、`editKind` = `sound-effect` / `background-music`）；「上传」复用 `upload_local_asset`。生成 / 上传成功后一律用「配对读 `(revision, manifest)`」交给 `onManifestChange`，走既有 manifest 刷新与资源投影链路，不重算依赖图、不另写布局。
|
||||
- 面板形态：独立浮层（`ThemedModal`），**不在当前面板下面追加内容**；面板内不写功能说明或规则解释文案。
|
||||
- 接线：图片类入口走本地 IPC `start_local_project_asset_generation`（`kind` ∈ `image / character / spec / icon-spec / ui-prototype / art-spritesheet`；**提交即返回任务记录**，生成由 Rust 后台任务跑完写回项目，进度用 `list_local_project_asset_generations` 读回项目内账本 `.agent/runtime/asset-generation-tasks/tasks.json`）；音频入口复用既有的无源生成链路 `derive_local_project_resource`（`generationMode: 'create'`、`editKind` = `sound-effect` / `background-music`）；「上传」复用 `upload_local_asset`。生成 / 上传成功后一律用「配对读 `(revision, manifest)`」交给 `onManifestChange`，走既有 manifest 刷新与资源投影链路，不重算依赖图、不另写布局。
|
||||
- 本地排队与进度可见：同项目图片类生成共用 single-flight 输出槽，所以第一条未终态时第二条提交停在**前端本地队列**里（不调用提交 IPC，显示本地排队的「排队中。」），前一条终态后自动补发；任务状态与阶段文案（后端 `phaseDetail`）由任务账本提供，前端不拼阶段、不做百分比。工具栏另给一个**非模态**「生成任务」浮层（入口按钮 `aria-label="生成任务"`，不铺全屏遮罩、不做焦点陷阱、不参与模态遮挡判据）列出每条任务的状态 / 阶段 / 已耗时 / 素材名，已完成条目可点击定位到对应素材卡（复用既有 `pendingResourceFocusRef` 聚焦链）。
|
||||
- 面板形态：独立浮层（`ThemedModal`），**不在当前面板下面追加内容**；面板内不写功能说明或规则解释文案。生成在后台跑，所以**提交期间面板不锁关闭**：× / 遮罩 / Esc /「后台运行并关闭」四条路径都通；关闭只是收起表单，**不等于取消请求**（请求挂在任务上，不挂在面板生命周期上）；失败仍保留草稿可重试。
|
||||
- 参数口径：比例 / 尺寸选项来自网页端美术画布的纯模型（`src/components/image-editor/ImageCanvasGenerationModel.ts`），并按本地 IPC 白名单收窄（本地通道明确拒绝 `4:3`）；默认档 `1:1 · 1K`，生成 UI 设计图沿用网页端 UI 设计面板的默认 `16:9 · 1K`。本地 IPC 没有 `model` 入参，因此面板**不渲染模型选择器**（渲染一个改不了请求的控件就是假控件）。
|
||||
- 规范类和固定档：生成规范下的图标规范 / 角色规范 / 自定义规范都是固定档——只读展示当前规格，不给点了不生效的比例控件。本地 IPC 只有一条规范通道（`spec` 在 Rust 侧收口到 `icon-spec`），**没有 `specType` 入参**，因此角色规范与自定义规范共用该通道，靠素材名与提示词区分。
|
||||
- 前置规范图：`generate_local_project_asset` 的 `ui-prototype` 与 `art-spritesheet` 要求项目里已有登记并绑定当前账号的 `assets/art-spec.png`（`kind: icon-spec`、图片媒体类型、来源为画布）。缺前置时对应入口**保持可点击**并给出可执行的原因与指路（仓库口径：视觉不可用但可点击说明原因，不用原生 `disabled`），原因文案包含 `assets/art-spec.png` 与「生成规范 → 图标规范」。
|
||||
- 前置规范图：`start_local_project_asset_generation` 的 `ui-prototype` 与 `art-spritesheet` 要求项目里已有登记并绑定当前账号的 `assets/art-spec.png`（`kind: icon-spec`、图片媒体类型、来源为画布）。**后台化没有改这条前置判据**：Rust 侧仍是同一口径，前端 `projectHasIconSpecReference` 仍与它逐字对齐，缺前置时对应入口**保持可点击**并给出可执行的原因与指路（仓库口径：视觉不可用但可点击说明原因，不用原生 `disabled`），原因文案包含 `assets/art-spec.png` 与「生成规范 → 图标规范」。
|
||||
- 权威规范图由工具栏自身可满足：「图标规范」入口在项目尚无权威规范图时按 `assets/art-spec.png` 落盘；已有权威规范图时**不再传 `outputPath`**（Rust 侧 `replace_existing` 固定为 `false`，指向已存在文件会被硬拒绝「outputPath 已存在，禁止静默覆盖」），改为生成一张新的普通图标规范资产。这条前端策略不扩接口。
|
||||
- 音频入口收敛：音频画布的「生成背景音乐 / 生成音效」由工具栏承载，既有「生成素材」浮层入口**只保留生成视频**（视频能力不删，只是不出现在工具栏里）。
|
||||
- 本轮明确不做：生成视频（保留在既有浮层入口）、宣发素材、生成游戏场景、画布级「选择工具 / 抓手工具」（AGC 现无画布级工具模式）。这五类都**不得**出现在工具栏里。
|
||||
@@ -652,11 +653,12 @@ type ProjectAgentMudPointAttribution = {
|
||||
|
||||
1. 工具栏只在资源栏目页且分类命中矩阵四个栏目时渲染；资源总览、「所有资源」展开态、文档 / 待归类 / 项目版本都不渲染。稳定 DOM 判据 `[data-resource-bottom-toolbar="<category>"]`；总览与「所有资源」展开态下该节点必须不存在。
|
||||
2. 工具栏是管理区 `.game-resource-book-manager` 的直接子节点、与画本场景并列（`closest('.game-resource-book-scene')` 为 `null`），且与右下角 Dock 互不抢位（左下角锚定：`left` 有值、`right` 无声明；Dock 相反）。二级菜单只在展开时出现，展开时可被外部点击 / Esc 收起。
|
||||
3. 每个图片类入口一次提交**一条** `generate_local_project_asset`，载荷字段逐字为 `{ projectPath, kind, prompt, aspectRatio, imageSize, assetName, outputPath }`；`kind` 映射：生成图片 `image`、生成角色形象 `character`、图标规范 `icon-spec`、角色规范 / 自定义规范 `spec`、生成图标素材 `art-spritesheet`、生成 UI 设计图 `ui-prototype`。
|
||||
3. 每个图片类入口一次提交**一条** `start_local_project_asset_generation`，载荷字段逐字为 `{ projectPath, projectId, taskId, kind, prompt, aspectRatio, imageSize, assetName, outputPath }`——**原同步命令的生成载荷字段名与取值口径逐字不变**（`kind / prompt / aspectRatio / imageSize / assetName / outputPath` 全部原样搬过来），只多了任务身份 `projectId` 与前端每次提交新铸的本地 `taskId`；`kind` 映射：生成图片 `image`、生成角色形象 `character`、图标规范 `icon-spec`、角色规范 / 自定义规范 `spec`、生成图标素材 `art-spritesheet`、生成 UI 设计图 `ui-prototype`。命令**提交即返回**一条任务记录，生成在 Rust 后台任务里跑，状态与阶段由 `list_local_project_asset_generations` 从项目内账本读回。
|
||||
4. 比例 / 尺寸选项**不含**本地通道拒绝的 `4:3`；比例与尺寸的切换都进入载荷；固定档规范入口只读展示当前规格（如 `1:1·1K`），不渲染可点比例控件。
|
||||
5. 缺权威规范图时「生成图标素材 / 生成 UI 设计图」保持可点击、给出含 `assets/art-spec.png` 的原因说明，且**不发出任何生成请求**；「图标规范」此时把 `outputPath` 指向 `assets/art-spec.png`；项目已有权威规范图时 `outputPath` 为 `null`（两种状态各一条用例）。
|
||||
6. 生成 / 上传成功后走既有刷新路径：`get_local_game_project_revision` + `get_local_game_manifest` 的配对读发生在写入命令之后，结果交给 `onManifestChange`；音频入口提交的是 `derive_local_project_resource`（`editKind` = `sound-effect` / `background-music`、`generationMode: 'create'`、`sourceMediaType: 'audio/mpeg'`）。
|
||||
6. 生成 / 上传成功后走既有刷新路径：`get_local_game_project_revision` + `get_local_game_manifest` 的配对读发生在**该任务收口之后**（提交命令不再等待生成，配对读由任务终态驱动，顺序仍在写入之后），结果交给 `onManifestChange`；音频入口提交的是 `derive_local_project_resource`（`editKind` = `sound-effect` / `background-music`、`generationMode: 'create'`、`sourceMediaType: 'audio/mpeg'`）。
|
||||
7. 既有「生成素材」浮层入口只呈现视频：面板不再渲染音效 / 背景音乐类型选择器（单类型入口没有类型选择器），音频入口只出现在音频栏目工具栏。
|
||||
8. 生成期间可退出与本地排队（2026-09-14）：提交后点 × / 遮罩 / Esc /「后台运行并关闭」任一都能关面板，画布立即恢复可交互，关闭不取消请求；面板关闭后任务仍在「生成任务」面板（非模态浮层，无 `aria-modal`）里显示后端 `phaseDetail`；第一条未终态时提交第二条 → 第二条显示「排队中。」且生成提交 IPC 次数仍为 1，第一条终态后自动补发（次数为 2）；两条各自完成后各走一次「配对读 + 落卡」，manifest revision 单调、不被后到者覆盖。
|
||||
|
||||
## 8. 非目标
|
||||
|
||||
|
||||
@@ -8674,3 +8674,14 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- 决策：复用判据收窄为**同一条写调用链（同一线程）重入**——按锁路径登记真实持锁线程，只有当前线程就是持锁线程时才返回 advisory guard；本进程其它线程的争用继续走有界等待与终态占用。自主游戏构建流水线的并行专家动作豁免保持不变；跨进程占用、残留回收、权限分类、等待预算和错误文案不变。
|
||||
- 边界：锁定这些不变量的既有用例（`project_tools` / `command_runtime` / `parallel_actions` / `runtime_state` / `response_stream` / `direct_tool_bridge` / `ui_editor::persistence`）不得为了让锁语义通过而改写；用「同线程自持锁」模拟「另一个写者」的两条用例改为**在另一条线程持锁**，断言语义不变。同进程跨线程重入（持锁链在 `await` / `spawn_blocking` 后于其它线程再取锁）仍会等满预算，出现现场时按 2026-08-27 的既有处置改用 `*_locked` 入口，不放宽判据。
|
||||
- 关联文档：[项目客户端占用锁收敛里程碑](../plans/【里程碑】项目客户端占用锁收敛-2026-09-14.md)、[踩坑记录](pitfalls.md)。
|
||||
|
||||
## 2026-09-14 AGC 图片类生成后台化：提交即返回 + 项目内任务账本 + 本地排队
|
||||
|
||||
- 背景：栏目画布图片类入口原先是一条同步 IPC `generate_local_project_asset`，一次调用最长等 35 分钟；提交期间两块生成浮层把 × / 遮罩 / Esc /「取消」全部锁死，用户既关不掉面板也看不到进度。远端图片类生成共用 single-flight 输出槽（`standalone_platform_art_generation_runtime_context` 按 `outputPath` 派生 `run_id`），并发提交会在远端 POST 之前被拒。
|
||||
- 决策（后台化）：新增 `start_local_project_asset_generation`（校验入参 → 落 `queued` 记录 → `tauri::async_runtime::spawn` 派发 → 返回任务记录）与 `list_local_project_asset_generations`（读回账本）。生成本身仍转调既有 `generate_platform_art_asset_with_options_at`（幂等账本、计费、下载校验、manifest/revision 登记、本地预览都不复制），同步命令 `generate_local_project_asset` **保留不动**。
|
||||
- 决策（账本落项目内）：`.agent/runtime/asset-generation-tasks/tasks.json`，复用既有 agent runtime sidecar 读写原语（临时文件 + rename）；非终态且不在本进程 live 集合里的记录在读取时收口为「上次运行中断」失败，不假装它还在跑；账本上限 50 条按创建时间淘汰。
|
||||
- 决策（阶段文案归后端）：`phaseDetail` 由 Rust 拥有（「排队中。」/「正在生成。」/「生成已完成。」/失败原因），前端面板与「生成任务」面板只渲染该字符串，不拼阶段、不做百分比。后端目前没有可播报的中间阶段（生成通道不暴露 job 的远端 `phaseDetail`），所以不伪造「正在处理。」这类前端文案。
|
||||
- 决策（本地排队）：第二条提交停在**前端本地队列**（`dispatched=false`，不调用提交 IPC，阶段显示本地排队的「排队中。」），第一条终态后由同一条循环自动补发。判据是「存在 `dispatched && 未终态` 的任务时不派发下一条」——后端 single-flight 拒绝并发，前端排队是它的对应设计而不是重复实现。
|
||||
- 决策（面板可关 + 非模态任务面板）：两块生成浮层在提交期间放开 × / 遮罩 / Esc，提交按钮旁给「后台运行并关闭」；**关闭 ≠ 取消**（表单的 `await` 挂在该任务的终局上，不是面板生命周期）。新增「生成任务」非模态浮层（不铺遮罩、不做焦点陷阱、**不进** `isResourceCanvasFloatingPanelOpen` / `resourceCanvasHostGenerationPanelOpen` 遮挡判据），入口按钮 `aria-label="生成任务"`；已完成的条目按 `assetId` 复用既有 `pendingResourceFocusRef` 聚焦链定位素材卡。
|
||||
- 影响范围：新增 `apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs`（+ `main.rs` 注册）、`src/features/resource-canvas/{resourceCanvasAssetGenerationTaskModel.ts,resourceCanvasAssetGenerationQueue.ts,ResourceCanvasAssetGenerationTasksPanelView.tsx}`；改动 `ResourceCanvasAssetGenerationPanelView.tsx` / `ResourceCanvasGenerationPanelView.tsx` / `src/view/project-development/index.tsx`；测试改动 `tests/{resourceCanvasAssetGenerationBackgroundClose.test.tsx,resourceCanvasAssetGenerationQueue.test.ts,resourceCanvasAssetGenerationTasksPanel.test.tsx}`（新增）与 `tests/appSurface/project-development.suite.ts`（把「每个入口一次 `generate_local_project_asset`」改成 `start_local_project_asset_generation` + `list_...` 轮询桩，载荷断言逐字不变）。**未动**：external v1 / OpenAPI、`packages/`、SpacetimeDB、音频入口的 pending-edit 账本语义、生成参数与 IPC 载荷字段名。
|
||||
- 关联文档：`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`（§4 / §4a / §8）、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11a / §7.3）。
|
||||
|
||||
@@ -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 阶段 · 版本与运行
|
||||
|
||||
@@ -246,7 +246,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 状态栏承载。
|
||||
|
||||
Reference in New Issue
Block a user