前言¶

DSH 的擴展方式是插件化。一個具體場景是：主模型保持 text-only，但聊天框裏已經出現了圖片。dsh-vision-fallback 處理的是這個落差：它不改變主模型，也不要求在 UI 裏額外處理圖片，而是在請求層把圖片自動交給固定視覺模型，轉換後以隱藏文本上下文返回給主模型。

這是什麼¶

dsh-vision-fallback 是 1HelloMan1 維護的 DSH 插件，許可證爲 MIT。

它的核心定位是：主模型照常選擇，圖片自動交給固定視覺模型後，以隱藏上下文返回主模型。聊天框中的原圖仍保留在 UI 中。

已覈實兼容的 DSH 版本包括：

• 0.1.2-alpha.3
• 0.1.2-alpha.4
• 0.1.2-alpha.5

運行要求爲 Node >=22.13.0。

核心功能¶

• 主模型保持 text-only，聊天框圖片自動交給固定視覺模型，並轉換爲隱藏文本上下文；UI 保留原圖。
• 處理 MCP / ACP 持久化附件與 PTC 嵌套圖片，並保持原順序。
• 支持通過 DSH Web 設置頁或 settings.yaml 配置視覺增強。
• 視覺模型請求不使用工具、系統提示或執行權限。
• 切換主模型不會改變固定視覺模型。

安裝與啓用¶

先安裝到 web profile：

dsh plugin --profile web add dsh-vision-fallback

安裝後查看配置層，確認插件已注入：

dsh --profile web --dump-config

在輸出中應能看到：

# == dsh-vision-fallback layer

由於 patch/bundle 層不支持熱加載，需要重啓 web 進程：

dsh web

如果從源碼目錄準備插件，pnpm install 可能需要添加繞過 pre-release peers 限制的參數：

pnpm install --config.minimumReleaseAge=0

典型用法¶

在 DSH Web UI 中進入：

Settings → 視覺增強 / Vision Enhancement

可配置項包括：

• Enabled
• Vision model
• Base URL
• Credential ref

也可以用 settings.yaml 配置。已列出的配置項包括：

vision-fallback:
  enabled: true
  model: <vision-model>
  baseURL: <vision-base-url>
  apiKeyRef: <credential-ref>

apiKeyRef 指向 DSH credentials 中的憑據引用。API key 通過 DSH credentials 解析，不寫入 shell 環境文件。

如果啓用 recordUsage，真實外部視覺調用會追加到：

<dshHome>/vision-fallback/usage.jsonl

該記錄只統計真實外部視覺調用；複用緩存 observation 不追加。

適用場景與注意¶

適合以下場景：

• 主模型是 text-only，但你希望聊天框圖片進入主模型可見的上下文。
• 希望固定一個視覺模型做圖片轉文本，而不隨主模型切換改變。
• 需要處理普通聊天圖片、MCP / ACP 持久化附件、PTC 嵌套圖片，並保持原有順序。

使用前注意：

• 已明確列出的兼容版本是 0.1.2-alpha.3、0.1.2-alpha.4、0.1.2-alpha.5。
• 安裝後需要重啓 dsh web，因爲 patch/bundle 層不支持熱加載。
• 視覺模型請求不使用工具、系統提示或執行權限。
• API key 通過 DSH credentials 解析，不寫入 shell 環境文件。
• 插件以當前 dsh 進程權限運行；安裝前應檢查源碼與許可證。
• usage.jsonl 只記錄真實外部視覺調用，不記錄複用緩存 observation。

參考¶

GitHub：https://github.com/1HelloMan1/dsh-vision-fallback