轻量生图 yupaoa/dsh-image-lite

dsh-image-lite

DSH 生图插件支持双模式生图：

- 对话模式：直接和对话模型说「画一张…」，模型调用 image_generate_lite 工具把图生出来；说「改这张 / 参考刚才那张」时自动带参考图，支持链式图生图。
- 工作台模式：在侧边栏「生图工作台」里手动处理生图任务——挑参考图、换模型与比例、写描述、出图后继续迭代，全程不占对话轮次。

两种模式共用同一份模型库与快速配置（插件入口 image-gen-lite，volatile 热生效），自包含、无外部依赖，密钥经 DSH 核心凭据服务解析。

环境要求：DSH >= 0.2.1-rc.2，Node.js ^22.19.0 || >= 24.0.0（随宿主）。
低于该版本的 DSH 不保证可用：本插件依赖的 configForms、右栏标签注册等接口在 0.2.1 系列才稳定。

两种生图模式

一、对话模式：让大模型直接生图

在任意会话里说「画一张/出个图/来张 16:9 的」，对话模型会自动调用 image_generate_lite：

- 不带参考图 → 文生图；
- 说「把这张改成…/参考刚才那张」 → 带 referenceImages 图生图；
- 结果文本内嵌 refs JSON，下一轮可以继续「用这张继续」，链式迭代不断档。

二、工作台模式：侧边栏「生图工作台」

会话 header 的「生图」角标（或右栏引导卡片）打开右栏 tab：

- 参考图：本会话最近结果「用这张继续」/ 上传 / 粘贴（经 attachment admission）；
- 换模型、选比例——实时调整，写入同一入口，热生效；
- 描述 → 生成 → 结果图库 + 灯箱 → 选中结果继续迭代；
- 右上角红色「清空」一键复位参考图、描述与结果。

共用配置：插件页 → dsh-image-lite → 插件配置（plugins.bundle.config 卡片）

- 模型库：增删改供应商/模型（name / baseUrl / 接口格式 / 密钥环境变量 / 模型列表，每行 id 或 id 显示名）。
- 快速配置：默认模型 + 默认图片规格（7 档比例 + auto），下一次 image_generate_lite 调用即生效。
- 图片存放位置：留空即 <会话工作区>/generate/image，也可填绝对路径，并可用「打开文件夹」调用系统选择器。
- 侧边栏 · 在侧边栏中使用生图工作台（开关，默认开）：关闭立即隐藏右栏「生图工作」标签、它的引导卡片与会话 header 的「生图」按钮（image_generate_lite 工具不受影响）；重新开启后刷新窗口即恢复。

这些设置存在哪里

| 内容 | 存放位置 |
| 模型库（供应商、模型列表）、默认模型、默认图片规格、图片存放位置、侧边栏开关 | DSH profile 配置里的插件入口 image-gen-lite（本机实测落盘为 ~/.dsh/profiles/<profile>/cordis.patch.yml 的 image-gen-lite 段，volatile 热生效） |
| API 密钥 | DSH 凭据服务，按环境变量名索引（本机实测为 ~/.dsh/.credentials.yaml，权限由 DSH 管理）；插件配置里只留变量名与掩码，如 IMAGE_GEN_AGNES_API_KEY / sk-m0RPD |
| 生成的图片 | <会话工作区>/generate/image/，或你在「图片存放位置」里指定的目录 |

也就是说：换台机器只要带上 profile 配置与凭据存储，模型库和密钥就跟着走；这两处都不在本插件目录里，卸载插件不会删掉它们。

工作原理

工作原理

两种入口共用同一条链路，插件本体只做四件事：读设置 → 换密钥 → 发一次请求 → 把图存下来。

