宜博 / h3livestream

dressup-dance-room.md 25.1 KB

换装跳舞直播间 — 需求文档（TODO / 未实现）

对应现状基线见 docs/done/live-channel-v1.md；架构层面的落地方案见 docs/structure/architecture.md。本文档记录已与产品方确认的决策 （第 2～7 节），以及仍需要技术验证/调研、非产品决策问题的部分（第 8 节）。

1. 背景与目标

新增一个跟现有文字点播直播间并列的产品：换装跳舞直播间。点播动作从 "打字描述想看什么"变成"选衣服 / 传衣服 / 传人"，本质是把"自由文本生成" 收窄成"资产库组合生成"：

人物照片（资产库） + 衣服照片（资产库或观众上传） → 生成"新衣服小姐姐"参考图 → 参考图 + 参考跳舞视频 → 生成新跳舞视频 → 排入直播间播放队列

2. 产品形态：两个独立的直播间页面（已确认）

  • live.html（现状，不变）：文字点播直播间，观众打字描述想看什么， 详见 docs/done/live-channel-v1.md。
  • dance.html（新增）：换装跳舞直播间，没有文字输入框，点播动作 全部是"选衣柜 / 传衣服 / 传人"。与 live.html 样式保持一致（同一套 视觉语言、同一套播放器/队列 UI 组件），但左侧点播面板换成换装操作， 右侧保留非文字的互动展示（在线人数、点赞、排队列表——这些跟 live.html 一样保留，只是没有聊天输入）。
  • 两个页面各自维护独立的播出时刻表（各自的 schedule/promptQueue）， 不是同一个直播间的两个 tab——它们是两条并行的产品线，共用后端的 素材库/生成流水线/账号体系等基础设施。
  • dance.html 默认竖屏、移动端优先——具体规格见第 4.4 节。 live.html 一侧此后也独立改成了竖屏默认（docs/done 2.2 节），两个 频道各自维护自己的 H3_GEN_PARAMS，互不影响、互不依赖对方的改动。

3. 观众体验流程（已确认：使用已有资产库免费，新增资产付费）

模式一：从衣柜选衣服（免费）

  1. 观众打开"衣柜"面板，浏览后台预置/其他观众上传后已沉淀的服装素材 （缩略图 + 名称/分类）。
  2. 点选一件 → 人物固定用系统默认人物（免费用户不能指定/上传人物，只能 换衣服）。第一期默认人物固定只有一个（不做多个轮换/观众选人物， 前端不需要人物选择器；后台仍以列表形式管理人物库，为以后想扩展成 多个预留空间，见 6.1 节）。
  3. 提交 → 进入生成流水线（第 4 节）→ 完成后排入播放队列。同一件衣服被 多个观众点中时，走去重缓存直接复用已有产物，见 4.6 节。
  4. 完全免费，不消耗积分——这是主力免费入口，降低参与门槛。

模式二：上传自己的衣服照片（付费，"新增衣服"）

  1. 观众上传一张衣服/穿搭图片，走轻量内容审核。
  2. 消耗积分（因为这是往衣服库里"新增"一件素材，成本高于直接选用现成 素材）。
  3. 审核通过后默认沉淀进公共衣柜库，之后所有观众（含免费用户）都能在 模式一里选到这件衣服——相当于"付费的人帮全站扩充了衣柜"。
  4. 人物仍然是系统默认人物（模式二不涉及换人物）。

模式三：上传喜欢的小姐姐照片（付费，"新增人物"）

  1. 观众上传一张人物照片。
  2. 经自动化审核（第 5 节）后即可生成——不是强制人工先审。
  3. 充值/消耗的积分数量，直接决定这个新人物能播放几个 10 秒片段—— 花得越多，这个新角色在直播间露出的时长越长。
  4. 衣服可以在提交时一并选/传，也可以不选（系统随机挑一件衣柜库服装 搭配）。
  5. 参考跳舞视频固定走系统随机（第 3.4 点）。
  6. 新人物默认不沉淀进公共人物池，只服务上传者本人这次付费请求—— 不会出现"张三充值上传的照片被李四的免费请求随机抽中生成"的情况。
  7. 到期处理：购买的那几个 10 秒片段播完后，自动下线，但人物、 已生成的视频都保留记录——用户之后再充值，可以直接续播（复用 已有产物，不用重新生成）。

