merge latest master

2026-10-04 12:24:47 +08:00
parent d45a3fffb1 6c95660588
commit 3db120d72c
159 changed files with 13451 additions and 1653 deletions
@@ -1,5 +1,18 @@
 # 决策记录

+## 2026-10-03 AGC 发布版本标签改为由工程内部版本派生，取代「用户可编辑标签」口径
+
+- 背景：用户实机验收指出发布面板「项目版本」显示 v6，而 AGC 工程内部只有 4 条正式版本记录（资源总览「项目版本」栏目 4 张卡，顶栏「智能体修订」下拉同样只有这 4 条）。核实：面板值来自本地清单 `manifest.projectVersion` 这个可编辑标量，它被三条链路反复钉到**平台** `game_distribution_version.version_number` 上——发布成功回写（`apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs:1531-1535`）、打开面板回读绑定回填（`:536-541`）、用户手改（`:944-965`）；而 `manifest.versions` 从头到尾不参与该值。`publicationRevision` 只做 CAS，与任何版本号都无推导关系（`module-game-distribution/src/domain.rs:27-40` 的版本号解析只比 `max_existing` 与 `requested`）。
+- 决策：AGC 发布面板的「项目版本」改为**由 AGC 工程内部版本记录 `versions[]` 派生**（标签 = 当前存活内部版本条数，即最新版本卡的「版本 N」，空数组取 1），**只读**，且不得被平台 `version_number` 回填或覆盖、不得读取 `publicationRevision`。平台侧 `versionNumber` 语义不变（正整数、允许重复与回退；`None` 仍自动 `max+1` 以兼容网页端与历史客户端）。本地字段 `projectVersion` 降级为遗留兼容位：保留可解析、不再读写（Rust DTO 带 `deny_unknown_fields`，删字段会让存量清单解析失败）。
+- 取代（逐条）：
+  1. `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md:97,99`（原「项目清单保存唯一用户发行版本 `projectVersion`」「AGC 发布面板直接编辑项目清单的 `projectVersion`」）→ 已就地改写为「派生只读 + 遗留兼容位」。
+  2. 同文件原 `:105`（「允许用户修改项目版本标签、重复提交同版本和回退到旧版本标签」）→ 已就地改写为「用户不再编辑版本标签；回退与重复仍由平台侧接受」。
+  3. `docs/project-memory/plans/【实施计划】AGC已发布游戏版本更新-2026-10-02.md:11,23`（「本地唯一 `projectVersion`…不混入内部编辑迭代 `versions[]`」「发布面板编辑 `projectVersion`」）→ 行内追加取代标注。
+  4. `docs/project-memory/plans/【里程碑】AGC已发布游戏版本更新-2026-10-02.md:27-30` 的验收项「项目清单只有一个用户发行版本字段，发布面板编辑它」被取代；「项目版本可以低于线上最新版本」在平台侧继续成立，AGC 侧口径改为「派生标签可能因截尾删除而变小」。
+- 边界：不改 SpacetimeDB 表/字段/procedure，不改 `publicationRevision` CAS，不改公开地址与审核状态机，不重写平台历史版本行，不做版本历史/回滚 UI。AGC 工程内部版本 `versions` 只能追加或按显式放行删除一个后缀（删素材连带删版本），因此派生标签不保证单调；平台必须继续接受回退标签。
+- 影响范围：`packages/shared/src/contracts/gameCreationApp.ts`、`server-rs/crates/shared-contracts/src/game_creation_app.rs`、`apps/ai-game-creator-shell/src-tauri/src/{game_distribution_publish.rs,desktop.rs}`、`apps/ai-game-creator-shell/src/{services/gameDistributionPublish.ts,components/game-distribution/GameDistributionPublishPanel.tsx,App.tsx}`、`apps/ai-game-creator-shell/scripts/check-config.mjs`、`apps/ai-game-creator-shell/tests/**`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/project-memory/plans/`。
+- 验证方式：`npx vitest run …gameDistributionPublish*.test.*`、`npm run agc:typecheck`（含 `scripts/check-config.mjs`）、`cargo test -p shared-contracts`、`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml game_distribution_publish`、`npm run check:doc-index`、`npm run check:encoding`、`git diff --check`；真机：内部版本 4 条、线上最近提交 v6 的项目打开面板显示 v4 且只读，提交 `versionNumber: 4`。
+- 关联文档：[平台入口与玩法链路](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)、[里程碑](【里程碑】AGC发布版本以工程内部版本为准-2026-10-03.md)。
 ## 2026-10-04 游戏游玩次数修订：关停不强制 flush、flush 失败丢弃剩余分片、客户端 IP 只信 X-Real-IP

 - 变更：ADR `docs/adr/【ADR】游戏游玩次数计数-2026-10-03.md` 修订——原「正常 SIGTERM/滚动重启必须在 `finalize_shutdown` 内 force flush」作废；崩溃、被杀、正常关停都允许丢最后一个未落库窗口，`api-server` 不再注册关停 flush。
@@ -19,6 +32,18 @@
 - 权威文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 的 `game_distribution_game` 节，以及 `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 的「游玩计数（已实现）」节。
 - 验证：`cargo check -p api-server` 与 `cargo test -p api-server game_play_counter`（9 passed）通过；前端定向 vitest（点击上报断言 + clientId 稳定性）与 `eslint --max-warnings 0` 通过；`npm run check:server-rs-ddd`、`npm run check:generated-bindings`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。

