前言¶

用 DeepSeek Harness（DSH）搭智能体时常会撞上同一个限制：手头的文本模型没有原生图片输入能力，界面截图、数据图表贴进对话，模型读不了。没有插件时，只能先在上游用视觉模型读图，再把描述手动贴回对话，链路断在中间。

DSH 的理念是「一切皆插件」，这类缺口适合交给插件补齐。下面介绍的 dsh-tool-visual-primitives 就是这样一个插件：把图片交给外部视觉模型分析，返回带空间定位信息的纯文本视觉证据，再交回原对话模型继续推理。被增强的模型不需要原生图片输入能力。

这是什么¶

dsh-tool-visual-primitives 是 DSH 的插件，由 InkshadeWoods 维护，源码在 GitHub，当前版本 1.4.0，许可证为 MIT。核心思路参考 DeepSeek 的 Thinking with Visual Primitives：以归一化坐标和可引用对象，把图像理解转化为后续推理可使用、可检查的证据。

插件有两个入口，共用同一条 vision_analyze 分析核心：显式工具调用，以及对话中的 [vision] 模型变体。

工作方式¶

一条请求在插件内部的流转如下：

图片 + 用户问题
  → detectVisionMode() → shouldUsePrimitives() → buildVisionPrompt()
  → 外部视觉模型（OpenAI 兼容 Chat Completions）
  → 纯文本视觉证据（可含坐标化 primitives）
  → 原始文本模型继续回答

三个控制维度相互正交：Mode 决定任务类型，Detail 决定信息密度，Primitives 决定是否强制结构化的空间证据。

插件会自动识别 11 类视觉任务：caption（描述）、object_inventory（对象清单）、multi_subject（多主体）、counting（计数）、grounding（定位）、spatial_relation（空间关系）、comparison（比较）、path_tracing（路径）、topology（拓扑）、ui_analysis（UI）、document_visual（文档视觉）。优先级最高的关键词决定 Mode，没有匹配时落到 caption。例如「这个界面有几个按钮？」会识别为 ui_analysis。

核心功能¶

• 两个入口共用 vision_analyze 分析核心：显式工具调用与对话中的 [vision] 模型。
• 三档分析细节：brief、standard（默认）、verbose。
• 三种视觉原语策略：auto（默认）、on、off。原语使用 <ref>、<box>、<point>，坐标范围为 0–999。
• 仅对选定的纯文本模型追加 [vision] 变体，原模型保留，不受影响。
• 会话级视觉证据缓存：追问仅在已有证据覆盖新问题时复用，否则重新读图。
• 原生设置页：安全密钥存储、连接测试、/models 搜索选择、手动模型 ID，按供应商折叠选择待增强模型。
• 支持 OpenAI 兼容端点：POST <Base URL>/chat/completions 与可选模型目录 GET <Base URL>/models；小米 Mimo URL 自动改用 api-key 请求头。
• 相同图片与提示词的并发分析自动合并为一次上游请求，诊断日志设置项默认关闭（均为 1.3.0 引入）。
• 1.4.0 起，设置页的「对话视觉模型」列表改用 DSH 0.1.2-rc.1 的新模型目录接口读取。

安装与启用¶

前置条件¶

• 已可运行的 DSH Web Profile。当前版本要求 DSH 0.1.2-rc.1 或更高，dsh.plugin.json 与 package.json 的引擎声明同步收紧。
• Node.js >= 20 与 pnpm。
• 一个可访问的视觉模型服务，默认使用 OpenAI 兼容端点。视觉服务与被增强的文本模型可以来自不同供应商。

一键安装¶

在 PowerShell 或终端执行（前提是已全局安装 DSH，即 npm install -g @deepseek-ai/dsh）：

dsh plugin --profile web add dsh-tool-visual-primitives@latest

使用的不是 web Profile 时，把 --profile 改成对应名称。安装成功后，DSH 会识别包内的 dsh.bundle.patch 声明，自动把插件加入 dsh.profile.bundles；该过程不会直接修改 Profile 自身的 cordis.patch.yml，可与 dsh-better-sidebar 等插件共存。

