dsh-multimodal

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# DSH-Multimodal

DSH 多模态输入插件：为不同类型的文件（图片 / 视频 / 音频 / 文本）配置**独立的处理模型链**，在文件进入会话模型之前，先用预设模型把它处理成 Prompt Tokens（文本），再交给会话模型。插件在 DSH 设置中新增独立的 **Multimodal** 页面。

## 解决的问题

DeepSeek 等会话模型只接受文本输入（inputModalities 为 text）。DSH 原生行为是：向这类模型附加图片时直接拒绝（Model does not support image input），视频 / 音频 / 普通文件则根本无法附加。本插件在**发送路径**上拦截文件输入：先调用你配置的多模态模型（如视觉模型）把文件转成描述文本，再把文本作为 Prompt Tokens 发给会话模型。

## 特性

- **设置页**：DSH 设置中新增「Multimodal」菜单页，按通配符为不同文件格式配置预设；
- **预设可增删改**：**自带一个合并默认预设**「多媒体（默认）」——内置 DSH 支持的全部非文本输入类型后缀（png/jpg/jpeg/webp/gif、mp4/webm/mov/mkv/avi/flv/wmv/m4v/mpg/mpeg/ts/3gp、mp3/wav/flac/aac/ogg/opus/m4a/wma/mid/midi），可自由编辑后缀通配符；**可创建多个预设**为不同文件类型配置不同模型（按配置顺序首个匹配生效）；模型链为空时自动使用当前默认模型（即"匹配其多模态输入模型"）；
- **文本原生直通**：文本类型没有预设（所有 LLM 都原生支持文本输入），文本文件永远不做 Multimodal 转换；
- **模型链回退**：每个预设可配置多个模型，按顺序尝试，第一个成功者胜出（如视觉模型失败自动回退到下一个）；**链为空时自动回退到当前默认模型**（内置预设即如此，开箱即可用）；
- **提示词留空 = 使用类型默认**：预设的处理提示词留空时，按文件实际类型自动使用默认提示词（图片为「请仔细分析这张图片的内容，并将其转化为详细的文字描述…」，视频/音频为元数据说明）；custom 预设匹配到图片时同样以**真实图片块**传入处理模型（custom 只决定匹配方式，不改变传入格式）；
- **模型需声明图片能力**：处理模型的 Provider 适配器按模型声明的 input 模态决定是否接收图片（pi-ai 本地模型未声明会直接拒绝：`model does not support image input`）。在 DSH 设置 → 模型 中把本地视觉模型（如 Ollama 的 uGemma4）的 input 配置为 `[text, image]`；
- **图片默认不自动处理**：设置页开关「发送时自动处理图片」**默认关闭**——输入里的图片完全按原生行为处理（多模态会话模型直通、纯文本模型按原生规则拒绝）；开启后，存在匹配预设时自动调用预设模型链转为文本；
- **原生多模态模型直通**：即使开关开启，会话模型本身支持图片输入时图片仍**原样传递**（文本类文件始终不转换）；
- **大小限制**：默认 **10 MB**，每个预设可单独覆盖；
- **两条处理路径**：
  1. **发送路径**（图片）：粘贴 / 拖拽的图片经 `multimodal/send` 接管——**消息立即入日志**（用户消息含图片 + 文字原样显示，输入栏立即清空），描述在**首个模型调用时**由 llm/stream 瀑布惰性解析并注入上下文（日志永不被修改，同一图片+提问只跑一次链）；你输入的文字会一并注入处理提示词；
  2. **附件按钮**（任意文件）：输入框工具行的 ➕ 按钮选择文件，立即处理并把结果插入草稿；
- **兜底重写**：llm/stream 瀑布钩子会把仍然到达模型调用的图片块（如 read_image 工具结果）改写为处理文本；
- **失败策略**：每预设可选「原样传递」或「替换为失败说明」，**默认替换为失败说明**（新预设的默认值）。

## 安装

```sh
# 在 DSH 中挂载（web profile）
dsh plugin --profile web add <本插件路径或 tgz>
# headless profile 也会用到设置时同样挂载
dsh plugin --profile headless add <本插件路径或 tgz>
```

浏览器硬刷新（Ctrl+Shift+R）后，设置中会出现「Multimodal」页。

> 客户端改动热加载，无需重启 dsh web；host 半改动需要重启。

## 使用

1. 打开 **设置 → Multimodal**；
2. 打开「启用 Multimodal 处理」开关；
3. 为预设配置模型链（Provider + 模型，可多行，顺序即回退顺序；用「测试」按钮验证连通性）；
4. 回到会话：粘贴/拖入图片，或点击输入框 ➕ 附加任意文件。

示例：给图片预设配置一个视觉模型 → 发送图片时自动生成描述文本再进入文本会话模型；配置了原生多模态会话模型时，图片则原样交给会话模型。

## 配置（cordis.yml / settings.yaml）

```yaml
plugins:
  multimodal:
    enabled: true
    presets:
      - id: image
        name: 图片
        kind: image
        patterns: []          # 空 = 匹配该类型所有文件；如 [*.png, *.jpg]
        prompt: 请详细描述这张图片…
        maxBytes: 10485760    # 覆盖大小上限（字节，默认 10MB）
        onError: note         # 默认 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**：恢复 DSH 原生行为（文本模型会拒绝图片）。
- **默认行为 = 原生行为**：未配置任何预设、或未开启「发送时自动处理图片」时，图片按会话模型能力处理，文本/视频/音频不附加。

## 开发

```sh
npm install
npm run typecheck   # 类型检查
npm test            # vitest
npm run build       # tsc 类型 + tsdown 打包（lib/index.js + lib/client.js）
npm pack            # 发布包
```

## 架构

- **host 半**（Node）：设置命名空间 multimodal（schemastery schema + cordis.yml 作为 base 层）；/multimodal loopback RPC 通道（presets.get / process / send / chain.test / settings.get / settings.save / settings.reset —— 设置页通过本通道读写命名空间，因为 DSH 的 settings RPC 域不为第三方命名空间提供服务）；模型链执行器（prepareCall + 流式收集，失败回退，空链回退默认模型）；**send 端点**（发送路径接管：复刻准入的持久化转换与上限校验，原始消息经 `agent.followup` **立即**入日志，端点即时返回；多模态会话模型直接返回 native 直通）；**描述缓存**（attachmentId + preset + 提示词 + 用户文字为键，Promise 共享在途调用，一次链调用、全程复用）；llm/stream 瀑布重写（WeakSet 标记防递归；图片块在模型调用层替换为描述文本，按 onError 处理失败；目标模型原生支持图片时跳过）。
- **client 半**（浏览器）：settings.section「Multimodal」设置页；api.sessions.prompt 包装（仅把带图片的 queue 发送路由到 `multimodal/send`，**从不修改消息内容**，失败回退原生发送）；conversation.input.left 附件按钮 + conversation.input.dock 状态行。
- 两端共享同一处理管线（src/process.ts + src/describe.ts）；客户端只做 advisory 匹配，host 端权威校验大小与格式。

## License

MIT