Merge remote-tracking branch 'origin/master' into feat/adapt-taonier-skill

# Conflicts:
#	docs/project-memory/shared-memory/pitfalls.md

docs/project-memory/shared-memory/decision-log.md

@@ -1,5 +1,16 @@
 # 决策记录
 
+## 2026-10-07 AGC 命令沙箱原生支持 fnm/nvm：只读挂载窄叶安装前缀，npm 改走 node + npm-cli.js
+
+- 背景：开发构建里 AGC 让命令沙箱执行 `npm run build` / `npm install` 时，宿主 Node 由 fnm 托管，`node` / `npm` 实际是随 shell 会话变化的 fnm multishell 目录里的 shim；bwrap `--tmpfs /run` 会抹掉该路径，而只按单文件挂载 `<前缀>/bin/npm`（它软链到 `lib/node_modules/npm/bin/npm-cli.js`）会因 `Cannot find module '../lib/cli.js'` 失败。此前把宿主 `node` / `npm` / `npx` shim 指到 `/usr/bin/*` 是错误取舍：系统 Node 26 默认启用实验性 Web Storage，会顶掉 vitest 0.34 jsdom 的 localStorage，使 AGC 测试套件在 HEAD 即失败（见 `pitfalls.md` 2026-10-03 条）。
+- 决策（宿主发现与沙箱挂载共用窄叶校验）：新增 `validate_node_installation_prefix`，canonicalize 后拒绝 `/home`、`/root`、`/tmp`、`/var`、`/etc`、`/proc`、`/dev`、`/run`、`/sys`、`/boot`、`/srv` 根、HOME 及其祖先和相对路径，并要求前缀同时含 `bin/node` 与 `lib/node_modules/npm/bin/npm-cli.js`（bundle 形态为 `<前缀>/node` + `node_modules/npm/bin/npm-cli.js`）。宿主版本枚举与 Linux 沙箱只读挂载都调用它，避免两处信任口径漂移。
+- 决策（版本选择）：`.nvmrc` / `.node-version` 是权威 pin，能理解但未安装时返回 `node-version-pinned-not-installed` 失败关闭；`package.json` `engines.node` 只是偏好，永不阻塞；不支持的写法（`iojs`、`||`、部分 `>` / `<=`、hyphen range、prerelease）按未 pin 回退。整体顺序为 pin 命中 > PATH 可解析的可用 Node > 版本管理器回退链（`engines` 最高匹配 > 活动版本 > 默认别名 > 已安装最高版本），只实现文档化比较子集（精确三元组、major、`>=` / `>` / `<=` / `<`、`^`、`~`、`x` / `*`、`lts/*`）；`v22.23.3` 这类带 `v` 的 `.nvmrc` 必须先剥前缀。nvm 的 `alias/default` 常只写主版本号（如 `22`），必须按同一 pin 子集在已安装版本里选最高匹配，不能当成完整三元组 `(22,0,0)`。
+- 决策（沙箱内启动形态）：Linux npm 改为 `node <npm-cli.js>`，因为单文件挂载 npm 软链必然丢 `../lib/cli.js`；只读挂载整棵已验证的安装前缀（不是整个 HOME、`FNM_DIR` 或 `NVM_DIR`）。`npm install` 的联网判定跟随真实启动形态（`node` + `npm-cli.js` + `install`），不因包装变化丢 `--share-net`。
+- 决策（范围与非目标）：托管版本管理器发现只在 `debug_assertions` / development 生效，发布构建继续只认随包 bundle；不把 fnm / nvm CLI 做成沙箱内工具；Windows 不变；不新增 fnm / nvm 之外的版本管理器。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/environment_check.rs`（窄叶校验、托管安装枚举、pin / engines 解析、选择与回退）、`command_sandbox.rs`（Node 工具链挂载收集与合并、`command_sandbox_requests_npm_install`、`FNM_MULTISHELL_PATH` 清理）、`command_exec.rs`（Linux npm `node_launcher`、`project_command_actual_target`、非 Node 程序 PATH 前置工具链 bin）、`process_session_bridge.rs`（`ProcessSessionLaunchPlan::from_launch` 改用实际目标）。
+- 验证方式：`environment_check` 24 passed、`command_sandbox` 14 passed、`command_exec` 19 passed、`process_session` 27 passed（均 `--test-threads=1`）；`GENARRATIVE_COMMAND_SANDBOX_REAL_TEST=1` 真机 bwrap 内 fnm v22.23.3 的 `node --version` 与 npm 10.9.9 通过；另装 nvm v0.40.8 + Node v22.23.3，`command_sandbox_real_linux_opt_in_runs_nvm_installation_prefix` 证明真实 nvm 前缀可在 bwrap 内跑 node / npm，`real_node_npm_environment_versions`（仅 `NVM_DIR` + 空 PATH + 临时 HOME）证明托管解析确实选中 nvm；`cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。验证后 fnm 仍是宿主默认，nvm 未写入任何 shell profile。
+- 边界：nvm 已在验证主机安装（v0.40.8 + Node v22.23.3）并跑通真实前缀与仅 nvm 解析；CI 仍由临时目录夹具覆盖 fnm / nvm 布局，真实安装路径测试保持 opt-in。真实验收前不宣称发布构建也支持 fnm / nvm。
+
 ## 2026-10-06 小红书导出 validate/pack：Chrome 61 能力按硬性 ERROR 拦下，pack 自带白名单不再共享
 
 - 背景：真实项目适配反馈。① `validate.mjs` 的 `/#[A-Za-z_$][\w$]*/g`（class 私有字段）直接在原始文本上匹配，把 `"#e8f4ff"`、`document.querySelector('#hit')` 误判为 ES2018 语法并报 ERROR，把排查引向「构建链没转译」。② `CSS_MODERN_PATTERNS` / `MODERN_RUNTIME_API` 告警被移除后，`flex gap`（Chrome 84+）、`min()/max()/clamp()`（Chrome 79+）等晚于 Chrome 61 的写法被静默忽略却无人拦截，`references/manual-checks.md` 只有人读清单没有工具兜底。③ 宿主在**项目根** `.export/xhs-minitool.zip` 找产物，而 `--zip-out` 相对 cwd 解析；npm 脚本挂在 `game/` 子工程时 `.export/...` 会落到 `game/.export/`，没有任何提示。④ `pack.mjs` 直接 `import './validate.mjs'`，只复制 pack.mjs 会 `ERR_MODULE_NOT_FOUND`。⑤ `validate.mjs` 的 `[project]` 默认值只在源码 USAGE 里，SKILL 参数表没写默认值。

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

