c-ling / dsh-plugin-vision-bridge

dsh-plugin-vision-bridge

DeepSeek Harness 视觉识别插件：保留原生粘贴 / 拖拽图片体验，发送时先由 OpenAI 兼容视觉 API 生成英文描述，再把纯文本交给 DeepSeek。

English

简介

• 输入框上传按钮：与原生粘贴 / 拖拽共用同一套草稿缩略图、删除和限额校验。
• 自动看图：发送图片时，宿主先把图片保存为 durable attachment，再调用 OpenAI 兼容视觉 API（POST {baseUrl}/chat/completions）生成英文描述。
• 可回溯历史：每次发送追加一个 vision/image 图片展示事件 + 一条插件上下文 描述消息；最终用户消息保持纯文本，DeepSeek 只看到文字描述。
• describe_image 工具：模型可以主动重新观察已上传图片，不传 imageId / imageIds 时查看最近一张；多图时插件上下文会给出 attachmentId， 同时也接受文件名、draftId 或 1-based 图片序号。可通过 imageIds 数组在一次 调用中同时传入多张图片，让视觉模型一起理解、对比或推理。可传可选 prompt 参数临时覆盖默认描述提示词，让视觉模型按需提取指定信息（例如“读取图中的报错 信息”“图中按钮是什么颜色”）；不传则使用设置页配置的默认提示词。
• 设置页：Base URL、模型、只写 API Key、描述提示词模板、超时与图片限制； 支持在设置中直接“查看日志”以排查视觉 API 调用报错； 中英文界面随 Settings → General → Language 实时切换，明暗主题使用 --dsw-alias-* token。

视觉 API 失败时发送失败并恢复输入框草稿，不静默降级。

安装

从 GitHub 安装到 web profile（需要 pnpm 在 PATH 上；没有则用下面的 corepack 方式）：

npx @deepseek-ai/dsh plugin --profile web add "github:c-ling/dsh-plugin-vision-bridge#v1.0.1"

或使用已有的 dsh 命令：

dsh plugin --profile web add "github:c-ling/dsh-plugin-vision-bridge#v1.0.1"

pnpm 不在 PATH 上时：

cd ~/.dsh/profiles/web
corepack pnpm add "github:c-ling/dsh-plugin-vision-bridge#v1.0.1"

dsh plugin 把参数原样转发给 pnpm，直接从本仓库拉取包（pnpm 9+，本机需装有 git）。 安装时若看到 declares no dsh.bundle — installed as a plain dependency 的提示属正常现象： 本插件不是 profile bundle 层，而是通过下面的 loader 行激活。

然后在 ~/.dsh/profiles/web/cordis.patch.yml 增加一行插入：

- insert:
    - id: dsh-plugin-vision-bridge
      name: 'dsh-plugin-vision-bridge'

重启 dsh web（client-modules 按进程缓存包裁决，新包必须重启宿主），然后硬刷新页面。 在会话输入框左侧会出现图片上传按钮；设置页中出现「视觉识别」。

本地开发可直接安装 link 包：

cd ~/.dsh/profiles/web
corepack pnpm add "link:/abs/path/to/dsh-plugin-vision-bridge"

验证

curl -s http://127.0.0.1:3080/plugins/dsh-plugin-vision-bridge/client.js | head -c 60

应输出 window.__ModuleLoader__.load({ 开头的 factory bundle。进入 设置 → 视觉识别 配置 Base URL 和模型后，粘贴 / 上传一张图片并发送；历史中应依次出现 图片缩略图、英文描述上下文气泡和纯文本用户消息。

更新

dsh plugin --profile web add "github:c-ling/dsh-plugin-vision-bridge#v1.0.1"
# 或：npx @deepseek-ai/dsh plugin --profile web add "github:c-ling/dsh-plugin-vision-bridge#v1.0.1"
# 或：cd ~/.dsh/profiles/web && corepack pnpm add "github:c-ling/dsh-plugin-vision-bridge#v1.0.1"

用新的版本号重新执行安装命令即可升级依赖；cordis.patch.yml 中的 loader 行保持不变。 重启 dsh web，然后硬刷新页面。

卸载

cd ~/.dsh/profiles/web
corepack pnpm remove dsh-plugin-vision-bridge   # 或 dsh plugin --profile web remove dsh-plugin-vision-bridge

同时删除 cordis.patch.yml 中对应的 insert 行，然后重启 dsh web。 插件配置与视觉 API 调用日志保存在 $DSH_HOME/storages/dsh-plugin-vision-bridge/；图片由 harness 的 attachments 存储统一管理。卸载后这些数据都不会自动删除，如需彻底清除请手动清理。

开发

node --check lib/index.js lib/client.js
node --test
python3 -m json.tool package.json

• 宿主半部为纯 Node builtins 的 Cordis 插件：webServer 路由 + tools.register + ctx.attachments / ctx.sessions。
• 客户端为手写 factory-CJS bundle，无构建步骤；通过 conversation.input.left、 conversationEvents / conversation.chat.node 和 settings.section 注册 UI。
• 发送包装在 ctx.effect 内完成，fiber 销毁时恢复原始 conversation.sendSession。

已知限制

• v1 只支持 PNG / JPEG / WebP / GIF；描述语言固定为英文。
• 视觉 API 密钥明文保存在 $DSH_HOME/storages/dsh-plugin-vision-bridge/config.json （与本地 settings 的写入方式一致），接口只回传脱敏值。
• 真正的多模态 adapter / 模型切换不在 v1 范围。

License

MIT