.hermes/shared-memory/decision-log.md

@@ -16,6 +16,23 @@
 
 ---
 
+## 2026-06-03 拼消消收敛为单关 6x6 与 4-sheet 素材策略
+
+- 背景：最初 4 关 / 135 次消除 / 单张大 atlas 方案生图数量和空间一致性成本过高，真实 image2 结果容易被布局提示词诱导成带文字、边框或编号的说明图，不适合运行态 1x1 切片。
+- 决策：拼消消运行态收敛为单关 `6x6 / 35 次消除 / 600 秒`，直接解锁 `1x2`、`1x3`、`2x2`、`2x3`；素材生成改为 4 张 `1024x1536` 竖版 sheet，每张按 `4x6`、每格 `256x256` 切片，再由服务端合成 `10x10 / 2560x2560` 最终 atlas。形状配比固定为 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`，总计 35 个复合图案组和 95 个 1x1 卡牌切片。
+- 影响范围：`module-puzzle-clear` 关卡与图案组规划、api-server 拼消消素材生成编排、前端草稿试玩本地 runtime、结果页 atlas 预览、拼消消 PRD / 技术方案 / 平台链路文档。
+- 验证方式：`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle_clear --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+- 关联文档：`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-05-30 拼消消按独立玩法公开闭环接入
+
+- 背景：拼消消以拼图交换手感为基础，但核心规则从“拼完整单图过关”变为“拼成多个复合图案组后逐个消除”，同时需要顶部补牌、防死局、半锁定局部拼接组和正式统计，不能继续复用拼图运行态规则本体。
+- 决策：`puzzle-clear` 作为独立玩法域接入，公开作品码前缀固定为 `PC-`；创作链路采用表单 / 图片输入工作台 -> 独立生成页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式 runtime。领域规则落在 `module-puzzle-clear`，SpacetimeDB 新增 `puzzle_clear_*` 表 / procedure / view，并接入统一 `public_work_gallery_entry` / `public_work_detail_entry`；前端只表现后端 snapshot/action 结果，不把胜负、补牌或消除裁决做成前端事实源。
+- 补充约束：草稿编译和发布都必须拒绝缺失或 `placeholder` atlas / card assets，不允许后端 facade 或 SpacetimeDB 合成临时素材；当前单关正式 runtime 终态事件使用 `run-finished`、`level-failed`，并写入包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs` 的结果 JSON。
+- 补充约束：拼消消结果页草稿试玩使用前端本地 `runtimeMode=draft` snapshot，不调用 `/api/runtime/puzzle-clear/runs`，不写正式 run 统计；公开详情和推荐流正式运行继续走后端 `/api/runtime/puzzle-clear/*`，客户端需要区分创作详情 `/api/creation/puzzle-clear/works/{profileId}` 与公开运行态详情 `/api/runtime/puzzle-clear/works/{profileId}`。
+- 影响范围：`CONTEXT.md`、拼消消 PRD / 技术方案、平台玩法链路文档、`shared-contracts` / `packages/shared`、`api-server`、`spacetime-module`、`spacetime-client`、作品架 / 广场 / 统一作品详情 / runtime 前端分流。
+- 验证方式：PRD 和技术方案必须覆盖资产槽位、素材工作表风险、切片验证、恢复语义、API 命名空间和验证命令；实现侧至少运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`npm run check:server-rs-ddd`、`npm run typecheck`、`npm run check:encoding`、相关前端测试和 `cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`。
+- 关联文档：`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 ## 2026-06-05 Server-Provision 全程在目标部署 agent 执行且不安装构建链
 
 - 背景：`Genarrative-Server-Provision` 的 `DEPLOY_TARGET=development` 语义是部署到 dev 服务器，不是构建机 dry-run。旧流水线把 development 映射到 `linux && genarrative-build`，还先在 build 节点准备 `provision-tools/` 再 stash 给后续阶段，导致真实 dev 初始化可能跑到 Jenkins controller / build 节点；脚本还安装 clang / lld / pkg-config / OpenSSL headers / sccache 等构建链依赖，超出了服务器初始化职责。
@@ -1280,3 +1297,11 @@
 - 影响范围：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/module-auth/src/lib.rs`、`server-rs/crates/spacetime-module/src/auth/procedures.rs`、`server-rs/crates/spacetime-client/src/auth.rs`、对应生成 bindings。
 - 验证方式：`cargo check -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p module-auth password --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:spacetime-schema`、`npm run check:encoding`、`cargo test -p api-server spacetime_unavailable_router_returns_service_unavailable_for_requests --manifest-path server-rs/Cargo.toml -- --nocapture`。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 2026-05-31 拼消消底图 prompt 与 atlas 切片提示词收口
+
+- 背景：拼消消生成资产检查时，用户需要区分主题词、场地底图主题词和复合图 atlas prompt 的职责；若小图案显式画出切分线或边框，运行态 1x1 切片会显得像错误素材。
+- 决策：`boardBackgroundPrompt` 成为中央场地底图的优先 prompt 来源，只有该字段为空时才回退读取 `themePrompt`；用户上传底图时只执行平台资产持久化和换签，不用主题词重写上传资产。复合图 atlas prompt 只描述“可被服务端按等大 1x1 方格切分”，禁止模型在图案上绘制切分线、边框、网格线或裁切参考线。
+- 影响范围：拼消消工作台 payload、`shared-contracts` / `packages/shared` 契约、api-server 生成编排、SpacetimeDB session/work snapshot、文档与生成进度展示。
+- 验证方式：`npm run spacetime:generate`、`npm run check:encoding`、`npm run check:server-rs-ddd`、`cargo test -p module-puzzle-clear`、`cargo test -p spacetime-client puzzle_clear -- --nocapture`、`npm run test -- src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx src/services/miniGameDraftGenerationProgress.test.ts src/routing/appPageRoutes.test.ts src/services/publicWorkCode.test.ts`。
+- 关联文档：`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

.hermes/shared-memory/pitfalls.md

@@ -1,4 +1,4 @@
-# 踩坑与排障记录
+# 踩坑与排障记录
 
 > 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。
 
@@ -104,6 +104,30 @@
 - 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t \"puzzle draft generation auto starts trial and runtime back opens draft result\"`，确认 `window.location.pathname === '/runtime/puzzle'` 且 `window.location.search` 同时包含 `runtimeProfileId` 和 `runtimeSessionId`。
 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/services/puzzleRuntimeUrlState.ts`、`src/routing/appPageRoutes.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 拼消消草稿试玩不能只测 swap 回调
+
+- 现象：拼消消结果页和 runtime shell 的单测都能通过，但真实页面里卡片只是交换，完全不会消除，顶部准备区还会因为已知的卡背占位路径显示坏图。
+- 原因：草稿试玩走的是前端本地 runtime，早期测试只覆盖了 `onSwapCards` 回调和局部状态，没有验证完整的消除、重力补牌、关卡完成和资源兜底链路；同时顶部卡背对 `puzzle-clear-card-back.webp` 这类已知缺失资源没有前置回退。
+- 处理：草稿试玩的回归测试必须覆盖“交换 -> 完整图案消除 -> 补牌 -> 关卡完成”闭环，并在组件测试里验证真实点击/拖拽序列；顶部准备区卡背遇到已知占位路径时直接回退到 `puzzle.webp` 这类可用参考图，不等图片加载失败后再兜底。
+- 验证：`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 通过，浏览器 smoke 页实测可完成一次消除并弹出“本关完成”。
+- 关联：`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
+## 拼消消消除过渡不能隐藏已有卡片的最终下沉格
+
+- 现象：消除补牌过程中偶尔看起来下方有空位，但同列上方卡片没有落下来。
+- 原因：后端和本地 runtime 的重力补牌已经把已有卡片压到底；真正的问题在前端过渡层。消除动画曾按旧消除坐标隐藏棋盘格，掉落动画也曾隐藏所有 drop 目标格。当某个旧卡下沉到刚被消除的格子时，最终 snapshot 里的真实卡片会被隐藏，视觉上像补牌没有落下。
+- 处理：消除 / 掉落覆盖层只负责动画表现，不再隐藏已有场上卡片的最终格；只有从顶部准备区新补入、前一帧棋盘不存在的卡片，才允许临时隐藏底层目标格来配合下落动画。
+- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx -t "已有卡片因重力下沉时目标格不被过渡状态隐藏成空位"`，并保留领域侧 `cargo test -p module-puzzle-clear refill --manifest-path server-rs/Cargo.toml`。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`server-rs/crates/module-puzzle-clear/src/application.rs`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`。
+
+## 拼消消完整消除反馈不要让补牌抢帧
+
+- 现象：玩家正确拼完整组后，卡片几乎瞬间消失，顶部补牌马上出现或下落，导致“拼对了”的确认反馈很弱。
+- 原因：前端一收到新 snapshot 就同时播放消除和掉落叠层，旧消除动画时长较短；新补入卡牌的下落延迟接近 0ms，视觉上会抢在消除反馈之前开始。
+- 处理：局部正确拼合但未消除时只给锁定组做一次高光；完整消除时让旧卡片在消除叠层中短暂放大展示再淡出；新补入卡牌的下落延迟到淡出尾段，并继续只隐藏新补入目标格，不隐藏已有场上卡片下沉后的最终格。
+- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`，浏览器里确认局部拼合会闪、完整消除会放大淡出、补牌在淡出后段才开始掉落。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/index.css`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
 ## 首页推荐分流参数不能条件性调用 hook
 
 - 现象：桌面首页或移动首页在 HMR、断点切换或重新渲染后直接报 React hook 顺序错误，页面停在“正在加载内容”。
@@ -1026,6 +1050,14 @@
 - 验证：`cargo test -p api-server phone_auth_sms_provider_errors_keep_upstream_http_semantics --manifest-path server-rs/Cargo.toml`，真实 provider 频控时接口不再返回 `500`。
 - 关联：`server-rs/crates/module-auth/src/errors.rs`、`server-rs/crates/api-server/src/phone_auth.rs`、`docs/technical/PHONE_SMS_PROVIDER_ERROR_HTTP_MAPPING_FIX_2026-05-08.md`。
 
