Merge pull request 'AGC 运行画面点选：canvas 玩法上识别 Phaser 4 / three.js 的已登记素材（#612）' (#624) from feat/agc-runtime-picking-engines into master

Reviewed-on: http://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/624
2026-10-05 19:16:03 +08:00
parent fa42cdb139 df221f4eb9
commit 96859666ff
21 changed files with 3931 additions and 532 deletions
@@ -9,6 +9,8 @@ apps/ai-game-creator-shell/src/features/ui-editor/types/
 apps/ai-game-creator-shell/src/view/project-development/chat/generated/
 apps/ai-game-creator-shell/src/services/generated/
 apps/ai-game-creator-shell/src-tauri/resources/agc-skills/
+# 预览桥脚本：随包注入浏览器的资源，按字节搬运自 Rust 内联字符串，禁止 prettier 二次改写
+apps/ai-game-creator-shell/src-tauri/resources/preview/
 media
 *.log
 .preview.*
@@ -16,7 +16,7 @@ Use `agc_apply_patch` for targeted source edits with the official Add/Delete/Upd
 1. **Brief and scope** — Read the current planning output and project instructions. Record this turn's required game loop, actions, visuals, viewports and completion evidence. Use a bounded first-delivery scope; do not add new features or artwork during final review. For a new Web project, start from the prepared project scaffold. Do not repeat environment preflight unless new evidence requires it; `agc_environment_check` remains available for diagnosis. If blocked, report the toolchain/browser issue; do not download a second toolchain or search the whole machine. Read-only diagnosis and editor projects do not require this Web preflight.
 2. **Project and asset inventory** — Inspect the existing project structure and call `agc_list_registered_assets` (and `agc_list_project_files` when needed). Record which requested visuals already have usable registered identities and which are missing. Do not invent asset identities from filenames.
 3. **Visual production** — For missing or unsuitable visuals, call the reviewed `agc_tools` workflow: use `taonier_prepare_game_art` for a complete package, or `agc_generate_image` / `agc_edit_image` for focused assets. Read returned paths, identities, and warnings. A warning or partial package requires a narrower retry or independent assets before continuing.
-4. **Game implementation** — Implement the complete playable loop and wire the returned project-relative asset paths into the actual runtime. Every required character, object, background, effect, and UI visual must have a real source or an explicit brief-level decision to remain code-native. Generated assets that are unused, documentation-only, or replaced by emoji/CSS placeholders do not satisfy this stage.
+4. **Game implementation** — Implement the complete playable loop and wire the returned project-relative asset paths into the actual runtime. Every required character, object, background, effect, and UI visual must have a real source or an explicit brief-level decision to remain code-native. Generated assets that are unused, documentation-only, or replaced by emoji/CSS placeholders do not satisfy this stage. Web games (Phaser 4 / three.js) must also satisfy the 运行画面点选契约 in `agc-web-game-development`: publish the read-only engine handle, load Phaser images with `loader.imageLoadType='HTMLImageElement'`, annotate asset-rendered objects with the manifest identity, and keep media at a stable dist path aligned with `localPath`; without it 点选 only degrades to a region reference without an asset id.
 5. **Build and local verification** — Build and test as needed using the available command tools or `agc_run_validation`. Inspect actual command results and fix build or asset-loading failures before preview. Build/test return values and file existence are not contract requirements; visual/gameplay checks still require their existing trusted browser evidence.
 6. **Validation** — Use the approved browser tool and fixed scenarios. Call `agc_browser_playtest` with `mode=visual` for art/layout checks or `mode=gameplay` for fixed real-input/state/restart checks. Use `agc_run_validation` for existing focused Node/npm tests when needed. Fix blocking findings and rerun only the affected layer after an actual change. Do not rerun a whole playthrough for a color or documentation edit. A visual pass does not establish gameplay or complete-level coverage.
 7. **Delivery** — Once required evidence matches the current input, stop and report the observed validation scope. Do not start another side effect, art cycle, or polish cycle. A fixed scenario is not a full long-level playthrough. List new nonblocking ideas as follow-up work. Missing required evidence remains an explicit gap.
@@ -27,6 +27,24 @@ Make targeted source changes with `agc_apply_patch` using the official patch syn

 When implementing a new game loop or a broad gameplay revision, read `references/game-quality-checklist.md`.

+## 运行画面点选契约（运行态素材身份）
+
+客户端「点选素材」把运行画面里点中的对象落成一条 `runtime-region` 引用；命中已登记素材时引用带上该素材的稳定 id，显示名与 `@` 候选、资源卡「引用」一致。Phaser 4 与 three.js 项目都要满足下面四条，新生成的游戏才对点选可用。
+
+1. **发布只读引擎句柄**：引擎实例创建后发布一次，只服务点选与调试，不承载业务状态。句柄缺失或 `engine` 不是 `phaser` / `three` 时点选按第 4 条退化。
+   - Phaser：`window.__GENARRATIVE_PREVIEW_GAME__ = { engine: 'phaser', game };`
+   - three.js：`window.__GENARRATIVE_PREVIEW_GAME__ = { engine: 'three', three: { Raycaster, Vector2, Vector3, Box3 }, scene, camera, renderer };`
+     - **不要传整个 `three` 命名空间**：实测同一个 Vite 构建因此从 517,682 B 涨到 730,831 B（+213,149 B ≈ +41%），tree-shaking 失效。
+     - 这四个构造器是预览桥做射线与包围盒投影的最小集；该字段只给预览桥用，玩法代码不要引用它。
+     - 旧形态 `{ engine: 'three', THREE, scene, camera, renderer }` 仍被兼容读取，新代码一律用上面的瘦身形态。
+2. **Phaser 图片用 Image 标签装载**：游戏配置固定 `loader: { imageLoadType: 'HTMLImageElement' }`。默认的 XHR 装载把贴图地址换成会话内临时地址，点选读不回原始素材路径；这类项目只能靠第 3 条的显式标注。
+3. **给渲染对象标注素材身份**：用已登记素材渲染的对象要带上 manifest 的稳定身份，值只取 `agc_list_registered_assets` 返回的 `localAssetId` / `localPath`，不自行编造、不改写文件名；素材 id 不含空白与路径分隔符（`localAssetId` 由客户端生成）。
+   - Phaser：`sprite.setData('genarrativeResourceId', '<localAssetId>')`，或 `sprite.setData('genarrativeResourcePath', '<localPath>')`；两者都给时 id 优先。
+   - three.js：`mesh.userData.genarrativeResourceId` / `mesh.userData.genarrativeResourcePath`；GLB、分组或关卡导入的模型给 `traverse` 到的实际渲染 mesh 标注。
+4. **素材进 dist 走稳定路径**：素材放进游戏包 `public/`（脚手架 Vite 配置的默认 `publicDir`，原样拷贝、不加 hash），并保持与 `localPath` 相同的相对段（项目根 `assets/hero.png` → `game/public/assets/hero.png`，运行时用 `./assets/hero.png` 加载）。不要 `import` 图片或模型：构建产物名会带内容 hash，与 manifest 路径对不上，点选只剩文件名兜底，重名素材直接丢掉。
+
+点选只在用户按下时读取上述信息；不满足时**不报错、不伪造 id**，退化为不带素材的区域引用，引用仍能插入、能发送。这四条就是点选能力的验收面。
+
 # Notes
 * Do not edit UI Editor JSON directly. If the user exports `ui/generated-<digest>.js`, read that file instead; its embedded documentation explains how to use it.

@@ -11,3 +11,4 @@
 - 在构建后的实际页面检查桌面、移动和 resize：比较 canvas 与游戏父容器的中心，预期居中时水平/垂直误差不超过 1 CSS px，并检查画面没有溢出或意外滚动条。偏移先修游戏 CSS/scale 配置，不要靠调整预览位置掩盖布局问题。
 - HUD and overlays reserve space and do not cover essential interactive content.
 - Requested Taonier art is visibly integrated into the core experience when available.
+- 运行画面点选契约已满足：发布只读引擎句柄、Phaser 图片用 Image 标签装载、素材渲染对象带 manifest 身份标注，且素材在 dist 里保持与 `localPath` 对齐的稳定路径（见主 Skill「运行画面点选契约」）。
@@ -1,6 +1,6 @@
 {
  "schemaVersion": "agc-skill-pack.v1",
-  "version": "2026-08-26.40",
+  "version": "2026-08-26.42",
  "skills": [
    {
      "name": "agc-unity-editor",
@@ -59,7 +59,7 @@
        "agents/openai.yaml",
        "references/workflow-contract.md"
      ],
-      "sha256": "0ee5c36276f442da527e7f56e8b2e89632aa9bb63cabbdd689b15724357b6119"
+      "sha256": "d1431d2a66261466d3c8f76e6be7803f34f2f982573f538690030229a6469953"
    },
    {
      "name": "agc-project-structure",
@@ -121,7 +121,7 @@
        "agents/openai.yaml",
        "references/game-quality-checklist.md"
      ],
-      "sha256": "0e47c0e16d33f1cac66b959c7a574cc570674ab4a7555a8f732ea28842911397"
+      "sha256": "9959892b2b92a62aa5e8ca12a1938483a1bafc57c8b8e4520fed6547ed38d0de"
    },
    {
      "name": "agc-browser-playtest",
@@ -1254,7 +1254,7 @@ const DEFAULT_GAME_INDEX_HTML: &str = r#"<!doctype html>
 </html>
 "#;
 const DEFAULT_GAME_STYLE_CSS: &str = "body { margin: 0; display: grid; min-height: 100vh; place-items: center; background: #101827; color: #d9e7ff; font: 16px system-ui, sans-serif; }\nmain { width: min(720px, calc(100vw - 32px)); }\n";
-const DEFAULT_GAME_SCRIPT_JS: &str = "import Phaser from 'phaser';\nimport './style.css';\n\nclass PlaceholderScene extends Phaser.Scene {\n  create() { this.add.text(24, 24, '还没有生成游戏。回到聊天输入创意并确认生成后，这里会写入可试玩原型。'); }\n}\n\nnew Phaser.Game({ type: Phaser.AUTO, width: 720, height: 420, parent: 'game', scene: PlaceholderScene });\n";
+const DEFAULT_GAME_SCRIPT_JS: &str = "import Phaser from 'phaser';\nimport './style.css';\n\nclass PlaceholderScene extends Phaser.Scene {\n  create() { this.add.text(24, 24, '还没有生成游戏。回到聊天输入创意并确认生成后，这里会写入可试玩原型。'); }\n}\n\n// 用 Image 标签装载图片，让贴图保留原始素材地址，运行画面点选才能定位素材。\nconst game = new Phaser.Game({ type: Phaser.AUTO, width: 720, height: 420, parent: 'game', loader: { imageLoadType: 'HTMLImageElement' }, scene: PlaceholderScene });\n// 发布运行画面实例句柄，供预览桥点选定位游戏实例。\nwindow.__GENARRATIVE_PREVIEW_GAME__ = { engine: 'phaser', game };\n";

 const DEFAULT_EDITOR_BASE_URL: &str = "http://127.0.0.1:3000";
 const GAME_CREATOR_CONFIG_FILE_NAME: &str = "game-creator.config.json";
@@ -0,0 +1,173 @@
+import type { GameCreationAppAssetManifestEntry } from '../../../../../packages/shared/src/contracts/gameCreationApp';
+import { resourceDisplayName } from './resourceReferences';
+
+/**
+ * 运行画面点选结果 → manifest 现有素材 id 的唯一匹配口径。
+ *
+ * 桥（引擎档与 DOM 档）只给得出「显式素材 id」与「素材路径 / 贴图 URL」两种线索，两者都不可信：
+ * id 可能指向已删除 / 已改名的素材，路径可能是任意 URL pathname。宿主是唯一见过 manifest 的一方，
+ * 所以由这里把线索收敛成 manifest 里确实存在的 id —— **未知值一律丢弃**：Rust 侧遇到未知 id 会拒绝
+ * 整条 `runtime-region` 引用，宁可少给不可给错（见 `docs/【功能说明】AGC聊天素材引用-2026-09-08.md`
+ * 「运行画面素材点选（2026-10-04）」第 4 条）。
+ *
+ * 匹配优先级（结果按档位拼接后去重，档内按 manifest 顺序 / 输入顺序）：
+ *
+ * 1. 显式 `resourceIds` 中确实登记在 manifest 的（按输入顺序）；
+ * 2. `sourcePath` 与 `localPath` / `imageSequenceFrames[].imageSrc` 的**精确后缀匹配**：
+ *    按 `/`、`\` 分段逐段比较（大小写不敏感），`game/public/assets/hero.png` 命中
+ *    `assets/hero.png`，但段边界不同（`b/hero.png` vs `a/hero.png`）不算命中；
+ * 3. 文件名匹配（最后一段相等，大小写不敏感）——现有口径；重名素材命中多条时**全部返回**；
+ * 4. 序列帧 `imageSequenceFrames[].imageSrc` 与 `localPath` 同权参与第 2、3 档。
+ */
+export type RuntimeInspectMatchInput = {
+  assets: readonly GameCreationAppAssetManifestEntry[];
+  /** 桥给的素材路径 / 贴图 URL pathname（已过预览协议的净化，可能缺失）。 */
+  sourcePath?: string | null;
+  /** 桥给的显式素材 id（已过预览协议的净化，可能缺失 / 重复 / 指向未知素材）。 */
+  resourceIds?: readonly string[];
+};
+
+export type RuntimeInspectMatchResult = {
+  resourceIds: string[];
+};
+
+/** 路径分段：`/` 与 `\` 都算分隔符，丢弃空段（`a//b`、尾斜杠不会造出空段）。 */
+function pathSegments(value: string): string[] {
+  return value.split(/[\\/]+/u).filter((segment) => segment.length > 0);
+}
+
+/**
+ * 文件名去扩展名：与桥的派生逐字同一套规则（最后一个 `.` 之前为非空词干才去，
+ * `.env` 这类只有扩展名的词干为空）。用于「进来的 label 是不是文件名派生的」这条判据。
+ */
+function fileNameStem(fileName: string): string {
+  const dot = fileName.lastIndexOf('.');
+  if (dot < 0) {
+    return fileName;
+  }
+  return dot === 0 ? '' : fileName.slice(0, dot);
+}
+
+/** `sourcePath` 的文件名词干；没有文件名（空串 / 只有分隔符）时返回空串。 */
+function sourceFileNameStem(sourcePath: string | null | undefined): string {
+  if (!sourcePath) {
+    return '';
+  }
+  const segments = pathSegments(sourcePath);
+  const fileName = segments[segments.length - 1];
+  return fileName === undefined ? '' : fileNameStem(fileName);
+}
+
+/** `path` 的分段是否以 `suffix` 结尾（逐段大小写不敏感，段边界即后缀边界）。 */
+function endsWithSegments(path: string[], suffix: string[]): boolean {
+  if (suffix.length === 0 || suffix.length > path.length) {
+    return false;
+  }
+  const offset = path.length - suffix.length;
+  return suffix.every(
+    (segment, index) =>
+      path[offset + index]?.toLowerCase() === segment.toLowerCase(),
+  );
+}
+
+/** 一条素材参与路径匹配的全部候选：本地路径 + 序列帧地址（空值丢掉）。 */
+function assetCandidatePaths(asset: GameCreationAppAssetManifestEntry) {
+  const paths = asset.localPath ? [asset.localPath] : [];
+  for (const frame of asset.imageSequenceFrames ?? []) {
+    if (frame.imageSrc) {
+      paths.push(frame.imageSrc);
+    }
+  }
+  return paths;
+}
+
+export function matchRuntimeInspectResources(
+  input: RuntimeInspectMatchInput,
+): RuntimeInspectMatchResult {
+  const knownIds = new Set(input.assets.map((asset) => asset.id));
+  const matched: string[] = [];
+
+  // 档 1：显式 id 里登记在 manifest 的那些，按输入顺序。
+  for (const resourceId of input.resourceIds ?? []) {
+    if (knownIds.has(resourceId)) {
+      matched.push(resourceId);
+    }
+  }
+
+  const sourceSegments = input.sourcePath ? pathSegments(input.sourcePath) : [];
+  const sourceFileName = sourceSegments[sourceSegments.length - 1];
+  if (sourceFileName !== undefined) {
+    // 一趟扫完两档：后缀命中优先于同文件名命中，各自保持 manifest 顺序。
+    const suffixMatches: string[] = [];
+    const fileNameMatches: string[] = [];
+    for (const asset of input.assets) {
+      let tier: 0 | 2 | 3 = 0;
+      for (const path of assetCandidatePaths(asset)) {
+        const segments = pathSegments(path);
+        // 档 2：精确后缀匹配，段边界即后缀边界（`b/hero.png` 不会命中 `a/hero.png`）。
+        if (endsWithSegments(segments, sourceSegments)) {
+          tier = 2;
+          break;
+        }
+        // 档 3：文件名匹配（现有口径）；重名素材全部返回，不静默只取一条。
+        if (
+          segments[segments.length - 1]?.toLowerCase() ===
+          sourceFileName.toLowerCase()
+        ) {
+          tier = 3;
+        }
+      }
+      if (tier === 2) {
+        suffixMatches.push(asset.id);
+      } else if (tier === 3) {
+        fileNameMatches.push(asset.id);
+      }
+    }
+    matched.push(...suffixMatches, ...fileNameMatches);
+  }
+
+  return { resourceIds: [...new Set(matched)] };
+}
+
+/**
+ * 点选载荷的 `label`：**唯一确定素材**时用 manifest 的显示名统一它，否则原样保留桥给的 label。
+ *
+ * 「这次点选是不是引擎档」由桥的硬编码标记回答：`engineInspectSelection` 把 `elementTag` 固定成
+ * `'canvas'`，DOM 档给的是元素自己的标签（桥源码见 `src-tauri/resources/preview/local-preview-fit.js`）。
+ *
+ * 引擎档的 label 可能是文件名词干（显式 `genarrativeResourcePath` / 贴图 URL pathname 派生），
+ * 也可能退化成 Phaser 的 `texture.key` 或常量 `'canvas'`——后者不是文件名，没法与
+ * `resourceDisplayName` 逐字比对；但「已唯一命中 manifest 素材」本身就是定名依据，所以引擎档不看
+ * label 形状，直接归一化（主规范第 2 条：同一素材的显示名与 `@` 候选 / 资源卡「引用」完全一致）。
+ * 实测依据：Phaser 4 的 loader 走 XHR + `blob:` URL，贴图来源读不回原始地址，label 必然落到
+ * `texture.key`（见本轮 Chromium 冒烟记录）。
+ *
+ * DOM 档的 label 是元素文本或标签（`text || tag`）：只有它恰好就是 `sourcePath` 的文件名词干时
+ * 才做同一次归一化（避免 `Hero.PNG` 这类大小写差异），其余一律原样保留——DOM 点选行为逐字不变
+ * （主规范第 1 条）。
+ */
+export function resolveRuntimeInspectLabel(input: {
+  assets: readonly GameCreationAppAssetManifestEntry[];
+  resourceIds: readonly string[];
+  sourcePath?: string | null;
+  label: string;
+  /** 选中元素的标签：引擎档固定 `'canvas'`，DOM 档是元素标签。 */
+  elementTag?: string | null;
+}): string {
+  if (input.resourceIds.length !== 1) {
+    return input.label;
+  }
+  const asset = input.assets.find(
+    (candidate) => candidate.id === input.resourceIds[0],
+  );
+  if (!asset) {
+    return input.label;
+  }
+  const stem = sourceFileNameStem(input.sourcePath);
+  const labelIsFileNameStem =
+    Boolean(stem) && input.label.trim().toLowerCase() === stem.toLowerCase();
+  if (input.elementTag !== 'canvas' && !labelIsFileNameStem) {
+    return input.label;
+  }
+  return resourceDisplayName(asset);
+}
@@ -144,6 +144,10 @@ import {
  resourceLabelResolver,
  resourceReferenceCategoryLabel,
 } from '../../features/project-workspace/resourceReferences';
+import {
+  matchRuntimeInspectResources,
+  resolveRuntimeInspectLabel,
+} from '../../features/project-workspace/runtimeInspectResourceMatch';
 import { useElementFullscreen } from '../../features/project-workspace/useElementFullscreen';
 import { GameRunVersionPicker } from '../../features/resource-canvas/GameRunVersionPicker';
 import {
@@ -2860,28 +2864,27 @@ export default function ProjectDevelopmentView({
  }, [embeddedPreviewUrl, mode, onPlay, projectPath, runAvailable]);
  const handleRuntimeInspectSelection = useCallback(
    (selection: LocalGamePreviewInspectSelection) => {
-      const sourceName = selection.sourcePath?.split('/').pop()?.toLowerCase();
-      const matchedResourceIds = sourceName
-        ? manifest.assets
-            .filter(
-              (asset) =>
-                asset.localPath.split(/[\\/]/u).pop()?.toLowerCase() ===
-                sourceName,
-            )
-            .map((asset) => asset.id)
-        : [];
+      const { resourceIds } = matchRuntimeInspectResources({
+        assets: manifest.assets,
+        sourcePath: selection.sourcePath,
+        resourceIds: selection.resourceIds,
+      });
      dispatchResourceReferenceInsert({
        type: 'runtime-region',
-        label: selection.label,
+        label: resolveRuntimeInspectLabel({
+          assets: manifest.assets,
+          resourceIds,
+          sourcePath: selection.sourcePath,
+          label: selection.label,
+          elementTag: selection.elementTag,
+        }),
        runId: preview?.port ? `preview-${preview.port}` : undefined,
        elementTag: selection.elementTag,
        elementRole: selection.elementRole,
        text: selection.text,
        width: selection.width,
        height: selection.height,
-        resourceIds: [
-          ...new Set([...selection.resourceIds, ...matchedResourceIds]),
-        ],
+        resourceIds,
        source: 'runtime-picker',
      });
      setRuntimeInspectMode(false);
@@ -18,6 +18,21 @@ renderer.setPixelRatio(window.devicePixelRatio);
 renderer.setSize(window.innerWidth, window.innerHeight);
 container.append(renderer.domElement);

+// 发布运行画面实例句柄，供预览桥点选定位场景、相机与渲染器。
+// three 字段只放预览桥要用的构造器：整命名空间会破坏 tree-shaking（实测包体 +41%）。
+window.__GENARRATIVE_PREVIEW_GAME__ = {
+  engine: 'three',
+  three: {
+    Raycaster: THREE.Raycaster,
+    Vector2: THREE.Vector2,
+    Vector3: THREE.Vector3,
+    Box3: THREE.Box3,
+  },
+  scene,
+  camera,
+  renderer,
+};
+
 const light = new THREE.DirectionalLight(0xffffff, 1.2);
 light.position.set(4, 8, 6);
 scene.add(light, new THREE.AmbientLight(0x8899ff, 0.5));
@@ -12,10 +12,15 @@ class PlaceholderScene extends Phaser.Scene {
  }
 }

-new Phaser.Game({
+// 用 Image 标签装载图片，让贴图保留原始素材地址，运行画面点选才能定位素材。
+const game = new Phaser.Game({
  type: Phaser.AUTO,
  width: 720,
  height: 420,
  parent: 'game',
+  loader: { imageLoadType: 'HTMLImageElement' },
  scene: PlaceholderScene,
 });
+
+// 发布运行画面实例句柄，供预览桥点选定位游戏实例。
+window.__GENARRATIVE_PREVIEW_GAME__ = { engine: 'phaser', game };
@@ -18,6 +18,21 @@ renderer.setPixelRatio(window.devicePixelRatio);
 renderer.setSize(window.innerWidth, window.innerHeight);
 container.append(renderer.domElement);

+// 发布运行画面实例句柄，供预览桥点选定位场景、相机与渲染器。
+// three 字段只放预览桥要用的构造器：整命名空间会破坏 tree-shaking（实测包体 +41%）。
+window.__GENARRATIVE_PREVIEW_GAME__ = {
+  engine: 'three',
+  three: {
+    Raycaster: THREE.Raycaster,
+    Vector2: THREE.Vector2,
+    Vector3: THREE.Vector3,
+    Box3: THREE.Box3,
+  },
+  scene,
+  camera,
+  renderer,
+};
+
 const light = new THREE.DirectionalLight(0xffffff, 1.4);
 light.position.set(3, 5, 4);
 scene.add(light, new THREE.AmbientLight(0x8899ff, 0.6));
@@ -0,0 +1,278 @@
+import { describe, expect, it } from 'vitest';
+
+import type { GameCreationAppAssetManifestEntry } from '../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  matchRuntimeInspectResources,
+  resolveRuntimeInspectLabel,
+} from '../src/features/project-workspace/runtimeInspectResourceMatch';
+
+function asset(
+  id: string,
+  localPath: string,
+  frameSrcs: string[] = [],
+): GameCreationAppAssetManifestEntry {
+  return {
+    id,
+    kind: 'character',
+    mediaType: 'image/png',
+    localPath,
+    source: { kind: 'uploaded' },
+    imageSequenceFrames: frameSrcs.map((imageSrc) => ({
+      imageSrc,
+      width: 32,
+      height: 32,
+    })),
+  };
+}
+
+const hero = asset('hero', 'assets/hero.png');
+const enemy = asset('enemy', 'assets/enemy.png');
+const manifest = [hero, enemy];
+
+describe('运行画面点选 → manifest 素材 id', () => {
+  it('显式 id 优先：登记在 manifest 的按输入顺序保留，未知 id 一律丢弃', () => {
+    expect(
+      matchRuntimeInspectResources({
+        assets: manifest,
+        resourceIds: ['ghost', 'hero'],
+        sourcePath: '/assets/enemy.png',
+      }),
+    ).toEqual({ resourceIds: ['hero', 'enemy'] });
+    // 全是未知 id：宁可给空，也不能把值透传给 Rust（未知 id 会让整条引用被拒）。
+    expect(
+      matchRuntimeInspectResources({
+        assets: manifest,
+        resourceIds: ['ghost'],
+      }),
+    ).toEqual({ resourceIds: [] });
+  });
+
+  it('精确后缀匹配：深层路径以段边界命中短 localPath', () => {
+    expect(
+      matchRuntimeInspectResources({
+        assets: [asset('hero', 'game/public/assets/hero.png')],
+        sourcePath: '/assets/hero.png',
+      }),
+    ).toEqual({ resourceIds: ['hero'] });
+    // `/` 与 `\` 都是分隔符，两侧混用同样按段比较（大小写不敏感）。
+    expect(
+      matchRuntimeInspectResources({
+        assets: [asset('hero', 'game\\public\\assets\\hero.png')],
+        sourcePath: '/ASSETS/HERO.PNG',
+      }),
+    ).toEqual({ resourceIds: ['hero'] });
+  });
+
+  it('段边界不误配：后缀档先于文件名档，`minigame/hero.png` 不当作 `game/hero.png` 的后缀', () => {
+    expect(
+      matchRuntimeInspectResources({
+        assets: [
+          asset('mini', 'minigame/hero.png'),
+          asset('game', 'game/hero.png'),
+        ],
+        sourcePath: '/game/hero.png',
+      }),
+    ).toEqual({ resourceIds: ['game', 'mini'] });
+    expect(
+      matchRuntimeInspectResources({
+        assets: [asset('a', 'a/hero.png'), asset('ab', 'ab/hero.png')],
+        sourcePath: '/ab/hero.png',
+      }),
+    ).toEqual({ resourceIds: ['ab', 'a'] });
+  });
+
+  it('重名素材命中多条时全部返回，不静默只取一条', () => {
+    expect(
+      matchRuntimeInspectResources({
+        assets: [
+          asset('first', 'art/a/hero.png'),
+          asset('second', 'art/b/hero.png'),
+        ],
+        sourcePath: '/other/hero.png',
+      }),
+    ).toEqual({ resourceIds: ['first', 'second'] });
+  });
+
+  it('序列帧 `imageSrc` 与 `localPath` 同权参与后缀与文件名匹配', () => {
+    const walk = asset('walk', 'assets/hero.png', ['assets/walk/frame_01.png']);
+    expect(
+      matchRuntimeInspectResources({
+        assets: [walk],
+        sourcePath: '/game/assets/walk/frame_01.png',
+      }),
+    ).toEqual({ resourceIds: ['walk'] });
+    expect(
+      matchRuntimeInspectResources({
+        assets: [walk],
+        sourcePath: '/elsewhere/frame_01.png',
+      }),
+    ).toEqual({ resourceIds: ['walk'] });
+    // 序列帧不命中时不能靠 localPath 蹭上：这里文件名与帧地址都不同。
+    expect(
+      matchRuntimeInspectResources({
+        assets: [walk],
+        sourcePath: '/assets/other.png',
+      }),
+    ).toEqual({ resourceIds: [] });
+  });
+
+  it('无匹配时返回空数组', () => {
+    expect(
+      matchRuntimeInspectResources({
+        assets: manifest,
+        sourcePath: '/assets/missing.png',
+      }),
+    ).toEqual({ resourceIds: [] });
+    expect(matchRuntimeInspectResources({ assets: manifest })).toEqual({
+      resourceIds: [],
+    });
+    expect(
+      matchRuntimeInspectResources({
+        assets: [],
+        sourcePath: '/assets/hero.png',
+      }),
+    ).toEqual({ resourceIds: [] });
+  });
+
+  it('显式 id 与路径命中撞上同一素材时去重', () => {
+    expect(
+      matchRuntimeInspectResources({
+        assets: manifest,
+        resourceIds: ['hero', 'hero'],
+        sourcePath: '/assets/hero.png',
+      }),
+    ).toEqual({ resourceIds: ['hero'] });
+  });
+});
+
+describe('运行画面点选载荷的 label', () => {
+  // 引擎档证据：Phaser 4 loader 走 XHR + blob URL，贴图 URL 读不回来，桥的 label 会落到
+  // `texture.key`（`decoy`）或常量 `'canvas'`。唯一命中素材时这两类都要按 manifest 显示名定名。
+  it('引擎档（elementTag=canvas）唯一命中素材时，无论 label 是不是文件名派生，都归一化成资源显示名', () => {
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['enemy'],
+        sourcePath: '/assets/decoy.png',
+        label: 'decoy',
+        elementTag: 'canvas',
+      }),
+    ).toBe('enemy');
+    // 贴图 URL 读不回来（sourcePath 缺失）时同样定名。
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['enemy'],
+        label: 'decoy',
+        elementTag: 'canvas',
+      }),
+    ).toBe('enemy');
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['hero'],
+        label: 'canvas',
+        elementTag: 'canvas',
+      }),
+    ).toBe('hero');
+  });
+
+  it('label 是文件名派生的词干时归一化（含空白折 `-`、大小写取 manifest 的 localPath）', () => {
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['hero'],
+        sourcePath: '/assets/hero.png',
+        label: 'hero',
+        elementTag: 'canvas',
+      }),
+    ).toBe('hero');
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: [asset('hero-v2', 'assets/hero v2.png')],
+        resourceIds: ['hero-v2'],
+        sourcePath: '/assets/hero v2.png',
+        label: 'hero v2',
+        elementTag: 'canvas',
+      }),
+    ).toBe('hero-v2');
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['hero'],
+        sourcePath: '/assets/Hero.PNG',
+        label: 'Hero',
+        elementTag: 'canvas',
+      }),
+    ).toBe('hero');
+    // 非 canvas 的选点（DOM 档）恰好在媒体 `src` 上、且 label 逐字等于文件名时，同样归一化。
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['hero'],
+        sourcePath: '/assets/Hero.PNG',
+        label: 'Hero',
+        elementTag: 'img',
+      }),
+    ).toBe('hero');
+  });
+
+  it('DOM 档的元素文本 / 标签不是文件名派生时原样保留（DOM 点选行为逐字不变）', () => {
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['hero'],
+        sourcePath: '/assets/hero.png',
+        label: '开始按钮',
+        elementTag: 'button',
+      }),
+    ).toBe('开始按钮');
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['hero'],
+        sourcePath: '/assets/hero.png',
+        label: 'img',
+        elementTag: 'img',
+      }),
+    ).toBe('img');
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['hero'],
+        label: 'HUD 区域',
+        elementTag: 'div',
+      }),
+    ).toBe('HUD 区域');
+  });
+
+  it('匹配不到唯一素材时不改 label', () => {
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: [asset('first', 'a/hero.png'), asset('second', 'b/hero.png')],
+        resourceIds: ['first', 'second'],
+        sourcePath: '/other/hero.png',
+        label: 'Hero',
+        elementTag: 'canvas',
+      }),
+    ).toBe('Hero');
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: [],
+        sourcePath: '/assets/hero.png',
+        label: 'hero',
+        elementTag: 'canvas',
+      }),
+    ).toBe('hero');
+    expect(
+      resolveRuntimeInspectLabel({
+        assets: manifest,
+        resourceIds: ['ghost'],
+        sourcePath: '/assets/hero.png',
+        label: 'hero',
+        elementTag: 'canvas',
+      }),
+    ).toBe('hero');
+  });
+});
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD

