实现资源画布布局持久化 (#116)

冻结资源画布布局数据与 CAS 合同实现双模式本地 sidecar 安全读写接入二维拖动、默认排版和跨重启恢复补齐并发冲突、安全边界和界面测试同步技术文档与共享决策 Reviewed-on: http://192.168.35.82/git/GenarrativeAI/Genarrative/pulls/116 Reviewed-by: 段舒康 <kdletters@qq.com> Co-authored-by: menghao <mh18530625731@163.com> Co-committed-by: menghao <mh18530625731@163.com>
2026-07-31 12:00:48 +08:00
parent d4075c3423
commit 216407d93e
25 changed files with 4170 additions and 352 deletions
@@ -319,7 +319,7 @@ game-project/
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest` 派生项目文档、项目版本和 `assets`，并把首页已导入附件作为当前项目上传资源展示。资源按文档、版本、美术、动作、音乐音效分区；`按依赖 / 按类型` 只改变当前前端排列方式，不写回 manifest，也不伪造资源依赖。
- 资源卡首版支持选择聚焦、文档展开 / 收起、搜索和类型筛选的界面交互。拖拽自由排版、画板编辑、生成关系连线、同类型版本资源替换均保留清晰入口或状态提示，但在具备正式布局 / 版本引用写回契约前不保存为业务事实。
+- 资源卡支持选择聚焦、文档展开 / 收起、搜索和类型筛选的界面交互。2026-07-28 起，原一维会话拖拽已替换为两套二维坐标与本地 CAS sidecar；画板编辑、生成关系连线、同类型版本资源替换仍不得在缺少各自正式写回契约时保存为业务事实。
 - 运行表现层首版直接嵌入当前项目的 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 与回滚合同完备前不向普通用户开放。
@@ -330,6 +330,25 @@ game-project/
 - 外部 Runner 模式下，重试命令的 Session Runtime 快照可能仍指向旧 run，因此响应必须额外返回精确 `acceptedRunId` 作为入队受理事实，前端据此锁定恢复按钮并持续同步该 run，不能用 `state.runId` 是否立即切换判断失败。同一 `agentId + sourceRunId` 已存在非终态 retry successor 时必须幂等复用并返回其 `acceptedRunId`，不得再次入队或追加第二条 retry audit。
 - 该界面切片只允许受限的 loopback iframe，不得引入远程 URL、第二套资产模型、前端正式资源关系、前端版本替换真相或前端计费结论。

+### 资源画布布局持久化 V1
+
+2026-07-28 起，资源画布布局持久化以工作台 PRD §5.2 和 §7.2 为唯一编码合同，实施边界如下：
+
+- dependency 与 type 分别保存到 `.agent/workbench/resource-layouts/dependency.json` 和 `type.json`，schema 固定为 `game-creator-resource-layout.v1`。布局是本地工作台 UI sidecar，不进入 manifest、游戏项目 mutation revision、Runtime verification、Agent 产物、资产或云端事实。
+- `x / y` 使用 section 内容坐标，`updatedAt` 使用 Unix 毫秒；文件缺失只合成 revision `0` 空布局且不产生只读副作用。每个 mode 按 `projectId + mode + expectedRevision` 做 CAS，成功 revision 加一，冲突返回最新完整布局且不写文件。revision 虽在 Rust 中使用 `u64`，但跨 JSON / Tauri / TypeScript 的合法域固定为 `0..=Number.MAX_SAFE_INTEGER`；共享 DTO 序列化与反序列化、Tauri 输入和前端 IPC 响应均执行同一边界校验。
+- Tauri 命令固定为 `read_local_project_resource_canvas_layout` 与 `update_local_project_resource_canvas_layout`。写命令先只读确认有效 manifest，再通过持久 `.layout.lock` 入口获取句柄级跨窗口系统锁，并在锁内复核 projectId、重新读取当前 sidecar。Unix 使用 `flock`，Windows 使用不共享文件句柄；释放只通过句柄 Drop / 进程退出完成，不使用 mtime stale 回收，也不删除锁文件。其余写入继续复用安全路径、链接检查、容量上限、恢复副本与原子替换能力；不能只依赖 React 状态或进程内锁。
+- 前端从当前项目开发大组件中拆出纯布局模型与持久 Hook。默认布局、碰撞检查、资源增删协调和 section 边界由纯模型负责；读取、异步身份、CAS、错误回滚和冲突载入由 Hook 负责。Hook 以 `projectPath + projectId + mode` epoch 隔离异步结果，资源变化不取消首读或在途保存；单窗口写入经同一 FIFO 串行提交，每笔都使用最近一次成功 / 冲突响应的权威 revision。视图使用 Pointer Events 做二维拖动，保存中仍允许继续拖动并排队，普通点击、搜索、筛选和唯一资源详情浮层语义保持不变。
+- 新资源只在第一次进入某个 mode 时计算默认不重叠位置；全部现存坐标保持不变。搜索、筛选、窗口 resize 和 mode 切换不得重排或回写已有坐标，窄视图通过 section 画布范围与滚动访问，不裁切持久坐标。
+- type 默认布局固定按 `subtype -> mediaType -> label -> id` 排序。manifest 资产的 subtype 使用 `asset.kind`，任务产物、导入附件和 Agent 文本成果使用稳定的来源 fallback；subtype 必须进入资源协调签名，不能因 MIME 相同而退化成按名称混排。
+- 普通保存失败恢复最近可信持久布局；CAS 冲突载入对方最新布局并要求用户重新拖动，同时清除基于旧快照排队的全部手动意图，不自动重放旧坐标。即使冲突发生在允许自动重试的资源协调请求上，只要本次冲突清除了排队手动意图，重新拖动提示就必须绑定当前 scope 保留，不得被后续资源协调成功、失败或通用提示定时器静默清除；新的手动布局成功保存或 scope 切换后才解除。资源自动协调可基于冲突布局最多追加两次重试，持续跨窗口竞争时停止自旋并保留当前会话协调结果。损坏、未知 schema、身份冲突、超限与链接文件失败关闭，不能用空布局覆盖原文件。
+- 本切片不包含资源关系线、资源替换、详情浮层位置、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。关系线与其它 P1 能力必须在本切片独立验收后继续接入。
+
+实施顺序固定为：先同步 TypeScript / Rust DTO 与序列化测试，再实现 Tauri sidecar 读写和 CAS，随后接入前端纯模型、持久 Hook 与二维拖动，最后完成 Rust 安全测试、React 交互测试、跨重启 / 双窗口验收和文档状态回写。任何一步不得用 `localStorage`、manifest 字段或只在当前 React 会话有效的状态冒充项目持久化。
+
+2026-07-30 前端并发与性能加固状态：首读、资源更新和拖动保存已拆成 scope epoch + scope 内单写者 FIFO；定向 Hook 测试覆盖首读期间资源变化、在途手动 CAS 后资源协调、冲突清除排队拖动、旧 mode 迟到读取 / 写入、新 scope 不等待旧 scope 卡死请求、持续冲突有界停止，以及在途 CAS 后同资源连续拖动折叠为最后坐标。旧 scope 请求已经发出后不做不安全取消，但会释放前端活动槽并由 epoch 丢弃迟到响应；同 scope 的在途请求仍保持唯一。默认布局用 section 分组与二维占用索引替代逐 slot 全量扫描，dependency 使用按列单调游标，type 使用单调 slot 游标；`4096` 项双模式性能回归纳入前端测试，避免恢复到接近 `O(N³)` 的主线程阻塞实现。
+
+2026-07-30 Rust 并发与零副作用加固状态：资源布局锁已由 `create_new + mtime stale 删除` 改为持久锁文件上的 Unix `flock` / Windows 独占句柄，活锁即使 mtime 很旧也不能被另一个写入者回收，释放后仍复用同一文件实例。更新命令携带只用于校验的 `expectedProjectId`，在任何目录创建前先读取 manifest 并拒绝旧项目窗口，锁内再次核对 projectId；不存在根、非项目根、损坏 manifest 和路径重建后的旧窗口均不产生 `.agent/workbench`。revision 在共享 serde、Tauri 命令和前端 IPC 三层限制到 `Number.MAX_SAFE_INTEGER`，达到上限时保持原文件并失败关闭，不能让 Rust `u64` 值在 JavaScript 中失真后击穿 CAS。
+
 ## 分阶段实施

 1. 在 `platform-agent` 建立游戏创作专业组与种子任务图契约。