dsh-imagegen-plugin

给 DeepSeek Harness（DSH）加上第三方生图能力的插件：主模型（如 dsV4）不会画图没关系——本插件把「生图」做成一个可配置、可对话召唤的能力。

┌ 设置 → 插件 → 插件配置 ────────────────────────────────┐
│  终端            Agent 循环        网页搜索             │
│  ┌──────────────────────────────────────────────────┐  │
│  │ 生图配置   配置第三方生图 API；对话里提到「生图」│  │
│  │            即可自动生成。          ▾              │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

• 设置卡片：设置 → 插件 → 插件配置 里多一张「生图配置」卡片，填接口类型 / 地址 / 模型 / Key / 默认尺寸 / 张数 / 产物目录，保存即热生效。
• 对话召唤：装好配置后，直接在对话框说「生图：一只橘色小猫坐在窗台上」即可；也可以 $dsh-imagegen 显式召唤技能。
• 自动触发：当你提到 生图 / 画图 / 出一张图 / 文生图 / 改背景 等需求时，模型会自动加载 dsh-imagegen skill 并调用 image_generate 工具。
• 一键配置：生图 API 与主对话模型同一服务商时，对 agent 说一句「复用主模型配置生图，模型是 <模型ID>」即可——imagegen_configure {fromMainModel:true} 自动复用主模型的服务地址与 key 凭据，只补模型 ID，无需重复填地址和 Key。
• 四种接口类型：
  • openai —— OpenAI 兼容 /v1/images/generations（文生图）与 /v1/images/edits（图生图 / 局部重绘 / 指令编辑）。覆盖 OpenAI、OpenRouter、硅基流动等绝大多数端点；
  • dashscope —— 阿里百炼通义万相（wanx*）异步任务模式（提交 → 轮询任务 → 取图）；
  • replicate —— Replicate /predictions 异步任务（模型 ID 形如 owner/name:version）；
  • fal —— fal.ai 队列异步任务（模型 ID 即队列子路径）。
  • 除 OpenAI 兼容外都只走文生图（改图需要公开图片 URL，暂不支持本地文件）。
• 产物落盘：生成的图片保存为 <会话工作区>/<产物目录>/<时间戳>-<序号>.png，工具返回绝对路径。
• 对话里直接看到图：生图 API 返回的临时 https 链接会随工具结果给出（viewableUrls），模型在回复里用 Markdown 展示——对话流里直接出现图片（点击放大），不依赖宿主版本；链接过期后对话里的图失效属正常，落盘文件是最终版本。图片同时进入模型上下文，后续轮次模型「看得到」刚生成的图（「改一下刚才那张」可直接引用）。端点只返回 b64（无 URL）时，回复里给文件绝对路径。

安装

需要已有一个 DSH web 部署（dsh web 或桌面版）。

# 方式一：本仓库目录（默认；开发期 link: 软链安装，改动即时生效）
bash scripts/install.sh

# 方式二：发布后（npm / GitHub）
bash scripts/install.sh dsh-imagegen-plugin@1.0.0
bash scripts/install.sh git+https://github.com/<owner>/dsh-imagegen-plugin.git

等价的手工步骤（-w 必需：profile 是 pnpm workspace 根）：

dsh plugin --profile web add -w /path/to/dsh-imagegen-plugin

然后重启 DSH。 重启后：

1. 设置 → 插件 → 插件配置 出现「生图配置」卡片（本插件启动时幂等地把 imagegen 命名空间加入 Web 设置页的 api-proxy 白名单，故卡片在 下一次 启动生效）；
2. ~/.dsh/skills/dsh-imagegen/SKILL.md 写入（生图技能，模型目录可见）；
3. image_generate / imagegen_status / imagegen_test / imagegen_configure 四个工具注册进会话。

配置

卡片（推荐）

设置 → 插件 → 插件配置 → 生图配置：

字段	说明
接口类型	OpenAI 兼容（默认）/ 阿里百炼 DashScope / Replicate / fal.ai
接口地址	默认空，由你填写；OpenAI 兼容端点通常以 /v1 结尾。留空时百炼 / Replicate / fal.ai 使用官方默认地址（切换类型且该栏为空时自动预填）
模型 ID	端点提供的模型名称（格式按各家文档），文生图与改图都用它。如 gpt-image-1、flux-dev、wanx2.1-t2i-turbo
API Key	存凭据服务（固定条目 DSH_IMAGEGEN_API_KEY），不写入设置文件；已配置时输入框保持密文并显示「已配置」标签（跨页面刷新 / 宿主重启保持；读取失败会自动重试修复）。改 Key：点击输入框 → 密文清除 → 填新 Key → 保存，即以最新值为准。想复用主模型已有的 Key？不用碰这张卡片——直接对 agent 说「复用主模型配置生图，模型是 <ID>」
默认尺寸 / 默认张数	每次生成未显式指定时的兜底值
产物目录	相对会话工作区，默认 imagegen/

对话配置（免点页面，也是复用已有 Key 的唯一入口）

同一服务商（最常见）——对 agent 说：

复用主模型配置生图，模型是 qwen-image

agent 调用 imagegen_configure {fromMainModel:true, model:"qwen-image"}：自动读取主模型 provider 的 baseURL 与 key 凭据名写入生图配置，一步完成（卡片里会显示复用后的值与「已配置」标签）。

完全手动——直接对 agent 说：

配置生图：接口 openai，地址 https://api.example.com/v1，模型 gpt-image-1，Key sk-xxxx

