合并 master：资源画布与图片精修链路

四处冲突的取舍： - view/project-development/index.tsx：master 把 UI 编辑器从顶层三元分支挪进 workbench stage 内部，改用 `is-ui-editor` 类切单栏、运行与播放按钮在编辑器打开时禁用，并去掉了 `!focusedResource` 守卫。取 master 的结构，再把分支的 `is-conversation-only` 追加进同一个 className。 - styles.css：双方各加一条 `.game-workbench-layout` 规则（分支 `is-conversation-only`，master `is-ui-editor`），两条都留。 - tests/appSurface/home.suite.ts：双方在同一位置各加一个用例（分支的做方案根 run 路由、master 的直连美术实时刷新），两条都留。 - SupervisorChatOnlyView.tsx：master 在该文件只有 prettier 重排版，没有逻辑改动，取分支的 projectedRuntime 与 descendantsStillActive 判据。验证：agc:typecheck 通过；cargo check --all-targets 0 error；eslint、 prettier、cargo fmt、check:encoding 通过；AGC 前端 931 passed / 1 failed，唯一失败是本机已知的 Windows symlink EPERM 基线。appSurface 从 425 增至 426，双方新增用例都在。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-24 12:43:53 +00:00
parent 41adfea134 b00a3f8057
commit 7d92076071
43 changed files with 13024 additions and 2271 deletions
@@ -13,7 +13,7 @@
 - 统一资源编辑命令新增 `generationMode=create|derive`：`create` 用于无源生成视频、音效和背景音乐，`derive` 保持现有“基于已有资源派生”。视频新建请求不再携带 `referenceVideoSrcs`；音效 / 背景音乐新建使用同款文本生成端点，但提示词前缀改为“生成新音频”。
 - 图片资源新增“生成动画”派生入口：复用 `/api/external/v1/editor/character-animations/generations`（账号模式自动映射 `/api/editor/character-animations/generations`），以源图片的稳定 objectKey、真实宽高和固定 `seedance2.0-fast / 720p / same / 32帧 / 4秒` 参数提交；完成后下载 `previewVideoPath` 预览视频并以 `character-animation` 资源类型登记为本地 MP4/WebM 媒体，避免只保存首帧。
 - 本地 manifest 资产模型新增 `imageSequenceFrames` 与 `imageSequenceDurationMs`：角色动画完成时把远端 `frames` 与 `durationSeconds` 随账本持久化，恢复或重新提交后仍写回 manifest，前端资源投影同步暴露。
- 资源页顶部新增“生成视频 / 生成音效 / 生成背景音乐”三个入口，图片聚焦态新增“生成动画”按钮；统一资源编辑面板按 `generationMode` 显示“新建媒体资源”或“编辑现有资源”。
+- 资源页顶部不再展示“生成视频 / 生成音效 / 生成背景音乐”手动新建入口；无源资源生成继续由 Agent 语义工具调用统一资源生成能力。图片聚焦态保留“生成动画”按钮；统一资源编辑面板继续按 `generationMode` 区分“新建媒体资源”或“编辑现有资源”。
 - 新建视频 / 音效 / 背景音乐时，先复用 `prepare_external_canvas_generation_context` 创建或匹配同名画板项目与素材库目录，并在生成请求中携带 `projectId / assetFolderId / canvasCompletion`，结果同时进入平台画布 / 素材库与本地 manifest。
 - durable 账本新增 `remoteLegacyPublicPath` 字段（旧账本默认缺省），用于角色动画预览视频的换签下载与恢复；资源提交、轮询、下载、manifest 提交和恢复队列继续复用既有资源编辑事务链。
 - 资源编辑请求指纹纳入 `generationMode`，同一 `operationId` 换生成模式重试时不再按旧账本模式恢复；旧账本继续通过 legacy 指纹兼容。
@@ -1114,6 +1114,7 @@ game-project/

 - `.agent/manifest.json` 的存储写边界使用同目录持久文件锁跨线程、跨进程串行化；锁必须覆盖旧 manifest 读取、不可变版本前缀校验、临时文件安装和安装后回读一致性校验。锁文件拒绝符号链接、非普通文件和异常所有权 / 硬链接；Windows 使用不共享写句柄，Unix 使用 `O_NOFOLLOW + flock`。旧快照在新版本安装后只能被拒绝，不能覆盖已追加版本。
 - 后台 Agent 的 manifest 变化以共用 Runtime 状态投影 / 终态 emitter 作为失效因果点：`game-creator-agent-runtime-update` 的 Rust / TypeScript DTO 固定携带 `manifestInvalidated`，且 App 必须在 Supervisor、selected agent、session 和 run 身份的任何 early return 之前处理失效。GUI 进程内 Runtime 直接发该事件；External Runner 是独立进程、没有 GUI `AppHandle`，因此 Runner 协议 v5 的 `runner.attach_gui_owner` 必须登记 GUI 创建的随机 loopback 端口和 64 位随机令牌，Runner 的同一 emitter 通过受令牌保护的短连接转发 `game-creator-manifest-invalidated`。两条路径都只传项目路径与 Agent 身份，不复制 manifest，也不靠轮询补偿。
