前言¶

在 DSH Web 中，有些 Agent 只接入文本模型。當用戶上傳圖片、Agent 產生截圖、瀏覽器截圖或讀圖工具返回圖片時，文本模型本身無法直接完成圖片理解；如果需要生成或編輯圖片，也需要額外接入圖片 API。

dsh-vision-mix 是 DeepSeek Harness 的視覺增強插件。它把文本模型、視覺模型和可選圖片生成 API 組合成一個 Mix 模型，用於識圖、跨輪追問、圖片生成與編輯。

這是什麼¶

• 插件名：dsh-vision-mix
• 維護者：haiziyao
• 許可證：MIT
• 定位：DeepSeek Harness 的視覺增強插件
• 用途：把識圖、圖片追問、圖片生成與編輯能力接入 DSH 對話流程

Mix 是插件註冊的模型入口，不是獨立要求單獨填寫 API Key 的模型服務。模型憑據仍由 DSH 的 Provider 配置和憑據系統管理。

核心功能¶

• 把文本模型、視覺模型和可選的圖片生成 API 組合成一個 Mix 模型
• 讓原本不支持圖片的 Agent 識別上傳圖片、理解網頁截圖並持續追問圖片內容
• 支持生成或編輯圖片
• 在“設置 → Vision Mix”中檢測並聲明模型 image 能力
• 支持測試並啓用 image
• 支持強制啓用 image
• 支持獨立的 OpenAI-compatible 圖片生成與編輯 API
• 支持 vision_mix_image_generate 根據提示詞生成新圖片
• 支持 vision_mix_image_edit 編輯當前會話中出現過的用戶圖片或生成圖
• 支持分析 Agent 截圖、瀏覽器截圖和讀圖工具返回的圖片
• 識圖、基礎對話、意圖判斷和生圖可以分別使用不同 Provider

安裝與啓用¶

安裝¶

在 DeepSeek Harness 倉庫目錄執行：

pnpm dsh plugin --profile web add dsh-vision-mix

安裝後啓動 Web：

pnpm dsh web

配置基礎模型與識圖模型¶

先做模型配置：

1. 打開“設置 → 模型”
2. 配置基礎模型
3. 配置識圖模型
4. 識圖、基礎對話、意圖判斷和生圖可以分別使用不同 Provider

如果需要圖片生成與編輯，再配置獨立的 OpenAI-compatible 圖片生成與編輯 API Provider。

檢測並聲明 image 能力¶

在“設置 → Vision Mix”的“模型圖片能力”中完成：

1. 選擇已配置的視覺模型
2. 選擇“測試並啓用 image”或“強制啓用 image”
3. 如果選擇測試，插件會臨時授予該模型 image 能力
4. 測試失敗會自動回滾
5. 啓用成功後，回到“基礎設置”
6. 選擇基礎模型、圖片模型和可選意圖識別模型
7. 點擊“保存路由”

啓用圖片生成與編輯¶

配置圖片生成 Provider 後，在“圖片生成與編輯”中測試生圖 API。

測試生圖 API 會：

• 固定使用 low
• 固定使用 1024×1024
• 固定使用 PNG
• 產生一次實際生圖費用
• 只在內存中預覽並校驗結果
• 不會把測試圖片永久寫入 attachment 存儲

啓用後，可以調用：

• vision_mix_image_generate：根據提示詞生成新圖片
• vision_mix_image_edit：編輯當前會話中出現過的用戶圖片或生成圖

典型用法¶

新建對話，並在模型選擇器中選擇 Mix。下面這些操作都屬於該插件支持的典型場景：

1. 上傳圖片，讓 Agent 識別圖片內容
2. 下一輪繼續追問圖片中的局部或細節
3. 要求 Agent 截圖，並分析 Agent 截圖、瀏覽器截圖或讀圖工具返回的圖片
4. 要求根據提示詞生成圖片
5. 要求編輯當前會話中出現過的用戶圖片或生成圖

憑據、附件與記錄¶

插件的憑據和記錄邊界如下：

• 插件不包含或持久化硬編碼 API Key
• 模型調用通過所選 Provider 的 credential reference 解析憑據
• 配置寫回原 Provider 的模型 profile
• API Key 仍保存在 DSH 憑據系統中
• 會話記錄保存 attachment id，而不是宿主機器絕對路徑或圖片 base64
• vision_mix_attachment_query 只能讀取當前會話消息、工具結果或識圖記錄中出現過的附件
• vision_mix_image_edit 只能編輯當前會話消息、工具結果、識圖記錄或生圖記錄中出現過的附件
• 圖片預覽同時校驗會話 id 和調用記錄 id，不能跨會話枚舉

歷史記錄默認路徑：

識圖歷史：

$DSH_HOME/vision-mix/v1/calls/

生圖歷史：

$DSH_HOME/vision-mix/v1/generations/

適用場景與注意¶

適合以下場景：

• 已在 DSH 中配置文本模型，並希望 Agent 支持上傳圖片、截圖和跨輪追問
• 已配置視覺模型，需要檢測並聲明 image 能力
• 已配置 OpenAI-compatible 圖片生成與編輯 API，希望在對話中生成或編輯圖片

使用前注意：

• 插件以當前 dsh 進程權限運行
• 安裝前應檢查源碼與 MIT 許可證
• 測試圖片能力會臨時授予 image 能力，失敗自動回滾
• 測試生圖 API 固定使用 low、1024×1024、PNG，並會產生一次實際生圖費用
• dsh-better-sidebar 不是必需依賴
• 未安裝 dsh-better-sidebar 時，核心路由、識圖、跨輪追問、生圖和對話圖片顯示仍正常

項目地址¶

GitHub 倉庫：https://github.com/haiziyao/dsh-vision-mix

社區目錄可按插件名 dsh-vision-mix 檢索。