Icestab/dsh-image-vision-bridge

dsh-image-vision-bridge

npm version

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//node_modules/):

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

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

2. 在 $DSH_HOME/profiles//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