AstrBot ComfyUI Hub

提供四个入口：

命令	用途	内置工作流
/draw	Qwen Image 2.1：无图生成、有图编辑	workflows/example_qwen_image.json
/draw_sd	原 SD 动漫文生图，资源消耗较低	workflows/example_sd_image.json
/img2video（i2v）	图生视频	workflows/example_wan_video.json
/tagger	图片标签识别	workflows/example_tagger.json

/delete 仍用于撤回插件消息，仅支持 aiocqhttp。原 /img2img 入口及旧 Qwen Image Edit 工作流已移除。

LLM 工具调用

LLM 可见的工具名称与说明按能力描述，不包含具体生成模型的名称或版本。动漫工具名为 comfyui_generate_anime；此前在工具列表中选择了旧名 comfyui_draw_sd 的人格，需要重新选择新工具。手动 /draw_sd 命令不变。

使用 AstrBot 标准 FunctionTool 和 Context.add_llm_tools() 注册，要求 AstrBot 4.25.1 或以上。更新插件后重载，在 AstrBot 工具管理/人格工具选择中启用需要的工具，并使用支持工具调用的 LLM。关闭某项插件功能或对应工作流加载失败时，该工具默认不启用；运行时仍检查功能和会话权限。

工具	用途	图片来源
comfyui_generate_image	Qwen 文生图	不使用输入图片
comfyui_edit_image	Qwen 单图/多图编辑	当前/引用消息的 image_indices，或执行器的 image_paths
comfyui_generate_anime	SD 动漫文生图	不使用输入图片
comfyui_image_to_video	图生视频	消息图片 image_index，或执行器图片 image_path
comfyui_image_tagger	提取标签供 LLM 组织提示词	消息图片 image_index，或执行器图片 image_path

LLM 自动选择规则：

• 简单动漫头像、单一角色或常规姿势，没有严格细节或关系要求：优先轻量动漫工具 comfyui_generate_anime，传入英文标签或短语，不直接传中文句子。
• 有非典型动作、明确肢体姿势、物体接触、空间关系、多主体互动、准确文字或多条件构图：使用精细生成 comfyui_generate_image，支持中文/英文自然语言。即使是漫画风格、请求很短也按这一规则选择；一般非动漫生成也使用精细工具。
• 依据已有图片编辑或合成：使用 comfyui_edit_image，即使是动漫图片。
• 先判断动作和关系复杂度，再判断画风。例如“动物爬树、四肢分别攀附或蹬住树干”使用精细生成，不能仅凭漫画风格选择轻量工具。判断依据是原始需求，不是 LLM 自行扩写的画质标签；把复杂要求翻译成英文也不改变工具选择。手动 /draw、/draw_sd 路由不变。

图片编号从 1 开始，顺序与消息中的图片一致。编辑工具省略 image_indices 或传空列表时使用全部图片；例如 [2, 1] 会将原第 2 张作为新的 <image1>、原第 1 张作为 <image2>。缺图、无效编号或读取失败会返回明确错误，不会偷偷改成文生图。工具不会从历史对话中猜测图片；需要编辑早先的消息图片时，请引用那条消息。

代码执行器生成的图片也可直接使用：编辑工具传 image_paths 列表，视频和 Tagger 传单个 image_path。本地执行器相对路径按当前会话的 AstrBot 工作区解析，也支持绝对路径；沙箱路径通过当前会话的 get_booter().download_file() 读取。astrbot_download_file 返回的 AstrBot 临时目录路径和本插件返回的图片 file_path 也可使用。

例如给 Tagger 传 {"image_path": "output/plot.png"}；给编辑工具传 {"prompt": "把背景改成白色", "image_paths": ["output/plot.png"]}。仅提供路径时不再自动混入消息图片；编辑时同时提供 image_indices 和 image_paths，顺序为所选消息图在前、文件图在后。视频/Tagger 指定 image_path 后优先使用文件。

路径读取沿用 AstrBot 的 computer_use_require_admin 和执行环境设置，不新增权限开关；执行器禁用时不读取路径。文件必须是有效图片，每张不超过 20MB，不接受 URL。沙箱下载的中转文件会在读取后清理，原文件不删除。

生成和视频工具使用 AstrBot 原生后台任务：首次返回任务 ID，完成后发送媒体到当前会话，再由框架将最终结果回传 LLM。工具调用不直接发送“正在生成”“正在识别”或排队进度文字；手动命令保留这些提示。

最终结果为 JSON，包含 status（success / failed / delivery_failed）、media_type、file_path、media_sent、message，必要时包含 warning。路径是 AstrBot 主机上保存的最终媒体文件；media_sent=true 时不需要 LLM 再发送同一媒体。生成失败和媒体发送失败也会回传。结果还包含 feedback_hint：额外文字反馈可选；若决定反馈，需通过 send_message_to_user 发给用户，内部总结不会自动发送。media_sent=true 只表示无需重发媒体，不禁止补充一句话；未查看图片或视频时不应评价内容和画质。没有固定完成通知或强制回复兜底。Tagger 同步返回标签给 LLM，不额外发送一条标签消息，因此可在同一轮继续生成提示词或调用编辑工具。Tagger 排队等待仍受 AstrBot 的工具调用超时限制，繁忙时可将该超时设置为不低于插件 timeout。

所有工具复用命令的白名单、封禁、输入/输出审查和队列逻辑；LLM 不能传入管理员身份或更改审查配置。管理子命令和撤回仍通过手动命令操作。

