1

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 的滑动合并手感，服务端负责正式棋盘裁决、作品状态和成绩真相。

docs/prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md

@@ -0,0 +1,826 @@
+# AI 原生幸存者类游戏模板 PRD
+
+更新时间：`2026-05-05`
+
+## 0. 文档目的
+
+这份 PRD 用于在当前平台内新增一条“幸存者类游戏模板”产品链路，冻结它从创作入口、Agent 共创、结果页、试玩、发布到运行态结算的完整边界。
+
+本模板参考的是幸存者 / 割草 / 轻度 Roguelite 类玩法的通用结构：玩家在俯视角战场中移动、生存、自动攻击、拾取经验、选择升级，并在持续敌潮中坚持到胜利时间或击败终局首领。
+
+本次不是复制某个具体商业游戏，也不是新增一个孤立前端小游戏。正式实现必须接入 Genarrative 现有平台创作中心、作品架、广场、资产、钱包、埋点和 `server-rs + Axum + SpacetimeDB` 后端基线。
+
+---
+
+## 1. 一句话定义
+
+`survivor` 是一个 AI 原生幸存者类游戏模板：百梦主通过 Agent 设定主角幻想、敌潮母题、武器技能、成长流派和战场节奏，系统编译出一个移动端优先的俯视角割草生存作品；玩家通过移动躲避敌潮，武器自动攻击，拾取经验升级，在若干分钟内完成生存挑战、击败首领或倒下结算。
+
+---
+
+## 2. 当前接入级别
+
+根据新增玩法类型接入分级，本模板目标为 **完整玩法闭环**：
+
+1. 新增玩法 ID：`survivor`。
+2. 对外模板名称：`幸存者挑战`。
+3. 对外子标题：`割草成长玩法`。
+4. 支持 Agent 创作、草稿生成、结果页编辑、试玩、发布和公开运行。
+5. 支持作品架恢复草稿和已发布作品二次编辑。
+6. 支持玩家从作品详情或广场进入运行态。
+7. 支持后端权威生成局面、升级候选、波次配置、结算和成绩基础数据。
+8. 前端负责高频模拟与表现，但不得自行发明正式规则、波次、掉落、升级池或结算真相。
+
+---
+
+## 3. 产品定位
+
+## 3.1 命名
+
+1. 对外模板名称：`幸存者挑战`。
+2. 对外子标题：`割草成长玩法`。
+3. 开发代号：`Survivor`。
+4. 工程玩法域：`survivor`。
+5. 后端模块命名预期：`survivor`。
+
+## 3.2 核心乐趣
+
+1. 玩家被敌潮包围，通过走位制造空间。
+2. 武器自动攻击，玩家专注移动、拾取、选择升级。
+3. 每次升级出现少量高价值选择，形成局内构筑。
+4. 敌人数量、速度、血量和特殊能力逐步加压。
+5. 后期屏幕内形成高密度清场反馈，玩家获得成长压倒敌潮的爽感。
+
+## 3.3 与现有玩法的区别
+
+1. 不等同于 RPG：不依赖世界章节、NPC 对话或剧情推进。
+2. 不等同于大鱼吃小鱼：不做吞噬收编和三合一实体升级。
+3. 不等同于抓大鹅：不做备选栏三消和堆叠点击。
+4. 不等同于拼图：不切图、不交换、不合并拼块。
+5. 不新增通用动作游戏引擎，本期只服务幸存者类模板。
+
+---
+
+## 4. 完整闭环目标
+
+本模板首版必须补齐：
+
+1. 平台创作入口展示“幸存者挑战”。
+2. Agent 对话收集玩法锚点。
+3. 后端编译幸存者玩法草稿。
+4. 结果页编辑作品名、封面、标签、主角、敌人、武器、成长和战场配置。
+5. 结果页支持生成或替换关键视觉资产。
+6. 结果页支持发布前试玩。
+7. 作品可保存、发布、删除和二次编辑。
+8. 玩家从作品详情或广场创建 run。
+9. 后端下发权威 run seed、波次、敌人、武器、升级候选和结算规则。
+10. 前端按权威配置执行高频运行表现，定期提交 checkpoint。
+11. 玩家升级时从后端确认的候选卡中选择一张。
+12. 玩家死亡、主动退出、倒计时胜利或终局首领胜利后进入结算。
+13. 结算成绩以后端确认的 run snapshot 为准。
+
+---
+
+## 5. 明确不做
+
+首版明确不做：
+
+1. 不做联机、PvP、组队或排行榜赛季。
+2. 不做横屏专属设计，移动端竖屏优先。
+3. 不做复杂地形寻路、真实物理碰撞和高精度弹幕编辑器。
+4. 不做多地图章节战役，只做单局挑战。
+5. 不做局外装备养成、抽卡、永久技能树或付费强化。
+6. 不要求百梦主逐帧编辑怪物 AI、弹道曲线或数值公式。
+7. 不把玩法规则说明长文默认写进 UI 面板。
+8. 不把按钮弹出的资产、升级或参数编辑做成当前卡片下方展开内容，统一使用独立面板。
+9. 不让前端本地结算直接写入正式成绩、钱包、任务或排行榜。
+10. 不复用 `server-node`、Express、PostgreSQL 或旧 RPG runtime 作为新增实现目标。
+
+---
+
+## 6. 创作锚点设计
+
+Agent 型创作版本至少收集下面 5 个高杠杆锚点：
+
+| 锚点 | 字段建议 | 用途 |
+| --- | --- | --- |
+| 生存幻想 | `survivalFantasy` | 决定主角身份、战斗气质和作品一句话承诺。 |
+| 敌潮母题 | `hordeTheme` | 决定敌人类型、数量感、压迫方式和视觉风格。 |
+| 武器技能 | `weaponFantasy` | 决定自动攻击、范围技能、投射物和特效方向。 |
+| 成长流派 | `buildArchetype` | 决定升级卡池、进化组合和玩家构筑路线。 |
+| 战场节奏 | `stageRhythm` | 决定单局时长、波次曲线、首领节点和胜利条件。 |
+
+Agent 必须围绕用户灵感收束这些锚点，不允许把创作入口做成一屏参数问卷。
+
+## 6.1 锚点状态
+
+每个锚点都支持：
+
+1. `待补充`
+2. `Agent 推断`
+3. `已确认`
+4. `已锁定`
+
+## 6.2 收束条件
+
+满足下面条件后，系统允许编译第一版草稿：
+
+1. `生存幻想` 已确认或已锁定。
+2. `敌潮母题` 已确认或已锁定。
+3. `武器技能` 至少有 `3` 个可用武器草稿。
+4. `成长流派` 至少有 `6` 张升级卡草稿。
+5. `战场节奏` 已确认，或使用系统默认 `8` 分钟短局配置。
+
+## 6.3 快捷补全
+
+当会话至少完成 `2` 轮后，工作区提供 `补充剩余关键字` 快捷动作：
+
+1. 前端发送消息接口，并携带 `quickFillRequested: true`。
+2. 用户消息固定为“请补充剩余关键字。”。
+3. 后端 Agent 根据当前锚点补齐缺失内容。
+4. 前端不得自行推断武器、波次、敌人或升级卡。
+
+## 6.4 Agent AI 生成契约
+
+单轮模型输出必须是严格 JSON：
+
+```json
+{
+  "replyText": "",
+  "progressPercent": 0,
+  "anchors": {
+    "survivalFantasy": { "status": "pending", "summary": "" },
+    "hordeTheme": { "status": "pending", "summary": "" },
+    "weaponFantasy": { "status": "pending", "summary": "" },
+    "buildArchetype": { "status": "pending", "summary": "" },
+    "stageRhythm": { "status": "pending", "summary": "" }
+  },
+  "nextDraftPatch": {}
+}
+```
+
+落地约束：
+
+1. `replyText` 是直接展示给百梦主的中文回复，不得出现 JSON、字段名或内部协议说明。
+2. `progressPercent` 只能由后端校验后采纳，范围 `0~100`。
+3. `nextDraftPatch` 只允许写入幸存者草稿字段，不允许修改平台账号、钱包或作品归属。
+4. 模型不可用或结果无法解析时，接口返回明确错误，不用固定模板伪装 AI 回复。
+
+---
+
+## 7. 草稿契约
+
+## 7.1 `SurvivorResultDraft`
+
+```ts
+export interface SurvivorResultDraft {
+  profileId: string | null;
+  workTitle: string;
+  workDescription: string;
+  workTags: string[];
+  coverImageSrc: string | null;
+  anchors: SurvivorAnchorPack;
+  hero: SurvivorHeroDraft;
+  enemies: SurvivorEnemyDraft[];
+  weapons: SurvivorWeaponDraft[];
+  upgrades: SurvivorUpgradeDraft[];
+  evolutions: SurvivorEvolutionDraft[];
+  stage: SurvivorStageDraft;
+  wavePlan: SurvivorWavePlanDraft;
+  runtimeConfig: SurvivorRuntimeConfigDraft;
+  publishReady: boolean;
+  validationIssues: SurvivorValidationIssue[];
+  updatedAt: string;
+}
+```
+
+## 7.2 主角草稿
+
+```ts
+export interface SurvivorHeroDraft {
+  heroId: string;
+  name: string;
+  fantasy: string;
+  moveSpeed: number;
+  maxHp: number;
+  defense: number;
+  pickupRadius: number;
+  spriteAssetId: string | null;
+  portraitAssetId: string | null;
+}
+```
+
+默认范围：
+
+1. `moveSpeed`：`80~180`，默认 `120`。
+2. `maxHp`：`50~300`，默认 `100`。
+3. `defense`：`0~50`，默认 `0`。
+4. `pickupRadius`：`30~160`，默认 `60`。
+
+## 7.3 敌人草稿
+
+```ts
+export interface SurvivorEnemyDraft {
+  enemyId: string;
+  name: string;
+  role: 'fodder' | 'runner' | 'tank' | 'ranged' | 'elite' | 'boss';
+  visualPrompt: string;
+  maxHp: number;
+  damage: number;
+  moveSpeed: number;
+  xpValue: number;
+  spawnWeight: number;
+  spriteAssetId: string | null;
+}
+```
+
+首版发布至少需要：
+
+1. `2` 个 `fodder` 或 `runner` 敌人。
+2. `1` 个 `elite` 敌人。
+3. `1` 个 `boss` 敌人。
+
+## 7.4 武器草稿
+
+```ts
+export interface SurvivorWeaponDraft {
+  weaponId: string;
+  name: string;
+  attackKind: 'projectile' | 'orbit' | 'area' | 'beam' | 'melee_aura';
+  targeting: 'nearest' | 'random_enemy' | 'forward' | 'around_hero';
+  baseDamage: number;
+  cooldownMs: number;
+  projectileCount: number;
+  range: number;
+  effectAssetId: string | null;
+  upgradeTags: string[];
+}
+```
+
+首版必须至少有 `3` 个武器。玩家开局默认持有第一个武器。
+
+## 7.5 升级卡草稿
+
+```ts
+export interface SurvivorUpgradeDraft {
+  upgradeId: string;
+  name: string;
+  rarity: 'common' | 'rare' | 'epic';
+  targetKind: 'hero' | 'weapon' | 'global';
+  targetId: string | null;
+  effectKind:
+    | 'damage_percent'
+    | 'cooldown_percent'
+    | 'projectile_count'
+    | 'move_speed_percent'
+    | 'max_hp_flat'
+    | 'pickup_radius_percent'
+    | 'regen_flat';
+  value: number;
+  maxStack: number;
+  iconAssetId: string | null;
+}
+```
+
+首版至少需要 `6` 张升级卡，并保证任意升级节点能从可用池中抽出 `3` 张候选。
+
+## 7.6 进化组合
+
+```ts
+export interface SurvivorEvolutionDraft {
+  evolutionId: string;
+  name: string;
+  baseWeaponId: string;
+  requiredUpgradeIds: string[];
+  resultWeapon: SurvivorWeaponDraft;
+}
+```
+
+进化组合首版可选，但字段必须预留。若启用进化，结果页必须展示组合条件，不在运行态长文解释。
+
+## 7.7 战场草稿
+
+```ts
+export interface SurvivorStageDraft {
+  stageId: string;
+  name: string;
+  theme: string;
+  backgroundAssetId: string | null;
+  groundTextureAssetId: string | null;
+  safeAreaShape: 'rectangle' | 'circle';
+  width: number;
+  height: number;
+  obstacleDensity: number;
+}
+```
+
+首版默认不生成实心障碍，`obstacleDensity` 固定为 `0`。后续要开放障碍，必须先补充寻路与碰撞方案。
+
+## 7.8 波次草稿
+
+```ts
+export interface SurvivorWavePlanDraft {
+  durationSeconds: number;
+  waves: SurvivorWaveDraft[];
+  bossWave: SurvivorBossWaveDraft;
+}
+
+export interface SurvivorWaveDraft {
+  startSecond: number;
+  endSecond: number;
+  enemyPool: string[];
+  spawnRatePerSecond: number;
+  maxAlive: number;
+  statMultiplier: number;
+}
+```
+
+默认短局：
+
+1. `durationSeconds`：`480`。
+2. 每 `60` 秒一个波次。
+3. `240` 秒出现精英压力波。
+4. `480` 秒出现终局首领或进入胜利结算。
+
+---
+
+## 8. 运行规则设计
+
+## 8.1 单局结构
+
+首版标准局为 `8` 分钟短局：
+
+1. 玩家开局拥有 `1` 个基础武器。
+2. 玩家通过虚拟摇杆或键盘移动。
+3. 武器按冷却自动攻击。
+4. 敌人从屏幕外安全环刷出并向玩家移动。
+5. 敌人碰撞玩家造成伤害。
+6. 敌人死亡掉落经验晶体。
+7. 玩家拾取经验后升级。
+8. 升级时暂停运行态，展示 `3` 张升级卡。
+9. 玩家选择一张升级卡后继续运行。
+10. 玩家生命归零失败。
+11. 生存到终局时间或击败终局首领胜利。
+
+## 8.2 移动与输入
+
+1. 移动端使用左下角虚拟摇杆。
+2. 桌面端支持 `WASD` / 方向键移动。
+3. 首版不要求手动瞄准和手动开火。
+4. 前端必须保证摇杆、血量、经验条、升级面板和结算面板在竖屏下不遮挡核心战场。
+
+## 8.3 自动攻击
+
+1. 每个武器独立维护冷却。
+2. 目标选择策略由后端配置下发。
+3. 前端可本地执行攻击表现与命中模拟，但必须使用后端下发的武器参数和 RNG seed。
+4. 武器伤害、冷却、投射数量和范围变化来自后端确认的升级结果。
+
+## 8.4 敌潮生成
+
+1. 敌人只能从玩家当前视野外的刷怪环生成。
+2. 刷怪位置不得直接贴脸。
+3. 每个波次有 `spawnRatePerSecond` 和 `maxAlive` 上限。
+4. 前端不得自行增加敌人类型、刷新率或精英节点。
+5. 后端 checkpoint 校验时应能根据 seed、波次和输入摘要重放关键统计。
+
+## 8.5 经验与升级
+
+1. 敌人死亡生成经验晶体。
+2. 玩家碰到晶体或晶体进入拾取半径时获得经验。
+3. 经验达到当前等级阈值时触发升级。
+4. 升级候选由后端按当前 build、权重、稀有度和 seed 生成。
+5. 前端只能展示后端返回的候选卡。
+6. 玩家选择后，后端更新 run build snapshot。
+
+## 8.6 失败与胜利
+
+失败条件：
+
+1. `heroHp <= 0`。
+2. 玩家主动退出并确认放弃。
+3. 后端判定 run 校验失败。
+
+胜利条件：
+
+1. 生存到 `durationSeconds` 并完成终局结算。
+2. 或在终局波次击败 `boss`。
+
+---
+
+## 9. 权威状态与高频模拟边界
+
+幸存者类玩法需要高频碰撞和大量实体，不能把每一帧都交给 HTTP 往返。首版采用“后端权威配置 + 前端确定性运行表现 + 后端 checkpoint / 结算确认”的边界。
+
+## 9.1 后端职责
+
+后端负责：
+
+1. 创建创作会话和玩法草稿。
+2. 校验和保存作品 profile。
+3. 编译 run seed、波次、敌人、武器、升级池和结算规则。
+4. 生成升级候选。
+5. 确认升级选择。
+6. 接收运行 checkpoint。
+7. 校验关键统计是否在合理范围内。
+8. 确认死亡、胜利、退出和最终成绩。
+9. 写入作品游玩次数、成绩、埋点和任务事件。
+
+## 9.2 前端职责
+
+前端负责：
+
+1. 展示 Agent 工作台和结果页。
+2. 渲染战场、主角、敌人、投射物、特效、经验晶体和 HUD。
+3. 基于后端 run config 执行确定性高频模拟。
+4. 采集玩家移动输入。
+5. 展示攻击、受击、拾取、升级、胜利和失败反馈。
+6. 定期提交 checkpoint。
+7. 在后端拒绝 checkpoint 或结算时，展示同步失败并结束本局。
+
+## 9.3 Checkpoint 规则
+
+前端每 `5` 秒或关键节点提交 checkpoint：
+
+```ts
+export interface SurvivorRunCheckpointRequest {
+  runId: string;
+  snapshotVersion: number;
+  elapsedMs: number;
+  inputDigest: string;
+  rngStep: number;
+  heroHp: number;
+  heroLevel: number;
+  killCount: number;
+  eliteKillCount: number;
+  bossKillCount: number;
+  xpCollected: number;
+  selectedUpgradeIds: string[];
+  checksum: string;
+}
+```
+
+关键节点包括：
+
+1. 升级触发前。
+2. 选择升级后。
+3. 精英死亡。
+4. Boss 出现。
+5. Boss 死亡。
+6. 玩家死亡。
+7. 胜利结算。
+
+---
+
+## 10. 结果页设计
+
+## 10.1 结果页职责
+
+幸存者结果页是最小可编辑工作台，不是只读总结页。
+
+结果页至少包含：
+
+1. 作品基础信息。
+2. 主角配置。
+3. 敌人图鉴。
+4. 武器与升级卡池。
+5. 战场与波次。
+6. 资产状态。
+7. 试玩入口。
+8. 发布校验。
+
+## 10.2 移动端优先布局
+
+1. 首屏显示作品标题、封面、发布状态和试玩按钮。
+2. 主角、敌人、武器、战场使用分组入口。
+3. 点击分组入口打开独立编辑面板。
+4. 不在卡片下方展开长规则说明。
+5. 发布校验只展示短状态和可处理项，不展示底层协议。
+
+## 10.3 资产要求
+
+正式发布前至少需要：
+
+1. 作品封面。
+2. 主角头像或主角小人资产。
+3. `3` 类普通敌人资产。
+4. `1` 类精英或首领资产。
+5. `3` 个武器或技能图标。
+6. `1` 张战场背景或地面纹理。
+
+程序化色块或几何占位只允许用于开发调试和未发布草稿，不允许作为正式发布作品的默认资产。
+
+## 10.4 结果页核心操作
+
+结果页支持：
+
+1. `生成主角资产`
+2. `生成敌人资产`
+3. `生成武器图标`
+4. `生成战场背景`
+5. `重新编译波次`
+6. `试玩`
+7. `保存草稿`
+8. `发布`
+9. `返回创作对话`
+
+---
+
+## 11. API 设计
+
+## 11.1 创作接口
+
+1. `POST /api/creation/survivor/sessions`
+2. `GET /api/creation/survivor/sessions/{sessionId}`
+3. `POST /api/creation/survivor/sessions/{sessionId}/messages`
+4. `POST /api/creation/survivor/sessions/{sessionId}/messages/stream`
+5. `POST /api/creation/survivor/sessions/{sessionId}/actions`
+6. `POST /api/creation/survivor/sessions/{sessionId}/compile`
+7. `GET /api/creation/survivor/works`
+8. `GET /api/creation/survivor/works/{profileId}`
+9. `PUT /api/creation/survivor/works/{profileId}`
+10. `POST /api/creation/survivor/works/{profileId}/publish`
+11. `DELETE /api/creation/survivor/works/{profileId}`
+
+## 11.2 运行接口
+
+1. `GET /api/runtime/survivor/gallery`
+2. `GET /api/runtime/survivor/gallery/{profileId}`
+3. `POST /api/runtime/survivor/works/{profileId}/runs`
+4. `GET /api/runtime/survivor/runs/{runId}`
+5. `POST /api/runtime/survivor/runs/{runId}/checkpoint`
+6. `POST /api/runtime/survivor/runs/{runId}/upgrade-options`
+7. `POST /api/runtime/survivor/runs/{runId}/choose-upgrade`
+8. `POST /api/runtime/survivor/runs/{runId}/settle`
+9. `POST /api/runtime/survivor/runs/{runId}/stop`
+10. `POST /api/runtime/survivor/runs/{runId}/restart`
+
+## 11.3 SSE 事件
+
+创作对话流式事件复用平台 Agent envelope。运行态首版不要求全程 SSE；如后续加入服务端实时推送，只允许推送权威 milestone，不传每帧实体状态。
+
+---
+
+## 12. 后端分层边界
+
+完整实现时必须遵循当前后端路线：
+
+1. `server-rs/crates/module-survivor`
+   - 纯领域规则、草稿校验、波次编译、升级池、评分和 checkpoint 校验。
+   - 不依赖 Axum、SpacetimeDB、OSS 或 LLM。
+2. `server-rs/crates/shared-contracts`
+   - 暴露 Survivor Agent、作品、运行态 DTO。
+3. `server-rs/crates/spacetime-module`
+   - 存储 session、message、work profile、runtime run 和 runtime event。
+   - 表结构变化必须同步 `migration.rs` 与表目录。
+4. `server-rs/crates/spacetime-client`
+   - 提供 api-server 调用 SpacetimeDB 的 typed facade。
+5. `server-rs/crates/api-server`
+   - 暴露 `/api/creation/survivor/*` 与 `/api/runtime/survivor/*`。
+   - 处理鉴权、错误 envelope、LLM turn、资产生成和 HTTP facade。
+6. `platform-agent` / `platform-llm`
+   - 承接 Agent 对话与草稿生成。
+7. `platform-oss`
+   - 承接封面、角色、敌人、武器图标和战场背景资产。
+
+---
+
+## 13. SpacetimeDB 表建议
+
+首版建议新增：
+
+1. `survivor_agent_session`
+   - 创作会话主表，保存 owner、stage、anchors、draft、progress、published_profile_id。
+2. `survivor_agent_message`
+   - 创作消息流水。
+3. `survivor_work_profile`
+   - 作品 profile，保存发布态草稿、封面、标签、作者和公开状态。
+4. `survivor_runtime_run`
+   - 运行态 run，保存 run config、seed、当前 snapshot、checkpoint 摘要和结算状态。
+5. `survivor_runtime_event`
+   - 运行审计事件，记录 start、checkpoint、upgrade、death、victory、settle 等关键事件。
+
+首版不新增正式排行榜表。若后续加入排行榜，再新增 `survivor_leaderboard_entry` 并补充反作弊和赛季边界。
+
+---
+
+## 14. 作品结构建议
+
+```ts
+export interface SurvivorWorkProfile {
+  profileId: string;
+  ownerUserId: string;
+  sourceSessionId: string | null;
+  workTitle: string;
+  workDescription: string;
+  workTags: string[];
+  coverImageSrc: string | null;
+  publicationStatus: 'draft' | 'published' | 'archived';
+  draft: SurvivorResultDraft;
+  playCount: number;
+  updatedAt: string;
+  publishedAt: string | null;
+}
+```
+
+## 14.1 发布校验
+
+发布必须满足：
+
+1. `workTitle` 非空。
+2. 至少 `1` 个标签。
+3. 有封面图。
+4. 主角配置完整。
+5. 至少 `4` 个敌人，其中包含普通、精英或首领。
+6. 至少 `3` 个武器。
+7. 至少 `6` 张升级卡。
+8. 波次覆盖完整 `durationSeconds`。
+9. 资产覆盖满足正式发布要求。
+10. `runtimeConfig` 在后端数值上限内。
+
+---
+
+## 15. 运行态快照建议
+
+```ts
+export interface SurvivorRunSnapshot {
+  runId: string;
+  profileId: string;
+  ownerUserId: string | null;
+  status: 'running' | 'level_up_pending' | 'victory' | 'defeat' | 'stopped' | 'settlement_failed';
+  snapshotVersion: number;
+  seed: string;
+  elapsedMs: number;
+  durationLimitMs: number;
+  hero: SurvivorRunHeroSnapshot;
+  build: SurvivorRunBuildSnapshot;
+  wave: SurvivorRunWaveSnapshot;
+  stats: SurvivorRunStatsSnapshot;
+  pendingUpgradeOptions: SurvivorUpgradeOption[];
+  settlement: SurvivorRunSettlement | null;
+  updatedAt: string;
+}
+```
+
+前端渲染可维护更细的局内实体列表，但正式持久化只保存 run snapshot、checkpoint 摘要和结算结果。
+
+---
+
+## 16. 计分与结算
+
+首版结算至少展示：
+
+1. 胜利 / 失败状态。
+2. 生存时间。
+3. 击杀数。
+4. 等级。
+5. 精英击杀数。
+6. 首领击杀数。
+7. 选择过的核心升级。
+8. 再来一局。
+9. 返回作品详情。
+
+基础分数公式：
+
+```text
+score = survivedSeconds * 10
+      + killCount * 5
+      + eliteKillCount * 120
+      + bossKillCount * 500
+      + heroLevel * 80
+```
+
+结算入库以后端确认结果为准。前端展示的即时结算在后端确认前必须标记为待确认状态。
+
+---
+
+## 17. 平台接入
+
+## 17.1 创作入口
+
+需要接入：
+
+1. `src/config/newWorkEntryConfig.ts`
+2. `src/components/platform-entry/platformEntryCreationTypes.ts`
+3. `src/components/platform-entry/platformEntryTypes.ts`
+4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+
+新增阶段建议：
+
+1. `survivor-agent-workspace`
+2. `survivor-generating`
+3. `survivor-result`
+4. `survivor-runtime`
+5. `survivor-gallery-detail`
+
+## 17.2 前端组件建议
+
+1. `src/components/survivor-creation/SurvivorAgentWorkspace.tsx`
+2. `src/components/survivor-result/SurvivorResultView.tsx`
+3. `src/components/survivor-runtime/SurvivorRuntimeShell.tsx`
+4. `src/services/survivorCreationClient.ts`
+5. `src/services/survivorRuntimeClient.ts`
+6. `src/services/survivorWorksClient.ts`
+
+## 17.3 作品架与广场
+
+发布后必须接入：
+
+1. 创作页作品架。
+2. 平台作品详情。
+3. 首页或发现页公开作品流。
+4. 公开作品试玩入口。
+5. 删除、二次编辑和重新发布。
+
+---
+
+## 18. UI 设计约束
+
+1. 移动端竖屏优先，桌面端居中或宽屏增强。
+2. HUD 只保留血量、经验、时间、等级、击杀数和暂停入口。
+3. 升级卡使用独立面板，最多显示 `3` 张候选。
+4. 暂停、结算、资产生成、参数编辑都使用独立面板。
+5. 不默认展示规则说明长文。
+6. 运行态主画面不能被功能介绍、键位说明或装饰卡片遮挡。
+7. 触控区、摇杆、升级卡和按钮必须满足移动端可点击尺寸。
+8. 图标按钮优先使用现有图标库；无图标时再使用简短文本。
+
+---
+
+## 19. 里程碑拆分
+
+## 19.1 Phase 1：入口与 PRD 骨架
+
+1. 冻结 `survivor` 玩法 ID。
+2. 新增入口配置。
+3. 新增前端阶段枚举。
+4. 新增 shared contracts 草案。
+5. 入口可以进入占位工作台。
+
+## 19.2 Phase 2：创作会话与结果页
+
+1. 新增 Agent session。
+2. 新增消息与流式回复。
+3. 编译第一版 `SurvivorResultDraft`。
+4. 结果页可编辑主角、敌人、武器、升级和波次。
+5. 支持保存草稿。
+
+## 19.3 Phase 3：后端运行态
+
+1. `module-survivor` 实现波次、升级池、结算和 checkpoint 校验。
+2. SpacetimeDB 表、migration 和 facade 收口。
+3. api-server 暴露 runtime API。
+4. 支持创建 run、选择升级、提交 checkpoint 和结算。
+
+## 19.4 Phase 4：前端运行态
+
+1. 实现竖屏战场。
+2. 实现摇杆移动。
+3. 实现自动攻击、敌潮、经验和升级面板。
+4. 实现胜利、失败、暂停和结算。
+5. 接入后端 checkpoint 与升级确认。
+
+## 19.5 Phase 5：发布与平台闭环
+
+1. 发布作品。
+2. 接入作品架。
+3. 接入公开详情和广场。
+4. 支持二次编辑。
+5. 接入埋点、任务和基础成绩记录。
+
+---
+
+## 20. 验收标准
+
+1. `src/config/newWorkEntryConfig.ts` 中存在 `survivor` 类型。
+2. 新建作品入口和创作类型弹层能展示“幸存者挑战”。
+3. 能进入 `survivor-agent-workspace`。
+4. Agent 能生成锚点和草稿。
+5. 能进入 `survivor-result` 并编辑基础字段。
+6. 发布校验能阻止缺少主角、敌人、武器、升级卡、波次或资产的作品发布。
+7. 能从结果页进入试玩运行态。
+8. 运行态能移动、自动攻击、刷怪、拾取经验、升级和结算。
+9. 升级候选必须来自后端返回，不由前端临时生成。
+10. 前端提交 checkpoint 后，后端能接受或拒绝并返回明确结果。
+11. 作品发布后能在作品架和公开入口恢复。
+12. 移动端竖屏下主战场、摇杆、HUD、升级卡和结算不互相遮挡。
+13. 后端实现后执行对应 DDD 验收命令，并用 `npm run api-server` 启动后端检查 `/healthz`。
+14. 修改包含中文的文档后执行 `npm run check:encoding`。
+
+---
+
+## 21. 后续可选增强
+
+以下能力不进入首版，但需要保留扩展空间：
+
+1. 多地图主题。
+2. 局外角色解锁。
+3. 进化武器动画。
+4. 精英词缀。
+5. Boss 特殊弹幕。
+6. 道具掉落。
+7. 排行榜。
+8. 赛季挑战。
+9. 更多输入模式。
+10. 服务端更严格的确定性重放校验。
+

