实现资源画布布局持久化 (#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>
This commit was merged in pull request #116.
This commit is contained in:
@@ -16,6 +16,16 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-28 AI 游戏创作资源画布布局使用本地双模式 CAS sidecar
|
||||
|
||||
- 背景：项目开发工作台当前只在 React 会话内保存同分类资源的一维拖拽顺序，项目切换或客户端重启后重建默认排列；工作台 PRD 虽已给出二维位置字段，但缺少落盘路径、坐标系、Tauri API、CAS、异常与安全边界，仍不足以直接编码。
|
||||
- 决策：dependency 与 type 两套布局分别保存为项目内 `.agent/workbench/resource-layouts/dependency.json` 和 `type.json`，统一使用 `game-creator-resource-layout.v1`。`x / y` 是 section 内容 CSS 像素，revision 从缺文件时的 `0` 单调递增；新资源首次默认放置，任何已有坐标不因排序、筛选、模式切换或 resize 被自动覆盖。type 默认布局固定按 `subtype -> mediaType -> label -> id` 排序，manifest 资产使用 `asset.kind`，任务产物、附件与 Agent 文本成果使用稳定 fallback，subtype 同时进入资源协调签名。
|
||||
- 并发与失败：Tauri 用 `read_local_project_resource_canvas_layout` 和 `update_local_project_resource_canvas_layout` 暴露读写，以 `projectId + mode + expectedRevision` 在专用跨窗口布局锁内做 CAS。更新额外携带只读结果中的 `expectedProjectId` 身份栅栏，路径被重建为新项目时旧窗口在锁副作用前失败；Rust 内部 revision 保留 `u64`，但共享 serde、Tauri 输入和前端 IPC 统一限制为 `0..=Number.MAX_SAFE_INTEGER`，达到上限时保持原文件。锁入口文件持久存在，Unix 以 `flock` 文件描述符、Windows 以不共享句柄持有互斥；应用不按 mtime / PID 猜测 stale、不删除锁文件，进程退出由操作系统释放。更新在创建锁目录前只读验证 manifest，锁内复核 projectId；无效根保持零 workbench 副作用。前端以 project/path/mode epoch 丢弃旧 scope 迟到响应，资源变化不得取消首读或同 scope 在途写；同 scope 的手动拖动与资源协调进入单写者 FIFO，后一笔只使用前一笔权威响应的 revision。切换 scope 会释放旧活动槽，旧请求即使卡死也不能阻塞新 scope；同资源尚未发送的连续拖动折叠为最后坐标，已经在途的 CAS 不取消。冲突返回最新完整布局且零写入，前端载入最新值、丢弃基于旧快照排队的手动拖动并要求重新操作；资源协调最多追加两次冲突重试，普通失败恢复最近可信布局。写入复用项目安全路径、链接校验、容量上限、恢复副本与原子替换，损坏或身份冲突不能被空布局覆盖。
|
||||
- 业务边界：布局是本地工作台 UI sidecar，不进入 manifest，不推进游戏项目 mutation revision，不使 Runtime verification 失效，不触发 Agent 权限，也不属于资产、Agent 产物、Git 或云端事实。本切片不包含关系线、资源替换、浮层位置、缩放 / 平移、搜索 / 筛选条件和当前 mode。
|
||||
- 影响范围：`packages/shared` 与 Rust `shared-contracts` 的跨边界 DTO、AI 游戏创作 Tauri 项目持久层与命令、项目开发资源画布、定向 Rust / React 测试、工作台 PRD 和客户端实施计划。
|
||||
- 验证方式：序列化与字段上限测试、缺文件 / 损坏 / 原子恢复 / 链接安全测试、同 revision 双写最多一个成功、两种 mode 跨重启独立恢复、新增资源不移动旧坐标、`1280×800` 横屏无页面级溢出，以及 `npm run agc:typecheck`、定向测试、`npm run check:encoding`、`git diff --check`。
|
||||
- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
|
||||
|
||||
## 2026-07-29 game-chat 在创建 WebView 前确定初始 URL
|
||||
|
||||
- 背景：`agc:game-chat` 曾在 Tauri `.setup()` 中读取仍可能是 `about:blank` 或配置期地址的 `client.url()`，再导航到 game-chat；Windows WebView2 首航被覆盖后只剩黑边白块或全白原生窗口，刷新无法恢复。
|
||||
|
||||
@@ -3864,6 +3864,38 @@
|
||||
- 约束：一次性语义应按“成功或确定性终态”消费，不按“函数调用次数”消费。项目写锁竞争保留同一授权并轮询重试；成功、显式 deny 与非瞬时失败才清除。授权需持久化项目路径和 accepted runId，重启恢复时仍必须逐项匹配，切换项目不得继承。
|
||||
- 回归：AppSurface 模拟第一次 `start_local_game_preview` 返回 `项目正在被其他写操作占用`、第二次成功，断言最终渲染游戏区域且启动调用恰为两次；完整 AppSurface 仍需覆盖显式 deny、停止隐藏与项目切换隔离。
|
||||
|
||||
## 跨窗口 CAS 锁不能用 mtime stale 删除模拟系统互斥（2026-07-30）
|
||||
|
||||
- 现象：两个窗口基于同一 revision 保存资源布局时，正常测试看似只有一个成功；锁文件超过 stale 阈值或两个竞争者同时判断过期时，却可能各自删除 / 重建锁并同时进入 read-check-write，击穿“同 revision 最多一个成功”。无效绝对路径还会在 manifest 报错前遗留 `.agent/workbench/resource-layouts`。
|
||||
- 原因：`create_new` 只保证某一时刻创建文件原子，不保证“判断过期 → 删除 → 重建”整体原子；mtime 不能证明 owner 已退出，token 文本也不能阻止另一个竞争者删除新锁。先获取锁再读 manifest 又把目录创建副作用提前到了项目身份验证之前。
|
||||
- 处理：锁文件作为持久入口永不由应用删除；Unix 用文件描述符持有 `flock(LOCK_EX | LOCK_NB)`，Windows 用 `share_mode(0)` 独占句柄，Drop / 进程退出让操作系统释放锁。安全打开逐级拒绝符号链接 / reparse point，Unix 还核对 owner、硬链接数、inode 和 `0600`。更新携带只用于校验的 `expectedProjectId`，先只读验证 manifest，再获取系统锁并在锁内复核 projectId；不存在根、非项目根、损坏 manifest 和路径复用后的旧窗口都不能创建 workbench。revision 必须 checked increment，耗尽时不能饱和成功。
|
||||
- 验证：必须覆盖活锁 mtime 被设为 epoch 后竞争者仍拿不到锁、释放后同一 inode 可重新获取、同 revision 并发双写仍恰好一个 updated / 一个 conflict，三类无效根和旧 projectId 零 workbench 副作用，以及 `u64::MAX` revision 保持原文件。锁等待超时只能返回可重试错误，不得转为 stale 删除。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/resource_layout.rs`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`。
|
||||
|
||||
## 旧 scope 的卡死请求不能占住新资源画布队列（2026-07-30）
|
||||
|
||||
- 现象：用户在 dependency 布局保存尚未返回时切到 type 或另一个项目，新 scope 已完成读取且拖动已进入队列，但因为全局活动请求引用仍指向旧 scope，新的保存会无限等待旧请求结束。
|
||||
- 原因：epoch 只阻止迟到响应覆盖新状态，不会自动释放前端单写者槽；把“不能取消已经发出的请求”误写成“所有后续 scope 都必须等待它”，会把一个网络或 IPC 卡死扩大到整个 Hook 生命周期。
|
||||
- 处理：FIFO 和单写者只约束同一 `projectPath + projectId + mode` scope。切换 scope 或卸载时立即放弃旧活动槽并清空旧队列，旧 Promise 仍可在后台结束，但其结果由 epoch 丢弃，finally 也只能按意图身份清理自己，不能清掉新 scope 的活动请求。后端继续用 `expectedProjectId`、CAS revision 和系统锁仲裁已经发出的旧写入。同 scope 在途 CAS 不取消；其后相同资源与 section 的排队拖动只保留最后坐标，避免连续输入造成无界队列。
|
||||
- 验证：让旧 mode 更新 Promise 永不先 resolve，切换 mode 后应立即发送并完成新 mode CAS；随后再 resolve 旧请求，新布局、saving 状态和请求数均不得变化。另以百次同资源拖动证明在途请求之后只追加一笔、坐标为最后一次输入。
|
||||
- 关联：`apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts`、`apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts`。
|
||||
|
||||
## 资源协调冲突清除排队拖动时不能静默重试（2026-07-31）
|
||||
|
||||
- 现象：资源协调 CAS 在途期间，用户拖动资源形成排队 manual intent；协调请求随后 conflict 并基于权威 revision 自动重试成功，布局正确保留另一窗口结果，但界面没有提示本地拖动已经被丢弃。
|
||||
- 原因：冲突分支虽然清除了当前 scope 的全部 manual intent，却只按“当前 intent 是否为 manual”或“资源协调是否停止重试”决定提示；当前 intent 为 resources 且可重试时，排队拖动的丢弃事实没有进入提示条件。
|
||||
- 处理：过滤队列前记录本次是否实际清除了 manual intent。只要当前 manual 发生冲突或清除了任何排队 manual，就必须提示用户重新拖动；冲突前坐标不得自动重放，后续资源协调继续使用冲突响应的权威 revision，并且成功响应不能静默清除提示。
|
||||
- 验证：定向 Hook 测试固定“resource sync revision 1 在途、manual 排队、权威 revision 2 conflict、resource retry 成功”时序，断言 retry 使用 revision 2、权威坐标保留、旧 manual 不重放且 notice 仍存在。
|
||||
- 关联：`apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts`、`apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts`。
|
||||
|
||||
## Rust u64 revision 不能直接穿过 JavaScript number 边界（2026-07-31）
|
||||
|
||||
- 现象：资源布局 sidecar 的 revision 在 Rust 中可增长到完整 `u64`，但经 JSON / Tauri 返回 TypeScript 后只能用 `number` 表示；超过 `9_007_199_254_740_991` 时相邻整数会折叠为同一值，窗口可能持续 conflict，甚至用失真的 expectedRevision 破坏 CAS 判等语义。
|
||||
- 原因：Rust 的 `checked_add` 只防止 `u64` 溢出，不能证明序列化后的整数仍能被 JavaScript 精确表示；纯 Rust `u64::MAX` 测试没有经过真实跨 JSON 合同。
|
||||
- 处理：保留 Rust `u64` 存储类型，但把共享合同合法域冻结为 `0..=Number.MAX_SAFE_INTEGER`。共享 DTO 对 revision 自定义 serde 校验，Tauri 更新在任何项目或锁副作用前验证 expectedRevision，sidecar 读取拒绝超限值，前端在 IPC 读取、更新响应和请求发送前重复验证非负安全整数；达到上限时写入失败且 sidecar 字节不变。
|
||||
- 验证：Rust 与 TypeScript 合同测试分别覆盖最大安全值往返、最大值加一拒绝；Tauri 持久层覆盖超限 expectedRevision 零 workbench 副作用、超限 sidecar 原字节保留和最大安全值递增失败；Hook 覆盖不可信读写响应不能进入 CAS。
|
||||
- 关联：`server-rs/crates/shared-contracts/src/game_creation_app.rs`、`packages/shared/src/contracts/gameCreationApp.ts`、`apps/ai-game-creator-shell/src-tauri/src/project/resource_layout.rs`、`apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts`。
|
||||
|
||||
## 抽通用 Runtime 时不要把产品持久文件直接变成公共 ABI
|
||||
|
||||
- 现象：为了快速“抽 crate”，直接把 Tauri package 内的 `AgentRuntimeState`、sidecar struct 或 Runner protocol 改成 `pub`，第二个消费者虽然能编译，却同时绑定游戏 schema、UI 投影、文件路径和未稳定恢复顺序。
|
||||
|
||||
Reference in New Issue
Block a user