+- Direct Codex 不伪造普通 Agent Runtime state。每张平台美术在本地文件与 manifest 提交成功后，统一通过 standalone `game-creator-manifest-invalidated` 发送 `projectPath + direct-codex-art`；只读恢复的已付费源图同样在 `register_local_asset_at` 成功后发送，下载、解码、文件写入或登记失败时不得发送成功失效。前端仍把 `game-creator-agent-progress` 仅用于进度文案；Direct Codex 整体命令成功、失败或超时 reject 后都追加一次 manifest 最终对账，只有完整成功才启动本地预览。
 - App 收到当前项目的 Runtime / relay 失效后重新调用 `get_local_game_manifest`。重读按项目 single-flight 合并事件风暴；读取中再到达失效只追加一轮串行重读，不并发提交同项目响应。应用结果同时校验组件仍挂载、当前项目路径和项目 scope version；项目切换、组件卸载或旧 scope 的迟到响应不得覆盖新项目。Project Supervisor 对外发布前以“revision 前读 -> manifest -> revision 后读”取得一致快照，再通过 `onManifestChange(projectPath, manifest, metadata)` 携带 `projectId + revision + source`；启动器按 `projectPath + projectId` 只接受更高 revision，同 revision 只接受内容一致的重复，旧轮询和同 revision 分叉都不得覆盖。资源列表、依赖图输入、任务状态、运行入口和正式版本卡必须在当前页面实时重投影，不要求关闭或重开项目。集成测试记录“事件未重新打开项目”的调用基线前，必须先等待项目写入最近列表后触发的只读目录状态刷新完成，不能把这项合法后台检查误算成失效事件副作用。
 - `.agent/agent.db` 有界尾部读取报告截断时，审计 producer 映射失败关闭，不生成基于不完整审计的 producer、task flow 或对应任务环。前端收到截断 DTO 时只剔除 `producerAssignments`、`taskFlows` 与对应 `cyclicTaskIds`；Rust 根据当前 manifest、精确资源引用和仍可信任务深度下限返回的 `dependencyDepths` 继续保留，前端只校验资源仍存在且深度为非负安全整数，不得自行重算或压平权威深度。精确引用边、reference connection index、`cyclicResourceIds` 与 unresolved references 同样继续保留。
  -- 资源依赖 SVG 继续作为不可交互装饰层隐藏，但 dependency 画布通过 `aria-describedby` 提供当前可见精确引用和任务流的文本等价列表。中央资源聚焦按稳定 `resourceId` 驱动焦点状态：仅 `null -> id` 或 `idA -> idB` 聚焦详情 region，同一 ID 的 manifest 重投影不得抢走音频、视频、链接或关闭按钮焦点；显式收起和 Escape 恢复画布滚动并优先聚焦原触发卡片。聚焦资源被删除时清理 stale focused / selected ID，关闭详情并把焦点落到资源搜索框；项目切换或运行视图切换清除旧恢复意图，不得恢复旧项目卡片。橙色引用线及箭头使用对 `#fffdfa` 画布达到至少 `3:1` 的颜色。
