ShuiHan268/dsh-qwen-mm-plugins

dsh-qwen-mm-plugins

English · 中文

为 DeepSeek Harness（DSH）接入 QwenLM/Qwen-MM-Plugins 云端多模态能力的插件。

特性

- MCP 工具 — 12 个 mcp__qwen-mm-plugins-api__* 工具：vision_chat（图像理解）、ocr、grounding、transcribe_audio（ASR）、omni_multi_speaker_asr（说话人分离）、omni_av_caption / omni_av_grounding（音视频理解）等。
- 内置技能 — qwen-mm-plugins-api 技能随插件分发，无需手动复制到 ~/.dsh/skills。
- 设置页面 — Web GUI → 设置 → Qwen 多模态：粘贴 Qwen API Key 即可用；密钥存入凭据库 $DSH_HOME/.credentials.yaml（0600），不进会话日志。
- 热生效 — 保存或轮换 key 后 MCP 子进程自动重启，无需重启 DSH。
- 能力管理 — 8 个能力（core / api / search / video-memory / video-edit / blender / freecad / edu-agent）带三态管理：未安装 → 未启用 → 已启用，支持一键安装/启用/停用。
- /qwen-mm 命令 — status、verify、caps、install 、disable 、model set  。
- 模型配置 — 设置页的「模型」卡片可随时修改 VL / Omni 模型，保存后立即生效，无需重启 DSH。

快速安装

前提：Node ≥ 18，已安装 DeepSeek Harness，并且 pnpm 或 Corepack 至少有一个可用。

1. 获取插件源码
git clone git@github.com:ShuiHan268/dsh-qwen-mm-plugins.git

2. 一键安装（幂等，可重复执行）
cd dsh-qwen-mm-plugins
node install.js

3. 重启 DSH
npx @deepseek-ai/dsh web

安装器自动完成：创建 web profile → 安装 uv（缺失时）→ 构建插件 venv（不可变 tag 源码）→ 通过 profile 的 pnpm 布局注册插件（pnpm 不在 PATH 时使用 Corepack）→ 规范化 YAML patch → 运行系统自检。重复执行会修复中断状态和旧版 npm 安装布局。

打开 设置 → Qwen 多模态，粘贴 Qwen API Key 并保存。若本机存在旧版 ~/.qwen-mm-plugins/config，其中的 key 会自动迁移，无需重填。

可选参数：

- --install-source ：能力安装源改用本地 checkout（离线/镜像场景）。
- --skip-venv：跳过 venv 构建，交由插件首次启动时后台自动预置。
- DSH_HOME=：自定义 DSH 主目录（默认 ~/.dsh）。

在 DeepSeek Harness 插件目录中安装

也可以完全不用 install.js：在 DeepSeek Harness 的插件目录中，直接以对话的方式让 Agent 安装本插件，注册与配置由 Agent 自动完成。

使用

安装并启用能力后，不需要手动选择——直接在对话框里用自然语言说出需求、用 @ 引用文件即可，模型会自动调用对应的能力工具。

常见用法举例：

| 想做的事 | 直接这样说 |
|---|---|
| 看图/问图 | @photo.jpg 这张图里有什么？ |
| 提取文字 | 用 OCR 提取 @scan.png 里的文字 |
| 音频转文字 | 把 @meeting.wav 转成带时间戳的字幕 |
| 多人会议记录 | @meeting.mp4 区分说话人转写 |
| 视频要点 | 按时间线总结 @lecture.mp4 的主要观点 |
| 读文档/表格 | 总结 @report.pdf 第 3 页并提取表格（需先安装 core） |

需要记住的三点：

1. 不用选能力：每个能力启用后，它的工具就进入了模型目录；配好 Qwen API Key 的 api 能力开箱即用；
2. 新开会话再用：刚安装/启用的能力，建议新建一个会话后再用，新工具才能完整生效；
3. 随时查状态：对话里发 /qwen-mm caps，或在 设置 → Qwen 多模态 查看各能力是"未安装 / 未启用 / 已启用"。

注意事项：core、video-memory 需要先点安装（下载依赖约 1-2 分钟）；search 还需要搜索服务的 key（Serper/Exa/Tavily）；blender、freecad 需要本机已装对应软件；音视频工具需要 ffmpeg。

能力管理

| 状态 | 徽章 | 按钮 |
|---|---|---|
| 未安装 | 灰 | [安装] |
| 未启用 | 黄 | [启用] |
| 已启用 | 绿 | [停用] |
| 安装中… | 黄 | — |

