文档：同步 AGC 顶栏布局口径与改动后对照图

- PRD 顶栏条款改为一行到底 + 三档降级 + 运行页签即播放入口 + 运行画面刷新入口 - 验收用例 S17 改为「运行」页签入口语义，新增 S17a 刷新运行画面（含排障索引与验收记录表） - decision-log 新增 2026-10-04 顶栏布局决策（档位判据、两处「吞掉溢出」的坑、验证范围） - docs/README.md 索引新增改动后对照图；新增 docs/technical/assets/agc-toolbar-layout-after-20261004/（4 张真实 Chromium 实测截图）
2026-10-04 13:41:22 +08:00
parent b8849b8c01
commit 2bfc62f695
9 changed files with 41 additions and 3 deletions
@@ -78,6 +78,7 @@
 - [GameAgent 资源自由画板与快速编辑](./technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md)
 - [AGC 栏目画布底部工具栏入口矩阵](./technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md)：栏目画布底部工具栏的入口矩阵、可用条件与验收口径。
 - [AGC 资源工作台三处交互收口改动前对照图](./technical/assets/agc-resource-workbench-ui-before-20260914/README.md)：任务侧栏两个关闭入口、左侧贴边折叠把手、顶部播放按钮居中悬浮三张改动前截图与问题说明。
+- [AGC 顶栏布局收口改动后对照图](./technical/assets/agc-toolbar-layout-after-20261004/README.md)：顶栏一行到底、版本入口钉右并三档降级、「播放」并入「运行」页签、运行画面刷新入口四张改动后截图与口径。
 - [AGC 资源派生与非破坏性编辑合同](./technical/【技术方案】AGC资源派生与非破坏性编辑合同-2026-09-09.md)：AGC 全类型现有资源非破坏性编辑的权威合同，约束资源派生、替换与写回边界。
 - [AGC 聊天素材引用](./【功能说明】AGC聊天素材引用-2026-09-08.md)：聊天输入框 @ 引用项目素材的入口、引用模型与「当前版本素材」口径。
 - [AGC 聊天 AI 润色与发送前提醒](./【功能说明】AGC聊天AI润色与发送前提醒-2026-09-10.md)：提示词润色与发送前提醒的交互、失败与取消口径。
@@ -131,7 +131,7 @@
 - 资源总览的“资源依赖 / 资源类型”视图切换使用连通的分段按钮组，相邻选项共享边界并保持唯一选中语义。每个分段都必须有清晰的键盘焦点指示，焦点环不得被分段容器的圆角或 `overflow` 裁切。
 - 右侧 Supervisor 对话中，用户消息使用右对齐、最大宽度受限的主题暖色气泡，assistant 消息保持左对齐；消息换行不得产生水平溢出，执行过程卡继续占满消息区可用宽度。消息列表必须约束在右侧对话列内并独立滚动，不得覆盖中央资源或运行视图；提交按钮必须保留随状态变化的可访问名称。气泡正文在 light / dark 平台主题下均须满足 WCAG AA 普通文本 `4.5:1` 对比度。
 - 客户端正式产品仍只按最小 `1280×720` 横屏合同交付，并保留 `1280×800` 默认窗口与既有基线验收；更窄浏览器样式只负责不崩溃和开发兼容，不改成移动端创作工作台。
- 工作台顶部播放按钮紧贴「资源管理 / 运行」模式切换之后、整组左对齐；不再在桌面视窗中水平居中悬浮；两个页签下都常驻（运行视图空态与预览失败态要靠它重跑）。资源管理视窗触发播放时直接切换到运行视窗并启动本地预览，不再弹出 `game.run_local` 二次确认。
+- 工作台顶部工具条固定**一行到底**：左侧只有「资源管理 / 运行」模式切换，**「运行」页签本身就是播放入口**（页签前带 ▶ 图标；切过去即启动本地预览，不再单开一枚「播放」按钮，也不再弹出 `game.run_local` 二次确认；运行视图空态与预览失败态靠再点一次该页签重跑，不可运行时页签不置灰、点了不切视图并出提示）。右侧动作区贴右，**版本入口钉在最右缘**、固定显示 `版本 N`，空间够时补上括号里的「创建原因 + 时间」，空间不足按固定顺序降级：先只留 `版本 N`，再把「打开项目目录 / 资源面板 / 整理画布」收进「更多」下拉——任何宽度都不把控件甩到第二行。运行画面右下角提供「刷新运行画面」：游戏预览不是实时刷新，改完代码需要重载页面。
 - 创建模式素材画布的“素材名称”是用户可编辑的正式输出名称；“资源用途”是 manifest subtype，不向普通用户开放自由文本。新增资源默认“普通游戏美术”，可从普通游戏美术、统一视觉规范、游戏界面原型、核心美术图集四项中选择。图片精修继承源名称和用途，不显示创建模式保存设置；候选图片只从选中图片的“设为最终图”提交。精修顶栏只保留返回、导入、定位当前最终图、撤销和重做，删除进入图片上下文工具栏，通用 AI 生成只保留给创建模式。图片输出统一使用 PNG；创建模式工具动作与保存设置分层展示，“保存到项目”在 `1280×800` 和窄容器中都必须完整可见。
 - 首页创作输入区与“最近项目”之间不展示共享项目状态文本，“最近项目”标题下也不追加解释性副标题；默认、成功、进行中或失败状态均不得在该位置形成文字行，项目管理页继续保留自己的状态反馈。