@@ -0,0 +1,114 @@
+# Game Agent 资源自由画板与快速编辑
+
+## 目标
+
+资源管理的“按依赖”视图使用统一世界坐标的自由画板，支持拖拽平移、滚轮平移以及按住 Ctrl/Meta 的锚点缩放。资源详情是叠加在资源画板之上的非模态卡片；打开、切换和关闭详情都不得卸载背景工具栏、资源卡、依赖连线或重置 viewport、搜索和排序模式。
+
+图片资源从“编辑资源”进入持续精修草稿后，点击任意图片直接在图片下方显示快速编辑卡。每次快速编辑创建新的候选图，不覆盖来源图层；生成任务立即在画布中创建占位并进入任务侧栏。用户显式选择候选图“设为最终图”后，保持原资产 ID 不变，以事务方式切换 manifest 指向的正式 PNG；精修草稿和其它候选图继续保留。
+
+资源总览中的美术图片卡按真实纵横比计算展示矩形，并使用统一边界限制极端长图或宽图。非图片资源继续使用固定卡片尺寸。
+
+## 权威数据与持久化
+
+### 持续精修草稿
+
+- 一个图片 `sourceAssetId` 唯一发现一个活动精修 `draftId`；重新进入时恢复原草稿，不依赖进程内状态或创建平行画布。
+- 草稿 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 恢复。
+
+### 最终图事务
+
+- “最终图”权威定义为 manifest 中 `sourceAssetId` 当前指向的正式文件，不使用前端布尔值作为业务真相。
+- 前端只提交 `projectId + draftId + sourceAssetId + sourceLayerId + expectedProjectRevision + expectedDraftRevision + commitId + idempotencyKey`。后端重新读取权威草稿，验证目标图层属于当前 refine 草稿并引用完整 PNG `draft-media`。
+- 每次提交将候选图安装到新的 `assets/canvas/<name>--<commitId>.png`，保持原 `assetId` 不变，只更新该 manifest 条目的 `mediaType/localPath`，随后推进 project revision。已登记 refine 入口必须保留原 `source.resourceId`（例如 `editor-resource-*`）；只有 create 或缺少登记来源的本地资产才补为 `local-asset:<assetId>`。事务回读校验按同一来源解析规则验证，不能无条件要求 `local-asset:*`。
+- 文件、manifest、revision、ledger、draft 和事件继续使用现有 transaction journal、before/after snapshot、回读验证、幂等返回、回滚与 reconciliation 合同；任何 revision 冲突都不得静默覆盖其它窗口的更新。
+- 提交成功后草稿回到可编辑状态，并记录 `sourceLayerId + mediaSha256 + assetId + commitId + committedProjectRevision` 的最后提交投影。不得清空候选图或永久终结草稿；再次选择其它候选图可产生下一次最终图事务。
+- 删除已提交候选图层只影响草稿；正式项目资源继续指向已验证的 PNG。当前最终图显示必须由 manifest/revision 与最后提交摘要共同投影。
+
+### 精修来源规范化
+
+- refine 主来源不得仅凭 manifest 中已有的 `source.resourceId` 判断其可直接用于 `sourceReferenceId`。历史 Game Agent 资源可能以 `game-background`、`art-spritesheet` 等私有 kind 登记，虽然 ID 形态是正式 Editor Resource，仍不满足 External v1 快速编辑的 canonical 类型合同。
+- 客户端必须从本地正式图片重新取得受控字节，按现役映射登记 canonical 主来源，例如 `game-background -> scene`、`art-spritesheet -> icon-spritesheet`；`/api/external/v1/editor/images/edits` 仍只提交登记后返回的业务资源 ID，不扩大服务端白名单，也不在 edit DTO 中补发 `assetKind`。
+- canonical 来源缓存属于本地私有恢复数据，不写入 manifest。缓存身份至少绑定平台服务身份、平台 owner、Editor Project ID、源图片 SHA256 与 canonical kind；任一身份或图片内容变化都必须重新登记。
+- 缓存命中时复用已登记资源，避免每次快速编辑重复上传。平台明确返回来源不存在或类型不支持且请求尚未入队时，可以失效缓存并重建一次；不确定受理、已受理和对账状态不得换幂等键重提。
+
+### 本地图片批量导入
+
+- Tauri 正式链路使用原生多选文件对话框，不以隐藏 DOM `input[type=file]` 作为唯一入口。取消选择返回受控 `cancelled`，不修改草稿。
+- 一批导入在 Rust 中完成安全读取、PNG/JPEG/WebP 签名与尺寸校验、总量校验、媒体安装、图层追加和一次 draft revision 推进。全部身份、路径、层序和新 revision 必须在首个文件安装前完成验证；任一文件失败时不得留下公开部分成功，回滚删除失败必须返回明确对账错误。草稿写入结果无法回读确认时保留本批媒体并进入显式对账错误，禁止冒险删除可能已被新草稿引用的文件。
+- 导入图层保存真实原始宽高，显示矩形保持比例并受当前 viewport 可见边界限制；首张落在当前视口中心附近，多张确定性错位并避让现有图层。成功后返回权威 draft 与 `importedLayerIds`，前端 hydrate 后选中并定位。
+- UI 必须区分正在选择、正在导入、已导入数量和安全失败原因。不得把文件读取异常或 host failure 留成未处理 Promise，也不得依赖稍后的前端 autosave 才把已写媒体绑定到图层。
+
+### 失败生成任务归档与任务侧栏
+
+- 用户界面的“删除失败任务”语义是归档，不物理销毁私有 generation ledger。只有平台明确失败的 `failed` 任务可归档；`reconciliation-required`、已受理、运行中和结果未知任务不得移出恢复队列。
+- 归档命令校验 project、draft、generation 与 expected draft revision，在私有 ledger 先写入 `archived/archivedAt`，再从 `draft.generations` 公开投影移除并推进一次 revision。重放必须幂等；中途退出后以 archived ledger 收敛，重载不得复活已归档任务。
+- 失败占位和右上角任务项复用同一个归档动作，成功后两处同时消失，其它任务、图层和候选不受影响。
+- 任务侧栏折叠只属于当前会话 UI 状态，不写入 draft 或 manifest。视觉和交互复用现役美术画布：右上角独立“任务列表”图标按钮、20rem 白色模糊卡、总数徽标、`排队/生成中` 与 `已完成` 双 Tab、状态圆形图标、阶段进度和时间信息；折叠后只保留图标按钮，不显示摘要卡。用户显式新建 generation 时自动展开并切回活动 Tab，普通进度更新不得推翻用户已有折叠选择。Game Agent 的失败归档作为任务行扩展保留。
+
+## 操作边界
+
+- 依赖画布复用 `@genarrative/image-canvas-core` 的 viewport 计算，并复用现有资源卡片、布局和依赖连线模型。
+- 依赖模式不使用资源分区滚动条、分区缩放或分区高度操作作为主要导航；分区仍是画布世界中的视觉分组。
+- 依赖画布存在不可见导航边界：以当前项目全部资源的权威布局矩形、真实卡片尺寸、分区标题和世界 extent 的并集为内容范围，再在屏幕坐标四周外扩 `96px` 安全留白。搜索、详情卡和临时隐藏不得缩小边界，只有项目资源或权威布局真正变化时才重算。
+- 滚轮平移、指针拖动画布、Ctrl/Meta 缩放、复位以及容器 resize 后都必须经过同一个 viewport 约束。缩小下限是“全部内容加安全留白刚好可见”的 fit scale；内容小于视口时居中，内容大于视口时四条边最多移动到安全留白位置，禁止把资源整体拖出屏幕。边界只约束会话 viewport，不写入 manifest 或资源布局 sidecar，也不显示可见边框。
+- 统一世界画板显示当前可见资源之间的全部合法精确引用，包括跨视觉分组引用；装饰 SVG 与视觉隐藏的关系说明消费同一组可见边，搜索隐藏任一端点时两者同步移除。任务流仍只参与同类型布局聚类，不绘线也不进入关系说明。
+- 资源详情卡包含元数据、媒体预览和“编辑资源”操作，但不使用全屏 backdrop、不声明 `aria-modal=true`、不把 `focusedResource` 作为背景工具栏渲染条件。桌面端允许继续操作背景画板；窄屏可以使用有边界的贴边卡，但背景组件必须保持挂载。
+- 资源详情卡定位相对 `.game-workbench-stage`，桌面端在中间主视窗居中并受主视窗宽高边界约束；禁止使用相对整个窗口的右上角 `position: fixed` 定位。
+- 图片选中后的浮动工具栏整体退役。普通点击图片直接打开唯一的图片下方快速编辑卡；拖动不误触发，点击另一张图片切换卡片，点击画布空白关闭卡片。
+- 快速编辑卡底部统一承载“删除”“设为最终图”“修改”。“删除”只删除当前绑定图层并进入画布 history；“设为最终图”只对完整候选媒体可用；“修改”创建新 generation，不覆盖来源图层。
+- 页面级返回、导入、撤销和重做不属于图片浮动工具条，本次不以复制另一套图片操作条替代已退役工具条。
+- 资源自由画板顶部不展示“生成视频”“生成音效”“生成背景音乐”和“新增 UI 设计”等手动新建入口；顶部只保留播放、未完成编辑恢复、排序与复位等画布级动作。无源资源生成由 Agent 语义工具进入既有生成合同，已有资源的编辑、图片“生成动画”和精修图片“修改”入口不受影响。
+- 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，而不是只覆盖左侧画布区域。
+
+## 美术预览几何
+
+- 图片预览读取返回真实 `pixelWidth/pixelHeight`。PNG、JPEG、WebP 复用 Tauri 已完成的头部尺寸校验；GIF、AVIF、BMP 和安全 SVG 的媒体预览也只读取受限头部/根元素元数据，无法安全解析时回退固定卡片尺寸。
+- 第一版图片展示边界为最大宽 `220px`、最大高 `180px`、最小短边 `96px`，展示框纵横比夹取在 `1:2..2:1`；图片始终 `object-fit: contain`，不得拉伸或裁剪。
+- `resourceCanvasLayoutModel` 的碰撞、自动布局、section/world extent、适配视口和拖动几何必须消费每个资源自己的 `width/height`，不能只改 CSS。
+- `ResourceDependencyOverlay` 的端点和绕障矩形必须消费同一资源矩形表，保证横图、竖图和 fallback 卡片的连线均对齐。
+- `code/document/audio/version` 继续使用固定 `180x128`；尺寸只属于展示投影，不写入 manifest，也不成为第二份资源业务真相。
+
+## 验收
+
+1. 在依赖视图拖拽画布可以平移，滚轮可以平移，Ctrl/Meta + 滚轮以指针位置为锚点缩放，复位按钮可以适配全部依赖内容；极端拖拽和连续缩小均停在全部资源加 `96px` 安全留白形成的隐藏边界，搜索过滤不会改变该边界。
+2. 同类型和跨视觉分组的合法精确引用均在统一世界中连线，并具有与当前可见连线一致的无障碍关系说明；搜索隐藏任一端点后连线和说明同时消失。
+3. 点击任意资源后“新增资源 / 按依赖 / 按类型 / 复位”仍保持挂载和原状态；详情为非模态独立卡片，背景画板 viewport、搜索、排序、卡片和连线不卸载、不重置。
+4. 图片资源点击“编辑资源”后恢复唯一活动 refine 草稿，入口图进入默认参考；点击任意图片直接在其下方显示快速编辑卡，图片上方不再出现浮动工具栏。
+5. 快速编辑卡底部显示适用的删除、设为最终图和修改动作。拖动图片不误触发卡片；删除只影响草稿图层；候选设为最终图后保持原 asset ID、更新正式 PNG，草稿及其它候选仍可继续编辑。
+6. 点击修改后立即创建避让现有内容的生成占位和任务侧栏记录；成功图在同一落点出现，失败只影响该占位和任务，重启后恢复原 generation/operation，不重新扣费提交。
+7. refine 请求通过严格 DTO 合同且不携带非法 `assetKind`；参数、来源类型、余额、鉴权和对账错误显示不同的安全错误码。
+8. 1:1、16:9、9:16、2:3、3:2 和极端横竖图片按真实比例显示并受边界限制；卡片不重叠，世界 extent、复位视口和依赖连线端点正确。非图片资源尺寸不变。
+9. GIF、AVIF、BMP、SVG 等不满足栅格快速编辑能力的资源继续使用能力模型中的降级编辑路径，不伪装成可提交 PNG 候选。
+10. 历史 `game-background` 等私有类型来源不得直接作为 refine 主来源；首次快速编辑完成 canonical 登记，后续同源请求复用缓存，并实际到达 `candidate-ready`。
+11. 点击导入可以原生多选图片；成功批次只推进一次草稿 revision、立即出现在当前视口并被选中，取消和失败不改变草稿且不遗留部分导入。
+12. 明确失败任务可从占位或任务侧栏归档，重启后不恢复；`reconciliation-required` 不显示删除能力。任务列表具有与现役美术画布一致的独立按钮、双 Tab、状态图标与时间/进度信息；折叠后只保留按钮且不丢任务数据，新建任务自动展开。
+13. 画布带运行中 generation 重新进入时，在远端恢复完成前已经可选图、平移和继续编辑；后台恢复继续推进原 operation，不重复 POST、不重新扣费。阻断性提交/恢复失败的遮罩覆盖整个 Tauri 窗口。
+14. 已登记 refine 资产的候选设为最终图后保持原 `assetId`、原 `source.resourceId` 与新正式 PNG 路径；`revision-installed` 中断后重新加载可前向收敛为 committed。
+15. 资源自由画板顶部不显示“生成视频”“生成音效”“生成背景音乐”或“新增 UI 设计”；播放、未完成编辑恢复、按依赖、按类型和复位仍可正常操作。
+
+## PR 176 事务与宿主合同补充
+
+- 生成失败时，公开 generation 记录必须在同一草稿 revision 链路中落为 `failed` 或 `reconciliation-required`，不得留下持久化的 `generation-running` 幽灵任务。
+- 客户端处理生成失败时必须调用宿主的权威失败结算接口并携带 `expectedDraftRevision`；结算返回 revision 冲突或失败时保持失败/对账阻断态，不得把画布静默恢复为 clean editing。无私有账本的早期失败只允许由后端原子移除公开占位并返回 `not-started`，已进入候选或正式提交终态的结果返回 `already-terminal`，等待重新打开对账。
+- 权威失败结算与生成流程内部错误统一先将私有 ledger 写为 `failure-settlement-pending` 或 `reconciliation-settlement-pending`，再幂等更新公开草稿与 staging revision，最后发布 `failed` 或 `reconciliation-required`，任何路径都不得先发布终态 ledger。任一持久化边界中断后，启动恢复必须在解析生成服务凭据前完成 pending 结算；公开草稿或 staging revision 已写入时不得重复推进。
+- 候选成功回包不得整体 hydrate 覆盖生成期间的本地未 autosave 状态；必须以当前 runtime 的图层、viewport、背景、selection 和 history 为基线，只合并权威候选图层、预览地址与 generation 记录，并用一次带 CAS 的草稿保存确认候选。
+- 候选生成必须先幂等落盘候选媒体、候选图层和公开记录，回读成功后才能推进私有 ledger 的 `candidate-ready` 终态；两次写入之间中断时，恢复必须可重放。
+- 失败归档使用 `archive-pending` 中间态：先记录归档意图，再删除草稿公开记录，最后发布 `archived`；任一边界中断都必须在重启后收敛且保持幂等。
+- `ImageCanvasAssetPort.importLocalImages` 与 `ImageCanvasGenerationPort.archiveFailedGeneration` 是冻结合同中的必选方法；不支持的宿主返回结构化 `unsupported-capability`。
+- 快速编辑卡按自身测量宽高选择上下方位置，并在 viewport 四边保留安全留白；窄屏、滚动、缩放和 resize 后都重新计算。
+
+## 验证命令
+
+```powershell
+npm run ai-game-creator-shell:typecheck
+node node_modules/vitest/vitest.mjs run apps/ai-game-creator-shell/tests/assetCanvasSurface.test.tsx apps/ai-game-creator-shell/tests/projectResourceLiveIntegration.test.tsx apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts apps/ai-game-creator-shell/tests/useProjectResourceCardPreviews.test.ts apps/ai-game-creator-shell/tests/resourceCanvasLayoutContract.test.ts
+node node_modules/vitest/vitest.mjs run apps/ai-game-creator-shell/tests/appSurface.test.ts
+cargo fmt --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project::asset_canvas -- --test-threads=1
+npm run check:encoding
+git diff --check
+```
@@ -902,6 +902,16 @@ cancelling
 | A26 | 导出 | PNG/JPEG/WebP | Web 下载/云端、Tauri 保存对话框均成功；共享 UI 不接收绝对路径 |
 | A27 | 取消 | clean、dirty、generating、staging、committing | 分别符合第 12 节；committing 不伪装成可取消 |
 | A28 | 恢复草稿 | 主文件损坏但恢复副本可信/不可信 | 可信副本恢复到 clean history 基线；不可信进入对账，不猜测 |