@@ -10,6 +10,23 @@
 - **taonier zip 必须存档根 `index.html`**：`.export/taonier.zip` 的存档根必须直接有 `index.html`，不能套外层文件夹（`taonier/index.html`、`game/index.html` 都算失败）。`vite-export-taonier/scripts/pack.mjs` 在落盘前按根入口校验并拒绝；即使绕过，服务端发行合同只认根 `index.html`，会以 `ReleasePackageError::MissingEntry` 映射 422 `PACKAGE_VALIDATION_FAILED` 拒收。适配非标准工程布局时，让 `build:taonier` 把 `--vite-built-dir` 指到真正含 `index.html` 的目录，或让 `pack.mjs` 不套外层；客户端 `run_taonier_export_build` 也在产物收尾复核根入口。
 - **作者预览未发布作品必须走 owner 媒体读，不能再回退素材库 ACL**：发布媒体是项目快照桶对象、不建 `asset_object`，`/api/assets/read-url` 不会给它授权；公开读路由 `GET /api/game-distribution/media/read-url` 只认「已发布且 active」，两条都不覆盖"作者看自己未发布/被驳回作品"。症状是作者中心与 AGC 线上值封面/截图静默退化成占位图（换签失败被吞成空地址），不报错、不阻断。现行口径：作者侧一律走 `GET /api/game-distribution/my-games/{gameId}/media/read-url`（`read-bytes` 同理，需 bearer），判定 = 作品归属 + objectKey 命中该作品当前行的 `cover_object_key` / `screenshots_json`；AGC `resolve_preview_url` 与平台 web 的 `useGameDistributionMediaReadUrl({ gameId })`、`resolveGamePublishImagePreview(objectKey, gameId)` 都已切换。新增读路径时先确认它属于公开面还是 owner 面，别再让作者预览落到公开判定上。
 
