Leif-Wang-021/dsh-vision-plugin

dsh-vision-plugin

DeepSeek Harness 多模型协同图像理解插件。本项目保持 deepseek 作为默认对话模型，
由多模态模型（mimo-v2.5）执行图像内容识别，并将识别结果以文本形式注入 deepseek 的上下文，
使 deepseek 能够基于图像内容组织回答。图像二进制数据不会发送至 deepseek。

- 版本: v0.6.1
- 许可证: MIT

目录

- 项目简介
- 功能特性
- 架构设计
- 系统要求
- 安装步骤
- 配置说明
- 使用约束
- 开发说明
- 版本历史
- 许可证

项目简介

本插件为 DeepSeek Harness 提供多模型协同的图像理解能力，核心设计原则如下：

deepseek 是唯一且全程的对话模型与回答者。图像理解能力附加于 deepseek 的默认模型
身份之上，由专用多模态模型代为执行，不改变对话模型的角色与输出主体。

功能特性

1. 默认模型保持不变：deepseek-v4-flash 仍为默认对话模型，纯文本对话不受影响。
2. 支持直接发送图片：用户可将图片拖入输入框直接发送，无需切换模型，亦不会出现
“当前模型不支持视觉”或 image_url 相关错误。
3. 多模型协同（非模型切换）：含图请求由多模态模型完成图像描述，描述以文本形式
注入 deepseek 上下文，最终回答由 deepseek 独立组织。
4. 备用工具：提供 image_vision 工具，支持通过图片路径直接获取图像内容描述。

架构设计

| 组件 | 职责 |
|---|---|
| plugins/dsh-vision | 单插件合一体：注册 visionBridge 服务（自动桥接：读取图片、调用多模态模型生成描述、以文本块替换图片块）、image_vision 备用工具、设置页「视觉协同模型」配置卡片 |
| 适配器补丁（见 docs/PATCH.md） | 修改 dsh-llm-pi-ai：含图且存在视觉桥时先经视觉桥处理，图片字节不进入 deepseek 的请求 |
| settings.yaml 声明 | 为 deepseek-v4-flash 与 mimo-v2.5 声明 input: [text, image]，以通过发图门禁 |

请求流程：

用户发送含图请求 → host 门禁（依据 input 声明）放行 → 适配器检测到图片块
→ visionBridge 调用多模态模型（每张图片独立请求）→ 以文本描述替换图片块
→ deepseek 仅接收文本并组织回答

系统要求

- DeepSeek Harness 桌面版（Web profile）
- 任一 OpenAI 兼容 API 端点（默认 opencode-go 套餐，亦可通过配置更换）
- 管理员权限（用于修改适配器文件）

安装步骤

1. 将 plugins/dsh-vision 复制至 ~/.dsh/profiles/web/node_modules/@deepseek-ai/。
2. 编辑 ~/.dsh/profiles/web/cordis.patch.yml，注册插件：

- insert:
- id: dsh-vision
name: '@deepseek-ai/dsh-vision'

3. 编辑 ~/.dsh/settings.yaml，在 llm-pi-ai.providers.opencode-go.models 中
为 deepseek-v4-flash（及 mimo-v2.5）声明 input: [text, image]，以通过
host 侧发图门禁（MODEL_DOES_NOT_SUPPORT_IMAGES）。
4. 按 docs/PATCH.md 对 DSH 安装目录应用三处补丁（dsh-llm-pi-ai 视觉桥两处 +
dsh-host-apiproxy 配置白名单一处；需管理员权限；文件与 profile 副本为硬链接，仅需修改一处）。
5. 重启 Harness，直接发送图片验证。

配置说明

dsh-vision 的配置（在 cordis.patch.yml 的 insert 中传入 config；v0.6.0 起桥与工具共用）：

