docs: freeze play creation tool SOP
This commit is contained in:
@@ -1,389 +1,253 @@
|
||||
---
|
||||
name: genarrative-play-type-integration
|
||||
description: 在 Genarrative 中新增一个创作入口/玩法类型时，按入口配置、前端分流、契约、后端接口、工作台、结果页、可选 runtime 与作品架的顺序接入。
|
||||
license: MIT
|
||||
metadata:
|
||||
author: Hermes Agent
|
||||
version: "1.0"
|
||||
description: 在 Genarrative 新增、开放或重构玩法创作工具时，按平台级强约束 SOP 接入入口配置、表单/图片输入创作工作台、单图资产槽位、系列素材图集生成、独立契约、后端 DDD、结果页、运行态、作品架、广场与验证；用于避免复制既有玩法、默认对话式 Agent、页面内手写图片输入或复用玩法专属素材模型。
|
||||
---
|
||||
|
||||
# Genarrative 新增玩法类型接入流程
|
||||
# Genarrative 新增玩法创作工具平台 SOP
|
||||
|
||||
用于在 Genarrative 中新增一个创作入口/玩法类型，而不是单纯说明用户如何从入口创建作品。
|
||||
把新增玩法当成平台能力接入，不把任何既有玩法当作默认模板。先确定通用模式和契约，再写具体玩法代码。
|
||||
|
||||
## 适用场景
|
||||
## 硬性禁区
|
||||
|
||||
- 新增一个游戏玩法入口
|
||||
- 让某个玩法从“敬请期待”变为可创建
|
||||
- 为新玩法补齐创作工作台、结果页、发布与试玩链路
|
||||
- 将新玩法接入创作中心作品架与广场
|
||||
- 不恢复前端硬编码入口配置；创作入口事实源必须来自 SpacetimeDB 和 `/api/creation-entry/config`。
|
||||
- 不把聊天输入区、流式消息或轻输入 Agent 作为新增玩法默认工作台。
|
||||
- 不在新页面内手写图片上传、参考图、AI 重绘、历史图选择、预览或删除确认逻辑。
|
||||
- 不把通用系列素材建模成任一玩法专属 DTO；玩法只能追加自己的运行态字段。
|
||||
- 不让前端承接正式业务真相；发布、试玩、通关、失败、计分、资产持久化和作品状态以后端投影为准。
|
||||
- 不新建平行入口系统、平行作品架或平行公开列表；优先扩展现有平台壳、现有阶段和现有聚合。
|
||||
- 不在 UI 面板内默认写功能说明、规则说明或开发解释文案。
|
||||
|
||||
## 先判断接入级别
|
||||
## 接入前输入
|
||||
|
||||
### 1. 只做入口占位
|
||||
开始编码前，PRD 或当前玩法文档必须已经明确：
|
||||
|
||||
只需要新增入口配置，不接 session/workspace/result/runtime。
|
||||
- `playId`、对外名称、工程域名、入口 `visible/open` 状态。
|
||||
- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态。
|
||||
- 表单字段：字段名、默认值、校验、后端落库位置、生成提示词来源。
|
||||
- 单图资产槽位：`slotId`、`slotType`、`slotName`、提示词来源、读取字段、写回字段、是否允许历史图和 AI 重绘。
|
||||
- 系列素材槽位：`batchId` 语义、`sheetSpec`、`slotSpecs`、切图规则、透明化规则、失败回写、局部重生成策略。
|
||||
- API 命名空间：`/api/creation/<play>/sessions`、`actions`、`works`、`runtime`。
|
||||
- 草稿恢复、生成中恢复、失败重试、登录切换、发布后回读和移动端行为。
|
||||
- 验证命令和例外声明；没有例外时写明“无创作工具模式例外”。
|
||||
|
||||
适合：
|
||||
## 默认模式
|
||||
|
||||
- 敬请期待
|
||||
- 灰度占位
|
||||
新增玩法默认采用表单/图片输入创作工作台：
|
||||
|
||||
### 2. 可进入创作工作台
|
||||
```text
|
||||
创作入口 -> 表单/图片输入工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
|
||||
```
|
||||
|
||||
需要补齐前端分流、session、工作台、结果页，至少能生成草稿。
|
||||
工作台只提交结构化表单、图片槽位和配置 payload。确需自然语言对话时，先走“例外流程”，不能把聊天区直接加进默认工作台。
|
||||
|
||||
### 3. 完整玩法闭环
|
||||
## SOP
|
||||
|
||||
需要补齐：
|
||||
### 1. 文档和领域词先行
|
||||
|
||||
- 创作入口
|
||||
- 工作台
|
||||
- 草稿生成
|
||||
- 结果页
|
||||
- 发布
|
||||
- 试玩 runtime
|
||||
- 作品架 / 广场 / 分享
|
||||
先读：
|
||||
|
||||
## 推荐接入顺序
|
||||
- `AGENTS.md`
|
||||
- `.hermes/shared-memory/`
|
||||
- `CONTEXT.md`
|
||||
- `docs/README.md`
|
||||
- `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`
|
||||
- 相关玩法 PRD 或设计文档
|
||||
|
||||
### Step 1: 先定玩法 ID 和能力边界
|
||||
如果文档不能精确指导字段、契约、资产槽位、生成流程和恢复语义，先补文档再编码。新增长期约定时同步 `.hermes/shared-memory/`。
|
||||
|
||||
先明确：
|
||||
### 2. 定玩法边界
|
||||
|
||||
- `id` 是什么
|
||||
- 入口是否可见
|
||||
- 是否可点击创建
|
||||
- 是否需要对话式创作
|
||||
- 是否需要生成中页面
|
||||
- 是否需要 result/runtime/gallery/share
|
||||
固定 `playId`、对外名称、工程域、入口状态、是否支持结果页、试玩、发布、作品架、广场、分享和 runtime。不要先用临时 ID 接线后再批量改名。
|
||||
|
||||
不要先随便起临时 ID 再改名。
|
||||
### 3. 接入口配置
|
||||
|
||||
### Step 2: 新增入口配置
|
||||
入口配置事实源是 SpacetimeDB `creation_entry_type_config`。后台通过 `/admin/api/creation-entry/config` 管理，前台通过 `/api/creation-entry/config` 读取。
|
||||
|
||||
文件：
|
||||
前端只允许在展示层派生：
|
||||
|
||||
- `src/config/newWorkEntryConfig.ts`
|
||||
- 可见入口卡片。
|
||||
- 锁定或开放状态。
|
||||
- 排序、图标、短标题等展示信息。
|
||||
|
||||
在 `creationTypes` 中新增：
|
||||
`api-server` 路由熔断必须使用同一份入口配置。禁止新增或恢复前端本地默认入口配置作为事实源。
|
||||
|
||||
- `id`
|
||||
- `title`
|
||||
- `subtitle`
|
||||
- `badge`
|
||||
- `visible`
|
||||
- `open`
|
||||
### 4. 前端阶段
|
||||
|
||||
如果只是占位：
|
||||
按需要扩展 `SelectionStage`：
|
||||
|
||||
- `visible: true`
|
||||
- `open: false`
|
||||
- `<play>-workspace`
|
||||
- `<play>-generating`
|
||||
- `<play>-result`
|
||||
- `<play>-runtime`
|
||||
- `<play>-gallery-detail`
|
||||
|
||||
### Step 3: 确认类型过滤逻辑
|
||||
阶段名可以按玩法命名，UI 形态必须仍是表单/图片创作工作台。进入工作台时只初始化结构化草稿状态，不启动默认聊天会话。
|
||||
|
||||
文件：
|
||||
### 5. 工作台实现
|
||||
|
||||
- `src/components/platform-entry/platformEntryCreationTypes.ts`
|
||||
工作台必须满足：
|
||||
|
||||
检查：
|
||||
- 使用表单控件、图片槽位、风格选项、难度选项、开关和提交按钮组织输入。
|
||||
- 单图槽位统一使用 `CreativeImageInputPanel`。
|
||||
- 组件缺少能力时先扩展 `CreativeImageInputPanel` 的受控 props，不在玩法页面复制上传、参考图、AI 重绘、历史图、预览或删除确认。
|
||||
- 主图读取、裁剪、历史素材弹层、计费确认、自动保存和后端请求由外层页面持有；通用面板只表达输入 UI 和短生命周期 UI 状态。
|
||||
- 提交 payload 必须是表单字段与图片槽位结构，不是用户消息文本。
|
||||
|
||||
- `getVisiblePlatformCreationTypes()` 是否能展示新类型
|
||||
- `isPlatformCreationTypeVisible()` 是否能识别新类型
|
||||
- `locked` / `hidden` 是否正确映射
|
||||
### 6. 单图资产槽位
|
||||
|
||||
### Step 4: 扩展页面阶段
|
||||
角色形象、UI 背景、容器、封面、分享图、图标等单张图都按单图资产槽位处理。
|
||||
|
||||
文件：
|
||||
统一约定：
|
||||
|
||||
- `src/components/platform-entry/platformEntryTypes.ts`
|
||||
- 槽位用 `slotId` 稳定标识，`slotType` 表达用途，`slotName` 用于 UI 标签。
|
||||
- 上传图、参考图、AI 重绘、历史图选择和删除确认都通过 `CreativeImageInputPanel` 入口表达。
|
||||
- 后端写回 `imageSrc`、`imageObjectKey`、`assetObjectId` 中可用字段；前端展示前通过平台资产读取能力换签。
|
||||
- 单个槽位重生成只禁用该槽位动作，不阻塞结果页其它槽位、系列素材槽位或导航。
|
||||
|
||||
为新玩法补充 `SelectionStage`：
|
||||
### 7. 系列素材图集生成
|
||||
|
||||
- `*-agent-workspace`
|
||||
- `*-generating`（可选）
|
||||
- `*-result`
|
||||
- `*-runtime`（可选）
|
||||
- `*-gallery-detail`（可选）
|
||||
地块、物品、障碍、装饰、UI 部件等一组同类素材都走通用系列素材图集生成流程：
|
||||
|
||||
### Step 5: 在总流程中加类型分流
|
||||
```text
|
||||
批量规划 -> sheet 生图 -> 后端切图 -> 去背景/透明化 -> PNG 输出 -> OSS 持久化 -> 状态回写 -> 局部重生成
|
||||
```
|
||||
|
||||
文件：
|
||||
玩法只提供：
|
||||
|
||||
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
- `sheetSpec`：画布比例、行列、单格尺寸、输出格式、背景处理策略。
|
||||
- `slotSpecs`：每个素材槽位的 `slotId`、`slotType`、`slotName`、提示词、sheet 单元格映射。
|
||||
- 玩法字段映射：把通用素材结果映射回玩法自己的 draft/profile/runtime 字段。
|
||||
|
||||
在 `handleCreationHubCreateType(type)` 中新增分支，确保：
|
||||
通用系列素材结果建议字段：
|
||||
|
||||
- 能进入对应工作台
|
||||
- 能设置对应 `selectionStage`
|
||||
- 能关闭类型弹层
|
||||
|
||||
同时按玩法补齐：
|
||||
|
||||
- `open<Play>AgentWorkspace()`
|
||||
- `leave<Play>Flow()`
|
||||
- `submit<Play>Message()`（对话式玩法）
|
||||
- `execute<Play>Action()`
|
||||
|
||||
### Step 6: 接入通用 Agent flow controller
|
||||
|
||||
文件：
|
||||
|
||||
- `src/components/platform-entry/usePlatformCreationAgentFlowController.ts`
|
||||
|
||||
如果是 Agent 型玩法，复用通用控制器：
|
||||
|
||||
- `createSession`
|
||||
- `getSession`
|
||||
- `streamMessage`
|
||||
- `executeAction`
|
||||
- `isBusy`
|
||||
- `batchId`
|
||||
- `slotId`
|
||||
- `slotType`
|
||||
- `slotName`
|
||||
- `prompt`
|
||||
- `imageSrc`
|
||||
- `imageObjectKey`
|
||||
- `assetObjectId`
|
||||
- `sourceSheetCell`
|
||||
- `status`
|
||||
- `error`
|
||||
- `streamingReplyText`
|
||||
- `selectionStage` 切换
|
||||
|
||||
### Step 7: 定义 shared contracts
|
||||
玩法可追加运行态字段，例如半径、宽度、视图索引或碰撞参数，但不能依赖任何玩法专属字段作为平台通用模型。新增玩法 compile action 内部调用通用系列素材服务；如果通用服务还缺能力，先补通用服务再接玩法。
|
||||
|
||||
前端：
|
||||
### 8. 契约与 API
|
||||
|
||||
前后端必须同步补契约：
|
||||
|
||||
- `packages/shared/src/contracts/`
|
||||
|
||||
后端：
|
||||
|
||||
- `server-rs/crates/shared-contracts/src/`
|
||||
|
||||
至少补齐：
|
||||
玩法 API 保留独立命名空间：
|
||||
|
||||
- session snapshot
|
||||
- create session request/response
|
||||
- message request/response
|
||||
- action request/response
|
||||
- draft/result 结构
|
||||
- work summary / gallery 结构（如果需要）
|
||||
- runtime 结构（如果需要）
|
||||
- `POST /api/creation/<play>/sessions`
|
||||
- `GET /api/creation/<play>/sessions/{sessionId}`
|
||||
- `POST /api/creation/<play>/sessions/{sessionId}/actions`
|
||||
- `/api/creation/<play>/works`
|
||||
- `/api/creation/<play>/runtime`
|
||||
|
||||
### Step 8: 实现前端 service client
|
||||
契约需要区分：
|
||||
|
||||
目录参考：
|
||||
- 工作台输入。
|
||||
- 草稿 snapshot。
|
||||
- 单图资产槽位。
|
||||
- 系列素材批次与槽位。
|
||||
- 结果页操作。
|
||||
- 发布作品摘要。
|
||||
- runtime snapshot。
|
||||
|
||||
- `src/services/`
|
||||
### 9. 后端分层
|
||||
|
||||
按玩法补：
|
||||
按 DDD 边界落地：
|
||||
|
||||
- creation client
|
||||
- runtime client（可选）
|
||||
- works client（可选）
|
||||
- gallery client（可选）
|
||||
- `module-<play>`：纯领域规则、状态机、draft/runtime 校验。
|
||||
- `shared-contracts`：前后端 DTO。
|
||||
- `spacetime-module`：表、reducer、procedure、事务编排、migration。
|
||||
- `spacetime-client`：typed facade 和 row mapper。
|
||||
- `api-server`：Axum 路由、鉴权、BFF、SSE、生成编排。
|
||||
- `platform-*`：LLM、图片生成、OSS、认证等外部副作用。
|
||||
|
||||
建议保持和现有玩法一致的 API base 与命名风格。
|
||||
涉及 SpacetimeDB schema 时同步 `migration.rs`、表目录和绑定，并运行 `npm run check:spacetime-schema`。
|
||||
|
||||
### Step 9: 接后端 API
|
||||
|
||||
文件参考：
|
||||
|
||||
- `server-rs/crates/api-server/src/puzzle.rs`
|
||||
- `server-rs/crates/api-server/src/puzzle_agent_turn.rs`
|
||||
- `server-rs/crates/api-server/src/match3d.rs`
|
||||
|
||||
通常需要：
|
||||
|
||||
- create session
|
||||
- get session
|
||||
- send message
|
||||
- stream message
|
||||
- execute action
|
||||
- publish / save / delete
|
||||
- runtime start / action（可选）
|
||||
- gallery / detail（可选）
|
||||
|
||||
后端设计优先按 Genarrative 的 DDD 分层拆开，不要把玩法规则、数据库事务、LLM 调用和 HTTP handler 混在一个文件里：
|
||||
|
||||
- `module-<play>`：纯领域规则、状态机、draft/runtime 校验，不依赖 Axum、SpacetimeDB 或外部平台。
|
||||
- `shared-contracts`：前后端 DTO、请求/响应、session snapshot、draft/result/runtime 结构。
|
||||
- `spacetime-module`：表定义、reducer/procedure、事务编排、migration；表结构变化要同步生成绑定。
|
||||
- `spacetime-client`：api-server 到 SpacetimeDB 的 facade，隐藏 reducer 调用细节。
|
||||
- `api-server`：Axum 路由、鉴权、SSE/stream、应用层编排。
|
||||
- `platform-*`：LLM、资产上传、鉴权、第三方服务等副作用。
|
||||
|
||||
建议按四条线设计后端能力：
|
||||
|
||||
- Agent 创作线：session、turn、stream、compile action。
|
||||
- Works 作品线：保存、发布、删除、草稿恢复。
|
||||
- Gallery 广场线：公开列表、详情、like/remix/share。
|
||||
- Runtime 运行态线：开始试玩、提交动作、读取状态。
|
||||
|
||||
### Step 10: 新增工作台组件
|
||||
|
||||
目录建议：
|
||||
|
||||
- `src/components/<play>-creation/<Play>AgentWorkspace.tsx`
|
||||
|
||||
两种形态：
|
||||
|
||||
#### 对话式
|
||||
|
||||
适合设定逐轮补齐。
|
||||
|
||||
参考：
|
||||
|
||||
- `BigFishAgentWorkspace.tsx`
|
||||
- `Match3DAgentWorkspace.tsx`
|
||||
|
||||
#### 表单式
|
||||
|
||||
适合输入结构明确的玩法。
|
||||
|
||||
参考：
|
||||
|
||||
- `PuzzleAgentWorkspace.tsx`
|
||||
|
||||
### Step 11: 在渲染树中挂载新页面
|
||||
|
||||
文件：
|
||||
|
||||
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
|
||||
补齐：
|
||||
|
||||
- workspace 分支
|
||||
- generating 分支（如需要）
|
||||
- result 分支
|
||||
- runtime 分支（如需要）
|
||||
|
||||
### Step 12: 新增结果页
|
||||
|
||||
目录建议：
|
||||
|
||||
- `src/components/<play>-result/<Play>ResultView.tsx`
|
||||
### 10. 结果页
|
||||
|
||||
结果页至少支持：
|
||||
|
||||
- 展示 draft
|
||||
- 返回编辑
|
||||
- 发布
|
||||
- 试玩
|
||||
- 错误展示
|
||||
- 展示草稿和生成状态。
|
||||
- 返回工作台编辑。
|
||||
- 单图槽位重生成。
|
||||
- 系列素材追加、替换、局部重生成。
|
||||
- 发布。
|
||||
- 试玩。
|
||||
- 错误展示和失败重试。
|
||||
|
||||
### Step 13: 需要试玩就补 runtime
|
||||
单图槽位和系列素材槽位的生成状态互不阻塞。已有可查看结果时，局部重生成不能把作品架草稿重新变成不可打开的全局生成中。
|
||||
|
||||
目录建议：
|
||||
### 11. 运行态、作品架和广场
|
||||
|
||||
- `src/components/<play>-runtime/<Play>RuntimeShell.tsx`
|
||||
需要试玩或发布时补齐：
|
||||
|
||||
如果玩法是游戏类，建议补完整 runtime 闭环。
|
||||
- runtime start/action/finish API。
|
||||
- 作品保存、发布、删除、回读。
|
||||
- 作品架摘要。
|
||||
- 公开列表、详情、分享码。
|
||||
- 公开列表优先消费后端投影或 BFF 缓存，不让前端直接拼源表事实。
|
||||
|
||||
### Step 14: 接入作品架 / 广场 / 分享
|
||||
运行态可以做低延迟表现，但正式胜负、分数、奖励、排行榜和发布状态以后端裁决为准。
|
||||
|
||||
需要改：
|
||||
### 12. 恢复与登录态
|
||||
|
||||
- `src/components/custom-world-home/creationWorkShelf.ts`
|
||||
- `src/components/custom-world-home/CustomWorldCreationHub.tsx`
|
||||
- `src/services/publicWorkCode.ts`
|
||||
必须处理：
|
||||
|
||||
如果玩法支持发布，还要补：
|
||||
- 刷新恢复生成中草稿。
|
||||
- 生成页计时从后端摘要时间恢复。
|
||||
- 失败后回读 session/work detail 再决定是否展示失败。
|
||||
- 退出登录清空私有玩法状态。
|
||||
- 私有生成图展示前换签。
|
||||
- result/runtime 缺必要 draft 时回到可恢复入口，不停在空白页。
|
||||
|
||||
- public work code
|
||||
- public detail
|
||||
- publish share modal
|
||||
- like/remix（可选）
|
||||
### 13. 例外流程
|
||||
|
||||
### Step 15: 处理登录态与草稿恢复
|
||||
任何非表单/图片工作台、对话式 Agent、独立创作系统或特殊资产模型都必须先更新 PRD 和平台文档。例外声明至少写清：
|
||||
|
||||
要考虑：
|
||||
- 为什么默认表单/图片工作台不能满足。
|
||||
- 例外影响哪些输入、契约、后端流程和测试。
|
||||
- 如何保留单图资产槽位和系列素材槽位的通用能力。
|
||||
- 如何回退到平台默认链路。
|
||||
|
||||
- 刷新恢复草稿
|
||||
- 退出登录清空私有状态
|
||||
- result/draft 缺失时回退
|
||||
- busy / generating / runtime 中断恢复
|
||||
没有文档例外，不进入编码。
|
||||
|
||||
### Step 16: 补测试
|
||||
## PRD 检查块
|
||||
|
||||
至少覆盖：
|
||||
在新增玩法 PRD 中保留这一段：
|
||||
|
||||
- 入口展示
|
||||
- 类型分流
|
||||
- 工作台打开
|
||||
- session 创建
|
||||
- compile action
|
||||
- result 页切换
|
||||
- 发布后刷新作品架
|
||||
- runtime 进入与退出
|
||||
```md
|
||||
## 创作工具平台接入声明
|
||||
|
||||
## 最小改动清单
|
||||
|
||||
### 只做占位
|
||||
|
||||
只改：
|
||||
|
||||
- `src/config/newWorkEntryConfig.ts`
|
||||
|
||||
### 做到可进入工作台
|
||||
|
||||
至少改：
|
||||
|
||||
- `newWorkEntryConfig.ts`
|
||||
- `platformEntryTypes.ts`
|
||||
- `PlatformEntryFlowShellImpl.tsx`
|
||||
- 新玩法 service client
|
||||
- 新玩法工作台组件
|
||||
- shared contracts
|
||||
- 后端 API
|
||||
|
||||
### 做到完整闭环
|
||||
|
||||
还要补：
|
||||
|
||||
- result 页
|
||||
- runtime
|
||||
- works / gallery
|
||||
- public code
|
||||
- share
|
||||
- 作品架聚合
|
||||
- 测试
|
||||
|
||||
## 常见坑
|
||||
|
||||
1. 只加入口配置不够，类型分流和页面阶段也要补。
|
||||
2. `SelectionStage` 不扩展，前端无法安全切页。
|
||||
3. 新玩法如果要出现在作品架，必须改聚合逻辑，不只是加入口。
|
||||
4. 发布后不刷新 works/gallery，用户会看不到新作品。
|
||||
5. 如果走 SpacetimeDB，表结构变化要同步 migration 和绑定；`spacetime-client/src/module_bindings/` 通常是生成物，不要为了修编译或格式化而手改，优先改 module 源 schema/reducer/procedure 后重新生成。
|
||||
6. 做 analytics/tracking 这类 runtime 能力时，不要只补 API DTO；先在 `module-runtime` 写纯函数测试（例如 day/week/month/quarter/year bucket 聚合、scope/event 过滤），RED 后再补领域类型与聚合函数。
|
||||
7. 时间粒度聚合建议复用已有 date dimension 逻辑，把 daily stat 映射到 day/week/month/quarter/year bucket；bucket 输出要有稳定排序，并显式携带 `bucketKey`、`bucketStartDateKey`、`bucketEndDateKey`、`value`。
|
||||
8. 后端 shared-contracts 与前端 `packages/shared/src/contracts/runtime.ts` 要同步补 request/response/type union；admin-web 若有独立 `api/adminApiTypes.ts`，也要同步，避免共享包已更新但管理端本地类型缺失。
|
||||
9. 退出登录时要清空新玩法私有状态，避免串用户。
|
||||
10. 移动端入口卡片增多后要检查布局和滚动体验。
|
||||
|
||||
## 验证标准
|
||||
|
||||
一个玩法算真正接入成功，至少要满足：
|
||||
|
||||
- 入口能展示
|
||||
- 能进入对应工作台
|
||||
- 能创建 session
|
||||
- 能生成草稿
|
||||
- 能进入结果页
|
||||
- 能返回编辑
|
||||
- 如果需要，可试玩
|
||||
- 如果需要，可发布
|
||||
- 发布后能回到作品架 / 广场 / 分享链路
|
||||
|
||||
## 建议验证命令
|
||||
|
||||
按改动范围选择：
|
||||
|
||||
```bash
|
||||
# 后端 contracts / module-runtime / api-server
|
||||
cd server-rs
|
||||
cargo test -p shared-contracts
|
||||
cargo test -p module-runtime
|
||||
cargo check -p api-server
|
||||
|
||||
# SpacetimeDB schema/reducer/procedure 改动后，优先在有 CLI 的机器重新生成 bindings
|
||||
npm run spacetime:generate -- --rust-only
|
||||
|
||||
# 前端类型
|
||||
npm run admin-web:typecheck
|
||||
- 工作台模式：表单/图片输入创作工作台
|
||||
- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
|
||||
- 单图资产槽位：
|
||||
- slotId / slotType / slotName / 提示词来源 / 写回字段 / 是否允许历史图 / 是否允许 AI 重绘
|
||||
- 系列素材槽位：
|
||||
- batchId / sheetSpec / slotSpecs / 切图规则 / 透明化规则 / 失败回写 / 局部重生成
|
||||
- API 命名空间：/api/creation/<play>/...
|
||||
- 业务真相：后端裁决字段和前端表现字段边界
|
||||
- 创作工具模式例外：无；如有，先写明例外原因和回退方式
|
||||
- 验证命令：
|
||||
```
|
||||
|
||||
如果新增完整前端玩法闭环，还要按项目实际脚本补充 web typecheck、lint 或 Playwright/单元测试。
|
||||
## 验证门禁
|
||||
|
||||
按改动范围运行：
|
||||
|
||||
- `npm run check:encoding`
|
||||
- `npm run typecheck`
|
||||
- 前端工作台测试：确认没有聊天式 Agent 输入，提交的是表单/图片 payload。
|
||||
- `CreativeImageInputPanel` 测试：覆盖多玩法标签、上传、AI 重绘、参考图上限、历史图入口和删除确认。
|
||||
- 系列素材测试：覆盖 sheet layout、切图、透明化、OSS 持久化、追加、替换、局部重生成和失败回写。
|
||||
- 结果页测试：覆盖单图槽位重生成和系列素材槽位重生成互不阻塞。
|
||||
- 后端定向测试：覆盖 compile action、资产持久化、失败回写、发布和 runtime start。
|
||||
- 涉及 SpacetimeDB schema 时运行 `npm run check:spacetime-schema`。
|
||||
|
||||
@@ -103,6 +103,14 @@
|
||||
- 验证方式：容器连续 10 轮不重启 SpacetimeDB 压测，`PEAK_RPS=2500` 等价约 5000 HTTP req/s，平均实际吞吐约 `4219 HTTP req/s`，总计 `0` 个 5xx，200 请求平均 `p95=123ms`、`p99=234ms`；同时观察 SpacetimeDB 内存高水位，后续优化先处理连接 / 订阅 / tracking 下游状态。
|
||||
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/container/README.md`。
|
||||
|
||||
## 2026-05-19 新增玩法创作工具平台 SOP 冻结
|
||||
|
||||
- 背景：新增玩法的创作工具如果默认复制既有玩法的聊天式 Agent、轻输入 Agent 或专属素材模型，平台会不断复制出不可控分支，后续接入、测试和恢复语义都会漂移。
|
||||
- 决策：新增玩法创作工具统一收敛为平台级 SOP：默认使用表单/图片输入创作工作台；单图资产统一通过 `CreativeImageInputPanel`；系列素材统一走批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成流水线；不把任一玩法专属素材模型当平台通用模型。
|
||||
- 影响范围：`CONTEXT.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`.hermes/skills/genarrative-play-type-integration/SKILL.md`、后续新增玩法 PRD 和工程实现。
|
||||
- 验证方式：新增玩法 PRD 必须显式声明单图资产槽位和系列素材槽位；新增工作台测试确认没有默认聊天式 Agent 输入；skill 通过 `quick_validate.py`。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`.hermes/skills/genarrative-play-type-integration/SKILL.md`。
|
||||
|
||||
## 2026-05-16 公开作品列表短期由 BFF 订阅读模型缓存
|
||||
|
||||
- 背景：作品列表压测和实时性讨论中，曾考虑让浏览器前端直接订阅公开作品列表，减少 HTTP 拉取和 BFF 压力。
|
||||
|
||||
@@ -22,6 +22,14 @@
|
||||
- 验证：拼图入口测试仍可通过，且新组件可通过不同页面复用而不需要复制上传卡实现。
|
||||
- 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`。
|
||||
|
||||
## 新增玩法不要直接复制旧玩法创作工具
|
||||
|
||||
- 现象：新玩法一开始就复制既有玩法的聊天式 Agent、轻输入 Agent、专属素材 DTO 或生成流程，后续在结果页、作品架和 runtime 上不断补兼容层。
|
||||
- 原因：既有玩法只是历史实现，不是平台默认模板；把它们当起点会把玩法专属字段误当平台通用字段，导致创作工具和契约越来越难控制。
|
||||
- 处理：新玩法先走平台级 SOP，默认用表单/图片输入创作工作台、单图资产槽位和通用系列素材图集生成；如果确需例外，先写 PRD 例外原因、影响范围和回退方式，再编码。
|
||||
- 验证：新增玩法 PRD 中能直接找到平台级创作工具声明，不需要从某个既有玩法反推接入方式。
|
||||
- 关联：`.codex/skills/genarrative-play-type-integration/SKILL.md`、`.hermes/skills/genarrative-play-type-integration/SKILL.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## OTLP 端点只填 Collector HTTP base endpoint
|
||||
|
||||
- 现象：生产或容器 env 里把 `OTEL_EXPORTER_OTLP_ENDPOINT` 填成 `4317`、Rider 端口或别的非 HTTP base endpoint 后，api-server 发不出 OTLP，或者链路被错误转发。
|
||||
|
||||
@@ -1,348 +1,253 @@
|
||||
---
|
||||
name: genarrative-play-type-integration
|
||||
description: 在 Genarrative 中新增一个创作入口/玩法类型时，按入口配置、前端分流、契约、后端接口、工作台、结果页、可选 runtime 与作品架的顺序接入。
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Genarrative, 玩法接入, 创作入口, 前端, 后端, contracts, runtime]
|
||||
related_skills: []
|
||||
description: 在 Genarrative 新增、开放或重构玩法创作工具时，按平台级强约束 SOP 接入入口配置、表单/图片输入创作工作台、单图资产槽位、系列素材图集生成、独立契约、后端 DDD、结果页、运行态、作品架、广场与验证；用于避免复制既有玩法、默认对话式 Agent、页面内手写图片输入或复用玩法专属素材模型。
|
||||
---
|
||||
|
||||
# Genarrative 新增玩法类型接入流程
|
||||
# Genarrative 新增玩法创作工具平台 SOP
|
||||
|
||||
用于在 Genarrative 中新增一个创作入口/玩法类型，而不是单纯说明用户如何从入口创建作品。
|
||||
把新增玩法当成平台能力接入，不把任何既有玩法当作默认模板。先确定通用模式和契约，再写具体玩法代码。
|
||||
|
||||
## 适用场景
|
||||
## 硬性禁区
|
||||
|
||||
- 新增一个游戏玩法入口
|
||||
- 让某个玩法从“敬请期待”变为可创建
|
||||
- 为新玩法补齐创作工作台、结果页、发布与试玩链路
|
||||
- 将新玩法接入创作中心作品架与广场
|
||||
- 不恢复前端硬编码入口配置；创作入口事实源必须来自 SpacetimeDB 和 `/api/creation-entry/config`。
|
||||
- 不把聊天输入区、流式消息或轻输入 Agent 作为新增玩法默认工作台。
|
||||
- 不在新页面内手写图片上传、参考图、AI 重绘、历史图选择、预览或删除确认逻辑。
|
||||
- 不把通用系列素材建模成任一玩法专属 DTO；玩法只能追加自己的运行态字段。
|
||||
- 不让前端承接正式业务真相；发布、试玩、通关、失败、计分、资产持久化和作品状态以后端投影为准。
|
||||
- 不新建平行入口系统、平行作品架或平行公开列表；优先扩展现有平台壳、现有阶段和现有聚合。
|
||||
- 不在 UI 面板内默认写功能说明、规则说明或开发解释文案。
|
||||
|
||||
## 先判断接入级别
|
||||
## 接入前输入
|
||||
|
||||
### 1. 只做入口占位
|
||||
开始编码前，PRD 或当前玩法文档必须已经明确：
|
||||
|
||||
只需要新增入口配置，不接 session/workspace/result/runtime。
|
||||
- `playId`、对外名称、工程域名、入口 `visible/open` 状态。
|
||||
- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态。
|
||||
- 表单字段：字段名、默认值、校验、后端落库位置、生成提示词来源。
|
||||
- 单图资产槽位：`slotId`、`slotType`、`slotName`、提示词来源、读取字段、写回字段、是否允许历史图和 AI 重绘。
|
||||
- 系列素材槽位：`batchId` 语义、`sheetSpec`、`slotSpecs`、切图规则、透明化规则、失败回写、局部重生成策略。
|
||||
- API 命名空间：`/api/creation/<play>/sessions`、`actions`、`works`、`runtime`。
|
||||
- 草稿恢复、生成中恢复、失败重试、登录切换、发布后回读和移动端行为。
|
||||
- 验证命令和例外声明；没有例外时写明“无创作工具模式例外”。
|
||||
|
||||
适合：
|
||||
- 敬请期待
|
||||
- 灰度占位
|
||||
## 默认模式
|
||||
|
||||
### 2. 可进入创作工作台
|
||||
新增玩法默认采用表单/图片输入创作工作台：
|
||||
|
||||
需要补齐前端分流、session、工作台、结果页，至少能生成草稿。
|
||||
```text
|
||||
创作入口 -> 表单/图片输入工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
|
||||
```
|
||||
|
||||
### 3. 完整玩法闭环
|
||||
工作台只提交结构化表单、图片槽位和配置 payload。确需自然语言对话时，先走“例外流程”，不能把聊天区直接加进默认工作台。
|
||||
|
||||
需要补齐：
|
||||
- 创作入口
|
||||
- 工作台
|
||||
- 草稿生成
|
||||
- 结果页
|
||||
- 发布
|
||||
- 试玩 runtime
|
||||
- 作品架 / 广场 / 分享
|
||||
## SOP
|
||||
|
||||
## 推荐接入顺序
|
||||
### 1. 文档和领域词先行
|
||||
|
||||
### Step 1: 先定玩法 ID 和能力边界
|
||||
先读：
|
||||
|
||||
先明确：
|
||||
- `id` 是什么
|
||||
- 入口是否可见
|
||||
- 是否可点击创建
|
||||
- 是否需要对话式创作
|
||||
- 是否需要生成中页面
|
||||
- 是否需要 result/runtime/gallery/share
|
||||
- `AGENTS.md`
|
||||
- `.hermes/shared-memory/`
|
||||
- `CONTEXT.md`
|
||||
- `docs/README.md`
|
||||
- `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`
|
||||
- 相关玩法 PRD 或设计文档
|
||||
|
||||
不要先随便起临时 ID 再改名。
|
||||
如果文档不能精确指导字段、契约、资产槽位、生成流程和恢复语义，先补文档再编码。新增长期约定时同步 `.hermes/shared-memory/`。
|
||||
|
||||
### Step 2: 新增入口配置
|
||||
### 2. 定玩法边界
|
||||
|
||||
文件：
|
||||
- `src/config/newWorkEntryConfig.ts`
|
||||
固定 `playId`、对外名称、工程域、入口状态、是否支持结果页、试玩、发布、作品架、广场、分享和 runtime。不要先用临时 ID 接线后再批量改名。
|
||||
|
||||
在 `NEW_WORK_ENTRY_CONFIG.creationTypes` 中新增或调整：
|
||||
- `id`
|
||||
- `title`
|
||||
- `subtitle`
|
||||
- `badge`
|
||||
- `visible`
|
||||
- `open`
|
||||
### 3. 接入口配置
|
||||
|
||||
字段语义：
|
||||
- `visible: true`：在创作页签 / 新建作品入口中展示。
|
||||
- `visible: false`：不在平台入口展示，但不删除既有玩法路由和能力。
|
||||
- `open: true`：可点击进入创作流程。
|
||||
- `open: false`：展示为锁定 / 敬请期待，不应进入创建流程。
|
||||
入口配置事实源是 SpacetimeDB `creation_entry_type_config`。后台通过 `/admin/api/creation-entry/config` 管理，前台通过 `/api/creation-entry/config` 读取。
|
||||
|
||||
如果只是占位：
|
||||
- `visible: true`
|
||||
- `open: false`
|
||||
前端只允许在展示层派生：
|
||||
|
||||
相关渲染与过滤位置：
|
||||
- `src/components/platform-entry/platformEntryCreationTypes.ts`：将 `NEW_WORK_ENTRY_CONFIG.creationTypes` 映射为平台入口卡片，`getVisiblePlatformCreationTypes()` 会过滤隐藏项，并把可创建模板排在敬请期待模板前面。
|
||||
- `src/components/custom-world-home/CustomWorldCreationStartCard.tsx`：创作页签首屏模板入口卡片的实际渲染位置。
|
||||
- `src/components/platform-entry/PlatformEntryCreationTypeModal.tsx`：选择创作类型弹层的渲染位置。
|
||||
- 可见入口卡片。
|
||||
- 锁定或开放状态。
|
||||
- 排序、图标、短标题等展示信息。
|
||||
|
||||
注意：当前项目工作区通常已经是 `<repo-root>`，路径不要再额外拼接 `./Genarrative/`。
|
||||
`api-server` 路由熔断必须使用同一份入口配置。禁止新增或恢复前端本地默认入口配置作为事实源。
|
||||
|
||||
### Step 3: 确认类型过滤逻辑
|
||||
### 4. 前端阶段
|
||||
|
||||
文件：
|
||||
- `./Genarrative/src/components/platform-entry/platformEntryCreationTypes.ts`
|
||||
按需要扩展 `SelectionStage`：
|
||||
|
||||
检查：
|
||||
- `getVisiblePlatformCreationTypes()` 是否能展示新类型
|
||||
- `isPlatformCreationTypeVisible()` 是否能识别新类型
|
||||
- `locked` / `hidden` 是否正确映射
|
||||
- `<play>-workspace`
|
||||
- `<play>-generating`
|
||||
- `<play>-result`
|
||||
- `<play>-runtime`
|
||||
- `<play>-gallery-detail`
|
||||
|
||||
### Step 4: 扩展页面阶段
|
||||
阶段名可以按玩法命名，UI 形态必须仍是表单/图片创作工作台。进入工作台时只初始化结构化草稿状态，不启动默认聊天会话。
|
||||
|
||||
文件：
|
||||
- `./Genarrative/src/components/platform-entry/platformEntryTypes.ts`
|
||||
### 5. 工作台实现
|
||||
|
||||
为新玩法补充 `SelectionStage`：
|
||||
- `*-agent-workspace`
|
||||
- `*-generating`（可选）
|
||||
- `*-result`
|
||||
- `*-runtime`（可选）
|
||||
- `*-gallery-detail`（可选）
|
||||
工作台必须满足：
|
||||
|
||||
### Step 5: 在总流程中加类型分流
|
||||
- 使用表单控件、图片槽位、风格选项、难度选项、开关和提交按钮组织输入。
|
||||
- 单图槽位统一使用 `CreativeImageInputPanel`。
|
||||
- 组件缺少能力时先扩展 `CreativeImageInputPanel` 的受控 props，不在玩法页面复制上传、参考图、AI 重绘、历史图、预览或删除确认。
|
||||
- 主图读取、裁剪、历史素材弹层、计费确认、自动保存和后端请求由外层页面持有；通用面板只表达输入 UI 和短生命周期 UI 状态。
|
||||
- 提交 payload 必须是表单字段与图片槽位结构，不是用户消息文本。
|
||||
|
||||
文件：
|
||||
- `./Genarrative/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
### 6. 单图资产槽位
|
||||
|
||||
在 `handleCreationHubCreateType(type)` 中新增分支，确保：
|
||||
- 能进入对应工作台
|
||||
- 能设置对应 `selectionStage`
|
||||
- 能关闭类型弹层
|
||||
角色形象、UI 背景、容器、封面、分享图、图标等单张图都按单图资产槽位处理。
|
||||
|
||||
同时补：
|
||||
- `open<Play>AgentWorkspace()`
|
||||
- `leave<Play>Flow()`
|
||||
- `submit<Play>Message()`（对话式玩法）
|
||||
- `execute<Play>Action()`
|
||||
统一约定：
|
||||
|
||||
### Step 6: 接入通用 Agent flow controller
|
||||
- 槽位用 `slotId` 稳定标识，`slotType` 表达用途，`slotName` 用于 UI 标签。
|
||||
- 上传图、参考图、AI 重绘、历史图选择和删除确认都通过 `CreativeImageInputPanel` 入口表达。
|
||||
- 后端写回 `imageSrc`、`imageObjectKey`、`assetObjectId` 中可用字段；前端展示前通过平台资产读取能力换签。
|
||||
- 单个槽位重生成只禁用该槽位动作，不阻塞结果页其它槽位、系列素材槽位或导航。
|
||||
|
||||
文件：
|
||||
- `./Genarrative/src/components/platform-entry/usePlatformCreationAgentFlowController.ts`
|
||||
### 7. 系列素材图集生成
|
||||
|
||||
如果是 Agent 型玩法，复用通用控制器：
|
||||
- `createSession`
|
||||
- `getSession`
|
||||
- `streamMessage`
|
||||
- `executeAction`
|
||||
- `isBusy`
|
||||
地块、物品、障碍、装饰、UI 部件等一组同类素材都走通用系列素材图集生成流程：
|
||||
|
||||
```text
|
||||
批量规划 -> sheet 生图 -> 后端切图 -> 去背景/透明化 -> PNG 输出 -> OSS 持久化 -> 状态回写 -> 局部重生成
|
||||
```
|
||||
|
||||
玩法只提供：
|
||||
|
||||
- `sheetSpec`：画布比例、行列、单格尺寸、输出格式、背景处理策略。
|
||||
- `slotSpecs`：每个素材槽位的 `slotId`、`slotType`、`slotName`、提示词、sheet 单元格映射。
|
||||
- 玩法字段映射：把通用素材结果映射回玩法自己的 draft/profile/runtime 字段。
|
||||
|
||||
通用系列素材结果建议字段：
|
||||
|
||||
- `batchId`
|
||||
- `slotId`
|
||||
- `slotType`
|
||||
- `slotName`
|
||||
- `prompt`
|
||||
- `imageSrc`
|
||||
- `imageObjectKey`
|
||||
- `assetObjectId`
|
||||
- `sourceSheetCell`
|
||||
- `status`
|
||||
- `error`
|
||||
- `streamingReplyText`
|
||||
- `selectionStage` 切换
|
||||
|
||||
### Step 7: 定义 shared contracts
|
||||
玩法可追加运行态字段，例如半径、宽度、视图索引或碰撞参数，但不能依赖任何玩法专属字段作为平台通用模型。新增玩法 compile action 内部调用通用系列素材服务；如果通用服务还缺能力，先补通用服务再接玩法。
|
||||
|
||||
前端：
|
||||
- `./Genarrative/packages/shared/src/contracts/`
|
||||
### 8. 契约与 API
|
||||
|
||||
后端：
|
||||
- `./Genarrative/server-rs/crates/shared-contracts/src/`
|
||||
前后端必须同步补契约：
|
||||
|
||||
至少补齐：
|
||||
- session snapshot
|
||||
- create session request/response
|
||||
- message request/response
|
||||
- action request/response
|
||||
- draft/result 结构
|
||||
- work summary / gallery 结构（如果需要）
|
||||
- runtime 结构（如果需要）
|
||||
- `packages/shared/src/contracts/`
|
||||
- `server-rs/crates/shared-contracts/src/`
|
||||
|
||||
### Step 8: 实现前端 service client
|
||||
玩法 API 保留独立命名空间：
|
||||
|
||||
目录参考：
|
||||
- `./Genarrative/src/services/`
|
||||
- `POST /api/creation/<play>/sessions`
|
||||
- `GET /api/creation/<play>/sessions/{sessionId}`
|
||||
- `POST /api/creation/<play>/sessions/{sessionId}/actions`
|
||||
- `/api/creation/<play>/works`
|
||||
- `/api/creation/<play>/runtime`
|
||||
|
||||
按玩法补：
|
||||
- creation client
|
||||
- runtime client（可选）
|
||||
- works client（可选）
|
||||
- gallery client（可选）
|
||||
契约需要区分：
|
||||
|
||||
建议保持和现有玩法一致的 API base 与命名风格。
|
||||
- 工作台输入。
|
||||
- 草稿 snapshot。
|
||||
- 单图资产槽位。
|
||||
- 系列素材批次与槽位。
|
||||
- 结果页操作。
|
||||
- 发布作品摘要。
|
||||
- runtime snapshot。
|
||||
|
||||
### Step 9: 接后端 API
|
||||
### 9. 后端分层
|
||||
|
||||
文件参考：
|
||||
- `./Genarrative/server-rs/crates/api-server/src/puzzle.rs`
|
||||
- `./Genarrative/server-rs/crates/api-server/src/puzzle_agent_turn.rs`
|
||||
- `./Genarrative/server-rs/crates/api-server/src/match3d.rs`
|
||||
按 DDD 边界落地：
|
||||
|
||||
通常需要：
|
||||
- create session
|
||||
- get session
|
||||
- send message
|
||||
- stream message
|
||||
- execute action
|
||||
- publish / save / delete
|
||||
- runtime start / action（可选）
|
||||
- gallery / detail（可选）
|
||||
- `module-<play>`：纯领域规则、状态机、draft/runtime 校验。
|
||||
- `shared-contracts`：前后端 DTO。
|
||||
- `spacetime-module`：表、reducer、procedure、事务编排、migration。
|
||||
- `spacetime-client`：typed facade 和 row mapper。
|
||||
- `api-server`：Axum 路由、鉴权、BFF、SSE、生成编排。
|
||||
- `platform-*`：LLM、图片生成、OSS、认证等外部副作用。
|
||||
|
||||
后端设计优先按 Genarrative 的 DDD 分层拆开，不要把玩法规则、数据库事务、LLM 调用和 HTTP handler 混在一个文件里：
|
||||
- `module-<play>`：纯领域规则、状态机、draft/runtime 校验，不依赖 Axum、SpacetimeDB 或外部平台。
|
||||
- `shared-contracts`：前后端 DTO、请求/响应、session snapshot、draft/result/runtime 结构。
|
||||
- `spacetime-module`：表定义、reducer/procedure、事务编排、migration；表结构变化要同步生成绑定。
|
||||
- `spacetime-client`：api-server 到 SpacetimeDB 的 facade，隐藏 reducer 调用细节。
|
||||
- `api-server`：Axum 路由、鉴权、SSE/stream、应用层编排。
|
||||
- `platform-*`：LLM、资产上传、鉴权、第三方服务等副作用。
|
||||
涉及 SpacetimeDB schema 时同步 `migration.rs`、表目录和绑定，并运行 `npm run check:spacetime-schema`。
|
||||
|
||||
建议按四条线设计后端能力：
|
||||
- Agent 创作线：session、turn、stream、compile action。
|
||||
- Works 作品线：保存、发布、删除、草稿恢复。
|
||||
- Gallery 广场线：公开列表、详情、like/remix/share。
|
||||
- Runtime 运行态线：开始试玩、提交动作、读取状态。
|
||||
|
||||
### Step 10: 新增工作台组件
|
||||
|
||||
目录建议：
|
||||
- `./Genarrative/src/components/<play>-creation/<Play>AgentWorkspace.tsx`
|
||||
|
||||
两种形态：
|
||||
|
||||
#### 对话式
|
||||
适合设定逐轮补齐。
|
||||
|
||||
参考：
|
||||
- `BigFishAgentWorkspace.tsx`
|
||||
- `Match3DAgentWorkspace.tsx`
|
||||
|
||||
#### 表单式
|
||||
适合输入结构明确的玩法。
|
||||
|
||||
参考：
|
||||
- `PuzzleAgentWorkspace.tsx`
|
||||
|
||||
### Step 11: 在渲染树中挂载新页面
|
||||
|
||||
文件：
|
||||
- `./Genarrative/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
|
||||
补齐：
|
||||
- workspace 分支
|
||||
- generating 分支（如需要）
|
||||
- result 分支
|
||||
- runtime 分支（如需要）
|
||||
|
||||
### Step 12: 新增结果页
|
||||
|
||||
目录建议：
|
||||
- `./Genarrative/src/components/<play>-result/<Play>ResultView.tsx`
|
||||
### 10. 结果页
|
||||
|
||||
结果页至少支持：
|
||||
- 展示 draft
|
||||
- 返回编辑
|
||||
- 发布
|
||||
- 试玩
|
||||
- 错误展示
|
||||
|
||||
### Step 13: 需要试玩就补 runtime
|
||||
- 展示草稿和生成状态。
|
||||
- 返回工作台编辑。
|
||||
- 单图槽位重生成。
|
||||
- 系列素材追加、替换、局部重生成。
|
||||
- 发布。
|
||||
- 试玩。
|
||||
- 错误展示和失败重试。
|
||||
|
||||
目录建议：
|
||||
- `./Genarrative/src/components/<play>-runtime/<Play>RuntimeShell.tsx`
|
||||
单图槽位和系列素材槽位的生成状态互不阻塞。已有可查看结果时，局部重生成不能把作品架草稿重新变成不可打开的全局生成中。
|
||||
|
||||
如果玩法是游戏类，建议补完整 runtime 闭环。
|
||||
### 11. 运行态、作品架和广场
|
||||
|
||||
### Step 14: 接入作品架 / 广场 / 分享
|
||||
需要试玩或发布时补齐：
|
||||
|
||||
需要改：
|
||||
- `./Genarrative/src/components/custom-world-home/creationWorkShelf.ts`
|
||||
- `./Genarrative/src/components/custom-world-home/CustomWorldCreationHub.tsx`
|
||||
- `./Genarrative/src/services/publicWorkCode.ts`
|
||||
- runtime start/action/finish API。
|
||||
- 作品保存、发布、删除、回读。
|
||||
- 作品架摘要。
|
||||
- 公开列表、详情、分享码。
|
||||
- 公开列表优先消费后端投影或 BFF 缓存，不让前端直接拼源表事实。
|
||||
|
||||
如果玩法支持发布，还要补：
|
||||
- public work code
|
||||
- public detail
|
||||
- publish share modal
|
||||
- like/remix（可选）
|
||||
运行态可以做低延迟表现，但正式胜负、分数、奖励、排行榜和发布状态以后端裁决为准。
|
||||
|
||||
### Step 15: 处理登录态与草稿恢复
|
||||
### 12. 恢复与登录态
|
||||
|
||||
要考虑：
|
||||
- 刷新恢复草稿
|
||||
- 退出登录清空私有状态
|
||||
- result/draft 缺失时回退
|
||||
- busy / generating / runtime 中断恢复
|
||||
必须处理：
|
||||
|
||||
### Step 16: 补测试
|
||||
- 刷新恢复生成中草稿。
|
||||
- 生成页计时从后端摘要时间恢复。
|
||||
- 失败后回读 session/work detail 再决定是否展示失败。
|
||||
- 退出登录清空私有玩法状态。
|
||||
- 私有生成图展示前换签。
|
||||
- result/runtime 缺必要 draft 时回到可恢复入口，不停在空白页。
|
||||
|
||||
至少覆盖：
|
||||
- 入口展示
|
||||
- 类型分流
|
||||
- 工作台打开
|
||||
- session 创建
|
||||
- compile action
|
||||
- result 页切换
|
||||
- 发布后刷新作品架
|
||||
- runtime 进入与退出
|
||||
### 13. 例外流程
|
||||
|
||||
## 最小改动清单
|
||||
任何非表单/图片工作台、对话式 Agent、独立创作系统或特殊资产模型都必须先更新 PRD 和平台文档。例外声明至少写清：
|
||||
|
||||
### 只做占位
|
||||
- 为什么默认表单/图片工作台不能满足。
|
||||
- 例外影响哪些输入、契约、后端流程和测试。
|
||||
- 如何保留单图资产槽位和系列素材槽位的通用能力。
|
||||
- 如何回退到平台默认链路。
|
||||
|
||||
只改：
|
||||
- `./Genarrative/src/config/newWorkEntryConfig.ts`
|
||||
没有文档例外，不进入编码。
|
||||
|
||||
### 做到可进入工作台
|
||||
## PRD 检查块
|
||||
|
||||
至少改：
|
||||
- `newWorkEntryConfig.ts`
|
||||
- `platformEntryTypes.ts`
|
||||
- `PlatformEntryFlowShellImpl.tsx`
|
||||
- 新玩法 service client
|
||||
- 新玩法工作台组件
|
||||
- shared contracts
|
||||
- 后端 API
|
||||
在新增玩法 PRD 中保留这一段：
|
||||
|
||||
### 做到完整闭环
|
||||
```md
|
||||
## 创作工具平台接入声明
|
||||
|
||||
还要补：
|
||||
- result 页
|
||||
- runtime
|
||||
- works / gallery
|
||||
- public code
|
||||
- share
|
||||
- 作品架聚合
|
||||
- 测试
|
||||
- 工作台模式：表单/图片输入创作工作台
|
||||
- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
|
||||
- 单图资产槽位：
|
||||
- slotId / slotType / slotName / 提示词来源 / 写回字段 / 是否允许历史图 / 是否允许 AI 重绘
|
||||
- 系列素材槽位：
|
||||
- batchId / sheetSpec / slotSpecs / 切图规则 / 透明化规则 / 失败回写 / 局部重生成
|
||||
- API 命名空间：/api/creation/<play>/...
|
||||
- 业务真相：后端裁决字段和前端表现字段边界
|
||||
- 创作工具模式例外：无；如有，先写明例外原因和回退方式
|
||||
- 验证命令：
|
||||
```
|
||||
|
||||
## 常见坑
|
||||
## 验证门禁
|
||||
|
||||
1. 只加入口配置不够，类型分流和页面阶段也要补。
|
||||
2. `SelectionStage` 不扩展，前端无法安全切页。
|
||||
3. 新玩法如果要出现在作品架，必须改聚合逻辑，不只是加入口。
|
||||
4. 发布后不刷新 works/gallery，用户会看不到新作品。
|
||||
5. 如果走 SpacetimeDB，表结构变化要同步 migration 和绑定；`spacetime-client/src/module_bindings/` 通常是生成物，不要为了修编译或格式化而手改，优先改 module 源 schema/reducer/procedure 后重新生成。
|
||||
6. 做 analytics/tracking 这类 runtime 能力时，不要只补 API DTO；先在 `module-runtime` 写纯函数测试（例如 day/week/month/quarter/year bucket 聚合、scope/event 过滤），RED 后再补领域类型与聚合函数。
|
||||
7. 时间粒度聚合建议复用已有 date dimension 逻辑，把 daily stat 映射到 day/week/month/quarter/year bucket；bucket 输出要有稳定排序，并显式携带 `bucketKey`、`bucketStartDateKey`、`bucketEndDateKey`、`value`。
|
||||
8. 后端 shared-contracts 与前端 `packages/shared/src/contracts/runtime.ts` 要同步补 request/response/type union；admin-web 若有独立 `api/adminApiTypes.ts`，也要同步，避免共享包已更新但管理端本地类型缺失。
|
||||
9. 退出登录时要清空新玩法私有状态，避免串用户。
|
||||
10. 移动端入口卡片增多后要检查布局和滚动体验。
|
||||
按改动范围运行：
|
||||
|
||||
## 参考资料
|
||||
|
||||
- `references/genarrative-analytics-tracking-runtime.md`：analytics/tracking runtime 粒度聚合、contracts 同步与 SpacetimeDB 生成物注意事项。
|
||||
|
||||
## 验证标准
|
||||
|
||||
一个玩法算真正接入成功，至少要满足：
|
||||
|
||||
- 入口能展示
|
||||
- 能进入对应工作台
|
||||
- 能创建 session
|
||||
- 能生成草稿
|
||||
- 能进入结果页
|
||||
- 能返回编辑
|
||||
- 如果需要，可试玩
|
||||
- 如果需要，可发布
|
||||
- 发布后能回到作品架 / 广场 / 分享链路
|
||||
- `npm run check:encoding`
|
||||
- `npm run typecheck`
|
||||
- 前端工作台测试：确认没有聊天式 Agent 输入，提交的是表单/图片 payload。
|
||||
- `CreativeImageInputPanel` 测试：覆盖多玩法标签、上传、AI 重绘、参考图上限、历史图入口和删除确认。
|
||||
- 系列素材测试：覆盖 sheet layout、切图、透明化、OSS 持久化、追加、替换、局部重生成和失败回写。
|
||||
- 结果页测试：覆盖单图槽位重生成和系列素材槽位重生成互不阻塞。
|
||||
- 后端定向测试：覆盖 compile action、资产持久化、失败回写、发布和 runtime start。
|
||||
- 涉及 SpacetimeDB schema 时运行 `npm run check:spacetime-schema`。
|
||||
|
||||
14
CONTEXT.md
14
CONTEXT.md
@@ -2,6 +2,20 @@
|
||||
|
||||
Genarrative 是一个 AI 原生互动内容与小游戏平台，当前上下文记录团队在玩法、作品、运行态和平台闭环中使用的领域语言。
|
||||
|
||||
## 平台创作工具
|
||||
|
||||
**表单/图片输入创作工作台**:
|
||||
新增玩法默认采用的创作工具模式，用户通过结构化表单、图片槽位和配置控件提交创作输入，链路覆盖入口、工作台、生成页、结果页、试玩、发布和运行态闭环。
|
||||
_Avoid_: 默认对话式 Agent 工作台、默认轻输入 Agent 工作台、复制既有玩法工作台
|
||||
|
||||
**单图资产编辑**:
|
||||
角色形象、UI 背景、容器、封面、分享图等单张图资产的统一输入与重生成方式，统一通过 `CreativeImageInputPanel` 表达上传、AI 重绘、参考图、历史图和删除确认。
|
||||
_Avoid_: 在玩法页面内手写上传、参考图、重绘、预览、删除确认
|
||||
|
||||
**系列素材图集生成**:
|
||||
一组同类素材的统一批量生成方式，采用批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成的通用流水线。
|
||||
_Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成任一玩法专属 DTO
|
||||
|
||||
## Language
|
||||
|
||||
### Bark Battle
|
||||
|
||||
Reference in New Issue
Block a user