+| A29 | 登录刷新重放 | context、参考图准备或首次提交返回 401，刷新后以相同 generationId 和幂等身份重放 | 401 账本保持可恢复且第二次真实访问平台；403 直接失败且不刷新；远端最多受理一次 |
+| A30 | 生成卡片拖动 | 生成中拖动占位卡片 | 卡片位置按画布坐标更新并持久化到 generation record，任务状态刷新不覆盖用户位置 |
+| A31 | 精修最终图唯一性 | 选择另一候选图设为最终图 | 入口原图和所有其他候选保持各自快照，只有 `lastCommit.sourceLayerId` 标识唯一正式候选，更新正式 asset 不反向改写历史图层 |
+| A32 | 精修默认比例 | 打开图片的快速编辑 | 按原图宽高映射到最接近的支持比例（1:1、2:3、3:2、9:16、16:9）；尺寸无效时回退 1:1 |
+| A33 | 旧提交被后继提交取代 | 同一 asset 的旧事务未收尾，且后继 committed 事务链、当前 manifest/revision 与最终文件全部可证明 | 旧事务进入 `superseded`，不回滚、不覆盖当前正式图、不重放旧事件；证据不完整仍进入对账 |
+| A34 | 同资源并发正式提交 | 同一 project/draft/asset 存在 prepared 或 reconciliation 事务时再次提交 | 拒绝新提交并要求先安全恢复；已 committed/rolled-back/superseded 事务不阻塞后续提交 |
+| A35 | 精修文件名包含历史提交后缀 | 后续精修重新打开当前 `localPath`，或再次生成 / 设为最终图 | 统一剥离文件名末尾一个或多个 `--<uuid>` 后缀并规范化为合法 1..=80 字符显示名；生成与最终提交使用同一结果 |
+| A36 | 确定性提交参数无效 | 候选提交名称或用途在校验阶段失败 | 在读取候选、staging、transaction 或 ledger 写入前零副作用失败；UI 作为输入校验错误允许继续编辑，不触发安全恢复 |
+| A37 | 候选首次确认 | 生成完成后与旧 autosave 并发 | 前端先同步 authoritative layers 并保存确认；确认前后端把未确认候选层合回旧保存，重启恢复可从私有 ledger 重建候选层，确认后的显式删除仍允许 |
+| A38 | 稳定运行入口 | 精修替换已在游戏源码中引用的图片，或继续精修旧版本事务创建的资源 | manifest 指向不可变正式版本，同时原稳定入口路径不变并刷新为新版本字节；新事务可从旧事务 `manifest.before.json` 迁移稳定入口身份，幂等重放和事务恢复会修复缺失或不匹配入口，游戏源码不需要改路径 |

 阶段一至五最终审计只有在矩阵对应的纯模型、共享 React、Web adapter、Tauri adapter、Rust 持久化与 AppSurface 测试全部通过后，才可宣称图片素材创作正式闭环完成。