+
+## 本地短信 smoke 先确认 SMS provider
+
+- 现象：浏览器里短信验证码发送成功，但提交 `123456` 仍然报验证码错误，或者短信登录后又回到未登录态。
+- 原因：当前运行中的 `api-server` 如果读取到 `.env.local` 里的 `SMS_AUTH_PROVIDER=aliyun`，就会走真实短信 provider 口径；这时 mock 验证码 `123456` 不会被接受。之前本地调试时常见的误判是把 `.env.local` 改成 mock 了，但没有重启 `npm run dev`，或者旧的 `scripts/dev.mjs` 进程还在沿用旧环境。
+- 处理：本地只做 UI / 账号链路 smoke 时，把 `.env.local` 显式设为 `SMS_AUTH_PROVIDER=mock` 且配置 `SMS_AUTH_MOCK_VERIFY_CODE=123456`，然后重启 `npm run dev` 或 `npm run dev:api-server`。要做真实短信联调时，再切回 `SMS_AUTH_PROVIDER=aliyun` 并重启。
+- 验证：`POST /api/auth/phone/send-code` 应返回 `providerRequestId=mock-request-id`；`POST /api/auth/phone/login` 用 `123456` 应返回 `200` 且 `user.loginMethod=phone`。浏览器侧短信登录成功后，会先进入邀请码弹窗或我的页面，不应再提示“验证码错误”。
+- 关联：`scripts/dev-utils.mjs`、`scripts/dev-utils.test.ts`、`scripts/dev.mjs`、`server-rs/crates/api-server/src/config.rs`。
 ## 手机验证码登录成功后又瞬间回到未登录
 
 - 现象：手机号验证码登录先成功，随后 UI 又闪回“未登录”，登录弹窗可能重新出现。
