princefrogdida-ux

dsh-vision-suite

Name: dsh-vision-suite
Author: princefrogdida-ux

Windows-first vision suite with image understanding, OCR, screenshot diffing, and multi-provider routing for DeepSeek Harness.

Stars: 1
Language: TypeScript
Created: Aug 15, 2026
Updated: Aug 15, 2026

Vision

GitHub repo

Introduction

DSH Vision Suite

面向 Windows 的 DeepSeek Harness 视觉能力套件，插件包名为 dsh-vision-workbench。它在保留官方 deepseek-official 文本路由的同时，为 DeepSeek 增加图片理解、OCR、截图裁剪、像素差异比较、主色提取和安全网页截图能力。

DeepSeek 继续负责推理。只有调用远程视觉工具时，插件才会把用户选定的图片发送给已配置的 OpenAI-compatible 视觉模型。

插件能力

工具	作用	执行位置
`vision_describe`	理解 1～4 张上传图片或工作区图片，支持图片问答、多图比较和结构化截图证据	视觉 Provider
`vision_ocr`	识别整张图片或指定区域中的文字，可选择远程视觉模型或本地 Tesseract	Provider 或本机
`vision_crop`	按像素坐标裁剪图片，并保存为可继续使用的持久附件	本机
`vision_compare`	比较两张同尺寸截图，返回变化比例和洋红色差异图	本机
`vision_palette`	提取图片中的近似主色	本机
`vision_browser_capture`	使用独立的无头 Edge 或 Chrome 截取白名单网页	本机浏览器

插件还提供：

支持 PNG、JPEG 和 WebP。
图片附件使用持久 ID，工具结果可随会话保存和回放。
支持一个主视觉 Provider 和最多三个顺序后备 Provider。
Provider 失败时执行有限回退，并通过冷却机制避免持续请求故障端点。
支持图片数量、文件大小、像素数、工作像素、超时和缓存限制。
API Key 通过 Harness Credentials 保存，不写入插件配置、日志或页面响应。
可为插件请求单独配置 HTTP/HTTPS 代理，不修改全局网络设置。
Sharp、Tesseract.js 和浏览器能力均按需加载。

配置入口

插件安装后默认保持关闭，不会自动接管模型路由，也不会自动发送图片。

推荐使用 DeepSeek Harness 原生配置页面：

启动安装了本插件的 Web Profile。
打开“设置 → 插件 → 插件配置”。
点击 Vision Workbench 展开全部配置项。
填写文本模型、视觉 Provider 和 API Key。
打开“启用插件”，保存配置。
重启当前 Profile，使路由和工具配置生效。

API Key 密码框为空时会保留已经保存的密钥。页面刷新后不会回显密钥，只会显示对应凭据是否已经配置。

API Key 官方入口

下面这些服务都提供官方 API Key，并有可通过 OpenAI-compatible Chat Completions 接收图片的模型。实际可用模型、额度和区域限制可能变化，请以服务商官网当前信息为准。

服务商	`baseURL`	API Key 官网	视觉兼容说明
OpenAI	`https://api.openai.com/v1`	创建 API Key	查看支持 Image input 和 Chat Completions 的模型
OpenRouter	`https://openrouter.ai/api/v1`	创建或管理 API Key	Image Inputs 官方文档
硅基流动 SiliconFlow	`https://api.siliconflow.cn/v1`	创建或管理 API Key	多模态输入官方文档
阿里云百炼	中国大陆：`https://dashscope.aliyuncs.com/compatible-mode/v1` 国际：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`	获取与配置 API Key	OpenAI 兼容 Chat 与图片输入

在插件中配置时：

把表格中的地址填入 visionProvider.baseURL。
从服务商官网复制一个支持图片输入的模型 ID，填入 visionProvider.model。
为该服务设置独立的 credentialRef，例如 OPENAI_VISION_KEY 或 OPENROUTER_VISION_KEY。
把真实 API Key 粘贴到对应 Provider 卡片的密码框中，不要写入 YAML、截图、Issue 或日志。

同一个服务商可能同时提供纯文本模型和视觉模型。选择模型时必须确认它支持 image_url 图片输入以及 /chat/completions 接口。

最小可用配置

第一次使用只需要配置以下内容：

配置项	推荐值或说明
`enabled`	开启
`wrapperRoute`	保持 `deepseek-vision-workbench`
`textProvider.provider`	保持 `deepseek-official`
`textProvider.model`	选择当前 Harness 中可用的 DeepSeek 模型
`visionProvider.name`	`primary`
`visionProvider.baseURL`	视觉服务的 OpenAI-compatible API 地址，例如 `https://api.example.com/v1`
`visionProvider.model`	服务商提供的视觉模型名称
`visionProvider.credentialRef`	凭据名称，例如 `VISION_API_KEY`
API Key	在同一 Provider 卡片的密码框中输入

