三渲二全链路现状与剩余缺口

[johnnyzhang-eng]

背景

三渲二的后端在 main 上已经完整：五个端点（master-precheck / GET / build / approve / discard）都在 openapi.json 里，图生 3D、自动绑骨、本地出帧三个 provider 都有实现，#192 已关闭。

但这条路线现在用户够不到，也无法证明它端到端可用。缺口散在 #192 的未勾子项、#518、#714 三处，没有一处能看到全貌。本 issue 把全链路的现状拉成一张图，并把剩余缺口收敛成可认领的条目。

链路现状

flowchart TD
    A["母版<br/>preview_url"] --> B["master-precheck<br/>零成本"]
    B --> C["build<br/>图生 3D · 20 积分"]
    C --> D{"人工确认闸<br/>awaiting_review"}
    D -->|approve| E["自动绑骨<br/>10 积分"]
    D -->|discard| C
    E --> F["model_3d_url<br/>落 CharacterOutfit"]
    F --> G["出帧<br/>node + Playwright"]
    G --> H["交付序列帧"]

    UI["前端入口"] -.->|缺| C
    UI -.->|缺| D
    RIG["骨架规范 + 挂点"] -.->|无落点| F
    GEO["逐帧几何量<br/>位移轨 · 时长 · 图集"] -.->|无落点| H

    classDef done fill:#e8f5e9,stroke:#2e7d32
    classDef gap fill:#fff3e0,stroke:#e65100,stroke-dasharray:4 3
    class A,B,C,E,F,G,H done
    class UI,RIG,GEO gap
    class D done

Loading

绿色 = main 上已有实现并部署；橙色虚线 = 缺口。

缺口

按「挡不挡得住验收」排，不按工作量排。

一、用户够不到（#518，已重开）

前端只有 render3dReady = Boolean(outfit.model3dUrl) 这一个只读判断，用来把三渲二按钮置灰并提示「需先建 3D 模型」。buildOutfitAsset / approveOutfitAsset / discardOutfitAsset 在整个 frontend 零调用，只有 entities 层的契约与测试桩。

即用户看得到提示，但没有入口去建。#192 的验收 1「从一张母版图出发……全程不手工介入」因此无法演示。

二、骨架规范与挂点无落点（#192 子项，未勾）

CharacterOutfit 现在只有 id / name / description / preview_url / model_3d_url。#121 要的「GLB + 骨架规范 + 挂点」里后两项没有字段。

后果不是少个功能：这段派生工作是每造型一次性的，产物要被该角色所有后续动作复用。无处存放就等于每补一个动作都重跑图生 3D + 绑骨，直接抹掉这条路线相对 i2v 的成本优势。#192 的验收 2「同一角色的第二个动作不再产生任何按次计费调用」目前证明不了。

三、逐帧几何量装不下（#192 子项，未勾）

SequenceGeometry 只有 canvas_w / canvas_h / anchor_x / anchor_y / foot_y。#81 要的位移轨（root motion）、逐帧时长、图集三项没有落点。引擎侧播放需要它们。

四、出帧仍在 worker 内起 Chromium（#714，PR #717 待评审）

docker-compose.yml 的 worker 仍是 target: runtime-render3d。应用机 4 核无 GPU，出帧只能走 SwiftShader 软件光栅，实测峰值需要 7.6 个核。PR #717 已把出帧改到用户浏览器并验过逐帧一致（最差一帧差 37/3,932,160 像素），等评审。

五、三条质量缺口（#192 子项，未勾；本 issue 不解，只登记）

• 正面细节糊：图生 3D 的自动 UV 展开把网格切成上千碎片，信息在那一步就丢了，换材质/加光照/提贴图分辨率都救不回来。解法是正面投影烘焙。
• 头发是刚体：自动绑骨按人形骨架把发壳蒙皮到头骨上。这是结构性的，不是偶发，要的不是修复而是路线分工判据——哪类角色和动作走三渲二、哪类必须走 i2v。
• 非人形漏认肢体，整幅指标看不见：实测四足角色仍差一条被遮挡的后腿，那条肢体每帧同姿势，而 motion_scale、死帧数、loop_seam、帧数时长成色全部正常，一道闸都不会红。需要逐肢体识别率指标。

范围

本 issue 只负责把缺口收敛成清单并给出优先级，不在此实现。一、二、三分别另开 scoped issue 由 PR 关闭；四已有 #714 / PR #717；五登记为已知限制，解法各自另议。

不包含

• 单帧画质优化（这条路线的定位是多朝向与一致性，不是单帧质量）
• 导出产物与引擎适配（见 导出产物契约与 Cocos 适配（Refs #37 §3.9） #94）
• 动作方向一致性的自动判定（现有实验模块实测不可靠）

验收