@@ -947,7 +957,7 @@ confirmation-required
 - `generation-accepted` 只表示 External `202 + operationId` 已原子落账；`queued/running` 继续属于远端生成期。
 - `remote-completed` 必须已经取得自洽稳定引用；缺 `objectKey/resourceId/assetObjectId` 中可支持下载与身份核验的必要组合时进入 `reconciliation-required`，不得显示成功。
 - `media-downloaded` 表示媒体通过 `/assets/read-url` 换签、SSRF/重定向门禁、大小、签名、完整解码和尺寸检查，并已写入阶段三受控 staging；重复 completed 不再下载或重写。
- `asset-durable-committed` 只来自阶段三 journal / ledger 的 `committed | already-committed`。下载成功但提交失败时保留 generation ledger、staging token 和原 commit 身份，恢复只继续本地事务，不重新生成或下载。
+- `asset-durable-committed` 只来自阶段三 journal / ledger 的 `committed | already-committed`。正式资源事务成功后，私有生成账本必须先进入 `asset-commit-settlement-pending`，再幂等补齐公开 generation 投影和 staging revision，最后才发布 `asset-durable-committed`；任一持久化切点重启都不得重复推进草稿 revision。恢复投影前必须逐项绑定私有 commit 回执、阶段三 commit ledger、transaction journal、manifest 资产与事件 payload；任一项目、草稿、commit、幂等键、revision、资产、资源或事件身份错配都保持 pending 并失败关闭。下载成功但提交失败时保留 generation ledger、staging token 和原 commit 身份，恢复只继续本地事务，不重新生成或下载。
 - `manifest-projected / layout-ready / selected` 继续复用阶段四单向链路。只有当前项目、flow、session、draft、intent 和 focus generation 全匹配时才允许选择；manifest 已提交但事件丢失时以 command/recovery 的权威完整快照继续投影。

 ### 14.4 首版请求范围与恢复
