合并 origin/master 到 Game Agent 读取路径分支

- 决策记录同时保留外壳状态栏浮层与 Game Agent 读取路径两条 2026-09-29 条目
2026-09-29 13:18:48 +01:00
parent 59966b55c0 1d6cbd4b67
commit 5454062423
15 changed files with 358 additions and 124 deletions
@@ -1,5 +1,17 @@
 # 决策记录

+## 2026-09-29 外壳状态栏退役：`status` 一行改由浮层承载
+
+- 背景：首页输入框下方、项目组页面头部那一行由 `WorkspaceLauncher` 的 `status` 承接，写入的内容很杂——进行中进度（`正在创建工作区`、`正在选择项目`）、“已取消 / 已创建项目 / 已打开项目目录”这类回显、失败结论（`创建未完成，请重试`、工作区看门狗文案、Provider 报错）以及项目组页面的 `正在检查项目状态`。这一行常驻占页面，用户明确要求整行改成浮层提示，而不是只把「已取消」挑出来。
+- 决策（一个通道）：`status` 不再由页面渲染，统一由外壳浮层承载（`LauncherNoticeToast`）。`HomeView` 只保留 `onStatusChange`，`ProjectsPage` 去掉 `status` prop 与 `.launcher-project-page-status` 那段；项目组页面的 `正在检查项目状态` 由外壳按 `recentWorkspaceRefreshing` 与当前视图合成后进入同一通道。
+- 决策（生存期按需要分两种）：进行中进度与失败结论走**粘性**浮层（`sticky: true`，不自动收起）——这与原来那一行一致，切页回来仍能看到，重建的 10 分钟看门狗文案也不会一闪而过；成功、取消这类回显走**一次性**浮层（`showTransientNotice`，`tone='neutral'` / 成功 2.6 秒、失败 6 秒）。一次性提示优先显示，自己收起后粘性状态（仍在的话）继续显示。
+- 决策（显示范围照旧）：粘性状态只挂在 `home` / `projects` 两个页面上，进项目工作台、模板库、帮助页不再飘在界面上（原来那一行也只长在列表页上），状态本身留着，回首页 / 项目组时照旧显示；运行 / 预览反馈与取消回显不受这条限制，仍在哪里发生就在哪里弹。
+- 决策（一枚 toast）：`RunNoticeToast` 更名 `LauncherNoticeToast`（类型 `LauncherNotice` 增加 `sticky`、挂点 `data-launcher-notice-toast`），运行 / 预览反馈、状态栏内容、取消回显共用一个挂点与一套色调；长文案容器限宽 `min(680px, 100vw - 2rem)` 并换行。
+- 决策（计时不被重渲染打断）：收起回调只从 ref 读，不写进 effect 依赖——外壳每渲染一次都会换一个内联箭头函数，写进依赖会让 2.6 秒在每次重渲染时重新起算。
+- 影响范围：`apps/ai-game-creator-shell/src/features/app-shell/{LauncherNoticeToast.tsx,model.ts,WorkspaceLauncher.tsx,ProjectCreation.tsx,useHomeProjectCreation.ts}`、`src/view/home/index.tsx`、`src/styles.css`；用例 `apps/ai-game-creator-shell/tests/launcherNoticeToast.test.tsx`（新增粘性不收起、重渲染不重新计时、取消短时收起）与 `launcherNoticeShellWiring.test.tsx`（原 `runNoticeToast` / `runNoticeShellWiring`；新增「进行中状态与取消回显都只走浮层、首页不留那一行」）、`tests/appSurface/home.suite.ts` 三处取消断言、`tests/{homeWebPreflight,designProjectRestore}.test.tsx` 的 hook 参数。
+- 验证：`npx vitest run apps/ai-game-creator-shell/tests` → 191 passed / 1 skipped；`npx tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`；`eslint`（改动文件）、`prettier --check`（改动代码文件）、`npm run check:encoding`、`npm run check:doc-index`、`npm run typecheck`、`git diff --check`。
+- 边界：本次只改这一条状态通道的呈现。首页那行**带动作**的提示留在原地——建项已落盘但没进项目时的「已创建的工作区：<路径>」+「打开已创建的工作区」按钮要能点，不能飘走；设置弹层里「项目创建目录」选择器的「已取消」仍是弹层内自己的状态文案，未一并改动；浮层外观没有在真机窗口里目测过（取消原生选择器需要 Tauri 客户端窗口）。
+
 ## 2026-09-29 Game Agent 读取工具接受绝对路径和项目外路径

 - 决策：`agc_read_project_context` 与 `agc_list_project_files` 可以读取绝对路径，以及用 `..` 离开当前项目的路径。项目内相对路径仍拒绝 `.agent`、凭据文件名、符号链接和硬链接。项目外读取同样拒绝这些受保护名字和链接，但不因路径落在项目外而失败。
@@ -9553,7 +9565,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（运行页顶栏是唯一入口）：运行区域上方的状态行与预览地址小字整体退役（运行画面回到两行栅格）；预览地址改成顶栏动作区里的一枚「在浏览器打开」按钮（opener 插件的 `openUrl`，只在有活预览时渲染；`scripts/check-native-shells.mjs` 另加「视图里 `openUrl(` 只有一个调用点」的判据）；版本入口搬进同一个顶栏动作区，外观复用 `.game-workbench-view-actions button` 的基础规则，不再自带边框 / 底色 / hover，也不再是绝对定位浮层。版本入口在**资源画布与运行页**显示，UI 编辑器壳里不渲染（那一页是聚焦编辑某个资源的界面）。版本名改用一层 span 承载省略号——按钮是 flex 容器，文本直接挂在按钮上时 `text-overflow` 不生效。
 - 决策（运行页不挂生成任务）：`ResourceCanvasAssetGenerationTasksPanelView` 只在资源画布 / UI 编辑器出现，运行页的入口、面板与锚点都不渲染；`[data-generation-tasks-placement='run']` 那一档坐标与组件 `placement` 联合类型里的 `run` 一并删除。任务不丢，切回资源页即可见。
 - 边界：预览的**启动与切换**仍然只走内置运行画面、不自动开系统浏览器——`scripts/check-native-shells.mjs` 那条负向守卫保持原样，本轮只补「浏览器入口只有顶栏这一枚按钮」的正向断言。