@@ -19,6 +19,17 @@
 - 权威文档：`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`）——窄档位收掉的是这一层而不是整枚入口；可访问名、菜单项与排障文案一律保留完整标识。
+- 决策（播放并入运行 + 刷新入口）：删掉独立的「播放」按钮，「运行」页签前加 ▶ 图标，点页签＝`showRunView()` + `onPlay?.()`（与旧播放按钮逐字等价，含「再点一次＝重跑」）；不可运行时页签不置灰、点了既不切视图也不发播放请求，只出既有提示。运行画面右下角新增「刷新运行画面」（全屏那一枚左侧）：`onPlay` 命中活体预览只切视图、不重启服务，真正重载页面靠换 `iframe` 的元素身份（`LocalGamePreviewFrame` 新增 `reloadNonce`）——运行页在另一个端口上，跨域 iframe 里 `contentWindow.location.reload()` 会被浏览器挡掉。
+- 边界：不改后端、契约与 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}.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`（199 passed / 1 skipped 文件，1925 passed / 17 skipped 用例，末次全量）；定向 8 个文件 253 passed；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`、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）：始终单行、版本入口贴右（`chipRightGap = 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` 的监听，批量引用连消费者都没有。
@@ -0,0 +1,23 @@
+# AGC 顶栏布局收口：改动后对照图（2026-10-04）
+
+本目录是「优化 AGC 标题栏布局」（`fix/agc-toolbar-layout`）的改动后截图，供 PR 与后续回归对照使用。四张图都取自一次性冒烟夹具（`.codex/skills/agc-workbench-browser-smoke`：真实 Chromium 挂 `ProjectDevelopmentView`，不是 Tauri 客户端），因此没有客户端窗口边框与左侧启动器侧栏。
+
+| 文件                                              | 画面                    | 改动后的形态                                                                                                                              |
+| ------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `01-toolbar-resources-full-1412.jpg`              | 资源管理页（窗口 1412） | 顶栏一行到底：左侧只剩「资源管理 / 运行」，右侧动作全部内联，版本入口钉在最右缘并显示完整标识 `版本 1（智能体修订 · 2026/10/3 14:21:05）` |
+| `02-toolbar-resources-compact-1240.jpg`           | 资源管理页（窗口 1240） | 空间不足第一档：版本入口收成 `版本 1`，动作一枚不动、不换行                                                                               |
+| `03-toolbar-more-menu-800.jpg`                    | 资源管理页（窗口 800）  | 空间不足第二档：`打开项目目录 / 资源面板 / 整理画布` 收进「更多」下拉，展开即同一批动作                                                   |
+| `04-toolbar-run-tab-and-preview-refresh-1412.jpg` | 运行页（窗口 1412）     | 「播放」并入「运行」页签（页签前带 ▶）；运行画面右下角多一枚「刷新运行画面」，与「全屏预览」并列                                         |
+
+改动前的问题（用户现场截图）：
+
+1. 顶栏放不下时两侧各自 `flex-wrap: wrap`：第二行只剩「播放」与版本入口，两行控件分裂；
+2. 版本入口不贴右缘，被前面按钮的文本宽度顶开；
+3. 「播放」与「运行」是两个入口说同一件事；
+4. 运行画面里的游戏不是实时刷新，改完代码只能切到资源管理再切回来重载。
+
+相关文档口径已同步到：
+
+- [`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`](../../../prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)（顶部工具条那一行）
+- [`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`](../【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md)（S17 播放、S19 刷新）
+- [`docs/project-memory/shared-memory/decision-log.md`](../../../project-memory/shared-memory/decision-log.md)（顶栏降级档位决策）
@@ -64,7 +64,8 @@
 | 步骤                   | 操作                                         | 期望结果                                                                                                 | 对应 PRD 条款                   | 怎么判"过了"                                                                                                                                                                                              | 已知例外 / 未做项                                                                                                                                                                                |
 | ---------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **S16** 版本切换       | 运行模块**右上角**版本选择器 → 切到另一版本  | 触发钮显示当前版本；切换后资源卡「当前使用」高亮与 **@ 面板「当前版本素材」同步更新**，并重载当前预览    | L165、L190、L324、L530；#309 C7 | `aria-label="当前版本：<label>"`、菜单 `role="listbox" aria-label="切换游戏版本"`、选项 `role="option" aria-selected`；`[data-used-by-current-version="true"]` 集合随切换变化                             | **C7 只做记录层 + UI 层**；"历史版本独有资源集合被运行时按版本加载"需新增版本化资源解析机制，**本轮未实现**；版本卡卡面**不渲染**「项目修订 / 父版本」文字                                       |
