From 48700083a37a084e042f30cbc2ce4c72da43c21a Mon Sep 17 00:00:00 2001 From: Suzumiya Date: Thu, 10 Sep 2026 14:26:57 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E9=BD=90=20AGC=20V3=20=E8=B5=84?= =?UTF-8?q?=E6=BA=90=E5=8F=A3=E5=BE=84=E4=B8=8E=E7=8E=AF=E5=A2=83=E7=BA=A6?= =?UTF-8?q?=E6=9D=9F=E7=9A=84=E6=9D=83=E5=A8=81=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - PRD §5.4 版本记录补充"只允许追加"的唯一例外：用户显式确认的连带删除，并写明放行集合按写入前 manifest 求值、被放行版本不得进入追加段 - decision-log 新增三条 2026-09-10 定稿：版本绑定恒等化并撤回运行期资源观察侧车；素材删除新口径（三分支 + 可选连带删除版本）；资源画布交互 1:1 复刻美术画布（取消资源详情面板与全屏编辑路由、复用共享组件以可选 prop opt-in、AGC 宿主自备 chrome 样式） - pitfalls 新增四条：新工作树的 cargo 必须在 npm ci 之后跑；残留 dev stack 会拖死 Rust 门禁；改共享美术画布组件时 AGC 门禁覆盖不到它自己的测试；AGC 侧没有 image-canvas-editor__* chrome 样式 --- ...AI游戏创作】项目开发工作台PRD-2026-07-20.md | 1 + .../shared-memory/decision-log.md | 37 +++++++++++++++++++ docs/project-memory/shared-memory/pitfalls.md | 28 ++++++++++++++ 3 files changed, 66 insertions(+) diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md index 98e9471fc..4b52f3eba 100644 --- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md +++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md @@ -407,6 +407,7 @@ type GameCreationAppManifest = { - `projectRevision` 与 `createdAt` 必须是 JavaScript 安全非负整数；子版本的修订必须严格大于父版本，创建时间不得早于父版本。 - 同一版本内 `slotId` 唯一；`resourceId` 固定保存 manifest asset ID，不保存资源卡显示名称、External Editor resource ID、路径或布局 ID。历史资源已不在当前 manifest 时仍保留原绑定，但界面不为其合成资源卡。 - Tauri manifest 存储边界在每次写入前校验完整版本图，并与磁盘中的旧 `versions` 前缀逐项比较；只允许追加新记录，已有记录被修改、删除或重排时写入失败且原文件保持不变。 +- （2026-09-10 补充）上述"只允许追加"有且只有一个例外：**用户在删除素材时显式确认"把相关游戏版本一并删除"**。该路径下，只有引用被删素材的那些版本允许消失，其余既有版本仍必须原样、原顺序保留，新增版本仍只能追加在末尾；放行集合按**写入前的 manifest** 求值，且被放行的版本不得出现在追加段里（防止"删除后重排"绕过校验）。除该路径外，任何版本删除、修改、重排仍然失败关闭。 - 版本卡标题由稳定追加序号生成，卡片与聚焦态展示 `versionId / projectRevision / createdReason / parentVersionId`；聚焦态额外展示直接子版本和全部 slot 绑定。点击版本卡只高亮当前投影中唯一匹配 `asset:` 的资源卡，不修改版本或资源。 ### 5.5 测试切片与数值参数（P2） diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index cbd5fd45e..0c6ec0d90 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -8224,3 +8224,40 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 边界：`agent-runner.lock` / `agent-runner.gui-owner.lock` 是 OS 独占句柄锁，进程退出即释放，残留文件不阻塞下次启动；不要把它们当成项目写锁的同类残留处理。 - 边界：锁文件里的 PID 若超出平台进程号空间（Unix `pid_t` 是有符号 32 位、Windows 是 32 位，均恒大于 0），它不可能属于任何活进程，按“持有者不存在”直接回收，不再落回 600 秒保守分支。 - 验证：`project_lock_recovery` 11 条与 `diagnostic_log` 7 条定向测试通过，真实二进制双实例复现“第二个实例写 `startup.runner.owner-lock.failed` 并弹出可见提示”。 + +## 2026-09-10 AGC 资源记录口径收敛：版本绑定恒等化，撤回运行期资源观察侧车 + +- 决策：游戏版本“使用了哪些资源”的权威记录就是 `.agent/manifest.json` 里该版本的 `resourceBindings`。`slotId` 恒为恒等映射 `asset:{assetId}`，`resourceId` 指向 manifest 资产 ID；契约字段不变，不做迁移脚本。 +- 决策：**撤回早期的运行期资源观察方案**。`slotId` 不承载“游戏里哪个位置用了它”的语义，因此不需要代码注入、Phaser wrapper、Vite 虚拟模块、脚手架哈希校验或 `.agent` 资源使用侧车。整条 `project/asset_usage.rs`（含其 16 条定向测试）按四不写整体删除，`game_iteration_resource_bindings` 退回纯恒等映射，`delete_manifest_asset_at` 不再做“真实运行槽位绑定”判定与 usage 引用清理。 +- 边界：不做未登记素材诊断，不做运行画面点选，不引入第二套资源真相；资源文件与登记路径都不变。 +- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/project/asset_usage.rs`、`src-tauri/src/tests/asset_usage.rs`、`project/manifest.rs`、`assets.rs`、`project.rs`、`tests/mod.rs`。 +- 验证：`game_iteration` / `manifest` / 删除相关定向 Rust 测试；`cargo check --all-targets`；AGC 前端全量套件不倒退。 + +## 2026-09-10 AGC 素材删除新口径：用户确认 + 可选连带删除引用它的游戏版本 + +- 决策：删除素材由用户确认，分三条路径，且必须在**同一次 manifest 写入**里原子完成： + 1. 未被任何版本绑定 → 直接删除； + 2. 被版本绑定过、用户**不勾选**连带删除 → 只删素材；引用它的版本原样保留悬空绑定，**界面不为其合成资源卡**，不做二次拦截，后果用户自负； + 3. 被版本绑定过、用户**勾选**“把相关游戏版本一并删除” → 素材与所有引用它的版本一起删除。 +- 决策：Tauri 删除命令新增“连带删除”开关；写入前先能读到“被哪些版本使用”，前端据此给出二次提示与勾选框（默认不勾）。 +- 决策：版本数组“只允许追加”的唯一例外就是路径 3。放开实现为显式传入**按写入前 manifest 求值的放行版本 ID 集合**，其余既有版本仍必须原样、原顺序保留，新增版本只能追加，且被放行版本不得出现在追加段里（防止“删除后重排”绕过）。不得全局关闭该校验。 +- 决策：更换某个版本使用的资源仍然只是“改 manifest 里该版本的绑定指向另一个已登记资源”，不动文件、不创建新版本、不引入 UI 流程。替换功能（候选素材 / 替换关系 / 替换队列 / Agent 审核 / 单点替换）整条取消，不实现。 +- 影响范围：`src-tauri/src/commands.rs`、`assets.rs`、`project/manifest.rs`、`main.rs`、`view/project-development/`（删除确认与连带删除勾选）。 +- 验证：Rust 定向覆盖三分支与版本写入边界的正反用例；前端覆盖勾选与不勾选两条路径；`cargo check --all-targets` 与 AGC 全量套件不倒退。 + +## 2026-09-10 AGC 资源画布交互 1:1 复刻美术画布 + +- 决策：资源画布的**结构**仍是资源卡组织板（默认“全部资源” + 功能画布 + 资源卡 + 筛选，不做图层编辑），但**交互**与网页端美术画布逐条对齐：点击资源卡 = 选中并在卡片旁浮出选中工具条；工具条动作（快速编辑 / 重绘 / 裁剪扩图 / 去背景 / 像素完美 / 切图集 / 提取 UI 素材 / 角色动画 / 下载）与美术画布同名同语义；“快速编辑”打开浮层面板，语义是**产出新素材，不原地改**（素材不可变）。 +- 决策：**明确取消**点击资源卡弹出“资源详情”面板与“编辑资源”全屏路由；分类与标签等编辑入口改由工具条承担。 +- 决策：能复用就复用 —— 直接复用 `src/components/image-editor/` 下的工具条、面板与生成 composer，不重写平行实现；共享组件的新需求以**可选 prop**（如 `unsupportedActions` / `extraActions`）opt-in 扩展，默认值必须保持网页端美术画布的原有行为。 +- 边界：`image-canvas-editor__*` 的 chrome 样式位于网页端全局表 `src/index.css`，AGC 侧没有这套规则。**不做**把数百条规则抽到 packages 的重构，**不允许** AGC import 网页端 `src/index.css`；口径是“复用组件 + AGC 宿主在 `apps/ai-game-creator-shell/src/styles.css` 里给浮出工具条补宿主 chrome 样式”。 +- 关联：快速编辑落地后，`scripts/check-config.mjs` 的 `allowedUncalledTauriCommands` 中 `normalize_local_project_raster_resource`（2026-09-09 的过渡项）解除条件达成，该 allowlist 条目随之删除。 +- 验证：共享组件自身测试（`npm run test -- src/components/image-editor`）与 AGC 全量套件同时通过；工具条“贴卡片浮出、层级正确、可点、窄屏不溢出”需人工浏览器核验。 + +## 2026-09-10 Agent 资源检索投影暴露功能分类与自定义标签 + +- 决策：`agc_list_registered_assets` 的投影（`agent/direct_tool_bridge.rs` 的 `bridge_registered_resource`）在 `mediaType` 之后固定新增 `category` 与 `tags`，位置稳定；工具描述同步补上“功能分类与自定义标签”。这闭环了 2026-09-05 资源分类决策里“本轮不做 `agc_list_registered_assets` 投影扩展”的遗留项。 +- 决策：投影**不重新按 kind 派生分类**。manifest 反序列化时已按 C2 口径解析（显式合法值原样保留，缺失/非法才按 kind 派生），在投影层再调 `game_creation_app_asset_category_for_kind(&asset.kind)` 会覆盖用户显式分类；`tags` 缺失即空数组。 +- 边界：不改 manifest 结构、不改对外 OpenAPI 或 SpacetimeDB schema。该投影同时被 `agc_create_or_derive_resource` 的完成回包复用，两条路径语义一致。 +- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs`、`agent/direct_tools_mcp.rs`。 +- 验证：定向 `cargo test -- bridge_registered_resource bridge_art_resource` 3 passed；新增 `bridge_registered_resource_projects_manifest_classification_verbatim` 锁定“显式分类与标签原样透出、不泄漏 prompt/model”；`cargo check --all-targets` 与 AGC 全量套件（1049 passed / 4 skipped / 0 failed）不倒退。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 86a25036e..20daf3451 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -5031,3 +5031,31 @@ - 处理：payload 只解析一次并连同字节一起快照；删除前重新核对字节，只有内容仍是判定时的内容才 unlink；文件已消失或被替换时返回 false 并重试 `create_new`，不报错。 - 补充：`project_write_lock_file_modified_seconds` 读不到 mtime 时不要返回 `0`——纪元 0 会被算成极大年龄，把保守判定反转成“立刻回收”，甚至把活持有者当 PID 复用抢走；要用 `Option` 区分“mtime 未知”和“mtime 等于纪元 0”。 - 关联：`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`。 + +## 新工作树的 cargo 必须在 npm ci 之后跑（2026-09-10） + +- 现象：新建 worktree 后直接跑 `cargo test --no-run` 立即失败：`内置 Codex CLI 缺失；请先在仓库根目录执行 npm ci（已检查：.../node_modules/@openai/codex-win32-x64/vendor/...）`。 +- 原因：`apps/ai-game-creator-shell/src-tauri/build.rs` 会把 `node_modules` 里内置的 Codex CLI 打进客户端产物，并在构建期硬校验这些路径。 +- 处理：新工作树先 `npm ci`，再跑任何 cargo 命令；两者不要并发启动，否则 cargo 会先于依赖就位而失败。 +- 关联：`apps/ai-game-creator-shell/src-tauri/build.rs`。 + +## 同一工作树里残留 dev stack 会拖死 Rust 门禁（2026-09-10） + +- 现象：`cargo test` 长时间不返回，或报 `failed to remove file ...genarrative-ai-game-creator-shell.exe` / `os error 5`；增量编译退化成像全量重编。 +- 原因：同一工作树里还挂着 `npm run agc`（`scripts/start-tauri-dev.mjs` → `tauri dev`）等进程。它的文件 watcher 会被 Rust 源码改动反复触发全量重编译，与 `cargo test` 抢同一个 `target` 锁，同时占住产出的 `.exe`。 +- 处理：跑 Rust 门禁前先确认该工作树没有 `start-tauri-dev` / `tauri dev` / vite / api-server / spacetimedb 进程，必要时按进程树结束；多工作树并行时各工作树有独立 `target`，但**不要在同一个工作树里重复起第二个 `cargo check`**。 +- 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`apps/ai-game-creator-shell/src-tauri/target`。 + +## 改共享美术画布组件时，AGC 的门禁覆盖不到它自己的测试（2026-09-10） + +- 现象：改动 `src/components/image-editor/**` 后只跑 `npm run test -- apps/ai-game-creator-shell/tests` 全绿，但网页端美术画布其实已经回归。 +- 原因：AGC 的测试入口只覆盖 `apps/ai-game-creator-shell/tests`；共享组件自己的测试是根目录 `src/components/image-editor/*.test.tsx`，属于根 `npm run test`（`vitest run`）的范畴。两者互不覆盖。 +- 处理：只要碰到 `src/components/image-editor/**`，门禁必须同时包含 `npm run test -- src/components/image-editor`。共享组件的新需求一律用**可选 prop** opt-in（例如 `unsupportedActions` / `extraActions`），默认值必须保持网页端美术画布的原有行为。 +- 关联：`src/components/image-editor/`、`apps/ai-game-creator-shell/tests/`。 + +## AGC 侧没有美术画布的 `image-canvas-editor__*` chrome 样式（2026-09-10） + +- 现象：在 AGC 客户端里复用美术画布组件后，浮出工具条没有定位、层级和外观，像是掉进文档流。 +- 原因：`image-canvas-editor__*` 的规则（约 918 条）全部在网页端全局样式表 `src/index.css` 里；AGC 只引入了 `@genarrative/image-canvas-react/styles.css`（178 行，只有 `genarrative-image-canvas__*` 视口样式）和 `apps/ai-game-creator-shell/src/styles.css`。 +- 处理：口径是“复用组件 + AGC 宿主给样式”——在 `apps/ai-game-creator-shell/src/styles.css` 里为实际用到的 class 补宿主 chrome 样式（浮出定位、层级、按钮外观）。**不要**让 AGC import 网页端 `src/index.css`（整站全局表会连带引入无关 reset 与主题），也不要在同一次改动里做数百条规则的抽取重构。 +- 关联：`src/index.css`、`packages/image-canvas-react/src/styles.css`、`apps/ai-game-creator-shell/src/styles.css`。