Merge branch 'master' into feat/msg-queue-to-rust

docs/project-memory/plans/【实施计划】AGC模型Agent模式绑定与Claude Code执行器-2026-09-30.md

@@ -0,0 +1,47 @@
+# 【实施计划】AGC模型Agent模式绑定与Claude Code执行器
+
+| 字段      | 值 |
+| --------- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC模型Agent模式绑定与Claude Code执行器-2026-09-30.md` |
+| Status    | ready |
+| Owner     | Codex |
+
+## 修改边界
+
+- 允许修改：
+  - `server-rs/crates/module-runtime`、`shared-contracts`、`api-server`、SpacetimeDB JSON 目录读写相关测试。
+  - `apps/admin-web` AGC 模型目录页面、类型和测试。
+  - `apps/ai-game-creator-shell` 客户端模型目录/选择、Tauri 配置、Agent Runtime 与 Claude Agent SDK sidecar/adapter、测试。
+  - 当前 AGC 模型目录/Runtime 权威文档和共享记忆（仅写入最终稳定结论）。
+- 明确不修改：
+  - 现有 Codex app-server 协议实现的行为与私有凭据。
+  - SpacetimeDB 表结构、migration、生成绑定（目录 JSON 载荷兼容即可）。
+  - 与本功能无关的工作树已有修改。
+
+## 实现顺序
+
+1. 先补齐目录领域字段、默认/兼容反序列化、后台 DTO/API/admin-web 编辑与测试。
+2. 扩展公开模型摘要和客户端缓存/选择，将后台 `codex`/`cc` 映射为内部执行模式并修复设置保存覆盖问题。
+3. 新增 Claude Agent SDK sidecar 执行器：隔离环境、stream-json 输入输出、模型/Anthropic 配置、MCP 配置、文本与工具事件、超时取消和进程回收；不修改 Codex 执行器。
+4. 在 Runtime/DirectProject 分发处按模型绑定路由；补齐 cc 的配置检查、错误分类、客户端状态展示和回归测试。
+5. 运行定向验证、隔离真实 smoke，回写文档证据；若发现合同变化，先回到主规范再继续。
+
+## 验证命令
+
+1. `npm run check:encoding`
+2. `git diff --check`
+3. `npm --prefix apps/admin-web run test -- --run src/pages/AdminAgcModelsPage.test.tsx`
+4. `npm --prefix apps/admin-web run typecheck`（以仓库实际 script 为准）
+5. `cargo test -p module-runtime agc_models`
+6. `cargo test -p api-server agc_model`
+7. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 的配置/Claude/Direct 定向测试
+8. `npm --prefix apps/ai-game-creator-shell run test -- --run` 与类型检查（按实际 script 收窄）
+9. 隔离临时项目运行 Claude Code 文本、受控 MCP、取消/回收 smoke
+
+## 风险与回滚点
+
+- Claude Agent SDK sidecar 的 stream-json 事件或输入格式变化：adapter 只接受白名单事件，失败关闭；可将模型绑定回 `codex`，不影响现有链路。
+- 后台目录新增字段与旧 JSON：使用缺省 `codex`，保存时写回字段；若兼容测试失败，保留目录载荷原格式并只在读投影填默认。
+- 客户端模型选择与 Agent 模式不同步：选择命令以模型目录快照的 `agentMode` 为输入并做枚举校验；同步失败不得切换活动回合。
+- Claude 原生工具越权：默认只接入受控 MCP，禁止原生 Bash/写文件；任何未经宿主确认的工具请求转失败。
+- 取消/进程归属不确定：保持失败关闭，不复用旧 cc 进程；Codex 模式继续走原有执行器。

docs/project-memory/plans/【里程碑】AGC模型Agent模式绑定与Claude Code执行器-2026-09-30.md

@@ -0,0 +1,51 @@
+# 【里程碑】AGC模型Agent模式绑定与Claude Code执行器
+
+| 字段        | 值 |
+| ----------- | --- |
+| Version     | 1.0 |
+| Status      | completed |
+| Date        | 2026-09-30 |
+| Parent Spec | `docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md` |
+
+## 目标
+
+让后台维护的每个 AGC 模型同时决定执行 Agent：默认使用 Codex，显式绑定 `cc` 时由 AGC 客户端调用 Claude Code，并保持宿主工具与回合边界。
+
+## 范围
+
+- AGC 模型目录、后台完整 DTO、客户端公开模型摘要增加 `agentMode`。
+- `codex` / `cc` 的绑定校验、旧目录兼容和客户端模型选择同步。
+- AGC 客户端新增 Claude Code 执行器，使用 Anthropic 接入、Claude Code stream-json 和受控 MCP。
+- 文本回复、受控只读/项目工具调用、流式活动、取消/超时、进程回收和错误分类。
+- Codex 原有模式、provider 模式、自定义模型和后台 revision/权限合同保持兼容。
+
+## 不在范围内
+
+- 删除或改写现有 Codex app-server。
+- 将本机 `cc`（可能是 C 编译器别名）覆盖为 Claude Code 命令。
+- 放开 Claude Code 原生 Bash、任意文件写入、编辑器执行、试玩、付费工具或未登记 MCP。
+- SpacetimeDB 表结构字段变更；目录继续存储在现有 JSON 载荷中。
+- 为 Claude Code 增加新的公开 API 或把 Anthropic 协议伪装为 OpenAI Responses。
+
+## 依赖与前置条件
+
+- Claude Agent SDK sidecar 在开发/运行环境可发现，并支持 `--print --input-format stream-json --output-format stream-json`。
+- 中转可处理 Claude Code 使用的 Anthropic Messages 请求，模型 ID 与后台目录一致。
+- AGC 现有 DirectProject MCP loopback、项目身份、权限、预算和执行租约可复用。
+- 先完成本里程碑的主规范与实施计划评审，再进入代码实现。
+
+## 验收标准
+
+- [x] 后台新增模型默认 `codex`，可选择 `cc`，非法值和缺失值分别按约定拒绝/兼容。
+- [x] 后台 GET/PUT、公开模型目录和客户端选择保持 `agentMode` 一致，旧目录/旧客户端兼容为 Codex。
+- [ ] 选择 `codex` 模型仍启动现有 Codex app-server；选择 `cc` 模型启动 Claude Agent SDK sidecar，不发送 Codex JSON-RPC。
+- [x] `cc` 文本回合成功，模型 ID、Anthropic 地址和凭据不出现在用户提示、日志和错误正文。
+- [x] `cc` 只能通过 AGC 受控 MCP 使用已登记工具；拒绝越界根目录、未授权工具、原生 Bash/写文件和付费工具。
+- [x] `cc` 超时、取消、sidecar 缺失、非零退出、坏 JSON、MCP 断连都能回收进程并释放回合/租约。
+- [x] Codex、provider、自定义 LLM 和模型选择回归通过。
+
+## 证据要求
+
+- 自动化：module-runtime/API/admin-web/AGC Tauri 定向测试；前端类型检查；Rust 编译与测试。
+- 运行时：隔离临时项目的 Claude Code 中转 smoke，至少文本 + 一次受控 MCP 工具 + 取消/进程退出。
+- 边界：旧目录反序列化、非法 agentMode、模型切换绑定、配置保存不覆盖模式、无 `claude`、Anthropic 地址缺失、Codex 回归。

docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md

@@ -320,3 +320,16 @@
 | 同上路径但带 `Cookie` | **403 Forbidden** + `application/json`（`x-api-version: 2026-06-16`、`x-response-time-ms`）——发行读取**拒绝携带账号凭证**的请求，与本地用例断言一致 |
 
 **生产环境**（`genarrative.world`）同一时刻 `/api/game-distribution/games` 返回 **0 条**：说明当前生产还没有任何已发布的游戏，条目 ④「真实环境整链路」需要在生产发布一个作品后再跑。也就是说此刻能拿到的真实环境证据是「dev 部署的公开读路径 + 发行隔离」，写路径与审核链路的真实环境验收仍需生产账号。
+
+## 网页侧两处交互修正（2026-09-30）
+
+- **广场首屏「立即试玩」不再替用户选中作品**：`src/components/game-distribution/GameGalleryPage.tsx` 原来是 `onClick={() => featuredGame && openDetail(featuredGame.id)}`，点一下等于直接打开第一款游戏的详情。现在按钮只把列表滚进视野（按平台页签面板计算相对偏移，`scrollTo({ behavior: 'smooth' })`，无 `scrollTo` 时退化成直接赋值），不再触发 `onOpenDetail`；`featuredGame` 派生随之退役。回归用例 `GameDistributionPages.test.tsx`「首屏「立即试玩」滚动到列表，而不是打开第一款游戏详情」断言 `onOpenDetail` 未被调用且滚动落在页签面板上。
+- **游玩页不再可滚**：移动端此前是整页可滚的半屏播放器。原因是面板仍是 `overflow-auto`，而播放器用 `min-height: calc(100dvh - 8rem)` 撑高页面。现在 `PlatformEntryActiveFlowShell.tsx` 在 `game-play` 舞台给页签容器加 `platform-tab-panel--game-play`（不滚动、去掉多余内边距），`.game-play-page` 改为 `height: 100%; min-height: 0`，播放器 `flex: 1; min-height: 0` 撑满剩余高度；矮视口（`max-height: 26rem`，横屏手机）另给启动面板一套压扁布局，兜底只在极端高度下发生在启动卡片内部，页面与面板本身始终不滚动。启动面板纵向对齐用 `safe center`（`center` 作旧浏览器回退）并把 `overflow-y: auto` 放在基础规则：居中溢出会把顶部标题裁到 `scrollTop = 0` 也够不到的位置，只加内部滚动并不能修掉。回归用例 `PlatformEntryActiveFlowShell.test.tsx`「游玩舞台的页签容器不滚动」「游戏广场等舞台仍保持页签容器滚动」双向锁定。
+- **补齐上面这条的空守卫**：`.platform-tab-panel--game-play { overflow: hidden }` 一开始只有单类名 (0,1,0)，被文件更靠后的 `.platform-desktop-shell--workbench .platform-tab-panel { overflow: auto }`（(0,2,0)）压掉，真实 Chromium 里 `overflow-y` 仍是 `auto`——只是当时内容恰好没溢出，测试与肉眼都没发现。现在覆盖规则带上 workbench 祖先一起写，实测 390x844/360x640/844x390 三档 `overflowY=hidden`、面板与整页横竖都不溢出，广场舞台仍是 `overflow: auto` 且内容可滚。详情见 pitfalls 同日条目。
+- **「我的游戏」列表与画廊同口径**：`.my-game-list` 的单列 `auto` 轨道会被 `white-space: nowrap` 的简介顶到内容最小宽度（实测 592px），加上 `.my-game-card` 缺 `min-width: 0`，390/360 宽的手机上卡片超出视口、面板横向可滚且看着不居中。现在改成画廊那套口径（`grid-template-columns: minmax(0, 1fr)`、`.my-game-card { min-width: 0; overflow: hidden }`、标题 `min-width: 0; overflow-wrap: anywhere`）；真实 Chromium 夹具在 390/360 下量到轨道=卡片=可视宽、面板横向溢出 0（改前 592px 卡片、横向可滚 230/260px）。
+- **页签面板左右留白对齐**：`.platform-tab-panel` 原本写死 `padding-right`（并在移动端与 workbench 两处再压成 0），而它是不分层规则、优先级高于 Tailwind 的 `padding-inline`，导致面板左 12/24px、右 0，列表左右留白 28/16。三处 `padding-right` 删除后左右统一由使用处的 `px-3`/`sm:px-6` 决定：390 下 12/12（列表 28/28）、820 下 24/24（列表 44/44），无 px 类的舞台仍是 0/0；Chromium 夹具实测「我的游戏」与画廊两张页面同时恢复对称，且横向溢出保持 0。
+- **广场的「发布游戏」「我的游戏」上移到 hero 右上角**：两个入口原本混在 hero 下方的 `.game-toolbar` 动作区（和搜索框同排），现在提到 `.game-page-actions` 一行、右对齐放在 hero 上方，并留 1.1rem 底部间距；工具栏只保留标题与搜索。未登录或灰度未命中时两者都不渲染，该行随之消失。Chromium 夹具实测 390/360/820 三档都是 `aboveHero=true`、与 hero 间距 18px、右边缘与 hero 对齐。
+- 真机口径的守卫补在现役 E2E 里：`scripts/check-game-distribution-web-e2e.mjs` 的移动端段新增「移动端游玩页不可滚动（面板与整页都不溢出）」，断言 `.platform-tab-panel` 的 `overflow-y` 为 `hidden`，且面板与整页**横竖两轴**都不溢出（面板自身 `overflow-x: hidden`，横向溢出只会被静默裁掉，只量 `scrollHeight` 会漏掉「内容被裁一半」）。（该脚本需要管理员账号发布一款真实游戏，未在本轮执行；同一批数值用 Chromium 直连 dev 栈的 `/games/play?id=…` 量过，见 pitfalls 同日条目。）
+- **详情页返回按来源回到上一页**：`GameDetailPage` 左上角原来是写死的「返回游戏广场」，并且直接 `setSelectionStage('games')`（等于 push 一条新的 `/games`）。从「我的游戏」点进详情再返回就落到广场，从广场进详情返回也会多压一条重复历史。现在文案简化为「返回」，行为改成优先 `window.history.back()`，由 `ActiveApp` 已有的 `popstate` 同步把舞台还原成真正的来源页（我的游戏 / 广场）；游玩页的返回同样处理，避免详情↔游玩互相 push。协议侧给应用写入的历史条目补了 `__genarrativeAppHistoryDepth`，新增 `hasAppHistoryBackEntry()` 判断「当前条目是应用内导航写入的且存在上一页」；直接打开详情深链、或原生壳里没有可回退条目时，才 `replaceAppHistoryPath` 兜底到广场（游玩页兜底到自己的详情）。回归用例 `activeAppPageRoutes.test.ts` 锁定深度标记语义，`PlatformEntryActiveFlowShell.test.tsx`「游戏详情返回」两条锁定原生返回与深链兜底。
+- **游戏分发的返回文案统一成「返回」**：`GameDetailPage`、`GamePlayPage`（含超时面板里的按钮）、`MyGamesPage`、`GamePublishPage` 四处原本是「返回游戏广场 / 返回详情」，同一套流程里出现三种写法；现在统一成「返回」，目标页仍由各自的 `onBack`（广场 / 我的游戏 / 详情）决定，按钮不再承诺一个可能不对的目的地。`GameDistributionPages.test.tsx` 的断言同步改为 `/^返回$/u`。游玩页工具栏上那个按钮展示的是游戏名（退出开始面板后就靠它认游戏），不属于「返回 xx」文案，保持不动。
+- 验证：`npx vitest run src/components/game-distribution/GameDistributionPages.test.tsx`（21 passed）、`npx vitest run src/components/platform-entry/PlatformEntryActiveFlowShell.test.tsx`（22 passed）、`npx vitest run src/routing/activeAppPageRoutes.test.ts`、`npm run typecheck`、`npx eslint`（五个改动文件）、`npm run check:encoding`、`git diff --check` 全部通过；启动面板的溢出可达性、「我的游戏」移动端横向溢出都用真实 Chromium 静态夹具量过（见 pitfalls 同日条目），详情返回链在真实 Chromium（dev 栈 390x844）实测 `/games`→详情→返回=`/games`、深链直开详情→返回=`/games`、详情→立即玩→返回详情=`/games/detail?id=…`。视觉与真机横竖屏走查仍需人工/截图评审（沿用阶段 C 第 8 条未取证口径）。

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

@@ -9235,3 +9235,9 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（弹窗层级）：个人中心的独立弹窗（`SquareImageCropModal`、`PlatformProfileModalShell` 两个壳层）改回 `UnifiedModal` 默认的页面级 portal（挂到 `document.body`），不再用 `portal={false}` 内联渲染；层级由现有 `z-[80]` 决定，仍在鉴权 / 法务 / 预览等 `z-[110]` 以上弹窗之下。`PlatformStatusDialog` 保持内联（承载运行态内嵌遮罩，不在本次范围）。
 - 影响范围：`src/components/platform-entry/PlatformEntryActiveFlowShell.tsx`、`src/components/creation-home/ClientDownloadEntry.tsx`、`src/components/common/SquareImageCropModal.tsx`、`src/components/platform-entry/PlatformProfileModalShell.tsx`、`src/index.css`。
 - 验证：本地 Vite + Chromium 真机尺寸复核（320/360/375/390/414/480/639/640/768/1024）：顶栏在 320–768 全部单行、右侧留白 16px；弹窗内「上传 / 保存」`elementFromPoint` 命中自身而非底部菜单，overlay 父节点为 `BODY`。定向 Vitest（`ClientDownloadEntry`、`PlatformProfileModalShell`、`PlatformActiveProfileView`、`PlatformEntryActiveFlowShell`、`UnifiedModalPortalTheme`）与 `prettier --check`、`eslint`、`tsc`、`check:encoding` 通过。
+
+## 2026-09-30 AGC 模型绑定 Agent 执行模式
+
+- 后台 AGC 模型目录新增 `agentMode`，只允许 `codex` / `cc`，缺失的历史目录按 `codex` 兼容；模型选择返回的公开摘要同步携带该绑定。
+- 客户端把后台 `codex` 映射到现有 Codex app-server，把 `cc` 映射到独立 Claude Code CLI adapter；不通过替换 Codex JSON-RPC 可执行文件实现。
+- Claude Code 只使用隔离环境和 AGC loopback MCP，禁用原生工具；取消通过独立 Direct 回合进程树回收处理。Codex、provider 和自定义 Responses 链路保持原路径。

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

@@ -6108,6 +6108,39 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **做法**：`npm run check:agc-direct-execution-fixture -- --agc-exe "<已安装渠道包的主程序绝对路径>" --cases completed`。夹具在临时项目和 loopback Provider 上跑 CLI 执行链路，可直接核对已安装包的随包 Codex。（该入口、夹具与 `--direct-codex-chat` CLI 已随入队化退役删除，见 09-24 实施计划第 4 步；这里记的是当时的做法。）
 - **判读**：若报 `Codex app-server JSON-RPC 失败`，sidecar 已启动并返回协议错误，应先检查请求体及已安装包的源码版本；若根本无法启动，再查安装目录 `coding-agent/win-x64/manifest.json` 的组件哈希、`codex-package.json` 的版本和缺失组件。夹具模式中的 `remote_control disabled reason=provider-proxy-auth` 是预期诊断行。
 
+## 2026-09-30 居中溢出叠加内部滚动，会把顶部内容裁到滚不到的地方（游玩页启动面板）
+
+- **现象**：极矮视口（横屏手机，游玩页 `max-height: 26rem` 那一档）里启动面板内容比容器高时，标题与简介被裁在容器上方，`scrollTop` 已经到 0 也够不到，看起来像「标题凭空消失」。
+- **根因**：`.game-player-launch` 同时有 `align-content: center`（两列布局下是 `align-items: center`）与 `overflow-y: auto`。溢出量被居中分配成上下各一半，负方向那一半落在滚动范围之外——滚动只能从 0 开始，所以顶部永远不可达。只给 `overflow-y: auto` 或只改居中都修不掉。
+- **处理**：纵向对齐改用 `safe center`（先写 `align-content: center` / `align-items: center` 作旧浏览器回退，再写 `safe center`），溢出时退回 start；并把 `overflow-y: auto` 提到基础规则，让启动卡片成为唯一的内部滚动兜底，页面与 `.platform-tab-panel` 本身仍保持 `overflow: hidden`。
+- **判据**：真实 Chromium 夹具（`tmp/launch-overflow-check`，把 `gameDistribution.css` 直接链进静态页面）在 `844x200` 下量：改回 `center` 时 `titleTopAtScrollZero = -20`（不可达），改成 `safe center` 后为 `+12`（可达），滚到底按钮同样可达；`390x844` 与 `1280x800` 正常视口不溢出，位置与改前一致。
+- **关联**：`src/components/game-distribution/gameDistribution.css` 的 `.game-player-launch` 与两处媒体查询、`src/components/game-distribution/GamePlayPage.tsx`。
+
+## 2026-09-30 单列 grid 的 auto 轨道被 nowrap 文本撑开，移动端面板只剩横向滚动
+
+- **现象**：「我的游戏」页在 390/360 宽的手机上可以横向滑动，卡片比可视区宽（实测卡片 592px、可视 390px、面板横向可滚 230px），看起来也不居中；同一页面的画廊卡片却正常。
+- **根因**：三件事叠在一起。① `.my-game-list` 是单列 grid，隐式列宽是 `auto`，而 auto 轨道的最小尺寸是**内容最小宽度**，不会被容器宽度压回去；② `.my-game-card`（flex 行）没有 `min-width: 0`，其最小内容宽度 = 封面 `8.5rem` + gap + 正文最小内容；③ 正文里的 `.my-game-card__summary` 是 `white-space: nowrap`，一条长且不可断行的简介就把最小内容宽度顶到 592px。画廊之所以正常，是因为 `.game-grid` 用 `repeat(n, minmax(0, 1fr))`，`.game-card` 又有 `min-width: 0; overflow: hidden`。
+- **处理**：让「我的游戏」与画廊同口径——`.my-game-list` 改 `grid-template-columns: minmax(0, 1fr)`，`.my-game-card` 加 `min-width: 0; overflow: hidden`，标题加 `min-width: 0; overflow-wrap: anywhere`。改后 390/360 实测轨道 = 列表 = 卡片 = 可视宽，面板横向溢出 0。
+- **同批修掉左右留白不对称**：面板左留白 12/24px（Tailwind `px-3`/`sm:px-6`），右留白却是 0，列表左右留白因此是 28/16。根因是 `src/index.css` 里 `.platform-tab-panel` 写死了 `padding-right: 0.25rem`——它属于**不分层（unlayered）规则，优先级高于 Tailwind 放进 `@layer utilities` 的 `padding-inline`**，把右内边距钉死在 0；`@media (max-width: 639px) .platform-tab-panel` 与 `.platform-desktop-shell--workbench .platform-tab-panel` 又各写了一次 `padding-right: 0`。三处声明全部删掉，左右统一交给使用处的 `padding-inline`；没有 px 类的舞台（创作主页 / 我的 / 游玩页）维持 0/0。改后实测 390 下 12/12、820 下 24/24，列表左右留白 28/28 与 44/44。
+- **判据**：真实 Chromium 静态夹具 `tmp/mygames-check/`（`tmp/` 已 gitignore，由 dev 栈 `http://127.0.0.1:10000/tmp/mygames-check/` 托管）同时渲染「我的游戏」和画廊两组卡片，量面板横向溢出与网格轨道宽度：改前 390/360 下轨道 591.891px、卡片 592px、面板横向可滚 230/260px；改后轨道 = 列表 = 卡片 = 可视宽、溢出 0。布局问题 jsdom 量不出来，这类回归目前靠这个夹具手工复核。
+- **关联**：`src/components/game-distribution/gameDistribution.css`、`src/components/game-distribution/MyGamesPage.tsx`、`.game-grid`/`.game-card`。
+
+## 2026-09-30 SPA 的「返回」写死目标页，会丢掉用户真实来源
+
+- **现象**：游戏详情页左上角写死「返回游戏广场」并把舞台设成 `games`。从「我的游戏」点进详情，返回后落在广场而不是我的游戏；从广场进详情，返回还会 push 一条重复的 `/games`，此时浏览器原生后退反而回到刚离开的详情页。
+- **根因**：`setSelectionStage(stage, { path })` 一律走 `pushAppHistoryPath`，而返回按钮复用它，语义变成「前进到广场」；来源页信息从未被记录，返回只能靠猜。
+- **处理**：`activeAppPageRoutes` 给应用写入的历史条目补内部深度标记（`push` 时 +1、`replace` 保持），新增 `hasAppHistoryBackEntry()`；详情/游玩页的返回改为「有应用内历史就 `window.history.back()`（`popstate` 已由 `ActiveApp` 同步舞台），否则 `replaceAppHistoryPath` 兜底到广场/详情」。深度标记而不是只看「有没有 state」是必要的：直接打开深链、或原生壳通过 host bridge 补写首条目时，`history.back()` 会直接退出应用。
+- **判据**：真实 Chromium（dev 栈 390x844）实测 `/games` → 详情 → 返回 = `/games`；深链直开 `/games/detail?id=…` → 返回 = `/games`；详情 → 立即玩 → 返回详情 = `/games/detail?id=…`。jsdom 侧 `activeAppPageRoutes.test.ts` 锁深度标记语义，`PlatformEntryActiveFlowShell.test.tsx`「游戏详情返回」两条锁原生返回与深链兜底。
+- **关联**：`src/routing/activeAppPageRoutes.ts`、`src/ActiveApp.tsx`、`src/components/platform-entry/PlatformEntryActiveFlowShell.tsx`、`src/components/game-distribution/GameDetailPage.tsx`。
+
+## 2026-09-30 单类名覆盖被 workbench 祖先规则压掉，游玩页的「不滚动」守卫实际是空的
+
+- **现象**：给游玩页面板加的 `.platform-tab-panel--game-play { overflow: hidden }` 看起来生效（类挂上了、单测断言类名也过），但真实 Chromium 里 `getComputedStyle(panel).overflowY` 是 `auto`——守卫没生效，只是当时内容恰好没溢出（`panelOverflowY = 0`），所以肉眼和 jsdom 都看不出来。
+- **根因**：`.platform-desktop-shell--workbench .platform-tab-panel { overflow: auto }`（`src/index.css` 文件末尾附近）特异性是 (0,2,0)，而且它在文件里更靠后，把单类名 (0,1,0) 的覆盖压掉了。面板在所有舞台都渲染在这层 workbench 容器里，所以这个覆盖永远轮不到生效。
+- **处理**：覆盖规则带上同样的祖先作用域，`overflow: hidden` 用两个选择器（单类名 + `.platform-desktop-shell--workbench .platform-tab-panel.platform-tab-panel--game-play`）一起写，既压得过 workbench 规则也不依赖文件顺序。
+- **判据**：真实 Chromium（dev 栈 390x844 / 360x640 / 844x390 横屏矮视口）实测 `overflowY=hidden`、面板与整页横竖都不溢出，同时广场舞台仍是 `overflowY=auto` 且内容可滚（689px）。同类问题排查姿势：改 `.platform-tab-panel` 或任何 workbench 内元素的样式，先在浏览器里读 `getComputedStyle`，别只看类名/源码顺序。
+- **关联**：`src/index.css`（`.platform-tab-panel--game-play` 与 `.platform-desktop-shell--workbench .platform-tab-panel`）、`scripts/check-game-distribution-web-e2e.mjs`、`src/components/game-distribution/gameDistribution.css`。
+
 ## 2026-09-24 移动端固定底部菜单会压住「内联」弹窗：`z-index` 高也点不到
 
 - **现象**：手机端主站从头像入口上传头像，裁剪弹窗的「取消 / 上传」被底部「游戏 / 我的」菜单盖住，点按钮命中底部菜单；弹窗遮罩、面板本身都正常渲染，只有底部一条区域失去交互。