# 换装跳舞直播间 — 开发任务规划（第 0 期 + 第一期）

需求见 `docs/todo/dressup-dance-room.md`（下称"需求文档"），设计见
`docs/todo/dressup-dance-room-mvcp.md`（下称"MVCP"），现状基线见
`docs/done/live-channel-v1.md`。需求文档第 9 节给的是**依赖顺序参考**，
本文把它落到可以派活的任务粒度：每条任务给**验收标准**（能跑/能看的
东西，不是"完成了"），并标出哪些能并行、哪些必须等第 0 期结论。

工时是**粗估**，单位人天，按熟悉这套代码的一个人算，用来排先后不用来
考核。

---

## 0. 已确认的前提（写在最前面，避免执行时反复回头查）

- **第 0 期 S1/S2/S4 已于 2026-09-02 跑完，全部通过**，证据见
  `spike/s1-s2-s4-2026-09-02/RESULTS.md`。结论：**一步法（路径 B）成立，
  没有 Stage1**——人物图+衣服图直接进 H3 Console 的 `ref2va`，一次调用
  出换装跳舞视频，`reference_video_urls` 字段真实生效，素材上传走 H3
  Console 自带的 `POST /v1/assets` 端点（新发现，已补进 `H3-CONSOLE.md`）。
  下面第 1 节的 spike 描述保留作记录，**不用再执行**；第 2 节的任务表
  已按这个结论同步更新。
- **第一～三期全程不调用 fal.ai，不调用任何视觉模型，零按次成本。**
  视频生成全部在内部 2080Ti 集群（4 卡 × 22G，`H3-CONSOLE.md`）上跑，
  一次调用完成换装+跳舞，Codex `gpt-image-2` 两步法（路径 A）不再需要，
  `CODEX-IMAGEGEN.md` 降级为技术储备文档。
- `appearanceDescriptor`（人物）/`garmentDescriptor`（衣服）= `characters`/
  `garments` 两个**管理员手写**字段，分别对应 M.15 模板的 `<Picture 1>`/
  `<Picture 2>`，不拼接、不依赖视觉模型。
- 第一期不涉及：账号、积分、支付、审核、`dance.html` 观众端。**第一期
  唯一的用户界面是后台**。

---

## 1. 第 0 期：技术验证 spike ✅ **全部完成（2026-09-02）**

**目的**：用最小代价证伪三个假设，避免在错误的地基上写产品代码。
**产出物**：全部丢在 `spike/` 目录下，是一次性脚本，**不进产品代码**，
验证完把结论写回需求文档第 8 节即可。
**总工时**：约 3–5 人天，串行做也就一周内。**实际结果：S1/S2/S4 全过**，
证据和方法见 `spike/s1-s2-s4-2026-09-02/RESULTS.md`；S3（Codex 两步法）
虽然也验证通过但**没被采用**，因为 S1 直接过了，一步法更省事。下面各
spike 的原始描述保留作记录。

### S1 —— H3 一步法实测（最高优先，可能删掉整个 Stage1）✅ **过（2026-09-02）**

| | |
|---|---|
| **做什么** | 手工准备 1 张人物图 + 1 张衣服图 + 1 条参考跳舞视频（都传到一个 H3 能访问到的地址），按 MVCP M.15 模板改写成"一步法"版本（`<Picture 1>`=人物、`<Picture 2>`=衣服、`<Picture 2>` 在 `retention_analysis` 标 `attribute_transfer`），`POST /v1/videos` 提交，轮询取回 mp4 |
| **怎么验** | 人眼看 3–5 组不同人物×衣服的产出 |
| **验收标准** | ① 任务能提交成功、`partition` 落到 `ref2va`；② 产出视频里**人脸与人物图一致**；③ **身上的衣服确实换成了衣服图那件**；④ 动作跟参考视频对得上。四条全过 = 路径 B 成立 |
| **过了会怎样** | **Stage1、`composed_images` 表、图片模型选型、图片去重缓存全部删掉**，MVCP 的 M.6 整节作废，流水线从两段变一段 |
| **没过会怎样** | 走 S3（路径 A），Stage1 保留 |
| **工时** | 1 |
| **实测结果** | **四条验收标准全过**（job `eac9f8fe1c36`，10s/480×832/ref2va）。人脸大体一致（头发有轻微变长变蓬松的漂移，不是像素级复刻）；换装准确（红色旗袍金边侧开衩全部还原）；动作跟参考视频的 hip-hop 风格/幅度高度一致。**副作用**：产出角色的鞋子是模型自选的（黑色短靴），prompt 未提鞋子——跟 Codex 路径 A 遇到的"鞋子自作主张"是同一类问题，正式模板要显式规定鞋子处理方式。**结论：路径 B 成立，Stage1 删除**，MVCP 已同步（M.6 作废、M.13/M.15 重写）|