保存并重启 Profile 后，在模型选择器中选择：

DeepSeek + Vision Workbench / <配置的 DeepSeek 模型>

随后上传图片并直接提问，例如“识别这张截图中的文字”或“比较这两张图片的布局差异”。

基础配置

字段	默认值	说明
`enabled`	`false`	是否注册包装路由和视觉工具
`wrapperRoute`	`deepseek-vision-workbench`	插件自己的模型路由名称，不能与 `deepseek-official` 或文本 Provider 重名
`textProvider.provider`	`deepseek-official`	负责最终推理的文本 Provider
`textProvider.model`	`deepseek-v4-pro`	包装路由公布的文本模型
`timeoutMs`	`120000`	一次视觉工具调用的总超时
`proxyUrl`	空	仅用于本插件请求的 HTTP/HTTPS 代理

视觉 Provider

主 Provider 位于 visionProvider，后备 Provider 位于 fallbackProviders。

字段	默认值	说明
`name`	`primary`	Provider 标识；主备 Provider 之间不能重名
`baseURL`	空	OpenAI-compatible API 根地址，正常使用必须是 HTTPS
`model`	空	视觉模型名称
`credentialRef`	`VISION_API_KEY`	Harness Credentials 中的凭据名称
`allowKeyless`	`false`	仅在服务明确不需要密钥时开启
`allowInsecureLocalhost`	`false`	仅允许显式连接本机回环地址上的 HTTP 测试服务
`maxTokens`	`4096`	视觉模型最大输出 Token 数

baseURL 中不能嵌入用户名、密码或 API Key。远程服务必须兼容 OpenAI /chat/completions 的 image_url 内容格式。

Provider 回退

最多可以配置三个后备 Provider，插件会按照列表顺序逐个尝试，不会并发把图片发送给多个端点。

字段	默认值	说明
`providerRouting.attemptTimeoutMs`	`45000`	单个 Provider 的尝试超时
`providerRouting.failureThreshold`	`2`	连续失败多少次后进入冷却
`providerRouting.cooldownSeconds`	`60`	故障 Provider 的冷却时间

总超时 timeoutMs 应大于单次超时 attemptTimeoutMs，否则可能没有足够时间尝试后备 Provider。

图片限制与缓存

字段	默认值	说明
`limits.maxImagesPerCall`	`4`	单次视觉调用最多处理的图片数
`limits.maxImageBytes`	`10485760`	单张图片最大字节数，默认 10 MiB
`limits.maxImagePixels`	`40000000`	单张图片最大像素数
`cache.enabled`	`true`	是否缓存视觉结果
`cache.maxEntries`	`200`	最大缓存条目数
`cache.ttlSeconds`	`3600`	缓存有效时间；设为 0 表示不按时间过期

本地图片处理

本地裁剪、截图比较和调色板提取依赖可选的 Sharp 后端。

字段	默认值	说明
`localProcessing.enabled`	`true`	是否启用本地像素工具
`localProcessing.maxWorkingPixels`	`16000000`	本地处理过程允许的最大工作像素数

vision_compare 要求两张截图尺寸完全相同。插件不会自动缩放或对齐图片，以免掩盖真实布局变化。

本地 OCR

vision_ocr 默认使用远程视觉 Provider。只有明确选择 backend="local" 时，才会进入本地 Tesseract OCR。

开启本地 OCR 前，需要自行准备可信来源的 Tesseract 语言数据文件：

字段	默认值	说明
`localOcr.enabled`	`false`	是否允许本地 OCR
`localOcr.languagePath`	空	语言文件所在的绝对本地目录
`localOcr.languages`	`eng`	1～4 个语言代码，例如 `eng`、`chi_sim`
`localOcr.gzip`	`true`	是否使用 `.traineddata.gz` 文件
`localOcr.timeoutMs`	`60000`	单次本地识别超时
`localOcr.maxLanguageBytes`	`52428800`	单个语言文件最大字节数
`localOcr.maxRegions`	`50`	最多返回的文字区域数
`localOcr.pageSegMode`	`auto`	页面分割模式：`auto`、`single-block` 或 `sparse-text`
`localOcr.autoRotate`	`true`	是否自动处理方向
`localOcr.lowConfidenceThreshold`	`40`	低置信度提示阈值

Windows 配置示例：

localOcr:
  enabled: true
  languagePath: 'D:\vision-data\tesseract'
  languages: [eng, chi_sim]
  gzip: true
  timeoutMs: 60000
  maxLanguageBytes: 52428800
  maxRegions: 50
  pageSegMode: auto
  autoRotate: true
  lowConfidenceThreshold: 40

目录中应存在 eng.traineddata.gz、chi_sim.traineddata.gz 等与配置一致的文件。本地 OCR 不会自动下载语言包、访问 CDN、写入 Tesseract 缓存，也不会在失败后自动切换到远程 Provider。