三种模式的共同后置流程

  • 提交后立刻在"生成中"列表出现一条（带上传者昵称），复用现有排队 UI。
  • 生成成功 → 排入待播队列。免费内容（模式一/二）按 v1 现有投票机制 排序；模式三付费新人物内容不参与投票，直接插队/优先播放（已 确认——付费买的是"确定性上镜"，不能让它跟免费内容拼投票数），这一点 是对 v1 ensureSchedule 选片算法的实质性改动，见 docs/structure/architecture.md 1.3/2.6 节。
  • 生成失败/审核不过 → 现有"❌"状态展示；若是付费请求失败，需要退还 已扣的积分，这是底线（见第 7.2 节）。

4. 生成流水线设计（一步法 + 双算力策略）

2026-09-02 更新：本节原设计是"两段式"（先出换装图 Stage1，再生成 跳舞视频 Stage2）。第 0 期 S1 spike 实测确认一步法成立，不需要 Stage1——人物参考图 + 衣服参考图两张一起作为 reference_image_urls 提交，一次调用直接产出换装后的跳舞视频，证据见 spike/s1-s2-s4-2026-09-02/RESULTS.md。下面按一步法重写。

4.1 Stage 1：人物 + 衣服 → 换装参考图 —— 已删除，并入 4.2

原设计是独立的换装图合成步骤，S1 spike 证明不需要，见上方 2026-09-02 更新说明。本节号保留但内容已并入 4.2，避免其他文档里"4.2 节"的 引用失效（docs/todo/dressup-dance-room-mvcp.md M.15、architecture.md 2.3 节等多处引用了原编号，改编号会牵一发动全身，所以选择"删内容、留 壳"而不是整体重新编号）。

4.2 人物 + 衣服 + 参考跳舞视频 → 一次生成跳舞视频（已确认：默认时长 10 秒）

人物参考图 + 衣服参考图（reference_image_urls，衣服图在六段式 prompt 里标 attribute_transfer，语义是"只转移服装的外观属性"）+ 参考跳舞视频 （reference_video_urls，提供舞蹈动作/运镜/配乐节奏，系统随机/轮换挑选， 观众不选风格）→ 一次调用生成固定 10 秒的跳舞视频片段（H3 输出时长 硬约束是 4–15 秒，10 秒是我们在这个区间内选定的固定默认值，不随请求 变化；对应 frames = 240，按 H3-CONSOLE.md 的 frames/24fps=秒 换算 公式；实测 10 秒产物耗时约 700s，比 H3-CONSOLE.md 早期记录的 4 秒 测试片段约 200s 明显更长，帧数越多耗时越长不是常数）。产物字段是 v1 library.json clip 的超集，加 characterId/garmentId/ refDanceVideoId 溯源字段（没有 composedImageId，因为没有中间 换装图这一步）。

Prompt 遵循内部 H3 提示词写作方法论（仓库里的 docs/h3skill.md—— 这是另一并行工作产出的官方 H3 提示词写作规范，内容独立于本项目其他 文档但直接适用，复用而不是另起一套），走它定义的"全能参考模式六段式" 结构（subject_definitions → summary → retention_analysis → detailed_description → overall_soundscape → non_diegetic_music）。 实测通过的默认模板见 docs/todo/dressup-dance-room-mvcp.md M.15，两处 需要人工填空才能拼出合规 prompt（该规范要求人物特征必须具体，不能写 "如图所示"）：

  • 人物外观描述（发色/发型/服装颜色款式等 2-3 条具体特征）+ 衣服外观描述：分别对应人物图（<Picture 1>）和衣服图 （<Picture 2>）两张独立参考图，由管理员在录入人物/衣服素材时手写， 一次性录入、长期复用（已确认，见 6.1/6.2 节）——不需要视觉模型看图 生成，因为一步法下没有中间合成图可看。
  • 舞蹈动作描述（"拉丁风格摆胯+举臂旋转"这类具体动作文字）：参考 跳舞视频总量有限（后台预置的一个小集合），由管理员在上传参考视频 时手写一段短描述，一次性录入、长期复用（已确认，见 6.3 节）。