-更新时间：`2026-09-21`（2026-09-20 音频生成并入图片类那份后台任务账本、派生/修改类任务并入同一「生成任务」侧栏，2026-09-21 卡片浮层改为「提交即关」、**「生成任务」侧栏从画布左侧贴边改为画布右上角锚点（开关常驻）**、**资源卡可拖到对话栏批量 @ 引用**、**替换面板改为非模态浮层并支持在画布上点选目标**（验收现场两条修正：任务锚点改挂画布那一格、展开后开关让位），见 §3.10 / §5.3 / §7.8 / §7.9 与 [`【功能说明】AGC聊天素材引用`](../【功能说明】AGC聊天素材引用-2026-09-08.md)；2026-09-14 图片类生成后台化：入口 IPC 为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变；2026-09-21 Godot 工作区发现放宽：一层多命中按目录名排序取第一个，`project.godot` 允许是链接/reparse point/硬链接，见 §3.8）
+更新时间：`2026-10-04`（2026-10-04 运行视窗「点选素材」补上 Phaser 4 / three.js 画面上的已登记素材识别与退化口径，见 §3.4；2026-09-20 音频生成并入图片类那份后台任务账本、派生/修改类任务并入同一「生成任务」侧栏，2026-09-21 卡片浮层改为「提交即关」、**「生成任务」侧栏从画布左侧贴边改为画布右上角锚点（开关常驻）**、**资源卡可拖到对话栏批量 @ 引用**、**替换面板改为非模态浮层并支持在画布上点选目标**（验收现场两条修正：任务锚点改挂画布那一格、展开后开关让位），见 §3.10 / §5.3 / §7.8 / §7.9 与 [`【功能说明】AGC聊天素材引用`](../【功能说明】AGC聊天素材引用-2026-09-08.md)；2026-09-14 图片类生成后台化：入口 IPC 为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变；2026-09-21 Godot 工作区发现放宽：一层多命中按目录名排序取第一个，`project.godot` 允许是链接/reparse point/硬链接，见 §3.8）

 ## 1. 产品定位

