1

2026-05-08 11:44:42 +08:00
parent b08127031c
commit abf1f1ebea
249 changed files with 39411 additions and 887 deletions
--- a/docs/prd/AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md
+++ b/docs/prd/AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md
@@ -0,0 +1,863 @@
+# AI 原生 2048 游戏玩法模板 PRD
+
+更新时间：`2026-05-05`
+
+## 0. 文档目的
+
+这份 PRD 用于在当前平台内新增一条 `2048` 游戏玩法模板，并冻结它从创作入口、Agent 生成、结果页编辑、试玩、发布、公开运行到作品架展示的完整产品边界。
+
+本次不是只做一个浏览器本地 2048 小游戏，也不是把经典 2048 规则随手写进某个前端组件。正式落地时，`2048` 必须作为平台内独立玩法类型接入现有创作中心、作品、广场、运行态和后端 DDD 分层。
+
+---
+
+## 1. 一句话定义
+
+`2048` 是一个主题化数字合成玩法模板：百梦主通过 Agent 设定棋盘主题、合成链、视觉皮肤、目标格和难度参数，系统生成可试玩、可发布的 2048 作品；玩家通过滑动方向移动棋盘格，相同等级方块合并升级，直到达成目标格或棋盘无可行动作。
+
+---
+
+## 2. 当前接入级别
+
+根据 `genarrative-play-type-integration` 的接入分级，本玩法按 **完整玩法闭环** 设计：
+
+1. 新增玩法 ID：`twenty-forty-eight`。
+2. 展示名称：`2048`。
+3. 子标题：`主题合成棋盘`。
+4. 新建作品入口可展示，开放节奏由 `src/config/newWorkEntryConfig.ts` 控制。
+5. 支持 Agent 创作、草稿生成、结果页编辑、试玩、发布、公开运行、作品架和广场。
+6. 后端以 `server-rs + Axum + SpacetimeDB` 为服务侧真相源。
+7. 前端负责棋盘渲染、输入采集和动画表现，不绕过后端保存正式运行结果、榜单、扣费和发布状态。
+
+工程命名采用 `twenty-forty-eight` 而不是裸 `2048`，避免 TypeScript、Rust 模块、文件名和路由中出现数字开头命名；面向用户的标题始终显示 `2048`。
+
+---
+
+## 3. 产品定位
+
+## 3.1 模板名称
+
+1. 对外模板名称：`2048`。
+2. 对外子标题：`主题合成棋盘`。
+3. 开发代号：`TwentyFortyEight`。
+4. 工程玩法域：`twenty-forty-eight`。
+5. 后端模块命名：`twenty_forty_eight`。
+6. 公开作品号前缀：`TF-`。
+
+## 3.2 核心乐趣
+
+1. 玩家通过一次滑动改变整盘局势。
+2. 相同方块合并升级，形成清晰的成长反馈。
+3. 主题化合成链让数字升级变成可感知的叙事或收藏序列。
+4. 棋盘越来越拥挤，玩家在空间管理和短期收益之间做取舍。
+5. 达成目标格后可以继续冲击更高分，也可以结算分享成绩。
+
+## 3.3 与现有玩法的区别
+
+1. 不等同于拼图：不切图、不交换、不合并图片碎片。
+2. 不等同于抓大鹅：不做三消备选栏，不做物体堆叠点击。
+3. 不等同于方洞挑战：不做单次投放裁决，不靠反直觉规则制造误导。
+4. 不等同于大鱼吃小鱼：不做实时移动、吞噬和碰撞成长。
+5. 不复用 RPG 的世界、角色、章节或剧情推进结构。
+
+---
+
+## 4. 完整闭环目标
+
+本玩法完整闭环必须补齐：
+
+1. 平台创作中心选择 `2048`。
+2. Agent 对话收集主题、合成链、视觉风格、目标格和难度。
+3. 生成 2048 草稿。
+4. 进入结果页编辑作品名、简介、标签、封面、棋盘配置和方块皮肤。
+5. 支持发布前试玩。
+6. 发布作品。
+7. 玩家从作品详情、广场或作品架进入运行态。
+8. 后端初始化 run，保存种子、当前棋盘、分数、目标、状态和动作序列摘要。
+9. 玩家滑动方向后，前端提交动作，后端裁决新棋盘；前端按返回快照播放移动与合并动画。
+10. 达成目标、继续挑战、失败结算和排行榜写入都由后端正式裁决。
+11. 前端不得自行提交伪造分数、目标达成或榜单记录。
+
+---
+
+## 5. 明确不做
+
+首版不做：
+
+1. 不做多人实时对战。
+2. 不做复杂技能树或 RPG 数值养成。
+3. 不做可破坏障碍、棋盘机关和随机事件。
+4. 不支持玩家自定义任意 JavaScript 规则。
+5. 不在 UI 中默认展示长篇玩法说明、规则描述或内部字段解释。
+6. 不新增独立于平台之外的 2048 站点。
+7. 不复用 `customWorld`、`rpgWorld` 或旧 `server-node` 命名承载 2048 业务。
+8. 不把 LLM、生图、OSS 上传放进 SpacetimeDB reducer。
+
+---
+
+## 6. 创作锚点设计
+
+Agent 型创作至少收集下面 5 个锚点：
+
+| 锚点 | 字段建议 | 用途 |
+| --- | --- | --- |
+| 合成主题 | `themePrompt` | 决定棋盘整体题材，例如修仙境界、猫咪成长、城市建设、料理升级。 |
+| 合成链 | `tileLadder` | 决定从 `2` 到目标格的每一级显示名、图标提示和视觉差异。 |
+| 视觉皮肤 | `visualStyle` | 决定方块材质、色彩、背景、动效气质和封面方向。 |
+| 难度参数 | `difficultyConfig` | 决定棋盘尺寸、目标格、初始方块、生成概率和是否允许撤销。 |
+| 反馈节奏 | `feedbackRhythm` | 决定移动、合并、升级、目标达成、失败结算的反馈强度。 |
+
+Agent 行为要求：
+
+1. 优先接住百梦主的一句话灵感，不把创作变成问卷。
+2. 每轮最多追问 1 个最影响成品质量的问题。
+3. 当主题和合成链已经足够明确时，优先生成草稿。
+4. 合成链必须围绕同一主题递进，不允许出现互不相关的方块名。
+5. 进入结果页前至少生成 `2` 到目标格之间的完整等级定义。
+
+---
+
+## 7. 玩法规则
+
+## 7.1 棋盘
+
+首版默认支持：
+
+1. `4x4` 标准棋盘。
+2. 可选 `5x5` 放松棋盘。
+3. 可选 `3x3` 高压棋盘。
+
+发布默认值：
+
+1. `boardSize = 4`。
+2. `targetTileValue = 2048`。
+3. 初始方块数量为 `2`。
+4. 新方块生成值为 `2` 或 `4`。
+5. `2` 的生成概率为 `90%`，`4` 的生成概率为 `10%`。
+
+## 7.2 输入
+
+玩家每次只能提交一个方向：
+
+```ts
+type TwentyFortyEightMoveDirection = 'up' | 'down' | 'left' | 'right';
+```
+
+交互支持：
+
+1. 移动端滑动。
+2. 桌面端方向键。
+3. 桌面端按钮或触控手势兜底。
+
+无效输入规则：
+
+1. 如果某方向不会改变棋盘，该动作不消耗步数。
+2. 无效动作返回当前快照和 `moveAccepted = false`。
+3. 前端只展示轻量反馈，不弹长说明。
+
+## 7.3 合并
+
+合并规则遵循经典 2048：
+
+1. 同一行或列按移动方向压缩。
+2. 相邻且同值的两个方块合并成一个更高值方块。
+3. 每个方块在一次移动中最多合并一次。
+4. 合并后的方块值为原值的 `2` 倍。
+5. 本次得分增加合并后方块值。
+6. 移动完成后，如果棋盘有变化，随机空格生成一个新方块。
+
+规则核心应封装为可测试的领域引擎。实现时优先评估成熟 2048 规则库；如 Rust / TypeScript 生态无合适库，必须把自研规则收敛在 `module-twenty-forty-eight` 的纯函数内，并用黄金用例、属性测试和前后端 fixture 保证一致。
+
+## 7.4 胜负
+
+状态取值：
+
+```ts
+type TwentyFortyEightRunStatus =
+  | 'playing'
+  | 'target_reached'
+  | 'continued_after_target'
+  | 'game_over'
+  | 'abandoned';
+```
+
+规则：
+
+1. 首次出现 `targetTileValue` 时进入 `target_reached`。
+2. 玩家可选择结算，或继续挑战。
+3. 继续挑战后状态变为 `continued_after_target`。
+4. 棋盘无空格且四个方向都无法移动时进入 `game_over`。
+5. 玩家主动退出未结算时为 `abandoned`。
+
+---
+
+## 8. 草稿与结果页
+
+## 8.1 结果页定位
+
+2048 结果页是发布前的最小工作台，承担：
+
+1. 编辑作品基本信息。
+2. 编辑棋盘参数。
+3. 编辑合成链显示名和视觉提示。
+4. 生成或上传封面。
+5. 进入试玩。
+6. 发布作品。
+
+## 8.2 必备字段
+
+```ts
+interface TwentyFortyEightResultDraft {
+  workTitle: string;
+  workDescription: string;
+  workTags: string[];
+  coverImageSrc: string | null;
+  coverAssetId: string | null;
+  themePrompt: string;
+  visualStyle: string;
+  boardConfig: TwentyFortyEightBoardConfig;
+  tileLadder: TwentyFortyEightTileDefinition[];
+  scoringConfig: TwentyFortyEightScoringConfig;
+}
+
+interface TwentyFortyEightBoardConfig {
+  boardSize: 3 | 4 | 5;
+  targetTileValue: 512 | 1024 | 2048 | 4096 | 8192;
+  initialTileCount: 2 | 3 | 4;
+  spawnValueWeights: Array<{ value: 2 | 4; weight: number }>;
+  allowUndo: boolean;
+  maxUndoCount: number;
+}
+
+interface TwentyFortyEightTileDefinition {
+  value: number;
+  label: string;
+  shortLabel: string;
+  colorToken: string;
+  iconPrompt: string;
+  imageSrc: string | null;
+  assetId: string | null;
+}
+
+interface TwentyFortyEightScoringConfig {
+  scoreMode: 'classic';
+  leaderboardMetric: 'score_then_steps' | 'score_then_time';
+}
+```
+
+## 8.3 字段约束
+
+1. `workTitle` 必填，建议 `4~16` 个中文字符。
+2. `workDescription` 必填，建议 `12~80` 个中文字符。
+3. `workTags` 必须为 `3~6` 个中文短标签。
+4. `boardSize` 首版只能是 `3`、`4`、`5`。
+5. `targetTileValue` 必须存在于 `tileLadder`。
+6. `tileLadder` 必须从 `2` 开始按倍增连续覆盖到目标格。
+7. `shortLabel` 移动端格子内最多建议 `4` 个中文字符。
+8. `spawnValueWeights` 权重和必须大于 `0`，归一化后用于后端生成。
+9. `allowUndo = true` 时 `maxUndoCount` 必须在 `1~3`。
+
+## 8.4 结果页 UI
+
+结果页采用移动端优先的页签结构：
+
+1. `基本信息`：标题、简介、标签。
+2. `棋盘`：棋盘尺寸、目标格、撤销次数、生成概率。
+3. `合成链`：每级方块的显示名、短标签、颜色和图标预览。
+4. `封面`：封面预览、生成、上传或历史素材选择。
+
+交互要求：
+
+1. 发布按钮放在结果页右下操作区，移动端固定在底部安全区。
+2. 试玩按钮与发布按钮并列，但试玩不触发发布阻断。
+3. 发布校验只在点击发布后进入独立发布面板展示。
+4. 合成链编辑使用独立面板或抽屉，不在当前列表下方展开大表单。
+5. 页面不默认展示玩法规则说明。
+
+---
+
+## 9. 作品发布与广场
+
+## 9.1 发布阻断
+
+发布前必须校验：
+
+1. 作品标题非空。
+2. 简介非空。
+3. 标签数量为 `3~6`。
+4. 棋盘配置合法。
+5. 合成链完整覆盖到目标格。
+6. 目标格存在。
+7. 封面存在。
+8. 作者信息可读。
+
+## 9.2 作品摘要
+
+```ts
+interface TwentyFortyEightWorkSummary {
+  workId: string;
+  profileId: string;
+  ownerUserId: string;
+  authorDisplayName: string;
+  gameName: string;
+  summary: string;
+  tags: string[];
+  coverImageSrc: string;
+  boardSize: 3 | 4 | 5;
+  targetTileValue: number;
+  bestScore: number | null;
+  playCount: number;
+  likeCount: number;
+  sourceSessionId: string;
+  publicationStatus: 'draft' | 'published';
+  updatedAt: string;
+  publishedAt: string | null;
+}
+```
+
+## 9.3 广场卡片
+
+广场卡片至少展示：
+
+1. 封面。
+2. 作品名。
+3. 作者名。
+4. 标签。
+5. 棋盘规格和目标格。
+6. 进入游戏按钮。
+
+不在卡片内展示完整规则说明。
+
+---
+
+## 10. 运行态设计
+
+## 10.1 首屏
+
+运行态首屏必须直接展示棋盘：
+
+1. 顶部 HUD：分数、最高格、目标格、步数。
+2. 中部正方形棋盘。
+3. 底部轻量操作区：撤销、重新开始、退出。
+4. 移动端棋盘尽量贴近屏幕两侧安全边界。
+5. 桌面端棋盘居中，不使用营销式大卡片布局。
+
+## 10.2 运行快照
+
+```ts
+interface TwentyFortyEightRunSnapshot {
+  runId: string;
+  profileId: string;
+  ownerUserId: string;
+  status: TwentyFortyEightRunStatus;
+  seed: string;
+  board: TwentyFortyEightBoardSnapshot;
+  score: number;
+  bestTileValue: number;
+  moveCount: number;
+  undoRemaining: number;
+  targetTileValue: number;
+  reachedTargetAtMove: number | null;
+  startedAtMs: number;
+  updatedAtMs: number;
+  endedAtMs: number | null;
+  lastMove: TwentyFortyEightMoveResult | null;
+  work: TwentyFortyEightWorkSummary;
+}
+
+interface TwentyFortyEightBoardSnapshot {
+  size: 3 | 4 | 5;
+  cells: TwentyFortyEightCellSnapshot[];
+}
+
+interface TwentyFortyEightCellSnapshot {
+  row: number;
+  col: number;
+  tile: TwentyFortyEightTileSnapshot | null;
+}
+
+interface TwentyFortyEightTileSnapshot {
+  tileId: string;
+  value: number;
+  mergedFromTileIds: string[];
+  spawnedAtMove: number;
+}
+
+interface TwentyFortyEightMoveResult {
+  direction: TwentyFortyEightMoveDirection;
+  moveAccepted: boolean;
+  scoreDelta: number;
+  spawnedTile: TwentyFortyEightTileSnapshot | null;
+  mergedTileIds: string[];
+}
+```
+
+## 10.3 前后端职责
+
+前端负责：
+
+1. 渲染棋盘、HUD、结算面板。
+2. 采集滑动、键盘和按钮输入。
+3. 根据后端返回的 `lastMove` 播放移动、合并和生成动画。
+4. 做乐观动画可以，但必须以服务端快照回正。
+
+前端不负责：
+
+1. 保存正式分数。
+2. 写入榜单。
+3. 伪造目标达成。
+4. 绕过后端生成新方块。
+5. 自行发布作品状态。
+
+后端负责：
+
+1. 创建 run。
+2. 按 seed 初始化棋盘。
+3. 裁决每次移动。
+4. 生成新方块。
+5. 保存分数、步数、最高格和状态。
+6. 裁决目标达成、继续挑战、失败和放弃。
+7. 写入排行榜和埋点事件。
+
+---
+
+## 11. 后端分层边界
+
+正式实现必须遵循当前 `server-rs + Axum + SpacetimeDB` 路线：
+
+1. `server-rs/crates/module-twenty-forty-eight`
+   - 纯领域规则、棋盘移动、合并裁决、随机种子输入、分数计算、发布校验。
+   - 不依赖 Axum、SpacetimeDB、OSS 或 LLM。
+2. `server-rs/crates/shared-contracts`
+   - 暴露 Agent、作品、运行态、广场 DTO。
+3. `server-rs/crates/spacetime-module`
+   - 存储 session、message、work profile、runtime run、leaderboard、event。
+   - 表结构变化必须同步 `migration.rs` 与表目录。
+4. `server-rs/crates/spacetime-client`
+   - 提供 api-server 调用 SpacetimeDB 的 typed facade。
+5. `server-rs/crates/api-server`
+   - 暴露 `/api/creation/twenty-forty-eight/*` 与 `/api/runtime/twenty-forty-eight/*`。
+   - 处理鉴权、错误 envelope、LLM turn、生图编排、OSS 资产和 HTTP facade。
+6. `platform-llm` / `platform-oss`
+   - 分别承载外部模型和资产副作用。
+
+涉及 SpacetimeDB 的表、reducer、procedure、绑定生成、前端 SDK 接入时，必须按 `spacetimedb-cli`、`spacetimedb-rust`、`spacetimedb-concepts`、`spacetimedb-typescript` 约束执行。
+
+---
+
+## 12. SpacetimeDB 表建议
+
+首版建议新增：
+
+1. `twenty_forty_eight_agent_session`
+2. `twenty_forty_eight_agent_message`
+3. `twenty_forty_eight_work_profile`
+4. `twenty_forty_eight_runtime_run`
+5. `twenty_forty_eight_leaderboard_entry`
+6. `twenty_forty_eight_event`
+
+表职责：
+
+| 表 | 职责 |
+| --- | --- |
+| `twenty_forty_eight_agent_session` | 创作会话、阶段、草稿、已发布 profile 绑定。 |
+| `twenty_forty_eight_agent_message` | Agent 对话消息和流式 turn 结果。 |
+| `twenty_forty_eight_work_profile` | 作品草稿、发布状态、封面、棋盘配置、合成链和统计投影。 |
+| `twenty_forty_eight_runtime_run` | 单次运行快照、动作摘要、分数、状态和结算时间。 |
+| `twenty_forty_eight_leaderboard_entry` | 按作品、用户、棋盘规格和目标格记录最好成绩。 |
+| `twenty_forty_eight_event` | 发布、试玩、开始、移动、达成目标、失败、结算等审计事件。 |
+
+reducer / procedure 不允许调用 LLM、OSS、生图、HTTP 或非确定性外部服务。
+
+---
+
+## 13. API 设计
+
+## 13.1 创作接口
+
+统一前缀：
+
+```text
+/api/creation/twenty-forty-eight
+```
+
+建议接口：
+
+1. `POST /api/creation/twenty-forty-eight/sessions`
+2. `GET /api/creation/twenty-forty-eight/sessions/{sessionId}`
+3. `POST /api/creation/twenty-forty-eight/sessions/{sessionId}/messages`
+4. `POST /api/creation/twenty-forty-eight/sessions/{sessionId}/messages/stream`
+5. `POST /api/creation/twenty-forty-eight/sessions/{sessionId}/actions`
+6. `POST /api/creation/twenty-forty-eight/sessions/{sessionId}/compile`
+7. `GET /api/creation/twenty-forty-eight/works`
+8. `GET /api/creation/twenty-forty-eight/works/{profileId}`
+9. `PUT /api/creation/twenty-forty-eight/works/{profileId}`
+10. `POST /api/creation/twenty-forty-eight/works/{profileId}/publish`
+11. `DELETE /api/creation/twenty-forty-eight/works/{profileId}`
+
+## 13.2 运行接口
+
+统一前缀：
+
+```text
+/api/runtime/twenty-forty-eight
+```
+
+建议接口：
+
+1. `GET /api/runtime/twenty-forty-eight/gallery`
+2. `GET /api/runtime/twenty-forty-eight/gallery/{profileId}`
+3. `POST /api/runtime/twenty-forty-eight/works/{profileId}/runs`
+4. `GET /api/runtime/twenty-forty-eight/runs/{runId}`
+5. `POST /api/runtime/twenty-forty-eight/runs/{runId}/moves`
+6. `POST /api/runtime/twenty-forty-eight/runs/{runId}/undo`
+7. `POST /api/runtime/twenty-forty-eight/runs/{runId}/continue`
+8. `POST /api/runtime/twenty-forty-eight/runs/{runId}/restart`
+9. `POST /api/runtime/twenty-forty-eight/runs/{runId}/abandon`
+10. `POST /api/runtime/twenty-forty-eight/runs/{runId}/leaderboard`
+
+移动请求：
+
+```ts
+interface TwentyFortyEightMoveRequest {
+  clientActionId: string;
+  direction: TwentyFortyEightMoveDirection;
+  baseSnapshotVersion: number;
+}
+```
+
+响应：
+
+```ts
+interface TwentyFortyEightMoveResponse {
+  snapshot: TwentyFortyEightRunSnapshot;
+}
+```
+
+---
+
+## 14. 前端落点
+
+建议新增：
+
+```text
+src/components/twenty-forty-eight-creation/TwentyFortyEightAgentWorkspace.tsx
+src/components/twenty-forty-eight-result/TwentyFortyEightResultView.tsx
+src/components/twenty-forty-eight-runtime/TwentyFortyEightRuntimeShell.tsx
+src/components/twenty-forty-eight-runtime/TwentyFortyEightBoard.tsx
+src/components/twenty-forty-eight-runtime/TwentyFortyEightHud.tsx
+src/services/twenty-forty-eight-creation/twentyFortyEightCreationClient.ts
+src/services/twenty-forty-eight-works/twentyFortyEightWorksClient.ts
+src/services/twenty-forty-eight-runtime/twentyFortyEightRuntimeClient.ts
+src/services/twenty-forty-eight-gallery/twentyFortyEightGalleryClient.ts
+```
+
+平台入口接入时需要扩展：
+
+1. `src/config/newWorkEntryConfig.ts`
+2. `src/components/platform-entry/platformEntryTypes.ts`
+3. `src/components/platform-entry/platformEntryCreationTypes.ts`
+4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+5. `src/components/custom-world-home/creationWorkShelf.ts`
+6. `src/services/publicWorkCode.ts`
+
+新增 selection stage：
+
+```ts
+| 'twenty-forty-eight-agent-workspace'
+| 'twenty-forty-eight-result'
+| 'twenty-forty-eight-runtime'
+| 'twenty-forty-eight-gallery-detail'
+```
+
+---
+
+## 15. UI 要求
+
+## 15.1 创作入口
+
+入口卡片只表达：
+
+1. `2048`
+2. `主题合成棋盘`
+3. 开放状态
+
+不在入口卡片里堆规则说明。
+
+## 15.2 Agent 工作台
+
+工作台结构：
+
+1. 对话流。
+2. 当前锚点摘要。
+3. 生成草稿动作。
+4. 进入结果页动作。
+
+不展示世界观、角色、地点等 RPG 重结构。
+
+## 15.3 运行态
+
+运行态设计原则：
+
+1. 棋盘是绝对主角。
+2. 移动端优先，单手可滑动。
+3. HUD 信息克制，只显示分数、目标、步数和最高格。
+4. 撤销、重新开始、退出使用 icon button 或短按钮。
+5. 目标达成、失败和排行榜使用独立弹窗或底部面板。
+6. 不把弹出面板实现成当前面板下方追加内容。
+
+---
+
+## 16. 测试与验收
+
+## 16.1 领域测试
+
+必须覆盖：
+
+1. 向左移动压缩。
+2. 向右移动压缩。
+3. 单次移动中每个方块最多合并一次。
+4. 合并得分计算。
+5. 无效移动不生成新方块。
+6. 有效移动按 seed 生成新方块。
+7. 目标格达成。
+8. 无可行动作进入失败。
+9. 撤销次数消耗和快照恢复。
+
+## 16.2 API 测试
+
+必须覆盖：
+
+1. 未登录不能创建作品和 run。
+2. 创建 session。
+3. 编译草稿。
+4. 发布校验阻断。
+5. 创建 run。
+6. 提交 move 后返回新快照。
+7. 无效 move 不增加步数。
+8. 达成目标后可继续挑战。
+9. 失败后不能继续提交 move。
+10. 排行榜只接受后端已结算 run。
+
+## 16.3 前端测试
+
+必须覆盖：
+
+1. 入口展示与点击分流。
+2. Agent 工作台打开。
+3. 结果页编辑棋盘参数和合成链。
+4. 试玩进入运行态。
+5. 移动端滑动提交方向。
+6. 键盘方向键提交方向。
+7. 无效移动反馈。
+8. 目标达成弹窗。
+9. 失败结算弹窗。
+
+## 16.4 建议验证命令
+
+按改动范围执行：
+
+```bash
+npm run check:encoding
+npm run typecheck
+npm run test
+cd server-rs
+cargo test -p shared-contracts twenty_forty_eight
+cargo test -p module-twenty-forty-eight
+cargo check -p api-server
+```
+
+涉及 SpacetimeDB 表变化后：
+
+```bash
+npm run spacetime:generate -- --rust-only
+npm run check:server-rs-ddd
+```
+
+涉及 API smoke 时：
+
+```bash
+npm run api-server
+```
+
+启动后确认：
+
+```text
+GET /healthz
+POST /api/creation/twenty-forty-eight/sessions
+POST /api/runtime/twenty-forty-eight/works/{profileId}/runs
+POST /api/runtime/twenty-forty-eight/runs/{runId}/moves
+```
+
+---
+
+## 17. 并行任务拆分
+
+## 任务 A：契约与共享类型
+
+写入范围：
+
+```text
+packages/shared/src/contracts/twentyFortyEightAgent.ts
+packages/shared/src/contracts/twentyFortyEightWorks.ts
+packages/shared/src/contracts/twentyFortyEightRuntime.ts
+packages/shared/src/contracts/twentyFortyEightGallery.ts
+server-rs/crates/shared-contracts/src/twenty_forty_eight_agent.rs
+server-rs/crates/shared-contracts/src/twenty_forty_eight_works.rs
+server-rs/crates/shared-contracts/src/twenty_forty_eight_runtime.rs
+server-rs/crates/shared-contracts/src/twenty_forty_eight_gallery.rs
+```
+
+验收：
+
+```bash
+npm run typecheck
+cd server-rs
+cargo test -p shared-contracts twenty_forty_eight
+```
+
+## 任务 B：领域规则模块
+
+写入范围：
+
+```text
+server-rs/crates/module-twenty-forty-eight/src/domain.rs
+server-rs/crates/module-twenty-forty-eight/src/application.rs
+server-rs/crates/module-twenty-forty-eight/src/rule_engine.rs
+server-rs/crates/module-twenty-forty-eight/src/random.rs
+server-rs/crates/module-twenty-forty-eight/src/lib.rs
+```
+
+验收：
+
+```bash
+cd server-rs
+cargo test -p module-twenty-forty-eight
+```
+
+## 任务 C：SpacetimeDB 表与 facade
+
+写入范围：
+
+```text
+server-rs/crates/spacetime-module/src/twenty_forty_eight.rs
+server-rs/crates/spacetime-module/src/lib.rs
+server-rs/crates/spacetime-module/src/migration.rs
+server-rs/crates/spacetime-client/src/twenty_forty_eight.rs
+docs/technical/SPACETIMEDB_TABLE_CATALOG.md
+```
+
+验收：
+
+```bash
+npm run spacetime:generate -- --rust-only
+npm run check:server-rs-ddd
+cd server-rs
+cargo check -p spacetime-module
+cargo check -p spacetime-client
+```
+
+## 任务 D：API / SSE facade
+
+写入范围：
+
+```text
+server-rs/crates/api-server/src/twenty_forty_eight.rs
+server-rs/crates/api-server/src/twenty_forty_eight_sse.rs
+server-rs/crates/api-server/src/app.rs
+server-rs/crates/api-server/src/state.rs
+```
+
+验收：
+
+```bash
+cd server-rs
+cargo check -p api-server
+npm run api-server
+```
+
+## 任务 E：前端创作、结果页与运行态
+
+写入范围：
+
+```text
+src/config/newWorkEntryConfig.ts
+src/components/platform-entry/*
+src/components/twenty-forty-eight-creation/*
+src/components/twenty-forty-eight-result/*
+src/components/twenty-forty-eight-runtime/*
+src/services/twenty-forty-eight-*
+```
+
+验收：
+
+```bash
+npm run typecheck
+npm run test -- twenty
+npm run check:encoding
+```
+
+## 任务 F：作品架、广场、分享与回归
+
+写入范围：
+
+```text
+src/components/custom-world-home/creationWorkShelf.ts
+src/services/publicWorkCode.ts
+src/components/common/PublishShareModal.tsx
+src/components/twenty-forty-eight-gallery/*
+docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md
+docs/technical/SPACETIMEDB_TABLE_CATALOG.md
+```
+
+验收：
+
+```bash
+npm run typecheck
+npm run test
+npm run check:encoding
+```
+
+---
+
+## 18. 最小上线清单
+
+1. `twenty-forty-eight` 入口可展示并进入工作台。
+2. Agent 可生成主题化 2048 草稿。
+3. 结果页可编辑基本信息、棋盘配置和合成链。
+4. 结果页可试玩。
+5. 运行态可完成标准 2048 移动、合并、生成新方块、目标达成和失败。
+6. 发布后作品进入作品架和广场。
+7. 玩家可从广场进入公开 run。
+8. 榜单只记录后端裁决的正式成绩。
+9. 前后端契约字段 camelCase / snake_case 映射明确。
+10. SpacetimeDB 表、migration、表目录和 bindings 同步。
+
+---
+
+## 19. 验收标准
+
+当下面结果都成立时，视为 `2048` 玩法模板落地完成：
+
+1. 平台有独立 `2048` 创作入口。
+2. 玩法 ID 使用 `twenty-forty-eight`。
+3. 能进入 2048 Agent 工作台。
+4. 能通过 Agent 生成草稿。
+5. 结果页可编辑作品名、简介、标签、棋盘参数、合成链和封面。
+6. 发布校验能阻断非法草稿。
+7. 试玩能进入 2048 运行态。
+8. 运行态支持移动端滑动和桌面方向键。
+9. 后端能裁决移动、合并、得分、新方块生成和胜负。
+10. 无效移动不增加步数，不生成新方块。
+11. 达成目标后可结算或继续挑战。
+12. 失败后不能继续提交移动。
+13. 发布作品能进入作品架、广场和分享链路。
+14. 排行榜只接受正式 run 的后端结算成绩。
+15. 新增表结构同步 `migration.rs`、表目录和 bindings。
+16. UI 不默认展示长篇规则说明，不把独立弹窗做成面板下方展开。
+17. 移动端和桌面端都能正常显示和操作。
+
+---
+
+## 20. 一句话结论
+
+`2048` 在 Genarrative 中应被做成一个可创作、可换皮、可发布、可排行的主题合成棋盘模板：创作端让百梦主定义合成链和视觉承诺，运行端保持经典 2048 的滑动合并手感，服务端负责正式棋盘裁决、作品状态和成绩真相。