alanzhao0128/dsh-image-plugins

dsh-image-plugins

npm version

为 DeepSeek Harness（dsh）在纯文本主模型（例如 DeepSeek 官方聊天路由，无法携带图像）背后提供多模态能力。该插件通过完全可配置的端点理解图像文件并生成图像——为你自己的视觉模型和图像生成模型提供 baseUrl / apiKey / model。任何 OpenAI 兼容端点均可使用；可选的 dashscope 适配器支持阿里云百炼原生 API。

一切都是可选的：只有当对应的配置块存在时，某项能力才会被启用，因此未配置的安装是惰性且安全的。包中不附带任何 API 密钥——每位用户配置自己的密钥。

它提供什么

| 能力 | 类型 | 行为 |
|---|---|---|
| understand_image | 模型工具 | 读取工作区中的图像文件，将其发送到你的视觉端点（chat/completions + base64 image_url），将模型的文本描述作为工具结果返回。该描述进入会话日志，因此纯文本主模型无需接收图像即可对图像进行推理。 |
| generate_image | 模型工具 | 通过你的端点根据提示词生成图像，将其保存到工作区，返回保存路径。使用 dashscope 提供方时，它还接受可选的 reference_image 用于图像编辑（I2I）。 |

自动理解（V2）：已实现但已禁用

该插件包含一个休眠的 agent/pre-step 重写（配置标志 autoUnderstand，默认关闭）：启用后，附加到聊天消息的图像会由视觉模型描述，消息在进入会话日志之前会被重写为携带该文本，因此主模型永远不会收到图像块。该代码已通过单元测试，但从未在实时会话中进行端到端验证，且不属于受支持的表面。

为什么它被禁用：将图像附加到聊天消息要求被路由的模型声明 input: [text, image]——宿主会拒绝纯文本模型的附件——而对于纯文本端点（如 DeepSeek 的端点），该声明是一种变通方案：一个端点从未真正兑现的声明，在传输前被重写所抵消。我们认为这不够优雅，因此禁用了该功能。受支持的流程是上述 V1 工具（工作区中的图像文件，无需声明）。未来的粘贴到聊天迭代将改用更轻量的粘贴到路径客户端方案。

快速开始

1. 安装（npm；其他渠道请参见 安装）：

dsh plugin --profile web add dsh-image-plugins

2. 配置——用你自己的端点和密钥（任何 OpenAI 兼容提供方）覆盖你配置文件 cordis.patch.yml 中的 image-plugins 行：

- id: image-plugins
name: dsh-image-plugins
config:
vision:yaml
baseUrl: 'https://your-vision-endpoint.example.com/v1'
apiKey: 'sk-...'
model: 'your-vision-model'
image:
baseUrl: 'https://your-image-endpoint.example.com/v1'
apiKey: 'sk-...'
model: 'your-image-model'
defaultSize: '1024x1024'

3. 重启 dsh web，然后在工作区中：

- 看图：“查看 images/screenshot.png 并告诉我它显示了什么。”
- 生图：“生成一张木桌上放着一个红苹果的图片。”（保存到 generated/）
- 图生图（需 dashscope provider）：“把 images/logo.png 的颜色改成蓝色。”

安装

该插件是一个标准的 dsh bundle。从 npm 安装（推荐）：
sh
dsh plugin --profile web add dsh-image-plugins

其他渠道：
sh
GitHub（固定一个版本；首次安装需要 allowBuilds，见下文）
dsh plugin --profile web add github:alanzhao0128/dsh-image-plugins#v0.1.0

Tarball（npm pack 产物，发送该文件）
dsh plugin --profile web add ./dsh-image-plugins-0.1.0.tgz

本地检出
dsh plugin --profile web add /path/to/dsh-image-plugins

然后重启 dsh web（或该 profile 的进程）。对于 GitHub 安装，pnpm ≥ 10 会拒绝运行该包的构建脚本，直到你在该 profile 的 pnpm-workspace.yaml 中允许它：
yaml
allowBuilds:
dsh-image-plugins: true

然后重新运行 add 命令。npm 和 tarball 安装会附带已构建的产物，无需允许。

该 bundle 会在无配置的情况下插入其行，因此安装后在你配置之前不会启用任何功能。无论哪种方式，插件都能正常加载。

配置

自 0.2.0 起，该插件附带一个设置面板（web：设置 → 图片插件 / Image Plugins）：编辑 vision 和 image 端点块，并通过官方凭据存储管理两个能力密钥。端点编辑的更改会立即生效（无需重启）；主机代码更改在升级后仍需重启 dsh web。

自 0.3.0 起，每个能力组在面板顶部都有一个启用开关：将其关闭后，该工具会被注销（模型再也看不到 understand_image / generate_image），该组的其余部分会被锁定（字段和凭据行变为只读），再将其打开会立即生效——无需重启。