网页截图

网页截图默认关闭。开启后必须填写精确的主机白名单：

字段	默认值	说明
`browserCapture.enabled`	`false`	是否注册网页截图工具
`browserCapture.browserChannel`	`msedge`	使用 `msedge` 或 `chrome`
`browserCapture.allowedHosts`	空	允许访问的精确主机名列表
`browserCapture.allowPrivateHosts`	`false`	是否允许访问本机或私有网络地址
`browserCapture.viewportWidth`	`1440`	浏览器视口宽度
`browserCapture.viewportHeight`	`900`	浏览器视口高度
`browserCapture.maxPageHeight`	`12000`	全页截图的最大页面高度
`browserCapture.navigationTimeoutMs`	`30000`	页面导航超时

白名单只填写主机名，不要包含协议、端口、路径或通配符：

browserCapture:
  enabled: true
  browserChannel: msedge
  allowedHosts:
    - example.com
    - cdn.example.com
  allowPrivateHosts: false
  viewportWidth: 1440
  viewportHeight: 900
  maxPageHeight: 12000
  navigationTimeoutMs: 30000

插件每次都会创建新的非持久浏览器上下文，不复用用户登录态。下载、弹窗和 Service Worker 会被禁用；导航、重定向、子资源及 WebSocket 都受同一白名单约束。

如需截图本机开发服务，必须把 127.0.0.1 加入 allowedHosts，并开启 allowPrivateHosts。这会扩大本机网络访问范围，只建议在可信的隔离 Profile 中使用。

YAML 配置示例

没有 Web 配置界面时，可以在 Profile 的后置 Patch 中使用：

- id: vision-workbench
  name: dsh-vision-workbench
  config:
    enabled: true
    wrapperRoute: deepseek-vision-workbench
    textProvider:
      provider: deepseek-official
      model: deepseek-v4-pro
    visionProvider:
      name: primary
      baseURL: https://your-provider.example/v1
      model: your-vision-model
      credentialRef: VISION_API_KEY
      allowKeyless: false
      allowInsecureLocalhost: false
      maxTokens: 4096
    fallbackProviders: []
    providerRouting:
      attemptTimeoutMs: 45000
      failureThreshold: 2
      cooldownSeconds: 60
    limits:
      maxImagesPerCall: 4
      maxImageBytes: 10485760
      maxImagePixels: 40000000
    cache:
      enabled: true
      maxEntries: 200
      ttlSeconds: 3600
    localProcessing:
      enabled: true
      maxWorkingPixels: 16000000
    localOcr:
      enabled: false
      languagePath: ""
      languages: [eng]
      gzip: true
      timeoutMs: 60000
      maxLanguageBytes: 52428800
      maxRegions: 50
      pageSegMode: auto
      autoRotate: true
      lowConfidenceThreshold: 40
    browserCapture:
      enabled: false
      browserChannel: msedge
      allowedHosts: []
      allowPrivateHosts: false
      viewportWidth: 1440
      viewportHeight: 900
      maxPageHeight: 12000
      navigationTimeoutMs: 30000
    timeoutMs: 120000
    proxyUrl: ""

API Key 不应直接写入 YAML。请在 Harness Credentials 或插件可视化配置卡片中，把真实密钥保存到 credentialRef 指定的名称。

使用示例

上传图片后可以直接向所选的包装模型提问。模型可根据任务调用：

vision_describe attachment_ids=["sha256:..."] question="这张截图显示了什么？" structured=true
vision_ocr attachment_id="sha256:..." language_hint="中文和英文"
vision_ocr attachment_id="sha256:..." backend="local"
vision_crop attachment_id="sha256:..." region={"x":100,"y":80,"width":600,"height":300}
vision_compare before={"attachment_id":"sha256:before"} after={"attachment_id":"sha256:after"} tolerance=0.02
vision_palette path="screenshots/home.png" count=6
vision_browser_capture url="https://example.com" full_page=true wait_after_load_ms=500

裁剪图、差异图和网页截图都会保存为持久附件，可继续交给 vision_describe、vision_ocr 或后续会话步骤使用。

能力边界

不禁用或替换 deepseek-official。
不内置匿名视觉服务，不会在没有配置 Provider 时发送图片。
不支持 GIF；请先转换为 PNG、JPEG 或 WebP。
不捆绑或自动下载 Tesseract 语言数据。
不接管用户已经打开的浏览器，不复用登录态，也不执行网页点击、输入或表单提交。
网页截图提供视觉证据，不提供 DOM 自动化、登录或 PDF 导出。
本地 OCR 对复杂表格、手写字、低对比度或旋转截图的效果可能低于多模态视觉模型。
调色板适合界面主色判断，不适合作为色彩管理或印刷取色工具。