@@ -1853,6 +1885,124 @@
 - 验证：`npx vitest run src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 覆盖访客态纵向滑动不弹登录且触发下一条推荐。
 - 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。
 
+## Windows junction worktree 下 Vitest 定向路径失败先切真实路径
+
+- 现象：在 `C:\Users\...\ .codex\worktrees\...` 这类 junction 工作区运行 `npm run test -- src/...` 时，Vitest 可能报 `Failed to load url C:/Users/... (resolved id: F:/DevWorktrees/...)`，同一测试文件明明存在却被判定找不到。
+- 原因：Vite / Vitest 在 Windows 下会把测试入口 realpath 到真实 worktree 路径；如果命令从 junction 路径传入相对文件参数，入口路径和 resolved id 可能跨盘符不一致。
+- 处理：前端定向测试优先从 `Get-Item <worktree> | Format-List Target` 显示的真实路径运行，例如 `F:\DevWorktrees\codex\worktrees\f584\Genarrative`；不要把这类文件加载失败误判成组件或路由断言失败。
+- 验证：同一命令从真实路径执行应正常收集并运行测试，例如 `npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+- 关联：`src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx`、`src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`src/routing/appPageRoutes.test.ts`。
+
+## 拼消消草稿试玩要和正式 runtime 分流
+
+- 现象：拼消消结果页点击“试玩”后如果仍然调用 `/api/runtime/puzzle-clear/runs`，草稿试玩会被正式 run 规则和统计约束卡住，公开作品又可能和草稿恢复串台。
+- 原因：拼消消既有草稿生成 / 结果页 / 发布闭环，也有正式公开 runtime；如果把结果页试玩和公开运行态复用同一个后端 startRun 入口，`work detail` 读取路径和统计口径都会混在一起。
+- 处理：结果页试玩改走前端本地 `runtimeMode=draft` snapshot，只用于草稿试玩和关卡切换，不写正式 run；公开详情和推荐流进入正式 runtime 时才走后端 `/api/runtime/puzzle-clear/*`。客户端读取作品详情时也要区分创作详情 `/api/creation/puzzle-clear/works/{profileId}` 与公开运行态详情 `/api/runtime/puzzle-clear/works/{profileId}`。
+- 验证：点击拼消消结果页的试玩按钮，不应再请求 `/api/runtime/puzzle-clear/runs`；公开详情入口仍应能读取后端运行态详情。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/services/puzzle-clear/puzzleClearClient.ts`、`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md`。
+
+## 拼消消 runtime 必须继承拼图模板的原生交互基线
+
+- 现象：拼消消卡片在浏览器里会出现原生图片拖拽 / 下载手柄，或窗口拉伸后棋盘和卡片被拉成矩形。
+- 原因：拼消消 runtime 早期只继承了“交换 / 消除”的业务逻辑，没有完整继承拼图模板在基础交互上的防护：`touch-none`、`select-none`、`aspect-square`、`draggable={false}`、`onDragStart(event.preventDefault())`、`-webkit-user-drag: none`。
+- 处理：棋盘容器必须保持正方形约束，卡片按钮和内层 `<img>` 都要显式禁用浏览器原生拖拽，样式层也要补 `user-select: none` 与 `-webkit-user-drag: none`，不能只靠业务指针逻辑。
+- 验证：浏览器中检查棋盘 `getBoundingClientRect().width === height`，卡片图片 `draggable="false"` 且 `-webkit-user-drag` 为 `none`；真实拖拽只应进入交换逻辑，不应触发原生图片拖拽。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/index.css`、`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
+## 拼消消拖拽浮层要挂到页面级 portal
+
+- 现象：拼消消拖拽时图片看起来没有贴在鼠标或手指上，尤其是平台壳层本身带有 transform 时更明显。
+- 原因：拖拽 ghost 用了 `position: fixed`，但如果还挂在会被 transform 的局部容器里，浏览器会把 fixed 当成相对该祖先定位；`clientX/clientY` 读到的是视口坐标，两个坐标系一混就会出现肉眼可见的偏移。
+- 处理：拖拽浮层必须通过 portal 挂到 `document.body` 这一层，再继续使用 `clientX/clientY - pointerOffset` 计算 left/top；不要把 ghost 留在平台壳或任何会参与 transform 的容器里。
+- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 应断言拖拽浮层父节点是 `document.body`，且 left/top 与按下点偏移一致。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
+## 拼消消要继承拼图模板的动作语言，不只是规则
+
+- 现象：拼消消如果只实现“交换后裁决”，但没有开局翻牌、按下留空位、被替换卡快速飞回、以及局部拼接块整体拖动，玩家会直觉上觉得比原拼图更笨重。
+- 原因：早期实现容易把“规则独立”误读成“动作语言也要重写”，结果只保留了交换逻辑，没有沿用拼图模板里已经验证过的拖拽反馈、空位让位和合并块连续感。
+- 处理：拼消消运行态要继承拼图模板的基础手感：只在开局保留入场翻牌，拖起时源位立即呈空，放下时被替换卡要有明确飞向空位的位移感，连通块要作为整体拖动和整体呈现。
+- 验证：浏览器拖拽时能看到跟手 ghost、源位空槽、落点飞入和整组拼接层；`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 应覆盖这些行为。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`src/index.css`。
+
+## 拼消消空格位必须允许落位，不能当成不可交互死格
+
+- 现象：运行到某一关后，棋盘里出现空格位，用户能看见空洞但拖不进去，也点不动。
+- 原因：空格位被前端交互或后端裁决误当成“无效目标”，只保留了交换逻辑，没有把“源卡落入空位、源位清空”当成合法移动。
+- 处理：空格位必须保留 button 交互态和落点命中逻辑；前端拖拽 / 点击落到空格时直接提交移动，后端和本地 runtime 都要把源卡移动到目标格并清空源格，不再走失败交换。
+- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml player_move_can_drop_card_into_empty_target_cell -- --nocapture`。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`server-rs/crates/module-puzzle-clear/src/application.rs`。
+
+## 拼消消空位落卡后必须立即补位，不能把空洞留成真空格
+
+- 现象：卡牌成功落进空格后，源位仍然留空，玩家会误以为那个格子坏掉了。
+- 原因：移动逻辑只处理了“落到空位”，没有在未消除时同步走一遍重力补位，所以源列会短暂或永久留下空洞。
+- 处理：只要移动后棋盘存在空位，就立即走补位和可解性修复；这样源位会从顶部准备区补卡，不会留下不可交互空洞。
+- 验证：`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml player_move_can_drop_card_into_empty_target_cell -- --nocapture`。
+- 关联：`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`server-rs/crates/module-puzzle-clear/src/application.rs`。
+
+## 拼消消素材错位先查 sheet 质量门禁
+
+- 现象：一张卡牌切片里同时出现两个或多个错位图案，或空白格、相邻编号区域里混入其他图案碎片。
+- 原因：provider 生成的 `1024x1536 / 4x6` 工作表可能违反视觉契约；旧流程只校验布局元数据和切片数量，无法发现图像内容已经主体缺失或污染空白格。边界贴边检测容易把正常铺满主体误判成跨格污染，不能作为高可靠硬门禁。
+- 处理：先强化 atlas prompt，要求每个 `256x256` 单元独立查看时只能包含一个主体或同一主体单一局部；服务端在 sheet 切片前做像素级质量门禁，硬拦截非空格前景占比过低和空白格污染，严重多边非同组边界贴边只记录 warning 供排查，不直接让创作失败。硬门禁失败的 sheet 最多尝试 4 次，仍失败则拒绝持久化脏 atlas。
+- 追加处理：照片式微场景素材必须把每个 `256x256` 单元收束为一张完整的单场景照片裁片；同编号连续格表示同一视觉家族，不是随机独立小图，要求共享同一场景锚点、主色和道具语言。禁止单格内部出现两张照片、两个不同场景、拼接线、内部竖切、内部横切或左右 / 上下两块不同背景；质量门禁只在单格内部强色差直线贯穿大部分高度或宽度，且两侧都像低纹理人工平铺色块时，按“单格内部疑似拼接线”硬失败并重试 sheet，避免把窗框、桌沿、地平线等自然场景强边缘误杀。
+- 追加处理：sheet 生成时如果 VectorEngine 返回 `retryable=true` 的 `502`、`504`、`429` 或请求超时，例如 nginx HTML `502 Bad Gateway`，不要立刻把草稿置为 failed，应消耗同一 sheet 的下一次 attempt；仍失败再回写失败状态。
+- 追加处理：`sheet-03` 原本唯一空白格容易被模型画入主题主体，导致第 6 行第 4 列反复报“空白格有主体”并消耗多次 image2 请求。该格改为 `FILL` 补位格，允许生成主题小图但服务端切片、atlas 合成和运行态全部丢弃；前端拼消消 action 等待窗口同步提高到 40 分钟，避免上游单图慢返回时用户侧 20 分钟超时。
+- 验证：`cargo test -p api-server puzzle_clear --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
+- 关联：`server-rs/crates/api-server/src/puzzle_clear.rs`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`。
+
+## 拼消消锁定组覆盖层必须锚定在棋盘本身
+
+- 现象：消除或补牌过程中，局部完成的组图偶尔会看起来从格子里“飘出去”，并且大小会随着窗口和外层面板变化而异常拉伸。
+- 原因：锁定组视觉层用了 `absolute inset-0`，但棋盘容器本身不是 `position: relative`，于是覆盖层实际锚到了更外层的运行态面板，`gridColumn` / `gridRow` 只能在错误坐标系里排版。
+- 处理：棋盘容器必须显式 `relative`，让锁定组覆盖层、拖拽鬼影和格子坐标都在同一正方形棋盘坐标系内排版；不要把这类覆盖层锚到外层 `section` 或整页容器。
+- 验证：浏览器里棋盘 `getBoundingClientRect()` 和锁定组覆盖层应共享同一块正方形区域，窗口缩放后组图不应再出现越界或被拉伸的现象；`PuzzleClearRuntimeShell.test.tsx` 需要断言棋盘 class 包含 `relative`。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
+## 拼消消中央场地底图必须挂在棋盘内部
+
+- 现象：创作阶段选择了中央场地底图，但运行态消除卡片后只看到浅色格子或空点，看不到底图。
+- 原因：底图被渲染成整页氛围背景，并被页面渐变、棋盘面板和格子 `bg-white/78` 遮住；棋盘内部没有静态底图层，空格仍保留不透明卡片底色。
+- 处理：`boardBackgroundAsset.imageSrc` 必须作为 `puzzle-clear-board` 内部的 `absolute inset-0` 静态底图渲染；空格、消除空位和拖拽源位必须透明或近透明，不能继续使用实体卡片白底。
+- 验证：`PuzzleClearRuntimeShell.test.tsx` 断言 `puzzle-clear-board-background` 在棋盘内，`/board-bg.png` 只出现一次，空格 class 包含 `bg-transparent` 且不包含 `bg-white/78`。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 创作入口突然消失先查前后端是否串到不同 worktree
+
+- 现象：`http://127.0.0.1:3000/` 可访问，但创作 Tab 里新增玩法入口消失；例如 `puzzle-clear` 已在代码默认种子中存在，浏览器仍看不到“拼消消”。
+- 原因：Vite 可能来自当前 worktree，但代理目标的 `api-server` 仍是另一个 worktree 的旧进程，或者 `api-server` 连到旧 SpacetimeDB 模块；此时 `/api/creation-entry/config` 会返回旧入口配置。
+- 处理：先用 `Get-NetTCPConnection -State Listen -LocalPort 3000,8083,3103` 结合 `Get-CimInstance Win32_Process` 确认端口进程路径；停止串线的旧 `api-server`，再用当前 worktree 的 `npm run dev:spacetime -- --spacetime-port <port> --database <database>` 和 `npm run dev:api-server -- --api-port <port> --spacetime-port <port> --database <database>` 拉起同一套服务。
+- 验证：`GET /api/creation-entry/config` 应包含目标入口，且监听端口的命令行都指向同一个 worktree；浏览器创作 Tab 对应分类应显示入口卡。
+- 关联：`scripts/dev.mjs`、`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## Windows junction 工作区下 dev.mjs 直接执行入口要用 realpath 判断
+
+- 现象：在 `C:\Users\...\ .codex\worktrees\...` 这类 junction 路径里运行 `npm run dev:web`，进程会秒退，`3000` 不监听，但同一脚本从真实 worktree 路径能正常启动。
+- 原因：`scripts/dev.mjs` 的入口判断只比对 `process.argv[1]` 和 `import.meta.url` 的字面路径；junction 路径和 realpath 路径不一致时会误判成“不是直接执行”，于是主流程根本不进入。
+- 处理：入口判断改成基于 `realpathSync(...)` 的 `isDirectModuleExecution(...)`，让 junction 路径和真实 worktree 路径指向同一个模块；同时补回归测试覆盖该场景。
+- 验证：`npm run test -- scripts/dev.test.ts scripts/dev-stack-port-utils.test.ts` 通过后，`npm run dev:web -- --web-port 3000 --api-port 8083 --no-interactive` 应能稳定把 `0.0.0.0:3000` 监听起来。
+- 关联：`scripts/dev.mjs`、`scripts/dev.test.ts`。
+
+## Vitest 定向测试在 Windows junction 工作区要切真实路径
+
+- 现象：在 `C:\Users\...\ .codex\worktrees\...` 这类 junction 路径里跑 `npm run test -- src/...` 时，Vitest 会报 `Failed to load url ... (resolved id: F:/DevWorktrees/...)`，看起来像文件不存在。
+- 原因：Vite / Vitest 会把入口 realpath 到真实 worktree 路径；如果命令从 junction 路径传入相对文件参数，入口路径和 resolved id 可能跨盘符不一致。
+- 处理：前端定向测试优先从真实路径 `F:\DevWorktrees\codex\worktrees\f584\Genarrative` 运行，不要把这类文件加载失败误判成组件或路由断言失败。
+- 验证：同一命令从真实路径执行应正常收集并运行测试。
+- 关联：`src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`src/routing/appPageRoutes.test.ts`。
+- 现象：新增或扩展 `*-generating` 页面后，生成卡只渲染首帧，`已耗时` / `预计等待` 停在进入页那一刻不动。
+- 原因：平台壳层的共享 `miniGameGenerationProgressNowMs` 时钟没有把新生成阶段纳入 tick 条件，或者该阶段的 `buildMiniGameDraftGenerationProgress(..., nowMs)` 没有接入同一时钟。
+- 处理：任何共享生成页都要通过平台壳层统一的时钟判断和 `nowMs` 传递刷新，新增生成阶段时要同时补 `selectionStage` 判定、`useEffect` 依赖和进度调用点。
+- 验证：浏览器里进入对应生成页后，`已耗时` / `预计等待` 应持续变化，不应停在首帧。
+
+## 拼消消要用真实可消除判断，不要把“已相邻”当成可解
+
+- 现象：拼消消开局或补牌后会直接出现已完成的图案组，或者 `1x2` 被当成半锁定局部留在场上。
+- 原因：早期把可解性写成“场上已经有同组相邻卡”或“只要有一对相邻同组卡就算可解”，这会把已完成盘面误当成合法盘面；同时半锁定规则没有排除 `1x2`。
+- 处理：开局和补牌后的重排必须先排除现成消除，再用真实交换 / 落位模拟判断是否会产生新消除；`1x2` 永远不进入半锁定组，半锁定只允许 `1x3`、`2x2`、`2x3`。
+- 验证：`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 与 `cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml -- --nocapture` 通过后，开局盘面不应直接出现 completed group。
+- 关联：`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`server-rs/crates/module-puzzle-clear/src/application.rs`。
 ## 推荐页作品 key 漏玩法会导致运行内容和标题作者错位
 
 - 现象：移动端推荐页进入跳一跳或敲木鱼等作品时，游戏运行内容已经切到当前作品，但下方标题、作者和头像仍显示第一条拼图或其它推荐作品。

.hermes/shared-memory/project-overview.md

@@ -1,6 +1,6 @@
 # Genarrative 项目共享概览
 
-更新时间：`2026-05-29`
+更新时间：`2026-06-03`
 
 ## 一句话定位
 
@@ -10,6 +10,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 
 - RPG / 自定义世界创作与运行时。
 - 拼图玩法创作、草稿、发布、运行态和排行榜。
+- 拼消消玩法创作、素材图集生成、结果页、发布、统一作品详情、正式运行态和基础统计。
 - 敲木鱼玩法创作、草稿、发布、运行态、公开详情和分享码。
 - 抓大鹅 Match3D 创作、2D 多视角素材生成、发布和运行态。
 - 大鱼吃小鱼、方洞挑战、视觉小说、汪汪声浪和儿童向寓教于乐玩法。

CONTEXT.md

@@ -18,6 +18,32 @@ _Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成
 
 ## Language
 
+### Puzzle Clear
+
+**拼消消**:
+基于拼图交换 / 拖拽手感的新玩法模板，玩家移动 1x1 卡牌碎片，把同一复合图案组拼成完整矩形后消除，并由顶部对应纵列补牌继续游玩。
+_Avoid_: 拼图整图过关、三消槽位玩法、前端本地裁决
+
+**复合图案组**:
+拼消消中可被消除的一幅小图，由 `1x2`、`1x3`、`2x2` 或 `2x3` 的 1x1 卡牌碎片组成；只有组内碎片按正确相对位置拼成完整矩形后才消除。
+_Avoid_: 单张卡牌、整关大图、任意相邻同色块
+
+**1x1 卡牌碎片**:
+复合图案组被服务端切成的最小可移动单位，带有所属组、形状、组内坐标和图片资产。
+_Avoid_: 前端临时裁图、无所属图案的普通方块
+
+**半锁定拼接组**:
+非 2 格复合图案组中已经局部完成的拼接状态，可作为整体拖动；玩家用外部单格撞入组内某格时只交换该格，其余部分保留并退回半完成状态。
+_Avoid_: 永久锁死、补牌打散、完整消除
+
+**顶部卡牌准备区**:
+拼消消棋盘上方按纵列排列的背面卡牌队列；某列产生空位时，准备区对应列的卡牌从顶部下落补齐。
+_Avoid_: 全局随机发牌槽、底部三消槽
+
+**防死局发牌**:
+拼消消开局和每次补牌后由后端保证至少存在一步可拼接；补牌时至少有一张新掉落卡能与场上剩余某张卡对应。
+_Avoid_: 前端提示代替可解性、完全随机补牌
+
 ### Wooden Fish
 
 **敲木鱼**:

docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md

@@ -0,0 +1,77 @@
+# 拼消消玩法模板 PRD
+
+日期：`2026-05-30`
+
+## 目标
+
+新增玩法模板 **拼消消**，工程域与 `playId` 均为 `puzzle-clear`，公开作品码前缀为 `PC-`。拼消消以拼图的交换 / 拖拽手感为原型，但运行态规则独立：玩家移动 1x1 卡牌碎片，把同一复合图案组拼成完整矩形后消除；消除产生空位后，由顶部对应纵列的卡牌准备区下落补位。
+
+首版必须完成公开闭环：
+
+```text
+创作入口 -> 轻表单工作台 -> 独立生成页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式 runtime -> 基础统计 / 作品架 / 广场
+```
+
+## 创作工具平台接入声明
+
+- 工作台模式：表单 / 图片输入创作工作台。
+- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态。
+- 单图资产槽位：
+  - `board-background` / `ui-background` / `中央场地底图` / `boardBackgroundPrompt` 优先、空值时回退 `themePrompt`，并支持用户上传图 / 写回 `draft.boardBackgroundAsset`、`draft.boardBackgroundPrompt`、`work.boardBackgroundAsset` 与 `work.boardBackgroundPrompt` / 允许历史图 / 允许 AI 重绘。
+  - 中央场地底图的字段名沿用平台表面口径，实际作用是玩家逐步消除清空中央棋盘后慢慢看到的主题目标图；AI 生成尺寸必须与中央棋盘一致，使用 1:1 正方形画面。prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，带来探索、揭开全貌和追求目标完成的感受；不得继续要求“画面干净”或“适合作为卡牌棋盘底图”。
+- 系列素材槽位：
+  - `batchId=puzzle-clear-pattern-atlas-v1`。
+  - `sheetSpec`：4 张素材工作表，每张 `1024x1536` 竖版，后台按 `4 列 x 6 行` 裁切，每个 1x1 单元为 `256x256`；服务端再把切片合成一张 `10x10 / 2560x2560` 最终 atlas。复合图案组总数为 `35`，形状配比 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`，总计 `95` 个 1x1 卡牌切片。
+  - `slotSpecs`：每个复合图案组一个 `patternGroup`，服务端预排 `groupId`、`shape`、atlas 坐标和 1x1 切片坐标。
+  - 切图规则：生图 prompt 只要求复合图案组能按 4x6 素材工作表均等切成 1x1 方形小份，不允许模型在图上绘制切分线、边框、网格线或裁切参考线；服务端按 sheet 布局直接裁出 1x1 卡牌碎片，校验每个编号占格数与领域图案组面积一致，再合成最终 atlas，写入 `patternGroups[]` 与 `cardAssets[]`。
+  - 透明化规则：首版保留完整方形卡面，不强制透明化；若 provider 输出带边框、切分线、网格、裁切参考线或文字，生成任务失败并回写审计。
+  - 失败回写：生成页写回 `generationStatus=failed` 与失败阶段；结果页保留重试入口。
+  - 局部重生成：v1 允许整批 4 张素材工作表重试，不做单组局部重生。
+- API 命名空间：`/api/creation/puzzle-clear/...` 与 `/api/runtime/puzzle-clear/...`。
+- 业务真相：草稿、发布、runtime snapshot、胜负、补牌、防死局、统计均由后端裁决；前端只做动画和交互表现。
+- 创作工具模式例外：无。
+- 验证命令：`npm run check:encoding`、`npm run typecheck`、`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle_clear --manifest-path server-rs/Cargo.toml -- --nocapture`；涉及 SpacetimeDB schema 后运行 `npm run spacetime:generate`、`npm run check:spacetime-runtime-access`、`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`。
+
+## 工作台字段
+
+| 字段 | 契约字段 | 默认值 | 校验 | 落库 |
+| --- | --- | --- | --- | --- |
+| 作品标题 | `workTitle` | 空 | 必填，1-30 字 | session draft / work profile |
+| 简介 | `workDescription` | 空 | 0-120 字 | session draft / work profile |
+| 主题词 | `themePrompt` | 空 | 必填，1-80 字 | 生成 prompt 与草稿 |
+| 场地底图主题词 | `boardBackgroundPrompt` | 空 | 0-80 字；为空时底图生成回退 `themePrompt` | session draft / work profile / 主题目标图生成 prompt |
+| 中央场地底图 | `boardBackgroundAsset` | 空 | 上传或 AI 生成至少一种 | 单图资产槽位 |
+| AI 生成底图 | `generateBoardBackground` | `true` | boolean | 生成编排参数 |
+
+规则参数不开放创作者编辑：棋盘尺寸、倒计时、消除次数、形状解锁、防死局发牌和半锁定规则固定。
+
+## 运行规则
+
+| 关卡 | 棋盘 | 目标消除 | 倒计时 | 解锁形状 |
+| --- | --- | --- | --- | --- |
+| 1 | 6x6 | 35 | 10 分钟 | 1x2、1x3、2x2、2x3 |
+
+- 开局每个小格子从背面翻向正面。
+- 可消除图由横向或纵向复合图案组组成，最小消除单位为两张图拼接。
+- 完成一个复合图案组后，该组所有 1x1 卡牌碎片消除。
+- 消除后空位按列由顶部卡牌准备区下落补齐。
+- 每次补牌至少保证掉落卡中有一张可以与场上剩余某张卡拼接，防止死局。
+- 非 2 格消除时，若场上已有局部完成的半锁定拼接组，补牌不得破坏它。
+- 半锁定拼接组可整体拖动；玩家用外部单格撞入组内某格时，只交换该格，组其余部分保留，组状态退回半完成。
+- 超时只判当前关失败，可重试当前关；完成 35 次目标并清空当前棋盘后整局完成。
+
+## 结果页
+
+结果页展示：素材 atlas、中央场地底图、发布状态、试玩入口和失败重试。结果页不写功能说明类文案，不开放规则编辑器，不新增排行榜配置。
+
+## 统计
+
+首版只记录正式 `published` run：
+
+- 开局。
+- 全局完成。
+- 当前关失败。
+- 耗时。
+- 消除统计。
+
+草稿试玩不写正式统计，不进入排行榜；v1 不做排行榜。

docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md

@@ -0,0 +1,123 @@
+# 拼消消玩法模板技术方案
+
+日期：`2026-05-30`
+
+## 总体边界
+
+拼消消使用独立工程域 `puzzle-clear`，不复用拼图运行态规则本体。实现按 DDD 分层：
+
+- `module-puzzle-clear`：纯领域规则，覆盖图案组规划、棋盘、交换、半锁定、消除、补牌、防死局、关卡状态。
+- `shared-contracts` / `packages/shared`：工作台输入、生成素材、结果页、作品摘要、runtime snapshot 与 action DTO。
+- `spacetime-module`：session、work profile、runtime run、事件 / 统计、公开 source view。
+- `spacetime-client`：typed facade 与 row mapper。
+- `api-server`：Axum 路由、鉴权、入口熔断、生成编排、资产持久化、BFF。
+- `platform-image` / OSS / asset object：图片生成、切图、上传、换签和失败审计。
+- 前端：轻表单、生成页、结果页与 runtime 动画，不承接正式业务真相。
+
+## 资产生成方案
+
+素材目标从“单张超大 atlas 生图”收敛为 4 张素材工作表，再由服务端合成最终 atlas：
+
+- image2 调用：4 次，每次生成 1 张 `1024x1536` 竖版素材工作表。
+- sheet 裁切：每张按 `4 列 x 6 行` 裁切，每个 1x1 单元为 `256x256`。
+- 最终 atlas：服务端把 95 个切片按领域坐标合成 `10x10 / 2560x2560` PNG，空单元保留浅色背景。
+- 运行态素材：最终写回 `35` 个复合图案组和 `95` 个 1x1 卡牌切片；`sheet-03` 的第 6 行第 4 列为 `FILL` 补位格，只为填满 4x6 工作表，生成后会被服务端丢弃，不进入最终 atlas 或运行态卡牌。
+
+服务端固定布局如下：
+
+| 形状 | 数量 | 单组单元数 | 解锁 |
+| --- | ---: | ---: | --- |
+| 1x2 | 23 | 2 | 第 1 关 |
+| 1x3 | 5 | 3 | 第 1 关 |
+| 2x2 | 4 | 4 | 第 1 关 |
+| 2x3 | 3 | 6 | 第 1 关 |
+
+流程：
+
+```text
+主题词 / 场地底图主题词 / 用户底图 -> 4 张 sheet 坐标规划 -> gpt-image-2 生成素材工作表 -> 按 4x6 裁切 1x1 -> 合成最终 atlas -> atlas 与卡牌切片持久化 -> OSS / asset_object / bind -> session draft 回写
+```
+
+中央场地底图的 prompt 来源固定为：若用户填写 `boardBackgroundPrompt`，AI 生成底图只读取该字段；若该字段为空，才回退读取 `themePrompt`。用户直接上传底图资产时不再用主题词重写该资产，只执行平台资产持久化与换签。中央场地底图在运行态不是普通棋盘衬底，而是玩家逐渐消除卡牌后露出的主题目标图；生成请求使用与中央棋盘一致的 1:1 正方形尺寸，prompt 必须强调探索、揭开全貌、追求完成目标、精致主题主视觉和强主题表现，不写“画面干净”或“适合作为卡牌棋盘底图”。
+
+### 素材工作表风险与切片验证
+
+风险：4x6 工作表 prompt 仍需要告诉 provider 编号布局；如果模型把布局理解成 UI 海报、说明图或卡牌模板，可能画出文字、编号、边框、切分线、贴纸外框或重复主体。若 provider 无法严格按布局输出，切片后可能出现跨格、主体贴边、重复图案、文字或图案错位。
+
+验证策略：
+
+- 生图 prompt 明确要求照片式构图 / 绘本式渲染的主题微场景拼图卡，每个 256x256 单元本身就是一张完整的单场景照片裁片，单元内部只能有一个连续画面，禁止出现两张照片、两个不同场景、拼接线、分割线、内部竖切、内部横切、左右 / 上下两块不同背景，场景变化只能发生在 256 单元边界上。
+- 同编号连续格表示同一视觉家族，不是随机独立小图；同组格子要共享同一场景锚点、主色和道具语言，像同一套连拍或同一场景的不同局部，彼此能看出是同一个故事或场景家族。
+- 同一张 sheet 内不同编号必须发散成不同视觉概念；以水果为例，应扩展为果园、集市摊位、野餐布、果汁杯、厨房案板、甜品盘、篮筐、玻璃罐、窗边餐桌、花园背景等微场景，禁止同品种主体换角度、换大小或换姿势后重复出现。
+- 每个 256x256 小卡切片独立查看时也要有可辨识的背景纹理、桌面、草地、天空、建筑、布料、器皿、叶片、阴影或装饰元素，避免“孤立主体 + 纯色背景”导致运行态难区分。
+- 生图 prompt 明确禁止文字、水印、UI、边框标签、切分线、网格线、裁切参考线、纯色背景、白底商品图、孤立主体、同品种重复和同一物体多角度。
+- 复合图案组本身不画任何可见分割辅助线，但 prompt 必须说明每个 `1x2`、`1x3`、`2x2`、`2x3` 图案都能被服务端按等大的 1x1 方形单元切分；纵向 `1x2` 按横向切线分成两个 1x1，横向 `1x2` 按纵向切线分成两个 1x1，其他形状同理。图案组可以在语义上成组，但不能把一张大图的照片边界或拼贴边界落在单个 1x1 单元内部。
+- 服务端保留 `PuzzleClearPatternGroup` 坐标清单，切片前校验每个 sheet 正式编号出现次数等于领域图案组 `width * height`，并要求同编号区域是完整连续矩形；`FILL` 补位格不参与校验、切片、atlas 合成和运行态。
+- 每张 sheet 生成后、正式切片前执行像素级质量门禁：非空格必须达到最低前景占比，空白格前景占比不得超阈值，单格内部明显人工拼贴式分割需要硬失败；内部强边缘检测必须同时满足“贯穿大部分高度或宽度”和“两侧近似低纹理平铺色块”，避免把照片式微场景里的窗框、桌沿、地平线等自然结构误杀。非同组边界前景贴边仅记录为质量提示，不作为硬失败，避免把模型正常铺满主体的图集误杀。
+- 每张 sheet 生成最多尝试 4 次；除质量门禁失败外，VectorEngine 返回 `retryable=true` 的 `502`、`504`、`429` 或请求超时也应消耗下一次 sheet attempt，避免上游 nginx 偶发 502 或单次拼贴式坏图直接把草稿置为 failed。
+- 前端拼消消创作 action 的请求等待窗口为 40 分钟，用于覆盖 VectorEngine 单张图偶发 10 分钟以上的慢返回；这只是本地验收稳定性兜底，后续若继续优化体验，应把素材生成迁到后台任务 / 轮询进度链路。
+- sheet 多次生成仍未通过硬质量门禁时，生成任务进入 `failed` 并写入错误原因；不得把明显空白格污染或主体缺失的工作表切成正式卡牌资产。
+- 首版若当前 provider 无法稳定产出可切 atlas，生成任务进入 `failed`，错误写入审计；不得退回前端假素材或绕过平台资产底座。
+- 草稿编译和作品发布都必须拒绝缺失 atlas、缺失卡牌切片、空 `assetObjectId` / `imageObjectKey` 或 `placeholder` 占位资产；`spacetime-client` 不再为编译请求合成默认 atlas / card assets。
+- 技术回退需要用户确认后才能改成更多 sheet、降低切片规格或改为逐图生成；当前需求固定为 4 张 `1024x1536` sheet 与最终 `2560x2560` atlas。
+
+## 领域规则
+
+`module-puzzle-clear` 已固定以下规则：
+
+- 关卡配置：单关 `6x6/35`，600 秒。
+- 图案组配比：`1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`。
+- 开局随机铺满并保证至少一步可解。
+- 补牌按列重力下落；补牌后仍保证至少一步可解。
+- 完整图案组消除并清空对应格。
+- 半锁定拼接组只由玩家主动交换 / 撞入打散，补牌不破坏。
+- 超时失败只作用于当前单关，可重试；完成 35 次消除目标并清空棋盘后整局完成。
+
+## API 命名空间
+
+- `POST /api/creation/puzzle-clear/sessions`
+- `GET /api/creation/puzzle-clear/sessions/{sessionId}`
+- `POST /api/creation/puzzle-clear/sessions/{sessionId}/actions`
+- `GET /api/creation/puzzle-clear/works`
+- `GET /api/creation/puzzle-clear/works/{profileId}`
+- `POST /api/creation/puzzle-clear/works/{profileId}/publish`
+- `GET /api/runtime/puzzle-clear/works/{profileId}`
+- `POST /api/runtime/puzzle-clear/runs`
+- `POST /api/runtime/puzzle-clear/runs/{runId}/swap`
+- `POST /api/runtime/puzzle-clear/runs/{runId}/retry-level`
+- `POST /api/runtime/puzzle-clear/runs/{runId}/next-level`
+- `POST /api/runtime/puzzle-clear/runs/{runId}/time-up`
+
+api-server 路由熔断使用 SpacetimeDB 创作入口配置 `puzzle-clear`，不得新增前端硬编码事实源。
+
+## Runtime 事件与统计载荷
+
+正式 `published` run 记录开局、全局完成、当前关失败、耗时和消除统计。runtime action 返回的终态事件包括：
+
+- `run-finished`：第 1 关完成并结束整局，结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs`。
+- `level-failed`：当前关超时失败，结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs`。
+
+草稿试玩只消费同一份 snapshot/action 结果做表现，不写正式统计。
+
+## 前端阶段
+
+新增阶段：
+
+- `puzzle-clear-workspace` -> `/creation/puzzle-clear`
+- `puzzle-clear-generating` -> `/creation/puzzle-clear/generating`
+- `puzzle-clear-result` -> `/creation/puzzle-clear/result`
+- `puzzle-clear-runtime` -> `/runtime/puzzle-clear`
+
+runtime 移动端优先，首屏结构为顶部倒计时 / 单关铭牌、顶部列准备区、棋盘、失败 / 完成弹层。棋盘主网格、半锁定组覆盖层和消除 / 掉落覆盖层统一使用 1.5px 格间距。动画包括开场翻转、局部正确拼合高光、完整消除放大淡出和列补牌延迟下落，不再有下一关切换。消除和补牌动画只能作为当前后端 snapshot 的表现层覆盖；已有场上卡片因重力下沉后的最终格不得被旧消除坐标或掉落覆盖层隐藏，避免出现“下方空位但上方卡片未下落”的视觉假象；新补入卡牌应等完整消除淡出进入尾段后再播放下落反馈。
+
+## 验证计划
+
+- `cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`
+- `cargo test -p api-server puzzle_clear --manifest-path server-rs/Cargo.toml -- --nocapture`
+- `cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml puzzle_clear_compile_requires_real_atlas_assets_from_api_server`
+- `npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`
+- `npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`
+- `npm run test -- src/routing/appPageRoutes.test.ts src/services/publicWorkCode.test.ts`
+- `npm run check:encoding`
+- `npm run typecheck`
+- 接入 SpacetimeDB schema 后：`npm run spacetime:generate`、`npm run check:spacetime-runtime-access`、`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`

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

@@ -632,6 +632,45 @@ npm run check:server-rs-ddd
 - Rust 结构体：`PuzzleWorkProfileRow`
 - 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
 
+### `puzzle_clear_agent_session`
+
+- Rust 结构体：`PuzzleClearAgentSessionRow`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
+- 说明：拼消消创作会话表，保存轻表单草稿、生成状态、已发布 profile 关联和更新时间；只由拼消消 procedure 读写。
+
+### `puzzle_clear_work_profile`
+
+- Rust 结构体：`PuzzleClearWorkProfileRow`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
+- 说明：拼消消作品 profile 表，保存中央底图资产、4 张素材工作表切片后合成的最终 atlas、35 个复合图案组、95 个 1x1 卡牌切片、卡背占位图、发布状态、可见性和基础 play count；公开列表 / 详情只通过 read model 消费，不让前端直接订阅源表。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
+
+### `puzzle_clear_runtime_run`
+
+- Rust 结构体：`PuzzleClearRuntimeRunRow`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
+- 说明：拼消消正式 runtime run 表，保存当前关卡、已消除次数、棋盘 snapshot、开始 / 完成时间和 run 状态；正式胜负、重试、完成、超时和交换结果以后端 procedure 裁决为准。
+
+### `puzzle_clear_event`
+
+- Rust 结构体：`PuzzleClearEventRow`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear/tables.rs`
+- 说明：拼消消基础 runtime 事件表，记录 published run 的开局、关卡完成、全局完成、失败、超时和消除统计来源；首版不做排行榜。
+
+### SpacetimeDB view：`puzzle_clear_gallery_view`
+
+- Rust view：`puzzle_clear_gallery_view`
+- 返回类型：`Vec<PuzzleClearGalleryViewRow>`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear.rs`
+- 说明：拼消消公开详情 source 投影，只暴露 `publication_status = published` 且 `visible = true` 的作品，包含 atlas、底图、图案组和卡牌切片等详情级字段；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。
+
+### SpacetimeDB view：`puzzle_clear_gallery_card_view`
+
+- Rust view：`puzzle_clear_gallery_card_view`
+- 返回类型：`Vec<PuzzleClearGalleryCardViewRow>`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle_clear.rs`
+- 说明：拼消消公开列表 source 投影，只暴露平台卡片需要的公开字段；统一公开列表主路径通过 `public_work_gallery_entry` 消费该 view，`/api/runtime/puzzle-clear/gallery` 保留玩法专属 HTTP shape。
+
 ### SpacetimeDB view：`puzzle_gallery_view`
 
 - Rust view：`puzzle_gallery_view`
@@ -661,6 +700,7 @@ npm run check:server-rs-ddd
 - `SELECT * FROM public_work_detail_entry`
 - `SELECT * FROM bark_battle_gallery_view`
 - `SELECT * FROM puzzle_gallery_card_view`
+- `SELECT * FROM puzzle_clear_gallery_card_view`
 - `SELECT * FROM jump_hop_gallery_card_view`
 - `SELECT * FROM wooden_fish_gallery_card_view`
 - `SELECT * FROM custom_world_gallery_entry`
@@ -677,6 +717,7 @@ npm run check:server-rs-ddd
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'visual-novel'`
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'big-fish'`
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'bark-battle'`
+- `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'puzzle-clear'`
 - `SELECT * FROM creation_entry_config`
 - `SELECT * FROM creation_entry_type_config`
 - `SELECT * FROM asset_object`

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

@@ -1,4 +1,4 @@
-# 本地开发验证与生产运维
+# 本地开发验证与生产运维
 
 更新时间：`2026-06-05`
 
@@ -51,6 +51,8 @@ Linux 本机多用户并发开发时，`npm run dev` 和 `npm run dev:*` 单模
 
 开发态 `npm run dev` 与 `npm run dev:api-server` 会默认注入 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，因此密码登录在本地开发环境可直接注册未知手机号账号；生产环境仍按 `api-server` 配置默认关闭该开关。
 
+本地只做账号/UI smoke 且需要短信登录时，`SMS_AUTH_PROVIDER` 应显式设为 `mock`，并把 `SMS_AUTH_MOCK_VERIFY_CODE` 设为固定值（当前常用 `123456`），再重启 `npm run dev` 或 `npm run dev:api-server`。如果 `.env.local` 还保留 `SMS_AUTH_PROVIDER=aliyun`，`POST /api/auth/phone/login` 用 mock 验证码会稳定报“验证码错误”，不是前端表单问题。真实短信联调再切回 `aliyun` 并重启。
+
 微信小程序虚拟支付使用 `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_OFFER_ID`、`WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_APP_KEY`、`WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_SANDBOX_APP_KEY` 和 `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV` 配置。小程序充值统一走 `wechat_mp_virtual` / `wx.requestVirtualPayment`：泥点属于代币（`coin`），`buyQuantity` 按当前充值商品快照里的 `points_amount` 传；会员和后台新增道具类商品走 `short_series_goods`，`productId` 对应微信后台道具 ID。旧登录快照若缺 `session_key`，需要用户在小程序内重新登录后再支付；客户端成功回调不是最终到账，仍以后端通知或查询确认订单为准。详细口径见 `docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。
 
 如果本地 `GET /api/creation-entry/config` 返回 `No such procedure`，或 `api-server` 日志出现 `no such table: puzzle_gallery_card_view` / `no such table: wooden_fish_gallery_card_view` 这类公开 view 缺失，通常是 `.env.local` 指向的 SpacetimeDB 库还没有发布当前 `spacetime-module`，或当前 CLI 身份无权发布该库。debug 构建的 `api-server` 会临时使用后端默认入口配置兜底，避免创作作品架整块消失；正式修复仍应切换到拥有目标库权限的 SpacetimeDB 身份后重新运行 `npm run dev` 完成发布，或用 gitignored 的 `spacetime.local.json` 指向可发布的本地库。

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

@@ -195,6 +195,34 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 
 平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 `sourceType='wooden-fish'` 与 `WF-*` 公开作品号识别敲木鱼作品；公开列表应走 `wooden_fish_gallery_card_view` 订阅缓存，公开详情或运行态启动时卡片摘要不足则补读完整 work profile。
 
+## 拼消消
+
+对外名称：拼消消。工程域与 `playId`：`puzzle-clear`。公开作品码前缀：`PC-`。当前按新增玩法 SOP 接入完整公开闭环，不复用拼图运行态规则本体。
+
+链路为：
+
+```text
+创作入口 -> 轻表单工作台 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式运行态
+```
+
+工作台字段固定为作品标题、简介、主题词、场地底图主题词 `boardBackgroundPrompt`、中央场地底图槽位、是否 AI 生成底图。中央场地底图必须复用 `CreativeImageInputPanel`，支持上传、历史图和 AI 重绘；若用户填写 `boardBackgroundPrompt`，AI 生成底图只读取该字段，字段为空时才回退读取 `themePrompt`；用户上传底图时不再用主题词重写该资产。中央场地底图的字段名保留平台口径，但实际语义是玩家逐步消除清空棋盘后露出的主题目标图，生成尺寸必须与中央棋盘一致，按 1:1 正方形出图；prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，不再要求“画面干净”或“适合作为卡牌棋盘底图”。运行态必须把中央场地底图作为棋盘内部静态底图使用，不能降级成整页氛围背景；卡牌消除后产生的空位和拖拽源位应露出该棋盘底图。卡面背面背景 v1 使用默认占位图，不作为创作者配置项。规则参数不开放编辑：单关 `6x6`、每局 10 分钟、35 次目标消除、形状解锁、防死局发牌和半锁定规则均由后端规则集固定。
+
+素材生成使用拼消消专用编排，但必须复用 `platform-image`、VectorEngine `gpt-image-2`、OSS、`asset_object`、换签和失败审计。素材目标是 4 张 `1024x1536` 竖版工作表，每张后台按 `4 列 x 6 行` 裁切，每格 `256x256`；服务端从工作表切出总计 95 个 1x1 卡牌碎片，再合成一张 `10x10 / 2560x2560` 最终 atlas。复合图案组总数固定为 35，形状配比固定为 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`。服务端先预排每个复合图案组的 sheet 布局、最终 atlas 坐标和形状，再按坐标切成 1x1 卡牌碎片作为运行态素材；sheet 生图 prompt 只能要求复合图案组可按后台 4x6 均等切成 1x1 方形小份，不能让模型在小图案上绘制切分线、边框、网格线、编号或裁切参考线。当前只有单关，同关内复合图案不重复。草稿编译和发布都必须使用 api-server 已持久化的真实 atlas / card assets，拒绝缺失、空对象键或 `placeholder` 占位素材，不允许 `spacetime-client` 或 SpacetimeDB 侧合成临时素材绕过平台图片底座。
+
+运行态规则：
+
+1. 单关固定为 `6x6 / 35次消除`。
+2. 每局固定 10 分钟；超时只判当前关失败，可重试当前关。
+3. 当前关直接出现 `1x2`、`1x3`、`2x2` 和 `2x3`。
+4. 开局棋盘随机铺满并保证至少一步可解；补牌后也必须由后端保证至少一步可解。
+5. 顶部卡牌准备区按纵列补位，某列有空格时该列卡牌从顶部下落。
+6. 非 2 格消除时，补牌不得破坏已完成局部；只有玩家主动交换或撞入才允许打散半锁定拼接组。
+7. 正式 runtime 只消费后端 snapshot 与 action 结果；前端负责开局翻转、拖拽、掉落、消除和弹层动画。
+   拖拽手感必须对齐拼图模板：开局小卡片只翻转一次，交换落位不得重新翻牌；按住后可见卡片立即跟随鼠标或手指，源位置即时留出空槽；放下时被替换卡片要快速飞向对应空位；已完成局部拼接组要以连续整体呈现并可作为整组拖起。拖拽浮层必须挂到页面级 `document.body` portal，避免平台壳层 transform 让 `position: fixed` 和 `clientX/clientY` 坐标系错位。
+8. 正式 `published` run 的终态事件使用 `run-finished` 和 `level-failed`，事件结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta` 和 `elapsedMs`，供基础统计与排障回读。
+
+新增阶段为 `puzzle-clear-workspace`、`puzzle-clear-generating`、`puzzle-clear-result` 和 `puzzle-clear-runtime`；路由为 `/creation/puzzle-clear`、`/creation/puzzle-clear/generating`、`/creation/puzzle-clear/result` 与 `/runtime/puzzle-clear`。API 命名空间为 `/api/creation/puzzle-clear/*` 与 `/api/runtime/puzzle-clear/*`。验证命令见 `docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md` 与 `docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`。
+
 ## 抓大鹅 Match3D
 
 对外名称：`抓大鹅`。工程域：`match3d`。

packages/shared/src/contracts/index.ts

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

packages/shared/src/contracts/puzzleClear.ts

@@ -0,0 +1,226 @@
+export type PuzzleClearGenerationStatus = 'draft' | 'generating' | 'ready' | 'failed';
+
+export type PuzzleClearShapeKind = '1x2' | '1x3' | '2x2' | '2x3';
+
+export type PuzzleClearOrientation = 'horizontal' | 'vertical';
+
+export type PuzzleClearRunStatus =
+  | 'playing'
+  | 'level_failed'
+  | 'level_cleared'
+  | 'finished';
+
+export type PuzzleClearActionType =
+  | 'compile-draft'
+  | 'regenerate-atlas'
+  | 'update-work-meta'
+  | 'update-board-background';
+
+export interface PuzzleClearImageAsset {
+  assetId: string;
+  imageSrc: string;
+  imageObjectKey: string;
+  assetObjectId: string;
+  generationProvider: string;
+  prompt: string;
+  width: number;
+  height: number;
+}
+
+export interface PuzzleClearPatternGroup {
+  groupId: string;
+  shape: PuzzleClearShapeKind;
+  width: number;
+  height: number;
+  atlasX: number;
+  atlasY: number;
+  atlasWidth: number;
+  atlasHeight: number;
+}
+
+export interface PuzzleClearCardAsset {
+  cardId: string;
+  groupId: string;
+  shape: PuzzleClearShapeKind;
+  orientation: PuzzleClearOrientation;
+  partX: number;
+  partY: number;
+  imageSrc: string;
+  imageObjectKey: string;
+  assetObjectId: string;
+  sourceAtlasCell: string;
+}
+
+export interface PuzzleClearWorkspaceCreateRequest {
+  templateId: 'puzzle-clear' | string;
+  workTitle: string;
+  workDescription: string;
+  themePrompt: string;
+  boardBackgroundPrompt: string;
+  generateBoardBackground: boolean;
+  boardBackgroundAsset?: PuzzleClearImageAsset | null;
+}
+
+export interface PuzzleClearActionRequest {
+  actionType: PuzzleClearActionType;
+  profileId?: string | null;
+  workTitle?: string | null;
+  workDescription?: string | null;
+  themePrompt?: string | null;
+  boardBackgroundPrompt?: string | null;
+  generateBoardBackground?: boolean | null;
+  boardBackgroundAsset?: PuzzleClearImageAsset | null;
+  atlasAsset?: PuzzleClearImageAsset | null;
+  patternGroups?: PuzzleClearPatternGroup[] | null;
+  cardAssets?: PuzzleClearCardAsset[] | null;
+}
+
+export interface PuzzleClearDraftResponse {
+  templateId: string;
+  templateName: string;
+  profileId: string | null;
+  workTitle: string;
+  workDescription: string;
+  themePrompt: string;
+  boardBackgroundPrompt: string;
+  generateBoardBackground: boolean;
+  boardBackgroundAsset: PuzzleClearImageAsset | null;
+  cardBackImageSrc: string | null;
+  atlasAsset: PuzzleClearImageAsset | null;
+  patternGroups: PuzzleClearPatternGroup[];
+  cardAssets: PuzzleClearCardAsset[];
+  generationStatus: PuzzleClearGenerationStatus;
+}
+
+export interface PuzzleClearSessionSnapshotResponse {
+  sessionId: string;
+  ownerUserId: string;
+  status: PuzzleClearGenerationStatus;
+  draft: PuzzleClearDraftResponse | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface PuzzleClearSessionResponse {
+  session: PuzzleClearSessionSnapshotResponse;
+}
+
+export interface PuzzleClearActionResponse {
+  actionType: PuzzleClearActionType;
+  session: PuzzleClearSessionSnapshotResponse;
+  work: PuzzleClearWorkProfileResponse | null;
+}
+
+export interface PuzzleClearWorkSummaryResponse {
+  runtimeKind: 'puzzle-clear';
+  workId: string;
+  profileId: string;
+  ownerUserId: string;
+  sourceSessionId: string | null;
+  workTitle: string;
+  workDescription: string;
+  themePrompt: string;
+  coverImageSrc: string | null;
+  publicationStatus: string;
+  playCount: number;
+  updatedAt: string;
+  publishedAt: string | null;
+  publishReady: boolean;
+  generationStatus: PuzzleClearGenerationStatus;
+}
+
+export interface PuzzleClearWorkProfileResponse {
+  summary: PuzzleClearWorkSummaryResponse;
+  draft: PuzzleClearDraftResponse;
+  boardBackgroundAsset: PuzzleClearImageAsset | null;
+  atlasAsset: PuzzleClearImageAsset;
+  patternGroups: PuzzleClearPatternGroup[];
+  cardAssets: PuzzleClearCardAsset[];
+}
+
+export interface PuzzleClearWorksResponse {
+  items: PuzzleClearWorkSummaryResponse[];
+}
+
+export interface PuzzleClearWorkDetailResponse {
+  item: PuzzleClearWorkProfileResponse;
+}
+
+export interface PuzzleClearWorkMutationResponse {
+  item: PuzzleClearWorkProfileResponse;
+}
+
+export interface PuzzleClearGalleryCardResponse
+  extends PuzzleClearWorkSummaryResponse {
+  publicWorkCode?: string;
+  authorDisplayName?: string;
+  recentPlayCount7d?: number;
+}
+
+export interface PuzzleClearGalleryResponse {
+  items: PuzzleClearGalleryCardResponse[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export interface PuzzleClearGalleryDetailResponse {
+  item: PuzzleClearWorkProfileResponse;
+}
+
+export interface PuzzleClearBoardCell {
+  row: number;
+  col: number;
+  card: PuzzleClearCardAsset | null;
+  lockedGroupId: string | null;
+}
+
+export interface PuzzleClearBoardSnapshot {
+  rows: number;
+  cols: number;
+  cells: PuzzleClearBoardCell[];
+}
+
+export interface PuzzleClearRuntimeSnapshotResponse {
+  runId: string;
+  profileId: string;
+  ownerUserId: string;
+  runtimeMode?: 'draft' | 'published';
+  status: PuzzleClearRunStatus;
+  levelIndex: number;
+  clearsDone: number;
+  targetClears: number;
+  levelDurationSeconds: number;
+  levelStartedAtMs: number;
+  board: PuzzleClearBoardSnapshot;
+  readyColumns: PuzzleClearCardAsset[][];
+  startedAtMs: number;
+  finishedAtMs: number | null;
+}
+
+export interface PuzzleClearRunResponse {
+  run: PuzzleClearRuntimeSnapshotResponse;
+}
+
+export interface PuzzleClearStartRunRequest {
+  profileId: string;
+}
+
+export interface PuzzleClearSwapRequest {
+  fromRow: number;
+  fromCol: number;
+  toRow: number;
+  toCol: number;
+  clientActionId: string;
+}
+
+export interface PuzzleClearRetryLevelRequest {
+  clientActionId: string;
+}
+
+export interface PuzzleClearNextLevelRequest {
+  clientActionId: string;
+}
+
+export interface PuzzleClearTimeUpRequest {
+  clientActionId: string;
+}

scripts/check-spacetime-schema-guard.mjs

@@ -477,8 +477,14 @@ function getChangedFiles(baseRef) {
   const diffOutput = tryGit(['diff', '--name-only', '-z', baseRef, '--']) ?? '';
   const untrackedOutput =
     tryGit(['ls-files', '--others', '--exclude-standard', '-z', moduleSrcRoot]) ?? '';
+  const untrackedBindingsOutput =
+    tryGit(['ls-files', '--others', '--exclude-standard', '-z', bindingsRoot]) ?? '';
   return new Set(
-    [...diffOutput.split(/\u0000/u), ...untrackedOutput.split(/\u0000/u)]
+    [
+      ...diffOutput.split(/\u0000/u),
+      ...untrackedOutput.split(/\u0000/u),
+      ...untrackedBindingsOutput.split(/\u0000/u),
+    ]
       .map(normalizePath)
       .filter(Boolean),
   );

scripts/dev-utils.test.ts

@@ -88,6 +88,29 @@ describe('dev utils env merge', () => {
     );
   });
 
+  test('本地短信 smoke 可以用 mock 验证码覆盖真实短信 provider 口径', () => {
+    withTempEnvFiles(
+      {
+        '.env.local': [
+          'SMS_AUTH_ENABLED=true',
+          'SMS_AUTH_PROVIDER=mock',
+          'SMS_AUTH_MOCK_VERIFY_CODE=123456',
+        ].join('\n'),
+      },
+      (_env, tempDir) => {
+        const env = mergeApiServerEnv(tempDir, {
+          SMS_AUTH_ENABLED: 'true',
+          SMS_AUTH_PROVIDER: 'aliyun',
+          SMS_AUTH_MOCK_VERIFY_CODE: '654321',
+        });
+
+        expect(env.SMS_AUTH_ENABLED).toBe('true');
+        expect(env.SMS_AUTH_PROVIDER).toBe('mock');
+        expect(env.SMS_AUTH_MOCK_VERIFY_CODE).toBe('123456');
+      },
+    );
+  });
+
   test('空外层 shell 变量不会遮蔽本地私密配置', () => {
     withTempEnvFiles(
       {

scripts/dev.mjs

@@ -5,6 +5,7 @@ import {
   existsSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   statSync,
   watch,
   writeFileSync,
@@ -2046,6 +2047,36 @@ function normalizePath(path) {
   return path.replace(/\\/gu, '/');
 }
 
+function normalizeDirectExecutionPath(path) {
+  return normalizePath(path).replace(/^\/([A-Za-z]:\/)/u, '$1');
+}
+
+function safeRealpath(pathValue) {
+  try {
+    return realpathSync(pathValue);
+  } catch {
+    return resolve(pathValue);
+  }
+}
+
+function isDirectModuleExecution(argv1, moduleUrl, resolvePath = safeRealpath) {
+  if (!argv1) {
+    return false;
+  }
+
+  try {
+    return (
+      normalizeDirectExecutionPath(resolvePath(argv1)) ===
+      normalizeDirectExecutionPath(resolvePath(fileURLToPath(moduleUrl)))
+    );
+  } catch {
+    return (
+      normalizeDirectExecutionPath(resolve(argv1)) ===
+      normalizeDirectExecutionPath(fileURLToPath(moduleUrl))
+    );
+  }
+}
+
 function buildSpacetimePublishArgs({database, server, preserveDatabase}) {
   const args = [
     'publish',
@@ -2098,6 +2129,7 @@ export {
   createDevServerSpawnOptions,
   createWatchConfigs,
   isSpacetimePublishPermissionError,
+  isDirectModuleExecution,
   parseSpacetimeToolVersion,
   parseArgs,
   resolveDevStackStatePath,
@@ -2129,6 +2161,6 @@ async function main() {
   }
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectModuleExecution(process.argv[1], import.meta.url)) {
   void main();
 }

scripts/dev.test.ts

@@ -13,6 +13,7 @@ import {
   buildSpacetimePublishArgs,
   createDevServerSpawnOptions,
   createWatchConfigs,
+  isDirectModuleExecution,
   isSpacetimePublishPermissionError,
   parseSpacetimeToolVersion,
   parseArgs,
@@ -39,6 +40,19 @@ function workspaceSpacetimeVersionForTest() {
 describe('dev scheduler argument routing', () => {
   const linuxTest = process.platform === 'linux' ? test : test.skip;
 
+  test('Windows junction 路径下的直接执行入口也能识别为当前模块', () => {
+    const moduleUrl =
+      'file:///F:/DevWorktrees/codex/worktrees/f584/Genarrative/scripts/dev.mjs';
+    const argv1 =
+      'C:\\Users\\wuxiangwanzi\\.codex\\worktrees\\f584\\Genarrative\\scripts\\dev.mjs';
+    const resolvePath = (value) =>
+      value.startsWith('C:\\Users\\')
+        ? 'F:\\DevWorktrees\\codex\\worktrees\\f584\\Genarrative\\scripts\\dev.mjs'
+        : value;
+
+    expect(isDirectModuleExecution(argv1, moduleUrl, resolvePath)).toBe(true);
+  });
+
   test('完整 dev 栈覆盖前端代理到本次解析出的 api-server 地址', () => {
     const {command, explicitOptions, options} = parseArgs([], {
       GENARRATIVE_API_PORT: '8090',

server-rs/Cargo.lock

@@ -113,6 +113,7 @@ dependencies = [
  "module-match3d",
  "module-npc",
  "module-puzzle",
+ "module-puzzle-clear",
  "module-runtime",
  "module-runtime-item",
  "module-runtime-story",
@@ -1971,6 +1972,15 @@ dependencies = [
  "spacetimedb",
 ]
 
+[[package]]
+name = "module-puzzle-clear"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "shared-kernel",
+ "spacetimedb",
+]
+
 [[package]]
 name = "module-quest"
 version = "0.1.0"
@@ -3416,6 +3426,7 @@ dependencies = [
  "module-match3d",
  "module-npc",
  "module-puzzle",
+ "module-puzzle-clear",
  "module-runtime",
  "module-runtime-item",
  "module-runtime-story",
@@ -3451,6 +3462,7 @@ dependencies = [
  "module-npc",
  "module-progression",
  "module-puzzle",
+ "module-puzzle-clear",
  "module-quest",
  "module-runtime",
  "module-runtime-item",

server-rs/Cargo.toml

@@ -22,6 +22,7 @@ members = [
     "crates/module-match3d",
     "crates/module-npc",
     "crates/module-puzzle",
+    "crates/module-puzzle-clear",
     "crates/module-progression",
     "crates/module-quest",
     "crates/module-runtime",
@@ -68,6 +69,7 @@ module-match3d = { path = "crates/module-match3d", default-features = false }
 module-npc = { path = "crates/module-npc", default-features = false }
 module-progression = { path = "crates/module-progression", default-features = false }
 module-puzzle = { path = "crates/module-puzzle", default-features = false }
+module-puzzle-clear = { path = "crates/module-puzzle-clear", default-features = false }
 module-quest = { path = "crates/module-quest", default-features = false }
 module-runtime = { path = "crates/module-runtime", default-features = false }
 module-runtime-item = { path = "crates/module-runtime-item", default-features = false }

server-rs/crates/api-server/Cargo.toml

@@ -29,6 +29,7 @@ module-inventory = { workspace = true }
 module-match3d = { workspace = true }
 module-npc = { workspace = true }
 module-puzzle = { workspace = true }
+module-puzzle-clear = { workspace = true }
 module-runtime = { workspace = true }
 module-runtime-story = { workspace = true }
 module-runtime-item = { workspace = true }

server-rs/crates/api-server/src/app.rs

@@ -67,6 +67,7 @@ pub fn build_router(state: AppState) -> Router {
         .merge(modules::jump_hop::router(state.clone()))
         .merge(modules::wooden_fish::router(state.clone()))
         .merge(modules::public_work::router(state.clone()))
+        .merge(modules::puzzle_clear::router(state.clone()))
         .merge(modules::puzzle::router(state.clone()))
         .merge(visual_novel_router(state.clone()))
         .route(
@@ -4135,8 +4136,7 @@ mod tests {
             .await
             .expect("banners body should collect")
             .to_bytes();
-        let payload: Value =
-            serde_json::from_slice(&body).expect("banners payload should be json");
+        let payload: Value = serde_json::from_slice(&body).expect("banners payload should be json");
 
         assert_eq!(payload["eventBanners"][0]["title"], "后台表单公告");
         assert_eq!(payload["eventBanners"][0]["renderMode"], "html");

server-rs/crates/api-server/src/creation_entry_config.rs

@@ -77,17 +77,13 @@ pub fn resolve_creation_entry_route_id(path: &str) -> Option<&'static str> {
     {
         return Some("puzzle");
     }
-    if normalized.starts_with("/api/runtime/puzzle/gallery/")
-        && normalized.ends_with("/remix")
-    {
+    if normalized.starts_with("/api/runtime/puzzle/gallery/") && normalized.ends_with("/remix") {
         return Some("puzzle");
     }
     if normalized == "/api/runtime/big-fish/agent/sessions" {
         return Some("big-fish");
     }
-    if normalized.starts_with("/api/runtime/big-fish/gallery/")
-        && normalized.ends_with("/remix")
-    {
+    if normalized.starts_with("/api/runtime/big-fish/gallery/") && normalized.ends_with("/remix") {
         return Some("big-fish");
     }
     if normalized == "/api/runtime/custom-world/agent/sessions"
@@ -115,6 +111,9 @@ pub fn resolve_creation_entry_route_id(path: &str) -> Option<&'static str> {
     if normalized == "/api/creation/jump-hop/sessions" {
         return Some("jump-hop");
     }
+    if normalized == "/api/creation/puzzle-clear/sessions" {
+        return Some("puzzle-clear");
+    }
     if normalized == "/api/creation/visual-novel/sessions" {
         return Some("visual-novel");
     }
@@ -178,6 +177,10 @@ mod tests {
             resolve_creation_entry_route_id("/api/runtime/puzzle/agent/sessions"),
             Some("puzzle"),
         );
+        assert_eq!(
+            resolve_creation_entry_route_id("/api/creation/puzzle-clear/sessions"),
+            Some("puzzle-clear"),
+        );
         assert_eq!(
             resolve_creation_entry_route_id("/api/runtime/puzzle/gallery/profile-1/remix"),
             Some("puzzle"),
@@ -236,6 +239,10 @@ mod tests {
             resolve_creation_entry_route_id("/api/runtime/wooden-fish/runs/run-1"),
             None,
         );
+        assert_eq!(
+            resolve_creation_entry_route_id("/api/runtime/puzzle-clear/runs/run-1"),
+            None,
+        );
         assert_eq!(
             resolve_creation_entry_route_id("/api/creation/wooden-fish/sessions"),
             Some("wooden-fish"),

server-rs/crates/api-server/src/http_error.rs

@@ -42,6 +42,10 @@ impl AppError {
         &self.message
     }
 
+    pub fn details(&self) -> Option<&Value> {
+        self.details.as_ref()
+    }
+
     pub fn body_text(&self) -> String {
         // 批处理任务不能只读 HTTP 状态文案，否则 DashScope 返回的真实失败原因会被压成“上游服务请求失败”。
         self.details

server-rs/crates/api-server/src/main.rs

@@ -64,6 +64,7 @@ mod prompt;
 mod public_work;
 mod puzzle;
 mod puzzle_agent_turn;
+mod puzzle_clear;
 mod puzzle_gallery_cache;
 mod refresh_session;
 mod registration_reward;

server-rs/crates/api-server/src/modules.rs

@@ -13,6 +13,7 @@ pub mod platform;
 pub mod profile;
 pub mod public_work;
 pub mod puzzle;
+pub mod puzzle_clear;
 pub mod square_hole;
 pub mod story;
 pub mod wooden_fish;

server-rs/crates/api-server/src/modules/puzzle_clear.rs

@@ -0,0 +1,116 @@
+use axum::{
+    Router, middleware,
+    routing::{get, post},
+};
+
+use crate::{
+    auth::{require_bearer_auth, require_runtime_principal_auth},
+    puzzle_clear::{
+        advance_puzzle_clear_next_level, create_puzzle_clear_session, execute_puzzle_clear_action,
+        get_puzzle_clear_gallery_detail, get_puzzle_clear_run, get_puzzle_clear_runtime_work,
+        get_puzzle_clear_session, get_puzzle_clear_work, list_puzzle_clear_gallery,
+        list_puzzle_clear_works, mark_puzzle_clear_level_time_up, publish_puzzle_clear_work,
+        retry_puzzle_clear_level, start_puzzle_clear_run, swap_puzzle_clear_cards,
+    },
+    state::AppState,
+};
+
+pub fn router(state: AppState) -> Router<AppState> {
+    Router::new()
+        .route(
+            "/api/creation/puzzle-clear/sessions",
+            post(create_puzzle_clear_session).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/puzzle-clear/sessions/{session_id}",
+            get(get_puzzle_clear_session).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/puzzle-clear/sessions/{session_id}/actions",
+            post(execute_puzzle_clear_action).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/puzzle-clear/works",
+            get(list_puzzle_clear_works).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/puzzle-clear/works/{profile_id}",
+            get(get_puzzle_clear_work).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/creation/puzzle-clear/works/{profile_id}/publish",
+            post(publish_puzzle_clear_work).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/works/{profile_id}",
+            get(get_puzzle_clear_runtime_work),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/runs",
+            post(start_puzzle_clear_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_runtime_principal_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/runs/{run_id}",
+            get(get_puzzle_clear_run).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_runtime_principal_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/runs/{run_id}/swap",
+            post(swap_puzzle_clear_cards).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_runtime_principal_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/runs/{run_id}/retry-level",
+            post(retry_puzzle_clear_level).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_runtime_principal_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/runs/{run_id}/next-level",
+            post(advance_puzzle_clear_next_level).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_runtime_principal_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/runs/{run_id}/time-up",
+            post(mark_puzzle_clear_level_time_up).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_runtime_principal_auth,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/gallery",
+            get(list_puzzle_clear_gallery),
+        )
+        .route(
+            "/api/runtime/puzzle-clear/gallery/{public_work_code}",
+            get(get_puzzle_clear_gallery_detail),
+        )
+}