dev-plan.md
16.7 KB
换装跳舞直播间 — 开发任务规划（第 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）上跑， 一次调用完成换装+跳舞，Codexgpt-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 观众端 + 免费衣柜模式）。
3. 依赖关系
下图是第 0 期开工前画的原始依赖图，S1–S4 现在全部是绿色（已完成）， 留着是为了说明"当初为什么这么排"，实际现在可以直接从 T1–T10 一起排起。
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）