前言¶
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 仓库。
