From 629369eb0ca0dc7aea3cb26db7905b16f3d0a73e Mon Sep 17 00:00:00 2001 From: Suzumiya Date: Mon, 5 Oct 2026 15:31:44 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E9=BD=90=E8=BF=90=E8=A1=8C=E7=94=BB?= =?UTF-8?q?=E9=9D=A2=E7=82=B9=E9=80=89=E7=9A=84=E4=B8=A4=E6=9D=A1=E7=9C=9F?= =?UTF-8?q?=E6=9C=BA=E8=B8=A9=E5=9D=91=E4=B8=8E=E9=98=B6=E6=AE=B5=E4=BA=8C?= =?UTF-8?q?=E7=9C=9F=E6=9C=BA=E5=A4=8D=E9=AA=8C=E7=8A=B6=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - pitfalls：新增「three 档句柄少构造器会整体失效」（Raycaster/Vector2/Vector3/Box3 缺任一即不进引擎档、芯片回落 canvas 且不报错，含四步排查顺序）与「预览桥脚本是编译期内嵌的：改完必须重启 AGC 客户端」 - 实施计划·阶段二进展：补真机复验环境已就绪（客户端自本分支编译启动、exe 内 6 处新代码标记已核实、CDP 可用）与「点选复验待执行」（客户端登录态过期停在登录页） --- ...实施计划】AGC运行画面点选引擎适配-2026-10-04.md | 1 + docs/project-memory/shared-memory/pitfalls.md | 14 ++++++++++++++ 2 files changed, 15 insertions(+) diff --git a/docs/project-memory/plans/【实施计划】AGC运行画面点选引擎适配-2026-10-04.md b/docs/project-memory/plans/【实施计划】AGC运行画面点选引擎适配-2026-10-04.md index 84044dd88..a335ba215 100644 --- a/docs/project-memory/plans/【实施计划】AGC运行画面点选引擎适配-2026-10-04.md +++ b/docs/project-memory/plans/【实施计划】AGC运行画面点选引擎适配-2026-10-04.md @@ -74,3 +74,4 @@ - 冻结面不变：`preview.rs`、`resources/preview/local-preview-fit.js`（sha256 仍为 `6276ac48…917a`）、宿主匹配、脚手架与模板源均未改；未合并主线。 - 可见性补强 + 句柄瘦身：桥端 three 句柄改推荐瘦身形态 `three: { Raycaster, Vector2, Vector3, Box3 }`（旧 `THREE` 命名空间仍兼容读取，缺任一构造器按未命中退化），并补 label 兜底——three `object.name` → `geometry.type` → `object.type`、Phaser `texture.key` → `name` → `type`，命中对象但取不到素材身份时芯片不再一律是 `@canvas`；契约文本、`threejs-3d-starter` 与 `blank-3d-scene` 模板同步瘦身（整命名空间实测把 517,682 B 的构建撑到 730,831 B，+41%）。 - 该轮验证：`tests/runtimeInspectEngines.test.ts` 33 例（新增 6 例：瘦身句柄、旧命名空间兼容、name / geometry.type / object.type 兜底、缺构造器退化）；真实 Chromium + 真实 three 0.184 + 真实桥脚本实测 slim 句柄命中、`Crate` / `SphereGeometry` / `LegacyMesh` 三种芯片名与对象区域矩形；`agc:typecheck`、`check-doc-index`、`check:encoding`、`git diff --check` 通过。 +- 真机复验（待执行）：环境已就绪——客户端从本分支源码编译启动（`npm run agc` → `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`，Vite `127.0.0.1:3080`）、exe 内已核实内嵌新桥（6 处新代码标记：`handle.three || handle.THREE`、`inspectObjectLabel` 及其 4 个调用点）、CDP `http://127.0.0.1:9222` 可用（`Edg/154.0.4258.53`，page target 为 `陶泥儿 @ 127.0.0.1:3080`）。**点选复验待执行**：客户端登录态已过期（localStorage 里唯一 access token `exp=2026-10-01T08:24:51Z`），UI 停在登录页，需人工登录后才能打开 `gameagent-73ab2832` 进「运行」页挑选；未取得芯片文本 / 高亮矩形 / iframe 内句柄，不写"已完成"。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 85bada0df..ac48aeef9 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/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 画面时，按「数组第一个 / 最后一个」当最上层会点错对象——点的是上层精灵，引用却落到下层的素材上；对象越多越容易错。