远程生图工具 leolee9086/dsh-tool-image

dsh-tool-image

DeepSeek Harness 的远程图像生成 / 参考生图插件，挂载在 HOST 平面，供不同 agent 预设下的会话共用。支持 OpenAI 兼容的图像接口、图像聊天接口和 Gemini 原生接口；出图同时保存为文件，并注册为会话附件，让模型和界面都能看见结果。

站点地址和凭据名来自运行时配置，插件不内置供应商地址或密钥。当前版本 0.4.0，更新内容见 CHANGELOG。

工具

| 工具 | 用途 | 必填参数 |
| image_generate | 文生图 | prompt |
| image_edit | 参考生图 / 改图，支持一次传多张参考图 | prompt、image_path（路径或路径数组） |
| image_providers | 查询已配置 provider，按需探测当前凭据可见的模型目录 | 无 |

生图工具共用的可选参数：

| 参数 | 说明 |
| provider | DSH 中已配置的 provider id；从运行时读取其 baseURL、apiKeyEnv 和协议类型 |
| base_url、api_key_env | 显式指定 API 基址和保存密钥的变量名，可覆盖 provider 中对应的配置；密钥值不作为工具参数传入 |
| model | 默认 gpt-image-2。具体模型 id 以目标站点为准，插件不会把名称当成可用性保证 |
| api | auto（默认）、images、chat 或 gemini；自动选择仅是路由建议，可显式覆盖 |
| count | 图像接口支持 1–8，默认 1；chat / gemini 只接受 1，禁止自动拆成多个付费请求 |
| size | 如 1536x2048。图像接口直接传尺寸；chat / gemini 转成标准宽高比，非标准比例在请求前报错 |
| resolution | 1K、2K、4K，仅适用于 chat / gemini；模型是否支持对应档位由站点决定 |
| transparent | 仅 images 支持，设置 background=transparent；其它协议在请求前拒绝，避免悄悄忽略 |
| save_dir | 长期保留素材时显式指定。默认 <系统临时目录>/dsh-image，也可用插件配置 saveDir 设置默认值 |

自动路由：provider 的协议类型为 google-generative-ai 时使用 Gemini 原生接口；否则 Gemini image / nano-banana 名称走 chat，其它名称走 images。显式覆盖 base_url 后不沿用原 provider 的协议类型。自动路由不会在失败后尝试另一种收费接口。

选择接口

| api | 文生图和参考生图的请求 | 返回图片形态 |
| images | /images/generations JSON、/images/edits multipart，多张参考图使用重复的 image 字段 | data[].b64_json 或 data[].url |
| chat | /chat/completions，提示词和全部参考图放进用户消息 | message.images、内容中的图像块，或 Markdown 图片链接 |
| gemini | /models/{model}:generateContent，提示词和参考图以 parts / inlineData 传入 | candidates[].content.parts[].inlineData，兼容 inline_data |

OpenAI 兼容站的 base_url 应包含该站的 API 前缀，例如 https://relay.example/v1；Gemini 原生基址未带版本时会补 /v1beta，已带 /v1 或 /v1beta 时保留。请求失败会返回原接口错误，不自动重试、不切换站点，也不追加付费生成。

例如，工具参数可以这样填写（provider id 和 model 需换成自己的配置）：

{
"provider": "my-image-provider",
"model": "gpt-image-2",
"api": "images",
"prompt": "一张适合手机阅读的竖版漫画", "size": "1536x2048", "save_dir": "./image-out" }

参考生图在同一组参数中加 image_path：

{ "image_path": ["./reference-a.png", "./reference-b.png"] }

查询模型与判断依据

先调用 image_providers 查看运行时站点；probe=true 查询当前凭据能访问的模型目录，不调用收费生图。目录协议 api 可选 auto、openai 或 gemini，Gemini 目录支持分页。

show_all 默认 true，输出目录与配置模型的并集，保留陌生名称和仅配置的别名；设为 false 时只显示图像候选。每项标明来自目录、配置或两者，并区分：

- 输出模态 / 端点元数据：站点明确声明图像输出或图像生成接口。
- 名称推断：名称像已知图像模型家族，仍需确认实际接口与权限。
- 未确认图像输出：不因名字陌生而删掉，也不把能输入图片的视觉模型当成能生成图片。

显式文本输出信息会阻止仅凭模型名认定为图像模型。普通 generateContent 方法本身也不是图像输出的证据。同地址的不同 provider 可能使用不同凭据分组；目录里有某模型，不等于当前分组有生图权限。

文件、附件与尺寸

每次生成先保存真实图片，再向可选的 attachments 服务注册。返回 summary、files 和 images；output.render 为每张附件提供 image block。附件服务不可用时保留文件路径，不把已生成的图片当成生成失败。

附件服务可能缩小预览。插件保留 originalDimensions，在结果中分别说明原图尺寸与预览尺寸，输出契约严格声明这些字段并继续拒绝未知字段。原文件不会因预览缩小而被覆盖；4K 文件尺寸也不代表插件能证明模型的内部采样分辨率。
图片返回格式优先按 PNG / JPEG / WebP / GIF 文件特征识别。API 返回的图片下载链接不携带模型端点的 API 密钥。无图响应会报告拒绝或结束原因，避免只说「成功但没图片」。

安装与运行时配置

本仓库是可安装的 Cordis bundle，package.json 的 dsh.bundle.patch 指向 cordis.patch.yml。通过 DSH 的插件安装入口安装，挂载到 HOST 平面；不要把跨会话图片工具当作某个 agent 预设独占的服务。

凭据优先读取 api_key_env 或 provider 的 apiKeyEnv 指定的同名环境变量，再读取 DSH_HOME 下的凭据文件（默认 ~/.dsh/.credentials.yaml）。插件仅报告凭据名，不返回密钥值。

无 provider 时可通过 base_url + api_key_env 完整指定。DSH_IMAGE_BASE_URL 可作为地址后备；如果密钥保存在 DSH_IMAGE_API_KEY，显式传 api_key_env: "DSH_IMAGE_API_KEY" 即可使用。

本地开发时 Host 入口是 lib/index.js，Client 入口是 src/client.js。修改后按当前部署的插件重载 / 构建机制处理，并验证既有 GUI；单改文件或另开服务器不能保证现有页面已更新。

界面与工具检索

浏览器侧为 image_generate / image_edit 提供专属工具卡，显示全部附件，支持复制图片和存文件；透明区域以棋盘格呈现。图片由会话授权的 loadImage 加载。

工具描述包含「生成图片」「画图」「图生图」「模型查询」等检索词，适合配合 dsh-tool-gateway 的 find_tools 工具箱方式使用。

验证与限制

pnpm test

测试不依赖 DSH 内部包，也不发收费请求；覆盖输出契约的宿主关键词子集、严格返回值、原尺寸 / 缩小预览、模型目录合并与分页、多参考图传输、图片解析及失败不重试。受限环境中也可直接执行 node test/output-schema.test.mjs、node test/image-tool.test.mjs、node test/prompt-copy.test.mjs。

图像接口已做实际生成验证；新增聊天 / Gemini 原生适配的自动化验证使用模拟服务，不宣称所有站点和型号都已端到端实测。尺寸、分辨率档位、透明选项和多张生成仍取决于模型及站点适配。插件未实现取消之外的全局并发调度。

交流群

欢迎加个人讨论群【工具软件爱好者折腾群-综合讨论】：点击加入（群号 1017854502）。

赞赏

如果这个项目帮到了你，可以请我喝杯咖啡：

赞赏码

也欢迎通过 爱发电 支持。