Merge branch 'master' of https://git.genarrative.world/GenarrativeAI/Genarrative

.cloudbase/container/debug.json

@@ -0,0 +1 @@
+{"containers":[],"config":{}}

.hermes/shared-memory/pitfalls.md

@@ -23,6 +23,30 @@
 - 验证：点拼图 / 抓大鹅 / 汪汪声浪卡片后，应看到各自既有工作台内容，例如测试中的 `拼图工作区：missing-session`、`抓大鹅工作区：missing-session` 或 `汪汪声浪配置表单`，并且不再出现“X 创作入口”空白页。
 - 关联：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。
 
+## 创作流程刷新恢复必须写私有 query
+
+- 现象：创作生成页或结果页刷新后回到空白工作区、平台首页，或者从作品详情返回时错误复用了别的玩法草稿。
+- 原因：部分创作流程只把 `sessionId` / `profileId` / `draftId` / `workId` 放在前端内存里，没有写进 URL；也曾把写 URL 放在 stage 切换前，`writeCreationUrlState` 因为还停在非创作路径而直接跳过。若跨玩法或公开详情继续保留私有 query，还会污染 `/works/detail?work=...`。
+- 处理：创作页只使用私有 query `sessionId`、`profileId`、`draftId`、`workId` 做刷新恢复，不复用公开 `work` 参数；`pushAppHistoryPath` 只在同一创作流内保留这些 query，离开创作流或切到另一个玩法必须清掉；手动 draft 打开、生成完成和保存回调要在路由已经切到 `/creation/<play>` 后再调用 `writeCreationUrlState`。
+- 验证：`npm run test -- src/services/creationUrlState.test.ts src/routing/appPageRoutes.test.ts src/components/platform-entry/usePlatformCreationAgentFlowController.test.tsx`；手测生成页 / 结果页刷新仍恢复同一草稿，打开公开作品详情 URL 不带私有恢复参数。
+- 关联：`src/services/creationUrlState.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 拼图生成页轮询不要绑展示 phase 或不稳定 setter
+
+- 现象：拼图创作进入生成中页后，`/api/runtime/puzzle/agent/sessions/{sessionId}` 会在 0.3 到 0.5 秒内被反复 GET，看起来像轮询风暴，而不是 3 秒一次的正常刷新。
+- 原因：轮询 `useEffect` 同时依赖了拼图展示 phase 和会随父组件渲染变化的 `setSession` 函数，导致 `puzzleGenerationState` 的进度合并或页面重渲染就会重挂 effect；effect 里又会立即先请求一次 session，于是请求被放大成密集循环。
+- 处理：拼图轮询只绑定 `selectionStage`、`activePuzzleGenerationSessionId` 和“是否仍在生成中”这个布尔条件；`setSession` 通过 ref 保持稳定，不让父组件重新渲染改变轮询器身份。进度 phase 变化只更新展示，不重建轮询。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft"`，并确认恢复生成中草稿后 `getPuzzleAgentSession` 不会因为进度刷新继续连发。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/usePlatformCreationAgentFlowController.ts`、`src/components/platform-entry/usePlatformCreationAgentFlowController.test.tsx`。
+
+## 拼图试玩恢复 query 必须先切到运行态路径再写
+
+- 现象：拼图试玩或正式运行态打开后，刷新会停在“正在进入拼图关卡”，或地址栏只有 `runtimeProfileId`，缺少草稿 `runtimeSessionId`。
+- 原因：`writePuzzleRuntimeUrlState` 只会在当前路径已经是 `/runtime/puzzle` 时写入；如果先触发阶段切换再写 query，或者草稿作品摘要缺少 `sourceSessionId`，就会把恢复参数写丢。`App.tsx` 的 stage 同步也会改 pathname，所以顺序不对时容易只留下部分 query。
+- 处理：进入拼图 runtime 时先 `pushAppHistoryPath('/runtime/puzzle')`，再 `setSelectionStage('puzzle-runtime')`，最后写 `runtimeProfileId`、`runtimeSessionId`、`runtimeLevelId`、`work`、`mode`；草稿 runtime URL state 允许从 `profileId` 反推 `puzzle-session-*`，作为 `sourceSessionId` 的兜底。
+- 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t \"puzzle draft generation auto starts trial and runtime back opens draft result\"`，确认 `window.location.pathname === '/runtime/puzzle'` 且 `window.location.search` 同时包含 `runtimeProfileId` 和 `runtimeSessionId`。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/services/puzzleRuntimeUrlState.ts`、`src/routing/appPageRoutes.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 首页推荐分流参数不能条件性调用 hook
 
 - 现象：桌面首页或移动首页在 HMR、断点切换或重新渲染后直接报 React hook 顺序错误，页面停在“正在加载内容”。

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -8,6 +8,8 @@
 
 当前创作 Tab 只承载赛事 banner、玩法模板分类和两列模板卡；点击模板卡后直接进入对应玩法已有的入口创作表单 stage，不再经过空白占位页，也不把旧表单嵌进创作 Tab 首屏。移动端创作 Tab 顶栏在 `陶泥儿` 品牌同一行显示真实账户泥点数，数据来自 `profileDashboard.walletBalance`，不得再把活动奖池当作账号余额展示。首屏 banner 结构按参考图拆成横向可滑动赛事卡、主体宣传图文区、奖池胶囊、开始 / 结束时间条和卡片内分页点；轮播只保留 `拼图主题创作赛` 和 `抓大鹅主题创作赛`，两个主题赛事奖池均为 `1000` 泥点数。玩法列表不再套外部边框卡片，移动端需要压缩横向边距和两列间距；玩法卡统一按“上图、左上状态标签（仅非开放态显示）、封面右下 `10-20泥点数`、下方白底标题/描述”结构展示，卡片高度保持紧凑但标题、描述和预估消耗点数都必须可见。创作 Tab 根容器不再使用 `platform-page-stage` 这类全局内容卡片壳，但继续保留 `platform-remap-surface` 作为主题和输入框样式命中钩子。创作首屏字号需要对齐平台普通 UI 档位：顶栏泥点组件、banner 正文、分类 Tab 和玩法卡标题 / 副标题 / 消耗说明优先使用 `11px` 到 `14px`，不使用 `text-lg`、`text-xl` 或更大的展示级字号。草稿 Tab 继续承接作品架。RPG、RPG 之外的各玩法入口分别落到既有的 `agent-workspace`、`big-fish-agent-workspace`、`match3d-agent-workspace`、`square-hole-agent-workspace`、`jump-hop-workspace`、`wooden-fish-workspace`、`puzzle-agent-workspace`、`bark-battle-workspace`、`visual-novel-agent-workspace`、`baby-object-match-workspace`，这些入口继续承接各玩法自己的表单、草稿恢复和后续编排，不作为创作 Tab 首屏内容。
 
