GenarrativeAI/Genarrative
10
0
Fork 0
Code Issues 24 Pull Requests 7 Actions 1 Packages Projects 1 Releases Wiki Activity

修复资源分页与图片生成事务
Project CI / Repository checks (pull_request) Failing after 3m4s
Details
Project CI / Frontend tests (pull_request) Successful in 5m15s
Details
Project CI / Backend tests (pull_request) Successful in 5m19s
Details
Project CI / Native shell tests (pull_request) Successful in 15m46s
Details

Browse Source 
修复资源画布滚轮、拖拽取消、负坐标与快速编辑卡边界

修复生成占位、候选持久化、归档恢复与并发保存顺序

收紧 Host Port 合同并补齐回归测试

统一栏目合同并更新权威文档与项目记忆
This commit is contained in:
董羽秦
2026-08-23 20:47:10 +08:00
parent c97130f093
commit c01dc006f9
12 changed files with 749 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md
+6 -6
View File
@@ -2,7 +2,7 @@
## 目标
资源管理在空项目中展示现有按类型式分区展览。任一栏目出现资源后，“按依赖”和“按类型”共用同一套栏目分页画布：每个非空栏目拥有一个铺满资源管理区域的独立画布，栏目大纲悬浮在画布左侧中间，只显示图标和栏目名称，不占用画布布局宽度；顶部显示当前栏目标题，底部显示下一页标题。普通滚轮切换栏目，按住 Ctrl/Meta 的滚轮以指针为锚点缩放当前画布。两种模式唯一差异是“按依赖”在当前栏目内绘制引导线。资源详情是叠加在资源画板之上的非模态卡片；打开、切换和关闭详情都不得卸载背景工具栏、资源卡、依赖连线或重置 viewport、搜索和排序模式。
资源管理在空项目中展示现有按类型式分区展览。任一栏目出现资源后，“按依赖”和“按类型”共用同一套栏目分页画布：固定五个栏目各自拥有一个铺满资源管理区域的独立画布，空栏目也保留可打开的空画布；栏目大纲悬浮在画布左侧中间，只显示图标和栏目名称，不占用画布布局宽度；顶部显示当前栏目标题，底部显示下一页标题。普通滚轮切换栏目，按住 Ctrl/Meta 的滚轮以指针为锚点缩放当前画布。两种模式唯一差异是“按依赖”在当前栏目内绘制引导线。资源详情是叠加在资源画板之上的非模态卡片；打开、切换和关闭详情都不得卸载背景工具栏、资源卡、依赖连线或重置 viewport、搜索和排序模式。
图片资源从“编辑资源”进入持续精修草稿后，点击任意图片直接在图片下方显示快速编辑卡。每次快速编辑创建新的候选图，不覆盖来源图层；生成任务立即在画布中创建占位并进入任务侧栏。用户显式选择候选图“设为最终图”后，保持原资产 ID 不变，以事务方式切换 manifest 指向的正式 PNG；精修草稿和其它候选图继续保留。
@@ -12,8 +12,8 @@
### 栏目分页投影与设计文档缺失边界
- 非空栏目页只由当前权威资源投影构造：manifest assets、已完成任务的 artifacts、用户已导入附件和持久化 Agent 文本回执。前端不得扫描项目目录自行发明资源。
- 设计文档栏因此只有在上述来源存在 Markdown / TXT / JSON / YAML 等文档类条目，或存在 Agent 文本回执时才出现。若 manifest 没有文档资产、任务 artifacts 未完成且没有附件 / 回执，资源页不显示设计文档页；这是生成或登记缺失，不由 UI 补假数据。
- 栏目内容只由当前权威资源投影构造：manifest assets、已完成任务的 artifacts、用户已导入附件和持久化 Agent 文本回执。前端不得扫描项目目录自行发明资源。
- 固定栏目页始终为 `设计文档 -> 美术资源 -> 音乐音效 -> 游戏代码 -> 项目版本`。若某栏目没有对应投影，Dock 仍显示该栏目并允许打开空画布；空画布只表达“当前没有已登记资源”，不得由 UI 补假数据。
- Direct Codex 的游戏生成链路以 `game/index.html`、`game/style.css`、`game/game.js` 作为代码资产登记；是否额外产出设计文档由当前任务和 Agent 决定，资源页只消费已登记结果。
### 持续精修草稿
@@ -22,7 +22,7 @@
- 草稿 JSON 位于 `.agent/workbench/asset-canvas/drafts/<draftId>.json`，只保存图层、viewport、选择、generation 投影和提交记录，不内嵌图片 Base64。
- 入口图片图层使用 `project-asset` 引用稳定 `sourceAssetId`。AI 生成、导入和中间图片使用不可变 `draft-media`，二进制位于 `.agent/workbench/asset-canvas/media/<draftId>/<mediaId>.png`，引用同时冻结 SHA256、字节数和像素宽高。
- 候选媒体只属于精修草稿，不写入 manifest、不出现在资源总览，也不成为正式依赖。删除图层只删除草稿引用；物理媒体在确认不被草稿、generation ledger、staging、transaction journal 或恢复记录引用后延迟清理。
- generation 占位与稳定 `generationId` 绑定，持久化落点、目标尺寸、阶段和结果图层身份；成功候选必须使用同一落点，页面重启后从草稿和私有 ledger 恢复。
- generation 占位与稳定 `generationId` 绑定。确认后 UI 立即显示内存占位；宿主创建私有 ledger 并接受请求后，才把落点、目标尺寸、阶段和结果图层身份投影到公开草稿。接受前失败或异常不得留下公开 `generation-running` 记录；成功候选必须使用同一落点，页面重启后从草稿和私有 ledger 恢复。
### 最终图事务
@@ -75,7 +75,7 @@
### 失败生成任务归档与任务侧栏
- 用户界面的“删除失败任务”语义是归档，不物理销毁私有 generation ledger。只有平台明确失败的 `failed` 任务可归档；`reconciliation-required`、已受理、运行中和结果未知任务不得移出恢复队列。
- 归档命令校验 project、draft、generation 与 expected draft revision，在私有 ledger 先写入 `archived/archivedAt`，再从 `draft.generations` 公开投影移除并推进一次 revision。重放必须幂等；中途退出后以 archived ledger 收敛，重载不得复活已归档任务。
- 归档命令校验 project、draft、generation 与 expected draft revision，先把私有 ledger 写入可重放的 `archiving/archivedAt`，再从 `draft.generations` 移除公开投影并推进一次 revision；草稿删除成功并回读后才发布 `archived`。`archiving` 以及历史上已写 `archived` 但仍残留公开记录的状态都必须在恢复阶段幂等收敛，且不依赖图片生成服务凭证。
- 失败占位和右上角任务项复用同一个归档动作，成功后两处同时消失，其它任务、图层和候选不受影响。
- 任务侧栏折叠只属于当前会话 UI 状态，不写入 draft 或 manifest。视觉和交互复用现役美术画布：右上角独立“任务列表”图标按钮、20rem 白色模糊卡、总数徽标、`排队/生成中` 与 `已完成` 双 Tab、状态圆形图标、阶段进度和时间信息；折叠后只保留图标按钮，不显示摘要卡。用户显式新建 generation 时自动展开并切回活动 Tab，普通进度更新不得推翻用户已有折叠选择。Game Agent 的失败归档作为任务行扩展保留。
@@ -96,7 +96,7 @@
- 快速编辑卡底部统一承载“删除”“设为最终图”“修改”。“删除”只删除当前绑定图层并进入画布 history；“设为最终图”只对完整候选媒体可用；“修改”创建新 generation，不覆盖来源图层。
- 页面级返回、导入、撤销和重做不属于图片浮动工具条，本次不以复制另一套图片操作条替代已退役工具条。
- refine `/api/external/v1/editor/images/edits` 严格遵循 `EditorImageEditRequest`，不得携带 `assetKind`、`sourceImageSrc` 或 `sourceResourceId`。Game Agent 本地 kind 在登记编辑器来源前映射到现役 canonical kind；服务端安全业务错误必须结构化返回，不能把全部 400 折叠为同一个“平台明确拒绝”。
- 生成提交后立即创建画布占位和任务侧栏记录；排队、运行、远端完成、下载、候选就绪、失败和对账是任务级状态，不得用全屏 `canvas.generating/canvas.failed` 遮挡或终结整张画布。重新进入时，关键提交事务由 `host.recover()` 在 hydrate 前收敛；草稿 hydrate 完成后立即进入 `canvas.editing`，耗时的 `recoverImages()` 转为后台任务投影恢复，只更新任务、候选和 notice，不能继续锁住画布或因后台恢复失败切换为全屏失败。真正阻断草稿/提交/恢复的错误使用挂到 `document.body` 的全窗口 portal，必须覆盖整个 Tauri WebView，而不是只覆盖左侧画布区域。
- 生成提交后立即创建内存画布占位和任务侧栏记录，宿主接受后再持久化公开 generation 投影；排队、运行、远端完成、下载、候选就绪、失败和对账是任务级状态，不得用全屏 `canvas.generating/canvas.failed` 遮挡或终结整张画布。候选持久化必须先写入并回读候选媒体、图层和公开记录，再发布私有 `candidate-ready` 终态；生成返回时前端只合并候选与 generation 权威事实，并在保存队列屏障后把生成期间的最新本地画布状态写回，禁止全量 hydrate 覆盖并发编辑。重新进入时，关键提交事务由 `host.recover()` 在 hydrate 前收敛；草稿 hydrate 完成后立即进入 `canvas.editing`，耗时的 `recoverImages()` 转为后台任务投影恢复，只更新任务、候选和 notice，不能继续锁住画布或因后台恢复失败切换为全屏失败。真正阻断草稿/提交/恢复的错误使用挂到 `document.body` 的全窗口 portal，必须覆盖整个 Tauri WebView，而不是只覆盖左侧画布区域。
## 美术预览几何