前言¶
在开发基于 DeepSeek Harness（DSH）的智能体时，我们常面临一个具体问题：项目里配置了 DeepSeek 或 GLM 等纯文本模型，但在处理包含图片的请求（如截图分析、图表读取）时会遭遇拒图或报错。手动切换路由虽然能解决问题，但破坏了 agent 的连续性和习惯。
dsh-mmroute 作为一个 DSH 插件，其核心价值在于“透明化”地解决这一问题。它不要求改变现有的模型调用习惯，而是作为中间层介入 llm/stream 流程，对纯文本模型发出的请求中的图片进行拦截、转述和分发，确保整个 agent 流程能顺畅处理视觉任务。
插件定位¶
- 名称：dsh-mmroute
- 维护者：jmxsxwyzjdwl
- 类别：模型推理
- 开源协议：MIT
- 核心功能：为 DSH 里的每一条模型路由做图片模态调度，贯穿整个 agent 流程。
核心能力¶
该插件主要处理以下场景和功能：
- 图片模态全程调度
从用户上传、read_image结果到 MCP 工具产生的渲染图（如 Figma 截图），所有图片都会被统一处理。 - 文本模型自动转述
对于纯文本模型（或未被标记为多模态的模型），插件会将其请求中的图片转述为详细的文字描述（含逐字转录、图表数据、布局与颜色信息）。 - 图片类报错自愈
如果纯文本模型（或网关）拒图导致请求失败，插件会自动将路由切换至理解模型进行重试，直到成功或达到重试上限。 - 历史图摘要重放
同一张图片在会话历史中再次出现时，会以摘要形式重放（≤1200字符），避免长会话因旧图全量重放而膨胀。 - 结构化转述与 vision_relook
转述内容包含图型判定、全量文字、图表数据等结构化信息。文本模型作答时可调用vision_relook工具，定点复看图片细节，形成“指挥与执行”的协作闭环。 - 多格式支持
支持 PNG、JPEG、WebP、GIF 等常见图片格式。
安装与启用¶
安装过程非常直接，使用官方提供的命令即可：
dsh plugin --profile web add dsh-mmroute
安装后，你需要重启 DSH Web 进程以使插件生效。插件会自动将依赖写入 profile 的 package.json。
使用方法¶
启用插件后，操作流程如下：
- 打开 设置 → 多模态路由。
- 在 「多模态理解模型」 下拉框中选择：
- 自动：使用发现的第一个原生多模态模型。
- 指定：手动选择你配置好的多模态模型（可以是免费云模型或本地模型）。
- （可选）在 「模型模态标记」 中，为个别模型显式选择 默认 / 多模态 / 纯文本。这会覆盖自动判定结果。
- 在对话中直接粘贴或上传图片，或让 agent 调用 MCP 工具产生图片，即可看到自动转述的效果。
注意：v0.6.0 版本起，设置页已简化，仅保留理解模型与模态标记。自动路由、报错自愈、历史图摘要等功能默认开启，后台持续运行。
配置与机制细节¶
- 配置持久化：插件的配置保存在
$DSH_HOME/mmroute目录（默认为~/.dsh/mmroute）。 - 模型标记同步：在设置页标记模型时，插件会自动同步写入
~/.dsh/settings.yaml中的原生input声明（如input: [text, image]），支持热重建路由。 - 缓存限制：转述缓存上限为 300 条，标记上限为 2000 条，超出后按 FIFO 淘汰。
- 并发处理：并发请求中如果转述同一张图，会合并为一次调用。
- 理解模型选择：理解模型可以是任何声明图片输入能力的 provider，不内置免费端点，也不借用任何外部登录态。
适用场景与注意¶
该插件适合需要让纯文本模型（如 DeepSeek、GLM）处理视觉任务的场景。它通过“转述”而非“直发”的方式，确保了纯文本模型能理解图片内容。
在使用前，请确保你已正确配置了用于“理解”图片的多模态模型（例如本地 Ollama 或其他云服务）。插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证。
总结¶
dsh-mmroute 解决了 DSH 生态中纯文本模型与视觉任务之间的鸿沟。它通过拦截层实现了零习惯改变的接入，并提供了报错自愈和结构化转述能力，是目前在多模态路由和 Agent 视觉处理方面较为专业的解决方案。