+创作恢复参数只保留 `sessionId`、`profileId`、`draftId`、`workId` 这四个私有 query。它们只允许在同一条创作链路的结果页、生成页、工作台之间保留；切到首页、公开作品详情、runtime 或另一条玩法链路时必须清掉。生成页恢复时只认当前进入页的时间作为新的 `startedAtMs`，作品摘要里的 `updatedAt` 只用于排序与摘要展示，不再作为生成进度起点。
+
 创作表单提交前的泥点余额前置校验只允许用独立弹窗提示失败原因，不得把用户退回创作入口或玩法模板列表，也不得清空当前表单状态。当前适用拼图、抓大鹅和汪汪声浪等会在前端提交前校验泥点的生成入口；余额不足、余额读取失败都应停留在当前工作台，由用户关闭提示后继续编辑或自行补足泥点。
 
 `PlatformEntryFlowShellImpl.tsx` 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 或同目录紧邻 helper 文件。拆分只允许改变文件组织，不改变入口配置事实源、默认导出、props、页面阶段、UI 文案或现有交互；其中拼图首访 onboarding 已拆为 `PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx`。
@@ -94,6 +96,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 - 结果页允许多关卡并行编辑和生成；某一关卡图片生成完成回包只静默更新该关卡素材与生成态，不得自动打开或切换关卡详情面板，避免打断用户正在编辑的其它关卡。
 - 结果页关卡图片生成只标记对应关卡的局部生成进度，不禁用“新增关卡”、其它关卡详情编辑和结果页导航。
 - 结果页单关测试只能把完整草稿持久化，并通过 `levelId` 指定运行态起始关卡；不得把单关快照作为整份草稿调用 `updatePuzzleWork`，否则 source session 和作品 profile 的 `levels` 会被覆盖成单关，退出重进后其它关卡会丢失。
+- 拼图试玩和正式运行态刷新恢复不复用创作私有 query。进入 `/runtime/puzzle` 时必须写入 `runtimeProfileId`、草稿 `runtimeSessionId`、可选 `runtimeLevelId`、公开作品 `work` 和 `mode=draft|published`；进入运行态的导航顺序必须先切到 `/runtime/puzzle`，再写这些 runtime query，避免被阶段导航清掉后刷新停在“正在进入拼图关卡”。
 - 结果页生成关卡图时若关卡名为空，前端必须传 `shouldAutoNameLevel=true`，后端复用首关命名契约先按画面描述生成关卡名，再在图片生成后用视觉命名结果精修，并把生成名和 UI 背景提示词随本次关卡快照写回。
 - 拼图运行态背景优先读取当前关卡 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，旧数据才兼容 `uiBackgroundImageSrc/uiBackgroundImageObjectKey`；本地试玩、直达指定关卡和正式 `next-level` 推进时，目标关卡缺关卡背景时必须继承同作品首个可用关卡背景，仍缺失时才沿用当前运行态快照背景或默认 UI。运行态按钮视觉优先读取当前关卡 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，先按透明 alpha 自动边界检测识别 spritesheet 中的独立按钮展示矩形，再按原图位置从左到右、从上到下映射到返回、设置、下一关、提示、原图、冻结；同一组件还要按较高 alpha 阈值派生紧致点击热区，透明留白和柔边低 alpha 区域尽量不响应点击。检测失败时回退旧固定六格裁切，缺失时才用现有图标按钮兜底。有 spritesheet 时，返回和设置按钮的点击容器只提供透明点击区，不再叠加默认白色圆形底；底部提示、原图、冻结三枚素材按检测矩形的原始宽高比显示，不能强行拉伸成正圆或铺满整列。底部道具区不再使用连片胶囊背景，提示、原图、冻结三个按钮均匀分布；运行态只展示按钮素材本身，不额外叠加“提示 / 原图 / 冻结”文字。
 - 推荐页本身不是登录门禁入口，未登录用户点击底部或侧边栏的推荐 Tab 应直接进入嵌入运行态，不主动打开登录弹窗。推荐页嵌入运行态必须按真实身份分流：已登录用户或本地已有 access token 时，启动拼图和后续排行榜 / 下一关等正式请求继续走账号 Bearer；只有确认为匿名访客时才申请并透传 runtime guest token。`/api/runtime/puzzle/runs*` 后端统一接受 `RuntimePrincipal`，可识别账号用户和匿名 runtime guest；推荐卡片的后台读写请求仍使用 local auth impact，避免单卡 401 清空整站登录态。创作、个人作品、删除、发布、Remix 等账号或所有权动作仍保持普通用户鉴权。

miniprogram/config.js