提示词组织原则

保留原始需求中的主体种类、数量、动作和空间关系；编辑时明确要修改及保持的部分。轻量动漫使用英文标签，精细生成/编辑使用中文或英文自然语言。不要把动物默认改成人物，不擅自添加剧情、角色或复杂限制。未要求尺寸、放大、帧率或负面提示词时，优先省略对应参数并沿用配置；Tagger 仅在需要标签时调用，不作每次绘图的固定步骤。面向用户的回复不主动展示内部路径、任务 ID 或实现细节。

配置

设置 server_url 和 timeout，开启需要的功能即可。Qwen、SD、视频、Tagger 各有一个可选的自定义工作流文件名，留空直接使用插件内置文件，不再自动复制出第二套默认示例。

内置 Qwen 工作流使用：

• qwen_image_2.1_nvfp4_T2.safetensors
• qwen3vl_8b_w4a8.safetensors
• qwen_image_2.1_vae_bf16.safetensors

ComfyUI 需支持 TextEncodeQwenImage21 和上述量化格式；NVFP4 原生计算需要相应硬件与后端。需要其他模型时修改工作流中的加载节点。

原白名单、审查开关、提供商、管理员绕过和异常策略的配置键保持不变。面板中 Qwen 图像审查沿用原 img2img 审查项；SD 使用原文生图输出审查项。default_negative_prompt 仅作用于 SD。原安全开关的默认行为不变。

Qwen 生成与多图编辑

/draw 一只蓝色陶瓷小鸟，白色背景
/draw 一张城市海报 宽1280 高768
/draw 将 <image1> 的方块改成 <image2> 的蓝色，保留其他内容

编辑时附上图片，或回复包含图片的消息。按消息链顺序传入所有图片；引用消息内的图片保持原顺序。<image1> 是第一张图，以此类推。未指定宽高时，编辑输出跟随第一张图的宽高比，默认将参考图缩放到约 1MP。

官方公开支持最多 10 张参考图。ComfyUI v0.37.0 的节点实际提供 16 个输入，本插件完整传入 1～16 张，超过 16 张明确报错，不静默截断；超过官方公开范围的效果没有保证。任一图片读取或上传失败会停止本次请求，避免后续参考图编号错位。

生成默认 1024×1024、25 步、CFG 1、Euler/simple；显式宽高按 32 对齐。编辑时指定宽高会改变输出画布，可能改变构图。放大2 使用解码后的图像缩放。Qwen 默认负面提示词为空，CFG 1 不启用负面分支；如需使用负面提示词，可在自定义工作流中提高 CFG。

SD 与其他命令

/draw_sd 1girl, solo, smile
/draw_sd 正面[1girl, solo] 负面[bad hands] 宽1024 高768
/img2video 一片随风摇动的树叶 fps=16 时长3
/tagger

SD 保留原 checkpoint、分辨率控制和提示词解析。视频、Tagger 需要附图或回复图片。视频的总帧数仍受 img2video_max_frames 限制。转发参数支持 转发=是，仅 aiocqhttp 支持合并转发。

管理员管理审查仍使用 /draw $enable_censorship、$disable_censorship、$add_block_tag、$remove_block_tag、$add_output_block_tag、$remove_output_block_tag。

自定义工作流与节点绑定

自定义文件放在 AstrBot 的 data/plugin_data/astrbot_plugin_comfyui_hub/workflows/ 中，在对应配置填文件名。必须是 ComfyUI API 格式。节点 ID 和字段名只在工作流中维护，不再在插件配置里重复填写。

在相关节点的 _meta.hub 中标记用途，例如：

{
  "6": {
    "class_type": "CLIPTextEncode",
    "inputs": {"clip": ["4", 1], "text": ""},
    "_meta": {"title": "正面提示词", "hub": {"positive": "text"}}
  }
}

positive 为用途，text 为该节点的输入字段名；字段顺序不影响写入。一个节点可以绑定多个用途。绑定重复或字段不存在时，加载会报告具体错误。

功能	必需绑定	可选绑定
SD	positive	negative、width、height、scale
Qwen	positive、negative、width、height、latent、output_image	—
视频	positive、image、width、height	negative、fps、length
Tagger	image、output	—

Tagger 的 output 绑定值用 null，表示整个输出节点。Qwen 的正负提示词绑定同一个 TextEncodeQwenImage21，latent 绑定采样器的 latent_image，output_image 绑定保存节点的 images。参考图节点由插件逐张添加，无需预留十个 LoadImage 占位节点。

从 1.x 更新

• 原 /draw 的 SD 功能改为 /draw_sd；新版 /draw 使用 Qwen 2.1，支持生成与编辑。
• 原 txt2img_workflow、img2img_workflow、img2video_workflow 改为 sd_workflow、qwen_workflow、video_workflow；原 enable_img2img 改为 enable_qwen。
• 22 项独立节点/字段配置已移除，总配置从 56 项缩减为 34 项。已有自定义 API 工作流需按上面的约定补充 _meta.hub，并重新选择文件；旧自定义文件不会被自动覆盖或删除。
• 原工作流里的 SD checkpoint 等参数保留在 workflows/example_sd_image.json。旧 Qwen 2511 示例不再加载，仓库外的模型权重不删除。

输入图片上限仍为每张 20MB，Discord/Telegram 输出仍按平台限制压缩。

更新日志

参见 CHANGELOG.md。