### S2 —— `reference_video_urls` 实测（Stage2 的地基）✅ **过（2026-09-02）**

| | |
|---|---|
| **做什么** | 单独验这个字段本身：固定一张参考图，只改 `reference_video_urls` 有/无，各提交一次 |
| **背景** | `H3-CONSOLE.md` 原话是这个字段"未实测，仅从控制台 UI tab 推断存在"。**整个 Stage2 设计、M.15 模板、`dance_refs` 表都建在这个推断上** |
| **验收标准** | ① 带 `reference_video_urls` 提交不报错；② 产出视频的**动作/节奏明显受参考视频影响**（跟不带的那条对比看得出差别）；③ 记录参考视频的时长/格式/分辨率限制（H13 说视频 ≤3 条、单段 2–15s） |
| **没过会怎样** | **设计级返工**：舞蹈动作只能靠 `motionDescriptor` 文字描述驱动，`dance_refs` 从"参考视频库"退化成"动作描述库 + 配乐库"，M.15 模板要去掉 `<Video 1>`/`<Audio 1>` 两个标签 |
| **工时** | 0.5 |
| **备注** | S1 天然覆盖了一部分（S1 也带参考视频），但 S1 一次改了两个变量，**这条要单独跑**才能定位问题出在哪 |
| **实测结果** | 单独做了 A/B：S1 用的 `reference_image_urls` 原封不动，`motionDescriptor` 文字也原封不动，唯一变量是去掉 `reference_video_urls` 和 prompt 里的 `<Video 1>`/`<Audio 1>` 两段（job `ecf3a02df7bd`）。**结果差异非常明显**——带参考视频那条是宽马步+甩臂过顶+比心的 hip-hop 能量感，不带的那条只是原地小幅度比手势，即使文字描述完全相同。**结论：字段真实生效，效果强到文字描述压不住**，`dance_refs`/`<Video 1>` 标签是必需项，不能退化成纯文字。参考视频限制沿用控制台 UI 的提示文案：最多 3 段、单段 2–15 秒、mp4、音轨自动带上，跟 H13 一致；本次只测了 4 秒 480×832，未测格式/分辨率边界 |

### S3 —— Codex `gpt-image-2` 多图编辑出换装图 ✅ **已完成（2026-09-01）**

**结论：路径 A 可用。** 两组换装实测全部通过——人脸/发型/体型/姿势/背景/
光线完全保持，服装细节（旗袍金边盘扣开衩、校服水手领红领巾百褶）准确转移，
尺寸精确 1024×1536，单张约 73 秒 / 2.3 万 token，走 ChatGPT 订阅额度无按次
费用。完整数据、调用写法和三个踩坑见 **`CODEX-IMAGEGEN.md`**。

**仍需补的一步**：实测用的是合成素材，**换真实拍摄的人物照/衣服图再抽查
一遍**（真实照片的光线和背景杂乱度更难），0.5 人天。

| | |
|---|---|
| **调用写法（实测可用）** | `codex exec --skip-git-repo-check -s workspace-write -o out.txt "$PROMPT" -i person.png -i garment.png`。**prompt 必须放在 `-i` 前面，且每个文件单独一个 `-i`** —— `-i` 是变长参数，写错会吞掉 prompt 或直接挂死 |
| **尺寸** | 用 `1024x1536` 或 `832x1472`，**`480x832` 是非法输入**（总像素低于 `gpt-image-2` 的 655,360 下限）；参考图不必等于视频分辨率。**尺寸要在 prompt 里单独一行明确写出来**，写含糊会漂 |
| **T7/T9 要注意** | ① prompt 里必须**显式规定鞋子怎么处理**，否则同批产出脚部不统一（实测两组一组保留原鞋、一组自作主张换了鞋）；② 一次 exec 生成多张比一张一次省 token（3 张 = 3.9 万 vs 单张 3 万）；③ 产物只落在 `$CODEX_HOME`，脚本必须自己搬到 `uploads/composed/` |
| **剩余工时** | 0.5（换真实素材抽查一遍） |