@@ -76,6 +76,7 @@
 - 运行视窗必须占满中央工作区为游戏保留的可用区域。loopback 预览页通过客户端本地 preview server 注入的只读尺寸桥上报文档实际宽高；宿主只接受当前 iframe、当前 loopback origin 的固定版本消息，并将完整游戏文档等比缩放、居中放入视窗。iframe 首次适配后发生的真实内容增高或缩短仍必须被接受；仅浏览上下文宽高回灌或内容宽高未变化时保持当前状态，不触发重复渲染。
 - 窗口或中央区域尺寸变化后必须重新测量和适配；内容已经放得下时保持 `1:1`，不得无故放大。游戏文档宽高超过视窗时缩小整体画面，不显示 iframe 横向或纵向滚动条，也不得用单纯裁切替代完整展示。尺寸桥以根布局 `ResizeObserver` 为主，并在页面可见时每 `500ms` 至多探测 `512` 个元素作为绝对定位溢出的低频兜底；探测截断时不得用部分样本下调尺寸，viewport 耦合的 `100vh / 100% / bottom / right` 布局也不得形成自反馈。相同测量结果去重，不监听整页属性、文本或子节点突变；桥不读取项目正文、不修改 manifest、游戏文件或运行业务状态。桥脚本只能注入到真实 HTML 标签上下文，不能把脚本、样式、模板或注释中的 `</body>` / `</html>` 文本误判为结束标签；省略结束标签的 UTF-8 HTML 仍需安全注入。
 - 运行视窗右下角提供“全屏预览”：只把游戏画面那一格送进全屏，顶部页签、右侧对话和底部信息栏不跟着放大；再次点击该入口、按 `Esc` 或由宿主退出全屏都回到原布局。宿主没有 Fullscreen API 时整枚入口不渲染，不留点了没反应的按钮。
