前言¶

DeepSeek Harness (DSH) 中的大多數模型（如 deepseek-v4-pro）爲純文本。當用戶粘貼圖片時，網關（如 opencode-go）可能會返回 400 unknown variant image_url。一旦圖片出現在會話日誌中，每次對話回放都會重複此錯誤，導致會話死鎖。dsh-vision-guard 旨在解決這個問題。

簡介¶

dsh-vision-guard 是一個透明圖片防護與視覺分析工具，用於 DeepSeek Harness (dsh)。它由 good-boy4069 開發，採用 MIT 許可證。該插件通過兩道防線，將圖片轉換爲文本，讓文本模型能夠“看見”圖片，同時防止死鎖發生。

核心功能¶

該插件包含以下核心能力：

1. 轉換圖片爲文本：在圖片寫入會話日誌前，先通過視覺模型將其轉換爲文本，防止因日誌中存在圖片塊導致的死鎖。
2. 修復死鎖會話：對於已存在死鎖的會話，插件會在請求時重寫歷史記錄中的圖片爲 OCR 文本，恢復對話功能。
3. vision_analyze 工具：支持本地 OCR、PDF、docx、pptx 以及視頻文件的分析。
4. 原生圖片透傳：通過白名單機制，爲真正支持圖片的路由提供原生支持。
5. 零依賴：純 Node 內置模塊構建，無額外複雜依賴。

安裝與啓用¶

安裝該插件使用以下命令：

dsh plugin --profile web add dsh-vision-guard

安裝完成後，dsh web 進程會自動加載該插件。

典型用法¶

1. 配置視覺路由¶

在 DSH 的配置中，需要指定一個支持圖片的視覺模型。默認配置如下：

visionProvider: opencode-go
visionModel: minimax-m3

請確保 visionModel 指向一個支持圖片輸入的模型。

2. 使用 vision_analyze 工具¶

在模型調用時，可以使用 vision_analyze 工具。該工具通過 engine 參數選擇 OCR 引擎：
* local：本地 OCR（免費，字符識別）。
* vision：使用上述配置的視覺模型。

3. 檢查運行狀態¶

可以通過以下代碼檢查插件運行狀態：

ctx.get('visionGuard')?.status()

4. 配置透傳白名單¶

對於原生支持圖片的路由（如 minimax-m3），需要將其添加到 passthrough 數組中，以避免被重寫爲文本：

passthrough:
  - { provider: "opencode-go", model: "minimax-m3" }

注意事項與限制¶

1. 模型依賴：使用該插件時，必須配置一個支持圖片的模型（例如 minimax-m3）。純文本模型無法作爲視覺模型使用。
2. 系統工具要求：vision_analyze 工具在處理文檔和視頻時，需要系統安裝相應的工具：
   • PDF：pdftotext、pdfimages (poppler-utils)。
   • 視頻：ffmpeg、ffprobe。
   • Office 文檔：python3。
   • 本地 OCR：tesseract (可選)。
3. 圖片大小限制：圖片大小被限制在 5 MB 以內。
4. 輸入安全性：圖片被視爲不受信任的輸入，僅作爲只讀數據。
5. 配置耦合警告：如果在僅文本模型的設置中聲明瞭 input: [text, image]，必須保持該插件安裝，否則會導致死鎖。

總結¶

dsh-vision-guard 通過在日誌寫入前轉換圖片內容和請求時重寫歷史圖片，解決了文本模型與圖片輸入的兼容性問題。它不僅提供了基礎的 OCR 能力，還確保了在插件移除或故障時不會導致系統死鎖。