⚠️ S1 实测发现的一个副作用：产出视频里角色的鞋子是模型自己选的 （未指定时会自作主张配鞋），正式模板要显式规定鞋子处理方式，避免同一 角色不同视频里鞋子不一致。

4.3 双算力策略（已确认）

同一次生成，跑在两条不同的算力路径上，按"是否是付费实时请求"切换：

场景 算力 理由
冷启动/后台种子内容（admin 预先批量生成，铺满衣柜库/默认人物库的初始内容，不面向单个观众的实时请求） 内部 H3 Console（自建 GPU 集群） 免费、无按次成本，但单条（10 秒产物）约 700s，批量提前跑不受实时性压力，适合"不着急"的场景
观众付费实时请求（模式二付费传衣服、模式三付费传人物） fal.ai 云端（minimax/h3* 系列端点，/fal/* 反代已有雏形，见 app.js） 快得多（H3-CONSOLE.md 早期对比约 4s 级别 vs 内部集群同参数约 200s），付费用户对等待时间敏感，成本由用户支付的积分覆盖。注意：S1 的一步法/attribute_transfer 写法只在 H3 Console 上实测过，接入 fal.ai 时需要先复核同一套 prompt 技巧在 fal 的模型上是否同样成立，这是第五期要做的事，不阻塞第一～三期

即：免费内容靠自己的卡慢慢攒库存，付费内容花钱买 fal.ai 的实时速度。

4.4 视频规格：默认竖屏，移动端优先（已确认）

  • dance.html 生成的视频默认竖屏，与 live.html 各自维护独立的 H3_GEN_PARAMS 配置（第 2 节）——live.html 一侧后来也独立改成了 竖屏默认（docs/done 2.2 节），两边不是同一份配置，只是刚好选型 一致。
  • 默认分辨率 480×832——总像素量 ≈ 40 万，与早期横屏默认 832×480 完全一致（只是宽高对调），理论上不会因为竖屏化而拖慢生成耗时（H3 集群单条本来就约 200s，见 H3-CONSOLE.md，竖屏化不能再让这个数字 变得更差）。
  • 更高分辨率（576×1024/720×1280 等）画质更好，但会明显增加生成耗时， 不作为默认，可以作为后续付费选项预留（呼应第 7.2 节"新增资产才 消耗积分"的思路——高清可以是另一档付费能力，不是本期范围，先不做）。
  • 前端播放器/排版要跟着调整：dance.html 复用 live.html 的 CSS 风格 （2.1 节），但播放器容器要按 9:16 竖屏比例设计，不能直接套用 live.html 现有横屏播放器的宽高比，否则会出现大黑边——这是 dance.html 相对 live.html 除了"没有文字输入框"之外的第二个视觉 差异点。

4.5 失败/超时处理

  • 生成失败/超时：复用 v1 generateForPrompt 现成的重试/超时/持久化 套路（h3JobId/fal 任务 id 落盘，进程重启能续投）；付费请求的话退还 积分。

4.6 相同人物+衣服组合去重缓存（已确认，限模式一免费路径）

  • 模式一固定用同一个默认人物（2 节），衣服总量有限，多个观众大概率会 选中同一件——相同"人物+衣服"组合直接复用已有的生成视频，不重新 生成，直接把已有产物排入播放队列。
  • 目的：省 GPU/API 成本，也让免费入口的点播延迟大幅降低（命中缓存约等 于 v1 现有"素材库命中"那种秒级体验，见 docs/done 2.2 节）。
  • 缓存 key 是 (characterId, garmentId) 组合；命中判断在提交时做， 跟 v1 findLibraryMatch 的"先查库再生成"套路是同一个思路，只是匹配 维度从"文本相似度"换成"资产 id 组合"，实现上更简单可靠。
  • 模式二/三（付费路径）不做去重——每次付费传衣服/传人物本身就是 在新增独特资产，不存在"组合已存在"的情况。

5. 内容审核（已确认：自动黑名单 + 事后人工兜底，非强制先审后播）

  • 模式二（传衣服）：基础审核，复用/扩展 v1 关键词审核思路，但要能 过图片——需要图片内容审核能力（供应商待定，见第 8 节）。
  • 模式三（传人）：走自动化人脸识别黑名单过滤（比如过滤涉政人物 形象），不在黑名单里的人物照片自动通过、直接进入生成，不做强制 人工预审。风险兜底靠两层：
    1. 后台运营发现问题内容可以随时手工下架（第 6.5 节播放管理）。
    2. 新人物内容本身生命周期短——播完购买的那几个 10 秒片段就自动下线 （第 3.3 节第 7 点），把"有问题内容能公开曝光多久"这个风险窗口 天然限制住了，不需要靠"生成前卡审核"来兜底。
  • 无论哪种模式，最终生成内容仍会过 H3 Console / fal.ai 自身的生成时 安全策略兜底（docs/done 2.7 已有此保底），是最后一道防线，不是 唯一防线。
  • 人脸识别黑名单模型具体选型待定，见第 8 节。

5.1 年龄确认与免责声明（已确认）

  • dance.html 涉及付费、真人照片上传、可能包含泳装等服饰分类，且对外 公开——进入前要求勾选"我已满18岁"确认框 + 展示免责声明。基础年龄 确认，不做第三方实名认证（成本更高，暂不需要，见第 8 节留作后续 评估项）。
  • 免费模式一是否也要挂这道确认，还是只在涉及付费/传人操作时弹出： 建议统一放在 dance.html 首次进入时做一次性确认（跟现有 live.html 首次进聊天框弹昵称框的交互套路一致，见 docs/done 2.5 节），而不是 每个操作都弹一次。

6. 后台资产管理需求

在现有 admin.html（v1 素材表格）基础上，新增几类资产的管理页面/模块， 保持同一套"表格 + 行内编辑 + 新增表单"交互风格。

6.1 人物图片管理

  • CRUD：上传人物参考图、命名、打标签、设为"直播默认人物"。
  • 来源区分：admin_seed（后台预置/冷启动批量生成） vs user_paid（模式三付费上传）。user_paid 来源不进入"系统随机挑选 免费用户默认人物"的池子（3.3 节第 6 点），但需要能在后台看到、关联到 付费用户、追踪其"剩余可播 10 秒片段数"。
  • 「设为直播默认人物」开关：模式一/二里"系统指定"的人物来源于此。 第一期只允许同时有一个人物被设为默认（2 节已确认，不做多人物 轮换），开关设计上仍按"列表 + 单选"做，方便以后放开多选/轮换不用 改数据模型。

6.2 衣服物品管理

  • CRUD：上传衣服图、命名、分类/标签、缩略图、上下架开关。
  • 来源区分：admin_seed vs user_paid（模式二上传，审核通过后默认 沉淀进公共库，3.2 节第 3 点）。

6.3 参考跳舞视频/音乐管理

  • CRUD：上传参考跳舞视频（含配乐），命名、风格标签、时长、上下架开关。
  • 动作描述字段（已确认，4.2 节）：上传时管理员手写一段短描述具体 动作（如"拉丁风格摆胯+举臂旋转"），供 Stage2 prompt 模板拼装用， 一次录入、后续所有用到这条参考视频的生成都复用，不必每次重写。
  • 版权来源字段：当前先用测试素材占位（正式版权素材待确认，见第 8 节），后台需要能记录/后续批量替换。

6.4 生成后的视频管理

  • 扩展现有 admin.html 素材表格：新增 characterId/garmentId/ refDanceVideoId 列，追溯"谁的脸 + 谁的衣服 + 哪条参考跳舞视频" 生成的（一步法下没有中间合成图，不需要 composedImageId 列）。
  • 人工下架/加精；批量删除入口。

6.5 播放管理

  • 插播/置顶下一条、手动跳过当前、暂停自动填充、拉黑某个用户/资产（对接 第 5 节的人工兜底手段）。

7. 用户体系与积分（已确认）

7.1 用户注册

  • 起步方式：邮箱登录（账号+邮箱验证）。
  • 后续迭代：加 Google / Apple / GitHub 三方登录。
  • 现有 viewer_uid/viewer_nickname cookie 身份平滑绑定到账号，历史 投票/点播记录不丢（沿用 docs/structure/architecture.md 2.4 节的 过渡方案）。

7.2 积分模型

  • 充值 → 通用积分池，而不是"充值金额直接换算成固定数量的 10 秒 片段"——积分是通用货币，未来别的付费场景（比如优先排队）也能复用 同一套机制，跟原始需求里"未来消耗积分限制生成频率/质量"的说法一致。
  • 计费边界（已确认）：
    • 使用已有资产库（衣柜里选衣服、系统默认人物）—— 免费，不扣积分。
    • 新增资产（模式二付费传衣服、模式三付费传人物）—— 消耗积分。
    • 新增人物额外规则：消耗的积分数量决定该角色可播放的 10 秒片段数 （3.3 节第 3、7 点）；片段播完后角色下线但记录保留，用户可再充值 续播而不需要重新生成。
  • 具体每次操作扣多少积分、充值档位等数值，还没定（不阻塞开发，先把 余额+流水+配置化扣费额这套机制打好，数值上线前再定，见第 8 节）。
  • 失败退还：生成失败，已扣积分必须退还，不能出现"扣了积分但没生成成功 也不退"的黑洞。

7.3 充值支付渠道（已确认：Stripe，不需要预先锁定目标地域）

  • 接 Stripe。产品方已确认不需要在开发前锁定目标观众地域——Stripe 本身覆盖全球区域，积分系统设计成"内部余额+流水"，支付渠道只是"给 余额充值"的一个外部入口，换渠道/加渠道不影响积分模型本身，后续如需 补充支付宝/微信支付等本地渠道，直接加一个入口即可，不用推翻现有设计。

7.4 个人中心「我的作品」（已确认）

  • 付费生成的内容（模式二上传的衣服、模式三的新人物及其视频），即使 已经从直播排播/复用池下线（3.3 节第 7 点"到期处理"），用户仍要能在 自己的账号下单独查看/回放——不是"下线=消失"，只是"下线=不再出现在 公开直播间和其他人的衣柜/随机池里"。
  • 数据模型含义：生成的视频/换装图/人物记录要挂在 userId 下长期可查， 和"是否还在直播池中"是两个独立的状态维度（呼应 docs/structure/architecture.md 2.7 节"人物生命周期"里提到的 status: active|expired 设计，这里进一步要求 expired 状态下这些 记录依然可被拥有者检索，不是软删除后就不可访问）。
  • 具体页面/交互（列表、是否能重新分享到直播间等）留到对应分期再细化， 这里只确认"数据要保留、要能查"这个底线。

8. 待验证事项（不是产品决策分歧，是需要技术验证/调研才能定的点）

  1. Stage1 换装怎么做 —— 已实测确认（2026-09-02，S1 spike）： 路径 B（一步法）成立，Stage1 整段删掉。人物图 + 衣服图两张一起 放进 ref2va 的 reference_image_urls，六段式 prompt 里 <Picture 2> 标 attribute_transfer，配参考跳舞视频一次调用直接出换装跳舞视频， 四条验收标准（提交成功/人脸一致/换装正确/动作对得上参考视频）全过， 证据见 spike/s1-s2-s4-2026-09-02/RESULTS.md。composed_images 表、 Stage1 图片模型选型、图片去重缓存三项全部作废（MVCP 已同步删除 M.6，见该文档改动）。路径 A（Codex gpt-image-2 两步法）作为纯技术 储备保留在 CODEX-IMAGEGEN.md，但第一～三期不需要用它。
  2. H3 Console reference_video_urls 实测 —— 已实测确认 （2026-09-02，S2 spike）：这个字段真实生效，且效果强——同一份 reference_image_urls、同一句动作文字描述，只切换有无 reference_video_urls，产出的动作幅度/风格有明显可见差异（宽马步+ 甩臂过顶 vs 原地小幅度比心），不能只靠 motionDescriptor 文字描述 替代。证据见 spike/s1-s2-s4-2026-09-02/RESULTS.md。
  3. 参考跳舞视频/配乐正式素材来源：目前先用测试素材占位，正式版权 素材（自制还是购买授权）待确认，后台字段已预留（6.3 节）。
  4. 人脸识别黑名单模型选型：用什么模型/服务做"涉政等敏感人物"识别 过滤，需要调研候选方案。
  5. 积分具体数值：充值档位、每次新增衣服/新增人物扣多少积分、新 人物每个 10 秒片段的积分单价——机制已定（7.2 节），数值上线前再定。
  6. 支付网关选型 —— 已确认：接 Stripe，不需要预先锁定目标 观众地域，Stripe 本身覆盖全球区域（7.3 节）。后续如需补充支付宝/ 微信支付等本地渠道，直接加一个入口即可。
  7. "我的作品"页面的第三方实名认证需求：第一期只做"我已满18岁" 勾选式确认（5.1 节），是否需要更严格的第三方实名认证，看实际运营 风险再评估，不预设一定要做。
  8. 人物外观自动打标的视觉模型选型 —— 第一～三期不需要，推迟 到第四期：appearanceDescriptor（人物）/garmentDescriptor（衣服） 分别由管理员在录入人物/衣服素材时手写一次、长期复用（跟 motionDescriptor 完全同一套路，见 6.1/6.2 节和 MVCP M.3/M.4）—— 一步法下两者对应两张独立参考图 <Picture 1>/<Picture 2>，不再 拼接成一句。衣柜里的衣服全部来自后台录入或审核通过，模式一永远 走手写这条，不需要视觉模型；比让视觉模型去描述图片更稳定（看图 描述本身会出错）。只有用户自助上传的新资产（模式二的衣服、模式三 的人物照）没人手写，才需要自动打标，随第四期一起做。
  9. Stage2 默认 prompt 模板的机械验收 —— 已完成，且已按一步法 实测跑通：模板按 docs/h3skill.md §1.7 的 22 项清单写成并逐条核对 （MVCP M.15.1），2026-09-02 S1 spike 用真实调用验证了人脸/换装/动作 三项效果，不只是纸面合规。词数风险仍在：appearanceDescriptor/ garmentDescriptor 是管理员手写、长度可控，但拼装后仍应实测词数， 超限截断到 2-3 条特征。
  10. fal.ai 能否访问我们本地的上传图片（推迟到第四期）：注意这是 入站方向的问题——fal 需要可公网访问的 URL 才能拉到我们 uploads/ 里的图，内网部署下它够不着；下载 fal 的产物到服务器一直不是问题。 按第 1 条的决策，第一～三期全程不调用 fal（生成全部在自己的 2080Ti 上），这条到第四期模式二付费实时路径上线时再解决。注意 S4 spike 找到的 POST /v1/assets（H3-CONSOLE.md）只解决 H3 Console 这一侧，fal 是完全不同的服务，这条不能照搬：要么先 PUT 到 fal 自己的存储，要么给上传目录挂公网可读的临时签名地址，方案见 MVCP M.13。

9. 分期建议（不是承诺的排期，是依赖顺序参考）

任务粒度的拆分（第 0 期技术验证 + 第一期，含验收标准/工时/依赖图） 见 docs/todo/dev-plan.md。第 0 期已于 2026-09-02 跑完，S1/S2/S4 全过，一步法确认，Stage1 已删除——第一期可以直接开工。

  1. 第一期：后台先把「人物库 / 衣服库 / 参考跳舞视频库」CRUD 模块 搭出来，用内部 H3 Console 批量跑冷启动种子内容（4.3 节），验证一步法 生成流水线可行性（不接入付费/审核/账号）。
  2. 第二期：dance.html 上线（含首次进入的年龄确认+免责声明，5.1 节），接入「衣柜选衣服」免费模式（3.1 节）+ 相同人物+衣服组合去重 缓存（4.6 节），复用现有排播队列基础设施（此阶段全部免费内容仍按 v1 投票排序，还不涉及"付费插队"这条新规则）。
  3. 第三期：用户注册体系上线（邮箱登录），把匿名 cookie 身份绑定 到账号——账号是后面付费功能的前提，必须先落地。
  4. 第四期：积分体系（余额/流水/配置化扣费）+ 充值支付渠道接入 （7.3 节，先确认目标地域再选具体渠道），先上线免费换衣服 + 付费 传衣服（模式二），验证扣费/退还/公共库沉淀链路。
  5. 第五期：付费传人物（模式三）+ 自动人脸黑名单审核 + "购买 10 秒 片段数 / 到期下线 / 续播"这套人物生命周期管理 + 排播优先级改造（付费 新人物插队播放，见 3 节"共同后置流程"）+ 个人中心"我的作品"页面 （7.4 节），接入 fal.ai 实时算力路径（4.3 节）。