Merge remote-tracking branch 'origin/master' into hermes/hermes-996d586b

2026-05-08 14:42:15 +08:00
parent 539ddbde24 326cc6b062
commit 5e419fa2f7
29 changed files with 1909 additions and 124 deletions
--- a/.hermes/shared-memory/decision-log.md
+++ b/.hermes/shared-memory/decision-log.md
@@ -32,6 +32,14 @@
 - 验证方式：新增或修改后端相关文档时，检查不得要求 `api-server:maincloud` 或 `GENARRATIVE_SPACETIME_MAINCLOUD_*`；触碰历史残留时同步删除或改名。
 - 关联文档：`docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md`、`docs/technical/SPACETIMEDB_CLOUD_CONFIG_REMOVAL_2026-05-02.md`。

+## 2026-05-05 新手引导首版复用拼图本地运行时
+
+- 背景：首次打开产品的新用户需要先体验输入想法、生成拼图、通关、登录保存、回到首页的闭环，但首版不应引入新的持久化表或独立玩法运行时。
+- 决策：未登录首次访问由前端 localStorage 标记触发；生成入口走公开 BFF `POST /api/runtime/puzzle/onboarding/generate` 生成 1 关临时拼图；登录后保存走鉴权 BFF `POST /api/runtime/puzzle/onboarding/save`，由服务端创建当前用户拼图 agent session 并更新其草稿作品 profile；游玩阶段复用现有本地拼图运行时。
+- 影响范围：平台入口首屏、新手引导 PRD、拼图 BFF、拼图作品契约与前端 puzzle runtime。
+- 验证方式：未登录首次访问应展示新手引导；生成后只进入 1 关本地拼图；通关后登录保存应在当前用户拼图作品架出现草稿作品；不应产生 SpacetimeDB schema 变更。
+- 关联文档：`docs/prd/FIRST_LAUNCH_PUZZLE_ONBOARDING_PRD_2026-05-05.md`。
+
 ## 2026-05-04 在仓库 `.hermes/` 中建立团队共享记忆

 - 背景：团队有 3 名开发人员，均在各自本地安装 Hermes，并需要独立拉取仓库、修改代码、本地测试；团队希望形成共享的长期项目记忆。
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.hermes/shared-memory/pitfalls.md
@@ -14,7 +14,13 @@
 - 关联：相关文件、文档、提交或 Issue
 ```

---
+## OSS V4 签名时间和 bucket/object_key 兼容
+
+- 现象：OSS V4 私有读签名在部分时间点失败，可能出现 `OSS V4 签名时间格式化失败` 或服务端判定签名格式错误；排查用例中 bucket 为 `xushi-dev`，object_key 为 `generated-square-hole-assets/.../image.png`。
+- 原因：旧逻辑依赖 `time::Time::to_string()` 再去掉冒号，小时小于 10 时输出不稳定补零；同时排查时容易把 bucket 名误当成 object_key 的一部分。
+- 处理：OSS V4 `x-oss-date` 使用固定宽度 `yyyyMMdd'T'HHmmss'Z'` 格式化；调用读签名或 `HEAD Object` 时只传 object_key，不要传 `bucket/object_key` 拼接路径。
+- 验证：运行 `cd server-rs && cargo test -p platform-oss -- --nocapture`，并用 bucket=`xushi-dev`、object_key=`generated-square-hole-assets/square-hole-session-546d881972684be2980a2a882cd0cc71/square-hole-profile-134411276ce1469cbe398f946a25d7f8/square-hole-shape-image/rabbit-option/asset-1777979289912039/image.png` 覆盖签名生成。
+- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/platform-oss/README.md`。

 ## 中文乱码与编码风险

@@ -69,6 +75,14 @@
 - 验证：请求返回 JSON，相关页面不再出现 HTML parse 错误。
 - 关联：`docs/technical/PROFILE_MAIN_ROUTE_VITE_PROXY_FIX_2026-05-02.md`。

+## 拼图 APIMart 图片生成密钥不能复用 DashScope / ARK key
+
+- 现象：拼图新手引导或拼图创作点击生成后返回 `APIMart 图片生成密钥未配置`。
+- 原因：拼图 `gpt-image-2` / `nanobanana2` 图片生成已按技术方案统一走 APIMart；后端只读取 `APIMART_BASE_URL`、`APIMART_API_KEY`、`APIMART_IMAGE_REQUEST_TIMEOUT_MS`，不会用 `DASHSCOPE_API_KEY`、`LLM_API_KEY` 或 `ARK_API_KEY` 兜底。
+- 处理：在本机私密配置 `.env.secrets.local` 或进程环境中配置真实 `APIMART_API_KEY`，不要提交到 Git；填入后必须重启 `api-server` / `npm run dev`，运行中的进程不会自动加载新 env。
+- 验证：不打印密钥内容，只检查 `APIMART_API_KEY` 非空；重启后触发拼图生成不再返回本地配置缺失的 503。
+- 关联：`docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md`、`.codex/skills/gpt-image-2-apimart/SKILL.md`。
+
 ## Rust 冷编译导致 api-server 健康检查误超时

 - 现象：`npm run dev:rust` 在 Windows 冷编译/链接阶段误判 `/healthz` 等待超时并杀掉 `cargo run`。
--- a/docs/design/BAIMENG_EXPO_ROLLUP_BANNER_DESIGN_2026-05-07.md
+++ b/docs/design/BAIMENG_EXPO_ROLLUP_BANNER_DESIGN_2026-05-07.md
@@ -0,0 +1,110 @@
+# 百梦线下展会易拉宝设计记录 2026-05-07
+
+## 1. 目标
+
+为百梦线下展会制作一张纵向易拉宝广告展板，用于在展位现场快速传达：
+
+1. 产品名称：百梦。
+2. 产品愿景：百梦AI团队致力于打造AI互动内容UGC平台。
+3. 产品slogan：每个人都可以在10分钟内轻松创作出一款精品互动作品。
+4. 产品特点：低门槛创作、高完成度作品、玩过后可改造并发布。
+5. 关键技术：Harness Engineering、多Agent调度、AI创作工具、AI原生游戏框架。
+6. 产品心智：想玩但找不到、玩到不满意、平台外体验不满意时，都可以来百梦做成自己满意的。
+
+## 2. 视觉方向
+
+本次延续 `BAIMENG_LOGO_GPT_IMAGE_2_CONCEPTS_2026-05-05.md` 中最新收敛的气泡共创方向：
+
+- 参考 logo：`output/imagegen/baimeng-logo-bubble-04-07-refine-batch13/baimeng-bubble-04-07-refine-01-04-flat-rainbow-band-core.png`
+- 主视觉语义：轻盈气泡、很多创意、UGC共创、作品改造与分享。
+- 色彩：暖白、珊瑚粉、薰衣草紫、天蓝、薄荷青、少量金色光感。
+- 展会阅读策略：远看先读产品名与slogan，近看再读产品心智与关键技术。
+
+## 3. 文案层级
+
+最终展板文案压缩为四层。
+
+第一层：品牌识别
+
+```text
+百梦
+AI互动内容UGC平台
+把想玩的世界，亲手做出来
+```
+
+第二层：远读slogan
+
+```text
+每个人都可以在10分钟内
+轻松创作出一款
+精品互动作品
+```
+
+第三层：产品特点
+
+```text
+10分钟成品级创作
+玩过就能改造发布
+创意到作品闭环
+```
+
+并拆成三张近读卡：
+
+```text
+创作：从一句灵感开始，AI帮助完成剧本、角色、场景、系统与视觉草稿。
+游玩：作品不是静态文本，而是可进入、可推进、可演出的互动体验。
+改造：玩到不满意的作品，可以快速改成自己喜欢的版本并再次发布。
+```
+
+第四层：产品心智与关键技术
+
+```text
+当用户找不到想玩的游戏 -> 来百梦做给自己玩
+当用户玩到了不好玩的游戏 -> 快速改成自己喜欢玩的
+当用户在平台外玩到了不满意的游戏 -> 来百梦做成自己满意的
+什么游戏最好玩？ -> 来百梦玩自己做的游戏最好玩
+```
+
+关键技术压缩为：
+
+```text
+基于 Harness Engineering 理论，将专家知识融入 AI 创作工具与 AI 原生游戏框架。
+
+AI创作工具：
+通过多Agent调度算法，把策划、美术SOP与专家知识融入模板框架，提升剧本类、数值类、系统类、角色设计、场景设计、CG设计等垂类任务的完成率和效率。
+
+AI原生游戏框架：
+通过系统化约束模型输入输出，把实时剧本创作和游戏设计专家知识内嵌在规则中，提升实时剧情、数值对齐、画面对齐、任务与物品生成质量。
+```
+
+## 4. 生成方式
+
+主视觉底图使用仓库内 APIMart OpenAI 兼容 `gpt-image-2` 工作流生成：
+
+```text
+model: gpt-image-2
+size: 1536x3840
+reference image: 百梦气泡共创logo方向图
+output: output/imagegen/baimeng-expo-rollup/baimeng-rollup-background-gpt-image-2.png
+```
+
+因为图片模型直接生成中文长文案存在错字风险，最终稿采用“gpt-image-2 底图 + 本地精确中文排版”的方式生成：
+
+```text
+tmp/imagegen/generate-baimeng-rollup-background.mjs
+tmp/imagegen/render-baimeng-rollup.py
+```
+
+最终输出：
+
+```text
+output/imagegen/baimeng-expo-rollup/baimeng-rollup-final-cn.png
+output/imagegen/baimeng-expo-rollup/baimeng-rollup-final-cn-preview.png
+```
+
+## 5. 后续改版建议
+
+1. 若印刷厂提供具体尺寸和出血要求，优先在 `render-baimeng-rollup.py` 中调整画布比例、边距和安全区。
+2. 若需要放二维码，应放在底部独立留白区，不遮挡产品心智和关键技术段。
+3. 若展会现场观众偏投资人或B端合作方，可以把“产品心智”段压缩，放大“关键技术”与平台愿景。
+4. 若观众偏玩家或普通创作者，可以把“关键技术”段压缩，放大“10分钟创作、玩过就改、发布分享”的闭环。
--- a/docs/design/BAIMENG_LOGO_GPT_IMAGE_2_CONCEPTS_2026-05-05.md
+++ b/docs/design/BAIMENG_LOGO_GPT_IMAGE_2_CONCEPTS_2026-05-05.md
@@ -207,6 +207,26 @@
 - `01-ring-three-bubbles`：识别直接，但工具 icon 感略强。
 - `04-breath-origin`：梦感更强，但现实吹泡泡行为弱。

+## 12. 吹泡泡主标再收敛版补充
+
+在“方向正确，再来一些”的基础上，本轮继续压缩泡泡棒方向，目标是减少玩具感，让它更像成熟产品主标。
+
+本轮生成 prompt：
+
+`tmp/imagegen/baimeng_logo_bubble_refine_batch12_prompts.jsonl`
+
+本轮输出目录：
+
+`output/imagegen/baimeng-logo-bubble-refine-batch12/`
+
+当前最值得继续推进的是：
+
+- `02-simple-action-mark`：泡泡棒行为明确，结构干净，比上一批更接地气，也不太幼稚。
+- `06-one-plus-two-bubbles`：更抽象、更高级，但现实吹泡泡行为感弱一些。
+- `08-final-simple-bubbles`：适合 App icon，但聊天气泡联想较强，需弱化社交聊天框尾巴。
+
+不建议推进 `03/04/07`，它们出现了不稳定文字或方案式字标；`01` 容易被误认为放大镜。
+
 批量生成 prompt 已放在：

 `tmp/imagegen/baimeng_logo_gpt_image_2_prompts.jsonl`