+- 运行视窗提供“点选素材”：把画面上点中的内容落成一条 `runtime-region` 引用插入对话，只影响这一次引用——不改资源选中、不改信息栏判据、不写 manifest 或版本、不重载预览，也不代表“该素材正在被这个位置使用”。预览页是 Phaser 4 或 three.js 玩法时，点中由**已登记素材**渲染的精灵、图集帧、贴图网格或模型，引用必须带该素材的稳定 id，显示名与其它引用入口一致；玩法没有发布引擎句柄、对象既没有标注也取不到贴图地址、或画面是程序化绘制时，退化为不带素材的区域引用——不报错、不伪造 id、引用照常能插入能发送；点选不得改变预览的内容尺寸与适配缩放，命中区域只取画布内可见部分。
 - 运行视窗下方的信息栏只在**有真实内容**时存在（当前判据是**资源选中态**：在资源画布或浮层资源面板里选中一张资源后切到运行页签仍保留，信息栏渲染它的只读字段；运行画面上的“点选素材”只往对话插入引用，不改选中）：没有内容时整栏不渲染，有内容时自动展开并可手动收起到只剩一行开合按钮；不显示示例字段、默认数值、未载入控件或功能说明。暂时没有数据源的区域（「数值微调」的登记表）不渲染区域标题与卡片，等编辑态登记表接进来后与内容一起出现。Agent 对话标题栏不显示头像图标，“与陶泥儿的对话”及副标题按标题栏左侧对齐，钱包和审批入口继续位于右侧。

 - 数值修改立即写入当前项目的编辑态配置。
