合并 master 并修复架构分支回归

合入 master 最新的认证、玩法契约与推荐页改动。

修复拼图草稿生成、推荐页下一关和公开详情访客试玩回归。

修复抓大鹅草稿试玩鉴权与首屏推荐详情测试入口。

补齐相关测试夹具、文档与团队记忆更新。

.hermes/shared-memory/pitfalls.md

@@ -31,6 +31,22 @@
 - 验证：触发任一平台级异步失败时，页面应出现包含“错误来源”和“错误内容”的弹窗；复制内容应包含来源和错误正文；旧页面内错误 banner 不再重复出现。
 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformErrorDialog.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 自定义世界旧公开作品不要用 published_at 判断是否存在
+
+- 现象：RPG / 自定义世界作品详情能打开，但点赞时报 `custom_world 已发布作品不存在，无法点赞`，错误来源是 `作品详情 CW-*` 或其它自定义世界历史公开号。
+- 原因：部分历史 `custom_world_profile` 已是 `publication_status=Published`，但 `published_at` 为空；统一公开详情会用 `updated_at` 兜底展示，旧点赞 / 游玩 / Remix 判断却额外要求 `published_at.is_some()`。
+- 处理：公开互动存在性统一按 `Published + deleted_at=None + visible=true` 判断；`custom_world_gallery_entry` 同步和公开展示时间在 `published_at` 缺失时回退 `updated_at`。
+- 验证：`cargo test -p spacetime-module custom_world_public_interactions_accept_legacy_missing_published_at --manifest-path server-rs/Cargo.toml`。
+- 关联：`server-rs/crates/spacetime-module/src/custom_world.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`。
+
+## 推荐页 WF 点赞不要落到 RPG / custom-world
+
+- 现象：推荐页里给 `WF-*` 敲木鱼作品点赞时，平台错误弹窗显示 `custom_world 已发布作品不存在，无法点赞`。
+- 原因：推荐页点赞统一走 `likePublicWork`，但敲木鱼尚未接入点赞后端；缺少 `wooden-fish` 分支时会落入默认 RPG / custom-world 点赞路径，把敲木鱼的 owner/profile 传给 custom-world reducer。
+- 处理：所有公开作品互动必须先按 `packages/shared/src/contracts/playTypes.ts` 中的全局 `sourceType` 分流；暂未接入点赞的玩法直接报“该作品类型暂不支持点赞”，禁止显示开放兜底文案，也禁止用默认 RPG / custom-world 分支兜底。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation wooden fish like does not call RPG gallery like"`。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。
+
 ## 暗色创作进度卡不要被 platform-remap-surface 改成深色文字
 
 - 现象：统一创作页里的暗色进度卡背景是深绿 / 深蓝，但“创作进度”、百分比和进度提示显示成深色，移动端几乎看不清。
@@ -1238,8 +1254,8 @@
 - 后续更新：该条仍适用于常规构建 / 发布流水线；`Genarrative-Server-Provision` 已在 2026-06-05 改为服务器初始化专用口径，不允许公网 Git fallback，Job 的 `Pipeline script from SCM` 和 Jenkinsfile 内部 checkout 都必须使用本机路径或目标 agent 可访问的内网 Git 源。
 - 现象：生产发布、数据库导入导出、服务器配置、构建或 `Genarrative-Full-Build-And-Deploy` 流水线执行 `GitSCM checkout` 时，如果 Jenkins 生成的 fetch 是 `+refs/heads/*:refs/remotes/origin/*`，公网 Git 链路可能在收包阶段以 `git-remote-https died of signal 15`、`curl 56 GnuTLS recv error (-9)`、`early EOF`、`invalid index-pack output` 失败；发布类流水线还可能先遇到 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 不可达。
 - 原因：`127.0.0.1` 只代表当前执行阶段的 agent 自身；当 release agent 与 Git 服务不在同一台机器，或本机 Git/Web 服务临时不可用时，固定写死 localhost 会阻断 Jenkinsfile 内部源码/脚本 checkout。即使只使用域名 Git，如果 `GitSCM` 没有显式 refspec 并开启 `CloneOption honorRefspec=true`，Jenkins Git 插件也会拉取所有分支。
-- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 `linux && genarrative-build` 的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段、`Genarrative-Web-Build` checkout 阶段，以及部署/发布类 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；这些首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，只有指定 commit 时才允许加深历史做分支归属校验。
-- 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有生产 Jenkinsfile 的首次 `GitSCM checkout`，确认 `userRemoteConfigs` 带 `+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}`，`CloneOption` 带 `honorRefspec: true`；运行 `bash -n scripts/jenkins-checkout-source.sh`。
+- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 `linux && genarrative-build` 的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段、`Genarrative-Web-Build` checkout 阶段，以及部署/发布类 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；这些首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，指定 commit 时也先保持 `depth=1` 校验，浅历史无法证明归属时才按 `GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS` 逐步加深，最后才展开完整历史。发布流水线不得为了缩短 checkout 时间清空上游构建传入的 `COMMIT_HASH`。
+- 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有生产 Jenkinsfile 的首次 `GitSCM checkout`，确认 `userRemoteConfigs` 带 `+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}`，`CloneOption` 带 `honorRefspec: true`；扫描发布流水线确认传给 `scripts/jenkins-checkout-source.sh` 的 `COMMIT_HASH` 未被硬编码为空；运行 `bash -n scripts/jenkins-checkout-source.sh`。
 - 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-web-build`、`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-web-deploy`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`jenkins/Jenkinsfile.production-server-provision`、`jenkins/Jenkinsfile.production-database-export`、`jenkins/Jenkinsfile.production-database-import`、`scripts/jenkins-checkout-source.sh`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
 
 ## Jenkins 可选参数在 set -u 下不能裸读
@@ -1532,7 +1548,7 @@
 
 ## 推荐页嵌入拼图通关结算不要放在运行态内部 absolute 层
 
-- 现象：推荐页里玩拼图通关后，结算面板只显示上半部分，排行榜、下一关按钮或相似作品卡被截断。
+- 现象：推荐页里玩拼图通关后，结算面板只显示上半部分，排行榜或下一关按钮被截断。
 - 原因：推荐页把运行态放在滑动作品卡的视觉区内，`platform-recommend-swipe-page`、`platform-recommend-swipe-card__visual` 和 `platform-recommend-runtime-viewport` 都是 `overflow: hidden`；拼图通关结算如果仍是运行态内部 `absolute inset-0` 弹层，就只能在半屏卡片区域里显示。
 - 处理：`PuzzleRuntimeShell` 在 `embedded` 模式下把通关结算层通过 portal 挂到 `document.body`，使用 `puzzle-runtime-modal-overlay--fixed` 页面级 fixed 浮层；非嵌入态继续使用运行态内部覆盖层。
 - 验证：运行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx -t "推荐页嵌入拼图通关结算使用页面级浮层避免卡片裁剪"`，确认弹层不再位于 `.platform-recommend-runtime-viewport` 内。
