前言¶

用 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 / 幻方無官方從屬關係。