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 原生配置页面：

1. 启动安装了本插件的 Web Profile。
2. 打开“设置 → 插件 → 插件配置”。
3. 点击 Vision Workbench 展开全部配置项。
4. 填写文本模型、视觉 Provider 和 API Key。
5. 打开“启用插件”，保存配置。
6. 重启当前 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 与图片输入

在插件中配置时：

1. 把表格中的地址填入 visionProvider.baseURL。
2. 从服务商官网复制一个支持图片输入的模型 ID，填入 visionProvider.model。
3. 为该服务设置独立的 credentialRef，例如 OPENAI_VISION_KEY 或 OPENROUTER_VISION_KEY。
4. 把真实 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 对复杂表格、手写字、低对比度或旋转截图的效果可能低于多模态视觉模型。
• 调色板适合界面主色判断，不适合作为色彩管理或印刷取色工具。