-| **S17** 播放           | 顶部「播放」                                 | 直接切运行视图并启动本地预览；**不再弹 `game.run_local` 二次确认**；预览占满中央可用区、无 iframe 滚动条 | L16、L71–72、L122、L493         | `data-resource-view-state` 变为 `undefined`；`await window.__TAURI__.core.invoke('get_local_game_preview_status',{projectPath})` → `status==='running'` 且有 `url`（形如 `http://127.0.0.1:<随机端口>/`） | 播放按钮 `disabled={!runAvailable \|\| !onPlay \|\| uiEditorRoute!==null}`，**不可用时点不动**；不可用提示实现文案为「首个可运行原型尚未完成，运行视图暂不可用」，与 PRD L165 表述不同（见 7.4） |
+| **S17** 播放           | 顶部「运行」页签（页签前带 ▶ 图标）          | 切到运行视图并启动本地预览；**不再弹 `game.run_local` 二次确认**；预览占满中央可用区、无 iframe 滚动条 | L16、L71–72、L122、L493         | `data-resource-view-state` 变为 `undefined`；`await window.__TAURI__.core.invoke('get_local_game_preview_status',{projectPath})` → `status==='running'` 且有 `url`（形如 `http://127.0.0.1:<随机端口>/`） | 播放并进「运行」页签，**没有独立的「播放」按钮**：不可运行时（`runAvailable === false`）页签不置灰，点了既不切视图也不发播放请求，只出提示「首个可运行原型尚未完成，运行视图暂不可用」（与 PRD L165 表述不同，见 7.4） |
+| **S17a** 刷新运行画面  | 运行画面右下角「刷新运行画面」（全屏那一枚左边） | 重新载入游戏页面：游戏预览不是 vite dev 的实时刷新，改完代码要看到新一版只有重载页面这一条路（此前只能切到资源管理再切回来） | L134                            | `iframe` 换成新 DOM 节点且 `src` 不变（跨域 iframe 里 `contentWindow.location.reload()` 会被浏览器挡掉，实现走 React `key` 换元素身份）；点击同时向宿主确认一次预览还活着（`onPlay` 命中活体预览不重启服务）。没有活预览时**不渲染**这枚按钮 | 全屏里照旧可用（两枚按钮都在画面那一格内）；只重载页面，不重跑构建                                                                                                                                |
 | **S18** 停止与退出收尾 | 聊天侧工程操作组点「停止预览」；或关闭客户端 | 预览停止、manifest `preview` 对齐 `stopped`（清 url/port）；退出时也统一收尾                             | L165                            | 停止后 `get_local_game_preview_status` 非 running；`.agent/logs/preview.log` 追加 `stopped`；退出后重开同一项目应落回 `resource-overview`                                                                 | 停止按钮**不在**运行视图工具栏，在工作台右侧工程操作组；退出失败会打 `preview.gui_exit.stop_failed`                                                                                              |

 ### E 阶段 · 对话侧
