完善资源管理工作台与有界预览
将资源卡本体化并补齐分区缩放滚动与依赖聚类 增加全进程三槽预览调度范围取消与安全分块读取 保持布局 CAS 预览缓存回收和依赖图权威合同 补齐资源管理前端 Tauri AppSurface 回归并同步文档
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# AI 游戏创作项目开发工作台 PRD
|
||||
|
||||
更新时间：`2026-08-10`（现有 Godot 项目入口与项目根绑定）
|
||||
更新时间：`2026-08-10`（资源卡本体化、分区缩放、同类型依赖聚类与详情优先收口；现有 Godot 项目入口与项目根绑定）
|
||||
|
||||
## 1. 产品定位
|
||||
|
||||
@@ -50,6 +50,22 @@
|
||||
- 资源分区由资源投影固定，前端交互不能改变分类。
|
||||
- 资源卡手动拖动、拖动持久化、拖动性能与冲突后的重新拖动提示全部暂缓，不作为当前产品合同或验收条件。
|
||||
|
||||
#### 3.3.1 资源管理三个串行阶段
|
||||
|
||||
1. 阶段一“资源卡本体化”：`dependency / type` 两种布局共用同一个资源卡组件和预览调度器。图片与安全 SVG 直接显示主体并保留透明棋盘底；视频显示首个可解码画面并可在卡内播放；音频使用清晰的音频视觉和独立播放键；文档显示安全纯文本摘要或稳定类型占位；项目版本不伪造媒体，只显示稳定版本视觉和必要的父子 / 绑定状态。中央详情以元数据、Rust 权威依赖关系和版本信息为主，不重复放大图片、SVG 或视频；文档正文和按用户意图读取的音频控件位于元数据之后。
|
||||
2. 阶段二“分区独立缩放”（已完成）同时包含互不替代的分区可视高度和内容倍率。文档、项目版本、美术资源、音乐音效资源的标题栏分别保留高度减小 / 恢复 / 增大，并新增 `50%..200%` 内容缩放减小 / 百分比复位 / 增大；触摸板捏合、`Ctrl/Cmd + wheel` 与按钮使用同一倍率模型，普通双指滚动仍只滚动。高度与倍率都以 `projectId + layoutMode + category` 隔离并只保留在当前会话内存；倍率以分区 viewport 中的手势中心为锚点，逻辑 `x / y`、`180×128` 本体尺寸和媒体比例不变。最小高度固定容纳标题操作与至少一排卡片，最大高度以中央资源画布当前可用高度为上限。分区保持正常文档流，后续分区由外层资源画布滚动访问，单区内容在缩放后仍只在该区内部滚动。两类表现态都不修改 manifest、`game-creator-resource-layout.v1`、布局 CAS 或资源身份，不重建媒体控件、不抢走焦点，也不恢复卡片拖动。
|
||||
3. 阶段三“依赖布局聚类”（已完成）：仅在 `dependency` 模式中，按固定资源分区对当前 Rust 只读图返回的同类型精确引用边和同类型聚合任务流做弱连通分组；任务流以流节点连接其成员，绝不展开成资源笛卡尔积，但只作为布局邻近提示，不绘制虚线、不进入画布关系说明。`dependencyDepth` 是唯一横向层级权威；每个相关簇先按“最小深度 -> 最小稳定资源 ID”排序，再在同层进行固定两轮由左至右、由右至左的中位数扫描，平局回退稳定资源 ID；同 SCC/环成员保持连续，环后资源继续按 Rust 深度推进。孤立资源是稳定单例组，紧凑排在相关簇之后，簇之间保持固定留白。跨分类 read model 关系不改变 Rust 业务真相，但不得进入前端布局邻接、关系说明或 SVG；搜索只隐藏卡片和橙色精确引用边，不重算组或压缩坐标。历史 `manuallyPlaced=true` 坐标继续原样保留并参与自动坐标避让。聚类是可派生表现，不新增 manifest 字段、sidecar schema、SpacetimeDB 表或第二套依赖真相。
|
||||
|
||||
#### 3.3.2 本体化资源卡交互与性能合同
|
||||
|
||||
- 卡片默认可视区域不再显示文件名、资源名称、来源、路径、任务和媒体类型等详细文本。这些字段继续进入搜索索引和中央详情；卡片“打开详情”入口的可访问名称必须包含稳定可辨识的资源名与类别。
|
||||
- 卡片外层是非交互容器；“打开详情”与“播放 / 暂停”必须是可分别键盘聚焦的同级按钮，禁止在 `<button>` 中嵌套 `<button>`。播放键不选择资源、不打开详情。
|
||||
- 同一时间最多播放一个卡片音频或视频。打开详情、切换布局模式、切换项目、进入运行视图、搜索 / 筛选隐藏当前资源、当前资源被删除或资源身份 / 路径变化时，必须暂停旧媒体并收口待播放意图；卡片卸载还必须执行防御性暂停。同资源 ID 的无关 manifest 更新不得重建控件或抢走焦点。
|
||||
- 图片、视频首帧和项目文档只在卡片进入资源画布可见区及小幅预取边界后读取；音频只在用户点击播放后读取。前端逻辑调度器必须使用有界并发、同身份去重、有界 LRU 淘汰，不允许按全部投影同步启动读取。`play > detail > visible` 是固定调度优先级；可见性预取不得占满全部队列容量或静默丢弃播放 / 详情请求，主动请求进入硬上限队列时必须替换最低优先级的排队预取并优先执行。终态预览缓存同时受 `48` 项和 `64 MiB` 总载荷双重上限约束，媒体按解码后的 Blob 字节、文档按 UTF-8 字节计入；Tauri 返回的 data URL 只允许作为 IPC 临时载体，进入 React 状态前必须转换为可撤销的 Blob URL。LRU 淘汰、资源删除、项目 / mode 切换和卸载都必须 `revokeObjectURL`，不能让 base64 字符串或失效 Blob 长期占用 WebView。
|
||||
- 卡片读取继续调用 `read_local_project_image_preview`、`read_local_project_media_preview` 和 `read_local_project_text_preview`；项目边界、manifest / 任务登记、`file.read` 策略、普通文件 / 链接、签名、尺寸和读取漂移门禁不变。每个 Hook 挂载及每次 `projectPath + projectId + mode` 变化必须生成不复用的 `scopeId`，每个实际读取生成唯一 `requestId`；每个队列任务和结果继续绑定完整的 `projectPath + projectId + mode + resourceId + category + path + mediaType`。前端 scope epoch 只隔离逻辑队列、缓存和异步回调；三个读取命令在 Tauri 进程中共用唯一的全局 `3` 槽物理读取管理器，不能因项目、mode、Hook 或窗口不同获得额外物理槽。scope 切换或卸载必须调用窄职责 `cancel_local_project_resource_preview_scope`，使等待 permit 和分块读取中的旧任务协作取消；旧 epoch 的 `then / catch / finally` 仍不得写入、释放或扣减新 scope 的前端状态，`A → B → A` 也不得复用第一轮 A 的 scope、请求或迟到结果。
|
||||
- 原生读取必须在命令入口、权限 / 登记复核后、打开文件后、每个固定上限读取块之间、签名 / 图片结构校验前、漂移复核前和 base64 编码前检查取消。取消的排队任务不得打开文件，取消的在途任务不得生成 data URL 或 Blob URL；全局 permit 只能在对应原生任务结束后释放。重复 `requestId` 失败关闭，取消未知或已完成 scope 幂等成功；成功、失败和取消均必须清理活动 request / scope registry。为防止近期 request ID 重放和已取消 scope 复活，原生管理器继续保留有界 tombstone：seen request 最多 `8192` 项；非活动 cancelled scope 的保留预算为 `1024` 项，仍有请求的已取消 scope 必须临时钉住，最后一个请求结束后立即重新淘汰到预算内。明确取消只静默收口旧 scope，当前 scope 的真实 transient / permanent 失败语义不变。
|
||||
- 安全读取失败、图片解码失败或视频无可解码画面时，卡片展示稳定类型占位，不挂载破图，不降级为项目外 URL 或裸路径读取。滚动可见性不得自动重试已失败预取；读取漂移、文件替换和通用暂时失败标记为 transient，用户再次打开详情或点击播放时可以显式重试。超尺寸、损坏、类型不支持和不安全 SVG 等永久失败继续缓存且不得用“关闭后重试”误导用户。
|
||||
|
||||
### 3.4 数值微调
|
||||
|
||||
- 数值修改立即写入当前项目的编辑态配置。
|
||||
@@ -131,11 +147,11 @@ idle -> focused(document|art|audio|version) -> idle
|
||||
```
|
||||
|
||||
- 文档：合法 Agent 文本回执直接使用对话投影内容；项目文件只允许读取当前 manifest 已登记资产或已完成任务产物中的 Markdown、文本、JSON、YAML、TOML，必须经过 `file.read` auto 权限、相对路径、项目边界、普通文件、符号链接 / 硬链接、读取漂移、2 MiB、UTF-8 与扩展名白名单校验。正文使用不执行 HTML、不加载远程图片、不产生可点击外链的安全 Markdown 渲染，并在中央画布内独立滚动；读取失败显示错误空态。
|
||||
- 美术：PNG、JPEG、WEBP 继续使用图片魔数与像素边界预览；GIF、SVG、AVIF、BMP、MP4、WebM、MOV 通过新增受控媒体读取链路按文件签名校验后在中央画布放大聚焦。SVG 额外拒绝脚本、事件处理器、外部资源引用和实体声明；视频使用内置播放控件。读取失败显示错误空态。
|
||||
- 美术：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 状态栏保持原位；聚焦容器只包含标题、资源主体、必要元数据与右上角收起按钮，不使用页面级浮层或可拖动标题栏。
|
||||
- 点击资源后，中央主视窗从 `resources.list` 切换为 `resources.focused.document / art / audio / version`，左侧平台导航、右侧 Supervisor 对话和底部 Agent 状态栏保持原位。聚焦容器以路径、类型、来源任务、Rust 权威依赖层级、同类型上下游、同类型任务流和版本字段为首屏主体；美术图片与视频不在详情页重复展示大尺寸本体，避免遮挡信息。文档正文与按意图加载的音频控制位于元数据之后；不使用页面级浮层或可拖动标题栏。
|
||||
- 焦点转换以稳定资源 ID 为准。只有从资源列表进入详情或从一个资源 ID 切换到另一个 ID 时聚焦详情 region；同一资源 ID 因 manifest 更新而重新投影时，不得抢走详情内音频 / 视频控件、文档链接或收起按钮的当前焦点。
|
||||
- 显式收起或按 Escape 后恢复进入前的搜索条件、dependency / type 布局模式、资源画布滚动位置和选中资源，并优先把键盘焦点还给原触发资源卡；这些只属于当前前端会话，不写入布局 sidecar。若资源已经被后台删除，必须清理 stale focused / selected ID、关闭详情并把焦点落到“搜索项目资源”，不得落到 `body`。项目切换和进入运行视图必须取消旧项目的焦点恢复意图。
|
||||
- 阶段四只新增上述受控读取与媒体展示；阶段六在同一聚焦容器内补齐正式版本只读展示和引用高亮，但不新增资源聚焦工具栏 / 工具侧边栏，不新增美术编辑、音频编辑 / 替换、资源重新生成、版本替换或运行模块。飞书原需求中“编辑并生成新资源”的条件项仍暂缓，不能只打开画板却缺少回写、`referenceResourceIds` 血缘登记、新资源自动选中与邻近布局的完整闭环。
|
||||
@@ -168,7 +184,7 @@ P0 中 `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-10）：dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑与确定性依赖深度、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。依赖图加载完成前设布局初始化屏障，避免以临时 `dependencyDepth=0` 生成并持久化错误坐标。当前用户入口只允许自动布局与资源卡点击；资源卡手动拖动已按 mentor 决定暂缓。历史 sidecar 坐标继续只读恢复，底层布局读写与 CAS 合同保留，但当前没有用户手动布局入口。阶段二的分区可视高度与内容倍率都是和 sidecar 完全分离的当前会话表现态；内容倍率不改变持久逻辑坐标或资源身份。整个资源画布的自由平移、资源替换等其余 P1 能力仍按本文非目标保持未实现。
|
||||
|
||||
```ts
|
||||
type ProjectResourceCanvasLayout = {
|
||||
@@ -251,10 +267,11 @@ type UpdateProjectResourceCanvasLayoutResult =
|
||||
|
||||
- 资源卡是可点击按钮，只负责选择资源并让中央主视窗进入当前唯一资源聚焦状态；不得绑定卡片级 `pointerdown / pointermove / pointerup / pointercancel` 拖动处理器。
|
||||
- 指针移动不得修改卡片 `x / y`、不得产生拖动预览、不得更新依赖线几何，也不得提交手动布局 CAS。卡片 title、cursor、`touch-action` 和 class 不得暗示可拖动。
|
||||
- dependency 默认布局按 `dependencyDepth` 形成横向层级，同层资源纵向寻找第一个不重叠位置；type 默认布局固定按“资源子类型 -> 媒体类型 -> 名称 -> 资源 ID”稳定排序，在分区内从左到右、从上到下寻找第一个空位。布局模型的 `subtype` 必填：manifest 资产使用 `asset.kind`，任务产物、导入附件与 Agent 文本成果分别使用稳定的 `task-artifact`、`attachment`、`agent-result`，不得以缺失值或显示文案兜底；资源协调签名必须包含 subtype。卡片尺寸与间距由单一前端布局模型常量维护。
|
||||
- type 模式资源集合变化时保留全部仍存在的坐标，只为新 ID 计算默认位置，并删除已确认失效的旧 ID。dependency 模式只永久保留 `manuallyPlaced=true` 的用户坐标；`manuallyPlaced=false` 属于可派生自动位置，在 Rust 关系图首次就绪或可信 producer / dependency depth 变化后按最终拓扑确定性重算。自动重算不得移动手动坐标，协调结果与持久布局逐项一致时不得产生 CAS 写入。
|
||||
- dependency 默认布局按 Rust 返回的 `dependencyDepth` 形成横向层级；同层仅在所属固定分区内按精确引用、聚合 task-flow 的稳定邻接、连通簇和固定两轮中位数扫描确定纵向次序，随后寻找第一个不重叠位置。task-flow 只作为聚合超边参与分组和排序，不能生成资源两两边。dependency 自动布局使用专用 `48px` 列间走线区和 `40px` 行间走线区；相关簇以本簇最大层行数为高度，资源较少的层在该高度中居中，避免菱形 / 分叉关系一侧极短、另一侧过长。type 默认布局继续使用原有 `16px` 行列间距，并固定按“资源子类型 -> 媒体类型 -> 名称 -> 资源 ID”稳定排序。布局模型的 `subtype` 必填：manifest 资产使用 `asset.kind`，任务产物、导入附件与 Agent 文本成果分别使用稳定的 `task-artifact`、`attachment`、`agent-result`，不得以缺失值或显示文案兜底；资源协调签名必须包含 subtype。卡片尺寸、间距和 `0..=1_000_000` 坐标上限由前后端同名合同维护。超深依赖仍保留原始 `dependencyDepth` 业务真相，但显示坐标在上限列确定性饱和并纵向避让；自动布局在 IPC 前必须保证全部 `x / y` 合法，不能向 Tauri 永久重放必然失败的坐标。
|
||||
- type 模式资源集合变化时保留全部仍存在的坐标，只为新 ID 计算默认位置，并删除已确认失效的旧 ID。dependency 模式只永久保留 `manuallyPlaced=true` 的历史坐标；`manuallyPlaced=false` 属于可派生自动位置，在 Rust 关系图首次就绪、`dependencyDepth` 或资源拓扑身份签名（精确引用端点和聚合 task-flow 成员）变化后按最终拓扑确定性重算。签名以稳定资源 ID 的规范端点 / 成员序列生成固定大小摘要，不使用显示名称或浏览器测量值；自动重算不得移动手动坐标，协调结果与持久布局逐项一致时不得产生 CAS 写入。
|
||||
- 搜索或筛选只隐藏卡片，不删除、压缩或重排其坐标；清空搜索后恢复原位置。
|
||||
- 窗口尺寸变化只改变可视范围和分区滚动边界，不回写、裁切或缩放持久坐标。当前客户端继续以 `1280×800` 横屏合同验收。
|
||||
- 窗口尺寸变化只改变可视范围和分区滚动边界，不回写或裁切持久坐标。当前客户端继续以 `1280×800` 横屏合同验收。
|
||||
- 分区高度和内容倍率都不属于逻辑布局几何。资源卡始终使用原 `x / y` 与 `180×128` 逻辑尺寸；内容 plane 只在显示层按 `50%..200%` 变换，并用同比例 frame 形成真实滚动范围。标题栏后的分区 viewport 使用内部滚动暴露缩放后的卡片，整个分区继续参与外层正常文档流。触摸板捏合、`Ctrl/Cmd + wheel` 与缩放按钮共享倍率状态，普通 wheel 不缩放；`Ctrl/Cmd + wheel` 必须由可取消的原生 `{ passive: false }` 监听处理并真实取消 WebView 默认缩放。搜索、项目或 mode 切换均不得把倍率写回布局。分区内部滚动按 `projectId + mode + category` 隔离，外层资源画布按 `projectId + mode` 隔离，二者在详情开关、模式与项目切换后分别恢复。
|
||||
- 打开项目、切换 mode 或当前 mode 首次出现新资源时执行“读取 -> 协调 -> 必要时 CAS 写入”；dependency 模式必须先等待与当前 `projectPath + projectId + resource inputs` 匹配的 Rust 图进入 `ready` 或 `failed` 终态，等待期间不得创建 fallback、读取 sidecar、协调资源或入队保存。`failed` 只允许以空图降级初始化一次。项目或 mode 已切换后返回的旧异步结果必须丢弃。
|
||||
- 同一 `projectPath + projectId + mode` 的首次读取与资源集合协调必须分开：资源集合变化不得取消已经发出的读取或保存。当前 scope 内资源自动协调写入使用单写者 FIFO，任一时刻最多一个 CAS 在途，后一笔必须使用前一笔成功返回的 revision。切换项目或 mode 后，旧 scope 的在途请求不能阻塞新 scope 队列；前端放弃旧请求槽位并丢弃其迟到响应，后端继续依靠 `expectedProjectId + expectedRevision + 系统锁` 仲裁已发出的请求。
|
||||
- 自动协调 CAS 冲突时直接载入返回的最新布局；仍需协调时可以基于权威 revision 最多追加 `2` 次重试，持续跨窗口写入时不得无限自旋。当前提示只说明“布局已在其他窗口更新”，不得要求用户重新拖动。
|
||||
@@ -271,17 +288,18 @@ type UpdateProjectResourceCanvasLayoutResult =
|
||||
- 阶段五实现状态（2026-08-03）：dependency 自动排列同时消费任务 DAG 与精确资源引用。Rust 把可信 producer 的任务深度作为资源深度下限，再对 `asset-reference` 图做迭代式 SCC 压缩与确定性层级传播；被引用资源位于引用资源之前，同一引用环共享稳定深度，环后资源继续递增，没有引用关系的资源保持默认不重叠位置。布局深度通过独立 `dependencyDepths` 返回，不能把 producer assignment 冒充全部资源的布局结果。
|
||||
- `producerMappingTruncated=true` 只关闭依赖有界 Agent DB 审计的 `producerAssignments`、`taskFlows` 和 `cyclicTaskIds`。Rust 返回的 `dependencyDepths` 仍是 manifest / 精确引用 read model 的权威结果，前端必须过滤未知资源、负数、非整数和非安全整数后继续消费；不得因 producer 截断清空全部深度，也不得在前端重算替代深度。`referenceEdges`、connection index 中的 reference 关系、`cyclicResourceIds` 和 unresolved reference 继续保持可信。
|
||||
- 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
|
||||
- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击。
|
||||
- `asset-reference` 表示精确资源引用，使用明亮橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
|
||||
- `task-flow` 表示同一资源类型内的任务产物流转，使用灰色圆头虚线；文档、项目版本、美术、音频之间不得绘制跨分区虚线。任务依赖按 `sourceTaskId -> targetTaskId + section` 分区聚合为一条主线，两端只保留同分区资源并绘制平滑曲线分支，不得出现直角折线；禁止对上下游资源生成笛卡尔积连线。任务主线与分支可以使用不同线宽和透明度表达聚合层级，但不能改变端点或方向语义。
|
||||
- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、逻辑 viewport 裁剪与原生 SVG path / marker。每个固定分区在自己的 `.game-resource-plane` 内持有一个 SVG，SVG 与卡片直接消费同一逻辑坐标、卡片尺寸、CSS scale 和 viewport scroll；端点主路径不得再通过 `getBoundingClientRect` 拼接全局屏幕坐标。SVG 位于资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击。
|
||||
- `asset-reference` 表示精确资源引用；只有两端属于同一固定资源分类时才进入前端布局邻接、无障碍关系说明和 SVG，使用明亮橙色实线与实心箭头。跨分类引用仍可存在于 Rust read model，但资源管理画布不得绘线、不得以它形成布局簇或边界偏置。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
|
||||
- `task-flow` 表示同一资源类型内的任务产物流转，但资源画布不再绘制灰色虚线或任务流 marker，也不把它加入 `aria-describedby` 关系说明。它只按 `sourceTaskId -> targetTaskId + section` 作为聚合超边参与 dependency 连通簇和中位数排序，禁止对上下游资源生成笛卡尔积邻接；详情仍可展示 Rust read model 已证明的任务信息。
|
||||
- 画布资产 producer 只能来自 `agent.runtime.canvas.asset_generate` 的 `assetId -> agentId` 审计且 `agentId` 必须存在于当前 manifest；External Editor `source.taskId` 属于平台生成任务命名空间，禁止当作 manifest task ID。证据缺失、冲突或有界审计读取未覆盖时不生成对应 task flow，不猜测归属。
|
||||
- 图模型必须对资源引用图和完整任务依赖图做迭代式环检测，不得用无界递归遍历；参与环的可见边保留渲染并标记 cyclic，环本身不能造成重复生成或死循环。
|
||||
- 资源自引用的起点与终点为同一张卡片时，必须绘制在卡片外侧的可见闭环并保留箭头，不得让路径穿过卡片后被底层 SVG 层级遮挡。
|
||||
- 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
|
||||
- 资源点击只进入中央聚焦并保留当前选中卡片，不改变依赖卡片或连线的颜色、线宽与透明度；关系线始终直接展示，不提供点击后的上下游高亮或无关线弱化。
|
||||
- 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该橙线隐藏。task-flow 不产生显示几何，搜索也不因此重排布局。
|
||||
- 同类型精确引用按稳定边 ID 和对端次序为同一卡片同侧的多条边分配独立端口；横向层级可用时优先左右连接，同列或横向间隙不足时才上下连接。同轴端点直接用直线，需转向时使用正交线段与最大 `10px` 的小圆角，不使用大范围贝塞尔控制柄。端口顺序不使用显示名称、随机数或浏览器枚举顺序，相同输入必须产生相同路径。资源点击只进入中央聚焦并保留当前选中卡片，不改变依赖卡片或连线的颜色、线宽与透明度；关系线始终直接展示，不提供点击后的上下游高亮或无关线弱化。
|
||||
- 资源卡 Pointer Move 不改变基础 positions 或 SVG 几何。连线只随布局读取、资源自动协调、搜索、项目切换或 section origin 变化而更新。
|
||||
- `ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
|
||||
- 阶段五不改变手动位置边界：已有 `manuallyPlaced=true` 坐标原样保留，资源引用新增或变化只允许重新派生 `manuallyPlaced=false` 的自动坐标；任务流继续按任务对与资源分区聚合，禁止为了计算深度或绘线生成资源笛卡尔积。
|
||||
- 每个已挂载 dependency 分区最多构造一个 `ResizeObserver`，四区总数最多四个；observer 只维护该分区的逻辑 viewport，不测量或重建卡片屏幕端点。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
|
||||
- 分区高度、分区内部滚动和窗口 resize 在各分区内通过单一 `requestAnimationFrame` 调度器合并逻辑 viewport 更新，不得在每个 scroll event 中同步重算。浏览器以分区 viewport 原生裁剪同属该 plane 的 SVG 和卡片，因此线段不能穿过标题栏或泄漏到其它分区；一端可见时绘制入向 / 出向边界继续线，两端都离屏时不渲染。项目 / mode 切换或卸载时必须清理对应 observer、scroll 与 window resize 监听。
|
||||
- 阶段五不改变手动位置边界：已有 `manuallyPlaced=true` 坐标原样保留，资源引用新增或变化只允许重新派生 `manuallyPlaced=false` 的自动坐标；任务流继续按任务对与资源分区聚合，禁止为了布局分组生成资源笛卡尔积，且不进入 SVG。
|
||||
|
||||
### 5.3 资源类型与替换兼容性（P1）
|
||||
|
||||
@@ -439,15 +457,17 @@ type ProjectAgentMudPointAttribution = {
|
||||
|
||||
### 7.3 P1 资源依赖关系图验收
|
||||
|
||||
1. dependency 模式显示对画布背景至少 `3:1` 对比度的橙色实线资源引用，并只在同一资源类型分区内显示灰色虚线任务流；跨类型不显示虚线，type 模式没有图层或连线。
|
||||
1. dependency 模式只显示同一资源类型分区内的精确引用，使用对画布背景至少 `3:1` 对比度的橙色实线箭头；聚合任务流只参与布局，不绘制灰色虚线或 marker。type 模式没有图层或连线。
|
||||
2. 精确引用只接受唯一有效的外部资源 ID 映射，删除或不存在的资源不产生幽灵连线。
|
||||
3. 多资源任务依赖按资源类型分区后，各分区只形成一条聚合主线与 `O(S+T)` 条端点分支，不产生 `S×T` 连线或跨分区虚线。
|
||||
3. 多资源任务依赖按资源类型分区后只形成布局超边，以 `O(S+T)` 成员关系参与聚类，不产生 `S×T` 邻接、SVG 主线、端点分支或跨分区虚线。
|
||||
4. 资源引用环和无资源产物参与的任务环都可被有限遍历识别，界面不死循环。
|
||||
5. 搜索触发端点过滤；资源点击不改变上下游卡片或任何连线的视觉状态，资源卡指针移动不更新线段，点击与中央聚焦行为不回归。
|
||||
6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
|
||||
7. 4096 资源链式 fixture 继续验证拓扑、聚合复杂度和自动布局性能；拖动局部更新与真实 Chromium 拖动帧预算暂缓，不作为当前验收条件。最右侧自环与箭头仍需完整显示。
|
||||
8. Rust 图读取延迟时，dependency sidecar 在图进入 `ready / failed` 前没有读取或写入；首次布局直接使用 Rust 返回的最终 producer 与 dependency depth。Agent DB 有界读取截断时 producer、task flow 与 `cyclicTaskIds` 失败关闭，精确 manifest 引用及 Rust 返回的合法 `dependencyDepths` 继续到达布局层。重新打开包含深度 `0 / 1 / 2` 自动坐标的旧布局时不得降成全 `0` 或持久化扁平布局；手动位置逐项不变，自动位置按最终拓扑协调且相同结果不增加 revision。
|
||||
9. 依赖 SVG 作为装饰层不可聚焦并对辅助技术隐藏；画布通过关联的视觉隐藏文本逐条说明当前可见资源引用和任务流，搜索过滤或模式切换后文本与可见关系同步变化。
|
||||
9. 依赖 SVG 作为装饰层不可聚焦并对辅助技术隐藏；画布通过关联的视觉隐藏文本逐条说明当前可见的橙色精确引用，搜索过滤或模式切换后文本与可见关系同步变化。task-flow 不进入该关系说明。
|
||||
10. 精确引用使用橙色实线和可见箭头；dependency 自动卡片之间保留横向 `48px`、纵向 `40px` 走线区，相关簇的窄层按本簇最大层高度居中。不同横向层级且卡片间有空间时使用左右端口优先的横线，同列、同深度或横向空间不足时才使用上下端口纵向降级。同行 / 同列直接连线，需要转向时只使用正交线段与最大 `10px` 小圆角。同一卡片同侧的多条精确引用按稳定边 ID 与对端位置分配不同端口；自引用继续在卡片右侧外绕，箭头端点与卡片保留固定显示间隙。
|
||||
11. 每个分区 SVG 必须位于拥有相应资源卡的 `.game-resource-plane` 内，以同一逻辑坐标随原生滚动和 CSS scale 同步移动；滚动 / 缩放不得通过异步 DOM 屏幕测量重新绑定端点。分区 viewport 原生裁剪本区 SVG，不使用四区 viewport 并集裁剪；一端离屏时只显示对应方向、带同语义箭头的边界继续线，不保留指向已裁剪卡片的悬空主路径，两端离屏时隐藏。搜索隐藏精确引用任一端点时整边隐藏。
|
||||
|
||||
### 7.4 P1 正式项目版本阶段六验收
|
||||
|
||||
@@ -458,18 +478,28 @@ type ProjectAgentMudPointAttribution = {
|
||||
5. 任意现有 manifest 写入只能保留磁盘版本前缀并追加新记录；存储边界以跨进程专用锁串行覆盖旧状态读取、前缀校验、安装和回读，修改、删除、重排或并发旧快照覆盖已有版本时写入失败。
|
||||
6. 版本选择和高亮不写 manifest、布局 sidecar 或 project revision；dependency / type 两种布局都可显示绑定高亮，既有依赖关系 SVG 语义不变。
|
||||
|
||||
### 7.5 阶段七完整验收
|
||||
### 7.5 资源分区独立高度验收
|
||||
|
||||
1. 四个分区均可独立缩小、放大和恢复默认高度；任一分区变化时其它分区高度、资源卡尺寸和媒体比例不变。到达上下限时对应按钮同时具备正确的 disabled 视觉与辅助技术语义。
|
||||
2. 高度、倍率和分区内部滚动按 `projectId + dependency|type + document|version|art|audio` 隔离，外层资源画布位置按 `projectId + dependency|type` 隔离；切换模式、切换项目和打开 / 关闭资源详情后，分别恢复当前会话中的内外滚动位置，且键盘焦点不被无关重置。
|
||||
3. 最小高度可操作标题控制并完整容纳至少一排卡片；最大高度不超过中央资源画布当前可用高度。窗口变小后超界尺寸被永久夹取到新上限，后续放大窗口不自动恢复旧超界值。
|
||||
4. 分区放大只在正常文档流中下推后续分区，不使用浮层、绝对定位、负 margin 或 z-index 覆盖。分区内容超出时内部可滚动，外层画布仍可滚动访问其它分区，`1280×800` 无页面级溢出。
|
||||
5. dependency 线在高度、分区内部滚动、外层滚动和窗口 resize 后仍与可见卡片端点对齐；单端卡片被分区 viewport 裁掉时只保留边界继续线，不保留悬空主路径，两端都被裁掉时隐藏，线段不穿过标题栏。滚动与 resize 在每个分区内使用单一 `requestAnimationFrame` 合帧，每个分区 plane 最多创建一个 `ResizeObserver` 并在卸载时清理全部监听。
|
||||
6. 高度操作不调用 `update_local_project_resource_canvas_layout`，不改 manifest、不更新 sidecar revision；阶段一的图片 / 视频 / 音频 / 文档 / 版本卡片、单媒体播放与中央详情回归全部通过。
|
||||
|
||||
### 7.6 阶段七完整验收
|
||||
|
||||
1. 对照飞书需求、当前 PRD、技术方案、代码、测试与阶段提交复核阶段零至阶段六；美术编辑生成新资源继续按本 PRD 已确认的闭环条件暂缓，不作为遗漏或伪完成。
|
||||
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`。
|
||||
2. AppSurface 同时覆盖文档、图片、SVG、音频和视频资源卡与中央聚焦：图片、SVG 和视频主体只在卡内展示，中央详情展示元数据与依赖信息且不重复挂载 `img / video`；文档正文与按意图读取的原生音频 `controls` 位于详情元数据之后。读取策略失败时卡片或详情显示与错误类型一致的安全空态，右侧对话和底部 Agent 状态栏继续存在。
|
||||
3. 预览回归必须同时覆盖前端意图调度与原生物理读取：连续项目 / mode / Hook / 窗口切换和 `A → B → A` 下，全进程真实读取峰值始终 `<= 3`；旧 scope 的等待与在途任务可取消，新 scope 在旧任务最近取消点后取得 permit；取消任务不进入 base64 / Blob 阶段，不写当前状态，活动 request / scope registry 最终清零。seen request tombstone 最多保留 `8192` 项；非活动 cancelled scope tombstone 的预算为 `1024` 项，仍活动的取消 scope 可为防复活临时超出预算，但必须在对应 scope 结束后立即收敛。不得把这两类防重放 / 防复活 tombstone 误判为活动 registry 泄漏。文档、图片、安全 SVG、视频与音频原有登记、权限、路径、签名、尺寸、链接和漂移门禁必须全部回归。
|
||||
4. `1280×800` 必须在当前 HEAD 的真实、已认证应用 WebView / Chromium 中测量 `window`、documentElement 与 body 的 client / scroll 宽高，证明页面级横向和纵向均无溢出，并确认右侧对话、输入区和底部 Agent Dock 的边界全部位于视口内。浏览器开发页受真实登录门禁保护，不为验收绕过认证或伪造 Tauri；AppSurface 与资源布局 CSS 合同测试只作为内部结构回归，不能替代本条真实测量。验证记录必须包含当前 commit、视口、测量值、操作步骤和结果，确保可重复复核。
|
||||
5. 根目录全量 Vitest、前后端 typecheck / lint / build、Rust workspace test / check、SpacetimeDB schema、原生壳、内容 / 编码、生产运维与部署门禁全部通过后，阶段七才允许提交。
|
||||
6. 本地 `.env`、`.env.local`、密钥、缓存、日志和构建产物不进入阶段七提交；提交前再次执行编码检查和 `git diff --check`。
|
||||
|
||||
## 8. 非目标
|
||||
|
||||
- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、下一迭代版本创建入口、运行版本切换、版本回滚、运行模块扩展、测试切片、运行态消费版本、数值参数或泥点归因。正式版本记录已经成为 manifest 业务真相，但当前只读取、校验和展示已有记录。
|
||||
- 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
|
||||
- 本切片不持久化资源聚焦状态、分区高度、分区内部滚动、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
|
||||
- 不修改 SpacetimeDB schema。
|
||||
- 不开放普通用户 Agent.md/Skill。
|
||||
- 不自动确认 Agent 动作，不自动触发可能扣费的生成。
|
||||
|
||||
Reference in New Issue
Block a user