前言¶
DeepSeek Harness (DSH) 的设计理念是“一切皆插件”，允许通过插件扩展系统功能。对于开发者而言，本地或开源的会话模型通常只接受文本输入（inputModalities 为 text）。当原生模型不支持图片或其他文件格式时，DSH 的默认行为是直接拒绝图片输入（报错 Model does not support image input），或者根本无法附加视频、音频及普通文件。
dsh-multimodal 插件解决了这个问题。它在文件进入会话模型之前拦截输入，通过预设的模型链将图片、视频或音频转换为文本描述（Prompt Tokens），再由会话模型处理。这允许用户利用视觉模型或其他处理模型来预处理多模态内容。
核心功能¶
本插件在 DSH 设置中新增独立的 Multimodal 页面，提供以下能力：
- 独立配置处理链：为不同文件类型（图片、视频、音频、文本）配置独立的处理模型链。每个预设可以包含多个模型，按顺序尝试，首个成功者胜出。
- 预设管理：插件自带一个默认预设「多媒体（默认）」，涵盖了常见图片（png/jpg/webp/gif）、视频（mp4/webm 等）和音频格式。用户可以创建多个预设，通过通配符匹配特定文件类型。
- 文本原生直通：文本类型没有预设，文件内容始终原样传递，不做转换。
- 智能回退：如果配置的模型链为空或处理失败，系统会自动回退到当前会话的默认模型。
- 提示词配置：预设的处理提示词可以自定义，留空时则使用系统为该类型文件定义的默认提示词。
- 模型能力校验：处理模型必须声明图片能力。Provider 适配器会根据模型声明的
input模态决定是否接收图片，否则会直接拒绝（例如本地模型未配置input: [text, image]时）。 - 处理开关与路径：
- 默认不处理：图片默认不自动处理，完全按原生行为（原生多模态模型直通，纯文本模型拒绝）。
- 两条路径：支持“发送路径”（粘贴/拖拽图片）和“附件路径”（输入框 ➕ 按钮）。
- 大小限制：默认大小限制为 10 MB，每个预设可单独覆盖。
- 失败策略：每预设可选「原样传递」或「替换为失败说明」。
安装¶
使用 DSH 官方 CLI 安装插件。请将 <本插件路径或 tgz> 替换为实际的文件路径或 Tgz 包名。
# 在 web profile 中挂载
dsh plugin --profile web add <本插件路径或 tgz>
# headless profile 同样适用
dsh plugin --profile headless add <本插件路径或 tgz>
安装后，浏览器硬刷新（Ctrl+Shift+R）即可在设置中看到「Multimodal」页面。若修改了 host 端代码，可能需要重启 DSH。
使用¶
启用并配置插件后，使用步骤如下：
- 打开 设置 → Multimodal。
- 打开「启用 Multimodal 处理」开关。
- 为预设配置模型链。在设置中指定 Provider 和模型名称（可多行），顺序即为回退顺序。使用「测试」按钮验证连通性。
- 回到会话界面：
- 发送路径：直接粘贴或拖拽图片。图片会立即进入日志，并在首个模型调用时被转换为文本描述。
- 附件路径：点击输入框的 ➕ 按钮，选择任意文件（视频/音频等），系统会自动处理并存入草稿。
配置示例¶
配置文件通常位于 DSH 的设置目录下（如 settings.yaml）。以下是一个配置图片预设的示例，使用 deepseek-official 和 openai 作为备选视觉模型：
plugins:
multimodal:
enabled: true
presets:
- id: image
name: 图片
kind: image
patterns: [] # 空 = 匹配该类型所有文件
prompt: 请详细描述这张图片…
maxBytes: 10485760 # 覆盖大小上限（字节，默认 10MB）
onError: note # 默认替换为失败说明；或 pass-through
models:
- provider: deepseek-official
model: deepseek-chat
- provider: openai
model: gpt-4o
限制与注意事项¶
在使用前需了解以下限制：
- 视频/音频处理：适配层目前只支持提取文本与图片内容块（即元数据简报，包含文件名/类型/大小/MIME），无法直接转写音频或视频内容。转录功能需在会话中使用相应工具。
- 图片格式：仅支持 DSH 附件服务接受的 png / jpeg / webp / gif 格式。
- 远程浏览器：
/multimodal通道为 loopback 授权，远程浏览器不生效。 - Pass-through 策略：若处理失败且策略设为
pass-through，系统将恢复 DSH 原生行为（例如纯文本模型会拒绝图片）。 - 默认行为：未配置预设或未开启「发送时自动处理图片」时，图片按会话模型能力处理；文本/视频/音频不附加。
结语¶
dsh-multimodal 为 DSH 提供了灵活的多模态预处理能力。通过在会话模型之前插入视觉模型链，它解决了原生文本模型无法处理图片附件的问题。开发者可以根据实际需求配置不同的预设和回退策略，以适配各种本地部署的模型组合。