@@ -2051,6 +2067,14 @@
 - 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle draft generation auto starts trial and runtime back opens draft result"`。
 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 拼图文字直创的 compile 回包不等于生成完成
+
+- 现象：只输入文字点击生成拼图时，页面刚进入生成页就弹出“生成任务已完成，可以继续查看草稿。”，随后又提示“请先选择一张正式拼图图片。”，结果页关卡里也没有图。
+- 原因：统一创作表单路径把 `compile_puzzle_draft` 的同步回包无条件当成 ready；但后端在 AI 重绘路径会先返回 `stage=image_refining`、`progressPercent=88` 的会话，只表示首关草稿已编译且后台首图 / UI 资产任务已启动，还没有正式封面或候选图。
+- 处理：前端必须继续用 `isPuzzleCompileActionReady(...)` 判断回包 session；没有 `draft.coverImageSrc`、首关 `coverImageSrc` 或候选图时保持生成中，不弹完成、不把作品架 pending 标 ready、不自动试玩。生成页轮询合并 session 进度时，未进入编译态或进度无变化就返回原 state，避免轮询制造重复 render。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle text-only form stays generating|puzzle draft generation auto starts trial|running puzzle draft opens generation progress"`。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## CreativeImageInputPanel 主图点击默认预览
 
 - 现象：复用 `CreativeImageInputPanel` 的结果页 / 编辑页已有主图时，用户点击图片却触发上传，无法直接查看大图；不同玩法若各自手写上传按钮会让主图、历史图、AI 重绘和参考图行为再次分叉。
@@ -2058,3 +2082,11 @@
 - 处理：通用面板已有主图时默认点击主图打开全屏预览，上传 / 更换收口到右下角 `ImagePlus` 图标按钮；无图时仍允许点击空图卡上传。调用方用 `canUploadMainImage` 和 `canUseImageHistory` 分别控制上传与历史按钮，不要复制面板或用样式遮挡按钮。
 - 验证：`npm run test -- src/components/common/CreativeImageInputPanel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
 - 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 统一创作页短表单软键盘打开不要露出黑底
+
+- 现象：小程序 / H5 移动端点击拼图或敲木鱼创作输入框后，输入框和键盘之间出现一大片黑色区域；H5 还会明显弹一下。跳一跳因为按钮区用 `mt-auto` 撑开页面，看起来没有同样问题。
+- 原因：旧移动键盘处理会用 `--platform-keyboard-focus-offset` 把 `.platform-viewport-shell` 整体上移；但 H5 浏览器和小程序 `web-view` 已会自行处理输入框可见性，二次整体上移会造成页面弹跳并露出 `body` 或原生 `page` 的黑色宿主底色。统一创作短表单若内容区按短内容收缩，也会放大这个黑底暴露。
+- 处理：`UnifiedCreationPage` 根容器必须保留 `bg-[image:var(--platform-body-fill)]` 和 `overscroll-contain`，内容区必须用 `flex-1 min-h-0` 占满统一页剩余高度；移动端键盘打开时只记录 `data-mobile-keyboard-open`、隐藏底部 dock、设置键盘 inset 和浅色 `--platform-keyboard-exposed-fill`，不要再对 `.platform-viewport-shell` 做全局 `transform`；小程序 `pages/web-view` 的 `page` 和 web-view class 也要用浅色背景。不要只给某个玩法工作台单独加高度补丁。
+- 验证：`npm run test -- src/components/unified-creation/UnifiedCreationPage.test.tsx src/components/unified-creation/UnifiedCreationWorkspace.test.tsx src/mobileViewportKeyboardFocus.test.ts src/index.test.ts miniprogram/pages/web-view/index.style.test.js`；移动端点击拼图、敲木鱼、跳一跳输入框时，页面不应整体弹起，键盘上方应持续显示平台浅色背景。
+- 关联：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/mobileViewportKeyboardFocus.ts`、`src/index.css`、`miniprogram/pages/web-view/index.wxml`、`miniprogram/pages/web-view/index.wxss`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

.hermes/shared-memory/team-conventions.md

@@ -56,7 +56,7 @@
 3. 新增或沉淀 Markdown 文档时，确认文件名已使用 `【标签名】` 前缀。
 4. 若产生长期有效知识，更新 `.hermes/shared-memory/`。
 5. 若形成可复用流程，考虑沉淀到 `.hermes/skills/`。
-6. 在提交信息中区分代码变更与文档/记忆变更。
+6. 提交代码时，提交标题使用中文；标题后逐行写明本次提交修改了什么，每条变更单独一行。
 
 ## 文档阅读顺序
 

AGENTS.md

@@ -43,6 +43,7 @@ Single-context layout: read root `CONTEXT.md` when present. Current architecture
 - UI面板中不要默认写一些规则描述文案，清爽一些，按照游戏UI设计规范设计即可。
 - UI设计需要兼顾网页端、移动端双端的使用体验，确保在不同设备上都能正常显示和操作，移动端优先考虑。
 - 不要在gitignore中添加.env.local文件。