@@ -965,13 +975,14 @@ confirmation-required

 ## 15. 2026-08-06 画布 UI 对齐阶段三至五收口

- 阶段三没有新建平行画布。现有 `AssetCanvasSurface` 直接使用 `CanvasChromeButton`、`CanvasToolbar`、`CanvasToolbarGroup` 和 `CanvasToolbarDivider`，覆盖返回、导入、撤销、重做、删除、AI 生成、保存、生成确认、失败重试、停止等待和缩放。共享组件只接收图标节点、名称、事件和原生状态，不读取 Tauri、账号、钱包或 HTTP。
+- 阶段三没有新建平行画布。现有 `AssetCanvasSurface` 直接使用 `CanvasChromeButton`、`CanvasToolbar`、`CanvasToolbarGroup` 和 `CanvasToolbarDivider`。精修顶栏以紧凑尺寸覆盖返回、导入、定位当前最终图、撤销和重做；删除与“设为最终图”属于选中图片的上下文动作，通用 AI 生成与保存设置只保留给创建模式。生成确认、失败重试、停止等待和缩放继续复用共享 chrome。共享组件只接收图标节点、名称、事件和原生状态，不读取 Tauri、账号、钱包或 HTTP。
 - Tauri 样式只导入 `packages/shared/src/theme.css`、`@genarrative/image-canvas-react/styles.css` 与客户端宿主样式，没有导入主站 `src/index.css`。宿主删除了覆盖全部按钮的重复视觉规则，只保留保存/确认主操作、字段、弹窗、进度/失败卡、状态栏和 viewport 定位；颜色、边框、surface、文字、focus 和主次动作均使用平台 token。
