docs(prd): 同步功能画布生成入口的后台化事实

- 头部更新时间改为 2026-09-14 并说明本次同步内容,2026-09-13 的原口径与其余合同保持不变的声明保留
- §3.10 实现状态补 2026-09-14 后台化口径(提交即返回 + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板)
- §3.10 接线:图片类入口由 `generate_local_project_asset` 改写为 `start_local_project_asset_generation` + `list_local_project_asset_generations`
  + 项目内账本 `.agent/runtime/asset-generation-tasks/tasks.json`;音频 / 上传两条接线不变
- §3.10 新增「本地排队与进度可见」一条:第二条停在本地队列不调用提交 IPC、阶段文案由后端账本提供、
  非模态「生成任务」浮层与按素材卡定位
- §3.10 面板形态:补「提交期间面板不锁关闭」(×/遮罩/Esc/「后台运行并关闭」),并明确关闭不等于取消请求
- §3.10 前置规范图:命令名同步,并明确「后台化没有改这条前置判据」(`ui-prototype` / `art-spritesheet` 判据不变)
- §7.9 第 3 条:改写为 `start_local_project_asset_generation` 的载荷与「提交即返回」事实,
  保留「原载荷字段名与取值口径逐字不变」的说明,并补 `projectId` / `taskId` 两个新增字段
- §7.9 第 6 条:配对读改为「发生在该任务收口之后(提交命令不再等待生成)」,音频入口描述不变
- §7.9 新增第 8 条:生成期间可退出、面板关闭后进度可见、第二条本地排队(IPC 次数 1→2)、
  两条各自完成后各走一次「配对读 + 落卡」且 revision 单调
This commit is contained in:
2026-09-14 17:29:29 +08:00
parent bb7cbae118
commit 74b3760d0f
@@ -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.92026-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-132026-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. 非目标