AI 短剧频道 v1 —「文字点播」直播间（已完成）

状态：已上线运行（server.js + live.html，pm2 进程 minimax-live）。 本文档记录当前已实现的需求范围，作为后续「换装跳舞直播间」（见 docs/todo/dressup-dance-room.md）改造的基线参照。

1. 产品概述

一个 7x24 播放的虚拟直播间。所有观众看到同一个「虚拟播出时刻表」 （server 端统一计算的播放进度，非各自独立播放），可以：

• 直接观看正在播放的 AI 生成短视频（文字弹幕点播 + 随机填充）
• 在聊天区发一句话 → 命中素材库则很快排入播放；不命中则提交给 H3 后台生成新片段，生成完成后排入播放
• 给候选片段投票，得票最高的优先播出
• 浏览「最新 / 最早 / 最热」三种非直播的素材库列表，任意点播

2. 已实现的核心能力

2.1 虚拟播出时刻表（直播的核心机制）

• server.js 维护内存中的 schedule（[{clip, startAt, endAt, requestedBy}]）， 每 2 秒 tick 一次（ensureSchedule），始终保证时刻表填充到「未来至少 FILLER_DURATION_MS（30s）」。
• 选片优先级：投票最高的「已生成待播」（ready）> 投票最高的「素材库命中」 （matched）> 素材库随机填充（避开上一条、避开 20 分钟内播过的，两者都 没有时退化为纯随机，保证时刻表永不断流）。
• 所有观众通过轮询 GET /api/live/state（4s 一次）拿到同一份 {current, upNext, queue}，前端用「服务端 endAt 减本地时间」精确定时 切下一条，轮询只作为纠偏/兜底，不是切片的唯一触发点。
• 状态持久化到 live-state.json，进程重启后从中恢复，不会冷启动断播。

2.2 文字点播驱动生成

• 观众聊天发送文本 → 先做违禁词审核（moderateText，子串黑名单，非语义 审核）→ 通过后 submitPromptToQueue：
  • 命中素材库（中/英文 prompt 精确或子串匹配）→ 直接进入待播队列 （status: matched）。
  • 未命中 → 调用 H3 Console POST /v1/videos（文生视频，480x832 竖屏/ 120帧/20步——第一期默认横屏 832x480，后改为竖屏移动端优先，见 commit 1dc7084）异步生成，status: generating，生成完成后自动 写入 library.json 并推入待播队列（status: ready）。存量片段 保留生成时的原比例，播放器 object-fit: contain 兼容混合比例。
• 生成是完全后台化的（H3 自建集群单次约 200s），绝不阻塞直播时刻表或 HTTP 响应。
• POST /api/prompt 是同一条提交路径的非聊天版本（供测试/直接调用）。

2.3 排队投票

• POST /api/queue/vote/:id：按 uid（cookie）对某条排队中的 matched/generating/ready 条目投票/取消投票，票数决定谁先播（2.1）。

2.4 素材库浏览模式

• 三个 tab：最新 / 最早 / 最热（GET /api/library?sort=），点击任意条目 立即播放，播完自动顺延下一条（ended 事件），与直播模式的时刻表机制 完全独立。

2.5 观众身份

• 首次进聊天框（focus 触发，不需要先点发送）弹昵称输入框，生成 uid（crypto.randomUUID）+ nickname，写入 cookie（365 天）。
• 顶部常驻「昵称 ✎」可随时改名，uid 不变（投票/点播历史不丢失）。
• 无正式账号体系——身份完全基于浏览器 cookie，换设备/清 cookie 即视为 新观众。这是 v2 用户注册需求要解决的缺口，见 docs/todo。

2.6 在线人数

• 每次 /api/live/state 轮询带 cid（随机 clientId，非 cookie，纯前端 内存变量）打点到 viewers: Map<cid, lastSeenAt>，12s 内有心跳视为在线， 服务端返回 watching 计数。

2.7 内容审核 / 限流