+- 提交代码时，提交标题必须使用中文；标题后必须逐行写明本次提交修改了什么，每条变更单独一行。
 - 严格遵循简洁的代码风格
 - 请默认保持系统的简洁性，能复用、修改、扩展现有系统、页面就不新建新系统新页面。
 - 禁止将功能说明描述类的文本默认写入UI界面中。

apps/admin-web/src/pages/AdminCreationEntrySwitchPage.test.tsx

@@ -27,7 +27,7 @@ vi.mock('../api/adminApiClient', () => ({
 
 const puzzleSpec: UnifiedCreationSpecPayload = {
   playId: 'puzzle',
-  title: '想做个什么玩法？',
+  title: '拼图',
   workspaceStage: 'puzzle-agent-workspace',
   generationStage: 'puzzle-generating',
   resultStage: 'puzzle-result',
@@ -88,6 +88,9 @@ test('创作入口后台展示并保存统一创作契约', async () => {
 
   await screen.findByText('pictureDescription');
   expect(container.querySelector('.admin-subsection .admin-info-list')).not.toBeNull();
+  expect(
+    container.querySelector('.admin-subsection .admin-info-list')?.textContent,
+  ).toContain('拼图');
   expect(container.querySelector('.admin-panel .admin-panel')).toBeNull();
   expect(container.querySelector('.admin-muted')).toBeNull();
 

apps/admin-web/src/pages/AdminCreationEntrySwitchPage.tsx

@@ -707,6 +707,10 @@ function UnifiedCreationSpecSummary({specJson}: {specJson: string}) {
         <dt>玩法</dt>
         <dd>{parsed.spec.playId}</dd>
       </div>
+      <div>
+        <dt>表头</dt>
+        <dd>{parsed.spec.title}</dd>
+      </div>
       <div>
         <dt>阶段</dt>
         <dd>

apps/admin-web/src/pages/AdminWorkVisibilityPage.tsx

@@ -16,6 +16,7 @@ interface AdminWorkVisibilityPageProps {
 
 const sourceLabels: Record<string, string> = {
   puzzle: '拼图',
+  'puzzle-clear': '拼消消',
   'custom-world': '自定义世界',
   'jump-hop': '跳一跳',
   'wooden-fish': '敲木鱼',

docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md

@@ -135,11 +135,13 @@ successfulJumpCount desc -> durationMs asc -> updatedAt asc
 展示字段：
 
 1. rank；
-2. playerId；
+2. displayName；
 3. successfulJumpCount；
 4. durationMs；
 5. updatedAt。
 
+排行榜 UI 禁止展示 `user_id` / `playerId` 这类内部身份键。后端可以继续用 `playerId` 做作品维度最佳成绩去重和 `viewerBest` 匹配，但 HTTP 响应必须补齐 `displayName`；已登录用户读取账号 `displayName`，匿名游客展示为“游客玩家”，账号失效或无法解析时展示为“失效玩家”。
+
 草稿试玩可以展示本地结果，但正式排行榜只消费后端 run 记录。匿名 runtime guest 也按 guest subject 作为 playerId 参与当次作品维度排行。
 
 ## 8. 结果页

docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md

@@ -50,7 +50,7 @@
 - `GET /admin/api/works/visibility`
 - `POST /admin/api/works/visibility`
 
-后台操作 key 使用统一的 `sourceType + profileId` 组合。`profileId` 在大多数玩法中对应作品 profile；特殊玩法维持既有源表身份：`big-fish` 对应 `session_id`，`bark-battle` 对应 `work_id`。`custom-world` 更新源表时必须同步 `custom_world_gallery_entry.visible`，避免兼容 gallery 缓存与统一公开 read model 出现可见性漂移。
+后台操作 key 使用统一的 `sourceType + profileId` 组合。当前后端统一可见性管理覆盖 `puzzle`、`puzzle-clear`、`custom-world`、`jump-hop`、`wooden-fish`、`match3d`、`square-hole`、`visual-novel`、`big-fish` 和 `bark-battle`；`edutainment` 当前没有后端统一作品源表，暂不接入该后台能力。`profileId` 在大多数玩法中对应作品 profile；特殊玩法维持既有源表身份：`big-fish` 对应 `session_id`，`bark-battle` 对应 `work_id`。`custom-world` 更新源表时必须同步 `custom_world_gallery_entry.visible`，避免兼容 gallery 缓存与统一公开 read model 出现可见性漂移。
 
 该后台能力只修改源表 / source view 过滤事实，不把 `visible` 暴露到公开列表或公开详情契约。隐藏作品后，统一 `public_work_gallery_entry` 与 `public_work_detail_entry` 不再返回该作品；恢复显示后重新进入公开 read model。
 
@@ -77,6 +77,7 @@
 - 旧 view 退到底层 source / 兼容职责。
 - 新 `public_work_*` view 是 `api-server` 公开列表 / 详情的统一主读模型。
 - 各玩法 source view 只暴露 `visible=true` 的已发布作品；旧数据迁移默认补 `visible=true`，避免历史作品被误隐藏。
+- RPG / 自定义世界旧数据可能缺少 `published_at`。统一公开详情可以用 `updated_at` 作为展示和排序兜底；点赞、游玩、Remix 等写入路径也必须按 `publication_status=Published + visible=true + 未删除` 判断作品存在，不能额外要求 `published_at` 非空。
 - 临时运行约束：SpacetimeDB 2.2 下抓大鹅 `match_3_d_gallery_view` 的 `publication_status` 索引过滤在源表更新触发统一 view 刷新时可能初始化 panic；为避免后台隐藏作品打爆 module instance，统一 `public_work_*` view 暂不级联抓大鹅 source view，抓大鹅公开入口先保留玩法专用路径。后续应以 source projection 表替代索引 view 后再重新并入统一 read model。
 - 旧 `/api/runtime/<play>/gallery` 响应 shape 保持兼容，由 BFF mapper 把统一 cache 再映射回当前 DTO。
 - 旧详情 / runtime / 点赞 / 游玩 / Remix 仍走玩法专用路径。

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -66,6 +66,7 @@ npm run check:server-rs-ddd
 - 方洞挑战：`/api/creation/square-hole/*`、`/api/runtime/square-hole/*`。
 - 视觉小说：`/api/creation/visual-novel/*`、`/api/runtime/visual-novel/*`。
 - 大鱼吃小鱼：`/api/runtime/big-fish/*`。
+- 跳一跳：`/api/creation/jump-hop/*`、`/api/runtime/jump-hop/*`。
 - 汪汪声浪：`/api/runtime/bark-battle/*`。
 - 儿童向创作：`/api/creation/edutainment/*`。
 - AI task：`/api/ai/tasks*`。
@@ -74,7 +75,7 @@ npm run check:server-rs-ddd
 
 ### 认证态用户与会话摘要下发口径
 
-- `AuthUserPayload` / `AuthUser` 只保留前端当前会用到的身份与绑定展示字段：`id`、`publicUserCode`、`displayName`、`avatarUrl`、`phoneNumber`、`phoneNumberMasked`、`loginMethod`、`bindingStatus`、`wechatBound`、`wechatDisplayName`、`wechatAccount`。账号信息面板展示微信绑定时优先使用 `wechatDisplayName`；该字段只能来自微信平台 profile、历史已保存的微信身份资料，或小程序原生 `input type="nickname"` 提交的 `displayName`，不得用系统账号显示名或“微信旅人”这类假昵称兜底。小程序 `/api/auth/wechat/miniprogram-login` 与 `/api/auth/wechat/bind-phone` 可接收 `displayName`；`jscode2session` 无法直接返回微信昵称或个人微信号，只能稳定拿到小程序维度 `openid`，后端以 `wechatAccount` 下发可区分的绑定账号标识，前端在缺少真实昵称时展示账号尾号。
+- `AuthUserPayload` / `AuthUser` 只保留前端当前会用到的身份与绑定展示字段：`id`、`publicUserCode`、`displayName`、`avatarUrl`、`phoneNumber`、`phoneNumberMasked`、`loginMethod`、`bindingStatus`、`wechatBound`、`wechatDisplayName`、`wechatAccount`。账号信息面板展示微信绑定时优先使用 `wechatDisplayName`；该字段只能来自微信平台 profile、历史已保存的微信身份资料，或小程序原生 `input type="nickname"` 提交的 `displayName`，不得用系统账号显示名或“微信旅人”这类假昵称兜底。小程序 `/api/auth/wechat/miniprogram-login` 与 `/api/auth/wechat/bind-phone` 可接收 `displayName`；`/api/auth/wechat/miniprogram-login` 额外返回 `created`，供小程序壳在快捷登录后判断是否需要补采集微信昵称。`jscode2session` 无法直接返回微信昵称或个人微信号，只能稳定拿到小程序维度 `openid`，后端以 `wechatAccount` 下发可区分的绑定账号标识，前端在缺少真实昵称时展示账号尾号。
 - `AuthSessionSummaryPayload` / `AuthSessionSummary` 只保留设备卡片与撤销需要的摘要字段：`sessionId`、`sessionIds`、`sessionCount`、`clientLabel`、`ipMasked`、`isCurrent`、`createdAt`、`lastSeenAt`、`expiresAt`。
 - 设备诊断信息（例如原始 `clientType` / `clientRuntime` / `clientPlatform` / `userAgent` / `miniProgramAppId` / `miniProgramEnv` / `deviceDisplayName`）不再默认下发到前端；若未来确需展示，优先单独加窄 DTO，而不是把账号 / 会话快照恢复为全量对象。
 
@@ -343,7 +344,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`CreationEntryTypeConfig`
 - 源码：`server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`
 - 字段：`id`、`title`、`subtitle`、`badge`、`image_src`、`visible`、`open`、`sort_order`、`updated_at`、`category_id`、`category_label`、`category_sort_order`、`unified_creation_spec_json`。
-- 迁移兼容：旧迁移包缺少入口分类字段或统一创作契约字段时，由 `migration.rs` 写入 `None` / `0` / `None` 默认值；入口分组展示由 `module-runtime` 和前端展示派生消费，统一创作契约由 `module-runtime` 解析为 `creationTypes[].unifiedCreationSpec`，为空时只回退首批 `puzzle`、`match3d`、`wooden-fish` 默认 spec。
+- 迁移兼容：旧迁移包缺少入口分类字段或统一创作契约字段时，由 `migration.rs` 写入 `None` / `0` / `None` 默认值；入口分组展示由 `module-runtime` 和前端展示派生消费，统一创作契约由 `module-runtime` 解析为 `creationTypes[].unifiedCreationSpec`，为空时按 `shared-contracts` 中当前支持的统一创作默认 spec 回退。`unifiedCreationSpec.title` 是统一创作页表头契约内容，读取和保存时不按入口 `title` 自动覆盖。
 
 ### `custom_world_agent_message`
 
@@ -378,6 +379,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`CustomWorldProfile`
 - 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 - 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+- 兼容约束：历史公开 RPG / 自定义世界 profile 可能存在 `publication_status=Published` 但 `published_at=None`。公开详情、点赞、游玩、Remix 和 `custom_world_gallery_entry` 同步都以 `Published + deleted_at=None + visible=true` 判断作品可公开互动；展示和 gallery 同步时间在 `published_at` 缺失时回退 `updated_at`，不得仅因 `published_at` 为空返回“已发布作品不存在”。
 
 ### `custom_world_session`
 
@@ -414,6 +416,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`JumpHopLeaderboardEntryRow`
 - 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
 - 说明：跳一跳作品维度排行榜 read model，每个 `profile_id + player_id` 只保留 1 条最佳记录；排序口径为成功跳跃次数降序、游戏时长升序、更新时间升序，草稿试玩不作为公开排行榜语义。
+- 展示契约：`player_id` 只作为后端去重和 `viewerBest` 匹配身份键，不得直接进入 HTTP/UI 展示字段；`/api/runtime/jump-hop/works/{profile_id}/leaderboard` 必须补齐 `displayName`，已登录玩家读取账号显示名，匿名游客展示“游客玩家”，失效账号展示“失效玩家”。
 
 ### `jump_hop_runtime_run`
 

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -250,6 +250,8 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 
 生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。`Genarrative-Server-Provision` 是服务器初始化流水线，Job 配置里的 SCM URL 必须使用 controller 本机可访问的仓库路径或内网 Gitea 地址，不能使用 `https://git.genarrative.world/...`；否则日志一开始的 `Checking out git ... to read jenkins/Jenkinsfile.production-server-provision` 就会先从公网拉 Jenkinsfile。其它构建 / 发布流水线仍按各自 Jenkinsfile 的 checkout 口径执行；所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。
 
+`scripts/jenkins-checkout-source.sh` 是生产 Jenkinsfile 内部二次确认源码的统一入口。构建和发布流水线传入 `COMMIT_HASH` 时，脚本必须先保持 `depth=1` 浅拉，若上游 commit 已在浅历史内则直接校验并 checkout；只有浅历史无法证明 commit 属于目标分支时，才按 `GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS`（默认 `50 200 1000 5000`）逐步加深，最后才尝试展开完整历史。`Genarrative-Api-Deploy`、`Genarrative-Web-Deploy` 和 `Genarrative-Stdb-Module-Publish` 都必须保留上游构建传入的 `COMMIT_HASH`，不得为了缩短 checkout 时间改为空值或改用目标分支最新提交。
+
 
 `Genarrative-Stdb-Module-Publish` 在 `Pipeline script from SCM` 阶段如果一开始就报 `No such DSL method 'pipeline'`，优先检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 是否带 UTF-8 BOM。Jenkins Declarative Pipeline 的首个 token 必须是纯 `pipeline`；仓库中的 Jenkinsfile 应保存为 UTF-8 without BOM，只有临时写给 Windows PowerShell 5.1 `-File` 执行的 `.ps1` 才需要按对应 helper 转成带 BOM。验证时可检查文件前三字节不再是 `EF BB BF`，并运行 `validateDeclarativePipeline` 或重放该流水线。
 

docs/【项目基线】当前产品与工程约束-2026-05-15.md

@@ -45,11 +45,12 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台。当
 2. `login-options` 为空、失败、只返回 `phone` 或只返回 `password` 时，前端仍要同时展示验证码登录页签和密码登录页签；短信能力真实可用性由发送验证码接口返回结果表达。
 3. 登录弹窗继续复用现有独立 modal 和页签结构，不在页面中新增功能说明类文案，也不把邀请码输入放回登录面板。
 4. 微信小程序 `web-view` 外壳默认不预登录，首次进入直接打开 H5，并保持与 Web 端一致的未登录状态；只有 H5 触发 `openLoginModal` / `requireAuth` 等受保护入口时，才跳转小程序原生授权态。
-5. 小程序内需要登录时不展示 H5 登录弹窗，也不走手输手机号 / 短信验证码流程；统一先通过原生 `input type="nickname"` 获取微信昵称并作为 `displayName`，再通过 `wx.login` 获取微信登录 code 并调用 `/api/auth/wechat/miniprogram-login`。若后端返回 `pending_bind_phone`，再通过原生 `button open-type="getPhoneNumber"` 获取微信手机号授权并调用 `/api/auth/wechat/bind-phone` 换取系统登录态。
+5. 小程序内需要登录时不展示 H5 登录弹窗，也不走手输手机号 / 短信验证码流程；统一先通过 `wx.login` 获取微信登录 code 并调用 `/api/auth/wechat/miniprogram-login` 完成快捷登录。若该接口返回 `created=true`，或返回用户昵称仍是手机号、公开陶泥号、“微信旅人”等默认展示值，才展示原生 `input type="nickname"` 补充微信昵称并再次调用 `/api/auth/wechat/miniprogram-login` 写入 `displayName`。若后端返回 `pending_bind_phone`，再通过原生 `button open-type="getPhoneNumber"` 获取微信手机号授权并调用 `/api/auth/wechat/bind-phone` 换取系统登录态。
 6. 小程序外壳注入到 H5 URL 的 `clientType`、`clientRuntime`、`miniProgramEnv` 是宿主上下文，H5 内部 `pushState` / 阶段导航必须跨页面保留，避免登录和充值误判为普通浏览器；首点时微信 JS bridge 可能尚未就绪，前端还需用 `MicroMessenger + miniProgram` User-Agent 作为小程序识别兜底。
 7. 小程序 `web-view` 页必须启用好友分享与朋友圈分享，分享目标固定回到 `pages/web-view/index`，不把 H5 当前 URL 作为不受控启动参数传回小程序页。
 8. 小程序 `web-view` 外壳运行时通过 `wx.getAccountInfoSync().miniProgram.envVersion` 自动识别版本：线上版 `release` 使用 `www.genarrative.world`，体验版 `trial` 与开发版 `develop` 使用 `dev.genarrative.world`；传给后端的 `x-mini-program-env` 分别为 `release`、`trial`、`dev`。
-9. 账号信息面板只展示 `账号信息` 标题；绑定手机号和绑定微信以紧凑模块展示当前绑定状态，已绑定手机号展示完整手机号，已绑定微信优先展示微信平台实际返回并由后端保存的 `wechatDisplayName`。小程序 `jscode2session` 不能直接返回微信昵称或个人微信号，只能稳定拿到当前小程序维度的 `openid`，并在满足微信开放平台条件时拿到 `unionid`；小程序昵称来自原生 `input type="nickname"` 提交的 `displayName`。后端下发 `wechatAccount` 作为绑定账号标识，前端在没有真实昵称时展示微信账号尾号，不展示裸“已绑定”。换绑入口放在对应模块右上角，退出登录和退出全部设备固定放在面板内容最底部。
+9. 账号信息面板只展示 `账号信息` 标题；绑定手机号和绑定微信以紧凑模块展示当前绑定状态，已绑定手机号展示完整手机号，已绑定微信优先展示微信平台实际返回并由后端保存的 `wechatDisplayName`。小程序 `jscode2session` 不能直接返回微信昵称或个人微信号，只能稳定拿到当前小程序维度的 `openid`，并在满足微信开放平台条件时拿到 `unionid`；小程序昵称来自快捷登录后按需展示的原生 `input type="nickname"` 提交的 `displayName`。后端下发 `wechatAccount` 作为绑定账号标识，前端在没有真实昵称时展示微信账号尾号，不展示裸“已绑定”。换绑入口放在对应模块右上角，退出登录和退出全部设备固定放在面板内容最底部。
+10. H5 登录态从未登录变为已登录，或从已登录变为未登录后，必须刷新当前页面一次，确保推荐运行态、作品架、个人缓存和私有 query 都按新身份重新初始化；普通 access token 续期、账号资料更新和同一登录态内的设置变化不得触发整页刷新。
 
 ## 账户与充值
 
@@ -95,7 +96,7 @@ server-rs + Axum + SpacetimeDB
 3. 点击按钮弹出独立面板时，必须弹出 dialog / drawer / modal，不要在当前面板下方展开内容。
 4. 优先复用现有系统、页面、组件和弹层，不因一次需求新建平行系统。
 5. 游戏式页面要防止文字、按钮、HUD、底部 dock、输入法和画布互相遮挡。
-6. 平台根壳已处理移动端输入法聚焦：输入法弹出时保持画布稳定高度，用偏移聚焦输入框，业务组件不要重复注册全局键盘适配。
+6. 平台根壳已处理移动端输入法聚焦：输入法弹出时保持画布稳定高度，只记录键盘状态、隐藏底部 dock 并补齐浅色暴露背景，不再全局上移平台壳；业务组件不要重复注册全局键盘适配。
 7. 主站入口已锁定移动端页面级缩放；单个游戏页面不要再重复实现整页缩放锁定。
 8. 图像输入通用 UI 统一走 `src/components/common/CreativeImageInputPanel.tsx`。外层页面持有业务状态，组件只承担上传卡、预览、参考图缩略图、AI 重绘开关、错误展示和提交按钮。
 9. 发现页 `分类` 子频道的筛选必须打开独立 dialog / drawer / modal，至少支持玩法类型过滤与排序切换；筛选结果为空时显示空状态，不把筛选内容展开在当前列表下方。

jenkins/Jenkinsfile.production-api-deploy

@@ -89,17 +89,12 @@ pipeline {
             env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
           }
         }
-        script {
-          if (params.COMMIT_HASH?.trim()) {
-            echo "API 发布脚本 checkout 将忽略上游构建 commit=${params.COMMIT_HASH}，改用 ${params.SOURCE_BRANCH ?: 'master'} 最新提交，避免发布阶段回退到旧部署脚本。构建产物仍由 BUILD_NUMBER_TO_DEPLOY 决定。"
-          }
-        }
         sh '''
           bash -lc '
             set -euo pipefail
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
-            COMMIT_HASH="" \
+            COMMIT_HASH="${COMMIT_HASH:-}" \
             GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
             GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \

miniprogram/pages/web-view/index.js

@@ -111,6 +111,58 @@ function normalizeNicknameInput(value) {
   return String(value || '').trim();
 }
 
+function normalizeNicknameForMatch(value) {
+  return normalizeNicknameInput(value).replace(/\s+/gu, '').toLowerCase();
+}
+
+function isPhoneLikeDisplayName(value) {
+  const normalized = normalizeNicknameForMatch(value);
+  if (!normalized) {
+    return false;
+  }
+
+  const digits = normalized.replace(/\D/gu, '');
+  return (
+    /^(\+?86)?1\d{10}$/u.test(normalized) ||
+    /^1\d{2}\*{4}\d{4}$/u.test(normalized) ||
+    (/[*x]/iu.test(normalized) && digits.length >= 7) ||
+    digits.length >= 11
+  );
+}
+
+function isDefaultDisplayName(value, publicUserCode) {
+  const normalized = normalizeNicknameForMatch(value);
+  const normalizedPublicUserCode = normalizeNicknameForMatch(publicUserCode);
+  if (!normalized) {
+    return true;
+  }
+
+  return (
+    normalized === '微信旅人' ||
+    normalized === '玩家' ||
+    normalized === normalizedPublicUserCode ||
+    /^sy-\d{8}$/iu.test(normalized) ||
+    /^user[_-]/iu.test(normalized) ||
+    isPhoneLikeDisplayName(normalized)
+  );
+}
+
+function shouldRequestNicknameAfterLogin(authResult) {
+  const user = authResult && authResult.user ? authResult.user : {};
+  const wechatDisplayName = normalizeNicknameInput(user.wechatDisplayName);
+  if (wechatDisplayName && !isDefaultDisplayName(wechatDisplayName, user.publicUserCode)) {
+    return false;
+  }
+
+  return (
+    authResult &&
+    (authResult.created ||
+      isDefaultDisplayName(user.displayName, user.publicUserCode) ||
+      (wechatDisplayName &&
+        isDefaultDisplayName(wechatDisplayName, user.publicUserCode)))
+  );
+}
+
 function normalizeMiniProgramEnv(value) {
   const normalized = String(value || '').trim().toLowerCase();
   if (normalized === 'release') {
@@ -372,6 +424,8 @@ async function resolveAuthResult(displayName) {
   return {
     token: response.token,
     bindingStatus: response.bindingStatus || 'pending_bind_phone',
+    user: response.user || null,
+    created: response.created === true,
   };
 }
 
@@ -431,13 +485,14 @@ Page({
       authResult: null,
       bindingPhone: false,
       errorMessage: '',
-      loggingIn: false,
-      loading: false,
-      nicknameRequired: true,
+      loggingIn: true,
+      loading: true,
+      nicknameRequired: false,
       phoneBindingRequired: false,
       returnToPreviousPage,
       webViewUrl: '',
     });
+    await this.startAuthFlow(returnToPreviousPage, '');
   },
 
   handleNicknameInput(event) {
@@ -465,6 +520,20 @@ Page({
   async startAuthFlow(returnToPreviousPage, displayName) {
     try {
       const authResult = await resolveAuthResult(displayName);
+      if (!displayName && shouldRequestNicknameAfterLogin(authResult)) {
+        this.setData({
+          authResult,
+          errorMessage: '',
+          loggingIn: false,
+          loading: false,
+          nicknameRequired: true,
+          phoneBindingRequired: false,
+          returnToPreviousPage,
+          webViewUrl: '',
+        });
+        return;
+      }
+
       if (authResult.bindingStatus === 'pending_bind_phone') {
         this.setData({
           authResult,
@@ -512,7 +581,7 @@ Page({
           error && error.message ? error.message : '微信登录失败，请稍后重试。',
         loggingIn: false,
         loading: false,
-        nicknameRequired: true,
+        nicknameRequired: false,
         phoneBindingRequired: false,
         returnToPreviousPage,
         webViewUrl: '',

miniprogram/pages/web-view/index.style.test.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { describe, expect, test } from 'vitest';
+
+const PAGE_DIR = path.resolve(
+  process.cwd(),
+  'miniprogram/pages/web-view',
+);
+
+function readPageFile(fileName) {
+  return fs.readFileSync(path.join(PAGE_DIR, fileName), 'utf8');
+}
+
+describe('mini program web-view page background', () => {
+  test('keeps the native web-view host light when the mobile keyboard exposes it', () => {
+    const wxml = readPageFile('index.wxml');
+    const wxss = readPageFile('index.wxss');
+
+    expect(wxml).toContain('class="web-view-host"');
+    expect(wxml).not.toContain('class="web-view-page"');
+    expect(wxss).toContain('page');
+    expect(wxss).toContain('.web-view-host');
+    expect(wxss).toContain('background: #fffdf9;');
+
+    const webViewHostBlock = wxss.slice(
+      wxss.indexOf('.web-view-host'),
+      wxss.indexOf('.setup-screen'),
+    );
+    expect(webViewHostBlock).not.toContain('#0b0f14');
+  });
+});

miniprogram/pages/web-view/index.wxml

@@ -1,6 +1,7 @@
 <block wx:if="{{webViewUrl}}">
   <web-view
     id="genarrative-web-view"
+    class="web-view-host"
     src="{{webViewUrl}}"
     bindload="handleWebViewLoad"
     binderror="handleWebViewError"
@@ -10,7 +11,7 @@
 
 <view wx:elif="{{nicknameRequired}}" class="setup-screen">
   <view class="setup-card">
-    <view class="setup-title">登录</view>
+    <view class="setup-title">完善昵称</view>
     <view wx:if="{{errorMessage}}" class="setup-text setup-text--danger">
       {{errorMessage}}
     </view>
@@ -29,7 +30,7 @@
       disabled="{{loggingIn}}"
       bindtap="handleStartLogin"
     >
-      {{loggingIn ? '正在登录' : '微信快捷登录'}}
+      {{loggingIn ? '正在提交' : '确认昵称'}}
     </button>
   </view>
 </view>

miniprogram/pages/web-view/index.wxss

@@ -1,3 +1,14 @@
+page {
+  background: #fffdf9;
+}
+
+.web-view-host {
+  display: block;
+  width: 100%;
+  min-height: 100vh;
+  background: #fffdf9;
+}
+
 .setup-screen {
   min-height: 100vh;
   display: flex;

packages/shared/src/contracts/auth.ts

@@ -143,6 +143,7 @@ export type AuthWechatMiniProgramLoginResponse = {
   token: string;
   bindingStatus: AuthBindingStatus;
   user: AuthUser;
+  created: boolean;
 };
 
 export type AuthPhoneChangeRequest = {

packages/shared/src/contracts/index.ts

@@ -4,6 +4,7 @@ export type * from './hyper3d';
 export type * from './jumpHop';
 export type * from './puzzleCreativeTemplate';
 export type * from './puzzleClear';
+export * from './playTypes';
 export type * from './publicWork';
 export type * from './visualNovel';
 export type * from './barkBattle';

packages/shared/src/contracts/jumpHop.ts

@@ -294,6 +294,7 @@ export interface JumpHopJumpResponse {
 export interface JumpHopLeaderboardEntry {
   rank: number;
   playerId: string;
+  displayName: string;
   successfulJumpCount: number;
   durationMs: number;
   updatedAt: string;

packages/shared/src/contracts/playTypes.ts

@@ -0,0 +1,72 @@
+export const PLATFORM_CREATION_TYPE_IDS = [
+  'rpg',
+  'big-fish',
+  'puzzle',
+  'puzzle-clear',
+  'match3d',
+  'jump-hop',
+  'wooden-fish',
+  'square-hole',
+  'bark-battle',
+  'visual-novel',
+  'baby-object-match',
+  'creative-agent',
+  'airp',
+] as const;
+
+export type PlatformCreationTypeId =
+  (typeof PLATFORM_CREATION_TYPE_IDS)[number];
+
+const PLATFORM_CREATION_TYPE_ID_SET: ReadonlySet<string> = new Set(
+  PLATFORM_CREATION_TYPE_IDS,
+);
+
+export function isPlatformCreationTypeId(
+  value: string,
+): value is PlatformCreationTypeId {
+  return PLATFORM_CREATION_TYPE_ID_SET.has(value);
+}
+
+export function assertPlatformCreationTypeId(
+  value: string,
+): PlatformCreationTypeId {
+  if (isPlatformCreationTypeId(value)) {
+    return value;
+  }
+
+  throw new Error(`未知创作类型：${value}`);
+}
+
+export const PUBLIC_WORK_SOURCE_TYPES = [
+  'custom-world',
+  'big-fish',
+  'puzzle',
+  'puzzle-clear',
+  'jump-hop',
+  'wooden-fish',
+  'match3d',
+  'square-hole',
+  'visual-novel',
+  'bark-battle',
+  'edutainment',
+] as const;
+
+export type PublicWorkSourceType = (typeof PUBLIC_WORK_SOURCE_TYPES)[number];
+
+const PUBLIC_WORK_SOURCE_TYPE_SET: ReadonlySet<string> = new Set(
+  PUBLIC_WORK_SOURCE_TYPES,
+);
+
+export function isPublicWorkSourceType(
+  value: string,
+): value is PublicWorkSourceType {
+  return PUBLIC_WORK_SOURCE_TYPE_SET.has(value);
+}
+
+export function assertPublicWorkSourceType(value: string): PublicWorkSourceType {
+  if (isPublicWorkSourceType(value)) {
+    return value;
+  }
+
+  throw new Error(`未知公开作品类型：${value}`);
+}

packages/shared/src/contracts/publicWork.ts

@@ -1,5 +1,7 @@
+import type { PublicWorkSourceType } from './playTypes';
+
 export interface PublicWorkGalleryEntryResponse {
-  sourceType: string;
+  sourceType: PublicWorkSourceType;
   workId: string;
   profileId: string;
   sourceSessionId?: string | null;

packages/shared/src/contracts/puzzleRuntimeSession.ts

@@ -136,7 +136,6 @@ export interface DragPuzzlePieceRequest {
 
 export interface AdvancePuzzleNextLevelRequest {
   targetProfileId?: string | null;
-  preferSimilarWork?: boolean;
 }
 
 export interface UsePuzzleRuntimePropRequest {

packages/shared/src/index.ts

@@ -12,6 +12,7 @@ export type * from './contracts/hyper3d';
 export * from './contracts/match3dAgent';
 export * from './contracts/match3dRuntime';
 export * from './contracts/match3dWorks';
+export * from './contracts/playTypes';
 export * from './contracts/puzzleAgentActions';
 export * from './contracts/puzzleAgentDraft';
 export * from './contracts/puzzleAgentSession';

scripts/jenkins-checkout-source.sh

@@ -51,11 +51,71 @@ fetch_source_branch() {
   fi
 
   echo "[jenkins-checkout-source] 尝试 Git 远端: ${remote_url:-origin}"
-  if [[ -z "${COMMIT_HASH}" ]]; then
-    git fetch --no-tags --prune --depth=1 origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+  git fetch --no-tags --prune --depth=1 origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+}
+
+is_shallow_repository() {
+  [[ "$(git rev-parse --is-shallow-repository 2>/dev/null || echo false)" == "true" ]]
+}
+
+resolve_requested_commit_if_on_branch() {
+  local requested_commit="$1"
+  local resolved_commit
+
+  if ! git cat-file -e "${requested_commit}^{commit}" 2>/dev/null; then
+    return 1
+  fi
+
+  resolved_commit="$(git rev-parse "${requested_commit}^{commit}")"
+  if ! git merge-base --is-ancestor "${resolved_commit}" "refs/remotes/origin/${SOURCE_BRANCH}" 2>/dev/null; then
+    return 1
+  fi
+
+  printf "%s\n" "${resolved_commit}"
+}
+
+resolve_requested_commit_with_deepen() {
+  local requested_commit="$1"
+  local deepen_steps_raw="${GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS:-50 200 1000 5000}"
+  local deepen_steps=()
+  local deepen_depth
+  local resolved_commit
+
+  # 中文注释：上游构建 commit 通常就是分支 HEAD，先吃浅克隆；确实不是浅历史内提交时再逐步加深。
+  if resolved_commit="$(resolve_requested_commit_if_on_branch "${requested_commit}")"; then
+    printf "%s\n" "${resolved_commit}"
+    return 0
+  fi
+
+  read -r -a deepen_steps <<<"${deepen_steps_raw}"
+  for deepen_depth in "${deepen_steps[@]}"; do
+    if [[ ! "${deepen_depth}" =~ ^[0-9]+$ || "${deepen_depth}" -le 1 ]]; then
+      echo "[jenkins-checkout-source] 忽略无效加深深度: ${deepen_depth}" >&2
+      continue
+    fi
+
+    echo "[jenkins-checkout-source] 浅历史未命中 commit=${requested_commit}，加深到 depth=${deepen_depth}" >&2
+    if is_shallow_repository; then
+      git fetch --no-tags --prune --depth="${deepen_depth}" origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+    else
+      git fetch --no-tags --prune origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
+    fi
+
+    if resolved_commit="$(resolve_requested_commit_if_on_branch "${requested_commit}")"; then
+      printf "%s\n" "${resolved_commit}"
+      return 0
+    fi
+  done
+
+  if is_shallow_repository; then
+    echo "[jenkins-checkout-source] 逐步加深仍未命中 commit=${requested_commit}，最后尝试展开完整历史" >&2
+    git fetch --unshallow --no-tags origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}" || \
+      git fetch --no-tags --prune origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
   else
     git fetch --no-tags --prune origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}"
   fi
+
+  resolve_requested_commit_if_on_branch "${requested_commit}"
 }
 
 add_git_remote_candidate "${GIT_REMOTE_URL}"
@@ -80,17 +140,11 @@ else
   fi
 fi
 
-if [[ -n "${COMMIT_HASH}" && "$(git rev-parse --is-shallow-repository 2>/dev/null || echo false)" == "true" ]]; then
-  git fetch --unshallow --no-tags origin "+refs/heads/${SOURCE_BRANCH}:refs/remotes/origin/${SOURCE_BRANCH}" || true
-fi
-
 git cat-file -e "refs/remotes/origin/${SOURCE_BRANCH}^{commit}"
 
 if [[ -n "${COMMIT_HASH}" ]]; then
-  git cat-file -e "${COMMIT_HASH}^{commit}"
-  RESOLVED_COMMIT="$(git rev-parse "${COMMIT_HASH}^{commit}")"
-  if ! git merge-base --is-ancestor "${RESOLVED_COMMIT}" "refs/remotes/origin/${SOURCE_BRANCH}"; then
-    echo "[jenkins-checkout-source] 指定 commit 不属于 origin/${SOURCE_BRANCH}: ${RESOLVED_COMMIT}" >&2
+  if ! RESOLVED_COMMIT="$(resolve_requested_commit_with_deepen "${COMMIT_HASH}")"; then
+    echo "[jenkins-checkout-source] 指定 commit 不属于 origin/${SOURCE_BRANCH}: ${COMMIT_HASH}" >&2
     exit 1
   fi
 else