@@ -233,3 +253,35 @@ python "C:\Users\wuxiangwanzi\.codex\skills\.system\imagegen\scripts\image_gen.p
 APIMART_BASE_URL=https://api.apimart.ai/v1
 APIMART_API_KEY=...
 ```
+
+## 13. 04/07 气泡方向单独优化补充
+
+在用户反馈“更喜欢 04 和 07”后，本轮不再横向发散其它生活物件，而是只围绕两条已被接受的视觉方向做收敛：
+
+- 继承 `04` 的中心大泡泡：保留多条虹彩色带组成的饱满主视觉，但压低小泡泡的高光、阴影和玻璃拟物感。
+- 继承 `07` 的色彩和轻轻吹泡泡行为：减少元素数量，确保整体居中，避免一串气泡散向右上角。
+- 明确排除 `03/05/08` 中容易出现的聊天软件联想，不使用聊天尾巴、对话框轮廓、碎小装饰点和星形元素。
+
+本轮生成 prompt：
+
+`tmp/imagegen/baimeng_logo_bubble_04_07_refine_batch13_prompts.jsonl`
+
+本轮输出目录：
+
+`output/imagegen/baimeng-logo-bubble-04-07-refine-batch13/`
+
+联系表：
+
+`output/imagegen/baimeng-logo-bubble-04-07-refine-batch13/baimeng-bubble-04-07-refine-batch13-contact-sheet.png`
+
+当前最值得继续推进的是：
+
+- `01-04-flat-rainbow-band-core`：保留了 04 的彩虹色带饱满度，同时只留下一个小辅助泡泡，聊天气泡联想弱，适合作为“梦 / 很多 / 共创”的品牌主标继续精修。
+- `02-04-single-full-bubble-ring`：最克制、最像可注册主符号，完全去掉碎元素；缺点是“吹泡泡行为”和 UGC 共创感比其它方案弱，可作为极简品牌基线。
+- `08-07-rainbow-breath-symbol`：较好融合了 04 的虹彩大环与 07 的吹泡泡动作，亲和度高；后续需要继续压缩右上两个泡泡的体量，避免重心偏右。
+
+不建议优先推进：
+
+- `03-04-overlap-two-bubbles-brand`：结构清楚，但小环容易变成独立图标，整体略硬。
+- `04-04-rainbow-bubble-wand-minimal`：泡泡棒语义明确，但下方手柄过于具象，容易像工具图标。
+- `05/06/07`：色彩和亲和力可参考，但泡泡簇仍比 01/02/08 更接近装饰插画，产品主标凝聚力不足。
--- a/docs/design/README.md
+++ b/docs/design/README.md
@@ -15,6 +15,7 @@
 - [PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md](./PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md)：平台入口新增分类 Tab、登录态导航裁剪与创作 Tab 视觉强化设计。
 - [PLATFORM_BIG_FISH_ENTRY_HIDE_2026-04-28.md](./PLATFORM_BIG_FISH_ENTRY_HIDE_2026-04-28.md)：平台入口暂时隐藏大鱼吃小鱼创作卡片，但保留现有玩法链路。
 - [UNIFIED_MODAL_WINDOW_DESIGN_2026-04-25.md](./UNIFIED_MODAL_WINDOW_DESIGN_2026-04-25.md)：统一平台风与 RPG 像素风模态窗口外壳、交互边界和迁移顺序。
+- [BAIMENG_EXPO_ROLLUP_BANNER_DESIGN_2026-05-07.md](./BAIMENG_EXPO_ROLLUP_BANNER_DESIGN_2026-05-07.md)：百梦线下展会易拉宝广告展板的文案层级、视觉方向与 gpt-image-2 生成记录。
 - [AI_NATIVE_RUNTIME_ITEM_SYSTEM_REDESIGN_2026-04-02.md](./AI_NATIVE_RUNTIME_ITEM_SYSTEM_REDESIGN_2026-04-02.md)：运行时物品生成系统重设计。
 - [LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md](./LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md)：等级成长、章节经验节奏与 NPC 自动定级设计。
 - [RPG_NARRATIVE_PLANNING_FULL_PIPELINE_WORKFLOW_2026-04-12.md](./RPG_NARRATIVE_PLANNING_FULL_PIPELINE_WORKFLOW_2026-04-12.md)：专业剧情策划构建 RPG 游戏全剧情的工作流程与交付模板。
--- a/docs/prd/FIRST_LAUNCH_PUZZLE_ONBOARDING_PRD_2026-05-05.md
+++ b/docs/prd/FIRST_LAUNCH_PUZZLE_ONBOARDING_PRD_2026-05-05.md
@@ -0,0 +1,61 @@
+# 新手引导流程 PRD
+
+## 1. 目标
+
+引导未登录且首次访问产品的用户，快速体验从输入想法、AI 生成拼图游戏、完成拼图、注册或登录保留作品，到进入产品首页的创作闭环。
+
+## 2. 触发条件
+
+1. 用户处于未登录状态。
+2. 用户首次访问产品。
+
+## 3. 流程
+
+1. 用户首次打开产品。
+2. 页面浮现文字：`待定待定待定`。
+3. 文字下方展示文字输入框。
+4. 输入框提示文字：`把你的梦讲给我听吧`。
+5. 用户输入内容后，点击生成按钮。
+6. 系统拉起拼图游戏创作机制。
+7. 系统根据用户输入内容生成一个仅包含 1 关的拼图游戏。
+8. 生成完成后，页面浮现文字：`待定待定待定`。
+9. 用户进入当前生成的拼图游戏。
+10. 用户完成该拼图游戏的第 1 关。
+11. 页面浮现文字：`只差一步，就可以永久保留你的梦`。
+12. 文字下方展示注册账号/登录模块。
+13. 用户完成注册或登录。
+14. 系统进入产品首页。
+
+## 4. 文案
+
+| 位置 | 文案 |
+| --- | --- |
+| 首次启动浮现文案 | `待定待定待定` |
+| 输入框提示文字 | `把你的梦讲给我听吧` |
+| 生成完成浮现文案 | `待定待定待定` |
+| 完成拼图后的注册/登录引导文案 | `只差一步，就可以永久保留你的梦` |
+
+## 5. 范围边界
+
+1. 不增加跳过入口。
+2. 不定义额外功能说明文案。
+3. 不扩展拼图为多关。
+4. 不调整注册/登录后的去向，当前进入产品首页。
+5. 不新增未确认的 UI 动画、样式、奖励、埋点或保存策略。
+
+## 6. 验收标准
+
+1. 未登录首次访问产品时，进入新手引导首屏。
+2. 首屏展示确认文案、输入框和生成按钮。
+3. 用户输入内容并点击生成后，系统生成 1 关拼图。
+4. 生成完成后，用户可以进入该拼图并完成第 1 关。
+5. 第 1 关完成后，页面展示注册/登录引导文案和登录模块。
+6. 用户完成注册或登录后，进入产品首页。
+
+## 7. 落地接口与状态
+
+1. 首次访问判定由前端本地状态承载，未登录用户首次访问平台首页时展示；标记键为 `genarrative.puzzle-onboarding.first-visit.v1`。
+2. 临时生成入口为 `POST /api/runtime/puzzle/onboarding/generate`，不要求登录，只返回本次新手引导使用的 1 关拼图作品摘要与关卡数据。
+3. 登录后保存入口为 `POST /api/runtime/puzzle/onboarding/save`，要求登录；服务端为当前用户创建拼图 agent session，并把临时 1 关拼图保存为当前用户作品草稿。
+4. 新手引导游玩阶段复用现有本地拼图运行时，不新增 SpacetimeDB 表、reducer 或运行时真相。
+5. 保存完成后清空新手引导临时态，刷新拼图作品架，并回到产品首页。
--- a/docs/technical/MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md
+++ b/docs/technical/MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md
@@ -649,6 +649,8 @@ src/components/match3d-runtime/

 1. 名称：`抓大鹅`
 2. 子标题：`经典消除玩法`
+3. `src/config/newWorkEntryConfig.ts` 中 `match3d` 必须保持 `visible: true` 与 `open: true`，平台首屏卡带和创作类型弹层都从该配置派生，不允许只保留路由能力却隐藏创作入口。
+4. 入口点击后进入 `match3d-agent-workspace`，对应前端路径为 `/creation/match3d/agent`，并通过 `/api/creation/match3d/sessions` 创建正式 Agent 会话；如果公开广场读取失败，只降级广场列表，不能阻断或隐藏抓大鹅创作入口。

 ## 11.4 运行态 UI

--- a/docs/technical/MATCH3D_RUNTIME_3D_GEOMETRY_EXPERIMENT_2026-05-02.md
+++ b/docs/technical/MATCH3D_RUNTIME_3D_GEOMETRY_EXPERIMENT_2026-05-02.md
@@ -195,3 +195,58 @@ cannon-es
 4. 托盘仍使用共享 `WebGLRenderer`，继续按当前 `visualKey` 和尺寸关系生成同款模型；不得新增每格独立 renderer。
 5. 托盘缩放不能继续只按本局最大模型统一压缩所有物体；小尺寸模型需要保留最低可读显示尺寸，但仍不能改动场内真实尺寸、碰撞尺寸和后端权威尺寸。
 6. 备选栏单格高度可大于宽度，优先保证局内 3D 预览的识别面积；不得为了适配旧正方形格子把模型再次压小。
+
+## 16. 中心场地隐藏纵深与动态上顶
+
+2026-05-05 针对中心场地高数量局面穿模严重、消除后中下层物体长期陷在深处的问题，追加隐藏纵深与动态上顶表现修正。
+
+编码口径：
+
+1. 该纵深只存在于 3D 物理表现层，不修改锅体图案、锅壁模型、托盘表现、后端快照、点击权威判定、消除和胜负规则。
+2. 物体生成高度不再使用固定极小层级步长，而是按本局总物体数计算一个隐藏初始纵深；物体总量越大，初始逻辑纵深越深，用来减少大量放大后模型被挤进同一高度区间导致的穿模。
+3. 当前剩余场内物体数会动态缩短可用纵深；随着玩家持续消除，下层物体的目标高度逐步上移，表现为中下层物体陆续向上顶到表面层。
+4. 动态上顶只通过向上托举力和目标高度调整完成，不增加中心引力，不修改水平约束半径，不改变碰撞体尺寸倍率。
+5. 表面层高度保持稳定，避免越消除越显得物体掉进深处或视觉尺寸异常变小。
+
+## 17. 高数量局面物理稳定与动态锅容量
+
+2026-05-06 继续按方案 C 和方案 D 优化 `clearCount=100` 等高数量局面的稳定性。
+
+方案 C 编码口径：
+
+1. 只调整 3D 表现层的物理稳定参数，包括求解迭代次数、接触摩擦、接触弹性、线性阻尼、角阻尼、睡眠阈值和速度上限。
+2. 物体数量越大，物理世界越偏向高摩擦、低弹性和更强阻尼，减少大量物体同时生成后的持续弹跳、穿插和边界挤压。
+3. 速度保护只限制极端水平速度和垂直速度，不改物体位置生成规则、点击判定、备选栏、消除和胜负规则。
+
+方案 D 编码口径：
+
+1. 隐藏锅容量的纵深按本局总物体数，也就是用户配置的消除次数乘 `3` 后动态计算；消除次数越大，锅内容量纵深越深。
+2. 动态纵深只影响 3D 物理层的生成高度、目标层高度和消除后的上顶回补；锅底、锅壁、锅沿和 DOM 场地外观不随纵深变化。
+3. 高数量局面需要降低单层容量，让更多物体分散到纵向层级中，避免 `300` 个物体被压进少量高度层。
+4. 随着消除进度推进，当前可用纵深继续按剩余物体数收缩，确保下层物体逐步向表面回补，保持中心场地表层稳定可见。
+5. 本节不改变中心引力默认值，不改水平活动半径，不改碰撞体与视觉模型的尺寸一致性规则。
+
+## 18. 原型入场节奏与创建限流
+
+2026-05-07 根据原型视频补充创建过程优化。原型不是在同一帧把全部物体摆进容器，而是先短暂空场，再用连续小批量把物体投放到容器中，批与批之间留出自然沉降时间，最后再进入可操作局面。
+
+编码口径：
+
+1. 该优化只作用于前端 3D 表现层的物理 body 创建节奏，不改变后端快照、消除目标数量、点击权威判定、备选栏、三消和胜负规则。
+2. `totalItemCount < 30` 时保留较快创建节奏；`30 <= totalItemCount <= 50` 进入中速波次投放，降低每波数量并增加波次沉降窗口，避免最后一层物体压进尚未稳定的表层堆叠。
+3. `totalItemCount > 50` 后进入更强限流投放，单帧创建数量下降，避免同一帧把过多碰撞体塞入物理世界。
+4. 随着总物体数增加，投放初始等待、层级间隔和同层错峰间隔都要逐步变长，模拟原型中“持续落入、短暂沉降、继续补入”的节奏。
+5. `clearCount=100` 对应 `300` 个物体时，投放节奏应接近连续数秒完成，而不是在一秒左右完成全量创建。
+6. 该节不允许通过缩小碰撞体、扩大锅半径、开启中心引力或修改模型尺寸来掩盖穿模；如果后续仍需调整，只继续围绕创建节拍和物理沉降窗口处理。
+
+## 19. 生成高度避让已有堆叠
+
+2026-05-07 继续按方案 2 优化 `30` 件左右局面最后一层或最后一波物体仍会穿进已有堆叠的问题。
+
+编码口径：
+
+1. 该优化只作用于前端 3D 表现层的新物体创建高度，不改变后端快照、物品数量、模型尺寸、碰撞体尺寸、锅半径、点击判定、备选栏、三消和胜负规则。
+2. 新物体进入物理世界前，先根据当前同一水平区域附近已有物体的碰撞体顶部高度，计算一个不低于原计划高度的生成高度。
+3. 只有水平外接半径发生重叠的已有物体会影响本次生成高度；远处物体不能把新物体整体抬高，避免破坏原有随机洒落和分层节奏。
+4. 该避让只解决“直接创建在已有模型内部”的初始穿插，后续沉降、翻滚、堆叠仍交给 cannon-es 物理模拟。
+5. 本节不允许额外引入中心引力、扩大锅容量或修改模型生成规则；若后续仍需优化，只继续围绕生成高度、入场节拍和沉降窗口做局部迭代。
--- a/packages/shared/src/contracts/puzzleOnboarding.ts
+++ b/packages/shared/src/contracts/puzzleOnboarding.ts
@@ -0,0 +1,16 @@
+import type { PuzzleDraftLevel } from './puzzleAgentDraft';
+import type { PuzzleWorkSummary } from './puzzleWorkSummary';
+
+export interface PuzzleOnboardingGenerateRequest {
+  promptText: string;
+}
+
+export interface PuzzleOnboardingGenerateResponse {
+  item: PuzzleWorkSummary;
+  level: PuzzleDraftLevel;
+}
+
+export interface PuzzleOnboardingSaveRequest {
+  promptText: string;
+  item: PuzzleWorkSummary;
+}
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -10,6 +10,7 @@ export * from './contracts/match3dWorks';
 export * from './contracts/puzzleAgentActions';
 export * from './contracts/puzzleAgentDraft';
 export * from './contracts/puzzleAgentSession';
+export * from './contracts/puzzleOnboarding';
 export * from './contracts/puzzleResultPreview';
 export * from './contracts/puzzleRuntimeSession';
 export * from './contracts/puzzleWorkSummary';
--- a/server-rs/crates/api-server/src/app.rs
+++ b/server-rs/crates/api-server/src/app.rs
@@ -88,11 +88,12 @@ use crate::{
    puzzle::{
        advance_puzzle_next_level, claim_puzzle_work_point_incentive, create_puzzle_agent_session,
        delete_puzzle_work, drag_puzzle_piece_or_group, execute_puzzle_agent_action,
-        get_puzzle_agent_session, get_puzzle_gallery_detail, get_puzzle_run,
-        get_puzzle_work_detail, get_puzzle_works, list_puzzle_gallery, put_puzzle_work,
-        record_puzzle_gallery_like, remix_puzzle_gallery_work, start_puzzle_run,
-        stream_puzzle_agent_message, submit_puzzle_agent_message, submit_puzzle_leaderboard,
-        swap_puzzle_pieces, update_puzzle_run_pause, use_puzzle_runtime_prop,
+        generate_puzzle_onboarding_work, get_puzzle_agent_session, get_puzzle_gallery_detail,
+        get_puzzle_run, get_puzzle_work_detail, get_puzzle_works, list_puzzle_gallery,
+        put_puzzle_work, record_puzzle_gallery_like, remix_puzzle_gallery_work,
+        save_puzzle_onboarding_work, start_puzzle_run, stream_puzzle_agent_message,
+        submit_puzzle_agent_message, submit_puzzle_leaderboard, swap_puzzle_pieces,
+        update_puzzle_run_pause, use_puzzle_runtime_prop,
    },
    refresh_session::refresh_session,
    request_context::{attach_request_context, resolve_request_id},
@@ -1013,6 +1014,19 @@ pub fn build_router(state: AppState) -> Router {
                    require_bearer_auth,
                )),
        )
+        .route(
+            "/api/runtime/puzzle/onboarding/generate",
+            post(generate_puzzle_onboarding_work).layer(DefaultBodyLimit::max(
+                PUZZLE_REFERENCE_IMAGE_BODY_LIMIT_BYTES,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/onboarding/save",
+            post(save_puzzle_onboarding_work).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
        .route(
            "/api/runtime/puzzle/works",
            get(get_puzzle_works).route_layer(middleware::from_fn_with_state(
--- a/server-rs/crates/api-server/src/main.rs
+++ b/server-rs/crates/api-server/src/main.rs
@@ -72,12 +72,33 @@ mod work_author;

 use shared_logging::init_tracing;
 use tokio::net::TcpListener;
+use tokio::runtime::Builder as TokioRuntimeBuilder;
 use tracing::info;

 use crate::{app::build_router, config::AppConfig, state::AppState};

-#[tokio::main]
-async fn main() -> Result<(), std::io::Error> {
+const API_SERVER_STARTUP_STACK_SIZE_BYTES: usize = 32 * 1024 * 1024;
+
+fn main() -> Result<(), std::io::Error> {
+    // Windows 本地调试下 Axum 路由树和启动恢复链较重，显式放大启动线程栈，避免 debug 构建在进入监听前栈溢出。
+    std::thread::Builder::new()
+        .name("api-server-bootstrap".to_string())
+        .stack_size(API_SERVER_STARTUP_STACK_SIZE_BYTES)
+        .spawn(run_api_server_with_runtime)?
+        .join()
+        .map_err(|_| std::io::Error::other("api-server 启动线程异常退出"))?
+}
+
+fn run_api_server_with_runtime() -> Result<(), std::io::Error> {
+    TokioRuntimeBuilder::new_multi_thread()
+        .enable_all()
+        .thread_name("api-server-worker")
+        .thread_stack_size(API_SERVER_STARTUP_STACK_SIZE_BYTES)
+        .build()?
+        .block_on(run_api_server())
+}
+
+async fn run_api_server() -> Result<(), std::io::Error> {
    // 运行本地开发与联调时，优先从仓库根目录加载本地变量，避免手工逐项导出 OSS / APIMart 配置。
    let _ = dotenvy::from_filename(".env");
    let _ = dotenvy::from_filename(".env.local");
--- a/server-rs/crates/api-server/src/puzzle.rs
+++ b/server-rs/crates/api-server/src/puzzle.rs
@@ -45,7 +45,8 @@ use shared_contracts::{
        UsePuzzleRuntimePropRequest,
    },
    puzzle_works::{
-        PutPuzzleWorkRequest, PuzzleWorkDetailResponse, PuzzleWorkMutationResponse,
+        PutPuzzleWorkRequest, PuzzleOnboardingGenerateRequest, PuzzleOnboardingGenerateResponse,
+        PuzzleOnboardingSaveRequest, PuzzleWorkDetailResponse, PuzzleWorkMutationResponse,
        PuzzleWorkProfileResponse, PuzzleWorkSummaryResponse, PuzzleWorksResponse,
    },
 };
@@ -157,6 +158,222 @@ pub async fn create_puzzle_agent_session(
    ))
 }

+pub async fn generate_puzzle_onboarding_work(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    payload: Result<Json<PuzzleOnboardingGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_AGENT_API_BASE_PROVIDER,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    let prompt_text = payload.prompt_text.trim().to_string();
+    ensure_non_empty(
+        &request_context,
+        PUZZLE_AGENT_API_BASE_PROVIDER,
+        &prompt_text,
+        "promptText",
+    )?;
+
+    let now = current_utc_micros();
+    let session_id = build_prefixed_uuid_id("puzzle-onboarding-");
+    let level_name = generate_puzzle_first_level_name(&state, prompt_text.as_str()).await;
+    let tags = generate_puzzle_work_tags(&state, level_name.as_str(), prompt_text.as_str()).await;
+    let candidates = generate_puzzle_image_candidates(
+        &state,
+        "onboarding-guest",
+        session_id.as_str(),
+        level_name.as_str(),
+        prompt_text.as_str(),
+        None,
+        Some(PUZZLE_IMAGE_MODEL_GPT_IMAGE_2),
+        1,
+        0,
+    )
+    .await
+    .map_err(|error| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_AGENT_API_BASE_PROVIDER,
+            map_puzzle_generation_endpoint_error(error),
+        )
+    })?;
+    let selected = candidates.first().cloned().ok_or_else(|| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_AGENT_API_BASE_PROVIDER,
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
+                "message": "新手引导拼图图片生成结果为空",
+            })),
+        )
+    })?;
+    let level = PuzzleDraftLevelRecord {
+        level_id: "onboarding-level-1".to_string(),
+        level_name: level_name.clone(),
+        picture_description: prompt_text.clone(),
+        candidates,
+        selected_candidate_id: Some(selected.candidate_id.clone()),
+        cover_image_src: Some(selected.image_src.clone()),
+        cover_asset_id: Some(selected.asset_id.clone()),
+        generation_status: "ready".to_string(),
+    };
+    let anchor_pack = map_puzzle_domain_anchor_pack(module_puzzle::build_form_anchor_pack(
+        level_name.as_str(),
+        level.picture_description.as_str(),
+    ));
+    let item = PuzzleWorkProfileRecord {
+        work_id: format!("onboarding-work-{now}"),
+        profile_id: format!("onboarding-profile-{now}"),
+        owner_user_id: "onboarding-guest".to_string(),
+        source_session_id: None,
+        author_display_name: "百梦主".to_string(),
+        work_title: level_name.clone(),
+        work_description: prompt_text.clone(),
+        level_name,
+        summary: prompt_text,
+        theme_tags: tags,
+        cover_image_src: level.cover_image_src.clone(),
+        cover_asset_id: level.cover_asset_id.clone(),
+        publication_status: "draft".to_string(),
+        updated_at: format_timestamp_micros(now),
+        published_at: None,
+        play_count: 0,
+        remix_count: 0,
+        like_count: 0,
+        recent_play_count_7d: 0,
+        point_incentive_total_half_points: 0,
+        point_incentive_claimed_points: 0,
+        anchor_pack,
+        publish_ready: true,
+        levels: vec![level.clone()],
+    };
+
+    Ok(json_success_body(
+        Some(&request_context),
+        PuzzleOnboardingGenerateResponse {
+            item: map_puzzle_work_profile_response(&state, item.clone()).summary,
+            level: map_puzzle_draft_level_response(level),
+        },
+    ))
+}
+
+pub async fn save_puzzle_onboarding_work(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<PuzzleOnboardingSaveRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_WORKS_PROVIDER,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": PUZZLE_WORKS_PROVIDER,
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    let prompt_text = payload.prompt_text.trim().to_string();
+    ensure_non_empty(
+        &request_context,
+        PUZZLE_WORKS_PROVIDER,
+        &prompt_text,
+        "promptText",
+    )?;
+
+    let first_level = payload.item.levels.first().cloned().ok_or_else(|| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_WORKS_PROVIDER,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": PUZZLE_WORKS_PROVIDER,
+                "message": "新手引导拼图缺少可保存关卡",
+            })),
+        )
+    })?;
+    let levels_json = serialize_puzzle_levels_response(&request_context, &payload.item.levels)?;
+    let work_title = payload.item.work_title.trim();
+    let work_title = if work_title.is_empty() {
+        first_level.level_name.clone()
+    } else {
+        work_title.to_string()
+    };
+    let work_description = payload.item.work_description.trim();
+    let work_description = if work_description.is_empty() {
+        prompt_text.clone()
+    } else {
+        work_description.to_string()
+    };
+    let summary = payload.item.summary.trim();
+    let summary = if summary.is_empty() {
+        first_level.picture_description.clone()
+    } else {
+        summary.to_string()
+    };
+    let now = current_utc_micros();
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    let session_id = build_prefixed_uuid_id("puzzle-session-");
+    state
+        .spacetime_client()
+        .create_puzzle_agent_session(PuzzleAgentSessionCreateRecordInput {
+            session_id: session_id.clone(),
+            owner_user_id: owner_user_id.clone(),
+            seed_text: prompt_text.clone(),
+            welcome_message_id: build_prefixed_uuid_id("puzzle-message-"),
+            welcome_message_text: build_puzzle_welcome_text(&prompt_text),
+            created_at_micros: now,
+        })
+        .await
+        .map_err(|error| {
+            puzzle_error_response(
+                &request_context,
+                PUZZLE_WORKS_PROVIDER,
+                map_puzzle_client_error(error),
+            )
+        })?;
+
+    let (_, profile_id) = build_stable_puzzle_work_ids(session_id.as_str());
+    let item = state
+        .spacetime_client()
+        .update_puzzle_work(PuzzleWorkUpsertRecordInput {
+            profile_id,
+            owner_user_id,
+            work_title,
+            work_description,
+            level_name: first_level.level_name,
+            summary,
+            theme_tags: payload.item.theme_tags,
+            cover_image_src: first_level.cover_image_src,
+            cover_asset_id: first_level.cover_asset_id,
+            levels_json: Some(levels_json),
+            updated_at_micros: now,
+        })
+        .await
+        .map_err(|error| {
+            puzzle_error_response(
+                &request_context,
+                PUZZLE_WORKS_PROVIDER,
+                map_puzzle_client_error(error),
+            )
+        })?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        PuzzleWorkMutationResponse {
+            item: map_puzzle_work_profile_response(&state, item),
+        },
+    ))
+}
+
 pub async fn get_puzzle_agent_session(
    State(state): State<AppState>,
    AxumPath(session_id): AxumPath<String>,
--- a/server-rs/crates/platform-oss/README.md
+++ b/server-rs/crates/platform-oss/README.md
@@ -34,6 +34,8 @@
 1. 当前产品口径为服务器上传 AI 生成资源、Web 端只负责读取。
 2. 因此 `STS` 不作为默认上传主链，`api-server` 只暴露禁用式 contract，避免浏览器拿到 OSS 写权限。
 3. 服务端生成资源应优先复用 `OssClient::put_object`，上传成功后再走对象确认链路写入 `asset_object`。
+    4. 读签名和 `HEAD Object` 的入参必须直接传 object_key，不要把 bucket 名拼进路径；例如 `generated-square-hole-assets/.../image.png` 才是正确入参，`xushi-dev/...` 这类前缀不属于 object_key。
+    5. OSS V4 `x-oss-date` 必须固定为 `yyyyMMdd'T'HHmmss'Z'`，不能依赖 `time::Time::to_string()`；后者在小时小于 10 时可能输出非补零时间，导致签名格式错误。

 ## 3. 边界约束

--- a/server-rs/crates/platform-oss/src/lib.rs
+++ b/server-rs/crates/platform-oss/src/lib.rs
@@ -419,8 +419,11 @@ impl OssClient {
        let policy = serde_json::to_string(&policy_json)
            .map_err(|error| OssError::SerializePolicy(format!("序列化 policy 失败：{error}")))?;
        let encoded_policy = BASE64_STANDARD.encode(policy.as_bytes());
-        let signature =
-            sign_v4_content(&self.config.access_key_secret, &signature_scope, &encoded_policy)?;
+        let signature = sign_v4_content(
+            &self.config.access_key_secret,
+            &signature_scope,
+            &encoded_policy,
+        )?;

        Ok(OssPostObjectResponse {
            signature_version: "v4",
@@ -492,11 +495,8 @@ impl OssClient {
        let canonical_uri = build_v4_canonical_uri(&self.config.bucket, Some(&object_key));
        let object_url_path = format!("/{}", encode_url_path(&object_key));
        let additional_headers = "host";
-        let canonical_headers = format!(
-            "host:{}.{}\n",
-            self.config.bucket(),
-            self.config.endpoint()
-        );
+        let canonical_headers =
+            format!("host:{}.{}\n", self.config.bucket(), self.config.endpoint());
        let canonical_query = build_canonical_query_string(&query);
        let canonical_request = build_v4_canonical_request(
            Method::GET.as_str(),
@@ -506,10 +506,16 @@ impl OssClient {
            additional_headers,
            OSS_UNSIGNED_PAYLOAD,
        );
-        let string_to_sign =
-            build_v4_string_to_sign(query["x-oss-date"].as_str(), &signature_scope, &canonical_request);
-        let signature =
-            sign_v4_content(&self.config.access_key_secret, &signature_scope, &string_to_sign)?;
+        let string_to_sign = build_v4_string_to_sign(
+            query["x-oss-date"].as_str(),
+            &signature_scope,
+            &canonical_request,
+        );
+        let signature = sign_v4_content(
+            &self.config.access_key_secret,
+            &signature_scope,
+            &string_to_sign,
+        )?;
        query.insert("x-oss-signature".to_string(), signature);
        let signed_url = format!(
            "{}{}?{}",
@@ -1036,8 +1042,13 @@ fn signed_request_builder(
        additional_headers,
        &body_sha256,
    );
-    let string_to_sign = build_v4_string_to_sign(&signed_at_text, &signature_scope, &canonical_request);
-    let signature = sign_v4_content(config.access_key_secret(), &signature_scope, &string_to_sign)?;
+    let string_to_sign =
+        build_v4_string_to_sign(&signed_at_text, &signature_scope, &canonical_request);
+    let signature = sign_v4_content(
+        config.access_key_secret(),
+        &signature_scope,
+        &string_to_sign,
+    )?;
    let mut builder = client
        .request(method, target_url)
        .header("x-oss-content-sha256", body_sha256)
@@ -1065,33 +1076,23 @@ fn signed_request_builder(
 }

 fn build_v4_signature_scope(endpoint: &str, signed_at: OffsetDateTime) -> Result<String, OssError> {
-    let date = signed_at
-        .date()
-        .to_string()
-        .replace('-', "");
+    let date = signed_at.date().to_string().replace('-', "");
    let region = extract_oss_region(endpoint)?;

    Ok(format!("{date}/{region}/{OSS_V4_SERVICE}/{OSS_V4_REQUEST}"))
 }

 fn build_v4_signature_date(signed_at: OffsetDateTime) -> Result<String, OssError> {
-    let date = signed_at
-        .date()
-        .to_string()
-        .replace('-', "");
-    let time = signed_at
-        .time()
-        .to_string()
-        .split('.')
-        .next()
-        .unwrap_or("00:00:00")
-        .replace(':', "");
-
-    if time.len() != 6 {
-        return Err(OssError::Sign("OSS V4 签名时间格式化失败".to_string()));
-    }
-
-    Ok(format!("{date}T{time}Z"))
+    // 中文注释：time::Time 的 Display 在小时小于 10 时不会稳定补零，OSS V4 必须使用固定宽度 UTC 时间。
+    Ok(format!(
+        "{:04}{:02}{:02}T{:02}{:02}{:02}Z",
+        signed_at.year(),
+        u8::from(signed_at.month()),
+        signed_at.day(),
+        signed_at.hour(),
+        signed_at.minute(),
+        signed_at.second()
+    ))
 }

 fn build_v4_canonical_uri(bucket: &str, object_key: Option<&str>) -> String {
@@ -1116,9 +1117,7 @@ fn extract_oss_region(endpoint: &str) -> Result<String, OssError> {
        .map(str::to_string)
        .filter(|region| !region.is_empty())
        .ok_or_else(|| {
-            OssError::InvalidConfig(format!(
-                "OSS endpoint 无法解析 region，当前值：{endpoint}"
-            ))
+            OssError::InvalidConfig(format!("OSS endpoint 无法解析 region，当前值：{endpoint}"))
        })
 }

@@ -1131,7 +1130,10 @@ fn sign_v4_content(
    Ok(hex_sha256_hmac(&signing_key, content.as_bytes()))
 }

-fn build_v4_signing_key(access_key_secret: &str, signature_scope: &str) -> Result<Vec<u8>, OssError> {
+fn build_v4_signing_key(
+    access_key_secret: &str,
+    signature_scope: &str,
+) -> Result<Vec<u8>, OssError> {
    let mut parts = signature_scope.split('/');
    let date = parts
        .next()
@@ -1160,8 +1162,7 @@ fn hmac_sha256_raw(key: &[u8], content: &str) -> Result<Vec<u8>, OssError> {
 }

 fn hex_sha256_hmac(key: &[u8], content: &[u8]) -> String {
-    let mut signer = HmacSha256::new_from_slice(key)
-        .expect("HMAC-SHA256 accepts keys of any size");
+    let mut signer = HmacSha256::new_from_slice(key).expect("HMAC-SHA256 accepts keys of any size");
    signer.update(content);
    hex_lower(&signer.finalize().into_bytes())
 }
@@ -1213,7 +1214,13 @@ fn build_v4_canonical_headers(headers: &BTreeMap<String, String>) -> String {
 fn build_canonical_query_string(params: &BTreeMap<String, String>) -> String {
    params
        .iter()
-        .map(|(key, value)| format!("{}={}", encode_url_query_value(key), encode_url_query_value(value)))
+        .map(|(key, value)| {
+            format!(
+                "{}={}",
+                encode_url_query_value(key),
+                encode_url_query_value(value)
+            )
+        })
        .collect::<Vec<_>>()
        .join("&")
 }
@@ -1327,18 +1334,19 @@ mod tests {
            response.form_fields.signature_version,
            OSS_V4_ALGORITHM.to_string()
        );
-        assert!(response
-            .form_fields
-            .credential
-            .starts_with("test-access-key-id/"));
-        assert!(response
-            .form_fields
-            .credential
-            .ends_with("/cn-shanghai/oss/aliyun_v4_request"));
-        assert_eq!(
-            response.form_fields.date.len(),
-            "20260507T120000Z".len()
+        assert!(
+            response
+                .form_fields
+                .credential
+                .starts_with("test-access-key-id/")
        );
+        assert!(
+            response
+                .form_fields
+                .credential
+                .ends_with("/cn-shanghai/oss/aliyun_v4_request")
+        );
+        assert_eq!(response.form_fields.date.len(), "20260507T120000Z".len());
        assert_eq!(
            response.form_fields.metadata.get("x-oss-meta-asset-kind"),
            Some(&"character-visual".to_string())
@@ -1441,13 +1449,48 @@ mod tests {
                .signed_url
                .contains("x-oss-signature-version=OSS4-HMAC-SHA256")
        );
-        assert!(response
-            .signed_url
-            .contains("x-oss-credential=test-access-key-id%2F"));
+        assert!(
+            response
+                .signed_url
+                .contains("x-oss-credential=test-access-key-id%2F")
+        );
        assert!(response.signed_url.contains("&x-oss-expires=300"));
        assert!(response.signed_url.contains("&x-oss-signature="));
    }

+    #[test]
+    fn sign_get_object_url_uses_square_hole_object_key_without_bucket_prefix() {
+        let client = OssClient::new(
+            OssConfig::new(
+                "xushi-dev".to_string(),
+                "oss-cn-shanghai.aliyuncs.com".to_string(),
+                "test-access-key-id".to_string(),
+                "test-access-key-secret".to_string(),
+                DEFAULT_READ_EXPIRE_SECONDS,
+                DEFAULT_POST_EXPIRE_SECONDS,
+                DEFAULT_POST_MAX_SIZE_BYTES,
+                DEFAULT_SUCCESS_ACTION_STATUS,
+            )
+            .expect("OSS config should be valid"),
+        );
+
+        let response = client
+            .sign_get_object_url(OssSignedGetObjectUrlRequest {
+                object_key: "generated-square-hole-assets/square-hole-session-546d881972684be2980a2a882cd0cc71/square-hole-profile-134411276ce1469cbe398f946a25d7f8/square-hole-shape-image/rabbit-option/asset-1777979289912039/image.png".to_string(),
+                expire_seconds: Some(300),
+            })
+            .expect("square hole object key should build signed url");
+
+        assert_eq!(response.bucket, "xushi-dev".to_string());
+        assert_eq!(
+            response.object_key,
+            "generated-square-hole-assets/square-hole-session-546d881972684be2980a2a882cd0cc71/square-hole-profile-134411276ce1469cbe398f946a25d7f8/square-hole-shape-image/rabbit-option/asset-1777979289912039/image.png".to_string()
+        );
+        assert!(response
+            .signed_url
+            .starts_with("https://xushi-dev.oss-cn-shanghai.aliyuncs.com/generated-square-hole-assets/square-hole-session-546d881972684be2980a2a882cd0cc71/square-hole-profile-134411276ce1469cbe398f946a25d7f8/square-hole-shape-image/rabbit-option/asset-1777979289912039/image.png?"));
+    }
+
    #[test]
    fn sign_get_object_url_rejects_unsupported_prefix() {
        let client = build_client();
--- a/server-rs/crates/shared-contracts/src/puzzle_works.rs
+++ b/server-rs/crates/shared-contracts/src/puzzle_works.rs
@@ -127,3 +127,23 @@ pub struct PuzzleWorkDetailResponse {
 pub struct PuzzleWorkMutationResponse {
    pub item: PuzzleWorkProfileResponse,
 }
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleOnboardingGenerateRequest {
+    pub prompt_text: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleOnboardingGenerateResponse {
+    pub item: PuzzleWorkSummaryResponse,
+    pub level: PuzzleDraftLevelResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleOnboardingSaveRequest {
+    pub prompt_text: String,
+    pub item: PuzzleWorkSummaryResponse,
+}
--- a/src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx
+++ b/src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx
@@ -87,14 +87,16 @@ const baseDraftItem: CustomWorldWorkSummary = {
  canEnterWorld: false,
 };

-test('creation hub reflects updated draft title summary and counts after rerender', () => {
+test('creation hub reflects updated draft title summary and counts after rerender', async () => {
+  const user = userEvent.setup();
+  const onCreateType = vi.fn();
  const { rerender } = render(
    <CustomWorldCreationHub
      items={[baseDraftItem]}
      loading={false}
      error={null}
      onRetry={() => {}}
-      onCreateType={noopCreateType}
+      onCreateType={onCreateType}
      onOpenDraft={() => {}}
      onEnterPublished={() => {}}
    />,
@@ -105,14 +107,21 @@ test('creation hub reflects updated draft title summary and counts after rerende
  expect(screen.queryByText('角色 3')).toBeNull();
  expect(screen.queryByText('地点 4')).toBeNull();
  const puzzleButton = screen.getByRole('button', { name: /拼图.*创意礼物/u });
+  const match3dButton = screen.getByRole('button', {
+    name: /抓大鹅.*经典消除玩法/u,
+  });
  const squareHoleButton = screen.getByRole('button', { name: /方洞挑战/u });
  expect((squareHoleButton as HTMLButtonElement).disabled).toBe(false);
  expect(puzzleButton).toBeTruthy();
+  expect(match3dButton).toBeTruthy();
  expect((puzzleButton as HTMLButtonElement).disabled).toBe(false);
+  expect((match3dButton as HTMLButtonElement).disabled).toBe(false);
  expect(screen.getByText('反直觉形状分拣')).toBeTruthy();
  expect(screen.queryByRole('button', { name: /角色扮演/u })).toBeNull();
  expect(screen.queryByRole('button', { name: /大鱼吃小鱼/u })).toBeNull();
-  expect(screen.queryByRole('button', { name: /抓大鹅/u })).toBeNull();
+
+  await user.click(match3dButton);
+  expect(onCreateType).toHaveBeenCalledWith('match3d');

  rerender(
    <CustomWorldCreationHub
--- a/src/components/custom-world-home/CustomWorldCreationHub.test.tsx
+++ b/src/components/custom-world-home/CustomWorldCreationHub.test.tsx
@@ -44,9 +44,10 @@ test('creation hub draft card renders compiled work summary fields', () => {
  expect(html).toContain('守灯会与沉船商盟争夺航道解释权');
  expect(html).toContain('拼图');
  expect(html).toContain('创意礼物，生活分享');
+  expect(html).toContain('抓大鹅');
+  expect(html).toContain('经典消除玩法');
  expect(html).not.toContain('角色扮演');
  expect(html).not.toContain('大鱼吃小鱼');
-  expect(html).not.toContain('抓大鹅');
 });

 test('creation hub renders puzzle works in the same unified list with puzzle tag', () => {
--- a/src/components/match3d-runtime/Match3DPhysicsBoard.tsx
+++ b/src/components/match3d-runtime/Match3DPhysicsBoard.tsx
@@ -32,34 +32,116 @@ type ThreeRenderer = import('three').WebGLRenderer;
 type ThreeCamera = import('three').OrthographicCamera;

 type PhysicsEntry = {
+  boundaryRadius: number;
+  colliderHeight: number;
  item: Match3DItemSnapshot;
  body: PhysicsBody;
  lockReadableTop: boolean;
  mesh: ThreeObject3D;
  renderSignature: string;
+  spawnStartedAt: number;
+  targetY: number;
  topRotationY: number;
 };

+type PendingPhysicsSpawn = {
+  activeLayerRank: number;
+  item: Match3DItemSnapshot;
+  renderSignature: string;
+  spawnAtMs: number;
+  layerCapacity: number;
+  targetY: number;
+};
+
+type StackHeightTarget = {
+  activeLayerRank: number;
+  targetY: number;
+};
+
+type BoardDepthPlan = {
+  activeDepth: number;
+  activeItemCount: number;
+  baseY: number;
+  initialDepth: number;
+  layerCapacity: number;
+  layerCount: number;
+  layerStep: number;
+  maxVerticalSpeed: number;
+  surfaceY: number;
+};
+
+type PhysicsStabilityPlan = {
+  angularDamping: number;
+  contactFriction: number;
+  contactRestitution: number;
+  linearDamping: number;
+  maxHorizontalSpeed: number;
+  maxVerticalSpeed: number;
+  solverIterations: number;
+  solverTolerance: number;
+};
+
+type Match3DSpawnTimingPlan = {
+  frameSpawnLimit: number;
+  initialDelayMs: number;
+  layerDelayMs: number;
+  burstSize: number;
+  staggerMs: number;
+};
+
+type Match3DSpawnHeightObstacle = {
+  boundaryRadius: number;
+  colliderHeight: number;
+  x: number;
+  y: number;
+  z: number;
+};
+
 type PhysicsRuntime = {
  animationId: number | null;
  camera: ThreeCamera;
  entries: Map<string, PhysicsEntry>;
+  pendingSpawns: Map<string, PendingPhysicsSpawn>;
  raycaster: import('three').Raycaster;
  renderer: ThreeRenderer;
  scene: ThreeScene;
+  spawnTimingPlan: Match3DSpawnTimingPlan;
+  stabilityPlan: PhysicsStabilityPlan;
  world: PhysicsWorld;
  three: ThreeModule;
  cannon: CannonModule;
 };

+type Match3DStackHeightPlan = {
+  layerCapacity: number;
+  targets: Map<string, StackHeightTarget>;
+};
+
 const MATCH3D_POT_FLOOR_RADIUS = 4.75;
 const MATCH3D_POT_INNER_RADIUS = 4.52;
 const MATCH3D_POT_OUTER_RADIUS = 5.18;
 const MATCH3D_POT_WALL_HEIGHT = 2.15;
 const MATCH3D_ITEM_ACTIVITY_RADIUS = 3.58;
 const MATCH3D_ITEM_POSITION_RADIUS = 3.34;
-const MATCH3D_ITEM_SPAWN_HEIGHT = 1.25;
-const MATCH3D_ITEM_STACK_HEIGHT_STEP = 0.024;
+const MATCH3D_ITEM_BASE_HEIGHT = 1.18;
+const MATCH3D_ITEM_VERTICAL_DEPTH_BASE = 2.8;
+const MATCH3D_ITEM_VERTICAL_DEPTH_SQRT_SCALE = 0.52;
+const MATCH3D_ITEM_VERTICAL_DEPTH_COUNT_SCALE = 0.032;
+const MATCH3D_ITEM_VERTICAL_DEPTH_MAX_BASE = 12;
+const MATCH3D_ITEM_VERTICAL_DEPTH_MAX_COUNT_SCALE = 0.04;
+const MATCH3D_ITEM_VERTICAL_LAYER_CAPACITY_BASE = 18;
+const MATCH3D_ITEM_VERTICAL_LAYER_CAPACITY_MIN = 10;
+const MATCH3D_ITEM_VERTICAL_LAYER_STEP_MAX = 1.04;
+const MATCH3D_ITEM_LIFT_FORCE_SCALE = 18;
+const MATCH3D_ITEM_LIFT_MAX_SPEED = 4.2;
+const MATCH3D_ITEM_SPAWN_RISE_OFFSET = 0.42;
+const MATCH3D_ITEM_SPAWN_LAYER_DELAY_MS = 54;
+const MATCH3D_ITEM_SPAWN_STAGGER_MS = 4;
+const MATCH3D_ITEM_SPAWN_STACK_CLEARANCE = 0.14;
+const MATCH3D_ITEM_SPAWN_STACK_RADIUS_PADDING = 0.08;
+const MATCH3D_ITEM_SPAWN_ANIMATION_MS = 260;
+const MATCH3D_ITEM_EXTREME_VERTICAL_SPEED_LIMIT = 8.6;
+const MATCH3D_ITEM_EXTREME_HORIZONTAL_SPEED_LIMIT = 4.4;
 const MATCH3D_CENTER_GRAVITY_COEFFICIENT = 0;
 const MATCH3D_BOARD_CENTER = 0.5;
 const MATCH3D_PHYSICS_STEP = 1 / 60;
@@ -100,12 +182,350 @@ function toWorldPosition(item: Match3DItemSnapshot) {
  };
 }

+export function resolveMatch3DBoardDepthPlan(
+  totalItemCount: number,
+  activeItemCount: number,
+): BoardDepthPlan {
+  const normalizedTotalItemCount = Math.max(
+    1,
+    Math.round(Number.isFinite(totalItemCount) ? totalItemCount : 1),
+  );
+  const normalizedActiveItemCount = Math.max(
+    0,
+    Math.min(
+      normalizedTotalItemCount,
+      Math.round(Number.isFinite(activeItemCount) ? activeItemCount : 0),
+    ),
+  );
+  const volumePressure = Math.max(0, normalizedTotalItemCount - 90);
+  const depthMax =
+    MATCH3D_ITEM_VERTICAL_DEPTH_MAX_BASE +
+    volumePressure * MATCH3D_ITEM_VERTICAL_DEPTH_MAX_COUNT_SCALE;
+  const initialDepth = Math.min(
+    depthMax,
+    MATCH3D_ITEM_VERTICAL_DEPTH_BASE +
+      Math.sqrt(normalizedTotalItemCount) *
+        MATCH3D_ITEM_VERTICAL_DEPTH_SQRT_SCALE +
+      normalizedTotalItemCount * MATCH3D_ITEM_VERTICAL_DEPTH_COUNT_SCALE,
+  );
+  const remainingRatio =
+    normalizedActiveItemCount / normalizedTotalItemCount;
+  const activeDepth =
+    normalizedActiveItemCount <= 1 ? 0 : initialDepth * remainingRatio;
+  const pressureRatio = Math.min(1, volumePressure / 210);
+  const layerCapacity = Math.max(
+    MATCH3D_ITEM_VERTICAL_LAYER_CAPACITY_MIN,
+    Math.round(
+      MATCH3D_ITEM_VERTICAL_LAYER_CAPACITY_BASE - pressureRatio * 8,
+    ),
+  );
+  const layerCount = Math.max(
+    1,
+    Math.ceil(normalizedActiveItemCount / layerCapacity),
+  );
+  const layerStep =
+    layerCount <= 1
+      ? 0
+      : Math.min(
+          MATCH3D_ITEM_VERTICAL_LAYER_STEP_MAX,
+          activeDepth / Math.max(1, layerCount - 1),
+        );
+
+  return {
+    activeDepth,
+    activeItemCount: normalizedActiveItemCount,
+    baseY: MATCH3D_ITEM_BASE_HEIGHT,
+    initialDepth,
+    layerCapacity,
+    layerCount,
+    layerStep,
+    maxVerticalSpeed:
+      MATCH3D_ITEM_EXTREME_VERTICAL_SPEED_LIMIT + pressureRatio * 2.4,
+    surfaceY: MATCH3D_ITEM_BASE_HEIGHT + initialDepth,
+  };
+}
+
+export function resolveMatch3DStackTargetY(
+  totalItemCount: number,
+  activeItemCount: number,
+  activeLayerRank: number,
+) {
+  const depthPlan = resolveMatch3DBoardDepthPlan(
+    totalItemCount,
+    activeItemCount,
+  );
+  if (depthPlan.activeItemCount <= 1) {
+    return depthPlan.surfaceY;
+  }
+  const clampedRank = Math.max(
+    0,
+    Math.min(depthPlan.activeItemCount - 1, activeLayerRank),
+  );
+  const layerIndex = Math.floor(
+    (clampedRank / Math.max(1, depthPlan.activeItemCount - 1)) *
+      (depthPlan.layerCount - 1),
+  );
+
+  return (
+    depthPlan.surfaceY -
+    (depthPlan.layerCount - 1 - layerIndex) * depthPlan.layerStep
+  );
+}
+
+export function resolveMatch3DBoundaryRadius(
+  asset: Match3DGeometryAsset,
+  radius: number,
+) {
+  const bounds = resolveMatch3DColliderBounds(asset, radius);
+  return Math.hypot(bounds.width / 2, bounds.depth / 2);
+}
+
+export function resolveMatch3DSpawnY(
+  plannedSpawnY: number,
+  colliderHeight: number,
+  boundaryRadius: number,
+  position: Pick<Match3DSpawnHeightObstacle, 'x' | 'z'>,
+  obstacles: readonly Match3DSpawnHeightObstacle[],
+) {
+  const normalizedPlannedY = Number.isFinite(plannedSpawnY)
+    ? plannedSpawnY
+    : MATCH3D_ITEM_BASE_HEIGHT;
+  const selfHalfHeight = Math.max(0, colliderHeight / 2);
+  const selfBoundaryRadius = Math.max(0, boundaryRadius);
+
+  return obstacles.reduce((spawnY, obstacle) => {
+    const horizontalDistance = Math.hypot(
+      position.x - obstacle.x,
+      position.z - obstacle.z,
+    );
+    const overlapDistance =
+      selfBoundaryRadius +
+      Math.max(0, obstacle.boundaryRadius) +
+      MATCH3D_ITEM_SPAWN_STACK_RADIUS_PADDING;
+    if (horizontalDistance > overlapDistance) {
+      return spawnY;
+    }
+
+    // 中文注释：新物体生成时先避开同位置已有堆叠顶部，避免最后一波直接塞进未稳定的上层模型。
+    const obstacleTopY =
+      obstacle.y + Math.max(0, obstacle.colliderHeight) / 2;
+    return Math.max(
+      spawnY,
+      obstacleTopY + selfHalfHeight + MATCH3D_ITEM_SPAWN_STACK_CLEARANCE,
+    );
+  }, normalizedPlannedY);
+}
+
+export function resolveMatch3DSpawnDelay(
+  activeLayerRank: number,
+  layerCapacity = MATCH3D_ITEM_VERTICAL_LAYER_CAPACITY_BASE,
+  timingPlan?: Pick<
+    Match3DSpawnTimingPlan,
+    'burstSize' | 'layerDelayMs' | 'staggerMs'
+  >,
+) {
+  const normalizedLayerCapacity = Math.max(1, layerCapacity);
+  const normalizedLayerRank = Math.max(0, activeLayerRank);
+  const layerDelayMs =
+    timingPlan?.layerDelayMs ?? MATCH3D_ITEM_SPAWN_LAYER_DELAY_MS;
+  const staggerMs = timingPlan?.staggerMs ?? MATCH3D_ITEM_SPAWN_STAGGER_MS;
+  const burstSize = Math.max(
+    1,
+    timingPlan?.burstSize ?? normalizedLayerCapacity,
+  );
+  const layerIndex = Math.floor(
+    normalizedLayerRank / normalizedLayerCapacity,
+  );
+  const burstIndex = Math.floor(normalizedLayerRank / burstSize);
+  return (
+    Math.max(layerIndex, burstIndex) * layerDelayMs +
+    (normalizedLayerRank % burstSize) * staggerMs
+  );
+}
+
+export function resolveMatch3DSpawnTimingPlan(
+  totalItemCount: number,
+): Match3DSpawnTimingPlan {
+  const normalizedTotalItemCount = Math.max(
+    1,
+    Math.round(Number.isFinite(totalItemCount) ? totalItemCount : 1),
+  );
+  const crowdPressureRatio = Math.min(
+    1,
+    Math.max(0, normalizedTotalItemCount - 50) / 250,
+  );
+  const highCrowdRatio = Math.pow(crowdPressureRatio, 0.82);
+  const midCrowdRatio = Math.min(
+    1,
+    Math.max(0, normalizedTotalItemCount - 30) / 20,
+  );
+
+  return {
+    frameSpawnLimit:
+      normalizedTotalItemCount < 30
+        ? 4
+        : normalizedTotalItemCount <= 120
+          ? 2
+          : 1,
+    initialDelayMs: Math.round(
+      normalizedTotalItemCount < 30
+        ? 220
+        : normalizedTotalItemCount <= 50
+          ? 240 + midCrowdRatio * 40
+          : 260 + highCrowdRatio * 140,
+    ),
+    layerDelayMs: Math.round(
+      normalizedTotalItemCount < 30
+        ? MATCH3D_ITEM_SPAWN_LAYER_DELAY_MS
+        : normalizedTotalItemCount <= 50
+          ? 96 + midCrowdRatio * 24
+          : 110 + highCrowdRatio * 50,
+    ),
+    burstSize:
+      normalizedTotalItemCount < 30
+        ? 8
+        : normalizedTotalItemCount <= 50
+          ? 5
+          : normalizedTotalItemCount <= 120
+            ? 7
+            : 6,
+    staggerMs: Math.round(
+      normalizedTotalItemCount < 30
+        ? MATCH3D_ITEM_SPAWN_STAGGER_MS
+        : normalizedTotalItemCount <= 50
+          ? 9 + midCrowdRatio * 3
+          : 12 + highCrowdRatio * 6,
+    ),
+  };
+}
+
+function buildMatch3DStackHeightTargets(
+  run: Match3DRunSnapshot,
+): Match3DStackHeightPlan {
+  const activeItems = run.items
+    .filter((item) => isItemState(item.state, 'in_board'))
+    .sort((left, right) => {
+      if (left.layer !== right.layer) {
+        return left.layer - right.layer;
+      }
+      return left.itemInstanceId.localeCompare(right.itemInstanceId);
+    });
+  const targets = new Map<string, StackHeightTarget>();
+  const depthPlan = resolveMatch3DBoardDepthPlan(
+    run.totalItemCount,
+    activeItems.length,
+  );
+  activeItems.forEach((item, activeLayerRank) => {
+    targets.set(
+      item.itemInstanceId,
+      {
+        activeLayerRank,
+        targetY: resolveMatch3DStackTargetY(
+          run.totalItemCount,
+          activeItems.length,
+          activeLayerRank,
+        ),
+      },
+    );
+  });
+  return {
+    layerCapacity: depthPlan.layerCapacity,
+    targets,
+  };
+}
+
+export function resolveMatch3DPhysicsStabilityPlan(
+  totalItemCount: number,
+): PhysicsStabilityPlan {
+  const normalizedTotalItemCount = Math.max(
+    1,
+    Math.round(Number.isFinite(totalItemCount) ? totalItemCount : 1),
+  );
+  const pressureRatio = Math.min(
+    1,
+    Math.max(0, normalizedTotalItemCount - 90) / 210,
+  );
+
+  return {
+    angularDamping: 0.48 + pressureRatio * 0.18,
+    contactFriction: 0.55 + pressureRatio * 0.22,
+    contactRestitution: 0.28 - pressureRatio * 0.14,
+    linearDamping: 0.38 + pressureRatio * 0.2,
+    maxHorizontalSpeed:
+      MATCH3D_ITEM_EXTREME_HORIZONTAL_SPEED_LIMIT - pressureRatio * 0.9,
+    maxVerticalSpeed:
+      MATCH3D_ITEM_EXTREME_VERTICAL_SPEED_LIMIT + pressureRatio * 2.4,
+    solverIterations: Math.round(10 + pressureRatio * 8),
+    solverTolerance: 0.001 - pressureRatio * 0.0006,
+  };
+}
+
+function applyDynamicStackLift(entry: PhysicsEntry) {
+  const liftDistance = entry.targetY - entry.body.position.y;
+  if (liftDistance <= 0.04) {
+    return;
+  }
+  const liftSpeed = Math.min(
+    MATCH3D_ITEM_LIFT_MAX_SPEED,
+    Math.max(0.7, liftDistance * 1.8),
+  );
+
+  // 中文注释：纵深只作为隐藏的表现层支撑；消除后给低层物体向上的托举，避免它们长期陷在锅底。
+  entry.body.force.y +=
+    entry.body.mass * liftDistance * MATCH3D_ITEM_LIFT_FORCE_SCALE;
+  entry.body.velocity.y = Math.max(entry.body.velocity.y, liftSpeed);
+  entry.body.wakeUp();
+}
+
+function applyStabilityPlanToBody(
+  entry: PhysicsEntry,
+  stabilityPlan: PhysicsStabilityPlan,
+) {
+  const horizontalSpeed = Math.hypot(
+    entry.body.velocity.x,
+    entry.body.velocity.z,
+  );
+  if (horizontalSpeed > stabilityPlan.maxHorizontalSpeed) {
+    const ratio = stabilityPlan.maxHorizontalSpeed / horizontalSpeed;
+    entry.body.velocity.x *= ratio;
+    entry.body.velocity.z *= ratio;
+  }
+  entry.body.velocity.y = Math.max(
+    -stabilityPlan.maxVerticalSpeed,
+    Math.min(stabilityPlan.maxVerticalSpeed, entry.body.velocity.y),
+  );
+}
+
+function syncRuntimeStabilityPlan(
+  runtime: PhysicsRuntime,
+  totalItemCount: number,
+) {
+  const stabilityPlan = resolveMatch3DPhysicsStabilityPlan(totalItemCount);
+  runtime.stabilityPlan = stabilityPlan;
+  runtime.world.defaultContactMaterial.friction =
+    stabilityPlan.contactFriction;
+  runtime.world.defaultContactMaterial.restitution =
+    stabilityPlan.contactRestitution;
+  const solver = runtime.world.solver as import('cannon-es').GSSolver;
+  solver.iterations = stabilityPlan.solverIterations;
+  solver.tolerance = stabilityPlan.solverTolerance;
+
+  runtime.entries.forEach((entry) => {
+    entry.body.angularDamping = stabilityPlan.angularDamping;
+    entry.body.linearDamping = stabilityPlan.linearDamping;
+    entry.body.sleepSpeedLimit = Math.max(
+      0.08,
+      0.16 - Math.min(1, totalItemCount / 300) * 0.05,
+    );
+    entry.body.sleepTimeLimit = 0.18;
+  });
+}
+
 function constrainBodyInsidePot(entry: PhysicsEntry) {
-  const visualRadius = toWorldPosition(entry.item).radius;
-  // 中文注释：锅壁和锅沿是视觉边界，物体活动圈要更内缩，避免 3D 透视下贴边后被圆形 DOM 裁切。
+  // 中文注释：空气墙按真实碰撞外接半径收束，长条积木不能再只按近似圆半径贴近锅边。
  const maxDistance = Math.max(
    0,
-    MATCH3D_ITEM_ACTIVITY_RADIUS - visualRadius * 1.05,
+    MATCH3D_ITEM_ACTIVITY_RADIUS - entry.boundaryRadius,
  );
  const horizontalDistance = Math.hypot(
    entry.body.position.x,
@@ -128,6 +548,16 @@ function constrainBodyInsidePot(entry: PhysicsEntry) {
  }
 }

+function resolveSpawnAnimationProgress(entry: PhysicsEntry, now: number) {
+  return Math.min(
+    1,
+    Math.max(
+      0,
+      (now - entry.spawnStartedAt) / MATCH3D_ITEM_SPAWN_ANIMATION_MS,
+    ),
+  );
+}
+
 function applyCenterGravity(entry: PhysicsEntry) {
  if (MATCH3D_CENTER_GRAVITY_COEFFICIENT <= 0) {
    return;
@@ -536,6 +966,105 @@ function removePhysicsEntry(
  runtime.entries.delete(itemInstanceId);
 }

+function createPhysicsEntryFromPendingSpawn(
+  runtime: PhysicsRuntime,
+  pendingSpawn: PendingPhysicsSpawn,
+  now: number,
+) {
+  const visual = createItemMesh(runtime.three, pendingSpawn.item);
+  const asset = resolveGeometryAsset(pendingSpawn.item.visualKey);
+  const colliderBounds = resolveMatch3DColliderBounds(asset, visual.radius);
+  const boundaryRadius = resolveMatch3DBoundaryRadius(asset, visual.radius);
+  const position = visual.position;
+  const maxDistance = Math.max(0, MATCH3D_ITEM_ACTIVITY_RADIUS - boundaryRadius);
+  const horizontalDistance = Math.hypot(position.x, position.z);
+  if (horizontalDistance > maxDistance && horizontalDistance > 0) {
+    const ratio = maxDistance / horizontalDistance;
+    position.x *= ratio;
+    position.z *= ratio;
+  }
+  const spawnLayerIndex = Math.floor(
+    Math.max(0, pendingSpawn.activeLayerRank) /
+      pendingSpawn.layerCapacity,
+  );
+  const plannedSpawnY =
+    pendingSpawn.targetY +
+    MATCH3D_ITEM_SPAWN_RISE_OFFSET +
+    Math.min(spawnLayerIndex * 0.05, 0.62);
+  const spawnY = resolveMatch3DSpawnY(
+    plannedSpawnY,
+    colliderBounds.height,
+    boundaryRadius,
+    position,
+    [...runtime.entries.values()].map((entry) => ({
+      boundaryRadius: entry.boundaryRadius,
+      colliderHeight: entry.colliderHeight,
+      x: entry.body.position.x,
+      y: entry.body.position.y,
+      z: entry.body.position.z,
+    })),
+  );
+  const body = new runtime.cannon.Body({
+    angularDamping: runtime.stabilityPlan.angularDamping,
+    allowSleep: true,
+    linearDamping: runtime.stabilityPlan.linearDamping,
+    mass: 1 + visual.radius * 0.7,
+    shape: createMatch3DCannonShape(runtime.cannon, asset, visual.radius),
+    sleepSpeedLimit: 0.12,
+    sleepTimeLimit: 0.18,
+    position: new runtime.cannon.Vec3(
+      position.x,
+      spawnY,
+      position.z,
+    ),
+  });
+  body.velocity.set(
+    ((pendingSpawn.item.layer % 5) - 2) * 0.06,
+    -0.35,
+    (((pendingSpawn.item.layer + 2) % 5) - 2) * 0.06,
+  );
+  body.angularVelocity.set(
+    0.1 + (pendingSpawn.item.layer % 3) * 0.025,
+    0.08,
+    0.08 + (pendingSpawn.item.layer % 4) * 0.02,
+  );
+  visual.mesh.scale.setScalar(0.82);
+
+  runtime.world.addBody(body);
+  runtime.scene.add(visual.mesh);
+  runtime.entries.set(pendingSpawn.item.itemInstanceId, {
+    body,
+    boundaryRadius,
+    colliderHeight: colliderBounds.height,
+    item: pendingSpawn.item,
+    lockReadableTop: visual.lockReadableTop,
+    mesh: visual.mesh,
+    renderSignature: pendingSpawn.renderSignature,
+    spawnStartedAt: now,
+    targetY: pendingSpawn.targetY,
+    topRotationY: visual.topRotationY,
+  });
+}
+
+function flushPendingPhysicsSpawns(runtime: PhysicsRuntime, now: number) {
+  const readySpawns = [...runtime.pendingSpawns.entries()]
+    .filter(([, pendingSpawn]) => now >= pendingSpawn.spawnAtMs)
+    .sort((left, right) => {
+      if (left[1].spawnAtMs !== right[1].spawnAtMs) {
+        return left[1].spawnAtMs - right[1].spawnAtMs;
+      }
+      if (left[1].activeLayerRank !== right[1].activeLayerRank) {
+        return left[1].activeLayerRank - right[1].activeLayerRank;
+      }
+      return left[0].localeCompare(right[0]);
+    });
+  const spawnBudget = runtime.spawnTimingPlan.frameSpawnLimit;
+  readySpawns.slice(0, spawnBudget).forEach(([itemInstanceId, pendingSpawn]) => {
+    runtime.pendingSpawns.delete(itemInstanceId);
+    createPhysicsEntryFromPendingSpawn(runtime, pendingSpawn, now);
+  });
+}
+
 function disposeRuntime(runtime: PhysicsRuntime | null) {
  if (!runtime) {
    return;
@@ -1092,13 +1621,23 @@ export function Match3DPhysicsBoard({
        rim.position.y = MATCH3D_POT_WALL_HEIGHT + 0.1;
        scene.add(rim);

+        const stabilityPlan = resolveMatch3DPhysicsStabilityPlan(
+          runRef.current.totalItemCount,
+        );
+        const spawnTimingPlan = resolveMatch3DSpawnTimingPlan(
+          runRef.current.totalItemCount,
+        );
        const world = new cannon.World({
          gravity: new cannon.Vec3(0, -6.2, 0),
        });
        world.allowSleep = true;
        world.broadphase = new cannon.SAPBroadphase(world);
-        world.defaultContactMaterial.friction = 0.55;
-        world.defaultContactMaterial.restitution = 0.28;
+        world.defaultContactMaterial.friction = stabilityPlan.contactFriction;
+        world.defaultContactMaterial.restitution =
+          stabilityPlan.contactRestitution;
+        const solver = world.solver as import('cannon-es').GSSolver;
+        solver.iterations = stabilityPlan.solverIterations;
+        solver.tolerance = stabilityPlan.solverTolerance;

        const floorBody = new cannon.Body({
          mass: 0,
@@ -1125,9 +1664,12 @@ export function Match3DPhysicsBoard({
          animationId: null,
          camera,
          entries: new Map(),
+          pendingSpawns: new Map(),
          raycaster: new three.Raycaster(),
          renderer,
          scene,
+          spawnTimingPlan,
+          stabilityPlan,
          world,
          three,
          cannon,
@@ -1157,17 +1699,26 @@ export function Match3DPhysicsBoard({
          }
          const delta = Math.min(0.04, Math.max(0.001, (now - lastTime) / 1000));
          lastTime = now;
+          flushPendingPhysicsSpawns(activeRuntime, now);
          activeRuntime.entries.forEach((entry) => {
            applyCenterGravity(entry);
+            applyDynamicStackLift(entry);
+            applyStabilityPlanToBody(entry, activeRuntime.stabilityPlan);
+            constrainBodyInsidePot(entry);
          });
-          activeRuntime.world.step(MATCH3D_PHYSICS_STEP, delta, 3);
+          activeRuntime.world.step(MATCH3D_PHYSICS_STEP, delta, 5);

          activeRuntime.entries.forEach((entry) => {
            applyCenterGravity(entry);
+            applyDynamicStackLift(entry);
+            applyStabilityPlanToBody(entry, activeRuntime.stabilityPlan);
            constrainBodyInsidePot(entry);
+            const spawnProgress = resolveSpawnAnimationProgress(entry, now);
+            const spawnScale = 0.82 + spawnProgress * 0.18;
+            entry.mesh.scale.setScalar(spawnScale);
            entry.mesh.position.set(
              entry.body.position.x,
-              entry.body.position.y,
+              entry.body.position.y - (1 - spawnProgress) * 0.06,
              entry.body.position.z,
            );
            entry.mesh.quaternion.set(
@@ -1231,6 +1782,16 @@ export function Match3DPhysicsBoard({
      }
    });

+    runtime.pendingSpawns.forEach((pendingSpawn, itemInstanceId) => {
+      if (!activeItemIds.has(itemInstanceId)) {
+        runtime.pendingSpawns.delete(itemInstanceId);
+      }
+    });
+
+    syncRuntimeStabilityPlan(runtime, run.totalItemCount);
+    runtime.spawnTimingPlan = resolveMatch3DSpawnTimingPlan(run.totalItemCount);
+    const stackHeightPlan = buildMatch3DStackHeightTargets(run);
+
    run.items.forEach((item) => {
      if (!isItemState(item.state, 'in_board')) {
        return;
@@ -1247,44 +1808,46 @@ export function Match3DPhysicsBoard({
          removePhysicsEntry(runtime, item.itemInstanceId, existing);
        } else {
          existing.item = item;
+          existing.targetY =
+            stackHeightPlan.targets.get(item.itemInstanceId)?.targetY ??
+            existing.body.position.y;
          existing.mesh.visible = true;
          return;
        }
      }

-      const visual = createItemMesh(runtime.three, item);
-      const asset = resolveGeometryAsset(item.visualKey);
-      const body = new runtime.cannon.Body({
-        angularDamping: 0.48,
-        linearDamping: 0.38,
-        mass: 1 + visual.radius * 0.7,
-        shape: createMatch3DCannonShape(runtime.cannon, asset, visual.radius),
-        position: new runtime.cannon.Vec3(
-          visual.position.x,
-          MATCH3D_ITEM_SPAWN_HEIGHT + item.layer * MATCH3D_ITEM_STACK_HEIGHT_STEP,
-          visual.position.z,
-        ),
-      });
-      body.velocity.set(
-        ((item.layer % 5) - 2) * 0.08,
-        0,
-        (((item.layer + 2) % 5) - 2) * 0.08,
-      );
-      body.angularVelocity.set(
-        0.18 + (item.layer % 3) * 0.04,
-        0.12,
-        0.1 + (item.layer % 4) * 0.03,
-      );
+      const existingPending = runtime.pendingSpawns.get(item.itemInstanceId);
+      if (existingPending) {
+        if (existingPending.renderSignature !== renderSignature) {
+          runtime.pendingSpawns.delete(item.itemInstanceId);
+        } else {
+          existingPending.item = item;
+          existingPending.layerCapacity = stackHeightPlan.layerCapacity;
+          existingPending.targetY =
+            stackHeightPlan.targets.get(item.itemInstanceId)?.targetY ??
+            existingPending.targetY;
+          return;
+        }
+      }

-      runtime.world.addBody(body);
-      runtime.scene.add(visual.mesh);
-      runtime.entries.set(item.itemInstanceId, {
-        body,
+      const stackTarget = stackHeightPlan.targets.get(item.itemInstanceId);
+      const spawnAtMs =
+        performance.now() +
+        runtime.spawnTimingPlan.initialDelayMs +
+        resolveMatch3DSpawnDelay(
+          stackTarget?.activeLayerRank ?? item.layer - 1,
+          stackHeightPlan.layerCapacity,
+          runtime.spawnTimingPlan,
+        );
+      runtime.pendingSpawns.set(item.itemInstanceId, {
+        activeLayerRank: stackTarget?.activeLayerRank ?? item.layer - 1,
        item,
-        lockReadableTop: visual.lockReadableTop,
-        mesh: visual.mesh,
+        layerCapacity: stackHeightPlan.layerCapacity,
        renderSignature,
-        topRotationY: visual.topRotationY,
+        spawnAtMs,
+        targetY:
+          stackTarget?.targetY ??
+          resolveMatch3DStackTargetY(run.totalItemCount, activeItemIds.size, 0),
      });
    });
  }, [ready, run.items, run.runId, run.snapshotVersion]);
--- a/src/components/match3d-runtime/Match3DRuntimeShell.test.tsx
+++ b/src/components/match3d-runtime/Match3DRuntimeShell.test.tsx
@@ -25,6 +25,13 @@ import {
  createMatch3DThreeGeometry,
  measureMatch3DItemPreviewDimension,
  resolveMatch3DColliderBounds,
+  resolveMatch3DBoardDepthPlan,
+  resolveMatch3DBoundaryRadius,
+  resolveMatch3DPhysicsStabilityPlan,
+  resolveMatch3DSpawnTimingPlan,
+  resolveMatch3DStackTargetY,
+  resolveMatch3DSpawnDelay,
+  resolveMatch3DSpawnY,
  resolveMatch3DTrayPreviewRotation,
  resolveMatch3DTrayPreviewReferenceDimension,
  resolveMatch3DTrayPreviewScale,
@@ -447,6 +454,143 @@ test('3D 物体碰撞体按同款视觉尺寸生成', async () => {
  ).toBeCloseTo(cylinderBounds.height);
 });

+test('中心场地 3D 纵深随物体总量增加并随消除进度回补', () => {
+  const smallDepthPlan = resolveMatch3DBoardDepthPlan(30, 30);
+  const largeDepthPlan = resolveMatch3DBoardDepthPlan(300, 300);
+  const earlyBottomY = resolveMatch3DStackTargetY(300, 300, 0);
+  const lateBottomY = resolveMatch3DStackTargetY(300, 60, 0);
+
+  expect(largeDepthPlan.initialDepth).toBeGreaterThan(
+    smallDepthPlan.initialDepth,
+  );
+  expect(largeDepthPlan.layerCapacity).toBeLessThan(
+    smallDepthPlan.layerCapacity,
+  );
+  expect(largeDepthPlan.layerCount).toBeGreaterThan(
+    smallDepthPlan.layerCount,
+  );
+  expect(largeDepthPlan.surfaceY).toBeGreaterThan(largeDepthPlan.baseY);
+  expect(lateBottomY).toBeGreaterThan(earlyBottomY);
+  expect(lateBottomY).toBeLessThanOrEqual(largeDepthPlan.surfaceY);
+});
+
+test('高数量 3D 局面使用更稳定的物理参数', () => {
+  const smallPlan = resolveMatch3DPhysicsStabilityPlan(30);
+  const largePlan = resolveMatch3DPhysicsStabilityPlan(300);
+
+  expect(largePlan.contactFriction).toBeGreaterThan(
+    smallPlan.contactFriction,
+  );
+  expect(largePlan.contactRestitution).toBeLessThan(
+    smallPlan.contactRestitution,
+  );
+  expect(largePlan.linearDamping).toBeGreaterThan(smallPlan.linearDamping);
+  expect(largePlan.angularDamping).toBeGreaterThan(smallPlan.angularDamping);
+  expect(largePlan.solverIterations).toBeGreaterThan(
+    smallPlan.solverIterations,
+  );
+  expect(largePlan.maxHorizontalSpeed).toBeLessThan(
+    smallPlan.maxHorizontalSpeed,
+  );
+});
+
+test('3D 真实边界半径比视觉半径更保守，避免长条贴边穿出锅壁', () => {
+  const longBrick = resolveGeometryAsset('block-black-1x8');
+  const radius = 1;
+  const boundaryRadius = resolveMatch3DBoundaryRadius(longBrick, radius);
+  const visualRadius = Math.hypot(
+    resolveMatch3DColliderBounds(longBrick, radius).width / 2,
+    resolveMatch3DColliderBounds(longBrick, radius).depth / 2,
+  );
+
+  expect(boundaryRadius).toBeCloseTo(visualRadius);
+  expect(boundaryRadius).toBeGreaterThan(2.4);
+});
+
+test('100 次局面的新物体会按层级延迟生成并逐层回落', () => {
+  const fastTimingPlan = resolveMatch3DSpawnTimingPlan(29);
+  const smallDepthPlan = resolveMatch3DBoardDepthPlan(30, 30);
+  const largeDepthPlan = resolveMatch3DBoardDepthPlan(300, 300);
+  const smallTimingPlan = resolveMatch3DSpawnTimingPlan(30);
+  const largeTimingPlan = resolveMatch3DSpawnTimingPlan(300);
+  const bottomDelay = resolveMatch3DSpawnDelay(0, largeDepthPlan.layerCapacity);
+  const middleDelay = resolveMatch3DSpawnDelay(30, largeDepthPlan.layerCapacity);
+  const topDelay = resolveMatch3DSpawnDelay(120, largeDepthPlan.layerCapacity);
+  const dynamicCapacityDelay = resolveMatch3DSpawnDelay(
+    120,
+    largeDepthPlan.layerCapacity,
+  );
+  const defaultCapacityDelay = resolveMatch3DSpawnDelay(
+    120,
+    smallDepthPlan.layerCapacity,
+  );
+
+  expect(bottomDelay).toBe(0);
+  expect(middleDelay).toBeGreaterThan(bottomDelay);
+  expect(topDelay).toBeGreaterThan(middleDelay);
+  expect(dynamicCapacityDelay).toBeGreaterThan(defaultCapacityDelay);
+  expect(smallTimingPlan.frameSpawnLimit).toBeLessThan(
+    fastTimingPlan.frameSpawnLimit,
+  );
+  expect(smallTimingPlan.burstSize).toBeLessThan(fastTimingPlan.burstSize);
+  expect(smallTimingPlan.layerDelayMs).toBeGreaterThan(
+    fastTimingPlan.layerDelayMs,
+  );
+  expect(
+    resolveMatch3DSpawnDelay(29, smallDepthPlan.layerCapacity, smallTimingPlan),
+  ).toBeGreaterThan(450);
+  expect(largeTimingPlan.initialDelayMs).toBeGreaterThan(
+    smallTimingPlan.initialDelayMs,
+  );
+  expect(largeTimingPlan.frameSpawnLimit).toBeLessThan(
+    smallTimingPlan.frameSpawnLimit,
+  );
+  expect(largeTimingPlan.burstSize).toBeLessThanOrEqual(6);
+  expect(largeTimingPlan.layerDelayMs).toBeGreaterThanOrEqual(
+    smallTimingPlan.layerDelayMs,
+  );
+  expect(
+    resolveMatch3DSpawnDelay(299, largeDepthPlan.layerCapacity, largeTimingPlan),
+  ).toBeGreaterThan(5000);
+});
+
+test('3D 新物体生成高度会避让同位置已有堆叠', () => {
+  const plannedSpawnY = 2;
+  const raisedSpawnY = resolveMatch3DSpawnY(
+    plannedSpawnY,
+    0.8,
+    0.7,
+    { x: 0.1, z: 0.1 },
+    [
+      {
+        boundaryRadius: 0.7,
+        colliderHeight: 0.9,
+        x: 0.18,
+        y: 2.4,
+        z: 0.15,
+      },
+    ],
+  );
+  const unchangedSpawnY = resolveMatch3DSpawnY(
+    plannedSpawnY,
+    0.8,
+    0.7,
+    { x: 0.1, z: 0.1 },
+    [
+      {
+        boundaryRadius: 0.7,
+        colliderHeight: 0.9,
+        x: 3,
+        y: 4,
+        z: 3,
+      },
+    ],
+  );
+
+  expect(raisedSpawnY).toBeGreaterThan(plannedSpawnY);
+  expect(unchangedSpawnY).toBe(plannedSpawnY);
+});
+
 test('积木视觉键不会被统一兜底成红色苹字', () => {
  const run = startLocalMatch3DRun(2);
  run.items = run.items.slice(0, 2).map((item, index) => ({
--- a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
+++ b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
@@ -1,4 +1,4 @@
-import { Loader2 } from 'lucide-react';
+import { Loader2, Sparkles } from 'lucide-react';
 import { AnimatePresence, motion } from 'motion/react';
 import {
  lazy,
@@ -166,6 +166,10 @@ import {
  submitLocalPuzzleLeaderboard,
  swapLocalPuzzlePieces,
 } from '../../services/puzzle-runtime/puzzleLocalRuntime';
+import {
+  generatePuzzleOnboardingWork,
+  savePuzzleOnboardingWork,
+} from '../../services/puzzle-onboarding';
 import {
  claimPuzzleWorkPointIncentive,
  deletePuzzleWork,
@@ -251,6 +255,13 @@ type PuzzleRuntimeReturnStage =
  | 'work-detail'
  | 'platform';

+type PuzzleOnboardingPhase = 'input' | 'generating' | 'generated';
+
+type PuzzleOnboardingDraft = {
+  promptText: string;
+  item: PuzzleWorkSummary;
+};
+
 type BigFishRuntimeReturnStage = 'big-fish-result' | 'work-detail' | 'platform';
 type BigFishRuntimeSessionSource = 'draft' | 'work' | null;
 type SquareHoleRuntimeReturnStage =
@@ -605,6 +616,157 @@ function mergePuzzleWorkSummary(
  return current.profileId === updated.profileId ? updated : current;
 }

+const PUZZLE_ONBOARDING_FIRST_VISIT_STORAGE_KEY =
+  'genarrative.puzzle-onboarding.first-visit.v1';
+const PUZZLE_ONBOARDING_COPY = '待定待定待定';
+const PUZZLE_ONBOARDING_CLEAR_COPY = '只差一步，就可以永久保留你的梦';
+const PUZZLE_ONBOARDING_GENERATED_DELAY_MS = 700;
+
+function hasSeenPuzzleOnboarding() {
+  if (typeof window === 'undefined') {
+    return true;
+  }
+
+  try {
+    return (
+      window.localStorage.getItem(PUZZLE_ONBOARDING_FIRST_VISIT_STORAGE_KEY) ===
+      '1'
+    );
+  } catch {
+    return false;
+  }
+}
+
+function markPuzzleOnboardingSeen() {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  try {
+    window.localStorage.setItem(PUZZLE_ONBOARDING_FIRST_VISIT_STORAGE_KEY, '1');
+  } catch {
+    // 中文注释：localStorage 不可写时只降级为本次会话展示，不影响主流程。
+  }
+}
+
+function PuzzleOnboardingView({
+  prompt,
+  phase,
+  error,
+  onPromptChange,
+  onSubmit,
+}: {
+  prompt: string;
+  phase: PuzzleOnboardingPhase;
+  error: string | null;
+  onPromptChange: (value: string) => void;
+  onSubmit: () => void;
+}) {
+  const isGenerating = phase === 'generating';
+  const isGenerated = phase === 'generated';
+  const canSubmit = Boolean(prompt.trim()) && !isGenerating && !isGenerated;
+
+  return (
+    <div className="relative flex min-h-screen items-center justify-center overflow-hidden bg-[radial-gradient(circle_at_30%_15%,rgba(251,191,36,0.22),transparent_30%),linear-gradient(135deg,#0f172a,#111827_46%,#1e1b4b)] px-4 py-8 text-white">
+      <div className="absolute inset-0 bg-[linear-gradient(rgba(255,255,255,0.045)_1px,transparent_1px),linear-gradient(90deg,rgba(255,255,255,0.04)_1px,transparent_1px)] bg-[length:38px_38px] opacity-30" />
+      <section className="relative flex w-full max-w-[34rem] flex-col items-center gap-5 text-center">
+        <div className="grid h-14 w-14 place-items-center rounded-[1.2rem] border border-amber-200/32 bg-amber-200/14 text-amber-100 shadow-[0_18px_48px_rgba(251,191,36,0.18)]">
+          {isGenerating ? (
+            <Loader2 className="h-6 w-6 animate-spin" />
+          ) : (
+            <Sparkles className="h-6 w-6" />
+          )}
+        </div>
+        <h1 className="text-[2rem] font-black leading-tight sm:text-[2.85rem]">
+          {PUZZLE_ONBOARDING_COPY}
+        </h1>
+        <form
+          className="flex w-full flex-col gap-3"
+          onSubmit={(event) => {
+            event.preventDefault();
+            onSubmit();
+          }}
+        >
+          <textarea
+            value={prompt}
+            disabled={isGenerating || isGenerated}
+            onChange={(event) => onPromptChange(event.target.value)}
+            placeholder="把你的梦讲给我听吧"
+            rows={4}
+            className="min-h-32 w-full resize-none rounded-[1.25rem] border border-white/14 bg-black/28 px-4 py-4 text-base font-semibold leading-7 text-white shadow-[0_18px_50px_rgba(0,0,0,0.24)] outline-none backdrop-blur placeholder:text-white/42 focus:border-amber-200/70 focus:ring-2 focus:ring-amber-200/20 disabled:opacity-70"
+          />
+          <button
+            type="submit"
+            disabled={!canSubmit}
+            className="inline-flex min-h-12 items-center justify-center gap-2 rounded-[1rem] bg-amber-200 px-5 text-sm font-black text-slate-950 transition hover:bg-amber-100 disabled:cursor-not-allowed disabled:opacity-45"
+          >
+            {isGenerating ? (
+              <>
+                <Loader2 className="h-4 w-4 animate-spin" />
+                生成
+              </>
+            ) : (
+              '生成'
+            )}
+          </button>
+        </form>
+        {error ? (
+          <div className="w-full rounded-[1rem] border border-red-300/30 bg-red-500/14 px-4 py-3 text-sm font-semibold text-red-50">
+            {error}
+          </div>
+        ) : null}
+      </section>
+    </div>
+  );
+}
+
+function PuzzleOnboardingLoginOverlay({
+  isSaving,
+  error,
+  onLogin,
+}: {
+  isSaving: boolean;
+  error: string | null;
+  onLogin: () => void;
+}) {
+  return (
+    <div className="fixed inset-0 z-[110] flex items-center justify-center bg-slate-950/72 px-4 py-6 text-white backdrop-blur-md">
+      <section className="flex w-full max-w-[24rem] flex-col items-center gap-5 rounded-[1.35rem] border border-white/14 bg-slate-950/94 px-5 py-6 text-center shadow-[0_28px_90px_rgba(0,0,0,0.5)]">
+        <div className="grid h-12 w-12 place-items-center rounded-[1rem] bg-amber-200 text-slate-950">
+          {isSaving ? (
+            <Loader2 className="h-5 w-5 animate-spin" />
+          ) : (
+            <Sparkles className="h-5 w-5" />
+          )}
+        </div>
+        <h2 className="text-2xl font-black leading-tight">
+          {PUZZLE_ONBOARDING_CLEAR_COPY}
+        </h2>
+        <button
+          type="button"
+          disabled={isSaving}
+          onClick={onLogin}
+          className="inline-flex min-h-12 w-full items-center justify-center gap-2 rounded-[1rem] bg-amber-200 px-5 text-sm font-black text-slate-950 transition hover:bg-amber-100 disabled:cursor-not-allowed disabled:opacity-45"
+        >
+          {isSaving ? (
+            <>
+              <Loader2 className="h-4 w-4 animate-spin" />
+              注册账号 / 登录
+            </>
+          ) : (
+            '注册账号 / 登录'
+          )}
+        </button>
+        {error ? (
+          <div className="w-full rounded-[1rem] border border-red-300/30 bg-red-500/14 px-4 py-3 text-sm font-semibold text-red-50">
+            {error}
+          </div>
+        ) : null}
+      </section>
+    </div>
+  );
+}
+
 function mergeBigFishWorkSummary(
  current: BigFishWorkSummary,
  updated: BigFishWorkSummary,
@@ -1124,10 +1286,24 @@ export function PlatformEntryFlowShellImpl({
  const [puzzleRun, setPuzzleRun] = useState<PuzzleRunSnapshot | null>(null);
  const puzzleRunRef = useRef<PuzzleRunSnapshot | null>(null);
  const [isPuzzleLoadingLibrary, setIsPuzzleLoadingLibrary] = useState(false);
+  const [puzzleShelfError, setPuzzleShelfError] = useState<string | null>(null);
+  const [puzzleCreationError, setPuzzleCreationError] = useState<string | null>(
+    null,
+  );
  const [puzzleGenerationState, setPuzzleGenerationState] =
    useState<MiniGameDraftGenerationState | null>(null);
  const [puzzleFormDraftPayload, setPuzzleFormDraftPayload] =
    useState<CreatePuzzleAgentSessionRequest | null>(null);
+  const [puzzleOnboardingPrompt, setPuzzleOnboardingPrompt] = useState('');
+  const [puzzleOnboardingPhase, setPuzzleOnboardingPhase] =
+    useState<PuzzleOnboardingPhase>('input');
+  const [puzzleOnboardingDraft, setPuzzleOnboardingDraft] =
+    useState<PuzzleOnboardingDraft | null>(null);
+  const [puzzleOnboardingError, setPuzzleOnboardingError] = useState<
+    string | null
+  >(null);
+  const [isPuzzleOnboardingSaving, setIsPuzzleOnboardingSaving] =
+    useState(false);
  const [isPuzzleNextLevelGenerating, setIsPuzzleNextLevelGenerating] =
    useState(false);
  const [isSearchingPublicCode, setIsSearchingPublicCode] = useState(false);
@@ -1295,9 +1471,9 @@ export function PlatformEntryFlowShellImpl({
    try {
      const worksResponse = await listPuzzleWorks();
      setPuzzleWorks(worksResponse.items);
-      setPuzzleError(null);
+      setPuzzleShelfError(null);
    } catch (error) {
-      setPuzzleError(
+      setPuzzleShelfError(
        resolvePuzzleErrorMessage(error, '读取拼图作品列表失败。'),
      );
    } finally {
@@ -1609,6 +1785,106 @@ export function PlatformEntryFlowShellImpl({
    [authUi],
  );

+  const savePuzzleOnboardingDraft = useCallback(async () => {
+    if (!puzzleOnboardingDraft || isPuzzleOnboardingSaving) {
+      return;
+    }
+
+    setIsPuzzleOnboardingSaving(true);
+    setPuzzleOnboardingError(null);
+    try {
+      const response = await savePuzzleOnboardingWork({
+        promptText: puzzleOnboardingDraft.promptText,
+        item: puzzleOnboardingDraft.item,
+      });
+      setPuzzleWorks((current) => [response.item, ...current]);
+      setSelectedPuzzleDetail(null);
+      setPuzzleRun(null);
+      setPuzzleOnboardingDraft(null);
+      setPuzzleOnboardingPrompt('');
+      setPuzzleOnboardingPhase('input');
+      platformBootstrap.setPlatformTab('home');
+      setSelectionStage('platform');
+      void refreshPuzzleShelf();
+    } catch (error) {
+      setPuzzleOnboardingError(
+        resolvePuzzleErrorMessage(error, '保存新手引导拼图失败。'),
+      );
+    } finally {
+      setIsPuzzleOnboardingSaving(false);
+    }
+  }, [
+    isPuzzleOnboardingSaving,
+    platformBootstrap,
+    puzzleOnboardingDraft,
+    refreshPuzzleShelf,
+    resolvePuzzleErrorMessage,
+    setSelectionStage,
+  ]);
+
+  const requestPuzzleOnboardingLogin = useCallback(() => {
+    if (isPuzzleOnboardingSaving) {
+      return;
+    }
+    authUi?.openLoginModal(() => {
+      void savePuzzleOnboardingDraft();
+    });
+  }, [authUi, isPuzzleOnboardingSaving, savePuzzleOnboardingDraft]);
+
+  useEffect(() => {
+    if (
+      !authUi ||
+      authUi?.user ||
+      selectionStage !== 'platform' ||
+      hasSeenPuzzleOnboarding()
+    ) {
+      return;
+    }
+
+    setPuzzleOnboardingPhase('input');
+    setPuzzleOnboardingError(null);
+    setSelectionStage('puzzle-onboarding');
+  }, [authUi, authUi?.user, selectionStage, setSelectionStage]);
+
+  const submitPuzzleOnboardingPrompt = useCallback(async () => {
+    const promptText = puzzleOnboardingPrompt.trim();
+    if (!promptText || puzzleOnboardingPhase === 'generating') {
+      return;
+    }
+
+    setPuzzleOnboardingPhase('generating');
+    setPuzzleOnboardingError(null);
+    try {
+      const response = await generatePuzzleOnboardingWork({ promptText });
+      const item: PuzzleWorkSummary = {
+        ...response.item,
+        levels:
+          response.item.levels && response.item.levels.length > 0
+            ? response.item.levels
+            : [response.level],
+      };
+      setPuzzleOnboardingDraft({ promptText, item });
+      setSelectedPuzzleDetail(item);
+      setPuzzleOnboardingPhase('generated');
+      markPuzzleOnboardingSeen();
+      window.setTimeout(() => {
+        setPuzzleRun(startLocalPuzzleRun(item));
+        setPuzzleRuntimeReturnStage('platform');
+        setSelectionStage('puzzle-runtime');
+      }, PUZZLE_ONBOARDING_GENERATED_DELAY_MS);
+    } catch (error) {
+      setPuzzleOnboardingPhase('input');
+      setPuzzleOnboardingError(
+        resolvePuzzleErrorMessage(error, '生成新手引导拼图失败。'),
+      );
+    }
+  }, [
+    puzzleOnboardingPhase,
+    puzzleOnboardingPrompt,
+    resolvePuzzleErrorMessage,
+    setSelectionStage,
+  ]);
+
  const requestDeleteCreationWork = useCallback(
    (confirmation: DeleteCreationWorkConfirmation) => {
      if (deletingCreationWorkId) {
@@ -1986,8 +2262,14 @@ export function PlatformEntryFlowShellImpl({
    enterCreateTab,
    setSelectionStage,
    onSessionOpened: () => {
+      sessionController.setCreationTypeError(null);
+      setPuzzleCreationError(null);
      setShowCreationTypeModal(false);
    },
+    onOpenError: ({ errorMessage }) => {
+      sessionController.setCreationTypeError(errorMessage);
+      setPuzzleCreationError(errorMessage);
+    },
    onActionComplete: async ({ payload, response, setSession }) => {
      setPuzzleOperation(response.operation);
      setSession(response.session);
@@ -2167,6 +2449,8 @@ export function PlatformEntryFlowShellImpl({
    setPuzzleOperation(null);
    setPuzzleGenerationState(null);
    setPuzzleFormDraftPayload(null);
+    sessionController.setCreationTypeError(null);
+    setPuzzleCreationError(null);
    const nextSession = await puzzleFlow.openWorkspace({});
    if (nextSession) {
      void refreshPuzzleShelf();
@@ -2274,6 +2558,8 @@ export function PlatformEntryFlowShellImpl({
    setPuzzleRun(null);
    setPuzzleGenerationState(null);
    setIsPuzzleNextLevelGenerating(false);
+    setPuzzleShelfError(null);
+    setPuzzleCreationError(null);
    setPuzzleError(null);
    setDeletingCreationWorkId(null);
    setClaimingPuzzlePointIncentiveProfileId(null);
@@ -4970,6 +5256,7 @@ export function PlatformEntryFlowShellImpl({
              bigFishError ??
              match3dError ??
              squareHoleError ??
+              puzzleShelfError ??
              puzzleError)
        }
        onRetry={() => {
@@ -4977,6 +5264,8 @@ export function PlatformEntryFlowShellImpl({
          setBigFishError(null);
          setMatch3DError(null);
          setSquareHoleError(null);
+          setPuzzleShelfError(null);
+          setPuzzleCreationError(null);
          setPuzzleError(null);
          void platformBootstrap.refreshCustomWorldWorks().catch((error) => {
            platformBootstrap.setPlatformError(
@@ -4995,6 +5284,7 @@ export function PlatformEntryFlowShellImpl({
          bigFishError ??
          match3dError ??
          squareHoleError ??
+          puzzleCreationError ??
          puzzleError
        }
        createBusy={
@@ -5926,6 +6216,26 @@ export function PlatformEntryFlowShellImpl({
          </motion.div>
        )}

+        {selectionStage === 'puzzle-onboarding' && (
+          <motion.div
+            key="puzzle-onboarding"
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            className="fixed inset-0 z-[100]"
+          >
+            <PuzzleOnboardingView
+              prompt={puzzleOnboardingPrompt}
+              phase={puzzleOnboardingPhase}
+              error={puzzleOnboardingError}
+              onPromptChange={setPuzzleOnboardingPrompt}
+              onSubmit={() => {
+                void submitPuzzleOnboardingPrompt();
+              }}
+            />
+          </motion.div>
+        )}
+
        {selectionStage === 'puzzle-generating' && (
          <motion.div
            key="puzzle-generating"
@@ -6064,6 +6374,7 @@ export function PlatformEntryFlowShellImpl({
                  isPuzzleLeaderboardBusy
                }
                error={puzzleError}
+                hideBackButton={Boolean(puzzleOnboardingDraft)}
                onBack={() => {
                  setSelectionStage(puzzleRuntimeReturnStage);
                }}
@@ -6100,6 +6411,14 @@ export function PlatformEntryFlowShellImpl({
                </div>
              </div>
            ) : null}
+            {puzzleOnboardingDraft &&
+            puzzleRun?.currentLevel?.status === 'cleared' ? (
+              <PuzzleOnboardingLoginOverlay
+                isSaving={isPuzzleOnboardingSaving}
+                error={puzzleOnboardingError}
+                onLogin={requestPuzzleOnboardingLogin}
+              />
+            ) : null}
          </motion.div>
        )}

@@ -6345,6 +6664,7 @@ export function PlatformEntryFlowShellImpl({
          bigFishError ??
          match3dError ??
          squareHoleError ??
+          puzzleCreationError ??
          puzzleError ??
          sessionController.creationTypeError
        }
--- a/src/components/platform-entry/platformEntryCreationTypes.test.ts
+++ b/src/components/platform-entry/platformEntryCreationTypes.test.ts
@@ -11,8 +11,12 @@ test('platform creation types are derived from new work entry config', () => {
  const puzzleConfig = NEW_WORK_ENTRY_CONFIG.creationTypes.find(
    (item) => item.id === 'puzzle',
  );
+  const match3dConfig = NEW_WORK_ENTRY_CONFIG.creationTypes.find(
+    (item) => item.id === 'match3d',
+  );

  expect(puzzleConfig).toBeTruthy();
+  expect(match3dConfig).toBeTruthy();
  expect(PLATFORM_CREATION_TYPES).toContainEqual(
    expect.objectContaining({
      id: 'puzzle',
@@ -23,6 +27,16 @@ test('platform creation types are derived from new work entry config', () => {
      hidden: false,
    }),
  );
+  expect(PLATFORM_CREATION_TYPES).toContainEqual(
+    expect.objectContaining({
+      id: 'match3d',
+      title: '抓大鹅',
+      subtitle: '经典消除玩法',
+      badge: match3dConfig?.badge,
+      locked: false,
+      hidden: false,
+    }),
+  );
 });

 test('new work entry config controls visibility and open order', () => {
@@ -30,13 +44,14 @@ test('new work entry config controls visibility and open order', () => {

  expect(isPlatformCreationTypeVisible('rpg')).toBe(false);
  expect(isPlatformCreationTypeVisible('big-fish')).toBe(false);
-  expect(isPlatformCreationTypeVisible('match3d')).toBe(false);
+  expect(isPlatformCreationTypeVisible('match3d')).toBe(true);
  expect(visibleIds).not.toContain('rpg');
  expect(visibleIds).not.toContain('big-fish');
-  expect(visibleIds).not.toContain('match3d');
+  expect(visibleIds).toContain('match3d');
  expect(visibleIds[0]).toBe('puzzle');
  expect(visibleIds).toEqual([
    'puzzle',
+    'match3d',
    'square-hole',
    'airp',
    'visual-novel',
--- a/src/components/platform-entry/platformEntryTypes.ts
+++ b/src/components/platform-entry/platformEntryTypes.ts
@@ -31,6 +31,7 @@ export type SelectionStage =
  | 'square-hole-runtime'
  | 'puzzle-agent-workspace'
  | 'puzzle-generating'
+  | 'puzzle-onboarding'
  | 'puzzle-result'
  | 'puzzle-gallery-detail'
  | 'puzzle-runtime'
--- a/src/components/platform-entry/usePlatformCreationAgentFlowController.ts
+++ b/src/components/platform-entry/usePlatformCreationAgentFlowController.ts
@@ -75,6 +75,10 @@ type PlatformCreationAgentFlowControllerOptions<
  enterCreateTab: () => void;
  setSelectionStage: (stage: SelectionStage) => void;
  onSessionOpened?: () => void;
+  onOpenError?: (params: {
+    error: unknown;
+    errorMessage: string;
+  }) => void;
  onActionComplete?: (params: {
    payload: TActionPayload;
    response: TActionResponse;
@@ -173,9 +177,15 @@ export function usePlatformCreationAgentFlowController<
      options.setSelectionStage(options.workspaceStage);
      return nextSession;
    } catch (caughtError) {
-      setError(
-        options.resolveErrorMessage(caughtError, options.errorMessages.open),
+      const errorMessage = options.resolveErrorMessage(
+        caughtError,
+        options.errorMessages.open,
      );
+      setError(errorMessage);
+      options.onOpenError?.({
+        error: caughtError,
+        errorMessage,
+      });
      return null;
    } finally {
      setIsBusy(false);
--- a/src/components/puzzle-runtime/PuzzleRuntimeShell.tsx
+++ b/src/components/puzzle-runtime/PuzzleRuntimeShell.tsx
@@ -40,6 +40,7 @@ type PuzzleRuntimeShellProps = {
  run: PuzzleRunSnapshot | null;
  isBusy?: boolean;
  error?: string | null;
+  hideBackButton?: boolean;
  onBack: () => void;
  onRemodelWork?: (profileId: string) => void | Promise<void>;
  onSwapPieces: (payload: SwapPuzzlePiecesRequest) => void;
@@ -306,6 +307,7 @@ export function PuzzleRuntimeShell({
  run,
  isBusy = false,
  error = null,
+  hideBackButton = false,
  onBack,
  onRemodelWork,
  onSwapPieces,
@@ -1095,7 +1097,10 @@ export function PuzzleRuntimeShell({
              type="button"
              onClick={handleBackRequest}
              aria-label="返回上一页"
-              className="inline-flex h-11 w-11 items-center justify-center rounded-full bg-black/30 backdrop-blur"
+              disabled={hideBackButton}
+              className={`h-11 w-11 items-center justify-center rounded-full bg-black/30 backdrop-blur ${
+                hideBackButton ? 'invisible pointer-events-none' : 'inline-flex'
+              }`}
            >
              <ArrowLeft className="h-4 w-4" />
            </button>
@@ -1732,7 +1737,9 @@ export function PuzzleRuntimeShell({
                    setIsSettingsPanelOpen(false);
                    onBack();
                  }}
-                  className="rounded-full bg-amber-200 px-4 py-2 text-sm font-bold text-slate-950 transition hover:bg-amber-100"
+                  className={`rounded-full bg-amber-200 px-4 py-2 text-sm font-bold text-slate-950 transition hover:bg-amber-100 ${
+                    hideBackButton ? 'hidden' : ''
+                  }`}
                >
                  返回上一页
                </button>
--- a/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
+++ b/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
@@ -1143,6 +1143,10 @@ beforeEach(() => {
  window.history.replaceState(null, '', '/');
  window.sessionStorage.clear();
  window.localStorage.clear();
+  window.localStorage.setItem(
+    'genarrative.puzzle-onboarding.first-visit.v1',
+    '1',
+  );
  vi.mocked(getProfileDashboard).mockResolvedValue({
    walletBalance: 0,
    totalPlayTimeMs: 0,
@@ -1869,22 +1873,25 @@ beforeEach(() => {
  vi.mocked(streamRpgCreationMessage).mockResolvedValue(mockSession);
 });

-test('create hub hides RPG and Match3D while keeping AIRP and visual novel locked', async () => {
+test('create hub hides RPG while keeping Match3D open and future templates locked', async () => {
  const user = userEvent.setup();

  render(<TestWrapper withAuth />);

  await openCreationHub(user);

+  const match3dButton = screen.getByRole('button', {
+    name: /抓大鹅.*经典消除玩法/u,
+  });
  const airpButton = screen.getByRole('button', { name: /AIRP/u });
  const visualNovelButton = screen.getByRole('button', {
    name: /视觉小说/u,
  });

+  expect((match3dButton as HTMLButtonElement).disabled).toBe(false);
  expect((airpButton as HTMLButtonElement).disabled).toBe(true);
  expect((visualNovelButton as HTMLButtonElement).disabled).toBe(true);
  expect(screen.queryByRole('button', { name: /角色扮演/u })).toBeNull();
-  expect(screen.queryByRole('button', { name: /抓大鹅/u })).toBeNull();
  expect(createRpgCreationSession).not.toHaveBeenCalled();
  expect(match3dCreationClient.createSession).not.toHaveBeenCalled();
 });
@@ -2841,7 +2848,7 @@ test('puzzle creation timeout exits busy state and shows a readable error', asyn
  expect(screen.queryByText(/正在准备拼图共创工作区/u)).toBeNull();
 });

-test('hidden match3d creation card stays closed even when public galleries fail', async () => {
+test('visible match3d creation card opens workspace even when public galleries fail', async () => {
  const user = userEvent.setup();
  const match3dSession = buildMockMatch3DAgentSession();

@@ -2860,10 +2867,14 @@ test('hidden match3d creation card stays closed even when public galleries fail'
  await openCreationHub(user);
  expect(screen.queryByText('读取作品广场失败')).toBeNull();
  expect(screen.queryByText('读取抓大鹅广场失败')).toBeNull();
-  expect(
-    screen.queryByRole('button', { name: /抓大鹅.*经典消除玩法/u }),
-  ).toBeNull();
-  expect(match3dCreationClient.createSession).not.toHaveBeenCalled();
+  await user.click(
+    screen.getByRole('button', { name: /抓大鹅.*经典消除玩法/u }),
+  );
+
+  await waitFor(() => {
+    expect(match3dCreationClient.createSession).toHaveBeenCalledTimes(1);
+  });
+  expect(await screen.findByText('抓大鹅工作区：match3d-agent-session-1')).toBeTruthy();
 });

 test('puzzle draft result back button returns to creation hub', async () => {
--- a/src/config/newWorkEntryConfig.ts
+++ b/src/config/newWorkEntryConfig.ts
@@ -43,7 +43,7 @@ export const NEW_WORK_ENTRY_CONFIG = {
      title: '抓大鹅',
      subtitle: '经典消除玩法',
      badge: '可创建',
-      visible: false,
+      visible: true,
      open: true,
    },
    {
--- a/src/services/puzzle-onboarding/index.ts
+++ b/src/services/puzzle-onboarding/index.ts
@@ -0,0 +1,5 @@
+export {
+  generatePuzzleOnboardingWork,
+  puzzleOnboardingClient,
+  savePuzzleOnboardingWork,
+} from './puzzleOnboardingClient';
--- a/src/services/puzzle-onboarding/puzzleOnboardingClient.ts
+++ b/src/services/puzzle-onboarding/puzzleOnboardingClient.ts
@@ -0,0 +1,62 @@
+import type {
+  PuzzleOnboardingGenerateRequest,
+  PuzzleOnboardingGenerateResponse,
+  PuzzleOnboardingSaveRequest,
+} from '../../../packages/shared/src/contracts/puzzleOnboarding';
+import type { PuzzleWorkMutationResponse } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
+import { type ApiRetryOptions, requestJson } from '../apiClient';
+
+const PUZZLE_ONBOARDING_API_BASE = '/api/runtime/puzzle/onboarding';
+const PUZZLE_ONBOARDING_WRITE_RETRY: ApiRetryOptions = {
+  maxRetries: 1,
+  baseDelayMs: 120,
+  maxDelayMs: 360,
+  retryUnsafeMethods: true,
+};
+
+/**
+ * 未登录首次访问生成的临时 1 关拼图，不写入用户作品库。
+ */
+export async function generatePuzzleOnboardingWork(
+  payload: PuzzleOnboardingGenerateRequest,
+) {
+  return requestJson<PuzzleOnboardingGenerateResponse>(
+    `${PUZZLE_ONBOARDING_API_BASE}/generate`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    },
+    '生成新手引导拼图失败',
+    {
+      retry: PUZZLE_ONBOARDING_WRITE_RETRY,
+      skipAuth: true,
+      skipRefresh: true,
+    },
+  );
+}
+
+/**
+ * 登录后把临时拼图保存成当前用户的草稿作品。
+ */
+export async function savePuzzleOnboardingWork(
+  payload: PuzzleOnboardingSaveRequest,
+) {
+  return requestJson<PuzzleWorkMutationResponse>(
+    `${PUZZLE_ONBOARDING_API_BASE}/save`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    },
+    '保存新手引导拼图失败',
+    {
+      retry: PUZZLE_ONBOARDING_WRITE_RETRY,
+    },
+  );
+}
+
+export const puzzleOnboardingClient = {
+  generate: generatePuzzleOnboardingWork,
+  save: savePuzzleOnboardingWork,
+};