# 数字人接入 Comfy Cloud 视频工作流(完整视频入口)设计

日期:2026-06-18
分支:`feat/comfy-cloud-adapter`
状态:已通过调查,待用户复审

## 背景

LTX2.3 说话头像工作流(`comfy/video_digital_ltx2.json`)已就绪并通过 Comfy Cloud 校验
(节点+模型全兼容,probe `node_errors:{}`)。但 BoosAPI 数字人 UI 没有「视频/动画工作流」
入口,无法触发「肖像图 + 旁白音频 → 说话视频」这一步。本设计补齐贯穿三层的入口。

## 现状(调查结论)

- **BoosAPI 数字人前端 `src/web/pages/DigitalHuman.tsx`**:仅 3 个选择器——ttsWorkflow、
  imageWorkflow(从 mediaWorkflows 选,默认含 "image" 的)、frameTemplate(HTML 模板)。
  **无视频/动画工作流选择器**。流程是「生成图片 + TTS + HTML 模板合成」,不做说话头像动画。
- **BoosAPI 后端 `src/routes/digital_human.rs`** 的 `pixelle_request_body`(~line 2053):转发
  text/mode/title/backend_provider/workflow_source/n_scenes/video_fps/frame_template/
  template_params/prompt_prefix/bgm_*/media_workflow/tts_workflow/ref_audio。
  **不转发 `api_video_workflow`**;`workflow_source` 写死 `runninghub`/`selfhost`(无 comfy)。
- **Pixelle `pixelle_video/pipelines/asset_based.py`**(~line 693):动画步读
  `context.request.get("api_video_workflow")`;`audio_path` 仅当 `_get_api_workflow_info`
  (查 `api_media`,只 `api/` 通道)匹配到 `audio_driven_i2v` 能力时才注入 → **comfy 工作流
  拿不到 audio_path**。
- **Pixelle 工作流执行按前缀路由**:`runninghub` 走 RunningHub,其余(含 `comfy/`)走
  `comfyui_url`(= BoosAPI `/comfy-cloud` 适配器)。`comfy/video_digital_ltx2.json` 已在
  `/workflows/media` 列出(已加 `video_` 前缀)。
- 已完成的前置:comfy-cloud 适配器(已验证)、`comfy/video_digital_ltx2.json`(标记
  image_path/audio_path/prompt,probe 通过)、media.py 转发 image_path(已打补丁)。

## 已确认决策

1. 加完整视频入口:前端选择器 + 后端转发 + Pixelle 音频注入,三层都改。
2. 视频工作流选择器列 `video_*` media 工作流(含 `comfy/video_digital_ltx2.json`)。
3. 单人肖像说话头像;不做多人。

## 三层改动设计

### 层 1:前端 `src/web/pages/DigitalHuman.tsx`
- 新增 state `apiVideoWorkflow`(默认空=不启用动画,保持现有「图片+HTML」行为向后兼容)。
- 新增「视频工作流(可选)」`<select>`:选项 = `mediaWorkflows.filter(name 含 "video")`,
  含空选项「不生成视频(仅图片合成)」。
- 提交 payload 增加 `apiVideoWorkflow` 字段;draft 持久化同步。

### 层 2:BoosAPI 后端 `src/routes/digital_human.rs`
- `pixelle_request_body` 增加:
  ```rust
  if let Some(value) = optional_string(body, &["apiVideoWorkflow", "api_video_workflow"]) {
      request_body["api_video_workflow"] = json!(value);
  }
  ```
- 若所选视频工作流以 `comfy/` 开头,确保 `workflow_source` 不会阻断(comfy 工作流靠前缀
  路由,workflow_source 主要影响 media/tts 默认通道;api_video_workflow 独立按前缀执行,
  无需改 workflow_source。实现时验证不冲突)。
- 可选转发 `api_video_params`(若前端给了音频驱动等参数)。本期最小化:只转发 api_video_workflow。

### 层 3:Pixelle `pixelle_video/pipelines/asset_based.py`
- 动画步注入 `audio_path` 的条件放宽:除 `api_media` 能力匹配外,**当 `api_video_workflow`
  以 `comfy/` 开头时,也注入 `audio_path = frame.audio_path`**(comfy 工作流的 `$~audio_path!`
  标记需要它)。最小改动:在 `audio_driven_i2v` 判断旁边加 comfy 前缀分支。
- 镜像内置文件,改后重启容器,备份到 `/opt/Pixelle-Video/patches/`。

## 数据流(目标)

```
DigitalHuman.tsx: 选 comfy/video_digital_ltx2.json (apiVideoWorkflow)
  → BoosAPI digital_human.rs: request_body.api_video_workflow
  → Pixelle /api/video/generate/async: context.request.api_video_workflow
  → asset_based.py 动画步: 注入 image_path(media.py已补)+ audio_path(本期补)+ prompt
  → media() comfy 前缀 → comfyui_url=/comfy-cloud 适配器 → Comfy Cloud LTX2.3
  → 说话视频 → 帧合成/HTML 模板 → 成片
```

## 验证

- 前端 typecheck:`npm run typecheck:web`。
- 后端构建:`cargo build -j 2`。
- Pixelle 改动:语法校验 + 重启 healthy。
- 端到端:数字人任务选 `comfy/video_digital_ltx2.json`,确认 Comfy Cloud 出现 job、
  注入了 image_path+audio_path、出说话视频。

## 非目标

- 不改 comfy-cloud 适配器(已完成)。
- 不做多人对话数字人。
- 不重构数字人现有「图片+HTML 合成」路径(视频入口为可选叠加,默认不启用,向后兼容)。
- 不动 RunningHub 数字人路径。

## 提交约定

分支 `feat/comfy-cloud-adapter`。前端、BoosAPI 后端分别提交(项目内,受版本控制);
Pixelle 改动在容器内 + 备份 patches/(非本仓库)。中文 commit。