前言¶
在 DeepSeek Harness (DSH) 的生態中，純文本主模型（如 DeepSeek 系列模型）無法直接處理圖像。處理 UI 審查、OCR 或看圖問答時，通常需要啓動一個獨立的視覺子代理，這帶來了額外的上下文開銷和狀態管理的複雜性。
dsh-vision-resident 解決了這個問題。它是一個常駐在宿主進程裏的視覺助手插件，不依賴額外的子代理進程，而是通過掛載鉤子和組件，讓純文本主模型也能“看”圖。
是什麼¶
這是一個 DeepSeek Harness 的記憶類插件，由 AnnanRen 維護，採用 MIT 許可證。
它的核心價值在於：
1. 零子代理開銷：視覺模型直連（通過 ctx.llm.stream），每次識別只是一次 LLM 推理，沒有 agent 上下文初始化成本。
2. 常駐對話：視覺子代理擁有持續的上下文，記住看過的圖與識別結果，追問時不需要重複發送圖片。
3. 按會話隔離：每個 DSH 對話擁有獨立的視覺歷史、上下文與計數，互不串擾。
4. 持久化與清理：識別歷史與轉譯緩存落盤，重啓不丟失；支持歸檔聯動與閒置清理。
核心功能¶
工具與鉤子¶
插件提供了 describe_image 和 subagent_vision 兩個工具，用於讀取磁盤圖片並轉換爲文字結果。同時，它通過 llm/stream 鉤子實現了“粘貼圖片自動轉譯”功能：當主模型不支持圖片時，插件會自動調用視覺模型將圖片轉成文字注入請求。
狀態膠囊與詳情頁¶
在輸入框左側有一個狀態膠囊，實時顯示視覺子代理的工作狀態、模型名稱及識別次數。點擊膠囊可以打開摺疊式的詳情頁，查看每張圖的識別歷史（指令、思考過程、輸出），支持 Esc 或點擊背景關閉。
會話管理¶
視覺歷史按 DSH 對話隔離，默認保留最近 10 輪識別記錄。會話上限爲 40 條（LRU 策略），閒置超過 30 天的記錄會被自動清理。
安裝與啓用¶
安裝需要手動 clone 代碼並掛載到 DSH 的 profile 中。
- Clone 倉庫到本地：
git clone https://github.com/AnnanRen/dsh-vision-resident.git
- 創建軟鏈接掛載到 node_modules：
ln -s "$PWD/dsh-vision-resident" ~/.dsh/profiles/node_modules/dsh-vision-resident
- 編輯
~/.dsh/profiles/web/cordis.patch.yml，在insert列表中添加：
- id: dsh-vision-resident
name: dsh-vision-resident
- 重啓 DSH Web 服務。
配置¶
視覺模型設置¶
默認使用 opencode-go/mimo-v2.5 作爲主模型，opencode-go/minimax-m3 作爲回退。可以通過環境變量覆蓋：
export VISION_PROVIDER=opencode-go
export VISION_MODEL=mimo-v2.5
export VISION_FALLBACK_MODELS=opencode-go/minimax-m3
純文本主模型圖片准入¶
Harness 會檢查選中模型的 input 聲明。要讓純文本模型（如 deepseek-v4-flash）支持粘貼圖片，需在 ~/.dsh/settings.yaml 中聲明：
input: [text, image]
對於內置在 force-convert 名單中的模型（如 deepseek-v4-flash / deepseek-v4-pro），插件會強制轉譯，不將原圖直送上游。
使用方法¶
- 讀取磁盤圖片：
使用describe_image或subagent_vision工具，傳入image_path參數。例如：
await ctx.callTool('describe_image', { image_path: '/path/to/screenshot.png' });
-
純文字追問：
省略image_path參數，直接基於視覺子代理已知的上下文進行純文本追問。 -
自定義模型：
通過上述環境變量切換視覺模型或配置回退鏈。
已知限制¶
- 模型切換限制：當會話中已有圖片時，如果切換到不支持圖片的模型，會被 Harness 拒絕（
model-unavailable），需要開新會話才能切換。 - 工具剝離：當前提示詞中包含圖片時，工具會被剝掉（爲了防止弱模型反射性搜文件），建議分步操作。
- 歷史上下文：歷史上下文只包含文字，不包含歷史圖片。多圖請求在部分端點上可能不穩定，且歷史識別結果本身已是完整文字描述。
- 會話清理：主會話歸檔後，對應的視覺記錄會在 30 秒內清除。
結語¶
dsh-vision-resident 通過將視覺能力集成到主進程流中，爲 DSH 提供了一種輕量級的視覺增強方案。它適合需要頻繁進行視覺任務但不想引入複雜多代理架構的場景。
更多細節與源碼，請訪問 GitHub 倉庫。
