修复 AGC 画布四项验收问题：锚点让位标题栏、浮层不再撞画布边缘、拖动不再触发点击、图标规范参考口径对齐
- 生成任务锚点新增「资源总览」档：资源总览页仍贴画布顶边内缩 0.85rem，资源栏目画布页让开顶部钉住的整宽栏目标题栏（42px + 0.5rem），两档切换走 margin-top 过渡（减动效下关掉）。 - 生成浮层的顶边与可用高度改为按占位卡的真实屏幕位置算（卡下沿到安全底边），不再假设卡片贴在安全带上沿——占位落到下半屏时浮层底边不再越过画布下沿被切掉。 - 生成浮层新增水平收口：按「浮层左右各留 12px」把锚点收进画布可视范围，卡片靠边时浮层不再有一半落到画布之外；宽度口径与面板 CSS 同源（min(560px, 100% - 24px)）。 - 新增画布卡片手势的共享判据 resourceCanvasGestureExceededDragThreshold（阈值仍取 RESOURCE_CANVAS_DRAG_THRESHOLD）：资源卡与生成占位卡共用同一份「拖动还是点击」判断。 - 生成占位卡修掉拖动收尾误触点击：越过阈值才算拖动、登记一次性点击抑制（consumeDragClick）由宿主消费，「拖动中」样式也从越过阈值那一刻起才亮。 - 生成占位卡的删除按钮起手手势不再被当成「点卡片」：按起手点判定，松手落回卡片时不触发开合生成浮层。 - 图标规范面板的参考选择注释按现行判据改写（只有图集 icon-spritesheet 不接受用户参考），入口矩阵文档同步补「参考图（@ 引用）」口径并修掉「本地 IPC 没有参考图入参」的旧说法。 - 补齐回归用例：手势模型判据、占位卡拖动/点击与阈值、宿主级「拖完不弹浮层且普通点击仍开合」、浮层顶边与水平收口、锚点分档与跨文件标题栏高度守卫、逐条生成入口的 @ 与判据一致、图标规范面板的 @ 与提交带引用。 - 共享记忆 pitfalls.md 记录两条排障口径：卡类手势必须只有一份阈值与点击抑制判据；画布浮层几何只能按真实屏幕位置算、分页锚点必须让开钉死的标题栏。
This commit is contained in:
@@ -11,6 +11,23 @@ Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只
|
||||
- 处理：客户端门统一到 `PLATFORM_ART_SPRITESHEET_MAX_SLICES = 256`，判据与文案各只留一份（数字由常量插值），并在注释里点名三处同值权威（平台切分常量、工具 schema、公开契约）。
|
||||
- 复用判据：凡是「平台产出 → 客户端校验后落盘」的链路，客户端门只能表达**安全 / 预算**约束，不得比平台的产品上限更严；两边上限要引同一个常量或同一份文档，改一边时必须同时改另一边，并补一条「上限之内必须能落盘」的回归用例。
|
||||
|
||||
## 2026-09-21 画布卡片「拖一下就触发点击」：阈值与点击抑制必须是卡类手势的一份判据
|
||||
|
||||
- **现象**：拖动未生成的资源占位卡（背景音乐 / 音效等所有类型）松手后，卡片自己的点击语义被多执行一次——生成浮层被顺手弹开或收起。
|
||||
- **成因**：浏览器在 `pointerdown` 与 `pointerup` 落在同一节点上时**一定会补一次 `click`**，与中间移动了多少无关。生成占位卡那条手势把「收到过 pointermove」当成拖动信号（按下时浏览器就可能补一次零位移的 move），而且没有任何点击抑制；资源卡那条链路早就用 `RESOURCE_CANVAS_DRAG_THRESHOLD`（5px）+ `skipNextResourceCardClickRef` 处理过这件事，两条链路各写一套，于是只有占位卡漏。
|
||||
- **处理（现行口径）**：卡类手势只有一份判据 `resourceCanvasGestureExceededDragThreshold`（`features/resource-canvas/resourceCanvasCardGestureModel.ts`，阈值仍取 `RESOURCE_CANVAS_DRAG_THRESHOLD`）；拖动收尾那次 `click` 由手势层登记一次性抑制、宿主在「点卡片」的入口消费（占位卡是 `consumeDragClick`，资源卡是 `skipNextResourceCardClickRef`），抑制活过一个宏任务就清干净。「拖动中」样式也从越过阈值那一刻起才亮。
|
||||
- **相邻一档**：从删除按钮起手、松手落回卡片的手势，`click` 会被派给共同祖先（卡片）——判据要看**起手点**（`ResourceCanvasGenerationPlaceholderCardView` 的 `gestureOriginRef`），不能只看移动距离。
|
||||
- **易错点**：把「拖动样式」放在 `pointerdown` 上置位，等于承认「按下即拖动」，紧接着的点击又会被自己的抑制吃掉；阈值与抑制必须同时按同一判据走。
|
||||
|
||||
## 2026-09-21 画布浮层几何只能按卡片的真实屏幕位置算，分页锚点必须让开钉死的标题栏
|
||||
|
||||
- **现象一（浮层与画布边缘碰撞）**：生成浮层底边越过画布下沿被 `overflow: hidden` 切掉，卡片靠左右边时浮层还会有一半落到画布之外。
|
||||
- **成因**：可用高度只按「安全带高度 − 卡高」算，等于假设占位卡永远贴在安全带上沿；占位卡是追加在栏目内容最下方的，落到下半屏是常态。水平方向则完全没有收口——浮层 560px 宽、按卡片中心居中展开，卡片靠边必然越界。
|
||||
- **处理（现行口径）**：`resolveResourceCanvasGenerationPanelPlacement` 吃卡片的**屏幕顶边**，顶边与可用高度都由真实位置算（卡下面塞不下就改为盖住占位，且顶边收进安全带）；水平用 `clampResourceCanvasGenerationPanelAnchorX` 把锚点收进「浮层左右各留 12px」的区间。浮层宽度口径（`min(560px, calc(100% - 24px))`）在 CSS 与模型里各一份，有声明级守卫用例钉住同源。
|
||||
- **现象二（生成任务开关压在标题栏上）**：资源栏目画布页顶部钉着整宽的栏目标题栏（`.game-resource-book-scene-titlebar`，42px，右端是「返回资源总览」），右上角开关按总览页的坐标摆就会直接压在它上面。
|
||||
- **处理（现行口径）**：「生成任务」锚点按页分档（`canvas-overview` / `canvas` / `run` / `editor`）：画布页让开那条标题栏的高度再加一段间隙，总览页仍贴画布顶边内缩；两档之间的高度差走 `margin-top` 过渡（`prefers-reduced-motion` 下关掉）。让开多少与标题栏多高是**跨文件关系**，守卫用例读全局样式表里那条 `min-height` 断言「让开得比它高」。
|
||||
- **易错点**：给锚点写死 `top`，或只按某一页的 chrome 算一次坐标，工具条换行、页面切换或标题栏高度调整后都会重新压上去。
|
||||
|
||||
## Jenkins Windows 节点的 PATH 白名单决定 Godot 原生扩展能否构建
|
||||
|
||||
`Genarrative-Agc-Windows-Build` 在阶段里用 `AGC_WINDOWS_PATH` 整体替换 PATH、不继承节点机器的 PATH，所以 Godot C++ 引导需要的 CMake 与 Python 必须显式写进这份白名单，装在机器 PATH 上并不生效。2026-09-21 的 #97–#99 连续失败都停在 `Get-Command cmake.exe`（#93–#96 是更早的手写 C ABI 在 MSVC C 模式下的对齐问题）：节点只有 Visual Studio Build Tools（`C:\BuildTools`）自带的 CMake 3.31，缺 Python 3。修复后白名单包含 `C:\BuildTools\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`、`C:\Python312`、`C:\Python312\Scripts`，preflight 校验 CMake ≥3.25、Python 3 和 Visual Studio 17 2022 生成器；把 `cmake.exe` 单独复制到别的目录会丢掉 `share/cmake-*/Modules`，不能替代加入安装目录。新节点的 Python 用 `python-3.12.10-amd64.exe /quiet InstallAllUsers=1 TargetDir=C:\Python312 PrependPath=1 Include_launcher=1 InstallLauncherAllUsers=1` 静默安装即可，CMake 不必另装。
|
||||
@@ -96,6 +113,7 @@ Vite 默认监听应用根下的 Rust `src-tauri/target`，构建产物较多时
|
||||
- **易错点**：① 把弹层改成 `left: 0` 或往右挪也能让它可见，但那是改变展开方向，弹层会跑到触发钮右边（用户明确否决）；② 只放开最外层聊天列不够——surface 与 conversation 各自都会裁，三层必须同时放开；③ 只按宽度比大小会误判：280px 面板里控制排本身也超出（发送钮右侧溢出 22px，被窗口右缘吃掉），那不是本条的原因，别顺手去改控制排布局。
|
||||
- **验证**：`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts` 的 `keeps the landscape workbench edge-to-edge with internal chat scrolling` 钉住三条 override 声明在场（删掉任一条即红）。真机几何用 playwright-cli 打开一份只含真实 `styles.css` 与真实 composer DOM 的最小复现页实测（视口 1000×700、面板 280px）：弹层 rect 修复前后都是 `[-42, 108]`（位置未动），`elementFromPoint` 的命中区间从修复前的 `[2, 108]` 变成整块；档位文字在截图中完整可见。
|
||||
- **关联**：`apps/ai-game-creator-shell/src/styles.css`（`面板纵向布局（2026-07 Codex 风格改造）` 区块之后）、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
|
||||
|
||||
## 2026-09-17 资源卡「内容跟着边框动」与「模型缩略图被拉伸」是两条不同的几何陷阱
|
||||
|
||||
- **内容跟着状态边框位移**：卡片底态是 `border: 0`，悬停 / 选中才加 1px 边框；卡片是 `box-sizing: border-box`，而卡面（`.game-resource-card-visual`）与角标都是 `position: absolute; inset: 0`（包含块 = **padding box**）⇒ 状态一切换，内容盒四边各被吃掉 1px，卡面与角标整体位移并缩小 2px。修法：底态写成 `border: 1px solid transparent;`，状态只点亮 `border-color`；契约用例改成断言「资源卡规则里不得出现非 1px 的 `border` / `border-width`」。
|
||||
@@ -142,6 +160,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
|
||||
- **处理（现行口径）**：① 渲染 `ProjectDevelopmentView` 的桩统一登记 `list_local_project_asset_generations`（返回**数组**，空账本 `[]`；Rust 侧返回 `Vec<AssetGenerationTaskRecord>`，不是 `{ tasks: [] }`）；② `unexpectedCommands` 这类门禁**不要放宽**，只登记合法命令；③ 生产代码对 IPC 返回值做形状防御（`Array.isArray` 归一化），IPC 拒绝走既有提示路径，不产生 unhandled rejection（`resourceCanvasAssetGenerationTaskModel.ts` / `resourceCanvasAssetGenerationQueue.ts` / `index.tsx` 的恢复 effect）。
|
||||
- **易错点**：① 桩返回**非数组**时用例可能"看着绿"但同时报 unhandled rejection（实测：把 `[]` 误写成 `{ tasks: [] }` 就是 8 passed + 7 unhandled error），所以判"绿"必须同时看 unhandled 计数；② 新增挂载期 IPC 后要一次性 grep 所有 `ProjectDevelopmentView` 的桩，而不是等 CI 逐个炸；③ 提示条类断言（如「无读时提示」）会把「桩抛错」翻译成「多了一条提示」，排查时先看 unhandled，再看断言。
|
||||
- **关联**：`apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`、`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTaskModel.ts`。
|
||||
|
||||
## 2026-09-14 UI 编辑器返回后资源画布滚轮平移失效
|
||||
|
||||
- **现象**：资源管理打开 UI 编辑器再返回后，资源画布滚轮平移/缩放不再响应；返回前同一手势正常。
|
||||
@@ -149,6 +168,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
|
||||
- **处理**：将 `uiEditorRoute` 纳入 wheel effect 依赖，使进入/退出 UI 编辑器时先清理旧节点监听，再给返回后的新 manager 绑定同一处理器。
|
||||
- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts -t "restores resource canvas panning"`；回归用例覆盖打开栏目、wheel 平移、进入 UI 编辑器、返回并再次 wheel 平移。
|
||||
- **关联**：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
|
||||
|
||||
## 2026-09-14 AGC 就绪等待被 WMI 拖成分钟级：端口归属探测从 Get-NetTCPConnection 换成 netstat
|
||||
|
||||
- **现象**：`npm run agc` 从 `[ai-game-creator-shell] starting backend stack` 到 `backend ready` 要等约 80 秒，中途反复出现 `等待配套后端就绪时归属校验未通过（api-server-owner-mismatch: 未知进程）`；而这段时间后端其实已经好了（实测 api-server 12:39:01 已在 8084 监听、`/healthz` 已 200，12:40:19 才判 ready）。
|
||||
@@ -157,6 +177,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
|
||||
- **验证**：`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts` 新增两条——「探测脚本使用 netstat 且不再出现 Get-NetTCPConnection」「命令行按 PID 缓存后随请求下发、TTL 过期即失效」；定向 vitest 55 passed。本机实测：不含 SpacetimeDB 端口的探测 368 ms（原约 22 秒）、含 SpacetimeDB 端口 3.8 秒、命中缓存 368 ms；`npm run agc:serve` 的 `starting backend stack` → `backend ready` 由约 80 秒降到 16.7 秒（其中归属校验只占 4.4 秒，其余是 SpacetimeDB + api-server 的真实启动时间）。
|
||||
- **残留**：这台机器上首次 WMI 调用本身仍是秒级（曾见 18 秒），所以「新 SpacetimeDB PID 的第一次探测」仍可能多花几秒；命令行在进程存活期内不变，TTL 只用来限制 PID 复用造成的误判窗口。
|
||||
- **关联**：`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`（`readWindowsPortOwnerIdentities`）、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts`、`apps/ai-game-creator-shell/scripts/dev-windows-process.mjs`（退出清理仍走整份 `Win32_Process` 快照，自带 1 秒缓存，不在本次范围）。
|
||||
|
||||
## 2026-09-15 AGC JSON API 的响应体也必须有等待上限
|
||||
|
||||
- `fetchClientHttp` 的超时只覆盖请求到响应头返回；随后直接等待 `response.text()` 仍可能无限挂起。模型目录共用一个在途 Promise，响应体卡住会使后续刷新复用同一挂起请求、选择器持续忙碌。
|
||||
@@ -181,6 +202,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
|
||||
- **处理**：`runNativeShellGate` 收窄为 `(group, gate)`，label 回到各门禁执行体里以字面量打印；分组能力与 `--groups=` 语义不变。脚本内已注明"不要把 label 抽成变量"，外部壳的 `check-config` 是它的消费者。
|
||||
- **验证**：`node apps/mobile-shell/scripts/check-config.mjs` exit 0；`node apps/desktop-shell/scripts/check-config.mjs` 已越过第 740–777 行的根脚本断言段（本机随后卡在本机不存在的 Tauri 生成产物目录，与本次改动无关）；`--groups=contract`、vitest `scripts/project-ci-workflow.test.ts`、eslint 均通过。修复后 run 2097 六个 job 全绿。
|
||||
- **关联**：`scripts/check-native-shells.mjs`（`runNativeShellGate`）、`apps/desktop-shell/scripts/check-config.mjs`、`apps/mobile-shell/scripts/check-config.mjs`。
|
||||
|
||||
## 2026-09-14 AGC 资源画布不要恢复「无条件重派生」，否则新增一张素材就整张重排
|
||||
|
||||
- **现象**：用户生成一张新素材后，画布上既有卡片全部移位，刚摆好的位置失效。
|
||||
|
||||
Reference in New Issue
Block a user