@@ -0,0 +1,77 @@
+# 【实施计划】AGC 运行画面点选识别 Phaser 4 与 three.js 画面上的已登记素材
+
+| 字段      | 值                                                                      |
+| --------- | ----------------------------------------------------------------------- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC运行画面点选引擎适配-2026-10-04.md` |
+| Status    | in-progress                                                              |
+| Owner     | omp agent（issue #612）                                                   |
+
+## 修改边界
+
+允许修改：
+
+- `apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js`（新增）：现有预览桥脚本（尺寸上报 + DOM 点选）整体迁入，并新增 canvas 分支与两个引擎适配器。
+- `apps/ai-game-creator-shell/src-tauri/src/preview.rs`：`PREVIEW_FIT_BRIDGE_SCRIPT` 改为 `include_str!` 引用上面的文件；注入、去重扫描、`/__genarrative/local-preview-fit.js` 路由与响应逻辑不变。
+- `apps/ai-game-creator-shell/src/features/project-workspace/runtimeInspectResourceMatch.ts`（新增）：把宿主侧「点选结果 → manifest 素材 id」的匹配抽成纯函数。
+- `apps/ai-game-creator-shell/src/view/project-development/index.tsx`：`handleRuntimeInspectSelection` 改为调用该纯函数，派发载荷结构不变。
+- `apps/ai-game-creator-shell/tests/runtimeInspectEngines.test.ts`、`apps/ai-game-creator-shell/tests/runtimeInspectResourceMatch.test.ts`（新增）。
+- `apps/ai-game-creator-shell/src-tauri/src/main.rs`：`DEFAULT_GAME_SCRIPT_JS` 补引擎句柄发布。
+- `apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/game.js`、`.../threejs-3d-starter/project/game/main.js`：补引擎句柄发布（只改本地模板源，不重新发布 zip）。
+- 文档收口：`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`（「当前已完成」清单与本里程碑证据表）、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md` §3.4（如行为与草案有出入）。
+
+明确不修改：
+
+- `runtime-region` 引用契约、`genarrative.local-preview-inspect.v1` 消息版本号、`LocalGamePreviewFrame.tsx` 的解析与净化、Rust `direct_codex_user_item` 的校验口径（不新增字段；若实测必须加字段，单独评审）。
+- `packages/shared`、manifest / 版本绑定 / 素材替换链路、Runtime Prompt 文案、模板 zip 发布与线上索引（AGC 玩法 Skill 的生成期契约属阶段二，见下 `## 阶段二进展`）。
+- DOM 点选语义与 `enabled / disabled / cancelled` 协议。
+
+## 实现顺序
+
+1. **搬运桥脚本（行为零变化）**：把 `PREVIEW_FIT_BRIDGE_SCRIPT` 的字符串体原样落到 `resources/preview/local-preview-fit.js`，`preview.rs` 改 `include_str!`。跑 Rust 定向测试 + 一次真机 DOM 点选，确认尺寸上报与 DOM 点选完全不变。
+2. **拆出命中解析**：桥内把 `handleInspectMove` / `handleInspectClick` 共同的部分抽成 `resolveInspectTarget(clientX, clientY)`，返回 `{ selection, rect }`；DOM 分支逻辑等价搬运。
+3. **引擎句柄契约**：桥惰性读取 `window.__GENARRATIVE_PREVIEW_GAME__ = { engine: 'phaser', game }` 或 `{ engine: 'three', THREE, scene, camera, renderer }`（`THREE` 命名空间要求见下「风险」第 2 条）；只认显式句柄，不做鸭子类型猜引擎。缺句柄或 `engine` 未知 → 走第 6 步退化。
+4. **Phaser 4 适配**：`game.input.activePointer` 取指针 → `scene.input.hitTestPointer(pointer)` 优先；无命中对当前激活场景的 `scene.children.list` 逆序（含 `depth`）用 `getBounds()` 与指针世界坐标求交兜底。素材身份：`getData('genarrativeResourceId' | 'genarrativeResourcePath')` 优先，其次 `texture.getSourceImage()` / `texture.source[].image` 的 `currentSrc || src` 与 `texture.key` + `frame.name`。矩形：`getBounds()` 世界矩形按相机换算屏幕矩形。多场景只取激活场景；全程 try/catch，任何一步抛错按"未命中"处理。
+5. **three.js 适配**：`renderer.domElement` 矩形归一化出 NDC → `new THREE.Raycaster()` + `setFromCamera` → `intersectObjects(scene.children, true)` 取最近命中。素材身份：`object.userData.genarrativeResourceId | genarrativeResourcePath` 优先，其次沿 `object.material` 的贴图槽取 `texture.image.currentSrc || texture.source.data.currentSrc`。矩形：命中对象 `Box3` 八角投影取 min/max。
+6. **退化路径**：以上任一步拿不到结果时，按现状输出（`label` = 元素/画面可得的名字，`sourcePath` / `resourceIds` 为空，矩形 = 现状 DOM 语义），不报错、不伪造 id。
+7. **宿主匹配抽纯函数**：`runtimeInspectResourceMatch.ts` 实现优先级——显式 `resourceIds`（已按 manifest 过滤）→ `sourcePath` 与 `localPath` 的精确后缀匹配 → 文件名匹配（现有口径）；序列帧 `imageSequenceFrames[].imageSrc` 参与后两档；结果去重且只保留 manifest 现有素材 id。`index.tsx` 改为调用它。
+8. **脚手架与模板句柄**：`main.rs` 默认脚本与两个模板源补发布句柄（Phaser 在 `new Phaser.Game(...)` 处持有实例；three.js 在场景装配后发布）。
+9. **真机与文档收口**：两条 smoke（见下），补「当前已完成」清单与证据表。
+
+## 验证命令
+
+1. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --offline -- preview`
+2. `npx vitest run apps/ai-game-creator-shell/tests/runtimeInspectEngines.test.ts apps/ai-game-creator-shell/tests/runtimeInspectResourceMatch.test.ts apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx`
+3. `npm run agc:typecheck`（含 `check:tests:types`、`tsc`、skill-pack 指纹、包布局声明、`check-config`）
+4. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+5. 真机：`npm run agc` 拉起客户端 → 新建 Phaser 4 项目（默认脚手架）与 three.js 项目各点一次已登记素材，核对引用芯片名与载荷 `resourceIds`，并各点一次空白与 DOM HUD 确认退化与不回归。
+
+## 风险与回滚点
+
+1. **桥脚本迁移**（顺序 1）：纯搬运，但桥同时承载尺寸上报（`resolveLocalGamePreviewFitLayout` 依赖它），任何字符差异都可能表现为画面适配回归。回滚点：该步单独一次提交，红了就 revert 该提交再重做。
+2. **three.js 需要 `THREE` 命名空间**：Raycaster / Vector2 / Box3 都是模块内类，桥拿不到；从 `camera.constructor` 只能拿到相机类，因此句柄契约要求同时暴露 `THREE`。若实测希望避免暴露命名空间，退路是要求玩法暴露少量构造器（`Raycaster`）——需要改契约，先评审再动手。
+3. **Phaser 4 相机换算**：世界↔屏幕矩形依赖 4.2.1 的相机字段与缩放行为；实测不稳定时降级为"命中对象但只给点标记矩形"，不阻塞引用插入（主规范第 5 条的退化分支）。
+4. **`hitTestPointer` 只覆盖 `setInteractive()` 对象**：几何兜底必须存在，否则未开交互的精灵点不中。
+5. **three.js 递归 raycast 成本**：只在点选模式下按需执行（move 节流），不做常驻监听。
+6. **three.js 真机验收的模板来源**：本里程碑只改本地模板源，不重新发布 `template.zip`；three.js smoke 用模板工程 + 手工补一行句柄进行（句柄就是对外契约），正式"开箱可用"由下一个里程碑的模板发布覆盖。这条限制必须写进交付记录。
+7. **净化为不可绕过**：引擎档取到的 id / 路径先过既有 `sanitizeInspectResourceId` / `sanitizeInspectSourcePath` 再进载荷；宿主匹配只保留 manifest 现有 id，未知值一律丢弃（Rust 拒绝口径不变）。
+
+## 已完成
+
+- 桥脚本搬运 + 引擎档落地：桥脚本落到 `resources/preview/local-preview-fit.js`，`preview.rs` 改 `include_str!`，DOM 点选语义与协议不变，新增 canvas 引擎档。
+- 宿主匹配抽成纯函数 `runtimeInspectResourceMatch.ts`，`index.tsx` 改为调用它，派发载荷结构不变。
+- 脚手架与三个起步模板发布只读引擎句柄：`DEFAULT_GAME_SCRIPT_JS`、`phaser-2d-starter`、`threejs-3d-starter`、`blank-3d-scene`。
+- 自动化验证通过：五个前端用例文件（`runtimeInspectEngines` / `runtimeInspectResourceMatch` / `localGamePreviewFrame` / `resourceReferenceInput` / `appSurface`）292 passed / 9 skipped（301 项）；`npm run agc:typecheck` 通过；`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --offline -- preview` 通过（43 passed）。
+- 分四个提交落盘：6c6850352（桥与引擎档）、6264fed6b（宿主匹配）、ab518ea57（脚手架与模板）、f729203c6（规范与踩坑）；验收证据见里程碑文档。
+
+## 阶段二进展
+
+阶段一让点选能识别素材，但可用性依赖玩法满足三条约定（发布句柄、Phaser 用 Image 装载、对象标注素材身份）；阶段二把这几条写进**生成期契约**，新生成的 Phaser 4 / three.js 项目不改代码即可点出素材。同一 PR 续推，`template.zip` 与线上索引仍未重新发布。
+
+- 主源（唯一写全契约处）：`resources/agc-skills/agc-web-game-development/SKILL.md` 新增「运行画面点选契约（运行态素材身份）」四条——发布只读引擎句柄（`{ engine:'phaser', game }` / `{ engine:'three', three: { Raycaster, Vector2, Vector3, Box3 }, scene, camera, renderer }`，three 瘦身形态见下条）、Phaser 固定 `loader: { imageLoadType: 'HTMLImageElement' }`、给素材渲染对象标注 manifest 身份（Phaser `setData('genarrativeResourceId' | 'genarrativeResourcePath', …)`，three.js `mesh.userData.…`，值只取 `agc_list_registered_assets` 的 `localAssetId` / `localPath`）、素材进 dist 走与 `localPath` 对齐的稳定路径（`public/` 原样拷贝，不用 `import` 的 hash 产物名）；并写明不满足时不报错、不伪造 id、退化为不带素材的区域引用（= 验收面）。
+- 派生副本只补指针，不复制契约：`agc-web-game-development/references/game-quality-checklist.md` 增加一条勾选项；`agc-game-production-workflow/SKILL.md` 第 4 步（Game implementation）指向该契约（新游戏编排必读）。
+- 指纹同步：`npm run agc:skill-pack:sync` 更新 `resources/agc-skills/manifest.json` 的 `version` 与两个 skill 的 `sha256`；`skill_pack.rs` 逐文件 `include_bytes!`，因此**未新增 skill 文件、未改任何 Rust**。
+- 验证：`npm run agc:typecheck`（含 skill-pack 指纹校验）、`node scripts/check-doc-index.mjs`、`npm run check:encoding`、`git diff --check` 全部通过（退出码与结论行见 PR 评论）。
+- 冻结面不变：`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 内句柄，不写"已完成"。
@@ -0,0 +1,61 @@
+# 【里程碑】AGC 运行画面点选识别 Phaser 4 与 three.js 画面上的已登记素材
+
+| 字段        | 值                                                       |
+| ----------- | -------------------------------------------------------- |
+| Version     | 1.0                                                       |
+| Status      | in-progress                                               |
+| Date        | 2026-10-04                                                |
+| Parent Spec | `docs/【功能说明】AGC聊天素材引用-2026-09-08.md`「运行画面素材点选」、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md` §3.4 |
+
+## 目标
+
+- 运行画面点选在 Phaser 4 与 three.js 玩法上，能识别点中对象用的是哪一张已登记素材，并让引用载荷带上该素材的稳定 id。
+- 识别不出来时不伪造、不报错，按主规范退化为不带素材的区域引用。
+- HTML 区域点选语义、预览消息协议、引用发送链路与 Rust 校验口径逐字不变。
+- 新建 Phaser 4 项目与 three.js 起步工程开箱即具备点选所需的引擎句柄。
+
+## 范围
+
+- 运行画面点选的引擎档识别：命中对象解析、素材身份来源与优先级、命中矩形高亮。
+- 宿主侧把识别结果映射成 manifest 素材 id（含"精确优先于文件名"的口径）。
+- 起步工程与新建项目默认脚手架的引擎句柄发布。
+- 上述行为的自动化证据与真机 smoke 证据。
+
+## 不在范围内
+
+- 生成期契约落位：把句柄发布与对象素材标注写进 AGC 玩法 Skill（**同一 PR 的阶段二**，见实施计划 `## 阶段二进展`）；重新发布模板产物（`template.zip` 与线上索引）仍不在本次范围内。
+- 运行期资源使用关系持久化（不记录"某素材在某位置被用过"，不注入代码、不写侧车）。
+- Cocos Creator / Godot / Unity 的点选；纯 2D canvas 引擎与 Babylon.js。
+- `runtime-region` 引用契约、预览消息版本号、Rust `resourceIds` 校验、资源选中与信息栏判据的任何变化。
+- 旧项目自动获得能力（不写迁移、不做兼容分支；限制如实写进能力说明）。
+
+## 依赖与前置条件
+
+- 主规范（`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`）与本节里程碑评审通过。
+- 可拉起的 AGC 真机客户端（`npm run agc`，端口与栈规约按 `genarrative-dev-stack-port-routing`），以及一份可复现的 Phaser 4 / three.js 起步工程。
+- 一张已登记到 manifest 的项目素材（图片；three.js 侧另需一张贴图）。
+- 不依赖后端服务、Provider 或登录态。
+
+## 验收标准
+
+- [x] Phaser 4 起步工程：点中由已登记素材渲染的精灵 / 图集帧，引用芯片显示该素材名，载荷 `resourceIds` 命中该素材 id。（浏览器实测：`loader.imageLoadType='HTMLImageElement'` 下自动档 `@hero` + `["hero"]`；默认 XHR 装载贴图为 blob，须由玩法显式标注，见主规范边界）
+- [x] three.js 起步工程：点中贴了已登记贴图的 Mesh（含 GLB 内嵌纹理的模型走显式标注路径），结果同上。（浏览器实测：贴图 Mesh `@hero` + `["hero"]`；`userData.genarrativeResourcePath` 档 `@enemy` + `["enemy-tag"]`）
+- [x] 同一对象同时存在显式素材标注与贴图地址推断时，取显式标注。（`tests/runtimeInspectEngines.test.ts` 33 例；浏览器重叠位取最上层且显式 id 胜出 `["enemy-tag"]`）
+- [x] 无引擎句柄 / 点中空白 / 程序化绘制三种情况：退化为不带素材的区域引用，零报错、零伪造 id，引用可插入可发送。（`runtimeInspectEngines.test.ts` 33 例；浏览器点空白 `@canvas` + `[]` 零报错）
+- [x] 命中对象时高亮为该对象在画面上的区域；取不到对象矩形时高亮范围与 DOM 档一致。（矩形换算改用 `camera.matrixCombined`；浏览器实测与期望逐值相减 Phaser 差 0px、three 最大差 ≈0.0006px，DOM 档为元素矩形）
+- [x] DOM 点选（HTML HUD、媒体 `src`、资源标识属性）行为与现有用例逐字不变。（`localGamePreviewFrame` 14、`resourceReferenceInput` 43、`appSurface` 197 passed / 9 skipped；浏览器实测 HUD 芯片名 `@HUD 区域` 未被素材名改写）
+- [x] 起步工程与新建项目默认脚手架发布引擎句柄；新建 Phaser 4 项目不额外改代码即可点选。（`DEFAULT_GAME_SCRIPT_JS` 与三个起步模板源已发布句柄；`cargo test -- scaffold` 4 passed / 1 既有 ignore。开箱即用未跑真机链路）
+
+## 证据要求
+
+- 自动化：引擎档识别的 JS 单元用例（jsdom 中加载真实桥脚本 + 假引擎对象）、宿主素材映射纯函数用例、桥注入与协议回归用例、`npm run agc:typecheck`。
+- 运行时：Phaser 4 与 three.js 各一条真机点选 smoke（截图或录制，含引用芯片与载荷证据）。
+- 边界：三种退化情况各一条、净化与数量上限不回归、`resourceIds` 只取 manifest 现有素材。
+
+## 验收证据（2026-10-04）
+
+- 命令：`npm run agc:typecheck` 通过（`check:tests:types` / `tsc` / skill-pack 指纹 / 包布局声明 / `check-config` 全过）。
+- 前端用例：`runtimeInspectEngines.test.ts`（33）+ `runtimeInspectResourceMatch.test.ts`（11）+ `localGamePreviewFrame.test.ts`（14）+ `resourceReferenceInput.test.tsx`（43）= 101 passed；`appSurface.test.ts` 197 passed / 9 skipped。
+- Rust：`cargo test … -- preview` 43 passed / 0 failed；`cargo test … -- scaffold` 4 passed / 1 既有 `#[ignore]`（需 npm 装依赖 + Provider）。
+- 真实浏览器冒烟（真实 Phaser 4.2.1 / three 0.184 + 真实桥脚本 `local-preview-fit.js`，被测 sha256 `6276ac48…917a`）：已登记贴图对象得 `["hero"]`、显式标注对象得 `["enemy-tag"]`、非交互精灵经几何兜底命中；点空白 `@canvas` + `[]` 零报错；DOM 档芯片名不被改写；高亮矩形与期望逐值相减，Phaser 差 0px、three 最大差 ≈0.0006px。
+- 未覆盖：Tauri 真机链路（预览服务器注入与路由由 Rust 定向测试覆盖）、多场景叠加、非默认相机（scroll/zoom/rotation）、高亮真机目视。
@@ -2,6 +2,53 @@

 这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。