@@ -170,6 +171,7 @@ window.__TAURI__.core.invoke = (cmd, args) => {
 | S15  | 弹窗是否出现 `被 N 个游戏版本使用`；不勾选时版本记录仍在（可读但悬空）                                                                                                               |
 | S16  | `aria-label="当前版本：…"` 是否随切换更新；`[data-used-by-current-version="true"]` 集合是否变化                                                                                      |
 | S17  | `get_local_game_preview_status` 返回的 `status/url/port`；`.agent/logs/preview.log` 的 `running` 行                                                                                  |
+| S17a | `iframe` 是否是**新的** DOM 节点（`document.querySelector('iframe')` 前后比较）而 `src` 不变；没有活预览时 `button[aria-label="刷新运行画面"]` 是否为 `null`                          |
 | S18  | 退出后重开项目是否落回资源总览；Rust 日志中的 `preview.gui_exit.stop_failed`                                                                                                         |
 | S19  | chip 的 `data-resource-reference-id`；两页签 `role="tab"` 的 `aria-selected`；空态文案（`当前版本还没有绑定素材` / `当前项目还没有已登记素材` / `没有匹配的素材`）                   |
 | S20  | 弹窗标题「发送前提醒」；`localStorage['agc.chat.prompt-polish-reminder.disabled']` 的值；`润色中…` 或 `AI 润色失败，可重试` 状态行                                                   |
@@ -204,6 +206,7 @@ api-server 是否本次重启：□ 是  □ 否
 | S15 删除三分支                                                  | ☐ 无引用 ☐ 引用未勾选 ☐ 勾选连带 |                                       |
 | S16 版本切换 + 当前使用高亮 + @ 同步                            | ☐ 过 ☐ 不过                      |                                       |
 | S17 播放 → 运行视图 + 本地预览                                  | ☐ 过 ☐ 不过                      | url：******\_\_******                 |
+| S17a 刷新运行画面（iframe 换节点、src 不变）                      | ☐ 过 ☐ 不过                      |                                       |
 | S18 停止预览 / 退出收尾对齐 stopped                             | ☐ 过 ☐ 不过                      |                                       |
 | S19 @ 引用两页签 + 独立筛选 + chip 原子性                       | ☐ 过 ☐ 不过                      |                                       |
 | S19a @ 面板标签筛选（多标签 AND，叠加关键字与功能分类）         | ☐ 过 ☐ 不过                      |                                       |
@@ -264,7 +267,7 @@ api-server 是否本次重启：□ 是  □ 否
 | 偏差                   | 文档表述                                                           | 代码实际                                                                                                                                                        | 建议                                                                                                                         |
 | ---------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | 资源卡「打开详情」     | PRD L61–62 要求"打开详情"与"播放 / 暂停"是可分别键盘聚焦的同级按钮 | 不存在该按钮（测试显式断言为 `null`）；真正入口是 `选中资源：<栏目> <名>`，播放按钮是 `播放/暂停 <名>`；**只读信息浮层已回归**（2026-09-11 工具条「信息」动作） | 按 #309 C3（取消资源详情面板与全屏编辑路由）判，**C3 取消的仍只是可编辑详情面板与全屏编辑路由**；PRD L61–62 建议同步修订     |
-| 运行入口不可用文案     | PRD L165 显示"当前无可运行版本"，但仍允许点击                      | 源码中无此字符串；实现为「首个可运行原型尚未完成，运行视图暂不可用」；且播放按钮 `disabled`，只有"运行"tab 不 disabled、用 `data-unavailable` 表达              | 建议按"tab 可点 + 播放按钮置灰"判，并把 PRD L165 文案对齐实现                                                                |
+| 运行入口不可用文案     | PRD L165 显示"当前无可运行版本"，但仍允许点击                      | 源码中无此字符串；实现为「首个可运行原型尚未完成，运行视图暂不可用」；「运行」页签不置灰、用 `data-unavailable` 表达，点了不切视图也不发播放请求              | 按"页签可点 + 不可用时什么都不做并出提示"判，并把 PRD L165 文案对齐实现                                                                |
 | 画布生成入口           | #309「画布生成入口未接」                                           | 已接两条：浮层入口只做视频；音频与图片类在栏目画布底部工具栏（见 S11a / PRD §3.10）                                                                             | 按代码与当前产品口径判，并更新 #309 进度段                                                                                   |
 | 分类手设入口           | 旧版 PRD「用户可在分类与标签面板手动设置 category」                | 已移除；面板只编辑 tags（已随 `6bdc8bbd9` 入库）                                                                                                                | 按新口径判                                                                                                                   |
 | 真机 manifest 分类分布 | —                                                                  | 落盘 `unclassified 57 / ui-interaction 3 / scene 1`                                                                                                             | **读时自愈**会把 kind 可明确分类的资产显示到正确栏目，判定必须看 UI 栏目计数，不能看 manifest 文件，否则必然误报"分类不生效" |