> **第五期的隐患，现在就记下**：这条通道适合冷启动（我们自己的素材/合成
> 人物），但模式三是**观众上传真人照片换装**，走 OpenAI 大概率被内容策略
> 拦。第五期可能仍要回到自己的 GPU。见 `CODEX-IMAGEGEN.md` 第 7 节。

### S4 —— 素材可达性 ✅ **过（2026-09-02），且找到比原计划更简单的方案**

| | |
|---|---|
| **做什么** | 确认 H3 Console 能拉到什么形式的素材 URL：局域网地址行不行、要不要公网、有没有大小/格式限制 |
| **为什么** | 决定 MVCP M.13 里 `uploads/` 目录怎么对外暴露；S1/S2 一上来就会撞到 |
| **验收标准** | 一句能写进文档的结论 + 一个可用的素材托管方式 |
| **工时** | 0.5 |
| **备注** | 跟 S1 一起做，S1 的第一步就是这个 |
| **实测结果** | 读 H3 Console 自己的前端 JS，发现一个**原来没记录在案**的端点：`POST {base}/v1/assets`（multipart，字段名 `file`），是控制台自己的文件选择器在用的上传接口，返回的 URL 保证 H3 后端能拉到（本机实测上传后该 URL 本机也能直接 curl 到 200）。**不需要给我们自己的 `uploads/` 目录挂公网签名地址**——图片/视频先落本地盘给自己的页面用，需要喂给 H3 时再转发一次到 `/v1/assets` 换 URL 即可。已补进 `H3-CONSOLE.md`，MVCP M.13 已按这个方案重写。fal.ai 的入站可达性（需求文档 8.10）不受此影响，那是完全独立的服务，仍推迟到第四期解决 |

### 第 0 期出口 —— **已选定：S1 过，一步法**

原计划三选一，写回需求文档 8.1，**实测结果是第一档**：

- ~~S1 过~~ → **一步法，删 Stage1（已选定，最省事的分支）**
- S1 挂 + S3 过 → 两步法，Codex `gpt-image-2` 出换装图 + H3 出片（未采用，S3 虽验证通过但用不上了）
- S1 挂 + S3 挂 → 退到路径 A'（同机 ComfyUI 自建图片编辑工作流，+2
  人天）；再不行才回头考虑 fal（那就得先解决 8.10 的入站可达性，且产生
  按次成本）

---

## 2. 第一期：后台三库 + 冷启动批量生成

**目标**（需求文档 9.1）：后台能管人物/衣服/参考视频三个库，能批量跑
出冷启动种子内容，全链路跑通。**不含**观众端、账号、积分、审核。

### 2.1 不等 spike，可立即开工（约 6 人天）

这几条不依赖第 0 期任何结论，**今天就能派**。

| # | 任务 | 验收标准 | 工时 |
|---|---|---|---|
| T1 | **三个 JSON 库的读写层**：`characters.json` / `garments.json` / `dance-refs.json`，沿用 `library.json` 现有的全量读写模式（架构文档 1.4 节明确第一期不迁 SQLite） | 三个文件能增删改查，进程重启数据不丢 | 0.5 |
| T2 | **图片上传接口**（MVCP M.13，按 S4 结论简化）：`POST` multipart → 落 `uploads/{yyyymm}/{uuid}.{ext}`，服务端按**真实文件头**判类型、重编码剥 EXIF、大小 ≤8MB；配套 `GET /uploads/*` 只读静态路由；另加一个内部小函数 `forwardToH3Assets(localPath)`，需要喂给 H3 生成任务时把本地文件转发到 `POST {H3_CONSOLE_BASE}/v1/assets`，换回 H3 能拉到的 URL（`H3-CONSOLE.md` 已补充该端点文档） | 传一张带 EXIF GPS 的 jpg，落盘后 `exiftool` 看不到 GPS；改扩展名伪装的 `.jpg`（实为 zip）被拒；>8MB 被拒；本地文件转发到 `/v1/assets` 后拿到的 URL 可直接 curl 到 200 | 1 |
| T3 | **`admin-characters.html`**（MVCP V.2 / C.2，6.1 节）：表格+行内编辑+新增，字段照 M.3，含 `appearanceDescriptor` 手写框和「设为直播默认人物」单选开关（置一条 true 时其余全置 false） | 能建人物、能改、能删；点两次不同人物的默认开关，全库始终只有一条 `isDefault: true` | 1.5 |
| T4 | **`admin-garments.html`**（M.4，6.2 节）：同上，含分类、缩略图、上下架开关、`appearanceDescriptor` 手写框 | 同上；下架的衣服不出现在后续衣柜接口里 | 1 |
| T5 | **`admin-dance-refs.html`**（M.5，6.3 节）：视频上传 + `motionDescriptor` **必填**校验 + 风格标签 + 版权来源字段（第一期全部 `test_placeholder`） | `motionDescriptor` 留空时提交被拒（它是 M.15 模板的必需输入，不能事后补） | 1 |
| T6 | **后台鉴权**（MVCP M.1 `role` + M.10 `sessions`）：给 `/api/admin/*` 加一道最小的管理员校验 | 无凭证访问任一 `/api/admin/*` 返回 401 | 1 |

