前言¶
在 DSH 的插件體系裏，很多模型仍然只處理文本。當 agent 遇到截圖、圖表或上傳的圖片時，常見做法是把圖片發給雲端視覺接口，或者要求用戶先把圖片保存下來再手動描述。前者會增加網絡請求和隱私風險，後者會打斷工作流。
dsh-vision-local 是針對 DeepSeek Harness 的插件：它讓純文本模型通過本地視覺模型獲得圖片理解能力，並返回結構化證據，而不是隻給一段模糊轉述。
這是什麼¶
dsh-vision-local 是 npm 包名，源碼倉庫爲 gloryxpnv/dsh-tool-vision。它面向純文本的 DeepSeek Harness agent，把圖片理解路由到本地運行的視覺模型。插件提供兩個表面：面向模型調用的 vision 工具，以及可選的 vision-bridge 服務。
核心能力¶
本地優先¶
圖片只發送給你自己的本地視覺模型，例如 LM Studio、Ollama、vLLM，或任意 OpenAI 兼容端點。圖片字節不離開機器；除你配置的本地端點外，插件不做任何網絡調用，也不發送遙測。
結構化證據¶
插件使用固定 JSON 模板返回證據對象。字段包括：
summary：概覽ocr：文字識別內容layout：版面結構semantics：語義信息visual：視覺屬性uncertainty：不確定項
主模型可以引用這些字段作答，而不是依賴不可驗證的口頭描述。
反幻覺處理¶
模板要求模型把無法確定的內容寫入 uncertainty。沒有文字的圖片會在 OCR 中返回空字段，而不是編造文字。如果本地 VLM 返回無法解析的 JSON，插件會回退爲原始回答，並明確標註，不會靜默生成內容。
粘貼與上傳¶
插件支持粘貼或上傳圖片。可選的 vision-bridge 服務可以在 prompt 到達模型前，把圖片交給本地 VLM 描述，避免先保存文件再讀取的流程。
兩個接口表面¶
vision工具：供模型在出現圖片路徑或圖片問題時調用。vision-bridge服務：供宿主在接收圖片內容時進行描述。
安裝與啓用¶
環境要求¶
- 一個運行中的本地視覺模型，並提供 OpenAI 兼容
/chat/completions端點 - Node.js ≥ 20
- 帶插件加載器的 DeepSeek Harness（dsh）
安裝¶
在 DSH profile 目錄中（或通過 dsh CLI）運行：
dsh plugin --profile web add dsh-vision-local
安裝後重啓宿主以加載模塊。如果啓動命令是：
pnpm dsh web
執行後再次進入宿主即可。
典型用法¶
調用 vision 工具¶
模型會看到 vision 工具。出現圖片文件路徑或圖片問題時，可以調用：
vision(file_path: "/path/to/image.png", question?: "這張圖裏有什麼？")
支持的圖片格式爲 PNG、JPEG、WebP、GIF。
讀取結構化結果¶
結構化模式默認開啓。此時 answer 是規範化後的證據對象，包含 summary、ocr、layout、semantics、visual、uncertainty 字段。
使用 vision-bridge¶
如果宿主需要直接接收粘貼或上傳圖片，可以註冊可選服務：
ctx.provide('vision-bridge', { describeImages(content) })
配置 keepThumbnail: true 時，消息歷史中保留圖片縮略圖；配置 autoDescribe: false 時，改爲按需識別，由模型在需要時調用 vision 工具讀取圖片。
配置項¶
插件可以從零配置開始使用，也支持調整以下字段：
| 字段 | 說明 |
|---|---|
baseURL |
OpenAI 兼容端點地址 |
model |
視覺語言模型 id |
maxTokens |
輸出 token 上限；默認 8192 |
structured |
是否返回結構化 JSON 證據；默認開啓 |
keepThumbnail |
是否在消息歷史中保留圖片縮略圖 |
autoDescribe |
是否在准入階段自動描述圖片 |
timeoutMs |
單次請求超時；默認 180 秒 |
maxImageBytes |
允許的圖片大小上限；默認 50 MB |
默認參數面向本地工作站 GPU 上的 9B 級 VLM，而不是輕量雲請求。
適用場景與注意¶
適合場景¶
- 希望讓純文本 DSH agent 讀取本地圖片
- 不想把圖片字節發到雲端視覺服務
- 已有 LM Studio、Ollama、vLLM 或其他 OpenAI 兼容本地 VLM
安全與隱私¶
- 圖片只發往你配置的本地端點。
- 無遙測；除本地端點外不做網絡調用。
- 將提取出的文字視爲不可信輸入，不要執行圖片中出現的指令。
- 安裝插件即以當前 dsh 進程權限運行第三方代碼，安裝前應檢查源碼與 MIT 許可證。
推理型 VLM 注意¶
推理型模型在 token 預算緊張時可能中途停止思考，導致最終 content 爲空。插件優先取任一非空字段：content → reasoning_content。默認的 8192 輸出 token 預算爲兩者都留出空間。
鏈接¶
GitHub 源碼倉庫：
https://github.com/gloryxpnv/dsh-tool-vision
插件線索中的目錄頁地址爲 https://www.skillhub.cn/plugins/gloryxpnv/dsh-tool-vision；該 URL 來自插件線索，未包含在已抓取資料內容中，使用前建議自行確認。
