From 100fee7e7a2c41f713006e13d73b428a4e75d610 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8E=86=E5=86=B0=E9=83=81-hermes=E7=89=88?=
 <kdletters@qq.com>
Date: Mon, 4 May 2026 16:34:18 +0800
Subject: [PATCH] docs: add genarrative play type skill

---
 .../SKILL.md                                  | 389 ++++++++++++++++++
 1 file changed, 389 insertions(+)
 create mode 100644 .codex/skills/genarrative-play-type-integration/SKILL.md

diff --git a/.codex/skills/genarrative-play-type-integration/SKILL.md b/.codex/skills/genarrative-play-type-integration/SKILL.md
new file mode 100644
index 00000000..d4bcb86a
--- /dev/null
+++ b/.codex/skills/genarrative-play-type-integration/SKILL.md
@@ -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/单元测试。