+## 2026-10-05 运行画面点选的高亮框被尺寸上报当成页面内容：点选后预览自己缩放
+
+- **现象**：three 项目里点选 3D 对象后预览画面自己缩放、视角异常（相机 aspect 与重新适配的距离都变了），点选结束后视口仍停在放大后的尺寸。实测夹具里是**自激振荡**：10 秒内 1459 条尺寸消息、1457 次 iframe 尺寸/缩放变更、1454 次 `resize`，相机 aspect 在 1.607143 ↔ 1.421112 之间来回变。
+- **原因**：高亮框是 `document.body` 下的 `div[data-genarrative-preview-inspect]`（`position: fixed`、尺寸随命中对象），而尺寸上报的 `measureContentBounds` 用 `createTreeWalker(body, SHOW_ELEMENT)` 遍历所有元素并把 `rect.right/bottom` 计入内容尺寸。three 档的高亮矩形来自 `Box3` 八角投影，物体贴近相机时投影盒远超画布（实测 6607×4721、left/top 为负）→ 上报内容被撑到 3756×2643（视口只有 900×560）→ 宿主 `resolveLocalGamePreviewFitLayout` 把 iframe 改成 3756×2643 + scale 0.2119 → 游戏 `resize` 重算相机 → 视口变大又让投影盒更大，如此循环。
+- **结论（现行口径）**：① 桥自己的节点一律不进内容尺寸测量——`measureContentBounds` 的 TreeWalker 用 `acceptNode` 对 `data-genarrative-preview-fit` / `data-genarrative-preview-inspect` 返回 `FILTER_REJECT`；以后新增任何桥注入的 DOM 节点都要带上这两个标记之一，否则会重新引入这条反馈。② 引擎档命中矩形统一裁剪到画布可见范围（`clipInspectRect`；与画布无交集时退化为指针点矩形），不再出现比画面还大的高亮框。
+- **回归**：`apps/ai-game-creator-shell/tests/localPreviewInspectSizeStability.test.ts`（5 例：桥节点不参与测量、同尺寸普通节点仍计入的对照组、进入检查模式与 hover 后尺寸与宿主适配布局不变、投影盒超出画布时载荷被裁剪、与画布无交集时退化为 1×1）。
+- **关联**：`resources/preview/local-preview-fit.js`（`measureContentBounds` / `clipInspectRect` / `threeInspectTarget` / `phaserSelection`）、`features/project-workspace/LocalGamePreviewFrame.tsx`（`resolveLocalGamePreviewFitLayout`）。
+
+## 2026-10-05 把整个 `THREE` 命名空间塞进预览句柄会让 tree-shaking 失效
+
+- **现象**：three 项目的运行画面点选句柄写成 `{ engine: 'three', THREE, scene, camera, renderer }` 时，同一个 Vite 构建的产物从 517,682 B 涨到 730,831 B（+213,149 B ≈ +41%）。
+- **原因**：句柄引用整个 `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-05 预览桥的注入与去重在 Rust 侧没有用例覆盖
+
+- **现象 / 风险**：改动 `preview.rs` 的注入逻辑（`inject_preview_fit_bridge` / `build_preview_response` / `PREVIEW_FIT_BRIDGE_TAG`）时，没有自动化门禁会告诉你「标签没注入」或「注入了两次」。两种失效都只在运行时才暴露：没注入等于整套运行画面点选静默失效（桥脚本的尺寸上报与点选都不执行，页面看起来完全正常）；注入两次会让桥的监听、尺寸上报与点选回调各注册一遍，页面同样看不出差别。
+- **现状**：`preview.rs` 的 `mod tests` 只有 4 个用例——`npm_preview_requires_build_and_prefers_bundled_assets`、`root_layout_serves_root_entry_and_keeps_legacy_paths_available`、`root_layout_does_not_expose_control_or_data_directories`、`legacy_layout_serves_root_ui_modules`；它们只断言预览路由的选取、状态行与页面自身文本，不涉及桥标签是否出现、出现几次，也不覆盖 `scan_preview_fit_bridge_html` 的「页面已带标签就不重复注入」分支（`inject_preview_fit_bridge` 里的 `if scan.has_bridge_script { return html.into_bytes(); }`）。
+- **结论（现行口径）**：这类「把常量原样返回 / 标签字符串存在」的转发型行为不固化成长用例（仓库口径：复制与源码文本断言不进测试）。改注入逻辑时按人工验证清单核对：① 响应 HTML 里 ``<script src="/__genarrative/local-preview-fit.js"></script>`` 出现在 `</body>` 前，且是经典脚本（不带 `type` / `nomodule`）；② 页面自身已带该标签时，响应里的标签数量不增加；③ `/__genarrative/local-preview-fit.js` 返回 200，且内容与 `resources/preview/local-preview-fit.js` 逐字节一致（`include_str!` 内嵌，可比 sha256）。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/preview.rs`（`PREVIEW_FIT_BRIDGE_SCRIPT` / `PREVIEW_FIT_BRIDGE_TAG` / `inject_preview_fit_bridge`）、`apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js`。
+
+## 2026-10-04 Phaser 4 `hitTestPointer` 的返回顺序不是叠放顺序
+
+- **现象**：运行画面点选 Phaser 4 画面时，按「数组第一个 / 最后一个」当最上层会点错对象——点的是上层精灵，引用却落到下层的素材上；对象越多越容易错。
+- **原因**：`hitTestPointer` 返回的是输入对象的注册 / 内部列表顺序，与真实叠放无关；叠放由命中相机 `renderList` 的索引决定（含 depth 与入序）。
+- **结论（现行口径）**：点选命中要按 `pointer.camera.renderList` 的索引取最上层；几何兜底也必须按 depth + 入序排序，不能沿用注册顺序取值。
+
+## 2026-10-04 Phaser 4 默认 XHR 装载下贴图元素是 blob 地址
+
+- **现象**：运行画面点选拿不到原始素材路径——贴图元素上的地址是会话内的 blob 地址，按文件名反推素材会得到无意义的临时名。
+- **原因**：Phaser 4 默认用 XHR 装载图片，地址只在当前会话内有效，不携带仓库 / manifest 里的路径信息。
+- **结论（现行口径）**：Phaser 4 项目的素材身份必须靠玩法显式标注（`setData`）发布，不要试图从 blob 地址反推文件名；没有标注就退化为不带素材的区域引用。与主规范「运行画面素材点选（2026-10-04）」的边界一致。
+
 ## 2026-10-04 把非素材任务塞进「生成任务」账本：taskType 维度、v1 兼容与 live 集合

 - **现象**：首页「AI 项目命名」改成进「生成任务」列表后，第一次读账本（工作台打开项目就会读）就把那条还在跑的命名任务标成**失败**；随后前端的终态推进被拒（记录已终态）。