+## 2026-10-07 fnm/nvm 托管的 Node 进 bwrap：单文件挂载 npm 必失败，`--tmpfs /run` 会抹掉 multishell PATH
+
+- **现象**：开发构建在 Linux 命令沙箱里执行 `npm run build` / `npm install` 时，宿主 shell 里明明能跑通的 fnm Node，进沙箱后报 `Node.js v26.10.0` 与 `Cannot find module '../lib/cli.js'`，或 npm 命令在路径解析阶段就失败。
+- **根因 1（单文件挂载软链前缀）**：fnm / nvm 的 `<前缀>/bin/npm` 是指向 `<前缀>/lib/node_modules/npm/bin/npm-cli.js` 的软链。bwrap `--ro-bind <前缀>/bin/npm <前缀>/bin/npm` 只挂载这一个文件，`npm-cli.js` 里的 `require('../lib/cli.js')` 找不到同安装内的相对目标，于是报错；必须整棵只读挂载通过窄叶校验的完整安装前缀（含 `bin/node`、`lib/node_modules/npm`），不能只挂 shim 或 `bin/`。
+- **根因 2（`--tmpfs /run` 抹掉活动版本）**：fnm 的活动 `PATH` 项是 `/run/user/<uid>/fnm_multishells/<pid>/bin`；sandbox 的 `--tmpfs /run` 会清空该目录，sandbox 内解析到的 `node` 随之失效或退回系统版本。不要依赖宿主 `PATH` 原样进入沙箱：canonicalize 路径，并把活动版本管理器变量（如 `FNM_MULTISHELL_PATH`）从 sandbox 环境里剔除。
+- **根因 3（错误取舍会打穿测试）**：把宿主 `node` / `npm` / `npx` shim 指到 `/usr/bin/*` 能让沙箱借用系统 Node，但在本机系统 Node 26 上会默认启用实验性 Web Storage，顶掉 vitest 0.34 jsdom 的 localStorage，AGC 测试在 HEAD 即红（见下方 2026-10-03「AGC 测试不在任何 tsconfig 里」条的环境提示）。正确方向是原生支持托管安装，而不是改宿主 shim。
+- **补充（nvm default 别名是主版本号）**：`nvm alias default 22` 写进 `$NVM_DIR/alias/default` 的内容是 `22`，不是完整三元组。若按精确 `(22,0,0)` 去匹配 `versions/node/v22.23.3` 会永远落空，默认别名形同不存在；必须用与 `.nvmrc` 相同的比较子集在已安装版本里选最高匹配。
+- **现行口径**：宿主发现与沙箱挂载共用 `validate_node_installation_prefix`；`.nvmrc` / `.node-version` 权威、`engines.node` 偏好；Linux npm 以 `node <npm-cli.js>` 启动并保留 `npm install` 联网判定。契约见技术方案 V1.11.2。
+- **验证**：`GENARRATIVE_COMMAND_SANDBOX_REAL_TEST=1` 跑 `command_sandbox_real_linux_opt_in_runs_host_node_and_npm_cli`，在真实 fnm v22 前缀下 bwrap 内 `node --version` 与 `node <npm-cli.js> --version` 均通过；单元用例覆盖 pin / engines / 不支持写法 / 宽叶与逃逸前缀 / 联网判定。
+
+## 2026-10-07 cargo 目标目录里被"刷新 mtime"的陈旧 shared-contracts 会让编译报源文件里明明存在的字段缺失
+
+- **现象**：`cargo check` 在 AGC shell 上报 `unresolved import shared_contracts::runtime::ProfileMembershipUpgradeQuoteResponse`、`no field project_version / publication`、`LlmModelsResponse: Deserialize` 等一整组「契约落后」错误；但 `server-rs/crates/shared-contracts/src` 里这些符号确实存在，`git status` 干净，刚重建的 rlib 也含符号。
+- **根因**：`target/debug/deps` 里留着早先构建的 `libshared_contracts-<hash>.rmeta`，其 `.d` 依赖文件停留在旧时间戳，而 `.rmeta` 的 mtime 在快照 / 拷贝过程中被刷新成新时间；cargo 按 mtime 判定该 crate 仍然新鲜，于是把 `--extern shared_contracts=` 指到旧 rmeta，下游就看到旧 API。多份不同 feature 组合的 `shared-contracts-<hash>` 并存时更容易踩中。
+- **处理**：删除该 crate 的全部指纹与产物后重编即可，不必清整棵 target：`rm -rf target/debug/.fingerprint/shared-contracts-* target/debug/deps/*shared_contracts*`，再跑 `cargo check`。判断依据是错误集中在某个 `shared-contracts` API，而源文件与 `git status` 都正常；先用 `cargo check -v 2>&1 | grep -m1 -- '--extern shared_contracts='` 找到实际使用的 rmeta，再核对它同名 `.d` 里的源文件路径与时间戳。
+- **边界**：这是构建缓存 / 快照产物问题，不是契约真源问题；不要因为这类报错去改 `shared-contracts` 或回退下游代码。
+
 ## 2026-10-05 PR #607 复核修复：档位点对齐/对比度、状态文案也走浮层、键盘去重、卸载 flush
 
 - **档位圆点已删除（D1 的收口）**：这一轮把档位圆点**整体删除**（半透明备选方案未采用）。现在滑块只剩轨道 + 圆钮：轨道 6px 圆头、已选段 `--platform-accent` 由 `--strength-ratio` 驱动、**终点落在圆钮中心**（`calc(10px + ratio * (100% - 20px))`）、圆钮 20px 实心暖白（`--platform-panel-fill` + `--platform-subpanel-border` 1px 描边 + `color-mix` 柔影）；强度区横向内边距 `4px 6px 2px` → `4px 0 2px`（滑块铺满卡片内容宽度，填充段与圆钮两端与轨道两端贴齐）；相关 CSS（`space-between` 排布 / `z-index: 2` 抬层 / `.is-active{opacity:0}` / 点的 `color-mix` 底色 / 只为点对齐的 `padding: 0 7px`）与渲染标记一并删除。**判据**：`chatDialogFrameLayout.test.ts` 反向守卫（样式表里不再有 `.project-chat-composer-strength-stops` 规则、组件源码不再渲染该类名；滑块契约仍在：宽 100% / 高 26 / 圆钮 20×20、强度区左右内边距 0）+ `home.suite.ts` 首页菜单里查不到那组点。实测（447 视口，像素扫描）：轨道 90..324（宽 234 = 卡片内容宽），档位 0 时圆钮左缘 90.5（距轨道左端 0.5px）、档位 4 时圆钮右缘 322.3（距右端 1.8px，扫描行不在圆钮正中所以略窄），填充段终点落在**圆钮中心**（`calc(10px + ratio * (100% - 20px))`，被圆钮盖住），因此圆钮右侧不会露出橙色（终点曾写成 `20px + …` = 圆钮右缘，4× 设备像素下能看到一小截溢出）。**历史成因（只留一句，细节由 Git 追溯）**：圆点此前被 6px 轨道盖住、且与圆钮两端错位 ±12.2px，曾用「抬到轨道之上 + space-between 对齐 + 浅暖色」修过一轮，最终整体删除。