GenarrativeAI/Genarrative

Fork 0

Files

五香丸子 e444266e1e feat: add edutainment drawing and visual package flows

2026-05-14 14:56:36 +08:00

14 KiB

Raw Blame History

宝贝识物创作发布实现方案 2026-05-11

1. 范围

本方案对应第 2 线程：创作发布线程。

本线程落地：

创作入口配置；
模板表单；
本地草稿生成 service；
结果页；
发布 payload 约束；
本地 Demo 运行态；
后端 image-2 / 作品持久化 / 运行态接口预留形状。

本阶段运行态先做浏览器本地 Demo，并消费现有本地 mocap 动作数据源；正式硬件接口和摄像头调教在后续接口稳定后继续接入。

2. 前端接入点

新增玩法 ID：

baby-object-match

用户展示名：

宝贝识物

工程接入文件：

server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs
src/components/platform-entry/platformEntryCreationTypes.ts
src/components/platform-entry/PlatformEntryCreationTypeModal.tsx
src/components/platform-entry/PlatformEntryFlowShellImpl.tsx

src/config/newWorkEntryConfig.ts 已迁移删除，不再作为入口事实源。baby-object-match 必须存在于 SpacetimeDB creation_entry_type_config 默认种子中，默认展示名为 宝贝识物、visible=true、open=true、sortOrder=90；前端只通过 GET /api/creation-entry/config 读取后端配置并在 platformEntryCreationTypes.ts 做展示派生。

baby-object-match 必须复用 VITE_ENABLE_EDUTAINMENT_ENTRY 开关；开关关闭时，创作类型弹层不展示 宝贝识物，创作页作品架不展示本地宝贝识物草稿或已发布作品卡，公开发现、搜索、详情、作品号和浏览历史也继续完全不可见。

新增阶段：

baby-object-match-workspace
baby-object-match-generating
baby-object-match-result
baby-object-match-runtime

3. 契约

前端共享契约放在：

packages/shared/src/contracts/edutainmentBabyObject.ts

核心字段：

BabyObjectMatchDraft.templateId = "baby-object-match"；
BabyObjectMatchDraft.templateName = "宝贝识物"；
BabyObjectMatchDraft.themeTags 必须包含精确 寓教于乐；
BabyObjectMatchItemAsset.generationProvider 首版允许为 vector-engine-gpt-image-2 或 placeholder；
BabyObjectMatchDraft.visualPackage 可选承载背景环境、UI 装饰框、礼物盒、篮子和烟雾弹出特效五类视觉资源；
BabyObjectMatchPublishRequest.draft.themeTags 发布前必须归一化补齐 寓教于乐。

4. Service 边界

前端 service 放在：

src/services/edutainment-baby-object/babyObjectMatchClient.ts

首版提供：

createBabyObjectMatchDraft(payload)；
saveBabyObjectMatchDraft(draft)；
publishBabyObjectMatchWork(payload)；
deleteLocalBabyObjectMatchDraft(profileId)；
regenerateBabyObjectMatchDraftAssets(draft)；
hasBabyObjectMatchPlaceholderAssets(draft)。

当前后端正式作品持久化接口未在本线程扩表落地，因此 service 仍使用本地 Demo 存储草稿和发布状态。由于 image-2 会返回多张 base64 PNG 大图，本地 Demo 草稿必须优先写入 IndexedDB genarrative-edutainment-baby-object-drafts/drafts，不得把完整草稿 JSON 写入 localStorage；localStorage 仅作为旧版小草稿迁移读取来源，读取后迁移到 IndexedDB 并清理旧 key，避免触发浏览器 Storage 配额错误。

物品图片生成已接入后端 image-2 接口：

POST /api/creation/edutainment/baby-object-match/assets

请求体：

{
  "itemNames": ["苹果", "香蕉"]
}

响应体：

{
  "assets": [
    {
      "itemId": "baby-object-item-1",
      "itemName": "苹果",
      "imageSrc": "data:image/png;base64,...",
      "assetObjectId": null,
      "generationProvider": "vector-engine-gpt-image-2",
      "prompt": "..."
    }
  ],
  "visualPackage": {
    "themePrompt": "...",
    "assets": [
      {
        "assetId": "baby-object-visual-background",
        "assetKind": "background",
        "imageSrc": "data:image/png;base64,...",
        "assetObjectId": null,
        "generationProvider": "vector-engine-gpt-image-2",
        "prompt": "..."
      }
    ]
  }
}

