实现资源依赖关系图层
新增资源依赖图模型、去重、环检测与上下游查询。 使用原生 SVG 渲染资源引用和聚合任务流，并接入搜索、高亮、拖动及生命周期清理。 修复资源自引用连线被卡片遮挡的问题。 补充前端回归测试并同步工作台 PRD、技术方案和决策记录。
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# AI 游戏创作项目开发工作台 PRD
|
||||
|
||||
更新时间：`2026-07-28`
|
||||
更新时间：`2026-07-31`
|
||||
|
||||
## 1. 产品定位
|
||||
|
||||
@@ -58,14 +58,14 @@
|
||||
|
||||
现有六个专业组为：
|
||||
|
||||
| group | 普通用户名称 | 当前职责 |
|
||||
| --- | --- | --- |
|
||||
| `design` | 策划组 | 玩法规格、界面原型、规则与验收口径 |
|
||||
| `art` | 美术组 | 角色、场景、UI、动画和美术素材 |
|
||||
| `code` | 程序组 | 可运行原型、模块实现和工程验证 |
|
||||
| `balance` | 数值组 | 速度、生命、得分和难度参数 |
|
||||
| `audio` | 音频组 | 背景音乐、音效和音频资源 |
|
||||
| `publishing` | 发布组 | 质量评审、试玩、打包和发布准备 |
|
||||
| group | 普通用户名称 | 当前职责 |
|
||||
| ------------ | ------------ | ---------------------------------- |
|
||||
| `design` | 策划组 | 玩法规格、界面原型、规则与验收口径 |
|
||||
| `art` | 美术组 | 角色、场景、UI、动画和美术素材 |
|
||||
| `code` | 程序组 | 可运行原型、模块实现和工程验证 |
|
||||
| `balance` | 数值组 | 速度、生命、得分和难度参数 |
|
||||
| `audio` | 音频组 | 背景音乐、音效和音频资源 |
|
||||
| `publishing` | 发布组 | 质量评审、试玩、打包和发布准备 |
|
||||
|
||||
- 底栏默认突出策划、美术、程序三组。
|
||||
- 允许在同一底栏展开数值、音频、发布组，不删除既有专业组。
|
||||
@@ -153,7 +153,7 @@ P0 中 `approvalMode` 只能有效写入 `strict`；其它值只能作为不可
|
||||
|
||||
### 5.2 资源画布布局（P1）
|
||||
|
||||
实现状态（2026-07-28）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；关系线、资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
|
||||
实现状态（2026-07-31）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式的前端资源依赖关系图层也已落地，但不写入布局 sidecar。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
|
||||
|
||||
```ts
|
||||
type ProjectResourceCanvasLayout = {
|
||||
@@ -247,6 +247,18 @@ type UpdateProjectResourceCanvasLayoutResult =
|
||||
- CAS 冲突时直接载入返回的最新布局并提示“布局已在其他窗口更新，请重新拖动”，丢弃所有基于冲突前快照排队的手动拖动，不得自动重放本地旧坐标或静默覆盖另一窗口结果。即使当前在途请求是允许自动重试的资源协调，只要本次冲突实际清除了任何排队手动拖动，也必须按当前 scope 保留重新拖动提示；后续资源协调成功、失败或通用提示定时器都不得静默清除，只有新的手动布局成功保存或切换 scope 才能解除。资源自动协调可以基于冲突返回的新 revision 有界重试，单次资源签名最多追加 `2` 次，持续跨窗口写入时不得无限自旋。
|
||||
- 缺少 Tauri bridge 的浏览器开发态可以保留当前会话内布局用于界面测试，但不得宣称已经持久保存。
|
||||
|
||||
#### 5.2.5 资源依赖关系图层
|
||||
|
||||
- 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
|
||||
- 输入固定为当前资源投影的全部卡片坐标与前端 `ProjectResourceGraph`；输出使用原生 SVG 的 path 和箭头 marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击和 Pointer Events 拖动。
|
||||
- `asset-reference` 表示精确资源引用，使用橙色实线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
|
||||
- `task-flow` 表示任务产物流转，使用灰色虚线。任务依赖按 `sourceTaskId -> targetTaskId` 聚合为一条主线，两端资源仅绘制分支；禁止对上下游资源生成笛卡尔积连线。
|
||||
- 图模型必须对资源引用图和完整任务依赖图做迭代式环检测，不得用无界递归遍历；参与环的可见边保留渲染并标记 cyclic，环本身不能造成重复生成或死循环。
|
||||
- 资源自引用的起点与终点为同一张卡片时，必须绘制在卡片外侧的可见闭环并保留箭头，不得让路径穿过卡片后被底层 SVG 层级遮挡。
|
||||
- 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
|
||||
- 选中资源后，高亮其直接上游、直接下游卡片和关联边，弱化其余边；不做跨多层递归高亮。选中 ID 已失效时按未选中处理。
|
||||
- 拖动预览坐标必须直接进入 SVG 几何计算，使连线随 pointer move 实时更新；拖动结束仍只保存卡片布局坐标，不持久化 path、marker、section 原点或任何图结构。
|
||||
|
||||
### 5.3 资源类型与替换兼容性（P1）
|
||||
|
||||
```ts
|
||||
@@ -382,9 +394,18 @@ type ProjectAgentMudPointAttribution = {
|
||||
6. 布局读写不改变 manifest、游戏项目 mutation revision、Runtime verification、Agent 权限与预览状态。
|
||||
7. `1280×800` 最小横屏下全部资源可通过分区滚动访问，不出现页面级横向或纵向溢出，右侧对话和底部 Agent 状态栏保持可见。
|
||||
|
||||
### 7.3 P1 资源依赖关系图验收
|
||||
|
||||
1. dependency 模式同时正确显示橙色实线资源引用与灰色虚线任务流；type 模式没有图层或连线。
|
||||
2. 精确引用只接受唯一有效的外部资源 ID 映射，删除或不存在的资源不产生幽灵连线。
|
||||
3. 多资源任务依赖只形成一条聚合主线与 `O(S+T)` 条端点分支，不产生 `S×T` 连线。
|
||||
4. 资源引用环和无资源产物参与的任务环都可被有限遍历识别，界面不死循环。
|
||||
5. 搜索、选择和拖动分别触发端点过滤、直接上下游高亮和实时几何更新；原有点击、详情浮层与拖动保存行为不回归。
|
||||
6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
|
||||
|
||||
## 8. 非目标
|
||||
|
||||
- 资源画布布局持久化切片不实现资源关系线、资源替换、不可变迭代版本、画板编辑状态、测试切片、数值参数或泥点归因。
|
||||
- 本切片仍不实现资源替换、不可变迭代版本、画板编辑状态、测试切片、数值参数或泥点归因；已实现的资源关系图只提供前端派生展示，不建立新的资源业务真相。
|
||||
- 本切片不保存资源详情浮层位置、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；这些状态如需持久化必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
|
||||
- 不修改 SpacetimeDB schema。
|
||||
- 不开放普通用户 Agent.md/Skill。
|
||||
|
||||
@@ -16,6 +16,15 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-31 AI 游戏创作资源依赖图采用纯前端派生 SVG
|
||||
|
||||
- 背景：资源画布已有 dependency / type 双模式坐标与本地 CAS sidecar，但 dependency 模式尚未把当前 manifest 中可证明的资源引用和任务流转可视化；关系图不能反向污染布局持久化或建立第二套资源真相。
|
||||
- 决策：dependency 模式从当前资源卡投影与 manifest task 派生 `ProjectResourceGraph`，使用原生 SVG 底层图层渲染。资产 `source.referenceResourceIds` 只在唯一匹配另一资产 `source.resourceId` 后形成橙色实线；任务依赖按任务对聚合为灰色虚线主线与两端分支，禁止资源笛卡尔积。图模型以迭代式强连通分量分析识别资源环和完整任务 DAG 环；搜索、选择、拖动只改变当前图层几何和高亮。
|
||||
- 生命周期与边界：type 模式不挂载图层；切换 mode、项目或卸载工作台时销毁 SVG、ResizeObserver 和窗口监听。SVG 统一 `pointer-events: none`，不干扰卡片点击/拖动；path、marker、图结构和 section 原点从不持久化。本切片不修改 Rust、Tauri command、layout sidecar、`resourceCanvasLayoutModel.ts`、manifest、api-server 或 SpacetimeDB，也不引入第三方图表库。
|
||||
- 影响范围：`apps/ai-game-creator-shell` 项目开发资源投影、依赖图模型、SVG overlay、样式与前端测试，以及工作台 PRD 和客户端实施计划。
|
||||
- 验证方式：图模型与 SVG 定向测试覆盖去重、无效 ID、完整任务环、可见资源自引用闭环、任务流聚合、搜索过滤、选择高亮和拖动几何；AppSurface 覆盖两种边、type 模式卸载和项目切换销毁，并运行 shell typecheck、编码检查与 `git diff --check`。
|
||||
- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
|
||||
|
||||
## 2026-07-28 AI 游戏创作资源画布布局使用本地双模式 CAS sidecar
|
||||
|
||||
- 背景：项目开发工作台当前只在 React 会话内保存同分类资源的一维拖拽顺序，项目切换或客户端重启后重建默认排列；工作台 PRD 虽已给出二维位置字段，但缺少落盘路径、坐标系、Tauri API、CAS、异常与安全边界，仍不足以直接编码。
|
||||
|
||||
@@ -318,8 +318,8 @@ game-project/
|
||||
|
||||
- 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
|
||||
- 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
|
||||
- 资源管理从当前 `GameCreationAppManifest` 派生项目文档、项目版本和 `assets`，并把首页已导入附件作为当前项目上传资源展示。资源按文档、版本、美术、动作、音乐音效分区；`按依赖 / 按类型` 只改变当前前端排列方式，不写回 manifest，也不伪造资源依赖。
|
||||
- 资源卡支持选择聚焦、文档展开 / 收起、搜索和类型筛选的界面交互。2026-07-28 起，原一维会话拖拽已替换为两套二维坐标与本地 CAS sidecar；画板编辑、生成关系连线、同类型版本资源替换仍不得在缺少各自正式写回契约时保存为业务事实。
|
||||
- 资源管理从当前 `GameCreationAppManifest` 派生项目文档、项目版本和 `assets`，并把首页已导入附件作为当前项目上传资源展示。资源按文档、版本、美术、动作、音乐音效分区；`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
|
||||
- 资源卡支持选择聚焦、文档展开 / 收起、搜索和类型筛选的界面交互。2026-07-28 起，原一维会话拖拽已替换为两套二维坐标与本地 CAS sidecar；2026-07-31 起，dependency 模式增加不持久化的原生 SVG 关系图层。画板编辑和同类型版本资源替换仍不得在缺少各自正式写回契约时保存为业务事实。
|
||||
- 运行表现层首版直接嵌入当前项目的 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 与回滚合同完备前不向普通用户开放。
|
||||
@@ -328,7 +328,7 @@ game-project/
|
||||
- 当前独立 App 只交付横屏桌面工作台，Tauri `client` 默认与最小窗口统一为 `1280×800`；用户不能继续缩小到破坏双栏结构的窄屏尺寸。桌面工作台占满壳内剩余视口，四周只保留必要安全边距；右侧消息、Runtime 状态和输入区保持在同一栏内，专业状态过长时只滚动 Runtime 区，不得把输入区、底部 Agent 状态栏或整页撑出视口。`≤760px` 的浏览器样式仅保留开发兼容，不作为当前客户端交付口径。
|
||||
- 项目总控失败摘要必须提供“在当前项目重试总控”的明确恢复动作并说明不会新建项目；旧父 run 下仍在运行的专业 Agent 继续展示真实状态。terminal 总控下不得单独重试专业 Agent，避免创建没有可交付父级的孤立委派；新总控 run 负责重新建立后续专业委派合同。
|
||||
- 外部 Runner 模式下，重试命令的 Session Runtime 快照可能仍指向旧 run，因此响应必须额外返回精确 `acceptedRunId` 作为入队受理事实，前端据此锁定恢复按钮并持续同步该 run，不能用 `state.runId` 是否立即切换判断失败。同一 `agentId + sourceRunId` 已存在非终态 retry successor 时必须幂等复用并返回其 `acceptedRunId`，不得再次入队或追加第二条 retry audit。
|
||||
- 该界面切片只允许受限的 loopback iframe，不得引入远程 URL、第二套资产模型、前端正式资源关系、前端版本替换真相或前端计费结论。
|
||||
- 该界面切片只允许受限的 loopback iframe，不得引入远程 URL、第二套资产模型、前端版本替换真相或前端计费结论。资源关系图只能读取当前 manifest 与资源投影做派生展示，不得成为前端正式资源关系真相。
|
||||
|
||||
### 资源画布布局持久化 V1
|
||||
|
||||
@@ -341,7 +341,7 @@ game-project/
|
||||
- 新资源只在第一次进入某个 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 能力必须在本切片独立验收后继续接入。
|
||||
- 本布局持久化切片不包含资源关系线、资源替换、详情浮层位置、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。资源关系线已在后续独立的纯前端切片接入，不改变本段 sidecar 合同；其余 P1 能力继续独立实施。
|
||||
|
||||
实施顺序固定为：先同步 TypeScript / Rust DTO 与序列化测试，再实现 Tauri sidecar 读写和 CAS，随后接入前端纯模型、持久 Hook 与二维拖动，最后完成 Rust 安全测试、React 交互测试、跨重启 / 双窗口验收和文档状态回写。任何一步不得用 `localStorage`、manifest 字段或只在当前 React 会话有效的状态冒充项目持久化。
|
||||
|
||||
@@ -349,6 +349,19 @@ game-project/
|
||||
|
||||
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。
|
||||
|
||||
### 资源依赖关系图层 V1
|
||||
|
||||
2026-07-31 起，项目工作台在不修改 Rust、layout sidecar 和既有布局模型的前提下增加纯前端资源依赖图层：
|
||||
|
||||
- `resourceDependencyGraphModel.ts` 负责从当前资源卡投影和 manifest task 构建 `ProjectResourceGraph`。精确引用把资产 `source.referenceResourceIds` 唯一匹配到另一资产的 `source.resourceId`，再转换为实际卡片 ID；无匹配、多匹配和已删除资源只记录为 unresolved，不生成边。引用边按 `sourceResourceId + targetResourceId` 稳定去重。
|
||||
- task flow 只读取存在于当前 manifest 的任务依赖。资源按 `producerTaskId` 分组，每个 `sourceTaskId -> targetTaskId` 只生成一个聚合 flow；SVG 侧绘制 source 分支、唯一主线和 target 分支，路径数量为 `O(S+T)`，禁止资源笛卡尔积。
|
||||
- 资源引用图和完整任务依赖图分别使用迭代式强连通分量分析。任务环检测不能依赖可视 task flow 是否有两端资源，否则无产物任务参与的环会漏报；循环边只带 cyclic 标记，不触发递归展开。
|
||||
- `ResourceDependencyOverlay.tsx` 使用原生 SVG path/marker，绝对定位在 `.game-resource-canvas-content` 底层并统一 `pointer-events: none`。橙色实线表示 `asset-reference`，灰色虚线表示 `task-flow`；不引入 D3、React Flow 或其它图表依赖。
|
||||
- `asset-reference` 的 source / target 是同一资源时使用卡片右侧外绕贝塞尔闭环，两个锚点分开且 marker 保留在返回锚点；路径不穿过卡片，并与普通边一样直接由拖动预览坐标重算。
|
||||
- 图层用 SVG 自身节点定位所属画布容器，测量各 section plane 相对原点；`ResizeObserver` 与 window resize 只负责重新测量，并在卸载时清理。这样不依赖父组件 ref 在子组件 layout effect 中的绑定时序。type 模式不挂载图层；项目身份作为 key，切换 mode、项目或工作台卸载都会销毁旧 SVG。
|
||||
- 搜索可见 ID 在几何阶段过滤端点；选中资源只查询一跳上下游与关联边，关联卡片和边高亮，其余边弱化。拖动预览坐标直接替换当前卡片坐标传入图层，pointer move 实时更新 path；结束后仍只通过原布局 Hook 保存卡片坐标，SVG 几何从不持久化。
|
||||
- 前端模型、SVG 单测和工作台 AppSurface 回归覆盖精确引用、去重、无效 ID、完整任务环、聚合复杂度、搜索过滤、选择高亮、拖动更新、type 模式卸载与项目切换销毁。该切片不修改 `resourceCanvasLayoutModel.ts`、Tauri command、layout sidecar、`api-server`、Rust 或 SpacetimeDB。
|
||||
|
||||
## 分阶段实施
|
||||
|
||||
1. 在 `platform-agent` 建立游戏创作专业组与种子任务图契约。
|
||||
@@ -361,7 +374,7 @@ game-project/
|
||||
|
||||
- 用户能创建本地 Web 游戏项目。
|
||||
- 用户进入项目开发页后能看到资源管理主视窗、陶泥儿对话栏和底部策划 / 美术 / 程序 Agent 状态栏；`1280×800` 最小横屏窗口和更大桌面窗口均不得出现页面级横向 / 纵向溢出，对话输入与底部 Agent 状态栏始终位于视口内。
|
||||
- 资源管理可在按依赖 / 按类型之间切换、搜索资源、展开文档和聚焦资源；所有展示数据来自当前 manifest 或当前项目导入附件。
|
||||
- 资源管理可在按依赖 / 按类型之间切换、搜索资源、展开文档和聚焦资源；dependency 模式展示可验证的资源引用和聚合任务流，搜索、选择与拖动同步更新线段；所有展示数据来自当前 manifest、当前资源投影或当前项目导入附件。
|
||||
- 首个 `code-prototype` 任务未完成时运行入口不可进入并给出可感知提示；完成后可进入运行表现层，真实预览直接加载到客户端内受限运行容器。
|
||||
- 审批档位通过独立弹出面板切换，默认严格审批；界面选择不得绕过 Runtime 现有确认门禁。
|
||||
- 聊天输入 `/plan` 可在普通聊天消息里查看下一轮分工计划，不读取任务文件、不启动 run、不修改项目，也不新增普通用户计划面板。
|
||||
|
||||
Reference in New Issue
Block a user