1. 入口：对话模式由对话模型调用工具 image_generate_lite；工作台模式由客户端通过本地 RPC（挂在 DSH 现有 web server 的 /image-gen-lite/ 前缀下，受 DSH 自身登录令牌保护）请求同一套逻辑。
2. 读设置：从插件入口 image-gen-lite 取供应商 baseUrl、apiFormat、默认模型与图片规格、输出目录、侧边栏开关；这些值存在 profile 配置里，改完下一次调用即生效（volatile）。
3. 换密钥：配置里只有环境变量名（如 IMAGE_GEN_AGNES_API_KEY）和掩码，真正的密钥由 DSH 凭据服务按名字解析，插件进程里不落明文、不写日志。
4. 发请求：按 openai-images 约定向 {baseUrl}/images/generations 发一次 HTTPS；图生图时把参考图内联成 image data URL 放在同一个请求里（本机实测该供应商只支持这种写法）。
5. 取回并落盘：响应里的 b64_json 直接解码，或者按返回的 url 下载一次；随后 mkdir -p 输出目录并写文件，再登记进会话附件——所以下一轮能「用这张继续」。

权限与文件边界

| 类别 | 具体行为 |
| 读 | ① 插件入口 image-gen-lite 的配置；② 你在会话里显式传入的参考图附件（attachments.readImage，只认传进来的图）；③ 已生成的图片文件——路径白名单：仅 <会话工作区>/generate/image 与你在插件页「图片存放位置」里填的目录，越界一律报 path is not a generated image file |
| 写 | ① 图片：mkdir -p 输出目录后写 lite-image-<时间戳>-<随机>.png（按实际 MIME 取扩展名）；② 配置：经 DSH 配置表单写 profile 里的插件入口（本机实测落盘为 ~/.dsh/profiles/<profile>/cordis.patch.yml 的 image-gen-lite 段）；③ 密钥：经 DSH 凭据服务写入（本机为 ~/.dsh/.credentials.yaml），插件配置里只保留 sk-m0RPD 这样的掩码 |
| 网络 | 只有两个出口：你配置的供应商 baseUrl（如 https://api.agnes-ai.cn/v1），以及供应商返回结果图的那个 URL（通常同域名）。没有遥测、没有第三方上报、不访问其它站点、不新开监听端口 |
| 不做 | 不执行 shell 命令、不遍历或上传工作区其它文件、不改 DSH 源码、不安装额外依赖（package.json 里除 DSH 自带包外无 runtime 依赖）、不常驻后台任务 |

一句话：只读你显式给它的图，只写你指定的目录，只连你配置的域名。

卸载插件不会删除已生成的图片与已存进凭据服务的密钥；要彻底清理，删除 profile 配置里的 image-gen-lite 段、凭据里的对应环境变量名，以及你指定的输出目录。

安装

需要 DSH >= 0.2.1-rc.2（Node.js ^22.19.0 || >= 24.0.0，随宿主提供）。

方式一：从 npm 安装（推荐）

从 npm registry 安装到 desktop profile：
dsh plugin --profile desktop add dsh-image-lite

版本、文件清单与发布记录见 <https://www.npmjs.com/package/dsh-image-lite>。由仓库内 .github/workflows/release.yml（GitHub OIDC）发布的版本会额外附带 provenance 溯源证明；0.1.0 是本地 npm publish 发布的，暂无该证明。

方式二：从本地源码安装（开发 / 改代码时）

从 DSH 桌面端 CLI / 插件页安装本地包（link: 方式）：
dsh plugin --profile desktop add link:D:\path\to\dsh-image-lite

两种方式装的是同一个插件，包内 cordis.patch.yml 会自动挂载 image-gen-lite 入口，不需要手改 profile 配置。区别只有一点：link: 方式指向源码目录，改完代码刷新窗口即可生效；npm 方式装的是发布快照，升级靠重新执行 add。

重启 DSH（或 HMR 生效时自动重组合）后：

1. 插件页 → dsh-image-lite：添加供应商/模型、粘贴密钥，选默认模型与规格；
2. 对话模式：在会话里说"画一张…"即自动调用 image_generate_lite；
3. 工作台模式：会话 header 出现「生图」角标，点开即右栏「生图工作」tab （插件页该卡片里的「侧边栏」开关可把它连同角标一起关掉）。

密钥直接在 插件页 → dsh-image-lite 的供应商卡片里粘贴（存进 DSH 凭据服务，配置里只留环境变量名与掩码，如 IMAGE_GEN_AGNES_API_KEY / sk-07890）。

开发

node test/wire.test.js # 纯函数单测（比例映射/回退、wire 体、refs 校验）
node test/client-wiring.test.js # client 接线 + 模型库纯函数