+## 2026-10-04 AGC 工作台顶栏一行到底：三档降级 + 播放并入运行页签 + 运行画面刷新
+
+- 背景：用户现场截图指出四个问题（改动前的形态与口径见 `docs/technical/assets/agc-toolbar-layout-after-20261004/README.md`）：① 顶栏放不下时两侧容器各自 `flex-wrap: wrap`，第二行只剩「播放」与版本入口，两行控件分裂；② 版本入口不贴右缘，被前面按钮的文本宽度顶开；③「播放」与「运行」两个入口说的是同一件事；④ 运行画面里的游戏不是 vite dev 的实时刷新，改完代码只能切到资源管理再切回来才能重载页面（飞书讨论里提的「单独的刷新」）。
+- 决策（顶栏排版）：工具条改**一行到底**（`flex-wrap: nowrap` + `overflow: hidden`），空间不足不再换行，而是按固定顺序降级、档位写在工具条的 `data-layout` 上：`full` → `compact-version`（版本入口只留 `版本 N`）→ `collapsed-actions`（`打开项目目录 / 资源面板 / 整理画布` 收进「更多」下拉）。顺序与 1px 判定余量是纯函数（`workbenchToolbarModel.ts`，单独用例钉顺序）；档位由 `useWorkbenchToolbarLayout` 实测写入——`ResizeObserver` 管可用宽度、`MutationObserver` 管**内容**变化（切运行页、出现「恢复草稿」都不改顶栏宽度，只看尺寸会停在旧档位上），每次量宽都把候选档位真的写到 DOM 再读 `scrollWidth`。档位不参与 React 状态：写的是工具条自己的属性，React 不声明就不会覆盖；也没用容器查询（阈值随模式与按钮出现与否变化，写死必然抖）。
+- 决策（两个「吞掉溢出」的坑，都是实测踩出来的）：`overflow: hidden` 的 flex 子项能缩到 0 或靠省略号吸收溢出，档位判定就永远量不到真实溢出——所以版本入口默认 `min-width: max-content`（只在 `collapsed-actions` 档放开为 `0`，那一档已退无可退，省略号才是兜底）、「依赖 / 类型」分段补 `flex: 0 0 auto`（此前窄宽度下被压成 0 宽）。`max-width: 1000px` / `max-width: 760px` 两处把工具条改成 `flex-direction: column` 的媒体查询删除（那是「第二行」的另一个来源，降级已由档位负责），`≤1000px` 里给动作区的 `justify-content: flex-end` 一并删除（溢出会甩到左边，`scrollWidth` 看不见）。最后一档确实放不下时（视口远小于 1280 合同宽度）才改右对齐：宁可裁左边，也不把钉在最右的版本入口裁没。
+- 决策（版本入口与两端分组）：工具条这一行**两端留给体量最大的两枚分组控件**——左端「资源管理 / 运行」、右端「依赖 / 类型」（用户口径：「最大的这两个放两边」），中间依次是动作按钮与版本入口；版本入口 `margin-left: auto` 推到动作区右侧，且紧邻排序分段左侧（用户口径：「版本应该在依赖 / 类型左边」），不再是最右那一枚。显示 `版本 N（原因 · 时间）`，其中 `版本 N` 复用资源画布版本卡的编号口径（`manifest.versions` 落盘顺序 + 1，`formatIterationVersionTitle`），括号里那截是独立一层（`formatIterationVersionDetail`）——窄档位收掉的是这一层而不是整枚入口；可访问名、菜单项与排障文案一律保留完整标识。DOM 顺序由 `tests/resourceVersionSwitch.test.tsx`（版本入口在排序分段之前）与 `tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx`（排序分段是动作行最后一个子元素）双向钉住。
+- 决策（播放并入运行 + 刷新入口）：删掉独立的「播放」按钮，「运行」页签前加 ▶ 图标，点页签＝`showRunView()` + `onPlay?.()`（与旧播放按钮逐字等价，含「再点一次＝重跑」）；不可运行时页签不置灰、点了既不切视图也不发播放请求，只出既有提示。运行画面右下角新增「刷新运行画面」（全屏那一枚左侧）：`onPlay` 命中活体预览只切视图、不重启服务，真正重载页面靠换 `iframe` 的元素身份（`LocalGamePreviewFrame` 新增 `reloadNonce`）——运行页在另一个端口上，跨域 iframe 里 `contentWindow.location.reload()` 会被浏览器挡掉。
+- 决策（进入项目自动载入）：站在运行视图上却没有画面可看时自动补发一次 `onPlay`——典型现场是从别的项目切过来（工作台不重挂，`mode` 是工作台自己的 state，上一条项目的运行视图原样留下而画面已经没了），用户只会看到「客户端运行画面尚未载入」，像坏了一样。只在**没有画面且可运行**时发；`showRunView` 先记账再自己发播放（`autoRunPreviewProjectRef`）所以点页签不会被重复触发；同一个项目只自动补一次，失败不打转，手动重跑仍走页签或画面上的刷新按钮。
+- 边界：不改后端、契约与 SpacetimeDB；`runAvailable` / `showRunView` 的门槛语义不变，自动切运行的两条路径（会话内已确认的预览、播放请求）不走 `showRunView`，不会多发播放请求。窄于合同宽度只保证不崩，不做移动端布局。
+- 影响范围：`apps/ai-game-creator-shell/src/{styles.css,view/project-development/{index.tsx,workbenchToolbarModel.ts,useWorkbenchToolbarLayout.ts,WorkbenchMoreActionsMenu.tsx},features/resource-canvas/{GameRunVersionPicker.tsx,resourceCanvasVersionBindingModel.ts},features/project-workspace/LocalGamePreviewFrame.tsx}`；用例 `tests/{workbenchToolbarLayout,runPreviewRefresh,runAutoLoadOnEnter}.test.ts(x)`（新增）、`tests/appSurface/project-development.suite.ts`、`tests/{gameRunToolbarActionsStyle,resourceCanvasVersionBindingModel}.test.ts`；文档 `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S17 改写 + 新增 S17a）、`docs/README.md`、新目录 `docs/technical/assets/agc-toolbar-layout-after-20261004/`。
+- 验证：`npx vitest run apps/ai-game-creator-shell/tests`（200 passed / 1 skipped 文件，1929 passed / 17 skipped 用例，末次全量）；定向 8 个文件 253 passed；`npm run typecheck`（在 `apps/ai-game-creator-shell`，含 `check:tests:types`——只跑 `tsc -p tsconfig.json` 覆盖不到 `tests/`）、eslint `--max-warnings 0`、`prettier --check`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 全绿。真机几何用一次性 Vite 夹具在真实 Chromium 里逐档实测（视口 1412 / 1240 / 1100 / 1024 / 960 / 860 / 800 / 760 / 700 / 640 / 560 / 480 / 400）：始终单行、排序分段贴右缘（`工具栏右缘 - padding - 排序分段右缘 = 0`）、版本入口始终在排序分段左侧、1240/1100 走 `compact-version`、1024/800/700/640/560/480 走 `collapsed-actions`，「更多」下拉三条动作可点且点「资源面板」真的开面板、点「刷新运行画面」`iframe` 换新节点而 `src` 不变；截图见 `docs/technical/assets/agc-toolbar-layout-after-20261004/`。
+
 ## 2026-10-03 AGC 画布引用统一走「活跃聊天输入区」注册表（Issue 602）

 - 背景：画布的「引用」按钮与「拖拽批量引用」只派发 window 事件，消费者只有 `App.tsx` 一处，而它插的是绑在 `PlanningChatView` 上的 `chatComposerRef`；2026-09-22 DirectProject 拆分后普通项目走 `directProjectMode` 提前 return，渲染不到策划面 → ref 恒为 `null`，可选链静默吞掉点击（画布上是死按钮）。同一批合并冲突还丢了 `RESOURCE_REFERENCE_INSERT_MANY_EVENT` 的监听，批量引用连消费者都没有。
@@ -2,6 +2,42 @@

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

+## 2026-10-03 AGC 随包 plugins 的 feature 档位必须与消费方一致，且门禁会因 build.rs 未重跑而假通过
+
+- **现象**：Windows 本机 `npm run check:generated-bindings`（`npm run lint` 链内，`scripts/check-repository-ci.sh` 的 Repository checks 也走它）在 `build.rs:167:29` panic：`插件随包资源校验失败：随包插件存在未声明文件：.../src-tauri/resources/plugins/agc-godot-editor/native/gdextension/bin/win-x64/agc_godot_editor.dll（目标 x86_64-pc-windows-msvc 与当前 feature 组合不允许；请先执行随包资源准备步骤）`；树上换成 `agc-unity-editor/dotnet/publish/win-x64/Agc.Unity.Attach.exe` 时报同一类错。反向还有更隐蔽的形态：门禁 2 秒就 exit 0 说「通过」，但 tree 上其实带着编辑器产物。
+- **原因**：`apps/ai-game-creator-shell/src-tauri/resources/plugins/` 是 gitignored 但被 dev / 发布 / 门禁多流程共用的目录，它的**档位**（staging 里放了哪些编辑器产物）必须与本次 cargo 调用实际生效的 feature 组合一致。`apps/ai-game-creator-shell/src-tauri/Cargo.toml` 的 `[features] default =` 是空的，而 `scripts/check-generated-bindings.mjs` 对 AGC 用的是裸 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`（**不带任何 feature**）；`build.rs` 按「当前 TARGET + 已启用 `CARGO_FEATURE_*`」构造 plugins 允许集合，于是为 windows 编辑器 feature 准备的 `origin: prepared` / `libraryStaging` 产物全成了「未声明文件」。
+- **关键坑（假通过）**：`resources/**` **不是**构建脚本声明的输入（设计如此，避免每次资源变化都重编），所以缓存命中的 `cargo test` **根本不会重跑 `build.rs`**，校验被整个跳过。实测：树上带着未声明的 unity 产物时，门禁仍以 2.33 秒 exit 0「通过」；`touch apps/ai-game-creator-shell/src-tauri/build.rs` 强制重跑后才暴露。
+- **处理（现行口径）**：校验 / 无 feature 的消费方先复位到 featureless：`npm run agc:bundled-resources:prepare -- --features=`。要带编辑器能力的本地 AGC：`npm run agc:bundled-resources:prepare -- --target x86_64-pc-windows-msvc --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute`（`cocos-editor-bridge.dll` 的 native payload 另需 `cocos-editor-injection`）。要求门禁**真校验**过，先 `touch apps/ai-game-creator-shell/src-tauri/build.rs` 再跑门禁。
+- **判据/取证**：复位后强制重跑那次输出 `生成绑定校验通过：shared-contracts（1 个文件）` / `生成绑定校验通过：ai-game-creator-shell（104 个文件）` / `生成绑定校验通过：合计 105 个文件与 Rust 声明一致`（exit 0）。featureless 判据：`resources/plugins` 只有各插件 `plugin.json` + `src/`（cocos 另有 `panels/`），不存在 `Agc.Unity.Attach.exe` / `agc_godot_editor.dll` / `cocos-editor-bridge.dll`。
+- **边界**：这是同一工作树里多人共享的档位——featureless 是无 feature 构建与并发 cargo 运行的前提，带编辑器产物会让它们失败，反之亦然。`prepare-bundled-resources.mjs` 的原子替换要 rename `resources/plugins`，撞上外部目录句柄会 `EPERM` 并把 staging 留在 `resources/plugins-staging-<pid>-<hex>`（`.gitignore:61` 已声明该模式），确认无并发进程后重试即可。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/build.rs`（`validate_staged_plugins` / `validate_prepared_payloads`）、`src-tauri/build_support/package-layout.json`、`apps/ai-game-creator-shell/scripts/{prepare-bundled-resources.mjs,cargo-features.mjs}`、`scripts/check-generated-bindings.mjs`；另见本文件「随包资源的写入方按产物来源分界」「AGC 随包资源的布局只能改声明文件」「构建期 staging 撞上不装 npm 依赖的 Linux 门禁」三条。
+
+## 2026-10-03 工作树位于 `.worktrees/` 下时前端 Vite 被自己的忽略规则整棵排除：改代码不热更
+
+- **现象**：在 `.worktrees/<name>/` 里的工作树改主站或后台前端源码，浏览器看不到任何更新；重启 Vite 也不生效（本轮有人重启 3 次才发现不是缓存问题）。
+- **原因**：根 `vite.config.ts`（`ignoredWatchGlobs`，约 461-468 行）与 `apps/admin-web/vite.config.ts`（约 19-24 行）的忽略列表都含 `'**/.worktrees/**'`。工作树本身就在 `.worktrees/` 目录下，该 glob 会匹配工作树内的**每一个文件**，等于把整个项目排除出 watch——不报错、不提示，只是永远不触发 HMR / 重建。
+- **影响面**：主站 web 与 admin-web 都中招（两者共用这条规则）；`npm run dev:web` 走 `scripts/vite-cli.mjs`，它只是转发到 Vite 自带 bin、用的是同一份根配置，所以经 CLI 入口启动也一样。`apps/ai-game-creator-shell/vite.config.ts` 只忽略 `'**/src-tauri/target/**'`，**不受影响**。
+- **处理方向（本轮未改配置）**：忽略规则必须只排除**其它** worktree 而放行当前 root——例如按真实仓库根计算，形如只忽略 `<repoRoot>/.worktrees/*/` 且显式排除当前 root；或当项目 root 自身已落在 `.worktrees/` 内时不注入该条。不要保留无条件的 `'**/.worktrees/**'`。
+- **验证方向**：修改 `src/**` 一句话后，主站与 admin-web 各自应打印 HMR 更新（修改后立即生效），而不是只在重启后才生效；必要时打印生效的 watch 忽略集合确认不再覆盖当前 root。
+- **关联**：`vite.config.ts`、`apps/admin-web/vite.config.ts`、`apps/ai-game-creator-shell/vite.config.ts`、`scripts/vite-cli.mjs`。
+
+## 2026-10-03 同一工作树并发拉起多份 dev 栈：`.app/dev-stack.json` 互相覆盖，启动兜底清扫会反杀健康栈
+
+- **现象**：在同一工作树里再开一个 `npm run dev` 之后，AGC 侧报「后端归属校验失败」，或前端代理连到别的端口（「后端端口记错」）；更严重的是新会话启动后，`8082` / `8083` 上原本健康的后端被清掉，旧会话随即报连接失败。
+- **原因**：`.app/dev-stack.json` 是**全工作树单文件**（`scripts/dev.mjs` 的 `resolveDevStackStatePath()` → `<repoRoot>/.app/dev-stack.json`，`scripts/dev-all.mjs` 与若干 e2e 脚本也读它），每个 `DevRunner` 都整份覆写快照，端口、SpacetimeDB data-dir 与 instance id 只保留最后写入者，于是两份并发栈互相覆盖实例信息。同时 `dev.mjs` 在启动/退出时会按身份兜底清扫 `stopWindowsWorktreeBackendProcesses`（`api-server.exe` 绝对路径 + SpacetimeDB `--data-dir`），这是**按工作树**而不是按会话匹配的：其它会话留下的半死栈一旦重启，就会把当前健康栈一并收走。
+- **处理（现行口径）**：同一工作树保持**单栈**；确需并发时用显式端口参数（`--api-port` / `--web-port` / `--admin-web-port` / `--spacetime-port` 等）错开，并接受状态文件只有一个「最后写入者」。清理残留必须按**端口 → PID → 命令行**确认归属，再杀该 PID 的整棵进程树；不要 `taskkill /IM node.exe`（会误伤其它会话与 IDE 的 Node 进程）。
+- **排查顺序**：先比对 `.app/dev-stack.json` 的 status / 端口与实际监听（`Get-NetTCPConnection -State Listen -LocalPort ...`）是否一致，再用 `Get-CimInstance Win32_Process` 按本工作树 `server-rs\target\debug\api-server.exe` 路径与 SpacetimeDB `--data-dir` 核对归属；不要因为 `/healthz` 返回 200 就认定后端属于当前会话。
+- **关联**：`scripts/dev.mjs`（`resolveDevStackStatePath` / `stopWindowsWorktreeBackendProcesses`）、`scripts/dev-windows-process.mjs`、`scripts/dev-all.mjs`、`scripts/check-game-distribution-ratings-e2e.mjs`；另见本文件「`npm run agc` 的 Ctrl+C 不能只依赖 shell 包装层与端口健康检查」与 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 2026-10-03 Windows 上会弹阻塞模态的启动失败用例挂死本机分片 runner
+
+- **现象**：Windows 本机 `npm run ai-game-creator-shell:check:rust:shell -- --shard-index=3/4` 长时间无进展（可到 2400s 超时）；单独跑那条用例同样超时——进程还在、CPU 不再增长、也没有子进程，形态很像「测试死锁」或「分片器坏了」。
+- **原因**：`apps/ai-game-creator-shell/src-tauri/src/main.rs:2042` 的 `startup_log_slot_fail_without_path_still_reports_instead_of_going_silent` 调 `StartupLogSlot::fail()`（约 1854 行），而 `fail()` 会走 `show_startup_error_dialog()`；Windows 实现（约 1740 行）用的是 `MessageBoxW(..., MB_OK | MB_ICONERROR | MB_SETFOREGROUND)`，是**阻塞模态**，没有人点「确定」就永不返回。`STARTUP_ERROR_DIALOG_SHOWN`（约 1534 行）只在同一个进程内保证「只弹一次」，对测试用例没有任何豁免。分片 runner 用 `--exact <名单> --test-threads=1` 串行执行，一条挂死就整片挂死。
+- **影响面**：Linux CI 走非 Windows 分支（约 1778 行）只写 stderr，**不受影响**；这是本机专属现象，不要据此判定 Rust 代码或分片规则有问题。
+- **处理（本机绕过）**：改用等价分块跑，而不是整片上阵——同一个测试二进制、同一 `--exact <名单>` 与 `--test-threads=1` argv、同一 TMPDIR 隔离，把这条阻塞用例排除或单独限定。
+- **判据/取证**：单独执行 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell -- --exact startup_log_slot_fail_without_path_still_reports_instead_of_going_silent --test-threads=1` 本机同样挂住；对照非 Windows 分支只产生 stderr 文案。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/main.rs`、`apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`；另见本文件「AGC 壳 Rust 套件按「一片一 job」拆分，且分片必须自校验覆盖」条中此前记为「本机跑到约 20 分钟后长时间无进展」的同一现象。
+
 ## 2026-10-03 AGC 画布「引用」死按钮：window 事件的消费者挂在一个只在另一条链路赋值的 ref 上

 - **现象**（Issue 602）：AGC 资源画布选中一张已登记素材，选中工具条点「引用」（图标 `@`、可见文案与 `title` 都是「引用」）没有任何反应——聊天输入框里不出现 `@素材名` 芯片，也没有任何提示。普通项目（`directProjectMode`）必现，立项策划项目（`planningStartMode`）复现不出来；把素材卡拖到对话栏的批量引用同样没反应。