cneicy/dsh-imagegen

0 Fork 0

Files

T

cneicy 108e957c64

feat: 发布 DSH 生图插件与中文安装使用文档

2026-10-05 00:21:57 +08:00

8.9 KiB

Raw Blame History

DSH 生图插件

为 DeepSeek Harness（DSH） 添加「设置 → 生图」页面和可在对话中直接调用的生图工具。支持自定义 OpenAI Images API 兼容接口、API Key 和模型，生成结果可在对话内预览，并保存原图。

功能

接口配置：设置 Base URL 和 API Key，支持第三方兼容服务。
显式选择模型：手动维护模型 ID，或从接口读取模型列表；可设置对话默认模型，也可以每次在对话中指定。
对话生图：助手通过 imagegen_status 查询配置，通过 imagegen_generate 生成图片。
直接生成：在「设置 → 生图 → 生成图片」中输入提示词、选择模型并生成。
图片输出：支持 base64 和图片 URL 响应，提供图片预览与原图下载。
技能复用：附带 imagegen 提示词规范和示例，并注册 DSH 专用的 dsh-imagegen 技能。
密钥隔离：API Key 存入 DSH 凭据存储，按 Base URL 分开保存，不在配置查询中回显。

环境要求

已验证的 DSH 版本：0.2.0-rc.2，桌面版的 Web 界面。
安装目标需要提供 DSH 的插件管理、设置插槽、工具、凭据和图片附件服务。
一个支持 POST /images/generations 的 OpenAI Images API 兼容服务及有效 API Key。
从源码克隆安装需要 Git；运行测试建议 Node.js 24 或更新版本。

仓库已经包含可直接加载的 Host / Client 文件，不需要编译前端、不需要安装 Python，也没有运行时第三方 npm 依赖。其他 DSH 版本尚未验证。

安装

方式一：克隆到本地后安装（推荐）

在本仓库页面复制克隆地址，克隆到一个长期保留的目录：
```
git clone https://git.crash.work/cneicy/dsh-imagegen.git dsh-imagegen
```
打开 DSH 左侧的「插件」页面，使用安装入口，填写克隆目录的绝对路径。例如 Windows：
```
D:\Plugins\dsh-imagegen
```
如果通过 DSH 助手安装，可以直接说：

请把 D:\Plugins\dsh-imagegen 作为插件包安装并启用。

对应的插件管理工具调用：
```
{
  "action": "install_bundle",
  "target": "D:\\Plugins\\dsh-imagegen",
  "enabled": true
}
```
确认插件包 dsh-imagegen-local 已启用，然后打开「设置 → 生图」。启用后若入口没有出现，先刷新界面；如果安装结果提示需要重启，请重启 DSH。

本地目录可能以链接方式安装，安装后请保留该目录，不要移动或删除。

方式二：从 Git 地址安装

也可以在 DSH 的插件安装入口填写本仓库的 Git 安装地址：

git+https://git.crash.work/cneicy/dsh-imagegen.git

插件管理器会下载仓库并安装，默认启用。若希望固定版本，可以使用 #<提交哈希> 后缀。此方式需要 DSH 所在环境能访问 Gitea，并可调用 Git。

仓库包名为 dsh-imagegen-local。本项目尚未发布到 npm，不能直接用 npm install dsh-imagegen-local 从公共注册表安装。

配置

打开 设置 → 生图 → 接口设置：

配置项	说明
Base URL	API 根地址，例如 `https://api.openai.com/v1`；不要填写完整的 `/images/generations` 路径。
API Key	对应这个接口地址的密钥。保存后不回显；留空会保持已有密钥。
可选模型	每行填写一个完整、精确的模型 ID。名称是否可用取决于服务商。
对话默认模型	用户显式选定的默认模型；留空时，助手应先询问或使用本次对话明确指定的模型。

点击「保存设置」。保存接口与密钥后，可使用「从接口读取模型」，检查列表并再次保存。部分服务不提供 /models，或会同时返回聊天模型，此时手动填写可生图的模型 ID 即可。

更换 Base URL 后，需要为新地址配置密钥。勾选「清除这个地址已保存的密钥」并保存，才会删除该地址的凭据。不要把 API Key 发到聊天里。

使用

在对话中生图

配置完成后，直接对 DSH 助手描述图片：

用 gpt-image-2 生成一张雨夜霓虹街道，电影摄影风格，横版。

或者，在设置中已经选定默认模型时：

画一只趴在窗台上晒太阳的橘猫，柔和水彩风格。