该接口返回物品透明 PNG data URL，以及同一次创作生成的视觉主题包。本地 Demo 阶段暂不写入 OSS 或 SpacetimeDB asset_object。当前创作链路必须真实拿到 generationProvider = "vector-engine-gpt-image-2" 的物品图和视觉主题包后才允许进入结果页；若本地未配置 VectorEngine、登录态失效、接口返回 401/5xx、上游生成失败或响应缺少任一资源，前端 service 必须抛出错误并停留在生成失败状态，不得静默回退到占位图。

由于一次创作会生成 2 张物品图和 background、ui-frame、gift-box、basket、smoke-puff 5 张视觉包装图，该请求属于长耗时 image-2 链路。前端 babyObjectMatchClient 对该 POST 使用 10 分钟请求超时，且不做自动重试，避免第一次生成仍在后端执行时又发起第二次重复生成。后端同时启动物品图与视觉主题包生成，并把该路由的 VectorEngine 单图请求等待预算提升到至少 8 分钟，避免某张图 3 分钟附近仍在生成时被后端提前断开。后端日志记录每类资源的开始、完成和耗时，排查时优先按同一次 HTTP 请求查看 宝贝识物 image-2 物品资源生成完成、宝贝识物 image-2 视觉资源生成完成 与 VectorEngine 图片生成上游错误。

历史本地草稿中若已保存 generationProvider = "placeholder" 的旧占位资源，结果页必须提示“重新生成 image-2 资源”，并禁用试玩和发布。用户点击重新生成、发布或试玩前，前端统一调用 regenerateBabyObjectMatchDraftAssets(draft) 补齐资源；补齐失败时保留在结果页并展示错误。

后续正式作品持久化接入时，应补齐：

POST /api/creation/edutainment/baby-object-match/drafts
PUT  /api/creation/edutainment/baby-object-match/drafts/{draftId}
POST /api/creation/edutainment/baby-object-match/drafts/{draftId}/publish

图片生成必须在后端调用 VectorEngine gpt-image-2-all，不得从前端直接调用外部图片接口。

后端 image-2 prompt 约束：

锁定寓教于乐板块统一的卡通绘本草地舞台插画风；
每张图只能围绕对应关键词生成一个单一物品；
不生成背景、场景、氛围渲染、人物、手、篮子、礼物盒、文字、水印或 UI；
优先要求纯白或透明抠图友好的干净背景，服务端再统一转透明 PNG 并执行背景 alpha 清理；
返回 generationProvider = "vector-engine-gpt-image-2" 的素材必须已经完成透明抠图。

后端视觉主题包 prompt 约束：

同一次请求根据两个物品关键词生成 background、ui-frame、gift-box、basket、smoke-puff 五类资源；
总风格继续锁定寓教于乐明亮卡通绘本插画风；
若关键词偏动漫角色、玩具或公仔，背景环境和 UI 元素匹配动漫、玩具主题；若关键词偏水果，匹配果园、自然主题；其它关键词按语义匹配合适主题；
背景环境图使用非透明 16:9 图，但必须保证中间、中下方和底部左右篮子区域清爽，给放大后的礼物盒、中央物品和左右篮子预留空间，不画入礼物盒、篮子、物品、人物、文字或操作 UI；
UI 装饰框、礼物盒、篮子和烟雾弹出特效使用透明 PNG 后处理，不生成文字、数字、按钮、人物或待分类物品；
gift-box 提示词必须面向运行态约 2 倍视觉尺寸生成主体饱满的大号礼物盒，basket 提示词必须面向运行态约 1.5 倍视觉尺寸生成可读性高的大号篮子；
smoke-puff 只生成礼物盒打开瞬间使用的柔和烟雾云朵特效，不生成礼物盒、篮子、物品或文字；
左右篮子的固定选项规则不受主题包影响，运行态只把 basket 作为篮子造型包装复用。

5. UI 边界

工作台只展示两个必填输入和生成按钮。

结果页只展示草稿核心信息、两个物品、保存草稿、发布、试玩。不在 UI 内写玩法说明长文案。

移动端优先：表单和结果页使用单列布局，桌面端自然扩展为双列。

6. 运行态边界

前端运行态放在：

src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.tsx

运行态直接消费 BabyObjectMatchDraft，必须使用草稿中的两个物品名称和物品图。每轮只随机当前从礼物盒跳出的物品；左右篮子不随机交换，左侧固定为草稿 itemAssets[0]，右侧固定为草稿 itemAssets[1]。

若草稿包含 visualPackage，运行态通过背景图片层、CSS 变量和图片节点消费：