> **T6：已确认要做。** 严格说账号体系是第三期的事，但第一期就要新建 5
> 个后台页面，全部零鉴权暴露（架构文档 1.2 节记的技术债），产品方已
> 拍板做最小可用的一道口子——单个管理员凭证 + session cookie，不做
> 注册/找回/多角色，等第三期账号体系上来再并进 `users` 表。

### 2.2 原"等 S1 结论后开工"，现已解锁，可以立即开工（约 4–6 人天）

S1/S2 已过（一步法确认，`reference_video_urls` 确认生效），下面的依赖
都已满足，不用再等。

| # | 任务 | 依赖 | 验收标准 | 工时 |
|---|---|---|---|---|
| T7 | **Prompt 拼装器**：读 `characters`/`garments`/`dance_refs` 三个手写描述字段，按 MVCP M.15 一步法模板拼出六段式 prompt（`<Picture 1>`=人物图、`<Picture 2>`=衣服图 `attribute_transfer`）；**拼完实测词数**，超限截断 `appearanceDescriptor`/`garmentDescriptor`（M.15.1）；**顺带把 S1 spike 发现的"鞋子自作主张"这条修进模板**，显式规定鞋子处理方式 | T1 | 给定三条素材，输出的 prompt 过 M.15.1 那张表的全部机械项；词数校验对超长输入确实会截断；prompt 里包含明确的鞋子处理指令 | 1.5 |
| T8 | **单条生成编排**：拼 prompt → 上传素材到 `/v1/assets`（T2）换 URL → `POST /v1/videos` → 轮询 → 落 `generated_videos`。复用 v1 `generateForPrompt` 现成的重试/超时/`h3JobId` 落盘套路（架构文档 2.5 节），**别重写** | T2/T7 | 提交一条，约 700s 后（10s 产物实测耗时，比 4s 产物的 200s 更长）`library.json` 里出现带 `characterId`/`garmentId`/`refDanceVideoId` 溯源字段的记录；生成中途重启进程，恢复后继续轮询同一个 job | 1.5 |
| T9 | **`admin-batch-gen.html` + 批量接口**（MVCP V.2/C.2/P.7.1）：勾选人物×衣服×参考视频 → 展开组合逐条入队 → 进度表；**已有 `generated_videos` 缓存（M.7 唯一索引）的组合默认跳过**；失败条目可单独重投 | T7/T8 | 勾 1 人物 × 5 衣服提交，进度表能看到 5 条各自的状态；杀掉进程再起来，队列不丢；重复提交同一组合被跳过 | 2 |
| T10 | **`admin.html` 扩展**（6.4 节）：现有素材表格加溯源列 `characterId`/`garmentId`/`refDanceVideoId`（**一步法下没有 `composedImageId`/合成图这一列**） | T8 | 后台能看出每条视频是"谁的脸 + 谁的衣服 + 哪条参考视频" | 0.5 |

### 2.3 第一期出口

- 后台能录入 ≥1 个人物、≥10 件衣服、≥3 条参考跳舞视频；
- 批量跑出 **≥30 条**冷启动视频，落进 `library.json` 且带全溯源字段；
- 人眼抽查：换装正确、动作跟参考视频对得上、10 秒、480×832 竖屏；
- 全程零 fal 调用、零按次成本。

