拖图识图插件 lanbingyoumeng2023/dsh-multimodal

DSH 多模态 — 拖图自动识图插件

让 DeepSeek Harness（DSH）支持拖图即识图：当会话当前模型不支持图片输入时，自动把图片交给一个可配置的多模态模型转成文本描述，再喂回原模型。主模型保持 DeepSeek 不变，无需手动切换模型。

API 兼容任意 OpenAI 风格多模态服务（/chat/completions），完全通过环境变量配置，不绑定具体供应商。

原理速览

拖图（image 块） │ ▼ DSH api-proxy │ ├─ 当前模型支持图片 ──▶ 原样进模型 │ └─ 当前模型不支持图片 ──▶ 多模态模型识图（图片 → 文本描述） │ ▼ 原模型收到纯文本，正常流式回复

图片从不出现在原模型的上下文里——原模型只收到一段「用户上传了图片，内容如下：…」的文本。这就是为什么主模型可以保持 DeepSeek、无需切换。

解决什么问题

DSH 的 api-proxy 在图片消息进入模型前会硬编码拒绝「当前模型不支持图片」，且该位置没有插件钩子。本仓库给出两条路径：

1. host 补丁（拖图识图的核心）：直接修改 dsh-host-apiproxy 的 prompt 处理器，把「拒绝」改成「识图 → 文本 → 继续」。
2. agent preset（可分发部分）：注册三个模型工具——识图 / 文生图 / 文生视频。

目录结构

dsh-multimodal/
├── README.md 本文档 ├── INSTALL.md 一键安装：可直接扔给 DSH 自己执行的提示词 ├── SUMMARY.md 实现总结（改动点 + 踩坑记录 + 设计取舍） ├── CHANGELOG.md 版本历史（Keep a Changelog） ├── SECURITY.md 安全说明 + 漏洞报告渠道 ├── CONTRIBUTING.md 贡献指南 ├── .env.example 环境变量模板（无真实值） ├── docs/ │ ├── architecture.md 架构详解：异步轮询状态机 + 补丁 diff 解析 │ └── apiproxy.patch.diff 精确补丁 diff（原始 vs 补丁后） ├── LICENSE MIT ├── .gitignore ├── preset/multimodal/ 可分发的 agent preset │ ├── agent.cordis.yml 标准 agent + tool-multimodal 行 │ ├── preset.yml │ └── plugins/multimodal-tools/ │ ├── package.json │ └── index.js 识图/生图/生视频三个工具 ├── adapter/ 备选：把多模态服务注册成 DSH 的 LLM 适配器 │ ├── package.json │ └── index.js 零依赖自包含的 OpenAI 兼容适配器 ├── patch/ │ ├── dsh-host-apiproxy-index.js （已打补丁的 api-proxy 完整文件，供重打参考） │ └── apply-multimodal-patch.ps1 补丁重打脚本（npx 缓存清理/升级后恢复） ├── secrets/ │ └── Get-MultimodalKey.ps1 DPAPI 密钥读取脚本示例（Windows 本机可选项） └── .github/workflows/ci.yml 语法校验 CI（node --check）

安装

懒人路径：不想手动操作？见 INSTALL.md，里面有一段提示词，直接粘贴给 DSH 让它自己完成下载、复制 preset、打补丁、配置 API——你只需在它停下时提供 API Key 并手动重启网关。

1. 复制 preset

把 preset/multimodal/ 复制到 ~/.dsh/.agent-presets/multimodal/。

2. 配置 API（环境变量，必需）

| 变量 | 默认 | 说明 |
| MULTIMODAL_API_KEY | — | 必填（API 密钥，绝不写入代码/配置/仓库） |
| MULTIMODAL_BASE_URL | 占位地址 | OpenAI 兼容 API 基址，如 https://your-provider.example.com/v1 |
| MULTIMODAL_VISION_MODEL | your-vision-model | 识图模型 |
| MULTIMODAL_IMAGE_MODEL | your-image-model | 生图模型 |
| MULTIMODAL_VIDEO_MODEL | your-video-model | 生视频模型 |
| MULTIMODAL_VIDEO_HOST | 占位地址 | 视频轮询基址 |
| MULTIMODAL_VIDEO_POLL_PATH | /videos/tasks?video_id= | 视频轮询端点路径 |
| MULTIMODAL_CONTEXT_WINDOW | 131072 | （adapter 用）上下文窗口 |

所有默认值都是占位符，开箱不可用——请替换为你自己的服务与模型。这正是有意的：本仓库不捆绑任何第三方服务。

3. 打 api-proxy 补丁（拖图识图的关键，host 层）

pwsh -File patch/apply-multimodal-patch.ps1

补丁作用：在 dsh-host-apiproxy 的 prompt 处理器里，当模型不支持图片时调用 multimodalDescribeContent 识图替换（异步 + 轮询，见下）。
4. （可选）DPAPI 密钥存储

在 Windows 上，如果不想使用环境变量，可以用 DPAPI 加密密钥并存储到 ~/.dsh/secrets/，运行时通过 secrets/Get-MultimodalKey.ps1 解密取用。当环境变量未设置时，代码会自动回退到此脚本。

使用

- 新建会话时选择「多模态模式」preset
- 将图片拖到对话框并发送 → 自动识图（模型收到图片的文本描述，原模型不变）
- 工具（模型可主动调用）：multimodal_analyze_image（识图）、multimodal_generate_image（生图）、multimodal_generate_video（生视频）

架构与关键设计

完整的状态机、数据流与逐块 diff 解析见 docs/architecture.md。这里只讲最关键的三个点。

为什么识图要在 host 层打补丁

正因为上面那个「无插件钩子」的硬编码拒绝，拖图识图只能直接改 dsh-host-apiproxy——这是本方案的非分发点：apply-multimodal-patch.ps1 用于在 npx 缓存清理或 dsh 升级后重打。

异步 + 轮询（避免超时误报）

session.prompt 是前端 unary 调用，默认 30 秒超时。识图本身可能更慢（尤其大图、TTFT 抖动）。若在 prompt 处理器里同步等待识图，前端会先弹「超时报错」，而识图结果随后才到——典型的超时误报。

因此补丁把识图改成异步：

1. prompt 收到图片 + 模型不接受图片时，立即返回 accepted（前端不阻塞）；
2. 后台异步调用多模态模型识图；
3. 完成后把文本描述作为用户消息注入会话，原模型继续正常回复；
4. 识图期间在 webServer 服务实例上置 __multimodalDescribing 标志，供外部（如桌面灵动岛）轮询显示「正在识别图片…」。

跨 realm 通信的坑

动态 Cordis 插件跑在 node:vm 沙箱，其 globalThis 是独立 realm，无法用全局变量在主 realm 与插件间传状态。解法是用 webServer 服务实例作桥梁（往实例上挂 __multimodalDescribing 属性），因为两侧拿到的是同一个服务对象。

已知限制

- 识图补丁依赖 npx 缓存中的 dsh-host-apiproxy；npm cache clean 或 dsh 版本升级后需重打（脚本已备，且用 multimodalDescribeContent 标记检测是否已打）。
- 补丁是直接改第三方包文件，非正式插件分发方式；adapter/ 是朝「原生支持图片、彻底摆脱补丁」方向的备选实现。

许可证

MIT（各仓库代码按其原许可证）