docs: LTX2.3 数字人工作流(Comfy Cloud)设计 spec

用官方模板 video_ltx2_3_id_lora(LTX2.3 身份保持+音频驱动)做 Pixelle comfy/ 数字人工作流,
经 comfy-cloud 适配器执行。模型/节点已验证在 Comfy Cloud 托管齐全。
comfykit _meta.title 标记注入(image/audio/prompt)。硬依赖:用户导出 API 格式 JSON。

Co-Authored-By: Claude <noreply@anthropic.com>

docs/superpowers/specs/2026-06-18-ltx2-digital-human-workflow-design.md

@@ -0,0 +1,83 @@
+# LTX2.3 数字人工作流(Comfy Cloud)设计
+
+日期:2026-06-18
+分支:`feat/comfy-cloud-adapter`
+状态:已通过 brainstorming,待落实现计划
+
+## 背景
+
+Pixelle 数字人(说话头像)能力原先只有 RunningHub 形态(`runninghub/digital_*.json` 是
+`{"source":"runninghub","workflow_id":"..."}` 指针,非 ComfyUI 节点图,无法在 Comfy Cloud 跑)。
+为让数字人走 Comfy Cloud,采用官方 ComfyUI 模板 `video_ltx2_3_id_lora`(LTX2.3 身份保持
+LoRA + 音频驱动),把它做成 Pixelle 的 `comfy/` 工作流,经已建好的 comfy-cloud 适配器执行。
+
+可行性已验证(查 Comfy Cloud `/object_info` 3548 节点 + 模型池):
+- 模型齐全:`ltx-2.3-22b-dev-fp8`、`ltx-2.3-id-lora-talkvid-3k`、`gemma_3_12B_it_fp4_mixed`、
+  distilled LoRA 均托管;另有 `ltx-2.3-22b-ic-lora-lipdub-0.9` 口型 LoRA。
+- 节点齐全:LTX2.3 音视频节点(LTXVReferenceAudio/LTXVConcatAVLatent/LTXVAudioVAEDecode 等)
+  全在 Comfy Cloud 节点集中。
+- 模板 I/O = LoadImage(肖像)+ LoadAudio(旁白)+ 文本 → SaveVideo(带音频说话视频),
+  正好匹配数字人。
+
+## 已确认决策
+
+1. 用官方模板 `video_ltx2_3_id_lora`(LTX2.3),不自拼 InfiniteTalk(官方模板天然 Comfy-Cloud
+   兼容、模型已托管、风险低)。
+2. 接入方式:comfy 通道 + 节点图注入(放 `comfy/digital_ltx2.json`,经适配器),不走 RunningHub、
+   不另做独立入口。
+3. comfykit 注入机制:节点 `_meta.title` 标记(`$~image!` / `$~audio!` / `$prompt!`)。
+4. 分支 `feat/comfy-cloud-adapter`(与 comfy-cloud 适配器同分支,属同一能力线)。
+
+## 前置依赖(硬依赖)
+
+**需要用户从 Comfy Cloud 导出 API 格式 JSON**:模板当前是 UI 格式(含 subgraph 子图),
+`/api/prompt` 要求 API 格式(`{node_id:{class_type,inputs,_meta}}`)。子图必须展开。
+用户操作:Comfy Cloud 网页打开模板/share → Workflow → Export (API Format) → 放服务器
+(如 `/tmp/ltx2_api.json`)。服务端无法代取(需登录态)。
+
+## 架构
+
+```
+Pixelle 数字人流程
+  生成肖像图(image_path)+ TTS 旁白(audio_path)+ 脚本文本
+       │  comfykit 按 _meta.title 标记注入到 LoadImage/LoadAudio/文本节点
+       ▼
+comfy/digital_ltx2.json (API 格式 + 标记)
+       │  comfyui_url = http://<boosapi>/comfy-cloud
+       ▼
+Comfy Cloud /api/prompt → LTX2.3(id-lora-talkvid + 可选 lipdub)→ 带音频说话视频
+       ▼
+SaveVideo 产出 → 适配器 /view 取回 → Pixelle HTML 模板合成
+```
+
+## 工作流改造(实现步骤)
+
+基于用户导出的 API-format JSON:
+1. `LoadImage` 节点 → `_meta.title = "$~image!"`(必填、媒体上传)
+2. `LoadAudio` 节点 → `_meta.title = "$~audio!"`
+3. 文本提示节点(PrimitiveStringMultiline / CLIPTextEncode)→ `_meta.title = "$prompt!"`
+4. `SaveVideo` 已知输出节点,自动识别,不标记
+5. 删除 `RecordAudio` 节点(UI 录音交互,服务端不需要)
+6. 成品写 `data/workflows/comfy/digital_ltx2.json`(宿主持久化,经 `./data` 挂载)
+7. 参数名(image/audio/prompt)与 Pixelle 数字人 pipeline 实际传入键对齐:实现时读
+   `pixelle_video/pipelines/asset_based.py` 确认确切键名,不一致则调整标记名。
+
+## 验证
+
+- 校验探测:`POST /comfy-cloud/prompt`(body 为改造后 `{prompt:节点图}`)→ 期望
+  `node_errors:{}` + 返回 prompt_id(不跑完整数字人流程,先验证节点+模型全兼容)。
+- 真实验证:Pixelle 数字人任务选 `comfy/digital_ltx2.json`,出片确认。
+- 错误处理沿用适配器:节点不支持→400 透传;模型缺失→校验错误透传;执行失败→job failed。
+
+## 非目标
+
+- 不改 comfy-cloud 适配器代码(已完成且验证)。
+- 不做多人对话(multi-speaker)数字人,先单人肖像。
+- 不在 Comfy Cloud 上自训/上传新模型,只用已托管模型。
+- 不做 RunningHub 数字人的迁移/替换(保留并存)。
+
+## 提交约定
+
+分支 `feat/comfy-cloud-adapter`,工作流文件 + 任何 Pixelle 侧配置分开提交,中文 commit。
+注:工作流文件落在 Pixelle 宿主目录(`/opt/Pixelle-Video/data/workflows/comfy/`),不在
+BoosAPI 仓库内;若需纳入版本管理另议。