magicwang1111-Comfyui-Kling-Wrapper/docs/plan-v2.md

Comfyui-Kling-Wrapper 腾讯云 Provider 改造计划 v2

背景修正

上一版方案默认把腾讯云 provider 当作“首版受限能力”，在 Image2Video / Text2Video 上主动禁用了不少字段。

这与当前实际需求不符：

• 用户现有流程需要继续可用
• 腾讯文档覆盖范围并不只是最小图生视频/文生视频
• 腾讯侧能力至少已经覆盖：
  • 图生视频
  • 文生视频
  • 动作控制
  • 视频延长
  • 主体管理
  • 自定义音色
  • 多模态编辑
  • 多图参考生视频

因此 v2 的目标不再是“先禁掉复杂能力”，而是：

优先保证腾讯 provider 不破坏现有工作流输入；在节点层保留能力，在 provider 层做精确映射与渐进增强。

---

总目标

1. 节点层目标

对用户来说，provider=tencent_vod 时：

• 不应因为实现保守而丢失日常可用字段
• Image2VideoNode / Text2VideoNode 现有输入尽量保持可用
• 能力缺口优先通过“映射/透传”解决，而不是直接报不支持

2. 架构目标

在现有 provider 抽象上继续演进：

• official 路径保持现状与兼容性
• tencent_vod 路径单独维护腾讯请求映射
• 把腾讯特有 payload 组装逻辑从 py/nodes.py 逐步下沉到：
  • py/api/providers/tencent_vod/mapping.py
  • 后续可再拆 capabilities.py / schemas.py

3. 产品目标

先把 图生视频 / 文生视频 做到“能承接完整工作流字段”，然后再扩展到：

• MotionControl
• VideoExtend
• Subject / AdvancedCustomElements
• CustomVoice
• MultiModal Edit
• MultiImagesToVideo

---

当前代码现状

已经具备

• provider 基础目录已建立：
  • py/api/providers/base.py
  • py/api/providers/official/video.py
  • py/api/providers/tencent_vod/video.py
• py/nodes.py 已有：
  • provider 配置解析
  • provider factory
  • Image2VideoNode / Text2VideoNode provider 分发入口
• 官方路径已能通过 provider 包装调用
• 腾讯路径已经能发起 CreateAigcVideoTask / DescribeTaskDetail

当前问题

• 早期腾讯逻辑过于保守，仍然带有“能力先禁用”的设计痕迹
• 腾讯 payload 组装逻辑仍不够精细
• 有些字段只是粗粒度 passthrough，还未转成腾讯最终字段结构
• 图/文视频之外的腾讯能力尚未纳入 provider 化
• 当前 shell Python 环境缺少 torch，无法直接完整跑 pytest

---

v2 实施原则

原则 1：不轻易在节点层禁用字段

除非已经确定腾讯接口确实不支持，或当前字段会构造出无效请求，否则：

• 不在节点层报“不支持”
• 先保留输入
• 再在 provider 层做映射或透传

原则 2：节点是通用接口，provider 负责后端差异

节点层尽量继续表达统一业务语义，例如：

• voice_list
• element_list
• camera_control
• reference_video
• image_tail
• shot_type
• sound

这些差异应由 provider mapping 解释为腾讯 payload。

原则 3：先显式映射，再保底透传

对腾讯路径分两层处理：

1. 显式映射层
   • 明确转成腾讯结构与字段名
2. 透传层
   • 暂未最终建模的字段先通过 extra_payload / extra_output_config 带过去

这样既不阻塞现有流程，又为后续精细化收敛留下空间。

---

第一阶段范围：Image2Video / Text2Video 精确映射

这是当前最高优先级。

A. Image2Video 目标

provider=tencent_vod 时，至少承接以下输入：

• model
• image
• image_tail
• prompt
• negative_prompt
• cfg_scale
• mode
• duration
• sound
• voice_preset / custom_voice_id -> voice_list
• shot_type
• image_list
• element_list
• reference_video
• camera_control

B. Text2Video 目标

provider=tencent_vod 时，至少承接以下输入：

• model
• prompt
• negative_prompt
• cfg_scale
• mode
• aspect_ratio
• duration
• sound
• voice_preset -> voice_list
• shot_type
• image_list
• element_list
• reference_video
• camera_control

---

第一阶段技术方案

1. request 层扩展

继续使用 py/api/providers/base.py 的 request dataclass，补充腾讯映射所需字段。

Image2VideoRequest

保留/补充：

• image_urls
• image_tail_url
• voice_list
• element_list
• reference_video
• camera_control
• extra_payload
• extra_output_config

Text2VideoRequest

保留/补充：

• image_list
• image_urls
• voice_list
• element_list
• reference_video
• camera_control
• extra_payload
• extra_output_config

2. nodes 层职责

在 py/nodes.py：

• 继续负责把 ComfyUI 输入转成统一 request
• 上传图片/视频引用 URL
• 组装统一业务字段
• 不负责写腾讯最终 payload 结构

3. mapping 层职责

新增 / 使用：

• py/api/providers/tencent_vod/mapping.py

职责：