- 影响面：`apps/ai-game-creator-shell/src/{App.tsx,styles.css,view/project-development/index.tsx,features/app-shell/*,features/resource-canvas/*}`；用例新增 `tests/runPreviewBrowserOpen.test.tsx`、`tests/runNoticeToast.test.tsx`、`tests/runNoticeShellWiring.test.tsx`（外壳级：替身聊天发提示 → 壳真的渲染浮层）、`tests/gameRunToolbarActionsStyle.test.ts`，改写 `tests/previewActivation.test.tsx`（原断言「聊天里出现已载入运行视图」的地方改为断言 toast 通道 + 对话容器里没有这类提示，并补一条「启动失败走失败色提示且不写对话区」）与 `tests/appSurface/project-development.suite.ts` 的生成任务入口用例。
+- 影响面：`apps/ai-game-creator-shell/src/{App.tsx,styles.css,view/project-development/index.tsx,features/app-shell/*,features/resource-canvas/*}`；用例新增 `tests/runPreviewBrowserOpen.test.tsx`、`tests/runNoticeToast.test.tsx`、`tests/runNoticeShellWiring.test.tsx`（外壳级：替身聊天发提示 → 壳真的渲染浮层）、`tests/gameRunToolbarActionsStyle.test.ts`，改写 `tests/previewActivation.test.tsx`（原断言「聊天里出现已载入运行视图」的地方改为断言 toast 通道 + 对话容器里没有这类提示，并补一条「启动失败走失败色提示且不写对话区」）与 `tests/appSurface/project-development.suite.ts` 的生成任务入口用例。（后续更名：`RunNoticeToast` 与那两条用例自 2026-09-29 起叫 `LauncherNoticeToast` / `launcherNoticeToast.test.tsx` / `launcherNoticeShellWiring.test.tsx`，见当日条目。）
 - 验证：`appSurface` 全量、AGC 壳目录全量、`npm run typecheck`、`check:native-shells:contract`、`check:encoding`、`git diff --check` 全绿；真机观感未复验。

 ## 2026-09-22 DirectProject 聊天状态显式化：回合三态 + 「在跑吗」唯一派生入口 + 数据流地图
@@ -1140,6 +1140,7 @@ game-project/
 - 结构化对话记录按授权本地项目路径追加 JSONL；正式聊天读取 Supervisor active Session 与只读 legacy 项目历史，开发单 Agent 对话读取对应 Agent Session。开发入口已支持本地 Session 新建、切换、归档和分叉，但不提供云端同步。
 - Agent 状态列表从 `.agent/manifest.json` 的任务 / 角色清单、`.agent/run.latest.json` / `.agent/runs/<runId>.json` 的 step、taskGraph、passPlans、lifecycleStatus，以及 `read_game_creator_agent_runtimes` 批量读取的 `.agent/runtime/agents/<taskId>.json` 和最近任务派生；v1 不新增独立状态数据库，也不承诺完整后台 runner。
 - 首页发送、项目组目录选择和本地文件选择必须使用 Tauri 非阻塞原生 picker，并把选择器绑定到当前 `client` 窗口；禁止在同步 command 中调用 `blocking_pick_folder` / `blocking_pick_file` 阻塞 WebView 事件循环。选择器打开期间保留首页草稿可编辑，取消后恢复“开启创作”按钮并回显“已取消”。
+- 外壳状态栏（首页输入框下方、项目组页面头部那一行）不占页面：`status` 一律由外壳的浮层承载（见 `LauncherNoticeToast`）。进行中进度与失败结论走粘性浮层，生存期与原来那行一致（被下一条状态替换或清空时才消失，切页回来仍可见）；成功、取消这类回显走一次性浮层，成功与取消 2.6 秒、失败 6 秒收起。
 - GameAgent 首页“灵感推荐”当前使用客户端随包发布的内置图片素材，不请求主站 `/creation` 的陶泥儿精选 `/api/editor/showcase/resources`，也不引入远端灵感数据源。图片按原始宽高比组成响应式瀑布流，首页内容区域允许纵向滚动；点击图片只打开全屏原图预览，点击图片外遮罩或按 Escape 关闭，不展示标题或其它业务动作。后续改接远端数据前仍须先明确独立数据契约和交互验收。
 - 首页正式桌面版以约 `814px` 的居中内容栏组织品牌区、创作类型、输入框、最近项目与灵感推荐；品牌区和类型按钮在内容栏左缘对齐，输入框和下方模块仍保持整体居中。标题使用深色暖橙层级，固定副标题为“你的游戏创作管家”；选中的创作类型使用实心暖橙按钮，未选中项使用浅色描边，输入框使用更舒展的单行创作起始比例。
 - 最近项目固定展示至多三个横向信息卡：左侧为本地渐变封面占位，右侧只投影项目名称、项目类型、目录真实修改时间和已有最近运行状态。目录检查通过 `modifiedAt` 提供修改时间；没有封面资产时不得假装读取了项目封面，也不新增封面持久化字段。