设置面板会写入 ~/.dsh/settings.yaml 中的 dsh-image-plugins 命名空间。两个固定的凭据引用支撑这些能力——面板通过官方凭据接缝将密钥值写入 ~/.dsh/.credentials.yaml，且从不显示已存储的密钥：

| 引用 | 使用者 |
|---|---|
| UNDERSTAND_IMAGE_KEY | understand_image（vision 端点密钥） |
| GENERATE_IMAGE_KEY | generate_image（图像生成端点密钥） |

你也可以手动配置——在你的 profile 的 cordis.patch.yml 中覆盖 image-plugins 行（相同 id），或传入 --patch 覆盖层。patch 值充当初始（基础）层；一旦你从面板保存，settings.yaml 的值就会胜出：
yaml
- id: image-plugins
name: dsh-image-plugins
config:
vision:
enabled: true                  # 0.3.0：能力开关，默认 true
baseUrl: 'https://your-vision-endpoint.example.com/v1'
apiKey: 'env:VISION_API_KEY'   # 字面密钥、env:NAME 或 cred:NAME（见说明）
model: 'your-vision-model'
timeoutMs: 60000               # 可选
maxImageBytes: 20971520        # 可选，字节
systemPrompt: ''               # 可选，在图像之前发送
defaultPrompt: ''              # 可选，当模型未给出提示词时使用
image:
enabled: true                  # 0.3.0：能力开关，默认 true
provider: 'openai'             # 'openai'（默认）或 'dashscope'
baseUrl: 'https://your-image-endpoint.example.com/v1'
apiKey: 'env:IMAGE_API_KEY'
model: 'your-image-model'
timeoutMs: 120000              # 可选
defaultSize: '1024x1024'       # 可选
outputDir: 'generated'         # 可选，相对于工作区

说明：

- 每个块相互独立：可以只配置 vision、只配置 image，或两者都配置。部分填写的块（例如只有 baseUrl 而没有 apiKey）会导致加载明显失败。
- 自 0.3.0 起，每个块都接受 enabled: true|false（默认 true）。当为 false 时，该工具不会被注册——模型永远看不到它，也无法调用它（在开关切换的瞬间已派发的进行中调用也会失败关闭）——并且设置面板会锁定该组的其余部分。在面板中重新打开开关会立即重新启用该工具，无需重启。
- apiKey 接受三种形式：
- 字面密钥（'sk-...'），
- env:VARNAME——在加载时从进程环境解析，
- cred:NAME——在每次请求时通过宿主凭据接缝（ctx.credentials，例如 ~/.dsh/.credentials.yaml）解析（凭据服务可能在插件加载之后才启动，因此解析被推迟到请求路径）。需要宿主的凭据服务（标准 dsh 配置文件中已提供）。
- 使用设置面板时，apiKey 会自动成为固定的 cred:UNDERSTAND_IMAGE_KEY / cred:GENERATE_IMAGE_KEY 引用——面板通过凭据服务写入密钥值，因此你无需手动处理引用。
- 密钥永远不会进入会话日志或工具结果。
- 配置文件补丁按 id 定位行并替换其整个配置——请重新声明你需要的每一个键。
- 端点必须与 OpenAI 兼容：vision = POST {baseUrl}/chat/completions，接受 image_url 数据 URL；图像生成 = POST {baseUrl}/images/generations，返回 data[0].b64_json 或 data[0].url。任何兼容的服务——OpenAI、硅基流动、智谱、通义兼容模式、Ollama 等——均可直接使用。

DashScope（阿里云百炼）
DashScope 的兼容模式路径不提供 images/generations（会返回 404），因此图像生成通过 provider: 'dashscope' 使用原生 Model Studio API。视觉（understand_image）通过兼容模式的 chat/completions 路径与任何 VL 模型配合工作。两者共用同一个 API key：

- id: image-plugins
name: dsh-image-plugins
config:
vision:
baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
apiKey: 'sk-...'                # 百炼 API Key
model: 'qwen3.7-flash'          # 任意 VL 模型（已用 qwen3.7-flash 验证）
image:
provider: 'dashscope'
baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1'  # /v1 或 /compatible-mode/v1 后缀会被规范化去除
apiKey: 'sk-...'                # 百炼 API Key
model: 'qwen-image-3.0-pro'
defaultSize: '1024x1024'        # 会转换为原生的 10241024 形式

图像适配器调用 POST /api/v1/services/aigc/multimodal-generation/generation（同步），映射 output.choices[0].message.content[0].image，并下载 PNG（URL 在 24 小时后过期）。适用于 qwen-image 系列，包括 qwen-image-3.0-pro。

DeepSeek 官方（图像理解）

