2026 年 10 月 3 日，DeepSeek Harness (DSH) 依然秉持“一切皆插件”的設計理念。純文本模型缺乏處理圖像的能力，這是構建視覺智能體時的常見痛點。dsh-vision-bridge 插件旨在爲純文本模型補充視覺能力，它既可以複用 DSH 現有的 Provider，也支持配置任意 OpenAI 兼容的多模態 API。該插件由 alaxrpg 維護。
核心功能¶
插件提供以下核心能力：
vision_bridge_read_image工具：模型可主動調用該工具識別圖片，返回結構化文本證據，包含 OCR 文本、佈局信息和語義描述。- 粘貼圖片自動接管：在支持 TEXTAREA、INPUT 或 contenteditable（DSH 0.1.2-alpha+）的輸入框中粘貼圖片時，插件會自動上傳圖片，並插入緊湊的引用標記（例如
「▧ 圖片 #KdAy1D」），供模型後續調用視覺工具。 - 無廠商硬編碼：Provider 與模型列表實時讀取 DSH registry，不進行廠商硬編碼。
- 可視化配置：在設置頁的“插件 → 視覺橋接”子菜單中，可以選擇 DSH Provider，或新增自定義 OpenAI 兼容 Provider，保存後熱生效。
- 連通性測試：提供一鍵測試功能，向視覺 API 發送測試圖，返回延遲與響應樣本。
- 複用現有通道：選擇 DSH Provider 時，複用其 adapter、憑據和 attachment 通道，不註冊額外的 wrapper provider。
安裝與啓用¶
使用官方 CLI 安裝插件（會自動寫入 bundles）：
dsh plugin --profile web add github:alaxrpg/dsh-vision-bridge
安裝完成後，插件會加載到當前 DSH 進程中。
配置¶
推薦使用 GUI 設置頁進行配置。安裝並重啓 DSH 後，進入“設置 → 插件 → 視覺橋接”。
Provider 模式¶
- DSH Provider 模式：從 DSH 當前已添加的 Provider 與模型中選擇。圖片經 DSH attachment store 保存後交給選中 Provider 的 adapter。插件不讀取該 Provider 的 Base URL 或密鑰，憑據由其 adapter 管理。
- 自定義 Provider 模式：配置 OpenAI 兼容直連。自定義 Provider 只屬於本插件，不會註冊到 DSH 全局 Provider。
API Key 配置¶
若使用自定義 Provider，API Key 有以下優先級：
1. vision-bridge.apiKey（配置頁輸入或 settings.yaml 直填）。
2. vision-bridge.apiKeyEnv：通過 DSH 憑據服務解析，優先級高於環境變量文件。
重要說明：配置接口 GET /vision-bridge/config 永遠只返回 keySource 和 keyResolved 的布爾狀態，不會回顯密鑰。
桌面端說明¶
桌面端宿主啓動時，會將 settings.yaml 一次性導入內部存儲並改名 settings.yaml.imported。桌面端不向本插件注入 settings 服務。
爲此，插件做了以下兜底處理：
* 讀取時將 settings.yaml.imported 加入候選文件。
* 設置頁的“保存”按鈕在 settings 服務不可用時，會退化爲直寫 settings.yaml，寫後立即熱生效。
手動配置（YAML）¶
也可以直接編輯 ~/.dsh/settings.yaml：
vision-bridge:
enabled: true
providerMode: dsh
provider: your-dsh-provider-id
model: your-vision-model-id
timeout: 90
外部編輯配置文件同樣會被監聽並熱生效。
使用方法¶
配置完成後，插件提供兩種使用方式：
1. 模型主動調用工具¶
模型可以主動調用 vision_bridge_read_image 工具。示例命令：
使用 vision_bridge_read_image 工具識別圖片：/path/to/image.png
2. 粘貼圖片自動處理¶
用戶直接粘貼圖片時，插件會自動上傳圖片並插入引用標記。模型在上下文中看到該標記後，會自動調用視覺工具進行處理。
輸出格式¶
工具調用後會返回結構化 JSON 證據：
{
"summary": "圖片整體描述",
"ocr": {
"full_text": "完整 OCR 文本",
"lines": [{"text": "行文本", "language": "zh"}]
},
"layout": {
"regions": [{"type": "heading", "reading_order": 1, "text": "..."}]
},
"semantics": {
"scene": "場景描述",
"entities": [{"name": "實體名", "type": "類型"}]
},
"uncertainty": ["不確定項"]
}
技術細節與兼容性¶
- 兼容性：DSH 0.1.1+，Node.js 18+，支持 macOS / Linux。
- 依賴項：
@deepseek-ai/dsh-credentials(>=0.1.1-rc.1)，@deepseek-ai/schemastery(>=3.18.1)。 - 路由：
GET /vision-bridge/config：讀取配置狀態。POST /vision-bridge/config：保存配置。GET /vision-bridge/test：連通性測試。POST /vision-bridge/paste：粘貼上傳處理。GET /vision-bridge/verdict：判斷是否接管粘貼。
- 客戶端：classic script 經
__ModuleLoader__加載，粘貼攔截在無插件上下文時也照常工作。
