dsh-image-reader

English | 中文 | GitHub

一个不依赖第三方 npm 包的 DSH（DeepSeek Harness）插件，让只支持文本的模型也能“看懂”图片。

它通过 DSH 的 ctx.llm 服务调用视觉模型，不会把图片塞给当前文本模型，也不会要求切换主模型：

• 允许当前文本模型接收图片附件：advertiseImage 会让 DSH 的图片准入与 Web UI 认为当前模型支持图片，避免出现“当前模型不支持图片，请切换模型”。
• 自动识别用户附加的图片：在 agent/pre-step 阶段发现用户消息里的 ImageBlock，用视觉模型生成文字描述，并作为插件上下文追加到同一步。主文本模型实际不会收到图片，适配器会把它投影成占位文本，因此不会报 UNSUPPORTED_CONTENT。
• 自动识别工具返回的图片：tools/post-execute 会处理 read_image 等工具结果里的图片，把视觉描述追加到工具结果中。
• 提供 describe_image 工具：模型可以读取本地 PNG/JPEG/WebP/GIF 文件，调用视觉模型后返回文字描述/OCR 结果。它与内置 read_image 不冲突；内置工具需要当前模型支持图片输入，本工具专门补足文本模型场景。

默认使用 DeepSeek 官方适配器内的视觉模型：

provider: deepseek-official
model:    deepseek-v4-flash-vision-exp

因此通常直接复用 DSH 已经配置好的 DEEPSEEK_API_KEY，无需另配 OpenAI Key。

安装

方式一：作为 DSH bundle 安装（推荐）

包内已经提供 package.json 的 dsh.bundle.patch 和 cordis.patch.yml，可以直接被 dsh plugin 安装：

# 从 npm 安装
dsh plugin --profile web add dsh-image-reader

# 或从 GitHub 安装
dsh plugin --profile web add github:wang90/dsh-image-reader

# 或安装本地 checkout
dsh plugin --profile web add ./dsh-image-reader

安装后重启 DSH Web。

方式二：手动 profile patch

把下面一行加入 $DSH_HOME/profiles/web/cordis.patch.yml（路径按实际 clone 位置调整）：

- insert:
    - id: image-reader
      name: '/absolute/path/to/dsh-image-reader/image-reader.mjs'
      config:
        advertiseImage: true
        describeToolImages: true

patchReload: live 的 profile 会在保存 patch 后热加载插件；普通启动则重启 DSH Web 后生效。

使用

1. 用户直接附加图片

直接在 Web UI 里附加图片并发送。主模型收到请求前，插件会：

1. 找到消息中的图片附件；
2. 调用 deepseek-v4-flash-vision-exp 识别；
3. 把识别结果作为一条 plugin 来源的上下文插入用户消息之后；
4. 主模型继续按原来的文本模型运行。

原始图片仍保存在会话历史中；以后切换到支持视觉的模型时仍然可以直接查看原图。

2. 模型读取本地图片

模型可以调用：

{
  "file_path": "/path/to/image.png",
  "prompt": "只看左上角的报错信息，逐字转录"
}

返回：

{
  "text": "视觉模型给出的描述/OCR 结果",
  "model": "deepseek-official/deepseek-v4-flash-vision-exp",
  "path": "...",
  "mediaType": "image/png",
  "bytes": 12345,
  "width": 800,
  "height": 600
}

相对路径按当前会话工作区解析，并使用 ctx.fs，因此仍受文件系统 sandbox 约束。

配置

在 patch 的插件行里可加 config：

- insert:
    - id: image-reader
      name: '/absolute/path/to/dsh-image-reader/image-reader.mjs'
      config:
        provider: deepseek-official
        model: deepseek-v4-flash-vision-exp
        auto: true
        tool: true
        cache: true
        skipVisionModel: true
        advertiseImage: true
        describeToolImages: true
        maxImagesPerStep: 8
        maxOutputTokens: 2048
        timeoutMs: 120000
        maxDescriptionChars: 12000
        maxToolImageBytes: 20971520
        reasoningEffort: 'off'
        prompt: |
          请仔细识别并描述这张图片……

全部字段都有默认值；只在需要时覆盖即可。

字段	默认值	说明
provider	deepseek-official	调用视觉模型的 DSH provider
model	deepseek-v4-flash-vision-exp	必须是声明了 image input modality 的模型
auto	true	是否自动识别用户附加图片
tool	true	是否注册 describe_image 工具
cache	true	同一附件同一提示词是否复用识别结果
skipVisionModel	true	如果当前主模型真实能力本身支持图片，则跳过自动识别，避免重复处理
advertiseImage	true	让 DSH 认为当前文本模型也接受图片，从而允许 Web UI/API 提交图片；实际图片会由本插件转成文字描述
describeToolImages	true	自动识别工具结果里的图片，例如内置 read_image 返回的图片会追加文字描述
maxImagesPerStep	8	单步最多自动识别几张图片
maxOutputTokens	2048	视觉模型输出 token 上限
timeoutMs	120000	单次视觉调用超时
maxDescriptionChars	12000	注入上下文的单图描述长度上限
maxToolImageBytes	20971520	describe_image 读取的原始文件大小上限，同时受附件服务限制
reasoningEffort	off	辅助视觉调用的推理档位，off 可降低成本与延迟
prompt	内置中文识别提示词	视觉模型提示词

也支持环境变量：DSH_IMAGE_READER_PROVIDER、DSH_IMAGE_READER_MODEL、DSH_IMAGE_READER_AUTO 等，名称可由字段名推导。

失败行为

• 视觉调用失败时，自动路径不会中断当前 turn，而是把失败信息作为插件上下文注入，让主模型可以如实告诉用户。
• describe_image 工具失败时，按普通工具错误返回。
• 如果 provider / model 配错，错误信息会包含视觉调用的失败原因，便于在 DSH 模型设置中修正。

安全与数据

• 自动路径直接复用附件服务中已经持久化的图片，不会把 base64 写进会话日志。
• describe_image 读取文件后会调用 ctx.attachments.saveImage 做持久化，然后调用视觉模型。附件服务本身只接受 PNG/JPEG/WebP/GIF，并执行尺寸/字节校验。
• 文件读取通过 ctx.fs，遵守当前会话的文件系统策略。