前言¶
DeepSeek Harness (DSH) 的智能體在會話生命週期內鎖定單一的 provider/model。如果會話歷史記錄中包含了圖片，而當前選定的模型不支持圖片輸入，DSH 的內置機制（如 read_image 工具或 ApiProxy）會直接拒絕處理，並提示用戶手動切換整個會話的模型。
這種強制性的全局切換會破壞智能體在會話其他部分對差異化模型的選擇。dsh-plugin-modality-fallback 插件旨在解決這個問題，允許系統在檢測到特定模態缺失時，僅將單個請求路由到具備該模態能力的回退模型，而無需更改整個會話的模型配置。
插件介紹¶
dsh-plugin-modality-fallback 是一個 DeepSeek Harness 插件，用於實現智能體會話中的模態回退路由。
- 維護者：lilei0311
- 定位：不修改 DSH 核心代碼，通過包裝
agent/request流水線提供擴展能力。
該插件在請求發出前檢查會話派生的消息歷史。如果發現當前模型未聲明的模態（目前僅支持 image）且配置了回退路由，它僅針對該請求交換提供者和模型，保持會話原始選擇不變。
核心功能¶
- 檢測模態：讀取會話歷史，檢測是否存在圖片等模態需求。
- 單次路由：僅在配置了回退路由的情況下，針對缺失模態的請求交換提供者/模型。
- 非侵入式：作爲標準 Cordis 插件運行，不觸碰 DSH 核心邏輯。
安裝與配置¶
使用 dsh plugin 命令安裝：
dsh plugin --profile web add dsh-plugin-modality-fallback
或直接從 GitHub 源安裝：
dsh plugin --profile web add github:lilei0311/dsh-plugin-modality-fallback
安裝後，默認配置爲空 fallback: {}，此時行爲與未安裝時一致。需要在 cordis.patch.yml 中配置實際路由：
- id: modality-fallback
config:
fallback:
image: { provider: deepseek-official, model: deepseek-vision }
若在代碼中嵌入 DSH，可程序化加載：
import ModalityFallback from 'dsh-plugin-modality-fallback'
await ctx.plugin(ModalityFallback, {
fallback: {
image: { provider: 'deepseek-official', model: 'deepseek-vision' },
},
})
注意事項與限制¶
- 檢測範圍：當前僅支持檢測
image模態。擴展其他模態需要修改插件代碼，而非路由機制。 - 單次請求限制：每次請求最多解決一種缺失的模態。
- 核心門控不受影響：
read_image和ApiProxy的門控不受本插件影響，它們在插件介入前可能已拒絕請求。 - 未知能力處理：當模型能力未知（
inputModalities爲undefined）時，插件按“具備能力”處理，不觸發回退。 - 推理開銷：路由切換會丟棄繼承的 reasoning effort，回退路由使用其自身的 adapter/provider 默認值。
- 能力探針失敗：若能力探針失敗，插件會記錄警告並保持原路由（Fail Open），不會導致請求失敗。
結語¶
該插件爲 DSH 智能體提供了在不重置整個會話模型的情況下處理特定模態請求的靈活性。適用於需要混合使用不同模型能力的場景。更多細節可參考 GitHub 倉庫。