@@ -1,17 +1,17 @@
 // 中文注释：这里填写已经在“小程序后台-开发-开发设置-业务域名”配置过的 H5 入口。
 // 示例：https://game.example.com/
 // 注意：必须是 https 域名，不能是 localhost、IP 地址或未备案域名。
-const WEB_VIEW_ENTRY_URL = 'https://dev.genarrative.world/';
+const WEB_VIEW_ENTRY_URL = 'https://www.genarrative.world/';
 
 // 中文注释：这里填写 Rust api-server 的公网 HTTPS 域名，必须在“小程序后台-开发设置-request 合法域名”中配置。
 // 如果 H5 和 API 同域，可保持和 WEB_VIEW_ENTRY_URL 同一个域名；请求路径会固定走 /api/auth/wechat/miniprogram-login。
-const API_BASE_URL = 'https://dev.genarrative.world/';
+const API_BASE_URL = 'https://www.genarrative.world/';
 
 // 中文注释：这里填写微信小程序 AppID，用于后端记录会话来源；project.config.json 里的 appid 也要保持一致。
 const MINI_PROGRAM_APP_ID = 'wx3da23ea14ca66b65';
 
 // 中文注释：按当前上传版本填写 develop / trial / release，后端会写入会话来源快照。
-const MINI_PROGRAM_ENV = 'develop';
+const MINI_PROGRAM_ENV = 'release';
 
 // 中文注释：给 H5 加一个来源标记，便于后续前端或后端识别这是微信小程序 web-view 宿主。
 const WEB_VIEW_SOURCE_QUERY = {

src/components/platform-entry/usePlatformCreationAgentFlowController.test.tsx

@@ -300,6 +300,161 @@ function ActionCompleteHarness({
   );
 }
 
+function SessionChangeHarness({
+  onSessionChanged,
+}: {
+  onSessionChanged: (session: TestSession | null) => void;
+}) {
+  const flow = usePlatformCreationAgentFlowController<
+    TestSession,
+    Record<string, never>,
+    { session: TestSession },
+    TestMessagePayload,
+    { action: string },
+    { session: TestSession }
+  >({
+    client: {
+      createSession: async () => ({
+        session: {
+          sessionId: 'session-open',
+          messages: [],
+        },
+      }),
+      getSession: async () => ({
+        session: {
+          sessionId: 'session-restore',
+          messages: [],
+        },
+      }),
+      streamMessage: async () => ({
+        sessionId: 'session-open',
+        messages: [],
+      }),
+      executeAction: async () => ({
+        session: {
+          sessionId: 'session-compile',
+          messages: [],
+        },
+      }),
+      selectSession: (response) => response.session,
+    },
+    createPayload: {},
+    workspaceStage: 'match3d-agent-workspace',
+    resultStage: 'match3d-result',
+    platformStage: 'platform',
+    isCompileAction: (payload) => payload.action === 'match3d_compile_draft',
+    resolveErrorMessage: (error, fallback) =>
+      error instanceof Error ? error.message : fallback,
+    errorMessages: {
+      open: '打开失败',
+      restoreMissingSession: '缺少会话',
+      restore: '恢复失败',
+      submit: '发送失败',
+      execute: '执行失败',
+    },
+    enterCreateTab: () => {},
+    setSelectionStage: () => {},
+    onSessionChanged,
+    onActionComplete: ({ response, setSession }) => {
+      setSession(response.session);
+    },
+  });
+
+  return (
+    <div>
+      <button type="button" onClick={() => void flow.openWorkspace({})}>
+        打开
+      </button>
+      <button
+        type="button"
+        onClick={() => void flow.restoreDraft('session-restore')}
+      >
+        恢复
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          void flow.executeAction({ action: 'match3d_compile_draft' })
+        }
+      >
+        编译
+      </button>
+    </div>
+  );
+}
+
+function SessionSetterIdentityHarness({
+  onSetterIdentity,
+}: {
+  onSetterIdentity: (setter: unknown) => void;
+}) {
+  const [renderCount, setRenderCount] = useState(0);
+  const flow = usePlatformCreationAgentFlowController<
+    TestSession,
+    Record<string, never>,
+    { session: TestSession },
+    TestMessagePayload,
+    { action: string },
+    { session: TestSession }
+  >({
+    client: {
+      createSession: async () => ({
+        session: {
+          sessionId: 'session-open',
+          messages: [],
+        },
+      }),
+      getSession: async () => ({
+        session: {
+          sessionId: 'session-restore',
+          messages: [],
+        },
+      }),
+      streamMessage: async () => ({
+        sessionId: 'session-open',
+        messages: [],
+      }),
+      executeAction: async () => ({
+        session: {
+          sessionId: 'session-compile',
+          messages: [],
+        },
+      }),
+      selectSession: (response) => response.session,
+    },
+    createPayload: {},
+    workspaceStage: 'match3d-agent-workspace',
+    resultStage: 'match3d-result',
+    platformStage: 'platform',
+    isCompileAction: () => false,
+    resolveErrorMessage: (error, fallback) =>
+      error instanceof Error ? error.message : fallback,
+    errorMessages: {
+      open: '打开失败',
+      restoreMissingSession: '缺少会话',
+      restore: '恢复失败',
+      submit: '发送失败',
+      execute: '执行失败',
+    },
+    enterCreateTab: () => {},
+    setSelectionStage: () => {},
+    onSessionChanged: () => {},
+  });
+
+  useEffect(() => {
+    onSetterIdentity(flow.setSession);
+  });
+
+  return (
+    <button
+      type="button"
+      onClick={() => setRenderCount((current) => current + 1)}
+    >
+      重渲染 {renderCount}
+    </button>
+  );
+}
+
 test('creation agent flow preserves streamed assistant text when stream fails', async () => {
   const streamMessage = vi.fn(async (_sessionId, _payload, options) => {
     options?.onUpdate?.('先把方洞万能的反差定住。');
@@ -391,3 +546,48 @@ test('creation agent flow suppresses compile result stage for background complet
     'match3d-agent-workspace',
   );
 });
+
+test('creation agent flow notifies session changes after open restore and compile', async () => {
+  const onSessionChanged = vi.fn();
+
+  render(<SessionChangeHarness onSessionChanged={onSessionChanged} />);
+
+  await act(async () => {
+    screen.getByRole('button', { name: '打开' }).click();
+  });
+  await act(async () => {
+    screen.getByRole('button', { name: '恢复' }).click();
+  });
+  await act(async () => {
+    screen.getByRole('button', { name: '编译' }).click();
+  });
+
+  await waitFor(() => {
+    expect(onSessionChanged).toHaveBeenCalledTimes(3);
+  });
+
+  expect(
+    onSessionChanged.mock.calls.map(([session]) => session?.sessionId),
+  ).toEqual(['session-open', 'session-restore', 'session-compile']);
+});
+
+test('creation agent flow keeps session setter stable across parent rerenders', async () => {
+  const onSetterIdentity = vi.fn();
+
+  render(<SessionSetterIdentityHarness onSetterIdentity={onSetterIdentity} />);
+
+  await waitFor(() => {
+    expect(onSetterIdentity).toHaveBeenCalledTimes(1);
+  });
+  const initialSetter = onSetterIdentity.mock.calls[0]?.[0];
+
+  await act(async () => {
+    screen.getByRole('button', { name: /重渲染/u }).click();
+  });
+
+  await waitFor(() => {
+    expect(onSetterIdentity).toHaveBeenCalledTimes(2);
+  });
+
+  expect(onSetterIdentity.mock.calls[1]?.[0]).toBe(initialSetter);
+});

src/components/platform-entry/usePlatformCreationAgentFlowController.ts

@@ -1,4 +1,5 @@
-import { useCallback, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { Dispatch, SetStateAction } from 'react';
 
 import type { TextStreamOptions } from '../../services/aiTypes';
 import type { SelectionStage } from './platformEntryTypes';
@@ -75,12 +76,13 @@ type PlatformCreationAgentFlowControllerOptions<
   enterCreateTab: () => void;
   setSelectionStage: (stage: SelectionStage) => void;
   onSessionOpened?: () => void;
+  onSessionChanged?: (session: TSession | null) => void;
   onOpenError?: (params: { error: unknown; errorMessage: string }) => void;
   onActionComplete?: (params: {
     payload: TActionPayload;
     response: TActionResponse;
     session: TSession;
-    setSession: (session: TSession) => void;
+    setSession: Dispatch<SetStateAction<TSession | null>>;
   }) =>
     | Promise<{ openResult?: boolean } | void>
     | { openResult?: boolean }
@@ -94,7 +96,7 @@ type PlatformCreationAgentFlowControllerOptions<
     error: unknown;
     errorMessage: string;
     session: TSession;
-    setSession: (session: TSession) => void;
+    setSession: Dispatch<SetStateAction<TSession | null>>;
   }) => void | Promise<void>;
 };
 
