前言¶
在 DSH 智能體場景裏，文本模型經常需要處理圖片：用戶發來截圖、網頁報錯圖、表格、長聊天記錄，或者希望模型在圖中找某個圖標、按鈕、文字區域。若底層模型本身不支持圖片，插件就只能依賴外部補丁、手工轉述，或者把圖片先轉成文字再交給模型。
dsh-vision-skill 是一個 DeepSeek Harness（DSH）標準插件版識圖技能。它把識圖能力包裝成 DSH 原生 runtime skill，讓不支持圖片的純文本模型也能看圖、OCR、定位目標。
這是什麼¶
dsh-vision-skill 由 DDDFXYqiming 維護，採用 MIT 授權。
它提供 DSH 原生 runtime skill vision，由模型按需加載，並漸進式暴露識圖工具。加載後，對話中的圖片相關請求可以路由到對應的本地工具，而不是要求文本模型直接理解圖像。
該插件適用於 DSH 生態中的插件化智能體工作流，尤其適合需要在文本模型中補充圖片識別、文字提取和目標定位能力的場景。
核心能力¶
下面介紹已覈實的工具能力。
vision_analyze¶
vision_analyze 用於識別本地圖片，支持 6 種模式：
generalocrtablecodeerrorevidence
其中 evidence 是結構化證據模式，返回一段 JSON，包含：
summary / ocr_full_text / layout / semantics / uncertainty / visual
這個模式適合需要把圖片證據拆成可引用字段的場景，而不只是拿一段自然語言描述。
vision_ocr¶
vision_ocr 是獨立 OCR 工具，保留原始排版。適合從圖片中提取文字，同時儘量維持原有結構。
vision_ground¶
vision_ground 用於目標定位。模型可以請求在圖中找某個目標，工具返回像素座標和歸一化座標。
vision_detect¶
vision_detect 用於枚舉一類元素，例如按鈕、圖標、表格單元格等，並給出編號和像素座標框。
vision_dominant_colors¶
vision_dominant_colors 用於主色分析。該能力使用本地像素算法，不消耗視覺 API。
vision_long_screenshot_ocr¶
vision_long_screenshot_ocr 用於超長截圖分塊 OCR。流程是先跑本地 tesseract，失敗時再交給 VLM 兜底，最後合併結果。
vision_clipboard¶
vision_clipboard 用於剪貼板圖片兜底識別。適合截屏後直接讓模型“看圖”的場景。
工程化能力¶
除了工具本身，dsh-vision-skill 還有一些工程化設計。
直接貼圖¶
v0.4 起直接貼圖走 paste-to-path，不再需要 pi-ai 補丁。
如果舊版宿主沒有 reference 能力，直接貼圖會自動回退爲插入路徑文本。
多 provider 容錯¶
插件支持多 provider failover。遇到 429 時，會按 Retry-After 退避重試一次。
圖像緩存¶
插件提供圖像記憶緩存，按圖片 SHA-256 加 mode / budget / crop / prompt 做緩存。TTL 內命中時直接返回：
{
"cached": true
}
路徑圍欄¶
圖片路徑必須位於會話工作區、DSH 附件目錄或 allowedDirs 之一，並經過 realpath 校驗。
這可以防止任意路徑圖片被直接讀取。
安裝與啓用¶
安裝命令如下：
dsh plugin --profile web add github:DDDFXYqiming/dsh-vision-skill
該命令將插件安裝到 web profile 中。
運行環境要求：
{
"engines": {
"node": ">=22.19"
}
}
密鑰推薦用 DSH Credential 引用：
credential: VISION_API_KEY
插件也兼容明文 apiKey，但不推薦。
自定義配置時，用裸條目按 id 覆蓋。如果出現重複 id，會觸發：
duplicate loader entry id
宿主啓動會直接崩潰，因此不建議在已有 vision-skill 條目的配置裏再插入同 id 條目。
典型用法¶
在對話裏用自然語言描述需求即可，請求會被路由到對應工具。
識別這張圖 <路徑>
對應工具：
vision_analyze
OCR 這張圖 <路徑>
對應工具：
vision_ocr
在這張圖裏找到 <目標>
對應工具：
vision_ground
返回像素座標框。
清點這張圖的所有按鈕
對應工具：
vision_detect
這張圖的主色是什麼
對應工具：
vision_dominant_colors
該工具使用本地算法，不消耗視覺 API。
提取這段長聊天記錄的文字
對應工具：
vision_long_screenshot_ocr
看圖（剪貼板截圖）
對應工具：
vision_clipboard
適用場景與注意事項¶
dsh-vision-skill 適合以下場景：
- 文本模型需要識別圖片內容。
- 需要從圖片中提取文字。
- 需要在圖中定位目標或枚舉元素。
- 需要處理超長截圖。
- 需要分析圖片主色。
- 希望在 DSH 中以原生插件方式管理識圖能力。
使用前需要注意：
- 插件以當前 dsh 進程權限運行。安裝前建議檢查源碼、依賴和許可證。
- 本插件以 runtime 層註冊技能名
vision。如果同時安裝 user 層或 project 層同名技能，可能互相遮蔽，建議二選一安裝。 - 直接貼圖屬於 client/Web 行爲。重啓 web 宿主後，需要強刷瀏覽器才能驗證。
- pi-ai 舊補丁僅作兼容保留。若 dsh 升級後舊補丁被重新打上，可運行：
scripts/restore_pi_ai_vision_patch.py
- 圖片路徑受工作區、DSH 附件目錄或
allowedDirs限制。 - 自定義配置時避免重複 id，否則宿主啓動會失敗。
鏈接¶
GitHub：
https://github.com/DDDFXYqiming/dsh-vision-skill
授權：
MIT
