修复运行页刷新按钮不真正重载 #640
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: GenarrativeAI/Genarrative#640
Reference in New Issue
Block a user
Delete Branch "fix/run-preview-refresh-reload"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
现象
运行页右下角的「刷新运行画面」不是真正重载：游戏页面出现异常（白屏 / 报错）之后点它不会恢复，
必须切到「资源管理」再切回「运行」页才行。
根因（两条）
apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx（改前 :452-456）刷新只换 iframe 的 React
key，src一字不变 —— 同一地址的导航在请求层面没有任何变化，可能直接吃 HTTP 缓存；改了代码、或上一版崩过，都拿不到新页面。
embeddedUrl变化时清空，刷新时不清，于是新页面先被上一版的尺寸渲染、要等它自己上报才纠正；切页会把整个运行分支卸载
（尺寸归零）→ 这就是「必须切出再进才恢复」的来源。
修复
reloadNonce递增的非业务参数__agc_reload：首次加载（nonce=0）地址逐字不动；既有 query / hash 用 URL API 原样保留；
resolveEmbeddedPreviewUrl的http:+127.0.0.1约束与 postMessage 的 origin 校验都不变。key={reloadNonce}元素身份替换，以及点选模式在onLoad里重新 enable。前后对照
__agc_reload=<nonce>（首次加载不变）验证
npx vitest run五文件（localGamePreviewFrame / previewActivation / runPreviewFullscreen /runPreviewRefresh / appSurface）→ 5 passed，224 passed | 9 skipped (233)
npm run agc:typecheck→ EXIT=0npm run check:encoding→ EXIT=0（5268 files）；git diff --check空；git status --porcelain空tests/localGamePreviewFrame.test.ts新增「刷新运行画面：换新节点、地址带一次性参数，并丢掉上一版的测量结果按容器重新适配」（先上报 835px → 刷新后新节点宽高回到容器 800×500）
tests/runPreviewRefresh.test.tsx新增「连点两次各自都是一次新的载入：参数逐次递增」（1 → 2）；既有那条的
src断言按新契约更新为「origin + pathname 仍是原地址 + 带__agc_reload=1」，节点替换与
onPlay调用一次的断言未动边界
resources/preview/local-preview-fit.js、runtimeInspectResourceMatch.ts）。未验证
已同步最新 master（含点选功能 #624 的合并提交
96859666f），本分支新增 merge 提交386fe4b64。git merge --no-ff origin/master，无冲突（master 侧未改本 PR 的 3 个文件；LocalGamePreviewFrame.tsx的刷新修复与两个用例原样保留）。386fe4b64）：npx vitest run7 文件（localGamePreviewFrame / previewActivation / runPreviewFullscreen /runPreviewRefresh / runtimeInspectEngines / localPreviewInspectSizeStability / appSurface）
→ 7 passed，262 passed | 9 skipped (271)
npm run agc:typecheck→ EXIT=0npm run check:encoding→ EXIT=0（5278 files）；git diff --check空；git status --porcelain空（若是刚推完，等 CI 跑完再看结论）。
- 预览框 src 断言改为两种形态都接受：旧的 `src={embeddedUrl}`，或 `src={iframeUrl ?? undefined}` - 新形态额外要求 `iframeUrl` 由 `useMemo` 定义、且定义体内引用 `embeddedUrl`（只改名不算通过） - 其余断言（`resolveEmbeddedPreviewUrl(` / loopback 校验 / sandbox / 单 iframe 与单挂载）原样保留 - 背景：14283db94 为「刷新运行画面」引入 iframeUrl，撞红了 Native shell tests 的 Run native shell contract gates（missing src={embeddedUrl}）；只接受新形态会让 master 反过来红CI 失败根因与修复（Native shell tests）
根因：
Native shell tests的 step「Run native shell contract gates」（npm run check:native-shells:contract）唯一错误
AI game creator embedded preview boundary drifted: missing src={embeddedUrl}（
scripts/check-native-shells.mjs:2650，断言清单在:2645硬钉字面量'src={embeddedUrl}'）。引入者就是本 PR 的提交
14283db94：为了「刷新运行画面」真正重载，把apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx:456改成了
src={iframeUrl ?? undefined}。master（96859666f）跑同一命令 EXIT=0，本 head EXIT=1。修法（本 PR 追加提交
430d983f6）：把预览框 src 断言改成两种形态都接受——旧的
src={embeddedUrl}，或新的src={iframeUrl ?? undefined}且iframeUrl由const iframeUrl = useMemo(...)定义、定义体内引用了被校验过的embeddedUrl（只改名、丢掉派生关系仍按漂移处理）。其余断言（
resolveEmbeddedPreviewUrl(、loopback/127.0.0.1校验、
sandbox=...、单 iframe 与单挂载）一条没删；断言旁加了中文注释说明这次为何允许中转变量。刷新功能本身（
__agc_reload、尺寸重置、iframeUrl派生）一行未动。scripts/下没有该守卫的独立测试或 fixture 钉这些字面量（已搜过，无需连带修改）。
验证（均为本地实跑）：
node scripts/check-native-shells.mjs --groups=contract→ EXIT=0embeddedUrl无关的src={someOtherUrl}）：同一命令 → EXIT=1，报的正是
iframe src must derive from the validated embeddedUrl→ 守卫仍有牙齿（worktree 已删，改动未提交）
96859666f的旧源码 + 放宽后的守卫）：--groups=contract→ EXIT=0 → master 不会因为这次放宽反过来红（worktree 已删）npx vitest run3 文件（localGamePreviewFrame / runPreviewRefresh /previewActivation）→ 22 passed；
npm run agc:typecheck→ EXIT=0；git diff --check空；git status --porcelain空node scripts/check-native-shells.mjs（全量，非--groups=contract）在本机报failed to start h5-host-bridge-tests: spawnSync npm.cmd EINVAL；同一现象在 master 上一样出现（已实测），是脚本在 Windows 上拉起 npm 子进程的既有环境限制，与本改动无关；
CI（Linux）不受影响。
已推送
430d983f6，CI 会以新 head 重跑；Native shell tests 预计转绿。再次同步 master 并复跑门禁
git merge --no-ff origin/master→ 合入 master 顶端51cb05f41（#638「补充创作者主页与关注粉丝工程文档」），无冲突；本分支新增 merge 提交
df30fdeec（父：430d983f6 + 51cb05f41）。刷新修复与守卫修复都原样保留。node scripts/check-native-shells.mjs --groups=contract→ EXIT=0（守卫修复没被跑回去）npx vitest run7 文件（localGamePreviewFrame / previewActivation / runPreviewFullscreen / runPreviewRefresh /runtimeInspectEngines / localPreviewInspectSizeStability / appSurface）→ 7 passed，262 passed | 9 skipped (271)
npm run agc:typecheck→ EXIT=0；npm run check:encoding→ EXIT=0（5325 files）；git diff --check空；git status --porcelain空"Resolve comparison base"（Backend tests 现在是 "Has started running"，而上一轮它在同一 step 24s 就失败）
→ base 漂移已由这次同步解决。Native shell tests / Frontend tests / Rust lane 2/2 正在跑，
Repository checks 与 web tests 仍在排队；结论出炉后如需我再补一条以 CI 结果为准。
CI 8/8 全绿，可合并
df30fdeec77f5019a9dabb8c45d5e4e8578f1bef（含 master51cb05f41的同步 merge）Frontend tests（2m54s）、Backend tests（7m34s）、web tests（3m7s）、Repository checks（6m58s）、
Native shell tests（9m32s）
Backend tests与Repository checks上一轮卡在 "Resolve comparison base"（master 前移导致的base 漂移），这次同步
51cb05f41后都已真正执行并通过；Native shell tests的Run native shell contract gates 在守卫修复（430d983f6）后连续两轮为 success。