图像视频生成 KonnectSuite/dsh-tool-images

description: "面向模型的图像与视频生成工具（images_generate），基于 ctx.comfyImagesController：部署如何挂载它，以及模型提交 ComfyUI 工作流时看到什么。"
kind: "package-reference"

@deepseek-ai/dsh-tool-images

概述

dsh-tool-images 为模型提供一个 images_generate 工具，它从已连接的 ComfyUI 控制器目录中提交工作流，并报告所用的文件、工作流与模型。当智能体需要生成图像或短视频，而不想逐次调用驱动 ComfyUI（读取工作流图、暂存文件、轮询命令行）时选择它。每个工作流自身的画布、步数与批量即为默认值，调用方的覆盖值受固定边界限制。服务器不可达或工作流不可用时会报错并说明可用项。超过 defaultWaitSeconds 的运行会报告为仍在运行。

目录

- 使用此包
- 了解实现
- 模型体验
- 已知限制与延后工作
- 开发备注

使用此包

在同时挂载了工具注册表与 ComfyUI 控制器的组合中加载此包，它会向模型的工具集添加 images_generate。

何时选择

当模型应当创作媒体而不是读取媒体时选择它。该工具通过与图像面板相同的控制器提交，因此模型可选的目录就是面板显示的目录；服务器上新增的工作流对两者同时可用，无需额外配置。

最小配置

- name: '@deepseek-ai/dsh-tools'
- name: '@deepseek-ai/dsh-api-comfyui-controller'
- name: '@deepseek-ai/dsh-tool-images'

| 字段 | 默认值 | 含义 |
| defaultWaitSeconds | 120 | 提交后等待渲染的时长，超时后报告为仍在运行 |
| maxWaitSeconds | 600 | 调用方 wait_seconds 参数的上限 |
| inheritedTools | 不限制 | 其他提供方工具的可选允许列表，涵盖会话内工具。本插件的媒体工具仍可使用。跟随提供方的安装与移除。未安装的可选提供方不贡献工具。被排除的工具在该作用域中不可见，也不能执行。 |
| chatImageEdits | false | 以 prompt、可选的准确 source_attachment_id 或有序 source_attachment_ids，以及可选的已配置 workflow 覆盖已安装的 edit_image。仅提供提示词时，优先编辑最新用户消息中的附件，否则编辑对话中最新的图片（包括生成结果）。省略 workflow 时，由提供程序自动选择兼容工作流。该作用域不提供画布或文件路径选择器；其他智能体仍使用原工具。 |
| referenceSearch | false | 添加公共图像参考搜索与导入；需要 web 和 attachments 服务。 |
| referenceSearchResults | 6 | 来源页面与返回图像候选数量上限，范围为 1 到 20。 |
| referenceTimeoutMs | 20000 | 每次参考搜索与下载请求的时限。 |
| referencePageBytes | 1000000 | 来源页面或 Commons 响应的最大字节数。 |
| referenceCommonsEndpoint | https://commons.wikimedia.org/w/api.php | 公共 MediaWiki 图像搜索端点。 |
| referenceCommonsFallback | true | 已配置的网页搜索没有页面预览时搜索 Commons。 |

该工具需要 tools 与 comfyImagesController 两项服务，因此缺少任一项的组合会保持该行为待定，而不会注册一个无法运行的工具。

使用 images_generate

传入 prompt，以及需要特定风格或能力时的 workflow 目录 id。

images_generate({ prompt: 'a hedgehog in a tiny party hat, early digital camera flash', workflow: 'saved:Klein.json' })

size、steps、seed 与 batch 会覆盖所选工作流自身的设置；wait_seconds 限制调用等待多久。宽高须在 64 到 4096 之间，步数为 1 到 150，批量为 1 到 8。

失败与恢复

启用 referenceSearch 后，content_search_images 使用已配置的网页搜索发现来源页面的 OpenGraph 或 Twitter 预览图像。它不是专用图像搜索引擎。可以显式选择 Commons，或将其作为公共备用来源；结果可能不包含特定虚构服装或品牌素材。content_import_reference 通过匿名、有界的公共 HTTP 传输下载选中的 PNG、JPEG、WebP 或 GIF，经附件存储验证后返回可见像素、准确的附件 ID 和来源页面。外部文字与图像是参考材料，不是指令。导入不发送浏览器 Cookie；超大图像与非公共目标会报错。多参考编辑应先传客户照片，再传导入的参考图像；图像提供方必须支持有序参考，否则拒绝请求。

