前言¶
在開發基於 DeepSeek Harness（DSH）的智能體時，我們常面臨一個具體問題：項目裏配置了 DeepSeek 或 GLM 等純文本模型，但在處理包含圖片的請求（如截圖分析、圖表讀取）時會遭遇拒圖或報錯。手動切換路由雖然能解決問題，但破壞了 agent 的連續性和習慣。
dsh-mmroute 作爲一個 DSH 插件，其核心價值在於“透明化”地解決這一問題。它不要求改變現有的模型調用習慣，而是作爲中間層介入 llm/stream 流程，對純文本模型發出的請求中的圖片進行攔截、轉述和分發，確保整個 agent 流程能順暢處理視覺任務。
插件定位¶
- 名稱：dsh-mmroute
- 維護者：jmxsxwyzjdwl
- 類別：模型推理
- 開源協議：MIT
- 核心功能：爲 DSH 裏的每一條模型路由做圖片模態調度，貫穿整個 agent 流程。
核心能力¶
該插件主要處理以下場景和功能：
- 圖片模態全程調度
從用戶上傳、read_image結果到 MCP 工具產生的渲染圖（如 Figma 截圖），所有圖片都會被統一處理。 - 文本模型自動轉述
對於純文本模型（或未被標記爲多模態的模型），插件會將其請求中的圖片轉述爲詳細的文字描述（含逐字轉錄、圖表數據、佈局與顏色信息）。 - 圖片類報錯自愈
如果純文本模型（或網關）拒圖導致請求失敗，插件會自動將路由切換至理解模型進行重試，直到成功或達到重試上限。 - 歷史圖摘要重放
同一張圖片在會話歷史中再次出現時，會以摘要形式重放（≤1200字符），避免長會話因舊圖全量重放而膨脹。 - 結構化轉述與 vision_relook
轉述內容包含圖型判定、全量文字、圖表數據等結構化信息。文本模型作答時可調用vision_relook工具，定點復看圖片細節，形成“指揮與執行”的協作閉環。 - 多格式支持
支持 PNG、JPEG、WebP、GIF 等常見圖片格式。
安裝與啓用¶
安裝過程非常直接，使用官方提供的命令即可：
dsh plugin --profile web add dsh-mmroute
安裝後，你需要重啓 DSH Web 進程以使插件生效。插件會自動將依賴寫入 profile 的 package.json。
使用方法¶
啓用插件後，操作流程如下：
- 打開 設置 → 多模態路由。
- 在 「多模態理解模型」 下拉框中選擇：
- 自動：使用發現的第一個原生多模態模型。
- 指定：手動選擇你配置好的多模態模型（可以是免費雲模型或本地模型）。
- （可選）在 「模型模態標記」 中，爲個別模型顯式選擇 默認 / 多模態 / 純文本。這會覆蓋自動判定結果。
- 在對話中直接粘貼或上傳圖片，或讓 agent 調用 MCP 工具產生圖片，即可看到自動轉述的效果。
注意：v0.6.0 版本起，設置頁已簡化，僅保留理解模型與模態標記。自動路由、報錯自愈、歷史圖摘要等功能默認開啓，後臺持續運行。
配置與機制細節¶
- 配置持久化：插件的配置保存在
$DSH_HOME/mmroute目錄（默認爲~/.dsh/mmroute）。 - 模型標記同步：在設置頁標記模型時，插件會自動同步寫入
~/.dsh/settings.yaml中的原生input聲明（如input: [text, image]），支持熱重建路由。 - 緩存限制：轉述緩存上限爲 300 條，標記上限爲 2000 條，超出後按 FIFO 淘汰。
- 併發處理：併發請求中如果轉述同一張圖，會合併爲一次調用。
- 理解模型選擇：理解模型可以是任何聲明圖片輸入能力的 provider，不內置免費端點，也不借用任何外部登錄態。
適用場景與注意¶
該插件適合需要讓純文本模型（如 DeepSeek、GLM）處理視覺任務的場景。它通過“轉述”而非“直髮”的方式，確保了純文本模型能理解圖片內容。
在使用前，請確保你已正確配置了用於“理解”圖片的多模態模型（例如本地 Ollama 或其他雲服務）。插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證。
總結¶
dsh-mmroute 解決了 DSH 生態中純文本模型與視覺任務之間的鴻溝。它通過攔截層實現了零習慣改變的接入，並提供了報錯自愈和結構化轉述能力，是目前在多模態路由和 Agent 視覺處理方面較爲專業的解決方案。
