冻结客户端素材创作无限画布阶段一合同

新增共享画布、宿主适配、草稿与正式资产提交的完整技术合同同步工作台 PRD 与 AI 游戏创作 App 实施计划的产品范围补充事务恢复、焦点竞态、状态机和验收矩阵更新文档索引、决策记录与踩坑记忆
2026-08-05 12:45:04 +08:00
parent 96c66e619d
commit 3522285894
6 changed files with 982 additions and 21 deletions
@@ -10,6 +10,8 @@
 4. [平台入口与玩法链路](./【玩法创作】平台入口与玩法链路-2026-05-15.md)
 5. [本地开发验证与生产运维](./【开发运维】本地开发验证与生产运维-2026-05-15.md)
 6. [AI 游戏创作项目开发工作台 PRD](./prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)
+7. [AI 游戏创作智能体 App 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+8. [客户端素材创作无限画布阶段一合同](./technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md)

 团队长期约定、决策、流程和排障摘要统一从 [项目记忆入口](./project-memory/README.md) 读取。代码、当前融合文档与项目记忆冲突时，以代码和最新融合文档为准。

@@ -17,6 +19,7 @@

 ### 图片编辑器与 Agent

+- [客户端素材创作无限画布阶段一合同](./technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md)
 - [图片画布编辑器 MVP 接入方案](./technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md)
 - [图片画布编辑器前端拆分计划](./technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md)
 - [画布 Agent 对话面板](./【编辑器】画布Agent对话面板-2026-07-03.md)
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD

-更新时间：`2026-08-04`（依赖视图视觉口径调整）
+更新时间：`2026-08-05`（冻结客户端素材创作无限画布阶段一合同）

 ## 1. 产品定位

@@ -13,7 +13,7 @@
 3. 右侧 Project Supervisor 对话与确认区。
 4. 底部专业 Agent 状态栏。

-中央主视窗在“资源管理”和“运行测试”之间切换。正式预览始终在客户端当前窗口内展开，只允许载入当前项目启动的 `127.0.0.1:<port>` 本地 HTTP 预览，不调用系统外部浏览器。
+中央主视窗明确区分“资源总览画布”“素材创作无限画布”和“运行测试”三个状态。资源总览与素材创作不是两套项目页：前者负责 manifest 资源投影、依赖关系和类型布局，后者负责单个图片素材的无限画布创作；两者共用当前工作台中央区域。正式预览始终在客户端当前窗口内展开，只允许载入当前项目启动的 `127.0.0.1:<port>` 本地 HTTP 预览，不调用系统外部浏览器。

 ## 2. 创作工具平台接入声明

@@ -88,20 +88,25 @@
 ### 4.1 主视窗

 ```text
-resources
+resource-overview
+  -> asset-canvas.create（点击“新增资源”）
+  -> asset-canvas.refine（在唯一图片资源上点击“精修资源”）
  -> run（存在 runnableVersion 且 loopback preview 可启动）

+asset-canvas.create|refine
+  -> resource-overview（取消、保留草稿退出或保存投影完成）
+
 run.playing
  -> run.paused（用户暂停或切片结束）
-  -> resources（先暂停当前预览表现，再切换视图）
+  -> resource-overview（先暂停当前预览表现，再切换视图）

 run.paused
  -> run.playing（继续当前切片）
  -> run.relaunching（数值或版本编辑态发生变化）
-  -> resources
+  -> resource-overview
 ```

-运行入口不可用时仍允许点击，显示“当前无可运行版本”，但不切换状态。
+运行入口不可用时仍允许点击，显示“当前无可运行版本”，但不切换状态。素材创作的完整 opening/editing/generating/saving/cancelling/failed/recovering 状态、草稿身份和迟到结果门禁以 [`【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`](../technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md) 为准。

 ### 4.2 测试切片

@@ -127,10 +132,10 @@ idle -> focused(document|art|audio|version) -> idle
 - 美术：PNG、JPEG、WEBP 继续使用图片魔数与像素边界预览；GIF、SVG、AVIF、BMP、MP4、WebM、MOV 通过新增受控媒体读取链路按文件签名校验后在中央画布放大聚焦。SVG 额外拒绝脚本、事件处理器、外部资源引用和实体声明；视频使用内置播放控件。读取失败显示错误空态。
 - 音频：只读取 manifest 已登记音频或已成功导入且登记到 manifest 的附件，按文件签名接受 MP3、WAV、OGG / Opus、M4A、AAC、FLAC；聚焦态展示实际格式、浏览器解码后的时长以及带播放进度和暂停能力的内置播放器。音频任务声明中的未登记路径继续不得读取或播放。
 - 版本：只展示 manifest 中正式、不可变的迭代版本记录；版本卡展示项目修订、创建原因与父版本，聚焦态同时展示直接子版本和资源绑定。点击版本卡后高亮仍存在于当前资源投影中的引用资源；缺失历史资源只保留绑定身份，不生成幽灵资源卡。资源替换仍留给后续切片。
- mentor 最新决定：资源聚焦不提供工具栏，也不提供工具侧边栏。
- 点击资源后，中央主视窗从 `resources.list` 切换为 `resources.focused.document / art / audio / version`，左侧平台导航、右侧 Supervisor 对话和底部 Agent 状态栏保持原位；聚焦容器只包含标题、资源主体、必要元数据与右上角收起按钮，不使用页面级浮层或可拖动标题栏。
+- 资源聚焦不提供通用工具栏或工具侧边栏；图片聚焦态允许一个明确的“精修资源”业务动作进入素材创作无限画布，该动作不是在聚焦容器中内嵌编辑器或恢复通用工具栏。
+- 点击资源后，中央主视窗从 `resource-overview.list` 切换为 `resource-overview.focused.document / art / audio / version`，左侧平台导航、右侧 Supervisor 对话和底部 Agent 状态栏保持原位；聚焦容器只包含标题、资源主体、必要元数据与右上角收起按钮，不使用页面级浮层或可拖动标题栏。
 - 退出聚焦后恢复进入前的搜索条件、dependency / type 布局模式、资源画布滚动位置和选中资源；这些只属于当前前端会话，不写入布局 sidecar。
- 阶段四只新增上述受控读取与媒体展示；阶段六在同一聚焦容器内补齐正式版本只读展示和引用高亮，但不新增资源聚焦工具栏 / 工具侧边栏，不新增美术编辑、音频编辑 / 替换、资源重新生成、版本替换或运行模块。飞书原需求中“编辑并生成新资源”的条件项仍暂缓，不能只打开画板却缺少回写、`referenceResourceIds` 血缘登记、新资源自动选中与邻近布局的完整闭环。
+- 资源管理阶段四至阶段七只交付上述受控读取、媒体展示、正式版本只读展示和引用高亮；`2026-08-05` 起，后续素材创作切片已冻结完整图片闭环，不再把图片导入、基础编辑、生成、导出或本地回写列为非目标。入口必须与草稿 CAS、正式事务提交、`referenceResourceIds` 血缘、新资源即时投影、布局和焦点竞态一次实现，不能只打开一个没有回写的画板。

 ### 4.4 历史成果与当前状态

@@ -144,23 +149,32 @@ idle -> focused(document|art|audio|version) -> idle

 以下合同先冻结字段语义；P0 只实现标注为 P0 的部分。

-### 5.1 工作台视图状态（P0）
+### 5.1 工作台中央状态（素材创作阶段一目标合同）

 ```ts
 type ProjectWorkbenchViewState = {
-  schemaVersion: 'game-creator-workbench-view.v1';
+  schemaVersion: 'game-creator-workbench-view.v2';
  projectId: string;
-  mode: 'resources' | 'run';
+  centerState:
+    | { kind: 'resource-overview' }
+    | {
+        kind: 'asset-canvas';
+        sessionId: string;
+        draftId: string;
+        intent: 'create' | 'refine';
+        sourceAssetId: string | null;
+      }
+    | { kind: 'run' };
  approvalMode: 'strict' | 'risk' | 'none';
  expandedAgentGroups: Array<'balance' | 'audio' | 'publishing'>;
 };
 ```

-P0 中 `approvalMode` 只能有效写入 `strict`；其它值只能作为不可用选项展示。
+旧 `game-creator-workbench-view.v1.mode='resources'` 读取时只映射到 `resource-overview`，`mode='run'` 映射到 `run`；旧状态不能合成 asset-canvas 草稿。`sessionId` 是本次进入流程的短生命周期 UUID，`draftId` 是本地可恢复草稿 UUID。`create` 必须没有源资产，`refine` 必须绑定当前 manifest 中唯一图片资产。`approvalMode` 仍只有 `strict` 可有效写入；其它值只能作为不可用选项展示。

 ### 5.2 资源画布布局（P1）

-实现状态（2026-08-03）：dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑与确定性依赖深度、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。依赖图加载完成前设布局初始化屏障，避免以临时 `dependencyDepth=0` 生成并持久化错误坐标。当前用户入口只允许自动布局与资源卡点击；资源卡手动拖动已按 mentor 决定暂缓。历史 sidecar 坐标继续只读恢复，底层布局读写与 CAS 合同保留，但当前没有用户手动布局入口。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
+实现状态（2026-08-03）：dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑与确定性依赖深度、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。依赖图加载完成前设布局初始化屏障，避免以临时 `dependencyDepth=0` 生成并持久化错误坐标。资源总览当前只允许自动布局与资源卡点击，资源卡手动拖动继续暂缓；这不限制素材创作无限画布的 viewport 平移/缩放和图片图层移动/缩放，两套坐标及 sidecar 完全独立。

 ```ts
 type ProjectResourceCanvasLayout = {
@@ -393,7 +407,8 @@ type ProjectAgentMudPointAttribution = {
 - 已实施依赖/类型两套坐标持久化、首次默认不重叠布局、历史坐标跨重启恢复与自动协调 CAS 冲突处理；资源卡手动拖动暂缓。
 - 资源关系线在布局持久化验收通过后单独实施，不与本切片捆绑伪造完成。
 - 已实施正式版本只读模型、版本卡、父子关系与引用资源高亮；资源兼容性判断和不可变下一迭代版本创建仍待后续切片。
- 美术/音频编辑状态接线。
+- 素材创作无限画布阶段一按权威专题一次交付图片导入、编辑、生成、导出、草稿恢复、正式本地回写、即时投影和焦点竞态闭环。
+- 高级抠图、图集、角色动画、视频编辑和音频编辑按后续切片实施。

 ### P2

@@ -450,16 +465,27 @@ type ProjectAgentMudPointAttribution = {

 ### 7.5 阶段七完整验收

-1. 对照飞书需求、当前 PRD、技术方案、代码、测试与阶段提交复核阶段零至阶段六；美术编辑生成新资源继续按本 PRD 已确认的闭环条件暂缓，不作为遗漏或伪完成。
+1. 对照飞书需求、当前 PRD、技术方案、代码、测试与阶段提交复核资源管理阶段零至阶段六；该阶段本身保持只读收口。后续图片素材创作按 `2026-08-05` 阶段一合同实施，不得再引用阶段七的历史暂缓文字关闭新入口。
 2. AppSurface 同时覆盖文档、图片、SVG、音频和视频聚焦；视频必须使用原生 `controls` 且 `preload="metadata"`，读取策略失败时中央主视窗显示安全空态，右侧对话和底部 Agent 状态栏继续存在。
 3. `1280×800` 应用内浏览器实测 `window`、document 与 body 均无页面级横向或纵向溢出。浏览器开发页受真实登录门禁保护，不为验收绕过认证或伪造 Tauri；工作台内部结构由 AppSurface 集成测试与资源布局 CSS 合同测试复核。
 4. 根目录全量 Vitest、前后端 typecheck / lint / build、Rust workspace test / check、SpacetimeDB schema、原生壳、内容 / 编码、生产运维与部署门禁全部通过后，阶段七才允许提交。
 5. 本地 `.env`、`.env.local`、密钥、缓存、日志和构建产物不进入阶段七提交；提交前再次执行编码检查和 `git diff --check`。

+### 7.6 素材创作无限画布阶段一验收
+
+1. 网站与 Tauri 实际 import 同一份 `@genarrative/image-canvas-core` 和 `@genarrative/image-canvas-react`，客户端没有复制的主站画布目录；宿主差异只位于 adapter。
+2. “新增资源”和“精修资源”分别进入 create/refine 素材画布；精修保留原资产、创建新资产，并用规范 `referenceResourceIds` 登记直接血缘。
+3. 草稿 schema、revision、容量、项目身份、OS 锁、CAS、恢复副本和媒体引用符合权威专题；损坏、未知 schema、身份错配和超限均失败关闭。
+4. 正式提交携带 `expectedProjectId + expectedRevision + expectedDraftRevision + commitId + idempotencyKey`，按文件、manifest/revision、回读、ledger/draft、事件顺序完成；两窗口并发、重复提交和各崩溃阶段均有确定结果。
+5. 保存成功后不刷新、不重开项目即可进入 manifest 投影、依赖图、dependency/type 布局和允许时的选中定位；切项目、切中央状态、改选择或改搜索后的迟到结果不得抢焦点。
+6. 搜索/筛选隐藏新资源时保留条件，明确提示“新资源已保存，当前筛选条件下不可见”，只通过显式动作清除条件并定位。
+7. 新增、精修、生成、保存、取消、失败和恢复必须覆盖权威专题 §13 的完整验收矩阵；只完成画布 UI 或只完成本地写文件都不能算正式闭环。
+
 ## 8. 非目标

- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、下一迭代版本创建入口、运行版本切换、版本回滚、运行模块扩展、测试切片、运行态消费版本、数值参数或泥点归因。正式版本记录已经成为 manifest 业务真相，但当前只读取、校验和展示已有记录。
- 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
+- 资源总览当前不实现资源卡手动拖动，也不实现通用聚焦工具栏/工具侧边栏、下一迭代版本创建入口、运行版本切换、版本回滚、运行模块扩展、测试切片、运行态消费版本、数值参数或泥点归因。正式版本记录已经成为 manifest 业务真相，但当前只读取、校验和展示已有记录。
+- 素材创作阶段一不实现高级蒙版/毛发级抠图、图集、角色动画、视频编辑或音频编辑；图片画布平移/缩放、图层选择/移动/缩放、撤销重做、导入、基础编辑、生成、导出和本地回写明确不是非目标。
+- 资源总览不持久化资源聚焦状态、搜索条件、筛选条件或当前 dependency/type mode；其会话上下文不能塞入 `game-creator-resource-layout.v1`。素材创作 viewport 和图层状态按独立 `game-creator-asset-canvas-draft.v1` 保存，不能混用资源总览 sidecar。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
 - 不自动确认 Agent 动作，不自动触发可能扣费的生成。
@@ -1,5 +1,17 @@
 # 决策记录

+## 2026-08-05 素材创作无限画布共享源码并以本地事务形成图片闭环
+
+- 背景：资源管理阶段七已经完成 manifest 实时投影、dependency/type 布局、依赖图和中央只读聚焦，但“新增资源/精修资源”仍缺少草稿、生成、正式回写、血缘、布局和焦点竞态的完整合同。网站已有成熟图片画布，若直接复制进 Tauri 会形成两份长期分叉的画布内核和通用 UI。
+- 产品决策：项目工作台中央主视窗把 `resource-overview` 与 `asset-canvas(create|refine)` 建模为两个状态。“新增资源”和“精修资源”进入素材画布，资源总览卡片继续不可拖动，素材画布图片图层必须支持平移/缩放、选择/移动/缩放、撤销重做、导入、基础编辑、生成、导出和本地回写。首版只正式闭环图片；高级抠图、图集、角色动画、视频和音频编辑后续分期。
+- 架构决策：现役网站画布抽取到 `packages/image-canvas-core` 与 `packages/image-canvas-react`，网站和 Tauri 实际 import 同一源码，通过 Web/Tauri Host Port 注入差异。Web 保留账户、钱包、服务端 editor project 和云端素材库；Tauri 保留本地项目、受控文件、manifest、项目 revision 和 External Editor API。禁止复制整个 `src/components/image-editor/` 到客户端。
+- 持久化决策：Tauri 草稿使用 `.agent/workbench/asset-canvas/` 下的 `game-creator-asset-canvas-draft.v1`，以 `expectedProjectId + expectedDraftRevision` 在 OS 句柄锁内 CAS；JSON 最大 `2 MiB`、最多 `4096` 层，媒体只保存受控引用。正式 `commit_local_project_asset` 同时绑定项目 `expectedRevision`、草稿 revision、`commitId/idempotencyKey` 和 staging 摘要，按 prepared journal、最终图片、manifest/revision 可恢复更新、回读、ledger/草稿、最后 Tauri event 推进；事件 `game-creator-local-asset-committed` 至少一次并按固定 eventId 去重。
+- 血缘与并发：refine 永远保留源文件/asset 并创建 `canvas-<commitId>`。源没有外部 resourceId 时补齐 `local-asset:<manifestAssetId>`，新资产只通过规范 `referenceResourceIds` 引用，禁止混用裸 manifest asset ID。两个窗口基于同一 project/draft revision 最多一个成功；相同提交返回 already-committed，同键不同请求失败关闭。恢复只依据 journal、before/after 摘要和 ledger，不按文件存在、mtime 或 PID 猜测。
+- 投影与焦点：提交返回完整当前 manifest；同项目仍活动时立即更新 manifest 投影、依赖图输入和两种布局，不要求刷新或重开。自动选中还必须复核 project/path、asset-canvas session/draft/intent、selection epoch 和 search/filter epoch；用户已切项目、切模式、选其它资源或新资源被条件隐藏时不得抢焦点，隐藏时保留条件并提供显式清除/定位动作。
+- 影响范围：下一阶段的共享画布包、网站 adapter、`apps/ai-game-creator-shell` 前端与 Tauri Rust 本地持久化；不修改 SpacetimeDB schema，不把草稿或资源布局 sidecar 变成 manifest 业务真相。
+- 验证方式：按权威专题的 28 项矩阵覆盖 Web/Tauri 共用源码、新增/精修、生成响应丢失、重复提交、两窗口并发、事务各崩溃点、草稿恢复、切项目/切状态/改选择/改筛选迟到结果和不刷新即时投影。
+- 关联文档：`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-03 资源管理阶段七以完整 CI 与可重复界面合同收口

 - 背景：飞书资源管理需求的阶段零至阶段六已经分别完成资源卡禁拖、固定资源投影、中央聚焦、安全文档 / 媒体预览、依赖深度与正式版本只读模型；最后需要统一复核需求边界并用当前主分支完整门禁排除集成回归。
@@ -14,6 +14,22 @@
 - 关联：相关文件、文档、提交或 Issue
 ```

+## 正式素材提交不能把多文件写入或 Tauri 事件误当成一次原子动作
+
+- 现象：图片已经落到 `assets/` 但 manifest 没有资产，或 manifest 已追加而 project revision/草稿仍是旧值；进程在 emit 前后退出后，用户重试又得到第二份图片、第二个 asset 或重复选中。
+- 原因：文件系统只保证单文件原子替换，不能让最终图片、manifest、`.agent/runtime/project-revision.json`、commit ledger 和草稿跨文件物理原子；Tauri event 也没有跨崩溃 exactly-once。若先写副作用再临时生成幂等身份，或只凭目标文件存在推断成功，就无法区分未提交、已提交未回包和部分提交。
+- 处理：第一次保存前冻结 `commitId + idempotencyKey + eventId + requestFingerprint`，在项目 write lock 内先写 prepared journal 和 before/after 摘要，再按最终图片、manifest/revision 逻辑原子更新、回读、ledger/草稿提交推进，释放锁后最后 emit。恢复只按 journal stage、精确字节摘要和 ledger 前向完成/安全回滚；矛盾状态进入 reconciliation-required。事件采用至少一次，监听方按 eventId 和 project revision 去重。
+- 验证：分别在 prepared、图片安装、manifest 安装、revision 安装、ledger 提交、emit 和投递标记后强杀；确认只有唯一 `canvas-<commitId>`、revision 最多推进一次、源资产与血缘正确，响应丢失后返回 already-committed，矛盾 fixture 不自动重试。
+- 关联：`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`。
+
+## 素材保存成功不等于迟到结果仍有权抢占当前焦点
+
+- 现象：用户等待生成/保存时切到另一个项目、run、另一份素材草稿，或主动选择其它资源、修改搜索条件；旧请求完成后界面却切回旧画布、清空筛选并自动选中新资源。
+- 原因：异步回调只检查“请求成功”或捕获的旧 `isMounted/projectId`，没有绑定中央状态 session、draft/intent、selection epoch 和 query epoch；manifest 投影这一数据事实又被错误地与“当前应自动聚焦”的用户意图合并处理。
+- 处理：保存开始捕获 `projectPath + projectId + centerKind + sessionId + draftId + intent + selectionEpoch + queryEpoch`，响应时从当前 ref/store 完整复核。manifest 可以按精确项目身份更新当前上下文或后台缓存，但自动切状态、选择、滚动和聚焦必须等当前 mode 布局 ready 且全部焦点守卫仍相等。新资源被搜索/筛选隐藏时保留条件与选择，提示“新资源已保存，当前筛选条件下不可见”，只提供显式清除/定位动作。
+- 验证：使用 deferred commit/layout Promise，依次在请求后切项目、切 run/overview、新开 session、改选择和改筛选；断言 manifest 只更新对应项目，新资源仍进入投影/布局，但所有失效守卫都不切中央状态、不改选择、不清查询。条件未变化且资源可见时才自动定位。
+- 关联：`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`。
+
 ## Linux 生产脚本门禁不能假设本地也是 GNU userland

 - 现象：macOS 本地运行维护页、生产 API 部署和 Rust 产物门禁时，依次出现 `mv: illegal option -- T`、`mapfile: command not found`、`/usr/bin/cp` / `/usr/bin/chmod` 不存在，以及 `.rlib` 明明含有 `.o` 却报告“没有可扫描成员”；安全修复计划还会把 `/var/folders` 到 `/private/var/folders` 的系统别名误判为用户符号链接。
@@ -346,6 +346,8 @@ game-project/

 美术组和音乐组复用现有画板能力，不另建平行资产系统。

+`2026-08-05` 起，客户端图片精修不再通过“打开另一份主站画布副本”实现，而按 [`【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`](./【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md) 把现役网站图片画布抽取为共享 `@genarrative/image-canvas-core` 与 `@genarrative/image-canvas-react`。网站和 Tauri 实际 import 同一份 core/React/UI 源码，分别注入 Web 与 Tauri Host Port；禁止把 `src/components/image-editor/` 整目录复制到客户端。
+
 - 美术组通过画板链路生成角色、场景、UI、图标、动画和宣传素材。
 - 音乐组复用画板已有 `audio`、`sound-effect`、`background-music` 能力。
 - 默认后台生成，用户需要精修时打开画板继续编辑。
@@ -357,6 +359,9 @@ game-project/
 - 项目工作台点击已登记图片时必须在中央主视窗的资源聚焦状态中直接渲染图片，而不是只展示路径与 MIME。图片通过受控 Tauri 命令从项目 `assets/` / `game/` 读取，只允许 manifest 已登记资产或已完成任务产物，并复用 `file.read` auto 权限、图片魔数、文件大小、像素尺寸、普通文件、路径漂移和符号链接校验后以 data URL 返回；首版只支持 PNG、JPEG、WEBP，不向 WebView 暴露任意本机文件协议或绝对路径。
 - 2026-08-03 阶段四在上述图片链路外新增 `read_local_project_text_preview` 与 `read_local_project_media_preview`。前者只接收当前 manifest 已登记文档或已完成任务中的 Markdown / 文本 / JSON / YAML / TOML，限制 2 MiB 与 UTF-8；Agent 文本回执继续直接消费合法对话投影，不反查本地路径。后者的美术分支接收 GIF、安全 SVG、AVIF、BMP、MP4、WebM、MOV，音频分支只接收 manifest 已登记的 MP3、WAV、OGG / Opus、M4A、AAC、FLAC，二进制媒体限制 32 MiB。两条命令统一执行 `file.read` auto 权限、规范化相对路径、项目边界、敏感路径、普通文件、父目录链接、硬链接、读取漂移和重开身份复核；媒体按文件签名而非只按扩展名或 MIME 建立 data URL，SVG 额外拒绝活动内容与外部引用。
 - `canvas.export_import` 复用 `/editor/canvas` 已有素材导出 ZIP 格式，读取根 `metadata.json`、复制 `images/` / `media/` / `sequences/` 到本地项目 `assets/canvas-imports/`，再按导出层登记为 `canvas` 来源资产；导出包不保存真实 resourceId 时，使用 `canvas-export:<file>` 作为可追踪 assetObjectId，不伪造后端资源行。
+- 阶段一正式闭环只覆盖图片。网站 adapter 保留账户、钱包、服务端 editor project、云端素材库、OSS/asset object 与现有生成 API；Tauri adapter 使用本地项目、受控媒体、`game-creator-asset-canvas-draft.v1` 草稿、manifest、项目 mutation revision 和 External Editor API。高级抠图、图集、角色动画、视频和音频编辑后续分期。
+- Tauri 正式保存必须通过受控 staging 与 `commit_local_project_asset`，携带 `expectedProjectId + expectedRevision + expectedDraftRevision + commitId + idempotencyKey`。事务固定为 prepared journal、最终图片、manifest/revision 可恢复更新、回读验证、committed ledger/草稿、最后发布 `game-creator-local-asset-committed`；不能继续用先推进 revision 再分别登记资产的旧命令拼装正式闭环。
+- refine 默认保留源文件和源 manifest asset，新建 `canvas-<commitId>` 资产。源资产没有外部 `source.resourceId` 时在同一 manifest 事务中补齐 `local-asset:<manifestAssetId>`，新资产通过 `referenceResourceIds` 引用该规范身份；禁止把裸 manifest asset ID 冒充 External Editor resource ID。

 ## GameAgent V1.0 项目开发工作台首版界面

@@ -365,9 +370,9 @@ game-project/
 2026-07-20 起，产品状态机、P0/P1/P2 范围与后续数据合同以 [`【AI游戏创作】项目开发工作台PRD-2026-07-20.md`](../prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md) 为准；本节只保留当前实现边界。

 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
- 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
+- 中间主视窗提供 `resource-overview / asset-canvas / run` 三种状态。资源总览的“新增资源”和图片聚焦的“精修资源”进入 create/refine 素材创作无限画布；素材画布只替换中央区域，不覆盖右侧 Supervisor 或底部 Agent。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源总览只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
- 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态；美术编辑、音频编辑 / 替换、版本替换或运行模块仍不在本阶段。
+- 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源总览卡片拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供通用工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态。该资源总览边界不限制后续素材创作无限画布内的图片图层移动/缩放、生成和正式回写。
 - 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
@@ -391,7 +396,7 @@ game-project/
 - 新资源只在第一次进入某个 mode 时计算默认不重叠位置；全部现存坐标保持不变。搜索、筛选、窗口 resize 和 mode 切换不得重排或回写已有坐标，窄视图通过 section 画布范围与滚动访问，不裁切持久坐标。
 - type 默认布局固定按 `subtype -> mediaType -> label -> id` 排序。manifest 资产的 subtype 使用 `asset.kind`，任务产物、导入附件和 Agent 文本成果使用稳定的来源 fallback；subtype 必须进入资源协调签名，不能因 MIME 相同而退化成按名称混排。
 - 自动协调保存失败时保留当前会话布局；CAS 冲突载入对方最新布局，需要继续协调时最多追加两次重试，持续跨窗口竞争时停止自旋。用户提示只说明“布局已在其他窗口更新”，不要求重新拖动。损坏、未知 schema、身份冲突、超限与链接文件失败关闭，不能用空布局覆盖原文件。
- 本布局持久化切片不包含资源关系线、资源替换、聚焦态持久化、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。资源关系线与当前会话内中央聚焦已在后续独立前端切片接入，不改变本段 sidecar 合同；其余 P1 能力继续独立实施。
+- 本资源总览布局 sidecar 不包含资源关系线、资源替换、聚焦态持久化、资源总览缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。资源关系线与当前会话内中央聚焦已在后续独立前端切片接入；素材创作 viewport 和图层使用独立草稿 schema，不能写入 `game-creator-resource-layout.v1`。

 历史实施顺序已完成 TypeScript / Rust DTO、Tauri sidecar/CAS、前端纯模型与持久 Hook。二维手动拖动接线现已暂缓；重新开放前必须先更新 PRD 与验收合同。任何后续步骤不得用 `localStorage`、manifest 字段或只在当前 React 会话有效的状态冒充项目持久化。

@@ -429,11 +434,16 @@ game-project/
 3. 扩展 `apps/ai-game-creator-shell` 的本地能力：项目目录、文件写入、受限命令、本地 HTTP 预览。
 4. 用户侧项目开发页提供资源 / 运行工作台、当前项目的 loopback 游戏画面、陶泥儿对话、上传结果和 Agent 状态栏；开发专用单 Agent 对话、原始任务 / 文件面板、预览诊断面板和命令日志只在开发构建的独立开发窗口展示。
 5. 将美术组、音乐组接入现有画板与外部生成队列。
+6. 从现役网站画布抽取共享 `image-canvas-core/react`，先让网站改为消费共享源码，再由 Tauri adapter 接入；不得复制整个画布目录。
+7. 实现 Tauri 草稿/media/staging/commit/transaction/event 合同和跨窗口锁、CAS、幂等与崩溃恢复。
+8. 在项目工作台接入 create/refine 状态机、保存后的 manifest 即时投影、依赖图与两种布局协调，以及 project/session/selection/query 焦点守卫。
+9. 按权威专题验收矩阵同时完成 Web、Tauri、共享包、Rust 持久化和 AppSurface 证据后，才开放正式入口。

 ## v1 验收

 - 用户能创建本地 Web 游戏项目。
 - 用户进入项目开发页后能看到资源管理主视窗、陶泥儿对话栏和底部策划 / 美术 / 程序 Agent 状态栏；`1280×800` 最小横屏窗口和更大桌面窗口均不得出现页面级横向 / 纵向溢出，对话输入与底部 Agent 状态栏始终位于视口内。
+- “新增资源”和“精修资源”进入共用中央区域中的素材创作无限画布；图片导入、画布平移/缩放、图层选择/移动/缩放、撤销重做、基础编辑、生成、导出和 Tauri 正式保存形成完整闭环。保存后不刷新、不重开即可进入 manifest、依赖图、布局和选中流程，迟到结果不能覆盖用户后来切换的项目、状态、选择或搜索意图。
 - 资源管理可在按依赖 / 按类型之间切换、搜索资源并点击打开当前资源详情；dependency 模式展示可验证的资源引用和聚合任务流，搜索过滤端点、选择高亮直接上下游。资源卡不可拖动，Pointer Move 不更新坐标、线段或手动布局；所有展示数据来自当前 manifest、当前资源投影或当前项目导入附件。
 - 首个 `code-prototype` 任务未完成时运行入口不可进入并给出可感知提示；完成后可进入运行表现层，真实预览直接加载到客户端内受限运行容器。
 - 审批档位通过独立弹出面板切换，默认严格审批；界面选择不得绕过 Runtime 现有确认门禁。
@@ -898,3 +908,13 @@ game-project/
 - 嵌入项目工作台的 Project Supervisor 在本地 manifest 状态变化时向启动器外传完整 manifest，并携带来源项目路径。启动器只更新仍为同一路径的活动项目上下文；资源列表、依赖图输入、任务状态、运行入口和正式版本卡必须在当前页面实时重投影，不要求关闭或重开项目。
 - `.agent/agent.db` 有界尾部读取报告截断时，审计 producer 映射失败关闭，不生成基于不完整审计的 producer 或 task flow。前端收到截断 DTO 时再次清空 producer、task flow、任务环和依赖深度派生结果；只依赖 manifest 唯一外部资源 ID 的精确引用关系继续保留。
 - 资源依赖 SVG 继续作为不可交互装饰层隐藏，但 dependency 画布通过 `aria-describedby` 提供当前可见精确引用和任务流的文本等价列表。中央资源聚焦关闭或按 Escape 退出后恢复触发卡片焦点；橙色引用线及箭头使用对 `#fffdfa` 画布达到至少 `3:1` 的颜色。
+
+## 2026-08-05 客户端素材创作无限画布阶段一合同
+
+- 资源总览画布与素材创作无限画布是项目工作台中央主视窗的两个状态。资源总览继续消费 manifest、dependency/type 布局与 Rust 依赖图；素材画布以 `sessionId + draftId + create/refine` 建立独立生命周期。“新增资源”和“精修资源”只切换中央区域，右侧 Supervisor 与底部 Agent 状态栏常驻。
+- 网站与 Tauri 共用 `packages/image-canvas-core` 和 `packages/image-canvas-react`；网站保留账户、钱包、服务端项目和云端素材库 adapter，Tauri 保留本地项目、受控文件、manifest、项目 revision 和 External Editor API adapter。现役网站画布是抽取来源，不允许整体复制到客户端。
+- 本地草稿固定保存到 `.agent/workbench/asset-canvas/`，schema 为 `game-creator-asset-canvas-draft.v1`，以 `expectedProjectId + expectedDraftRevision` 做 OS 锁内 CAS；单 JSON `2 MiB`、最多 `4096` 层，媒体正文只进入受控 media/staging 文件。损坏、未知 schema、身份错配、超限和恢复摘要不匹配全部失败关闭。
+- 正式资产命令固定为 `commit_local_project_asset`，同时绑定 `expectedProjectId`、项目 `expectedRevision`、`expectedDraftRevision`、`commitId`、`idempotencyKey` 和 staging 摘要。事务在项目锁内按 prepared、最终图片、manifest/revision 逻辑原子更新、回读、ledger/草稿提交推进，释放锁后最后发布 `game-creator-local-asset-committed`；事件至少一次并按固定 eventId 去重。
+- refine 不覆盖源文件或复用源 asset ID。源缺少外部 resourceId 时补齐 `local-asset:<manifestAssetId>`，新 `canvas-<commitId>` 资产用 `referenceResourceIds` 登记源和其它直接引用，避免混淆 manifest asset ID 与 External Editor resource ID。
+- 提交返回完整最新 manifest；当前项目仍匹配时立即更新项目上下文、资源投影、依赖图和两种布局，布局 ready 后才按焦点守卫决定选中。用户已切项目、切状态、开始新 session、选择其它资源或改变搜索/筛选时，迟到结果不得抢焦点；新资源被隐藏时保留条件并提供显式清除/定位动作。
+- 图片首版包含平移、缩放、图层选择/移动/缩放、撤销重做、导入、基础编辑、生成、导出和本地回写。高级抠图、图集、角色动画、视频与音频编辑后续分期；本阶段不修改 SpacetimeDB schema。