测试不需要任何外部服务或密钥；index.js / client.js / wire.js 三个入口的分工见源码顶部注释。

dsh-image-lite 是 DeepSeek Harness（DSH）的图像生成插件，提供两种生成方式：

- 对话模式 —— 直接告诉聊天模型「画一张…」。模型会替你调用 image_generate_lite 工具；说「改这张」/「用上一张图」，它会自动传入参考图，这样你就能链式迭代。
- 工作台模式 —— 在右侧边栏的 Image Studio tab 里手动操作：挑参考图、切换模型与宽高比、写提示词，然后在图库里继续迭代。它从不消耗对话轮次。

两种模式共用一套模型库和一套默认值（插件入口 image-gen-lite，易变 / 热重载）。插件自包含，没有 runtime 依赖，API 密钥通过 DSH 的凭据服务解析。

要求：DSH >= 0.2.1-rc.2，Node.js ^22.19.0 || >= 24.0.0（由宿主提供）。
不支持更旧的 DSH 版本：本插件依赖的 configForms 与右侧边栏 tab API 到 0.2.1 系列才稳定下来。

两种模式

1. 对话模式 —— 让模型生成

在任何对话里说「画一张图」「生成一张图」「来一张 16:9 的…」；模型会调用 image_generate_lite：

- 没有参考图 → 文生图；
- 「改这张图」/「参考上一张图」→ 通过 referenceImages 走图生图；
- 每条结果都带一行 refs JSON，下一轮可以接着它继续。

2. Studio 模式 —— 侧边栏 Image Studio

从会话头部的「生图」按钮（或引导卡片）打开右侧标签页：

- 参考图：复用本会话最新结果、上传，或粘贴（走附件准入）；
- 切换模型和宽高比 —— 实时生效，写入同一条目并热重载；
- 提示词 → 生成 → 画廊 + 灯箱 → 选一张结果继续编辑；
- 右上角红色 Clear 按钮，一键重置参考图、提示词和结果。

共享设置 —— Plugins 页面 → dsh-image-lite → 插件配置 （plugins.bundle.config 卡片）

- 模型库：增删改服务商和模型（名称、baseUrl、API 格式、密钥环境变量、模型列表 —— 每行一个 id 或 id 显示名）。
- 快速配置：默认模型 + 默认宽高比档位（7 种比例 + auto），供下一次 image_generate_lite 调用使用。
- 图片文件夹：留空表示 <session workspace>/generate/image；也接受绝对路径，「打开文件夹…」按钮会唤起系统目录选择器。
- 侧边栏 · 在侧边栏使用 studio（开关，默认开启）：关掉后立即隐藏「生图工作」标签页、对应引导卡片和头部按钮（image_generate_lite 照常可用）；重新打开后刷新窗口即可恢复。

这些设置存在哪

| 内容 | 位置 |
| 模型库、默认模型、默认宽高比、图片文件夹、侧边栏开关 | DSH 配置档配置里的插件条目 image-gen-lite（本机观察到的是 ~/.dsh/profiles/<profile>/cordis.patch.yml 中的 image-gen-lite 段；易变，热重载） |
| API 密钥 | DSH 凭据服务，按环境变量名索引（观察到的是 ~/.dsh/.credentials.yaml，由 DSH 管理）；插件配置里只保留环境变量名和掩码，如 IMAGE_GEN_AGNES_API_KEY / sk-m0RPD |
| 生成的图片 | <session workspace>/generate/image/，或你在图片文件夹里设置的目录 |

换句话说：把配置档配置和凭据存储搬到另一台机器，模型库和密钥就跟着走 —— 两者都不在插件目录里，卸载插件也不会删掉它们。

工作原理

工作原理

两个入口共用同一条流水线；插件本身只做四件事： 读设置 → 解析密钥 → 发一次请求 → 保存图片。

