This commit is contained in:
389
.codex/skills/genarrative-play-type-integration/SKILL.md
Normal file
389
.codex/skills/genarrative-play-type-integration/SKILL.md
Normal file
@@ -0,0 +1,389 @@
|
|||||||
|
---
|
||||||
|
name: genarrative-play-type-integration
|
||||||
|
description: 在 Genarrative 中新增一个创作入口/玩法类型时，按入口配置、前端分流、契约、后端接口、工作台、结果页、可选 runtime 与作品架的顺序接入。
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
author: Hermes Agent
|
||||||
|
version: "1.0"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Genarrative 新增玩法类型接入流程
|
||||||
|
|
||||||
|
用于在 Genarrative 中新增一个创作入口/玩法类型，而不是单纯说明用户如何从入口创建作品。
|
||||||
|
|
||||||
|
## 适用场景
|
||||||
|
|
||||||
|
- 新增一个游戏玩法入口
|
||||||
|
- 让某个玩法从“敬请期待”变为可创建
|
||||||
|
- 为新玩法补齐创作工作台、结果页、发布与试玩链路
|
||||||
|
- 将新玩法接入创作中心作品架与广场
|
||||||
|
|
||||||
|
## 先判断接入级别
|
||||||
|
|
||||||
|
### 1. 只做入口占位
|
||||||
|
|
||||||
|
只需要新增入口配置，不接 session/workspace/result/runtime。
|
||||||
|
|
||||||
|
适合：
|
||||||
|
|
||||||
|
- 敬请期待
|
||||||
|
- 灰度占位
|
||||||
|
|
||||||
|
### 2. 可进入创作工作台
|
||||||
|
|
||||||
|
需要补齐前端分流、session、工作台、结果页，至少能生成草稿。
|
||||||
|
|
||||||
|
### 3. 完整玩法闭环
|
||||||
|
|
||||||
|
需要补齐：
|
||||||
|
|
||||||
|
- 创作入口
|
||||||
|
- 工作台
|
||||||
|
- 草稿生成
|
||||||
|
- 结果页
|
||||||
|
- 发布
|
||||||
|
- 试玩 runtime
|
||||||
|
- 作品架 / 广场 / 分享
|
||||||
|
|
||||||
|
## 推荐接入顺序
|
||||||
|
|
||||||
|
### Step 1: 先定玩法 ID 和能力边界
|
||||||
|
|
||||||
|
先明确：
|
||||||
|
|
||||||
|
- `id` 是什么
|
||||||
|
- 入口是否可见
|
||||||
|
- 是否可点击创建
|
||||||
|
- 是否需要对话式创作
|
||||||
|
- 是否需要生成中页面
|
||||||
|
- 是否需要 result/runtime/gallery/share
|
||||||
|
|
||||||
|
不要先随便起临时 ID 再改名。
|
||||||
|
|
||||||
|
### Step 2: 新增入口配置
|
||||||
|
|
||||||
|
文件：
|
||||||
|
|
||||||
|
- `src/config/newWorkEntryConfig.ts`
|
||||||
|
|
||||||
|
在 `creationTypes` 中新增：
|
||||||
|
|
||||||
|
- `id`
|
||||||
|
- `title`
|
||||||
|
- `subtitle`
|
||||||
|
- `badge`
|
||||||
|
- `visible`
|
||||||
|
- `open`
|
||||||
|
|
||||||
|
如果只是占位：
|
||||||
|
|
||||||
|
- `visible: true`
|
||||||
|
- `open: false`
|
||||||
|
|
||||||
|
### Step 3: 确认类型过滤逻辑
|
||||||
|
|
||||||
|
文件：
|
||||||
|
|
||||||
|
- `src/components/platform-entry/platformEntryCreationTypes.ts`
|
||||||
|
|
||||||
|
检查：
|
||||||
|
|
||||||
|
- `getVisiblePlatformCreationTypes()` 是否能展示新类型
|
||||||
|
- `isPlatformCreationTypeVisible()` 是否能识别新类型
|
||||||
|
- `locked` / `hidden` 是否正确映射
|
||||||
|
|
||||||
|
### Step 4: 扩展页面阶段
|
||||||
|
|
||||||
|
文件：
|
||||||
|
|
||||||
|
- `src/components/platform-entry/platformEntryTypes.ts`
|
||||||
|
|
||||||
|
为新玩法补充 `SelectionStage`：
|
||||||
|
|
||||||
|
- `*-agent-workspace`
|
||||||
|
- `*-generating`（可选）
|
||||||
|
- `*-result`
|
||||||
|
- `*-runtime`（可选）
|
||||||
|
- `*-gallery-detail`（可选）
|
||||||
|
|
||||||
|
### Step 5: 在总流程中加类型分流
|
||||||
|
|
||||||
|
文件：
|
||||||
|
|
||||||
|
- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||||
|
|
||||||
|
在 `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`
|
||||||
|
- `error`
|
||||||
|
- `streamingReplyText`
|
||||||
|
- `selectionStage` 切换
|
||||||
|
|
||||||
|
### Step 7: 定义 shared contracts
|
||||||
|
|
||||||
|
前端：
|
||||||
|
|
||||||
|
- `packages/shared/src/contracts/`
|
||||||
|
|
||||||
|
后端：
|
||||||
|
|
||||||
|
- `server-rs/crates/shared-contracts/src/`
|
||||||
|
|
||||||
|
至少补齐：
|
||||||
|
|
||||||
|
- session snapshot
|
||||||
|
- create session request/response
|
||||||
|
- message request/response
|
||||||
|
- action request/response
|
||||||
|
- draft/result 结构
|
||||||
|
- work summary / gallery 结构（如果需要）
|
||||||
|
- runtime 结构（如果需要）
|
||||||
|
|
||||||
|
### Step 8: 实现前端 service client
|
||||||
|
|
||||||
|
目录参考：
|
||||||
|
|
||||||
|
- `src/services/`
|
||||||
|
|
||||||
|
按玩法补：
|
||||||
|
|
||||||
|
- creation client
|
||||||
|
- runtime client（可选）
|
||||||
|
- works client（可选）
|
||||||
|
- gallery client（可选）
|
||||||
|
|
||||||
|
建议保持和现有玩法一致的 API base 与命名风格。
|
||||||
|
|
||||||
|
### 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`
|
||||||
|
|
||||||
|
结果页至少支持：
|
||||||
|
|
||||||
|
- 展示 draft
|
||||||
|
- 返回编辑
|
||||||
|
- 发布
|
||||||
|
- 试玩
|
||||||
|
- 错误展示
|
||||||
|
|
||||||
|
### Step 13: 需要试玩就补 runtime
|
||||||
|
|
||||||
|
目录建议：
|
||||||
|
|
||||||
|
- `src/components/<play>-runtime/<Play>RuntimeShell.tsx`
|
||||||
|
|
||||||
|
如果玩法是游戏类，建议补完整 runtime 闭环。
|
||||||
|
|
||||||
|
### Step 14: 接入作品架 / 广场 / 分享
|
||||||
|
|
||||||
|
需要改：
|
||||||
|
|
||||||
|
- `src/components/custom-world-home/creationWorkShelf.ts`
|
||||||
|
- `src/components/custom-world-home/CustomWorldCreationHub.tsx`
|
||||||
|
- `src/services/publicWorkCode.ts`
|
||||||
|
|
||||||
|
如果玩法支持发布，还要补：
|
||||||
|
|
||||||
|
- public work code
|
||||||
|
- public detail
|
||||||
|
- publish share modal
|
||||||
|
- like/remix（可选）
|
||||||
|
|
||||||
|
### Step 15: 处理登录态与草稿恢复
|
||||||
|
|
||||||
|
要考虑：
|
||||||
|
|
||||||
|
- 刷新恢复草稿
|
||||||
|
- 退出登录清空私有状态
|
||||||
|
- result/draft 缺失时回退
|
||||||
|
- busy / generating / runtime 中断恢复
|
||||||
|
|
||||||
|
### Step 16: 补测试
|
||||||
|
|
||||||
|
至少覆盖：
|
||||||
|
|
||||||
|
- 入口展示
|
||||||
|
- 类型分流
|
||||||
|
- 工作台打开
|
||||||
|
- session 创建
|
||||||
|
- compile action
|
||||||
|
- result 页切换
|
||||||
|
- 发布后刷新作品架
|
||||||
|
- runtime 进入与退出
|
||||||
|
|
||||||
|
## 最小改动清单
|
||||||
|
|
||||||
|
### 只做占位
|
||||||
|
|
||||||
|
只改：
|
||||||
|
|
||||||
|
- `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
|
||||||
|
```
|
||||||
|
|
||||||
|
如果新增完整前端玩法闭环，还要按项目实际脚本补充 web typecheck、lint 或 Playwright/单元测试。
|
||||||
Reference in New Issue
Block a user