• 一、二、三各有对应的 scoped issue，且都挂 MS4
• 前端能从母版走完 precheck → build → approve → 出帧，全程不手工介入
• 同一角色的第二个动作不产生任何按次计费调用（有 gateway_attempt 台账为证）
• 五里的三条在文档中被显式标为已知限制，不再被当成偶发缺陷重复排查

[johnnyzhang-eng]

2026-08-28 更新：③ 落库与 ④ 出帧今天都在生产跑通了，本 issue 开头列的「一次都没成功过」不再成立。

③ 落库（造型 character-110/outfit-default）

② 绑骨   JobId=1484856283097718784 → 落点 fmt=FBX
③ state=ready
   model_3d_url  = media.windup.xin/media/model-3d/8034ccda…fbx
   character_data 里同一个 URL
   rigged_motions = {'walk': …}

这一次能过是上游那阵下载故障自己恢复的，不是我们修好的。根因另开了 #884。

④ 出帧（task 761，8 帧 1536×2560 east）

用真浏览器（Playwright + Chromium，WebGL swiftshader）驱动完整链路：

spec      clip=walk  frames=8  material=cel  min_coverage=0.005
片段      ["Armature|32795ddb…_remap"] → resolveClip 兜底命中（只有一个片段就用它）
交帧      8/8 全部 200，received 递增到 8
complete  200「帧已交齐,继续后处理」
骨 28 · 蒙皮 1 · 顶点 45 万 · 根骨 root
任务终态  completed，8 个 action-frame PNG 已进对象存储

在此之前 ④ 从没成功过的原因不是它坏了，是出帧在用户浏览器里跑（#714 决定不在应用机起 Chromium），而从来没有人开着标签页走完过一次。同一个造型不挂浏览器的对照就在 task 760：900 秒后 浏览器出帧超时(900s 未交帧)，失败路径本身是对的。

剩余缺口

• 出帧台的等待窗口是硬编码的 RETRY_DELAYS_MS = [800,1600,3200,6000,8000]，合计 19.6 秒就 return false，而服务端 deadline 是 900 秒。队列一堵浏览器就放弃，而且是静默的（返回 false 不报错），之后只能靠用户碰巧刷新页面触发 resume() 重挂。两个数字应该对齐。
• 手机 WebGL 起不来时没有任何兜底，也没有提示。这条是 feat(render3d): 出帧交给用户浏览器，worker 不再装 Chromium #714 的有意决定，要改得另找机器。
• 绑骨提交成功之后的任何失败都让已扣的费作废：JobId 只进日志，fetch() 零调用方 #884：绑骨提交成功之后的失败仍让已扣的费作废（PR fix(render3d): 绑骨提交后的失败可零成本续取 #885 待合）。

[johnnyzhang-eng]

2026-08-29 收口。本 issue 开时列的缺口已全部消掉，关闭。

端到端跑通（第二次，且这次是从建项目开始的完整链路）

建项目 210 → 上传用户自己的角色图（正面 T-Pose）→ 建角色 154，图直接设为母版
→ 图生 3D  14.0MB  云到云=True
→ 人工确认闸 → 放行 → 绑骨 28 骨
→ 浏览器出帧 12/12 → 后处理 → task 883 completed

全程约 5 分钟，一次没卡。12 帧亮度 140.0–140.4，无黑帧。

这一轮补掉的缺口

缺口	修复
出帧从未在生产成功过	已跑通两次（task 761 / 883）
绑骨提交后失败让已扣的费作废	#885 断点续取
用户得自己知道要写 T-Pose	#904 系统自动转，且用能证伪的量验（宽高比须涨 1.15 倍）
一个造型只出得了走路	#916 rigged_motions 没过 MQ，已补
第 0 帧是纯黑剪影	#918 渲第一帧前 compileAsync + 亮度闸
上传的图不能当母版	#908 母版节点把它列为候选
先传图会丢图	#907（PR #923 待合）
建完资产下游看到旧快照	#900
多视图与建模参数用不到	#898

仍然开着的，各自单独跟踪

• [Proposal]: 工作流拓扑是照视频路线定的，三渲二被迫先买一张用不上的首帧 #901 工作流拓扑：三渲二被迫先买一张用不上的首帧（方案已定稿）
• 三渲二按 i2v 的整价收 50 积分，而它的上游调用数是 0 #890 三渲二按 i2v 整价收费，而它的上游调用数是 0
• [Bug]: 出帧台只等 19.6 秒就静默放弃，服务端却等 900 秒 #889 出帧台等待窗口 19.6 秒 vs 服务端 900 秒
• [Bug]: 腾讯从我们的域名取模型成功率低，云到云不是优化而是可靠性问题 #883 云到云是可靠性问题不是优化（当前实际都走到了云到云，但过期退回中转那条路仍不稳）