前言¶
DeepSeek Harness (DSH) 的設計理念是“一切皆插件”，允許通過插件擴展系統功能。對於開發者而言，本地或開源的會話模型通常只接受文本輸入（inputModalities 爲 text）。當原生模型不支持圖片或其他文件格式時，DSH 的默認行爲是直接拒絕圖片輸入（報錯 Model does not support image input），或者根本無法附加視頻、音頻及普通文件。
dsh-multimodal 插件解決了這個問題。它在文件進入會話模型之前攔截輸入，通過預設的模型鏈將圖片、視頻或音頻轉換爲文本描述（Prompt Tokens），再由會話模型處理。這允許用戶利用視覺模型或其他處理模型來預處理多模態內容。
核心功能¶
本插件在 DSH 設置中新增獨立的 Multimodal 頁面，提供以下能力：
- 獨立配置處理鏈：爲不同文件類型（圖片、視頻、音頻、文本）配置獨立的處理模型鏈。每個預設可以包含多個模型，按順序嘗試，首個成功者勝出。
- 預設管理：插件自帶一個默認預設「多媒體（默認）」，涵蓋了常見圖片（png/jpg/webp/gif）、視頻（mp4/webm 等）和音頻格式。用戶可以創建多個預設，通過通配符匹配特定文件類型。
- 文本原生直通：文本類型沒有預設，文件內容始終原樣傳遞，不做轉換。
- 智能回退：如果配置的模型鏈爲空或處理失敗，系統會自動回退到當前會話的默認模型。
- 提示詞配置：預設的處理提示詞可以自定義，留空時則使用系統爲該類型文件定義的默認提示詞。
- 模型能力校驗：處理模型必須聲明圖片能力。Provider 適配器會根據模型聲明的
input模態決定是否接收圖片，否則會直接拒絕（例如本地模型未配置input: [text, image]時）。 - 處理開關與路徑：
- 默認不處理：圖片默認不自動處理，完全按原生行爲（原生多模態模型直通，純文本模型拒絕）。
- 兩條路徑：支持“發送路徑”（粘貼/拖拽圖片）和“附件路徑”（輸入框 ➕ 按鈕）。
- 大小限制：默認大小限制爲 10 MB，每個預設可單獨覆蓋。
- 失敗策略：每預設可選「原樣傳遞」或「替換爲失敗說明」。
安裝¶
使用 DSH 官方 CLI 安裝插件。請將 <本插件路徑或 tgz> 替換爲實際的文件路徑或 Tgz 包名。
# 在 web profile 中掛載
dsh plugin --profile web add <本插件路徑或 tgz>
# headless profile 同樣適用
dsh plugin --profile headless add <本插件路徑或 tgz>
安裝後，瀏覽器硬刷新（Ctrl+Shift+R）即可在設置中看到「Multimodal」頁面。若修改了 host 端代碼，可能需要重啓 DSH。
使用¶
啓用並配置插件後，使用步驟如下：
- 打開 設置 → Multimodal。
- 打開「啓用 Multimodal 處理」開關。
- 爲預設配置模型鏈。在設置中指定 Provider 和模型名稱（可多行），順序即爲回退順序。使用「測試」按鈕驗證連通性。
- 回到會話界面：
- 發送路徑：直接粘貼或拖拽圖片。圖片會立即進入日誌，並在首個模型調用時被轉換爲文本描述。
- 附件路徑：點擊輸入框的 ➕ 按鈕，選擇任意文件（視頻/音頻等），系統會自動處理並存入草稿。
配置示例¶
配置文件通常位於 DSH 的設置目錄下（如 settings.yaml）。以下是一個配置圖片預設的示例，使用 deepseek-official 和 openai 作爲備選視覺模型：
plugins:
multimodal:
enabled: true
presets:
- id: image
name: 圖片
kind: image
patterns: [] # 空 = 匹配該類型所有文件
prompt: 請詳細描述這張圖片…
maxBytes: 10485760 # 覆蓋大小上限（字節，默認 10MB）
onError: note # 默認替換爲失敗說明；或 pass-through
models:
- provider: deepseek-official
model: deepseek-chat
- provider: openai
model: gpt-4o
限制與注意事項¶
在使用前需瞭解以下限制：
- 視頻/音頻處理：適配層目前只支持提取文本與圖片內容塊（即元數據簡報，包含文件名/類型/大小/MIME），無法直接轉寫音頻或視頻內容。轉錄功能需在會話中使用相應工具。
- 圖片格式：僅支持 DSH 附件服務接受的 png / jpeg / webp / gif 格式。
- 遠程瀏覽器：
/multimodal通道爲 loopback 授權，遠程瀏覽器不生效。 - Pass-through 策略：若處理失敗且策略設爲
pass-through，系統將恢復 DSH 原生行爲（例如純文本模型會拒絕圖片）。 - 默認行爲：未配置預設或未開啓「發送時自動處理圖片」時，圖片按會話模型能力處理；文本/視頻/音頻不附加。
結語¶
dsh-multimodal 爲 DSH 提供了靈活的多模態預處理能力。通過在會話模型之前插入視覺模型鏈，它解決了原生文本模型無法處理圖片附件的問題。開發者可以根據實際需求配置不同的預設和回退策略，以適配各種本地部署的模型組合。