@@ -141,12 +143,27 @@ export function usePlatformCreationAgentFlowController<
     TActionResponse
   >,
 ) {
-  const [session, setSession] = useState<TSession | null>(null);
+  const [session, rawSetSession] = useState<TSession | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [isBusy, setIsBusy] = useState(false);
   const [streamingReplyText, setStreamingReplyText] = useState('');
   const [isStreamingReply, setIsStreamingReply] = useState(false);
   const latestStreamingReplyTextRef = useRef('');
+  const onSessionChangedRef = useRef(options.onSessionChanged);
+
+  useEffect(() => {
+    onSessionChangedRef.current = options.onSessionChanged;
+  }, [options.onSessionChanged]);
+
+  const setSession = useCallback(
+    (nextSessionOrUpdater: SetStateAction<TSession | null>) => {
+      rawSetSession(nextSessionOrUpdater);
+      if (typeof nextSessionOrUpdater !== 'function') {
+        onSessionChangedRef.current?.(nextSessionOrUpdater);
+      }
+    },
+    [],
+  );
 
   const updateStreamingReplyText = useCallback((text: string) => {
     latestStreamingReplyTextRef.current = text;
@@ -174,10 +191,10 @@ export function usePlatformCreationAgentFlowController<
           createPayload ?? options.createPayload,
         );
         const nextSession = options.client.selectSession(response);
-        setSession(nextSession);
         options.enterCreateTab();
         options.onSessionOpened?.();
         options.setSelectionStage(options.workspaceStage);
+        setSession(nextSession);
         return nextSession;
       } catch (caughtError) {
         const errorMessage = options.resolveErrorMessage(
@@ -212,11 +229,11 @@ export function usePlatformCreationAgentFlowController<
       try {
         const response = await options.client.getSession(normalizedSessionId);
         const nextSession = options.client.selectSession(response);
-        setSession(nextSession);
         options.enterCreateTab();
         options.setSelectionStage(
           nextSession.draft ? options.resultStage : options.workspaceStage,
         );
+        setSession(nextSession);
         return nextSession;
       } catch (caughtError) {
         setError(

src/routing/appPageRoutes.test.ts

@@ -1,6 +1,9 @@
+/* @vitest-environment jsdom */
+
 import { describe, expect, it } from 'vitest';
 
 import {
+  pushAppHistoryPath,
   resolvePathForSelectionStage,
   resolveSelectionStageFromPath,
 } from './appPageRoutes';
@@ -117,4 +120,43 @@ describe('appPageRoutes', () => {
       '/creation/baby-object-match',
     );
   });
+
+  it('preserves creation restore query params within the same creation flow', () => {
+    window.history.replaceState(
+      null,
+      '',
+      '/creation/rpg?sessionId=session-1&profileId=profile-1&draftId=draft-1&workId=work-1&clientRuntime=wechat_mini_program',
+    );
+
+    pushAppHistoryPath('/creation/rpg/result');
+
+    expect(window.location.pathname).toBe('/creation/rpg/result');
+    expect(window.location.search).toBe(
+      '?sessionId=session-1&profileId=profile-1&draftId=draft-1&workId=work-1',
+    );
+  });
+
+  it('clears creation restore query params when leaving the flow or switching flows', () => {
+    window.history.replaceState(
+      null,
+      '',
+      '/creation/rpg?sessionId=session-1&profileId=profile-1',
+    );
+
+    pushAppHistoryPath('/creation/puzzle');
+
+    expect(window.location.pathname).toBe('/creation/puzzle');
+    expect(window.location.search).toBe('');
+
+    window.history.replaceState(
+      null,
+      '',
+      '/creation/rpg?sessionId=session-2&profileId=profile-2',
+    );
+
+    pushAppHistoryPath('/');
+
+    expect(window.location.pathname).toBe('/');
+    expect(window.location.search).toBe('');
+  });
 });

src/routing/appPageRoutes.ts

@@ -1,4 +1,9 @@
 import type { SelectionStage } from '../components/platform-entry';
+import {
+  buildCreationUrlSearchFromParams,
+  isCreationRestorePath,
+  isSameCreationFlowPath,
+} from '../services/creationUrlState';
 
 export type RuntimePageRoute = 'rpg-character-select' | 'rpg-adventure';
 
@@ -130,7 +135,14 @@ export function isKnownMainAppPagePath(pathname: string) {
 export function pushAppHistoryPath(path: string) {
   const nextUrl = new URL(path, window.location.origin);
   const normalizedPath = normalizeAppPath(nextUrl.pathname);
-  const nextRelativeUrl = `${normalizedPath}${nextUrl.search}`;
+  const nextSearch =
+    nextUrl.search ||
+    buildPreservedAppSearch(
+      window.location.pathname,
+      normalizedPath,
+      window.location.search,
+    );
+  const nextRelativeUrl = `${normalizedPath}${nextSearch}`;
   const currentRelativeUrl = `${normalizeAppPath(window.location.pathname)}${window.location.search}`;
   if (currentRelativeUrl === nextRelativeUrl) {
     return;
@@ -139,3 +151,18 @@ export function pushAppHistoryPath(path: string) {
   // 页面阶段变化是用户可感知导航，写入 history 以支持前进后退。
   window.history.pushState(null, '', nextRelativeUrl);
 }
+
+function buildPreservedAppSearch(
+  currentPathname: string,
+  normalizedPath: string,
+  search: string,
+) {
+  if (
+    !isCreationRestorePath(normalizedPath) ||
+    !isSameCreationFlowPath(currentPathname, normalizedPath)
+  ) {
+    return '';
+  }
+
+  return buildCreationUrlSearchFromParams(search);
+}

src/services/creationUrlState.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  clearCreationUrlState,
+  readCreationUrlState,
+  writeCreationUrlState,
+} from './creationUrlState';
+
+describe('creationUrlState', () => {
+  it('writes and reads restore state on creation restore paths', () => {
+    const replaceState = vi.fn();
+    const env = {
+      location: {
+        pathname: '/creation/puzzle/result',
+        search: '?clientRuntime=wechat_mini_program',
+      },
+      history: { replaceState },
+    };
+
+    writeCreationUrlState(
+      {
+        sessionId: ' session-1 ',
+        profileId: 'profile-1',
+        draftId: 'draft-1',
+        workId: 'work-1',
+      },
+      env,
+    );
+
+    expect(replaceState).toHaveBeenCalledWith(
+      null,
+      '',
+      '/creation/puzzle/result?clientRuntime=wechat_mini_program&sessionId=session-1&profileId=profile-1&draftId=draft-1&workId=work-1',
+    );
+    expect(
+      readCreationUrlState({
+        location: {
+          pathname: '/creation/puzzle/result',
+          search:
+            '?sessionId=session-1&profileId=profile-1&draftId=draft-1&workId=work-1',
+        },
+      }),
+    ).toEqual({
+      sessionId: 'session-1',
+      profileId: 'profile-1',
+      draftId: 'draft-1',
+      workId: 'work-1',
+    });
+  });
+
+  it('ignores writes and clears outside creation restore paths', () => {
+    const replaceState = vi.fn();
+    const env = {
+      location: {
+        pathname: '/works/detail',
+        search: '?work=PZ-123&sessionId=session-1',
+      },
+      history: { replaceState },
+    };
+
+    writeCreationUrlState({ sessionId: 'session-2' }, env);
+    clearCreationUrlState(env);
+
+    expect(replaceState).not.toHaveBeenCalled();
+  });
+
+  it('clears only private restore params on creation restore paths', () => {
+    const replaceState = vi.fn();
+    const env = {
+      location: {
+        pathname: '/creation/bark-battle/result',
+        search: '?draftId=draft-1&workId=work-1&clientRuntime=wechat',
+      },
+      history: { replaceState },
+    };
+
+    clearCreationUrlState(env);
+
+    expect(replaceState).toHaveBeenCalledWith(
+      null,
+      '',
+      '/creation/bark-battle/result?clientRuntime=wechat',
+    );
+  });
+});

src/services/creationUrlState.ts

@@ -0,0 +1,220 @@
+import {
+  CUSTOM_WORLD_AGENT_OPERATION_QUERY_KEY,
+  CUSTOM_WORLD_AGENT_SESSION_QUERY_KEY,
+  CUSTOM_WORLD_GENERATION_SOURCE_QUERY_KEY,
+} from './customWorldAgentUiState';
+
+export const CREATION_URL_SESSION_QUERY_KEY = 'sessionId';
+export const CREATION_URL_PROFILE_QUERY_KEY = 'profileId';
+export const CREATION_URL_DRAFT_QUERY_KEY = 'draftId';
+export const CREATION_URL_WORK_QUERY_KEY = 'workId';
+
+export const CREATION_URL_RESTORE_QUERY_KEYS = [
+  CUSTOM_WORLD_AGENT_SESSION_QUERY_KEY,
+  CUSTOM_WORLD_AGENT_OPERATION_QUERY_KEY,
+  CUSTOM_WORLD_GENERATION_SOURCE_QUERY_KEY,
+  CREATION_URL_SESSION_QUERY_KEY,
+  CREATION_URL_PROFILE_QUERY_KEY,
+  CREATION_URL_DRAFT_QUERY_KEY,
+  CREATION_URL_WORK_QUERY_KEY,
+] as const;
+
+export type CreationUrlState = {
+  sessionId?: string | null;
+  profileId?: string | null;
+  draftId?: string | null;
+  workId?: string | null;
+};
+
+type CreationUrlEnvironment = {
+  location?: {
+    pathname: string;
+    search: string;
+  } | null;
+  history?: {
+    replaceState: (
+      data: unknown,
+      unused: string,
+      url?: string | URL | null,
+    ) => void;
+  } | null;
+};
+
+const CREATION_PATH_PREFIXES = [
+  '/creation/rpg',
+  '/creation/big-fish',
+  '/creation/match3d',
+  '/creation/square-hole',
+  '/creation/jump-hop',
+  '/creation/wooden-fish',
+  '/creation/bark-battle',
+  '/creation/visual-novel',
+  '/creation/baby-object-match',
+  '/creation/puzzle',
+] as const;
+
+function resolveEnvironment(
+  env?: CreationUrlEnvironment,
+): Required<CreationUrlEnvironment> {
+  if (env) {
+    return {
+      location: env.location ?? null,
+      history: env.history ?? null,
+    };
+  }
+
+  if (typeof window === 'undefined') {
+    return {
+      location: null,
+      history: null,
+    };
+  }
+
+  return {
+    location: window.location,
+    history: window.history,
+  };
+}
+
+function normalizeValue(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function normalizePathname(value: string | undefined) {
+  const pathname = value?.trim().toLowerCase() ?? '';
+  if (!pathname || pathname === '/') {
+    return '/';
+  }
+
+  return pathname.replace(/\/+$/u, '');
+}
+
+export function isCreationRestorePath(pathname: string | undefined) {
+  const normalizedPathname = normalizePathname(pathname);
+  return CREATION_PATH_PREFIXES.some(
+    (pathPrefix) =>
+      normalizedPathname === pathPrefix ||
+      normalizedPathname.startsWith(`${pathPrefix}/`),
+  );
+}
+
+export function isSameCreationFlowPath(
+  currentPathname: string | undefined,
+  nextPathname: string | undefined,
+) {
+  const normalizedCurrentPath = normalizePathname(currentPathname);
+  const normalizedNextPath = normalizePathname(nextPathname);
+  if (
+    !normalizedCurrentPath ||
+    !normalizedNextPath ||
+    normalizedCurrentPath === '/' ||
+    normalizedNextPath === '/'
+  ) {
+    return false;
+  }
+
+  const currentCreationPrefix = CREATION_PATH_PREFIXES.find((pathPrefix) =>
+    normalizedCurrentPath === pathPrefix ||
+    normalizedCurrentPath.startsWith(`${pathPrefix}/`),
+  );
+  const nextCreationPrefix = CREATION_PATH_PREFIXES.find((pathPrefix) =>
+    normalizedNextPath === pathPrefix ||
+    normalizedNextPath.startsWith(`${pathPrefix}/`),
+  );
+  return Boolean(
+    currentCreationPrefix &&
+      nextCreationPrefix &&
+      currentCreationPrefix === nextCreationPrefix,
+  );
+}
+
+export function buildCreationUrlSearchFromParams(search: string) {
+  const params = new URLSearchParams(search);
+  const preservedParams = new URLSearchParams();
+
+  CREATION_URL_RESTORE_QUERY_KEYS.forEach((key) => {
+    const value = normalizeValue(params.get(key));
+    if (value) {
+      preservedParams.set(key, value);
+    }
+  });
+
+  const queryString = preservedParams.toString();
+  return queryString ? `?${queryString}` : '';
+}
+
+export function readCreationUrlState(
+  env?: CreationUrlEnvironment,
+): CreationUrlState {
+  const resolved = resolveEnvironment(env);
+  const params = new URLSearchParams(resolved.location?.search ?? '');
+
+  return {
+    sessionId: normalizeValue(params.get(CREATION_URL_SESSION_QUERY_KEY)),
+    profileId: normalizeValue(params.get(CREATION_URL_PROFILE_QUERY_KEY)),
+    draftId: normalizeValue(params.get(CREATION_URL_DRAFT_QUERY_KEY)),
+    workId: normalizeValue(params.get(CREATION_URL_WORK_QUERY_KEY)),
+  };
+}
+
+export function writeCreationUrlState(
+  state: CreationUrlState,
+  env?: CreationUrlEnvironment,
+) {
+  const resolved = resolveEnvironment(env);
+  if (
+    !resolved.location ||
+    !resolved.history?.replaceState ||
+    !isCreationRestorePath(resolved.location.pathname)
+  ) {
+    return;
+  }
+
+  const params = new URLSearchParams(resolved.location.search);
+  const entries = [
+    [CREATION_URL_SESSION_QUERY_KEY, state.sessionId],
+    [CREATION_URL_PROFILE_QUERY_KEY, state.profileId],
+    [CREATION_URL_DRAFT_QUERY_KEY, state.draftId],
+    [CREATION_URL_WORK_QUERY_KEY, state.workId],
+  ] as const;
+
+  entries.forEach(([key, rawValue]) => {
+    const value = normalizeValue(rawValue);
+    if (value) {
+      params.set(key, value);
+    } else {
+      params.delete(key);
+    }
+  });
+
+  const search = params.toString();
+  const nextUrl = search
+    ? `${resolved.location.pathname}?${search}`
+    : resolved.location.pathname;
+  resolved.history.replaceState(null, '', nextUrl);
+}
+
+export function clearCreationUrlState(env?: CreationUrlEnvironment) {
+  const resolved = resolveEnvironment(env);
+  if (
+    !resolved.location ||
+    !resolved.history?.replaceState ||
+    !isCreationRestorePath(resolved.location.pathname)
+  ) {
+    return;
+  }
+
+  const params = new URLSearchParams(resolved.location.search);
+  [
+    CREATION_URL_SESSION_QUERY_KEY,
+    CREATION_URL_PROFILE_QUERY_KEY,
+    CREATION_URL_DRAFT_QUERY_KEY,
+    CREATION_URL_WORK_QUERY_KEY,
+  ].forEach((key) => params.delete(key));
+
+  const search = params.toString();
+  const nextUrl = search
+    ? `${resolved.location.pathname}?${search}`
+    : resolved.location.pathname;
+  resolved.history.replaceState(null, '', nextUrl);
+}

src/services/puzzleRuntimeUrlState.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  clearPuzzleRuntimeUrlState,
+  readPuzzleRuntimeUrlState,
+  writePuzzleRuntimeUrlState,
+} from './puzzleRuntimeUrlState';
+
+describe('puzzleRuntimeUrlState', () => {
+  it('writes puzzle runtime identity on runtime paths', () => {
+    const replaceState = vi.fn();
+    const env = {
+      location: {
+        pathname: '/runtime/puzzle',
+        search: '?clientRuntime=wechat_mini_program',
+      },
+      history: { replaceState },
+    };
+
+    writePuzzleRuntimeUrlState(
+      {
+        runtimeSessionId: 'puzzle-session-1',
+        runtimeProfileId: 'puzzle-profile-1',
+        runtimeLevelId: 'puzzle-level-2',
+        publicWorkCode: 'PZ-12345678',
+        mode: 'draft',
+      },
+      env,
+    );
+
+    expect(replaceState).toHaveBeenCalledWith(
+      null,
+      '',
+      '/runtime/puzzle?clientRuntime=wechat_mini_program&runtimeProfileId=puzzle-profile-1&runtimeSessionId=puzzle-session-1&runtimeLevelId=puzzle-level-2&work=PZ-12345678&mode=draft',
+    );
+    expect(
+      readPuzzleRuntimeUrlState({
+        location: {
+          pathname: '/runtime/puzzle',
+          search:
+            '?runtimeProfileId=puzzle-profile-1&runtimeSessionId=puzzle-session-1&runtimeLevelId=puzzle-level-2&work=PZ-12345678&mode=draft',
+        },
+      }),
+    ).toEqual({
+      runtimeProfileId: 'puzzle-profile-1',
+      runtimeSessionId: 'puzzle-session-1',
+      runtimeLevelId: 'puzzle-level-2',
+      publicWorkCode: 'PZ-12345678',
+      mode: 'draft',
+    });
+  });
+
+  it('ignores writes outside puzzle runtime paths', () => {
+    const replaceState = vi.fn();
+    const env = {
+      location: {
+        pathname: '/creation/puzzle/result',
+        search: '?sessionId=puzzle-session-1',
+      },
+      history: { replaceState },
+    };
+
+    writePuzzleRuntimeUrlState({ runtimeSessionId: 'puzzle-session-2' }, env);
+
+    expect(replaceState).not.toHaveBeenCalled();
+  });
+
+  it('can write runtime state to an explicit puzzle runtime pathname', () => {
+    const replaceState = vi.fn();
+    const env = {
+      location: {
+        pathname: '/creation/puzzle/result',
+        search: '?clientRuntime=wechat_mini_program',
+      },
+      history: { replaceState },
+    };
+
+    writePuzzleRuntimeUrlState(
+      {
+        runtimeProfileId: 'puzzle-profile-1',
+        mode: 'published',
+        publicWorkCode: 'PZ-12345678',
+      },
+      env,
+      { pathname: '/runtime/puzzle' },
+    );
+
+    expect(replaceState).toHaveBeenCalledWith(
+      null,
+      '',
+      '/runtime/puzzle?clientRuntime=wechat_mini_program&runtimeProfileId=puzzle-profile-1&work=PZ-12345678&mode=published',
+    );
+  });
+
+  it('clears only puzzle runtime restore params on runtime paths', () => {
+    const replaceState = vi.fn();
+    const env = {
+      location: {
+        pathname: '/runtime/puzzle',
+        search:
+          '?runtimeSessionId=puzzle-session-1&runtimeProfileId=puzzle-profile-1&runtimeLevelId=puzzle-level-1&work=PZ-12345678&mode=draft&clientRuntime=wechat',
+      },
+      history: { replaceState },
+    };
+
+    clearPuzzleRuntimeUrlState(env);
+
+    expect(replaceState).toHaveBeenCalledWith(
+      null,
+      '',
+      '/runtime/puzzle?clientRuntime=wechat',
+    );
+  });
+});

src/services/puzzleRuntimeUrlState.ts

@@ -0,0 +1,155 @@
+export const PUZZLE_RUNTIME_WORK_QUERY_KEY = 'work';
+export const PUZZLE_RUNTIME_PROFILE_QUERY_KEY = 'runtimeProfileId';
+export const PUZZLE_RUNTIME_SESSION_QUERY_KEY = 'runtimeSessionId';
+export const PUZZLE_RUNTIME_LEVEL_QUERY_KEY = 'runtimeLevelId';
+export const PUZZLE_RUNTIME_MODE_QUERY_KEY = 'mode';
+
+export type PuzzleRuntimeUrlMode = 'draft' | 'published';
+
+export type PuzzleRuntimeUrlState = {
+  runtimeProfileId?: string | null;
+  runtimeSessionId?: string | null;
+  runtimeLevelId?: string | null;
+  publicWorkCode?: string | null;
+  mode?: PuzzleRuntimeUrlMode | null;
+};
+
+type PuzzleRuntimeUrlEnvironment = {
+  location?: {
+    pathname: string;
+    search: string;
+  } | null;
+  history?: {
+    replaceState: (
+      data: unknown,
+      unused: string,
+      url?: string | URL | null,
+    ) => void;
+  } | null;
+};
+
+type WritePuzzleRuntimeUrlOptions = {
+  pathname?: string;
+};
+
+function resolveEnvironment(
+  env?: PuzzleRuntimeUrlEnvironment,
+): Required<PuzzleRuntimeUrlEnvironment> {
+  if (env) {
+    return {
+      location: env.location ?? null,
+      history: env.history ?? null,
+    };
+  }
+
+  if (typeof window === 'undefined') {
+    return {
+      location: null,
+      history: null,
+    };
+  }
+
+  return {
+    location: window.location,
+    history: window.history,
+  };
+}
+
+function normalizeValue(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function normalizeRuntimeMode(value: unknown): PuzzleRuntimeUrlMode | null {
+  const normalized = normalizeValue(value);
+  return normalized === 'draft' || normalized === 'published'
+    ? normalized
+    : null;
+}
+
+function isPuzzleRuntimePath(pathname: string | undefined) {
+  return pathname?.trim().toLowerCase().replace(/\/+$/u, '') === '/runtime/puzzle';
+}
+
+export function readPuzzleRuntimeUrlState(
+  env?: PuzzleRuntimeUrlEnvironment,
+): PuzzleRuntimeUrlState {
+  const resolved = resolveEnvironment(env);
+  const params = new URLSearchParams(resolved.location?.search ?? '');
+
+  return {
+    runtimeProfileId: normalizeValue(
+      params.get(PUZZLE_RUNTIME_PROFILE_QUERY_KEY),
+    ),
+    runtimeSessionId: normalizeValue(
+      params.get(PUZZLE_RUNTIME_SESSION_QUERY_KEY),
+    ),
+    runtimeLevelId: normalizeValue(params.get(PUZZLE_RUNTIME_LEVEL_QUERY_KEY)),
+    publicWorkCode: normalizeValue(params.get(PUZZLE_RUNTIME_WORK_QUERY_KEY)),
+    mode: normalizeRuntimeMode(params.get(PUZZLE_RUNTIME_MODE_QUERY_KEY)),
+  };
+}
+
+export function writePuzzleRuntimeUrlState(
+  state: PuzzleRuntimeUrlState,
+  env?: PuzzleRuntimeUrlEnvironment,
+  options: WritePuzzleRuntimeUrlOptions = {},
+) {
+  const resolved = resolveEnvironment(env);
+  const pathname = options.pathname ?? resolved.location?.pathname;
+  if (
+    !resolved.location ||
+    !resolved.history?.replaceState ||
+    !isPuzzleRuntimePath(pathname)
+  ) {
+    return;
+  }
+
+  const params = new URLSearchParams(resolved.location.search);
+  const entries = [
+    [PUZZLE_RUNTIME_PROFILE_QUERY_KEY, state.runtimeProfileId],
+    [PUZZLE_RUNTIME_SESSION_QUERY_KEY, state.runtimeSessionId],
+    [PUZZLE_RUNTIME_LEVEL_QUERY_KEY, state.runtimeLevelId],
+    [PUZZLE_RUNTIME_WORK_QUERY_KEY, state.publicWorkCode],
+    [PUZZLE_RUNTIME_MODE_QUERY_KEY, state.mode],
+  ] as const;
+
+  entries.forEach(([key, rawValue]) => {
+    const value = normalizeValue(rawValue);
+    if (value) {
+      params.set(key, value);
+    } else {
+      params.delete(key);
+    }
+  });
+
+  const search = params.toString();
+  const nextPathname = pathname ?? resolved.location.pathname;
+  const nextUrl = search ? `${nextPathname}?${search}` : nextPathname;
+  resolved.history.replaceState(null, '', nextUrl);
+}
+
+export function clearPuzzleRuntimeUrlState(env?: PuzzleRuntimeUrlEnvironment) {
+  const resolved = resolveEnvironment(env);
+  if (
+    !resolved.location ||
+    !resolved.history?.replaceState ||
+    !isPuzzleRuntimePath(resolved.location.pathname)
+  ) {
+    return;
+  }
+
+  const params = new URLSearchParams(resolved.location.search);
+  [
+    PUZZLE_RUNTIME_PROFILE_QUERY_KEY,
+    PUZZLE_RUNTIME_SESSION_QUERY_KEY,
+    PUZZLE_RUNTIME_LEVEL_QUERY_KEY,
+    PUZZLE_RUNTIME_WORK_QUERY_KEY,
+    PUZZLE_RUNTIME_MODE_QUERY_KEY,
+  ].forEach((key) => params.delete(key));
+
+  const search = params.toString();
+  const nextUrl = search
+    ? `${resolved.location.pathname}?${search}`
+    : resolved.location.pathname;
+  resolved.history.replaceState(null, '', nextUrl);
+}