补齐运行画面点选的两条真机踩坑与阶段二真机复验状态

- pitfalls：新增「three 档句柄少构造器会整体失效」（Raycaster/Vector2/Vector3/Box3 缺任一即不进引擎档、芯片回落 canvas 且不报错，含四步排查顺序）与「预览桥脚本是编译期内嵌的：改完必须重启 AGC 客户端」
- 实施计划·阶段二进展：补真机复验环境已就绪（客户端自本分支编译启动、exe 内 6 处新代码标记已核实、CDP 可用）与「点选复验待执行」（客户端登录态过期停在登录页）

docs/project-memory/shared-memory/pitfalls.md

@@ -8,6 +8,20 @@
 - **原因**：句柄引用整个 `import * as THREE` 命名空间，打包器无法证明未使用的导出可以剪掉；预览桥实际只用 `Raycaster` / `Vector2` / `Vector3` / `Box3` 四个构造器。
 - **结论（现行口径）**：句柄用瘦身形态 `three: { Raycaster, Vector2, Vector3, Box3 }`；该字段只给预览桥用，玩法代码不要引用它。旧形态仍被兼容读取（两种形态都有用例锁定），但新代码与模板一律用瘦身形态。
 
+## 2026-10-05 运行画面点选 three 档的句柄少了构造器会整体失效
+
+- **现象**：three 项目句柄里 `Raycaster` / `Vector2` / `Vector3` / `Box3` 只缺一个，桥就**不进引擎档**：芯片回落 `@canvas`、控制台不报错——症状与「根本没发句柄」完全一样，容易误判成「点选没生效」。
+- **原因**：引擎档入口先认句柄形态、再逐个校验这四个构造器是否为 function，缺任一即按未命中退化（不降级、不猜）；射线需要 `Raycaster` + `Vector2`，对象矩形需要 `Box3` + `Vector3`，两组能力缺一方都点不出对象。
+- **排查顺序（现行口径）**：① 预览页有没有 `window.__GENARRATIVE_PREVIEW_GAME__`；② `engine` 是不是 `phaser` / `three`；③ 这四个构造器齐不齐（瘦身形态是 `three.Raycaster` 等，旧形态是 `THREE.Raycaster`）；④ `scene` / `camera` / `renderer`，three 侧还要 `renderer.domElement` 带 `getBoundingClientRect`。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js`（`threeInspectTarget`）、`agc-web-game-development` 的「运行画面点选契约」、`tests/runtimeInspectEngines.test.ts`（瘦身句柄命中、缺构造器退化两例）。
+
+## 2026-10-05 预览桥脚本是编译期内嵌的：改完必须重启 AGC 客户端
+
+- **现象**：改了桥脚本（运行画面点选 / 尺寸上报逻辑），Vite HMR 与刷新预览页都不换——预览页仍跑旧桥，新加的判定与兜底完全不生效。
+- **原因**：`apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js` 由 `preview.rs` 用 `include_str!` **编译期**编进客户端 exe，预览服务器 `/__genarrative/local-preview-fit.js` 返回的就是 exe 里那份常量，重读磁盘不会发生。
+- **结论（现行口径）**：改桥后必须重启 AGC 客户端才生效——先确认没有在跑的 AGC Vite（3080 等端口空闲）再 `npm run agc`；只刷新页面、只重启后端或只重装 npm 依赖都无效。核实内嵌版本：在 exe 二进制里搜新代码标记，或比对 `resources/preview/local-preview-fit.js` 的 sha256。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/preview.rs`（`PREVIEW_FIT_BRIDGE_SCRIPT`）、`apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js`、`genarrative-dev-stack-port-routing`（端口探测与 `npm run agc` 口径）。
+
 ## 2026-10-04 Phaser 4 `hitTestPointer` 的返回顺序不是叠放顺序
 
 - **现象**：运行画面点选 Phaser 4 画面时，按「数组第一个 / 最后一个」当最上层会点错对象——点的是上层精灵，引用却落到下层的素材上；对象越多越容易错。