- 安装向共享 venv 补充依赖并挂载该能力的 MCP 工具；停用移除工具、依赖保留，可随时重新启用。
- 不提供依赖级卸载：上游为单一发行包、能力间共享依赖，无法安全地按能力卸载。
- edu-agent 为纯 Skill，未随本插件分发；api 为核心能力，不可停用。

界面说明

安装并完成配置后，打开 设置 → Qwen 多模态（左侧导航中与"通用设置、模型"等并列），界面如下：

Qwen 多模态设置页

- Qwen API Key 卡片：粘贴阿里云百炼的 Qwen API Key，点「保存」立即生效；右上角圆点表示配置状态（绿 = 已配置，红 = 未配置）；
- 能力卡片：列出全部 8 个能力，每行包含能力名、状态徽章（未安装 / 未启用 / 已启用 / 安装中…）与操作按钮（安装 / 启用 / 停用）；缺系统依赖时显示提示（如上图中 blender 的「缺系统依赖：blender」）；
- 状态即时刷新：点击按钮后状态自动更新，安装完成后的依赖探测结果也会在数秒内同步到页面。

手动安装

与安装器等价的步骤，供排障或定制。

1. 通过 profile 包管理器加入插件

cd ~/.dsh/profiles/web
corepack pnpm add file:/插件源码的绝对路径/dsh-qwen-mm-plugins

不要直接在 node_modules 中创建符号链接：这会绕过 DSH 的 pnpm 依赖布局，导致插件无法解析 DSH peer dependencies。

2. 在 ~/.dsh/profiles/web/cordis.patch.yml 插入插件行

- insert:
- id: qwen-mm-plugins
name: 'dsh-qwen-mm-plugins'
config:
venvPath: '/Users/你的用户名/.dsh/mcp-envs/qwen-mm-plugins'   # 有预建 venv 时
留空则走 uvx + 不可变 tag（需要 uvx 与 GitHub 访问）

3. 预置 Python 环境

- 自动预置（推荐）：配置 venvPath 且 venv 缺失时，插件会在后台用 uv 构建并自动切换（要求 PATH 里有 uv）。
- 手动预建 venv（运行时不依赖网络与 uv；--python '>=3.10' 让 uv 自动选合适的解释器，本机没有时会自动下载）：
uv venv --python '>=3.10' ~/.dsh/mcp-envs/qwen-mm-plugins
uv pip install --python ~/.dsh/mcp-envs/qwen-mm-plugins/bin/python \
"qwen-mm-plugins[api] @ git+https://github.com/QwenLM/Qwen-MM-Plugins.git@qwen-mm-plugins-api-v1.0.3"

- 留空 venvPath：直接用 uvx --from "qwen-mm-plugins[api] @ git+…" 拉起。

4. 重启 DSH

打开 设置 → Qwen 多模态 粘贴 API Key 保存即可。

依赖

- ffmpeg / ffprobe（音视频工具；macOS：brew install ffmpeg；Debian/Ubuntu：apt install ffmpeg）。
- Qwen API Key：阿里云百炼 密钥管理（免费额度每模型 100 万 token / 90 天；ASR 类模型需在业务空间开通）。

工作原理

- 密钥经 DSH 凭据缝（ctx.credentials，ref QMP_DASHSCOPE_API_KEY）存取；页面使用内置 api.credentials.{describe,set} 远程。DSH 0.1.0-rc.6 的 settings 配置边界是硬编码白名单，credentials 是第三方插件存 API key 的官方通道。
- 能力状态经会话投影 qwen-mm-caps 推送；安装/停用经会话命令通道 /qwen-mm … 执行，状态随命令生命周期事件自动刷新。
- MCP 子进程的 key 以环境变量注入（Qwen 插件每次调用时读取），保存后 credentials/updated 触发子进程重建。

测试

node test/host.test.mjs    # host：Config、凭据→env、技能提供者、热切换、迁移、能力生命周期
node test/client.test.mjs  # client：bundle 注册冒烟测试
node test/install-profile.test.mjs # YAML patch 规范化与 pnpm runner 选择
node test/install-script.test.mjs  # 中断安装修复与幂等性

完整集成验证用隔离 dry-boot：把 profile 复制到临时 DSH_HOME，webserver 端口 patch 为 0，启动后检查日志无 error/failed、MCP 子进程已拉起、首页 boot graph 含 dsh-qwen-mm-plugins 模块记录。

说明与限制

- 媒体文件经本地预处理后上传 DashScope 云端，敏感内容请勿使用。
- gitTag 默认 qwen-mm-plugins-api-v1.0.3，可随上游发布更新。

License

Apache-2.0