- 生成设置继续通过独立 dialog 展示。生成/失败卡和底部状态使用受限高度加内部滚动，保存设置在窄宽下换为两行并保持主按钮整行可见；工具组不拆字，工具栏需要时横向收纳。普通确认文案不显示 manifest、幂等实现、开发者 API 配置或本机绝对路径。
+- 创建模式的通用生成设置继续通过独立 dialog 展示。图片精修从选中图片的快速编辑卡片进入生成确认，不在顶栏提供第二个通用生成入口；精修保存设置整排隐藏，候选图只通过上下文“设为最终图”提交。生成/失败卡和底部状态使用受限高度加内部滚动，创建模式保存设置在窄宽下换为两行并保持主按钮整行可见；工具组不拆字，工具栏需要时横向收纳。普通确认文案不显示 manifest、幂等实现、开发者 API 配置或本机绝对路径。
 - 阶段四保留左导航、中央主视窗、右侧 Project Supervisor 和底部 Agent Dock 四区 DOM。中央壳使用主面板层级；Supervisor 降为协作面板，其消息和 Runtime 状态内部滚动、composer 固定在栏底；Dock 使用较轻 surface 和可收缩状态卡，不与中央主要操作争抢层级。
 - 桌面 `>760px` 统一使用 `100dvh` 的两行工作台网格，第一行是内部滚动的主视窗/Supervisor，第二行是常驻 Dock。正式 `1280×800` 基线下页面级尺寸合同为 window/document/body `1280×800`；无登录会话的真实 Vite 入口按安全合同停在登录页，不绕过门禁，工作台内部由 AppSurface、共享 chrome 和 CSS 合同测试提供可重复证据。
 - 阶段五定向测试覆盖共享 chrome 的 pressed、Tauri 实际消费的工具组/分隔符、按钮名称、expanded/disabled、生成确认、失败重试、保存/取消，以及生成 dialog、进度/失败卡、状态栏、Supervisor composer 和 Agent Dock 的非裁剪/可见性合同。生成请求、登录态、泥点计费、Host Port、草稿 CAS、manifest/revision、Runtime、审批和保存事务均未改变。
 - 保存设置的产品语义固定为“名称可编辑、用途受控、格式枚举”。create 默认 `game-art`，普通用户只从 `game-art / icon-spec / ui-prototype / art-spritesheet` 四个权威用途选择；界面显示中文名称，不暴露自由 slug 输入。refine 必须继承源 manifest asset 的 `kind` 并锁定，未知历史 kind 原值透传但只显示“原资源用途”，不得借精修改变 subtype。PNG/JPEG/WebP 继续是有限格式选项。
+- refine 的继承名称从当前源 `localPath` 派生时必须使用唯一 canonical 规则：取文件名、去扩展名、循环剥离末尾 `--<uuid v4>` 历史提交后缀，再执行 NFC、非法字符清理、1..=80 字符边界、Windows 保留名和尾随空格/点防护。生成请求和“设为最终图”不得各自解析。名称 / 用途校验失败属于确定性的输入错误，后端必须发生在读取候选与 staging 之前，前端不得把它呈现为事务恢复。
 - 工具动作与保存设置必须是显式上下两行，保存栅格把主按钮列固定为 `max-content` 且禁止换行；容器宽度不足时保存按钮独占整行。普通用户工作区状态只显示项目名称，不直接展示本机绝对项目路径；显式目录选择、权限确认或开发诊断不受该展示规则替代。

 ## 16. 2026-08-10 全类型现有资源非破坏性编辑阶段覆盖条款