1. 入口：聊天模式调用工具 image_generate_lite；studio 模式通过本地 RPC 调用同一套逻辑（挂载在 DSH 现有 web 服务器的 /image-gen-lite/ 下，由 DSH 自己的会话 token 保护）。
2. 读设置：baseUrl、apiFormat、默认模型、宽高比档位、输出文件夹和侧边栏开关都来自插件条目 image-gen-lite，存放在配置档配置——改动只对下一次调用生效（易失）。
3. 解析密钥：配置里只存环境变量名（如 IMAGE_GEN_AGNES_API_KEY）和掩码；真实密钥由 DSH 凭据服务按名称解析。插件从不写入明文密钥，也不记录密钥。
4. 发送：按 openai-images 约定，向 {baseUrl}/images/generations 发一条 HTTPS 请求；图生图时，参考图以 image data URL 内联在同一请求里。
5. 获取并保存：解码响应里的 b64_json，或下载返回的 url 一次；然后 mkdir -p 创建输出目录，写入文件，并登记为会话附件——所以下一轮说「用这张」能生效。

权限与文件边界

| 方面 | 实际行为 |
| 读取 | (1) 插件条目 image-gen-lite 的配置；(2) 你在会话里显式传入的参考图附件（attachments.readImage）；(3) 已生成的图片文件——路径白名单：仅 <session workspace>/generate/image 和 Image folder 下设置的目录；其他路径一律报错 path is not a generated image file |
| 写入 | (1) 图片：mkdir -p 创建输出目录，然后写入 lite-image-<timestamp>-<random>.png（扩展名取自实际 MIME 类型）；(2) 配置：经 DSH 的配置表单写入配置档配置里的插件条目；(3) API 密钥：经 DSH 的凭据服务——插件配置只保留掩码，如 sk-m0RPD |
| 网络 | 只有两个目标：你配置的服务商 baseUrl（如 https://api.agnes-ai.cn/v1），以及服务商返回结果图时给出的 URL（通常同一主机）。无遥测、无第三方上报、无其他主机、无监听端口 |
| 绝不 | 不执行 shell 命令，不遍历或上传其他工作区文件，不修改 DSH 自身，不引入额外依赖（package.json 除 DSH 自带包外无运行时依赖），不启动后台常驻进程 |

一句话：只读你交给它的图片，只写你选的目录，只与你配置的域名通信。

卸载插件不会删除已生成的图片，也不会删除凭据服务里已存的密钥。要彻底清理，请从配置档配置里删掉 image-gen-lite 段，从凭据存储里删掉对应的环境变量条目，再删掉你的输出目录。

安装

需要 DSH >= 0.2.1-rc.2（Node.js ^22.19.0 || >= 24.0.0，由宿主提供）。

方式 1——从 npm 安装（推荐）：

Install into the desktop profile straight from the npm registry:
dsh plugin --profile desktop add dsh-image-lite

版本、文件列表和发布记录见 <https://www.npmjs.com/package/dsh-image-lite>。
由 .github/workflows/release.yml（GitHub OIDC）产出的发布还带有 provenance 证明；0.1.0 是本地用 npm publish 发布的，没有该证明。
方案二 —— 从本地检出安装（用于开发）：

Install the local package from the DSH desktop CLI or the Plugins page (link:):
dsh plugin --profile desktop add link:D:\path\to\dsh-image-lite

两种方式安装的是同一个插件；插件自带的 cordis.patch.yml 会自动挂载 image-gen-lite 入口，所以不需要改配置档。唯一区别：link: 指向你的源码目录（改完刷新窗口即可），npm 方式安装的是已发布快照（再跑一次 add 即可升级）。

重启 DSH 之后（或等 HMR 重新分组 bundle 之后）：

1. 插件页 → dsh-image-lite：添加服务商/模型，粘贴密钥，选默认模型和宽高比停靠项；
2. 聊天模式：在对话里说「给我画……」—— 会自动调用 image_generate_lite；
3. 工作室模式：会话头部会出现「生图」按钮；点击后打开右侧边栏的「生图工作」标签页（同一张卡片上的侧边栏开关可以把两者都隐藏）。

把密钥直接粘贴到插件页的服务商卡片里：密钥会进入 DSH 的凭据服务，配置里只保留环境变量名和掩码，例如 IMAGE_GEN_AGNES_API_KEY / sk-07890。

开发

node test/wire.test.js # pure helpers (aspect fallback, wire bodies, ref validation)
node test/client-wiring.test.js # client wiring + model-library helpers

测试不需要网络、密钥或外部服务。index.js、client.js 和 wire.js 各自的职责写在对应文件顶部。