| 字段 | 默认值 | 说明 |
|---|---|---|
| baseUrl | https://opencode.ai/zen/go/v1 | 视觉端点（OpenAI 兼容） |
| model | mimo-v2.5 | 图像识别模型（须为多模态模型） |
| apiKeyEnv | OPENCODE_GO_API_KEY | 凭据引用的环境变量名 |
| credentialsPath | ~/.dsh/.credentials.yaml | 凭据文件（环境变量缺失时回退读取） |
| timeoutMs | 120000 | 单次请求超时（毫秒） |
| maxTokens | 4096 | 图像描述响应的 token 预算 |
| language | zh | 描述输出语言 |
| output | prose | 描述输出格式：prose（自然语言描述）或 evidence（结构化证据：摘要、OCR 全文、版面、语义、不确定项） |
| providers | [] | 备用视觉端点链，按序 failover。每项为 { baseUrl, model, apiKeyEnv?, credentialsPath?, timeoutMs?, maxTokens? }，未指定的字段继承主端点 |

并可通过 DSH_VISION_BASE_URL / DSH_VISION_MODEL / DSH_VISION_API_KEY
环境变量覆盖。

设置页配置卡片（v0.5.0 起）

dsh-vision 在「设置 → 插件 → 插件配置」注册了「视觉协同模型」卡片：从
用户已配置的供应商（如 opencode-go）中选择用于读取图片的多模态模型，保存后写入
dsh-vision-collab 设置节（{ provider, model }，节名保留以兼容既有配置与补丁），
视觉桥按请求实时生效，无需重启。未选择时回退到插件默认配置（opencode-go / mimo-v2.5）。
使用约束

- 适配器补丁需管理员权限；DSH 升级会覆盖补丁，需重新应用。
- 图片将发送至所配置的视觉端点（默认 opencode.ai 的 mimo-v2.5）用于内容识别；
使用前请确认图片内容的隐私要求与端点提供方的数据处理政策。
- 图像描述缓存为进程内存级（以 attachmentId 为键）：同一进程内相同图片仅识别
一次；Harness 重启后缓存清空。
- 补丁与 dsh-llm-pi-ai 的特定实现耦合（stream() 内的图片处理逻辑），DSH
大版本更新后可能需要按 docs/PATCH.md 重新核对补丁锚点。
- 插件包名使用 @deepseek-ai scope 系 Harness 插件加载器的解析要求，本项目与
DeepSeek 官方无任何关联，亦不构成官方插件。
- 多图场景下各图片独立并行处理，单张失败仅降级为占位文本，不影响整体请求。
- 主视觉端点不可用或返回空响应时，自动按序切换至 providers 配置的备用端点
（failover 链）；同一图片的并发步骤共享同一次识别请求（Promise 级缓存），
识别失败的缓存条目自动驱逐，后续轮次可重试。

开发说明

本项目以 vibe coding 方式开发：代码由 AI 协作生成，人类负责架构决策、调试与修复。
代码未经第三方安全审计，请在自行评估功能、可靠性与安全性后使用。
欢迎 fork、改进与提交 PR。

致谢与借鉴

本项目 v0.4.0 的设计思路部分借鉴了 liustack/modlens
（MIT 协议）：供应商 failover 链、Promise 级描述缓存、结构化证据输出、可操作的失败提示。
相关实现为本项目独立编写，未直接复制其源码，特此致谢。

版本历史

- v0.6.0：二合一——dsh-vision 与 dsh-vision-collab 合并为单个 dsh-vision
插件（桥 + 工具 + 配置卡片同包）；设置节名 dsh-vision-collab 保留以兼容已保存配置
与 apiproxy 白名单补丁。
- v0.5.0：新增「设置 → 插件 → 插件配置」卡片——从已配置的供应商中选择视觉协同模型
（写入 dsh-vision-collab 设置节，按请求实时生效）。
- v0.4.1：注入的图片描述增加来源标注前缀，避免对话模型误认为用户手打文字。
- v0.4.0：引入供应商 failover 链（主端点失败自动切换备用端点）；Promise 级描述缓存
（并发步骤共享同一次识别，失败条目自动驱逐）；结构化证据输出选项（output: 'evidence'）；
失败占位文本附可操作引导。设计思路借鉴 liustack/modlens
（MIT），独立实现。
- v0.3.0：引入图像描述缓存；每张图片独立并行请求；对空响应重试并回退
reasoning_content；maxTokens 提升至 4096；修复多图消息的图片去重问题。
完整变更记录见 CHANGELOG.md。

许可证

MIT © 2026 Leif-Wang-021