@@ -99,16 +146,19 @@
 - **原因**：Windows 的 `npm.cmd` 是批处理入口；Node `child_process.spawn('npm.cmd', args, { shell: false })` 会直接返回 `EINVAL`，还未执行根 `npm run dev`。
 - **处理**：`scripts/dev-all.mjs` 在 Windows 使用 `shell: true`、`windowsHide: true` 启动 npm 子进程；POSIX 仍使用独立进程组，退出时按进程组收束。
 - **验证**：Windows 实测根开发栈已启动并完成端口漂移（Web `3001`、API `8084`、worker `8085`、SpacetimeDB `3104`、后台 `3105`），之后 AGC 因当前工作区缺少 `@anthropic-ai/claude-agent-sdk` 退出；dev:all 已收束根栈进程。
+
 ## 2026-10-02 AGC 页面在自绘标题栏外壳里自己算 `100vh`：底部被裁而且没得滚

 - **现象**：帮助页（使用指南 / 联系客服 / 更新日志）在矮窗口里底部卡片看不到，把窗口拉高才出现；外壳 `.launcher-main { overflow: hidden }` 之下没有任何可滚动祖先，页面既滚不动也裁得干净。首页在通知横幅出现时用 `h-[calc(100vh-32px)]`，同样把窗口高度当成了舞台高度。
 - **原因**：AGC 桌面外壳是自绘标题栏（`--window-chrome-height`；窗口 100vh=800 时舞台只有 750），页面根节点写 `100vh` / `100dvh` / `calc(100vh - Npx)` 就比真实舞台高一整个标题栏，差额被外壳裁掉；横幅是 `.launcher-main` 里的真实行，再写 `-32px` 等于重复扣一次。帮助页还没有内层滚动容器，连「内容超高就在内部滚动」这条兜底也不存在。
 - **处理（现行口径）**：页面高度只由外壳分配——`apps/ai-game-creator-shell/src/styles.css` 里 `.launcher-main:has(<页面钩子>)` 是纵向 flex 列（`height: 100dvh`，窗口外壳命中 `height: 100%` 时贴合真实舞台），`.launcher-main > <页面根节点>` 统一 `flex: 1 1 auto; height: auto; min-height: 0`，帮助页这类没有内层滚动容器的再加 `overflow-y: auto`。页面根节点一律不再写 `100vh` / `100dvh` / `calc(100vh - Npx)`；有横幅就靠 flex 自动少一份，不要手算偏移。
 - **验证**：真机判据是 Vite + Chromium 量页面根节点是否正好等于 `.window-chrome__content` 的高度（1440x800 / 1440x560 / 390x844 / 390x560，带与不带横幅），帮助页应可滚动到底。
+
 ## 2026-10-02 固定试玩误判祖先的指针穿透样式

 - `pointer-events:none` 不会强制禁用整棵子树；后代显式 `auto` 可以恢复命中。控件探针只检查目标的计算样式，继承未覆盖的 `none` 仍拒绝；可见性、遮挡、disabled 与 inert 保留各自检查。
 - 修复和回归必须经过生产输入入口及可信事件驱动的状态变化，不能用程序化点击证明真实可玩。双视口 generic 回归与真实触摸验收需要区分，详见 AGC 实施计划“固定试玩控件的指针命中边界”。
+
 ## 2026-10-01 Rust 分片编译失败只剩汇总错误

 - **原因**：`--message-format=json` 把编译诊断写到 stdout；只读取 `compiler-artifact` 的运行器会丢弃 `compiler-message`，CI 只能看到「due to 1 previous error」。
@@ -6285,6 +6335,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **现象**：模型目录把回合路由到 `cc`，本地 `game-creator.config.json` 的 `llm.apiKey` 为空时，Claude Agent SDK 返回失败终态；界面只显示“执行通道未能建立或已断开”。
 - **根因**：Claude sidecar 只从 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 或本地 `llm.apiKey` 读取认证，没有复用已登录的 AGC 平台会话；同时失败终态解析丢弃了上游错误摘要。
 - **处理**：官方模型且未启用自定义目录时，将当前平台会话令牌仅注入 sidecar 子进程环境；保留最多 512 字符的 Claude 终态错误摘要，继续由统一诊断层脱敏，避免凭据落盘。
+
 ## 2026-10-01 AGC 首页把 Web 预检错误与 Tauri IPC 错误合并，造成无法诊断的生成阻拦

 - **现象**：用户在首页点击「做游戏」后看到「Web 游戏环境预检未通过，请检查 Node/npm 或浏览器」，但同一安装包的 `--environment-check` 可能已经返回 `status=ready`；首页仍会阻止自动命名、建项和首次生成。
@@ -6388,11 +6439,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **验证**：`cargo test --locked -p api-server --bin api-server app::tests::http_tracing`（默认并发与 `--test-threads=1` 各连跑 20 次）、`cargo test -p platform-llm observability_tests`；更接近 CI 并发的是整段 `app::tests::`（91 用例同进程）与 `--skip bgfilter_worker --skip wallet_refund_outbox` 的全量 bin（1133 用例）连跑。
 - **关联**：`server-rs/crates/api-server/src/app.rs`、`server-rs/crates/platform-llm/src/observability_tests.rs`。

-
 ## 2026-10-04 AGC 通知计数与 graceful terminate 的断言偶发都来自"跨线程 / 跨用例串台"

 - **现象**：`agent::thread_manager::tests::active_turn_changes_publish_one_notification_per_real_change` 偶发 `left: 8 / right: 7`（进度内容变化必须通知一次）；`process_session::tests::process_session_graceful_terminate_keeps_wrapper_alive_for_target_cleanup` 偶发 `left: "exited" / right: "terminated"`；两者都在 `AI game creator shell Rust lane 2/2` 分片里红。
- **原因 1（通知计数串台）**：测试计数器 `DIRECT_ACTIVE_TURNS_EVENT_TEST_COUNT` 在 *2026-10-01 已按线程作用域隔离*（`thread_local! Cell`），但 2026-10-02 退役 `runtime_driver` 把这段接缝搬进 `agent/direct_events.rs` 时**降级回进程级 `static AtomicU64`**。`--test-threads=1` 只串行测试线程，宿主 `tauri::async_runtime` 的后台回合仍在自己的工作线程上广播「运行中的项目」变了，于是断言取到别的回合的广播。
+- **原因 1（通知计数串台）**：测试计数器 `DIRECT_ACTIVE_TURNS_EVENT_TEST_COUNT` 在 _2026-10-01 已按线程作用域隔离_（`thread_local! Cell`），但 2026-10-02 退役 `runtime_driver` 把这段接缝搬进 `agent/direct_events.rs` 时**降级回进程级 `static AtomicU64`**。`--test-threads=1` 只串行测试线程，宿主 `tauri::async_runtime` 的后台回合仍在自己的工作线程上广播「运行中的项目」变了，于是断言取到别的回合的广播。
 - **原因 2（terminate 竞速）**：测试命令里 leader 打印 READY 后立刻 `exit 0`，同组后代仍存活，trampoline 从 leader 被回收那一刻开始 `PROCESS_SESSION_TARGET_TERMINATE_GRACE_MS=800ms` 宽限；客户端只要在 leader 退出后 >800ms 才发出 terminate（CI 高负载下要跨 durable record 写盘、registry 注册、线程 spawn），会话已按 `exited` 收口，terminate 只能读到既成事实——不是产品缺陷，是测试赌了客户端调度。
 - **处理（现行口径）**：①测试专用的通知计数必须留在测试线程作用域（`thread_local! Cell`），不要用进程级 Atomic；②graceful terminate 用例的 leader 打印 READY 后要用 `wait` 等后台子进程，让 terminate 必然落在会话仍 running 时（断言、trap、`sleep 0.4`、marker 名字都不改）。
 - **验证**：①修复前把计数器临时改回 Atomic 时同一并行口径 42/50 红；修复后并行 50 次 0 红、`--test-threads=1` 200 次 0 红、CI 现场等价块（145 用例）3 次 0 红；②该用例是 `#[cfg(target_os = "linux")]`，Windows 本机跑不到，用真实 Linux 内核（WSL Alpine）验证命令形状：leader 活到 TERM、同组后代完成 400ms 延迟清理（marker=done，real 0.41s）、清理后组内零残留；CI 侧仍应跑 `node apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs --shards=4 --shard-index=4` 复核。