达成后才进第二期（`dance.html` 观众端 + 免费衣柜模式）。

> **T1-T10 已于 2026-09-02 端到端实测（真实调用 H3 Console，非 mock）**：
> 1 人物 / 10 件衣服 / 3 条参考视频，批量生成 11 条真实视频（10 个不重复
> 人物×衣服组合，其中一条因去重缓存的时序问题重复生成了一次），落进
> `library.json` 全部带 `characterId`/`garmentId`/`refDanceVideoId` 溯源。
> 人眼抽查：换装正确、动作对得上、10 秒/480×832 全部通过；但 **11 条里
> 3 条鞋子从人物图的黑色短靴变成了光脚**，精确对应同一条参考视频（用
> S1 spike 的控制组素材顶的，那条视频本身就是光脚跳舞）——H3 会把参考
> 视频里演员的鞋子泄漏进结果，尽管 prompt 明确写了"参考视频只提供动作
> 节奏"。以后正式录参考跳舞视频要避开光脚素材。
>
> **"≥30 条"这一条尚未达成**——M.7 的去重缓存是按 `(characterId,
> garmentId)` 唯一索引的（跟用哪条参考视频无关），1 个人物只有 10 件
> 衣服的情况下，批量生成最多只能产出 10 条不重复视频，要凑够 30 条得
> 补到 30 件衣服。这是设计上的硬限制，不是运营没做够。
>
> 过程中发现并修复两个真实 bug（`a68fd8b`/`12aff60`）：T8 落库的换装
> 视频没标 `edited: true`，会被 `ingest.js` 每 5 分钟一次的库同步冲掉
> 溯源字段（还会漏进 `live.html` 的播放池）；生成任务轮询用固定次数
> 而非墙钟时间做超时判断，批量提交排队变长时会被误判失败——H3 的 4 张
> GPU 跑的是同一个模型分片，不是 4 个独立 worker，批量提交本质是排队。

---

## 3. 依赖关系

**下图是第 0 期开工前画的原始依赖图，S1–S4 现在全部是绿色（已完成）**，
留着是为了说明"当初为什么这么排"，实际现在可以直接从 T1–T10 一起排起。

```mermaid
flowchart TD
  S4[S4 素材可达性] --> S1[S1 一步法实测<br/>最高优先]
  S4 --> S2[S2 reference_video_urls 实测]
  S1 -->|挂| S3[S3 gpt-image-2 出换装图]
  S1 -->|过| T7
  S2 --> T7[T7 Prompt 拼装器]
  S3 --> T7

  T1[T1 JSON 读写层] --> T3[T3 人物库后台]
  T1 --> T4[T4 衣服库后台]
  T1 --> T5[T5 参考视频库后台]
  T2[T2 图片上传] --> T3
  T2 --> T4
  T6[T6 后台鉴权] -.保护.-> T3

  T7 --> T8[T8 单条生成编排]
  T8 --> T9[T9 批量生成后台]
  T3 --> T9
  T4 --> T9
  T5 --> T9
  T8 --> T10[T10 admin 溯源列]

  classDef spike fill:#fff3cd,stroke:#d39e00
  classDef ready fill:#d4edda,stroke:#28a745
  class S1,S2,S3,S4 spike
  class T1,T2,T3,T4,T5,T6 ready
```

绿色 = 不等 spike 可立即开工；黄色 = 第 0 期验证。

**关键路径是 S4 → S1 → T7 → T8 → T9**，约 6 人天；T1–T6 那 6 人天可以
完全并行掉，所以第一期的实际墙钟取决于有几个人。

---

## 4. 明确不在第一期范围

避免执行时范围蔓延：

- `dance.html` 观众端任何部分（第二期）
- 用户注册/登录/`sessions` 完整实现（第三期；第一期只做 T6 那道最小口子）
- 积分、支付、`pricing_config`、退款（第四期）
- 图片内容审核、人脸黑名单（第四/五期）
- 付费插队排播、人物生命周期/配额（第五期）
- fal.ai 任何调用，以及 MVCP M.13 里 fal 入站可达性那条（第四期）
- 视觉模型自动打标（第四期，见需求文档 8.8）