agent 会调用 imagegen_configure 写入并（建议）用 imagegen_test 验证。

环境变量

DSH_IMAGEGEN_API_KEY（或 apiKeyEnv 指定的同名变量）——共享部署下比把 Key 写进凭据库更稳妥。

使用示例

你：生图：一只橘色小猫坐在窗台上，午后阳光，电影感
agent：（调用 image_generate，约 6s）
       ![1](/…/工作区/imagegen/2026-08-17-09-55-00-1.png)

你：把这张图改成黄昏油画质感，改动大一点
agent：（image_generate + image=上一步路径 + strength=0.7）

你：把背景换成海边，其他都别动
agent：（image_generate + edit=true，指令编辑，用已配置的模型）

工具清单

工具	作用
image_generate	文生图（prompt）/ 图生图（image+strength）/ 局部重绘（image+mask）/ 指令编辑（image+edit:true）；可选 size n negativePrompt seed steps；成功时结果内联展示图片（可点击放大）并返回绝对路径
imagegen_status	查看当前配置就绪度、Key 来源层、主模型信息（mainModel）、一键复用建议（reuseHint）、内联展示能力（inlineImages）、skill / 白名单补丁安装情况
imagegen_test	连通性 + 鉴权 + 模型是否在端点列表
imagegen_configure	对话中热配置 api / baseURL / model / apiKey / apiKeyEnv（复用已有凭据）/ fromMainModel:true（一键复用主模型服务商）

工作原理

• host 半（lib/index.js）：注册 imagegen 设置命名空间（schema 默认值 → cordis 入口 base → ~/.dsh/settings.yaml 用户层，三层解析、热更新）；注册 4 个工具；启动时做两件幂等的自举——
  1. api-proxy 白名单补丁：DSH 的 Web 设置页只服务 dsh-host-apiproxy 白名单内的命名空间（白名单是 host 代码而非插件声明），本插件在启动时向所有已知安装位置（当前运行的宿主、桌面版、npx 缓存、profile pnpm store）的 WEB_SETTINGS_NAMESPACES 数组幂等插入 "imagegen"；已补丁的文件跳过，结构变化的版本跳过并记日志。
  2. skill 安装：把 SKILL.md（内嵌于包内）写入 ~/.dsh/skills/dsh-imagegen/，使生图技能进入模型目录——它的 description 命中 生图/画图 等关键词时由模型自动加载，user-invocable 默认可 $dsh-imagegen 召唤。
• client 半（lib/client.js）：向 settings.plugin.item 槽注册「生图配置」卡片，表单模型与核心插件卡片一致：暂存编辑、保存时经 settings.mutate（带 revision 栅栏）写回、Key 走 credentials 域（不回传明文）。
• BYO endpoint：插件不内置任何厂商密钥；OpenAI 兼容模式兼容 url / b64_json / 裸图片响应三种返回形态，改图走 multipart FormData。

文件结构

dsh-imagegen-plugin/
├── lib/
│   ├── index.js      # host 半：设置命名空间 + 4 个工具 + 启动自举
│   └── client.js     # client 半：「生图配置」卡片
├── scripts/install.sh
├── cordis.patch.yml  # bundle 声明（dsh.plugin CLI 自动挂载用）
├── package.json      # dsh.bundle.patch + dsh.client 声明
├── README.md
└── LICENSE

卸载

dsh plugin --profile web remove dsh-imagegen-plugin   # 移除依赖与挂载
rm -rf ~/.dsh/skills/dsh-imagegen                     # 移除技能（可选）

api-proxy 白名单里的 "imagegen" 行保留无害（命名空间不再注册时不渲染任何卡片）。

FAQ

• 第一次生图报「未配置」？ 这是预期路径：对 agent 说「复用主模型配置生图，模型是 <ID>」（同一服务商时一步到位），或在「设置 → 插件 → 插件配置 → 生图配置」卡片里填写（卡片未配置时会直接给出这条提示）。
• 重启后卡片没出现？ 对话里让 agent 跑 imagegen_status，看 apiproxy 段的 skipped 原因（通常是 DSH 版本结构变化，锚点失配）；或确认 dsh-host-apiproxy 版本仍是 rc.6 一系。
• 保存卡片报「本部署没有接受这些值」？ 多半是 n 超出 1-4 或 api 填了非法值；修正后重新保存。
• model_not_allowed？ 你的端点密钥有模型白名单且不含该生图模型：在服务商控制台重建包含该模型的密钥。
• 想加新的接口协议？ 在 lib/index.js 里照 dashscopeText2Image 的模式加一个分支 + 卡片下拉项即可。
• 对话报「本轮运行失败 API key is invalid」？ 流程始终是：主对话模型（设置 → 模型，如 qwen3.8-flash）先理解「生图：…」，再调 image_generate 走生图 API。这个 401 是主模型的 key 问题（比如该 key 在服务商侧只开了生图 API 分组、没开对话模型分组），与生图 key 无关——给主模型 key 加上对话模型权限即可。生图 key 只对 image_generate 生效，两个 key 可以不同。

发布到 GitHub

1. 把 package.json 里 repository.url 改成你的仓库地址；
2. git init && git add -A && git commit -m "dsh-imagegen-plugin 0.4.3"；
3. 推仓库后，使用者 bash scripts/install.sh git+https://github.com/<owner>/dsh-imagegen-plugin.git，或 npm publish 后按版本安装。

License

MIT