安装后需完整重启 DSH；首次更新客户端界面时，在浏览器按 Ctrl+Shift+R 强制刷新。

首次配置¶

打开 DSH 设置 → 视觉分析，按顺序做：

1. 填写 API Key、Base URL 与视觉模型。
2. 点击「加载模型」，插件从 <Base URL>/models 拉取可搜索列表；服务不提供模型目录时，直接填写自定义模型 ID。
3. 点击「测试连接」。
4. 在「对话视觉模型」中勾选希望追加 [vision] 的纯文本模型。

两点细节：已保存的 API Key 重新打开页面时不会回显，填写新值会覆盖旧值，点击「清除 API Key」才会删除；排查问题时可开启诊断日志（默认关闭），插件会向 DSH 控制台输出运行日志。

从源码本地挂载¶

开发调试可用 GitHub 源码方式：

$source = 'D:\DSH\dsh-tool-visual-primitives'
git clone https://github.com/InkshadeWoods/dsh-tool-visual-primitives.git $source

Set-Location $source
pnpm install
pnpm run build

dsh plugin --profile web add $source

卸载¶

先在设置页点击「清除 API Key」，再执行：

dsh plugin --profile web remove dsh-tool-visual-primitives

典型用法¶

对话中使用 [vision]¶

经过上面的配置步骤后：

1. 在插件设置的「对话视觉模型」中勾选一个纯文本模型。
2. 重新打开对话模型列表，选择新增的「模型名 [vision]」。
3. 上传、粘贴或拖入图片，直接提问。

插件只把图像块替换为视觉证据文本，最终回答仍由所选的原文本模型生成。对于明确指向最近图片的追问，插件会检查缓存证据是否覆盖新的任务、细节与关注对象；覆盖不足时重新分析图片，而不是把不充分的旧答案当作事实。

显式调用 vision_analyze¶

工具接收且只接收一个图片来源：本地绝对路径或 HTTP(S) URL。

{
  "image_path": "D:/images/dashboard.png",
  "prompt": "统计界面上可点击的主要按钮，并标出它们的位置"
}

{
  "url": "https://example.com/chart.png",
  "prompt": "解读图表的趋势，并说明读不清的标签"
}

启用视觉原语时，返回的证据按 [Mode]、[Visual Primitives]、[Observations]、[Relations]、[Uncertainty]、[Answer] 等标题组织，定位信息形如：

<ref>submit_button</ref><box>[[742, 861, 900, 930]]</box>
<point>[[125, 430], [210, 430], [300, 510]]</point>

所有坐标相对 0–999，不是原图像素。

分析参数¶

连接配置完成后，再按需调整参数。设置页提供这些项：

适用场景与注意事项¶

适合的场景：

• 对话模型没有原生图片输入能力，但任务涉及截图阅读、图表解读、UI 复刻。
• 希望视觉服务与文本模型分属不同供应商。

README 附带了端到端测试记录（对话图片理解、截图驱动的 UI 复刻），素材与结果保存在仓库的 test/ 目录。生成效果取决于外部视觉模型、文本模型、提示词和图片质量。

使用前注意：

• 安全限制：远程 URL 不允许指向 localhost、私有网络地址或携带用户名/密码，重定向会被拒绝，以降低 SSRF 风险。
• 插件以当前 dsh 进程权限运行，安装前请自行审查源码与许可证。
• 卸载前先在设置页清除 API Key，再执行卸载命令。

相关链接¶

dsh-tool-visual-primitives 把「读图」外移给外部视觉模型，让纯文本模型拿到带坐标、可检查的视觉证据。对用 DSH 搭建智能体、又被模型视觉能力卡住的开发者来说，这是一个针对明确缺口的补件。

• GitHub 仓库：https://github.com/InkshadeWoods/dsh-tool-visual-primitives
• 社区插件目录收录页：https://www.skillhub.cn/plugins/InkshadeWoods/dsh-tool-visual-primitives

目录站点为社区独立维护，与 DeepSeek / 幻方无官方从属关系。