服务器不可达时会报错并给出其地址。workflow 未知或不可用时会报错并列出可用 id，以便模型换一个真实 id 重试。等待到期而渲染未完成时返回 status: 'running' 与提示 id，完成后结果会出现在该对话的历史中。

了解实现

仅视频模式（videoOnly: true）注册 content_video_workflows、content_generate_video、content_video_status 和 content_assemble_video，与配置中的图像服务并用。创建使用已安装的视频工作流，可上传会话中的一张图片作为起始帧，并返回实际输出链接或正在运行的任务编号。请查询状态，不要重复提交。duration_seconds 与 frame_rate 覆盖受支持的场景时间设置；segments_json 提供 Director 提示词片段。未指定时间覆盖时，使用保存的工作流时长与帧率。

设置 production: true 后，content_project 读取并保存会话专属的创作需求与顺序分镜。每次保存要求最新修订编号，并创建不可变修订；并发保存不会相互覆盖。projectDirectory 默认为用户主目录下的 .arya/content-projects；maxProjectBytes 默认限制每个完整修订为 65536 字节。项目保存场景提示词、时长、工作流选择、参考和实际生成回执。读取早期修订后可通过新保存恢复；保存分镜不会生成场景。

content_assemble_video 按指定顺序组合准确的保留输出引用，并支持可选裁剪、交叉淡化和字幕轨道。只有编码成功才返回完成影片的链接。使用组合前，须配置控制器的本地 FFmpeg 支持。已有生成片段保持不变；此工具不提供上传视频暂存、自动视频理解、旁白合成或配乐替换。

实现内部细节 — 点击展开

设计原则

- 目录即约定。 工具从控制器报告的条目中选择，并以每个工作流自身的设置为默认值，未指定工作流时优先选择部署内置的默认工作流，因此在服务器上新增或停用工作流即可改变模型可请求的内容，无需改代码。
- 结果说明实际发生了什么。 每次回复都带有所用工作流与模型的标签，因为渲染出的图像本身并不能证明是哪个模型生成的。
- 提交归控制器所有。 参数校验、图转换、HTTP、历史投影与取消都留在服务中；本包只构建请求并读取结果。

源码索引

| 文件 | 职责 |
| src/index.ts | 插件入口：配置模式、基于目录的工作流选择、请求构建、轮询、工具注册 |

模型体验

工具定义

模型所见

images_generate 的 schema — 必填的 prompt，以及可选的 workflow、negative_prompt、size、steps、seed、batch 与 wait_seconds — 及其描述，说明工作流 id 来自图像目录，且不接受参考编辑或图生视频请求。

Token 影响

工具注册期间，每次请求产生固定的 schema 开销。

KV Cache 影响

定义不变时前缀稳定；插件生命周期变化可能使复用从首个变化的 token 起失效。

完成的运行

模型所见

status、promptId、工作流标签、模型标签，以及本次运行产出的媒体文件名。

Token 影响

固定字段加上每个产出文件一行，直到压缩前都会重复计入。

KV Cache 影响

仅追加；结果位于可复用的请求前缀之后。

未完成或失败的运行

模型所见

超出等待时间的渲染会以 status: 'running' 与其提示 id 报告。服务器不可达、工作流未知或参数越界时会报错，并给出地址、可用 id 或可接受范围。

Token 影响

只有保留的结果计入 token。

KV Cache 影响

仅追加；结果位于可复用的请求前缀之后。

已知限制与延后工作

- 不接收源图像或源视频 — 该工具两者都无法暂存，因此参考编辑与处理源视频的图形会被明确拒绝并说明原因，而不是在 ComfyUI 内部失败。文生视频无需源文件，仍然可用。参考编辑与图生视频仍需在提供源图的图像面板中完成。
- 没有结果卡片 — 该工具的主机渲染为文本；尚无基于结果元数据派生的 Web 卡片。
- 等待受配置限制 — 超过 maxWaitSeconds 的渲染会返回 running 而不是一直占用调用；调用方需从对话历史中读取完成的文件。
- 故事板的录制行为 — snapshots/session/content-project 通过随附的 headless 配置回放制作工具，无需模型或渲染器。ComfyUI 提交、轮询、参考图暂存和影片拼接由工具、Loader 及真实编码器测试覆盖；GPU 渲染需要下载模型。

开发备注

维护者工作上下文 — 点击展开

本开发备注是维护者的工作上下文，明确不具权威性。

未来：参考图像参数

增加一个 reference 参数，把工作区图像暂存到 ComfyUI 的输入目录，可让模型触达目录中已经列出的编辑与图生视频工作流。它需要控制器尚未暴露的暂存步骤，因此本版本未包含。