• 审核：仅关键词黑名单（BANNED_WORDS），非语义级别；生成内容本身的 安全检查依赖 H3 Console 自身的生成时安全策略（被拒会以「生成失败」 形式体现在队列里）。
• 限流：按 IP，5 分钟内最多 3 次聊天/点播提交（RATE_LIMIT_MAX/WINDOW_MS）。 无账号维度限流。

2.8 后台管理（admin.html）

• 表格形式管理 library.json：搜索（名称/prompt/id）、按来源筛选 （h3console / manual）、任意列排序、行内编辑、删除。
• 「新增」表单可手动挂载一条外部视频地址（source: manual）的素材， 不经过 H3 生成。
• 编辑/新增会置 edited: true，让后续自动同步（2.9）不覆盖人工修改。
• 删除一条 h3console 来源的素材，会级联调用 H3 Console 的 DELETE /v1/videos/:id（移入 H3 自己的回收站），避免下次同步又冒出来。
• 无鉴权——admin.html 和所有 /api/admin/* 接口对能访问到该端口的 任何人开放，依赖网络边界（内网/反代）而非应用层鉴权。

2.9 与 H3 Console 的集成

• ingest.js 的 syncLibrary()：启动时 + 每 5 分钟，从 H3 Console 拉取 全量 job 列表重建 library.json（规则提取短 prompt，过滤基础设施 烟雾测试 job，保留 likes，跳过 edited: true 的条目）。这让直接在 H3 Console 网页端产出的内容，5 分钟内自动出现在直播间素材库。
• 视频本体不落本地盘：GET /lib/video/:id 服务端代理转发 H3 Console 的 /v1/videos/:id/file（H3_CONSOLE_TOKEN 不下发到浏览器）；若素材有 videoUrl（manual 来源或管理后台设置过）则 302 跳转到该地址。
• 详细 API 契约见 H3-CONSOLE.md（H3 Console 是独立于本项目的内部服务， 4 卡 GPU 单节点，无按次计费）。

3. 数据模型（现状）

library.json（数组，逐条追加，无数据库）：

{
  "id": "19c6b745a68e",          // h3console: H3 job id；manual: manual-<ts><rand>
  "source": "h3console",          // "h3console" | "manual"
  "edited": false,                // true = 后台改过/手动新增，同步时跳过重建
  "prompt": "...",                // 展示用短 prompt（中文）
  "promptEn": "...",              // 可选，英文短 prompt
  "fullPrompt": "...",            // 完整生成 prompt（H3 结构化 prompt 或用户原话）
  "videoUrl": "...",              // 可选，外部视频地址（manual 或后台改过播放源）
  "width": 480, "height": 832,     // 当前默认竖屏；早期/存量片段可能是 832x480 横屏
  "duration": 5,                  // 秒
  "partition": "text",            // text | ref2va | fl2va | manual
  "likes": 0,
  "lastPlayedAt": 1788250666831,  // 可选，用于播出冷却
  "createdAt": 1788250666831
}

live-state.json：{ schedule, promptQueue, chatMessages }，结构见 server.js 顶部注释，逐 tick 全量覆写。

4. 已知限制（未做的事，供 v2 参考）

• 无正式用户账号（仅 cookie 身份）、无积分/消费体系。
• 素材类型单一：只有「生成好的视频片段」，没有可复用的「人物」「服装」 「参考动作/音乐视频」这类结构化中间资产——每条素材都是一次性的最终 产物，无法组合复用。
• 生成路径只有「纯文字 → H3 文生视频」一条，没有「参考图/参考视频驱动」 的生成路径（H3 Console 本身支持 ref2va/fl2va，但本项目尚未从 /api/prompt、/api/chat 之外的路径调用过）。
• 无人工审核队列，内容一旦生成完成即自动排入公开播放，无「先审后播」 开关。
• 无任何鉴权，管理后台和写接口都是「网络可达即可操作」。