docs/prd/README.md

@@ -0,0 +1,20 @@
+# PRD 总览
+
+本目录用于存放产品需求、玩法闭环、阶段计划和可直接指导编码的需求拆分文档。
+
+## 重点入口
+
+- [AI 原生幕间文字游戏模板 PRD：参考 MOKU 的剧本模拟器闭环](./AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)：参考 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，但只落为百梦 `text-game` 模板，复用平台接口，不迁入外部社区、支付、私有存档或回放。
+- [AI 原生视觉小说模板 PRD：TXT 玩法平台化接入](./AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)：参考 `Interactive-fiction-backend` / `Interactive-fiction-frontend` 的 TXT 玩法经验，但只保留视觉小说模板创作与运行闭环，完全使用 Genarrative 平台接口，并明确删除回放和外部平台功能。
+- [AI 原生幸存者类游戏模板 PRD](./AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)：定义 `survivor` 幸存者挑战模板，从 Agent 创作、结果页、资产、试玩、发布到后端权威配置与前端高频运行表现的完整闭环。
+- [创意互动内容生成 Agent Phase 1 PRD：LangChain-Rust PoC + 拼图闭环](./CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)：首版只支持拼图模板，Agent 使用 APIMart Responses `gpt-5` 支持文本和图像多模态输入，明确模板选择、积分范围、草稿字段填充、单关卡/多关卡图片生成、立即试玩、自然语言修改和可并行任务拆分。
+- [AI 原生 2048 游戏玩法模板 PRD](./AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md)：新增 `twenty-forty-eight` 玩法模板，定义主题化合成链创作、结果页、发布、公开运行、后端棋盘裁决、排行榜和并行落地任务。
+- [AI 原生拼图玩法创作工具与玩法系统 PRD](./AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md)：拼图玩法创作、结果页、发布、广场和运行时主链路。
+- [AI 原生方洞挑战玩法创作工具与玩法系统 PRD](./AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)：方洞挑战创作、发布与试玩闭环。
+- [后台管理独立前端工程 PRD](./ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)：后台管理端产品边界。
+
+## 使用规则
+
+- 新玩法、新 Agent 阶段、新创作闭环或较大功能落地前，优先补 PRD。
+- PRD 必须写到可以编码的程度，包含字段、接口、状态、验收和并行任务拆分。
+- 若 PRD 与最新代码或技术方案冲突，以代码和最新技术方案为准，并同步修正 PRD。

docs/prd/TXT_MODE_CORE_GAMEPLAY_PRD_2026-04-20.md

@@ -2,6 +2,8 @@
 
 更新时间：`2026-04-20`
 
+> 2026-05-05 更新口径：本文保留为历史参考。视觉小说模板后续落地以 [`AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`](./AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md) 为准；冲突时不再按“外部 TXT 模式原样迁入”执行，必须只保留模板玩法能力、完全使用 Genarrative 平台接口，并删除回放功能。
+
 ## 0. 文档目的
 
 这份 PRD 只定义 `Interactive-fiction-frontend` + `Interactive-fiction-backend` 中 TXT 模式在 `Genarrative` 落地时的**核心玩法闭环**。