• Image2VideoRequest -> Tencent payload
• Text2VideoRequest -> Tencent payload
• FileInfos 组装
• OutputConfig 组装
• sound / voice / element / camera / shot / reference 映射
• extra_payload / extra_output_config 合并

4. provider 层职责

py/api/providers/tencent_vod/video.py 只负责：

• 签名
• HTTP 请求
• 轮询
• 调 mapping 产出 payload
• 响应解析

避免 provider 文件同时承载过多字段组装细节。

---

建议的腾讯映射分层

一、稳定显式映射（优先完成）

这些字段应尽量直接进入腾讯固定 payload：

• ModelVersion
• GenerationMode
• Prompt
• NegativePrompt
• OutputConfig.Duration
• OutputConfig.AspectRatio
• OutputConfig.AudioGeneration
• OutputConfig.CfgScale（若腾讯结构允许）
• FileInfos

二、结构化扩展映射（阶段内完成）

这些字段先用结构化 helper 明确装入 payload：

• VoiceList
• ShotType
• ElementList
• CameraControl
• ReferenceVideo
• LastFrame
• ImageList / 多图参考输入

三、保底透传（阶段内保留）

对于暂时还无法确认最终字段位置的能力：

• 允许通过 extra_payload / extra_output_config 合并
• 等拿到腾讯完整字段说明后再收敛成显式映射

---

第一阶段验收标准

功能验收

1. Image2VideoNode(provider=tencent_vod) 不再因为保守实现拒绝正常字段
2. Text2VideoNode(provider=tencent_vod) 不再因为保守实现拒绝正常字段
3. 图生视频支持：
   • 主图
   • 参考图
   • 末帧
   • 参考视频
4. 文生视频支持：
   • prompt
   • aspect_ratio
   • duration
   • 参考图/参考视频（如果腾讯 payload 接受）
5. 音频/主体/镜头相关字段至少能进入 provider payload

代码验收

1. 腾讯 payload 组装逻辑主要位于 mapping.py
2. nodes.py 不再堆积大量腾讯特判
3. video.py 主要聚焦请求/轮询逻辑

测试验收

新增/修改测试覆盖：

1. provider 选项仍然暴露正确
2. official 路径不回归
3. Tencent request 不再因为这些字段直接报错：
   • sound
   • voice_list
   • shot_type
   • element_list
   • reference_video
   • camera_control
   • image_tail
   • image_list
4. mapping.py 的 payload 结构正确
5. FileInfos / OutputConfig / extra merge 覆盖

---

第二阶段范围：扩展到其他腾讯能力节点

在图/文视频映射稳定后，进入第二阶段。

1. MotionControl

对应当前：

• MotionControlNode
• py/api/motion_control.py

目标：

• 让腾讯 provider 能承接动作控制业务语义
• 支持参考图 + 参考视频 + 保留原声 + element_list 等

2. VideoExtend

对应当前：

• VideoExtendNode

目标：

• 把视频延长纳入 provider 分发

3. Subject / AdvancedCustomElements

对应当前：

• AdvancedCustomElementCreateNode
• AdvancedCustomElementQueryNode

目标：

• 腾讯主体管理能力独立 provider 化
• 支持 element_voice_id

4. CustomVoice

对应当前：

• CustomVoiceCreateNode
• CustomVoiceQueryNode
• TTSNode

目标：

• 让自定义音色与图/文视频 voice 逻辑衔接

5. MultiImagesToVideo / MultiModalEdit

目标：

• 与腾讯多图参考、多模态编辑文档对齐

---

风险与处理策略

风险 1：腾讯文档当前无法完整抓取字段细节

处理：

• 先做“统一业务语义 + 显式映射 + 保底透传”
• 等补充更精确字段说明后再收敛

风险 2：节点语义与腾讯字段语义不完全一致

处理：

• 在 mapping 层做适配，不在节点层改用户输入语义

风险 3：测试环境缺依赖

处理：

• 当前先做 py_compile
• 完整 pytest 需要带 ComfyUI/torch 的 Python 环境运行

---

推荐实施顺序

Step 1

完成 Image2Video / Text2Video 的腾讯 mapping 精细化：

• mapping.py 完整接管 payload 组装
• 减少节点层硬编码腾讯逻辑

Step 2

修正测试：

• 去掉“腾讯应拒绝工作流字段”的旧断言
• 改成“腾讯 request 能承接并构造 payload”

Step 3

在带依赖环境跑定向测试：

• tests/test_backend_config.py

Step 4

进入第二阶段节点扩展：

• MotionControl
• VideoExtend
• Subject
• Voice
• Multi-image / Multi-modal

---

本计划对应产物

文档产物

• docs/plan-v2.md（本文件）

第一阶段目标代码文件

• py/nodes.py
• py/api/providers/base.py
• py/api/providers/tencent_vod/mapping.py
• py/api/providers/tencent_vod/video.py
• tests/test_backend_config.py

---

阶段结论

v2 的核心不是“再加几个 if”，而是把腾讯云路径从“受限首版”升级为：

可承接现有工作流输入的正式 provider 实现

先完成图生视频 / 文生视频的精细映射，再向动作控制、主体管理、自定义音色、多图参考等腾讯能力扩展。