@@ -991,7 +1002,7 @@ confirmation-required
 - 所有编辑结果固定创建新的本地 asset、文件路径、版本 ID 或资源身份。源 asset、源文件、Agent 回执与源版本不得删除、覆盖或复用；新 asset 的 `referenceResourceIds` 必须包含源资源规范身份，资源总览同时保留新旧资源。
 - 各类型统一使用稳定 `operationId / Idempotency-Key`。普通站内响应的 queued operation 与高级 External v1 的 `202` 都只表示受理，必须轮询原 operation；inline 完成则直接消费同一请求的稳定结果。提交结果未知或登录失效时保留原身份供恢复，不能换键重提。签名 URL 不得写入 manifest，manifest 只保存稳定 objectKey 对应的资源 / 资产身份。
 - 图片 refine、视频、音效和背景音乐请求统一在 `generationInputs.source` 写入专用消费身份 `game-creator-resource-editor`；普通内部路由和高级 External 路由都必须实际读取并传递同一稳定 `Idempotency-Key`。队列完成态只向该消费身份返回经过裁剪的稳定 `objectKey / resource / asset` 引用和必要媒体元数据，不暴露 provider、worker、队列内部字段或临时签名 URL。
- 生成公开状态每次写入草稿都必须推进草稿 revision，并把最新 revision 同步到私有生成账本、进度事件、staging 与正式 commit；旧 UI 快照不得覆盖 accepted/running/reconciliation 状态。
+- 生成公开状态每次写入草稿都必须推进草稿 revision，并把最新 revision 同步到私有生成账本、进度事件、staging 与正式 commit；旧 UI 快照不得覆盖 accepted/running/reconciliation 状态。正式 commit 已成功但公开终态尚未写入时，恢复扫描必须在无需远端凭据的情况下完成 `asset-commit-settlement-pending`，不能把私有 committed 账本当作已经完成公开投影。
 - operation 已受理或首次提交结果未知后遇到 `401`，不得写成 terminal failed 或不可逆 `reconciliation-required`。普通模式先按上述单飞流程刷新；刷新失败、换号或当前 owner 不匹配时保留原 remote phase、operation、原请求字节和原幂等身份，停止网络。重新登录同一 owner 后，已有 `operationId` 只继续 GET 同一 operation，未受理请求才允许用冻结正文和原幂等键重试 POST。高级 External v1 模式修正 Developer API Key 后遵守相同恢复规则。
 - 全类型资源编辑私有账本必须冻结 `sourceAssetId / sourceMediaType / sourceAssetKind / producerTaskId / sourceVersionId` 源快照；新账本不得依赖 UI 仍停留在原资源，旧账本则只允许从当前 manifest、已完成任务产物、版本数组和受控扩展名兼容恢复。恢复结果仍要重新校验唯一来源、项目归属与媒体类型，不能把账本快照当成越权凭据。
 - 普通模式私有账本绑定固定官方 origin 与 ownerUserId，不绑定可轮换的 Access Token；恢复命令不得让前端重新拼请求或把 Token 写入参数。高级 External v1 账本绑定显式服务 origin，同样不绑定可轮换的 Developer API Key。两种模式都不得因凭据轮换改变原 operation；`401/403/404`、轮询超时或网关暂时失败必须保留原 endpoint、请求字节、幂等键和 operation，并先按账本记录的模式与 owner 做隔离校验。
@@ -1002,5 +1013,6 @@ confirmation-required
 - Tauri 画布普通滚轮按二维 delta 平移，Shift 加纵向滚轮作为横向平移回退，Ctrl/Command 加滚轮才围绕指针缩放；一次 Shift 指针事件序列只能切换一次选择。生成中必须把焦点移到“停止等待”，并阻止 wheel、指针拖拽、缩放快捷键和方向键继续改变画布，避免生成恢复期间写入新的 UI 快照。
 - `editing` 是唯一允许发起新生成的生命周期。`generating/committing/recovering/failed` 及独立 modal 打开时，画布与顶部工具栏必须同时 disabled/inert；生成事件 handler 还要读取当前权威 lifecycle 再次失败关闭，不能依赖遮罩层或渲染时闭包。
 - asset transaction journal 已精确证明目标 asset、正式媒体和 target revision 写入时，恢复应允许当前 manifest 包含该目标的同时已有后续合法追加，且只要求 `currentRevision >= targetRevision`；补齐同一 ledger/draft 后仍复用原 commit/event 身份，不能因为整个 manifest 不再等于历史 after 快照而永久对账。
+- 未收尾事务只有在同一 project/draft/asset 的后继事务为 `committed/event-attempted`，且旧事务 after 与后继 before、后继 after 与当前 manifest/revision、两份最终文件摘要和 manifest 唯一引用全部严格匹配时，才可标记为 `superseded`。该终态保留旧 journal、ledger、snapshots 与候选文件，不修改草稿 lastCommit，也不重放旧事件；任何证据缺失继续保持 `reconciliation-required`。正式提交入口发现同资源存在 `prepared/reconciliation-required` 事务时必须先拒绝并引导安全恢复，避免制造第二笔可覆盖旧结果的提交。

 当前阶段不主动扩展 create 专属空画布导入、生成或保存体验；图片继续复用现有画布，其他类型使用同一资源编辑壳按能力分流，不能把视频、音频或版本强塞进图片图层模型。共享持久化、安全、幂等和可访问性缺陷仍必须修复，因为它们直接影响编辑链路。