模型名称仅作示例，以你的服务实际支持的模型为准。助手会调用插件，返回图片预览和保存路径。插件不会自动更换模型，也不会自动重试收费请求。

在设置页面直接生图

进入「设置 → 生图 → 生成图片」。
选择或输入本次生成模型。
输入画面描述。
按需展开尺寸、质量与数量设置。
点击「生成图片」，完成后预览并下载原图。

对话工具

工具	用途
`imagegen_status`	返回 Base URL、是否已配置、候选模型、默认模型与输出目录；不返回密钥。
`imagegen_generate`	以明确的模型和提示词生成图片，并返回 DSH 图片附件及原图路径。

生成参数示例：

{
  "model": "gpt-image-2",
  "prompt": "一只趴在窗台上晒太阳的橘猫，柔和水彩风格",
  "n": 1,
  "size": "1024x1024"
}

必填参数是 model、prompt；n 默认为 1，范围为 1–4。可选参数还有 size、quality、background、output_format。这些参数是否可用取决于选定模型与服务商；未指定的可选参数不会额外发送。网页生成表单目前提供尺寸、质量和数量，背景与格式可通过对话工具设置。

数据保存

普通配置：$DSH_HOME/imagegen/settings.json。
生成原图：$DSH_HOME/imagegen/outputs/。
未设置 DSH_HOME 时，默认根目录为用户主目录下的 .dsh。
API Key：由 DSH 凭据服务保存，不写入插件目录或上述普通配置文件。
对话预览：使用 DSH 持久化附件。预览可能被缩小，输出目录里的原图保留服务返回的原始字节。

使用插件会将提示词和生成参数发送到配置的服务商，并按其规则计费。点击「停止等待」不能保证服务商已经取消生成或计费。

更新与卸载

本地克隆方式安装：在插件目录执行 git pull --ff-only，然后重启 DSH，以加载新的 Host / Client 代码。
Git 地址方式安装：通过 DSH 插件管理器安装所需的新提交或版本，然后按提示重启。
在 DSH「插件」页面停用或卸载 dsh-imagegen-local。
卸载不会自动删除已保存的图片和凭据。如需清理密钥，请先在生图设置里清除对应地址的密钥，再卸载。

常见问题

出现 HTTP 401 / 403：检查 API Key、Base URL 以及账号是否有该模型的权限。

出现 HTTP 404：检查地址是否包含服务商要求的 /v1，以及是否支持 Images API。不要把完整生成端点填进 Base URL。

出现 HTTP 502 / 503 或超时：通常是服务或网关暂时不可用。确认服务状态后手动重试；插件不会自动重试。单次网络操作最多等待 180 秒。

模型列表读取失败：可以手动填写模型，不要求服务必须支持 /models。

模型不支持尺寸、质量或透明背景：去掉不受支持的可选参数，或显式选择支持这些能力的模型。第三方服务也可能忽略某些参数。

能否用参考图或修改已有图片？ 当前只实现文生图，不支持参考图输入、图像编辑或蒙版。附带的上游 imagegen 技能资源包含编辑说明，但不代表本插件已实现编辑接口。

开发与验证

node --test test/*.test.mjs

测试使用本地模拟 HTTP 服务和隔离的临时目录，不会访问付费生图接口。覆盖参数校验、模型选择、base64 / URL 返回、下载时不携带密钥、错误处理、取消、响应大小限制、设置与凭据隔离、图片附件和路径校验。

项目结构：

lib/index.mjs          Host 插件、设置路由、聊天工具和附件
lib/client.js          DSH ModuleLoader 格式的设置界面
lib/engine.mjs         Images API 请求与校验
skills/SKILL.md        DSH 生图技能适配层
vendor/imagegen/       上游 imagegen 技能与许可证
bundle.yaml           DSH 插件安装补丁
test/                 本地模拟接口测试

接口响应与解码图片总量有 64 MiB 限制。网络引擎校验图片格式签名，DSH 附件服务负责进一步验证与预览处理。

技能来源与许可证

vendor/imagegen/ 复用 OpenAI Codex 的 imagegen 技能资源，包含原始脚本、提示词参考、示例和 Apache-2.0 许可证。上游资源完整保留，DSH 的执行适配放在 skills/SKILL.md 中；插件本身通过原生 JavaScript 调用 Images API，不运行附带的 Python CLI。

本项目采用 Apache-2.0 许可证，详见 LICENSE；第三方资源归属说明见 THIRD_PARTY_NOTICES.md。

8.9 KiB Raw Blame History Unescape Escape