前言¶
DeepSeek Harness (DSH) 采用插件化架构，扩展行为通常通过挂载钩子实现。在 Web GUI 的交互场景中，用户经常会附加图片。如果底层模型是纯文本模型（例如 DeepSeek），这些图片会被系统默认忽略，导致模型无法理解视觉内容。dsh-image-bridge 插件通过拦截消息组装前的钩子，利用视觉模型将图片转为文字描述，再注入对话，从而让纯文本模型具备“看图”能力。
插件介绍¶
dsh-image-bridge 是一个 DSH 插件，由 Seryta 维护，遵循 MIT 许可证。它主要解决的问题是：当模型不支持图片输入时，自动将 Web GUI 中的图片通过视觉模型（默认使用智谱 GLM-4V-Flash）转录为文字，并替换原图片块进入对话流程。
核心功能¶
该插件在 agent/pre-step 钩子处运行，核心能力包括：
- 拦截与重写：拦截
agent/pre-step瀑布事件，读取消息中的图片内容块（{ type: 'image', attachment: ImageAttachmentRef }），通过ctx.attachments.readImage取出图片字节。 - 自动转录：将图片转为文字描述，并替换原图片块为
[图片描述]文本块。 - 缓存机制：使用
attachmentId作为缓存键，记录已识别的图片描述。同一张图片在后续步骤中不再重复识别（缓存上限 100，FIFO 淘汰）。失败结果不缓存。 - 韧性策略：
- 单模型重试：遇到 429/503 错误时，进行指数退避重试（默认额外 2 次：1s、2s）。
- 模型回退：遇到 404 或重试耗尽（5xx），自动切换到下一个备选模型（默认链：
glm-4.6v-flash → glm-4.1v-thinking-flash → glm-4v-flash）。 - 失败降级：全部尝试失败后，将图片块替换为
[图片识别失败]文本，避免触发UNSUPPORTED_CONTENT导致整轮对话失败。
- 限制与防护：
- 限制图片体积（默认 10MB）和分辨率（默认 40MP），超限直接报错。
- 处理
content parts数组健壮性，网关返回[{text}]数组时按序拼接。 - 剥离 thinking 模型的
</tool_call>推理块。
- 递归处理：支持
tool-result嵌套图片的递归转录。
安装与启用¶
安装命令如下：
dsh plugin --profile web add github:Seryta/dsh-image-bridge
安装完成后，重启 dsh web 进程即可生效。
配置说明¶
插件支持通过环境变量进行配置，主要包括模型选择、重试策略、限流设置等：
| 配置项 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| 主模型名 | IMAGE_BRIDGE_MODEL |
glm-4v-flash |
用于图片转录的视觉模型 |
| 回退模型链 | IMAGE_BRIDGE_FALLBACKS |
glm-4.6v-flash,glm-4.1v-thinking-flash,glm-4v-flash |
逗号分隔，依次尝试 |
| 重试次数 | IMAGE_BRIDGE_RETRIES |
2 |
单模型在 429/503 上的额外重试次数 |
| 描述语言 | IMAGE_BRIDGE_LOCALE |
zh |
zh 中文 / 其他英文 |
| 图片字节上限 | IMAGE_BRIDGE_MAX_IMAGE_BYTES |
10485760 |
超限直接失败，不自动压缩 |
| 图片像素上限 | IMAGE_BRIDGE_MAX_IMAGE_PIXELS |
40000000 |
width×height 超限直接失败 |
凭证读取¶
插件会按顺序尝试以下环境变量读取视觉 API 密钥：
* ZHIPU_API_KEY
* ZHIPUAI_API_KEY
* VISION_API_KEY
* DASHSCOPE_API_KEY
模型限制说明¶
若所选模型声明 inputModalities: ['text']，DSH 会在消息进入循环前拒绝图片。本插件本身不修改模型声明，因此需要配合一个补 image 模态声明的插件（例如 llm-deepseek-image-admit）才能让所有模型支持图片输入。
注意事项¶
- 图片处理：一次消息中的多张图片会合并为一次视觉 API 调用。缓存按有序
attachmentId组合键命中，图片顺序不同则视为新请求。 - 无预处理：图片不做压缩或缩放预处理，仅做体积和像素限制。
- 限流风险：免费档 VLM 可能存在限流问题，插件虽提供重试和回退机制，但仍需关注 API 配额。
- 依赖环境：插件纯手写 JS，零构建、零第三方依赖，但依赖 Node 内置模块。
总结¶
dsh-image-bridge 提供了一个从 Web GUI 到纯文本模型的视觉信息桥接方案。它通过拦截、转录、缓存和降级策略，确保了图片信息能被模型理解，同时保持了对话的稳定性。适合需要在 DeepSeek 等纯文本模型上处理 Web GUI 图片输入的开发者使用。
