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）。

赞赏

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

也欢迎通过 爱发电 支持。