background：作为舞台最底层 ResolvedAssetImage 背景图；存在该资源时必须关闭默认草地兜底层，避免生成场景被 CSS 草地遮住或弱化；
ui-frame：作为字幕条和计数器装饰背景；
gift-box：替换 CSS 礼物盒主体，按旧视觉约 2 倍尺寸展示，只在礼盒入场和打开阶段存在；
basket：替换篮子主体造型，按旧视觉约 1.5 倍尺寸展示，左右两侧复用同一张主题篮子图；
smoke-puff：作为礼物盒打开和中央物品弹出期间的透明烟雾特效资源。

旧草稿或接口失败时 visualPackage = null，运行态继续使用现有 CSS 绘本风兜底。

首关状态机：

gift-entering：礼物盒从上方落下入场动画阶段，不接受动作判定；
gift-opening：礼物盒打开并播放烟雾特效阶段，不接受动作判定；
item-appearing：礼物盒从舞台移除，当前物品从烟雾中出现并停稳，不接受动作判定；
active：物品彻底出现后才开放选篮判定；
correct：展示“真棒”反馈，对应篮筐播放正确特效并停顿，成功次数加 1；特效完全结束后重新进入 gift-entering，下一轮礼物盒从上方落下；
wrong：展示“再想一想吧”反馈，物品弹回中央；反馈结束后回到 active，不重新随机物品；
complete：成功次数达到 20，展示“恭喜你！小朋友！”和按钮。

动作输入：

左手连续横向移动达到阈值：将当前物品送入左侧篮子；
右手连续横向移动达到阈值：将当前物品送入右侧篮子。

运行态直接通过 useMocapInput 消费本地 mocap WebSocket /stream。选篮只使用明确 leftHand 或 rightHand 的连续横向轨迹阈值，不再通过 wave_left_hand、wave_right_hand、wave 等动作名触发；侧别为 unknown 的手部轨迹也不参与选篮，以避免多套判定误命中和连续误触发。动作判定只在 active 阶段开放，礼盒入场、礼盒打开、物品出现、正确反馈和错误反馈阶段收到的动作包必须清空轨迹并忽略，不允许跨阶段补判定。当前本地 mocap 输出的 handedness 按摄像头视角标记，宝贝识物运行态必须先换算为用户身体视角：rightHand 轨迹映射玩家左手并进入左侧篮子，leftHand 轨迹映射玩家右手并进入右侧篮子。草稿试玩、发布后正式体验和热身关后的本地 Demo 都复用同一个运行态，因此三条入口都必须具备同一套动作控制能力。

开发者调试输入：

鼠标左键按下并拖动：映射左手轨迹，抬起后将当前物品送入左侧篮子；
鼠标右键按下并拖动：映射右手轨迹，抬起后将当前物品送入右侧篮子。

运行态不得新增计时、失败次数、分数、体力或难度递增规则。

音效和语音播报当前只保留接口预留边界，正式语音接口后续接入。

7. 发布约束

发布前必须执行：

两个物品名非空；
两个物品名对应的 asset 存在；
标签补齐精确 寓教于乐；
publicationStatus 从 draft 变为 published。

发布后首版本地响应返回 publicWorkCode，用于分享弹窗；正式后端接入时 public code 生成规则需要纳入统一作品号服务。

8. 热身关衔接

/child-motion-demo 热身完成后的“开始游戏”按钮进入同一个 BabyObjectMatchRuntimeShell。

热身关独立 Demo 没有创作者草稿上下文，因此使用固定本地 Demo 草稿承载两个物品，仅用于热身关后验证首关体验；正式平台体验仍必须从 宝贝识物 模板创作发布后进入寓教于乐板块。

9. 验收命令

npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.test.tsx src/components/child-motion-demo/ChildMotionWarmupDemo.test.tsx src/services/edutainment-baby-object/babyObjectMatchClient.test.ts
cargo test -p api-server edutainment_baby_object --manifest-path server-rs/Cargo.toml
npx vitest run src/components/platform-entry/platformEdutainmentVisibility.test.ts src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/custom-world-home/creationWorkShelf.test.ts src/services/useMocapInput.test.ts src/services/child-motion-demo/childMotionDebugInput.test.ts src/routing/appRoutes.test.ts
npx eslint src/components/platform-entry/platformEntryCreationTypes.ts src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --ext .ts,.tsx --max-warnings 0
npm run check:encoding
npm run typecheck
npm run build:raw

若后续接入真实 Rust API 和 SpacetimeDB 表，再补充 npm run api-server、/healthz、Rust contract / api-server / spacetime-client 定向测试和 migration 表目录更新。

14 KiB Raw Blame History Unescape Escape