@@ -1,6 +1,6 @@
 # AGC 聊天素材引用

-更新时间：2026-10-03
+更新时间：2026-10-04

 AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，并提供 Codex 风格的 Skill 提及。输入 `@` 会按素材名称、资源 ID 和类型过滤候选项；输入 `$` 会按当前 DirectProject 可用 Skill 名称过滤候选项；也可以点击输入框右侧的 `@` 按钮打开素材选择面板。

@@ -53,6 +53,47 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，

 输入校验按整条消息判断是否有内容：每个 `input_text` 片段都允许是空字符串、空格或换行，不逐片段拒绝，也不合并、删除或改写片段；原始文字、分段和 `content[]` 顺序保持不变。整条消息必须至少包含一段非空白文字，或至少一个非文本 part（素材引用 / 运行画面引用 / Skill 引用 / 附件引用），否则返回“聊天内容不能为空”。各类引用继续执行原有字段、数量、manifest 归属和路径安全校验；即使消息同时带有正文，非法引用也必须拒绝，不能由正文绕过。

+## 运行画面素材点选（2026-10-04）
+
+「点选素材」把运行画面里点中的内容落成一条 `runtime-region` 引用插入对话。点选只影响这一次引用：不改资源选中、不改信息栏判据、不写 manifest 或版本、不重载预览。
+
+### 必须成立的行为
+
+1. **HTML 区域**：点中预览页里的 DOM 元素时，语义保持 2026-09 起的能力——元素矩形、元素上的资源标识属性或媒体 `src` 参与引用身份，行为逐字不变。
+2. **引擎画面**：预览页是 Phaser 4 或 three.js 的 canvas 玩法时，点中由**已登记项目素材**渲染的精灵、图集帧、贴图网格或模型，引用必须带该素材的稳定 id；同一素材在对话里的显示名与其它引用入口（`@` 候选、资源卡「引用」、拖拽批量引用）完全一致。
+3. **身份来源与优先级**：玩法在渲染对象上显式标注的素材身份优先于从贴图地址推断出的文件名；两者都取不到时按第 4 条退化。推断结果必须与 manifest 现有资产对得上——宁可不成引用，也不伪造 id。
+4. **无法确定素材时退化**：画面为程序化绘制、对象没有标注也取不到贴图地址、预览页没有发布引擎句柄——全部退化为**不带素材**的区域引用，与今天的 DOM 退化语义一致：不报错、不静默丢弃，引用仍能插入、能发送；Rust 对未知素材 id 的既有拒绝口径不变。
+5. **命中反馈**：能定位到命中对象时，高亮范围是命中对象在画面上的区域；取不到对象矩形时退化为与 DOM 档一致的高亮范围。
+6. **协议与净化不变**：运行画面点选与 DOM 点选共用同一套预览消息协议、同一套字段净化与数量上限；引擎侧取到的标识必须先过同一套净化才能进入引用载荷。
+7. **点选不改变预览适配**：进入检查模式、悬停、点中对象都不得改变预览页上报的内容尺寸与宿主算出的适配布局；点选自身的高亮层不属于页面内容，不得参与内容尺寸测量。
+8. **命中区域裁剪在画布内**：引擎档的命中区域只取画布范围内的可见部分；命中区域与画布无交集时退化为指针点区域，不产生超出画布的巨型区域。DOM 档仍是元素矩形。
+
+### 边界与非目标
+
+- 支持范围是 Phaser 4 与 three.js 两条 AGC 主力链路；Cocos Creator、Godot、Unity 走各自编辑器桥接，不在本能力范围内。
+- 玩法必须先发布一个只读的引擎句柄，点选才能进入引擎档；未发布的项目按第 4 条退化。**改动前生成的历史项目不会自动具备该句柄**，需要重新生成或人工补充——能力说明里必须如实标注，不承诺历史项目可用。
+- 不引入运行期资源使用关系的持久化：不记录"某素材在画面上某位置被用过"，不注入玩法代码、不写资源侧车、不改 manifest。
+- 不做像素级或颜色拾取，不为了识别素材去改写玩法源码、资源文件或渲染结果。
+- **Phaser 4 默认装载下贴图地址不可得**：Phaser 4 默认用 XHR 装载图片，贴图元素上的地址是会话内的临时地址，读不回原始素材路径。这类项目**必须由玩法显式标注素材身份**才能点出素材；没有标注就按第 4 条退化（退化为不带素材的区域引用），不猜。
+- **只认玩法发布的只读引擎句柄**：预览页没有发布该句柄、或句柄声明的引擎类型不在支持范围内时，一律退化为不带素材的区域引用；宿主不通过扫描全局对象去猜引擎。
+- **引擎档对象名有 40 字符上限（有意保留）**：引擎档命中对象的名字超过 40 字符时按取不到处理，标签退到几何类型 / 对象类型；宿主侧标签上限另为 120。取 40 是为了避免程序化生成的长名塞进引用芯片。
+- **生成期契约落在 AGC 玩法 Skill**：句柄发布、Phaser 图片的 Image 装载、素材渲染对象的身份标注、素材在 dist 的稳定路径这四条写进 `agc-web-game-development` 的「运行画面点选契约」，生成期即按契约产出；本能力说明不承诺历史项目自动具备，也不改写既有项目。
+- **three 句柄只放桥要用的构造器**：契约推荐 `{ engine: 'three', three: { Raycaster, Vector2, Vector3, Box3 }, scene, camera, renderer }`；传整个 `THREE` 命名空间会破坏 tree-shaking（同一 Vite 构建实测 517,682 B → 730,831 B，+41%）。旧形态仍被兼容读取，但新代码与模板只用瘦身形态。
+
+### 验收标准与证据
+
+| 条款 | 验收方式 | 证据 |
+| ---- | -------- | ---- |
+| 2、3 | Phaser 4 与 three.js 各一条真机 smoke：起步工程 + 一张已登记素材，点中渲染对象后核对引用芯片名与 `resourceIds` | 真实 Chromium 端到端（真实 Phaser 4.2.1 / three 0.184；Phaser 分别用 `loader.imageLoadType='HTMLImageElement'` 与默认 XHR 两种装载）：已登记贴图对象得 `resourceIds=["hero"]`、显式标注对象得 `["enemy-tag"]`、非交互精灵走几何兜底也命中。**Tauri 客户端链路未跑**（预览服务器注入与路由由 Rust 定向测试覆盖）。 |
+| 1、6 | 现有 DOM 点选与运行视窗用例不回归 | `tests/localGamePreviewFrame.test.ts`（14 例）、`tests/resourceReferenceInput.test.tsx`（43 例）、`tests/appSurface.test.ts`（197 passed / 9 skipped）不回归；点选载荷仍走同一套净化与消息版本号。 |
+| 4 | 无引擎句柄 / 命中空白 / 程序化绘制三种情况的退化用例 | `tests/runtimeInspectEngines.test.ts`（33 例）覆盖无句柄 / 点空白 / 缺 `renderer.domElement` 三种退化；浏览器点空白得 `@canvas` 且 `resourceIds=[]`、零报错。 |
+| 5 | 高亮矩形：声明级用例 + 真机目视 | 浏览器实测高亮矩形与期望逐值相减：Phaser 差 0px、three 最大差 ≈0.0006px；DOM 档仍是元素矩形。 |
+| 4、5 | 命中对象但取不到素材身份时：芯片显示画面侧可得的名字（对象名 → 几何类型 → 对象类型），不是一律的 `canvas`；矩形仍是命中对象在画面上的区域 | 真实 Chromium + 真实 three 0.184 + 真实桥脚本实测（瘦身句柄 `three: { Raycaster, Vector2, Vector3, Box3 }`）：`object.name = 'Crate'` → 芯片 `Crate`、矩形 143×143；无名字的 `SphereGeometry` → 芯片 `SphereGeometry`、矩形 227×227；旧 `THREE` 命名空间句柄 → 芯片 `LegacyMesh`（两形态都命中）；`userData.genarrativeResourceId` → `resourceIds: ["local-asset:probe"]`。两条 label 兜底与两形态句柄另由 `tests/runtimeInspectEngines.test.ts`（33 例）锁定。 |
+| 7 | `tests/localPreviewInspectSizeStability.test.ts`（5 例，对修复前的桥 5 failed） | 真实 Chromium 夹具对照：尺寸消息 1459 → 3、iframe 布局变更 1457 → 1、游戏 `resize` 1454 → 1、相机 `aspect` 由振荡变为恒定 1.607143。 |
+| 8 | 同文件用例覆盖引擎档的「投影盒超出画布被裁剪」与「无交集退化为 1×1 指针点区域」 | 真实夹具高亮矩形由 `[-2852,-2078,6607,4721]` 变为 `[0,0,904,564]`（画布 900×560 + 2px 边框）；DOM 档仍给元素矩形。 |
+
+素材收敛口径由 `tests/runtimeInspectResourceMatch.test.ts`（11 例）覆盖：显式 id、精确后缀、文件名、序列帧四档与去重。
+
 ## 粘贴解析（2026-09-22）

 把含引用 token 的纯文本粘进输入区时，可以逐字命中的 token 会原位变回引用芯片：