dsh-image-vision-bridge

DSH 宿主插件:你发送的图片照常显示在聊天记录里,插件在 llm/stream 水线上把发给主模型的请求里的图片块悄悄替换成视觉模型 mimo-v2.5 (默认走你已配置的 opencode-go 路由,复用现有 OPENCODE_GO_API_KEY) 生成的文本描述。描述只进模型、不进聊天:DeepSeek 基于描述回复你, 聊天里看不到任何"图片解析"文本。

工作原理

1. 图片消息原样进入 agent、原样写入会话日志——聊天框显示的就是你发的图。
2. 主循环(以及压缩、标题生成等)发出的任何模型请求都会经过 llm/stream 水线。插件检查请求消息里是否含 image 块:
   • 不含图片 → 直接放行;
   • 目标是插件配置的视觉模型本身(自己的调用,或某会话本来就选用了 视觉模型)→ 放行,让视觉模型直接看图;
   • 其他情况 → 构造一份重写后的请求:消息里的 image 块(含 tool-result 嵌套)替换为描述文本,再以这份请求实际流式调用。原请求对象与 会话日志完全不被修改。
3. 描述结果按附件 id 在进程内缓存(重试/后续轮次不重复调用);视觉调用 失败时降级为一段失败说明文本,不打断对话;用户取消时错误照常抛出。

兼容性

• 已测试环境:DeepSeek Harness 0.1.0-rc.6 与 0.1.1-rc.2(@deepseek-ai/dsh、dsh-llm 同版本、cordis 4.0.1),11 项离线自测均通过。
• 插件依赖的公开 API:ctx.llm.stream、llm/stream 水线、contentHasImage/createMessage/BlockAssembler、附件 image 块。这些在 0.1.x 线内稳定;但插件会重写进入水线的请求(框架文档要求监听器只读不改),这是官方尚未承诺的用法,升级 dsh 前建议先在临时 profile 里冒烟测试(发一张图即可)。
• 插件不修改 dsh 安装、不写 dsh 目录、不碰会话日志;失败时按请求降级,不会影响纯文本对话。
• dsh 0.1.1+ 内置了文本模型的图片占位降级(不报错,但模型看不到图片内容);本插件提供真正的视觉描述,二者互补。

安装(标准 bundle 方式)

本包声明了 dsh.bundle,是标准的可分发 bundle:安装时自动插入插件行, 无需手改 cordis.patch.yml。

# 本地目录 / tarball / npm / GitHub 均可:
dsh plugin --profile web add dsh-image-vision-bridge              # npm
dsh plugin --profile web add github:Icestab/dsh-image-vision-bridge#c67b4b3  # GitHub(锁定版本)
dsh plugin --profile web add ./dsh-image-vision-bridge            # 本地目录
dsh plugin --profile web add ./dsh-image-vision-bridge-0.1.0.tgz  # tarball

仍有两步手工操作(插件无法替用户完成):

1. 让主模型声明可接收图片(必做):主机的 API 边界 (dsh-host-apiproxy)会在图片消息进入 agent 之前用当前模型的 inputModalities 做校验,主模型若不声明 image 会被直接拒绝 (客户端提示"当前模型不支持图片")。在 DSH 设置文件 $DSH_HOME/settings.yaml(也可通过 Web 界面的 Models 页维护)的 llm-pi-ai.providers.<路由> 下为主模型加 modelOverrides (该文件热重载,免重启):

   llm-pi-ai:
     providers:
       opencode-go:
         apiKeyEnv: OPENCODE_GO_API_KEY
         modelOverrides:
           deepseek-v4-pro:
             input: [text, image]

   插件会在请求水线上把图片换成文本描述,主模型请求里永远不会真的出现 图片块,所以这个声明只是放行边界,不会把图片发给 deepseek。

2. 重启 dsh web(web profile 已禁用 HMR,必须重启才生效)。

bundle 默认配置(provider: opencode-go,model: mimo-v2.5)可被用户覆盖: 在 profile 自己的 cordis.patch.yml 里按行 id image-vision-bridge 重写 config 即可(后层胜出)。

安装(手工平铺方式)

不通过 dsh plugin 的手工装法(适合不想用 pnpm 或想直接改代码的场景):

1. 把本包目录复制到 profile 的模块解析路径(裸包名从 profile 目录沿 node_modules 链向上查找;hoisted 布局通常是 $DSH_HOME/profiles/node_modules/,扁平布局则是 $DSH_HOME/profiles/<name>/node_modules/):

   cp -r ./dsh-image-vision-bridge "$DSH_HOME/profiles/node_modules/"

   注:以后若在 profile 里运行过 dsh plugin --profile <name> add/install …, pnpm 可能清掉这个手工放置的目录,重新执行上面这条命令即可恢复。

2. 在 $DSH_HOME/profiles/<name>/cordis.patch.yml 中加入插件行(settings.yaml 的 modelOverrides 配置仍是插件无法替用户完成的前提,见上一节):

   - insert:
       - id: image-vision-bridge
         name: 'dsh-image-vision-bridge'
         config:
           provider: opencode-go
           model: mimo-v2.5

3. 同样需要上面的 settings.yaml modelOverrides 配置,然后重启 dsh web。

配置

| 键 | 默认值 | 说明 | |---|---|---| | enabled | true | false 时完全透传,不做桥接 | | provider | opencode-go | 视觉模型所在 LLM 路由(必须已注册,即 settings.yaml 里 llm-pi-ai.providers 已配置) | | model | mimo-v2.5 | 视觉模型 id | | maxTokens | 2048 | 视觉调用最大输出 token | | maxDescriptionChars | 6000 | 注入主模型前的描述长度上限 | | prompt | 内置中文提示词 | 发给视觉模型的指令(用户原文会自动拼在前面) |

示例(自定义):

- insert:
    - id: image-vision-bridge
      name: 'dsh-image-vision-bridge'
      config:
        model: mimo-v2.5
        maxTokens: 4096
        prompt: 'Describe this image in English, including all visible text.'

自测

cd "$DSH_HOME/profiles"
node node_modules/dsh-image-vision-bridge/test/transform.test.mjs