DeepSeek 的官方端点现在提供一个支持图像的模型 deepseek-v4-flash-vision-exp（dsh ≥ 0.1.1-rc.2 在 deepseek-official 目录中提供该模型）。你可以用 DeepSeek API key 将 vision 指向它——把 key 保存在 ~/.dsh/.credentials.yaml 中，并用 cred: 引用它：

- id: image-plugins
name: dsh-image-plugins
config:
vision:
baseUrl: 'https://api.deepseek.com'
apiKey: 'cred:DEEPSEEK_API_KEY'
model: 'deepseek-v4-flash-vision-exp'

切换前需要了解两件事：

- 该插件以内联 base64 image_url 部分发送图像。 DeepSeek 的官方适配器通常通过其 Files API 上传图像，并以 file_id 引用它们，以避免重复发送字节；而该插件的直接 chat/completions 路径改用内联 data URL。这可以工作（已验证），但重复理解同一张图像会重新发送字节——如果这有影响，对于该端点，优先使用宿主的原生图像输入（选择 deepseek-v4-flash-vision-exp 作为路由模型），而不是此插件。
- 第三方 DeepSeek 兼容渠道可能不携带该视觉模型。 例如，火山方舟（火山方舟）接受该模型 id 用于文本，但会以 400 Model do not support image input 拒绝图像输入（截至 2026-08）。在依赖之前，请先在你的渠道上验证图像输入。

使用参考图像进行图像编辑（I2I）

使用 dashscope provider 时，generate_image 接受一个可选的 reference_image 路径。参考图像（PNG/JPEG/WebP/GIF，≤ 10 MiB，上限可通过 image.maxReferenceBytes 配置）会与提示词一起以 base64 发送给模型：

将 images/logo.png 的颜色改为蓝色，其余部分保持不变。
模型会编辑参考图像，而不是从头生成。openai flavor 没有图像输入，并会以明确的错误拒绝该参数。

使用

理解图像（V1 工具，推荐）

将图像放在工作区中的某个位置，然后询问 agent：

查看 images/screenshot.png 并告诉我它显示了什么。

agent 会使用该路径调用 understand_image，并可选地将具体问题作为 prompt 传入（例如 “这张图中第三行的趋势是什么？”）。

生成图像（V1 工具，推荐）

生成一张木桌上放着一个红苹果的图像。

agent 会调用 generate_image；文件会落在工作区中的 generated/ 下（或你配置的 outputDir），工具结果会报告该路径。

分发

| 渠道 | 安装命令 | 备注 |
|---|---|---|
| npm | dsh plugin --profile web add dsh-image-plugins | 推荐；无需构建许可 |
| GitHub | dsh plugin add github:alanzhao0128/dsh-image-plugins#v0.1.0 | 需要一次性 allowBuilds |
| Tarball | dsh plugin add ./dsh-image-plugins-0.1.0.tgz | 来自 npm pack；安装后可安全删除（之后在 profile 中执行 pnpm install 时可能需要该文件回来） |

它如何保持与 dsh 架构兼容

- 工具通过文档化的 ctx.tools 接缝（@deepseek-ai/dsh-tools 的 defineTool）注册；工具结果是持久日志条目，这正是“模型可见 ⟺ 已记录”不变量所要求的通道。
- 该插件仅依赖已发布的 @deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery；不依赖任何内部模块。

开发

npm install
npm test          # unit tests against mock endpoints + real Cordis mount
npm run build     # tsc -> lib/ (also runs on prepare)

针对临时 profile 进行冒烟验证（不会触碰你的真实 profile）：

DSH_HOME=/tmp/dsh-image-test-home dsh plugin --profile test add /path/to/dsh-image-plugins
DSH_HOME=/tmp/dsh-image-test-home dsh --profile test --dump-config   # shows the layer

已知限制与待办工作

- 二进制写入绕过 fs 审批事件。 fs 接缝目前不暴露二进制写入，因此 generate_image 通过 ctx.fs 解析目标（一致的路径规则、会话工作区 cwd），但使用 node:fs 写入字节。因此该写入不会发出 fs/write-intent 审批事件。当 fs 服务增加该能力时，应切换到接缝写入。
- 视觉响应仅限文本。 该插件以文本形式返回描述；它从不发出图像内容块，因为仅文本路由无法将它们带入下一个请求。
- 尚无内联聊天预览。 生成的图像以路径形式返回，并带有通用工具卡片（该路径可点击打开）。内联预览需要客户端侧的 tool.call.toolview 注册（V1.5，尚未发布）。
- 无视频生成。 计划在选定提供方接口后，作为后台任务能力（ctx.jobs）实现。
- 端点失败时不进行按请求重试/退避；调用方会看到该错误。
- 版本固定。 基于 @deepseek-ai/ 0.1.0-rc.6 构建并测试；dsh 处于开发者预览阶段，预计各版本之间会有破坏性变更。升级宿主后请重新运行 npm test。

许可证

MIT