deepseek-visual-plugin

前言¶

DeepSeek Harness 的理念是“一切皆插件”。在构建智能体时，纯文本模型无法直接处理图片输入。本插件解决了这个问题：它拦截含图片的消息，判断当前模型是否原生支持 image。多模态模型直接放行，纯文本模型则调用视觉模型生成描述，再把图片块替换为文字。这样，纯文本模型也能“看懂”图片。

安装与启用¶

本插件以单文件 ESM 插件形式部署到 Harness 家目录，通过 home 级补丁启用，对所有 profile（web / headless 及未来新建的 profile）生效。

Windows（PowerShell）

# 1. 部署插件代码
$dest = "$env:USERPROFILE\.dsh\profiles\node_modules\deepseek-visual-plugin"
New-Item -ItemType Directory -Path $dest -Force | Out-Null
Copy-Item index.js, package.json, cordis.patch.yml -Destination $dest -Force

# 2. 在 $DSH_HOME/cordis.patch.yml 中加入（不存在则创建）
# - insert:
#     - id: deepseek-visual
#       name: deepseek-visual-plugin
#       config:
#         model: <视觉模型名>
#         baseUrl: <OpenAI 兼容端点>
#         apiKeyEnv: <凭证引用名>

Linux / macOS（Bash / Zsh）

# 1. 部署插件代码
dest="$HOME/.dsh/profiles/node_modules/deepseek-visual-plugin"
mkdir -p "$dest"
cp index.js package.json cordis.patch.yml "$dest"

# 2. 在 $DSH_HOME/cordis.patch.yml 中加入
# - insert:
#     - id: deepseek-visual
#       name: deepseek-visual-plugin
#       config:
#         model: <视觉模型名>
#         baseUrl: <OpenAI 兼容端点>
#         apiKeyEnv: <凭证引用名>

也可以作为常规 bundle 安装进单个 profile：

dsh plugin --profile web add C:\path\to\deepseek-visual-plugin

配置¶

插件通过 cordis.patch.yml 配置。可调参数如下：

API Key 的解析优先级：config.apiKey（显式覆盖）→ config.apiKeyEnv（credentials 服务解析 ~/.dsh/.credentials.yaml）→ 环境变量回退（QWEN_API_KEY / DASHSCOPE_API_KEY / OPENAI_API_KEY）。

推荐做法：把 key 存进 ~/.dsh/.credentials.yaml，配置里只写 apiKeyEnv 引用，避免明文密钥落在配置文件里。

# ~/.dsh/.credentials.yaml
DOUBAO_API_KEY: <你的 key>

# cordis.patch.yml
- insert:
    - id: deepseek-visual
      name: deepseek-visual-plugin
      config:
        model: doubao-seed-2-0-mini-260428
        baseUrl: https://ark.cn-beijing.volces.com/api/v3
        apiKeyEnv: DOUBAO_API_KEY

工作原理¶

插件按原生协议实现，主要包含以下逻辑：

1. 拦截与判断：拦截含图片的消息，查询当前模型是否原生支持 image。
2. 分流处理：
   • 纯文本模型：调用视觉模型生成详细描述，再把图片块替换为描述文本。
   • 多模态模型：图片块原样进入模型请求，插件不介入。
3. 覆盖范围：替换发生在内容写入会话日志之前。插件覆盖 agent/pre-step（Web UI 粘贴/拖拽图片、客户端消息）与 tools/post-execute（read_image 等工具结果）。
4. 能力声明：插件包装 ctx.llm.resolveModelInfo / listModels，为所有 provider 声明 ['text','image']，使 Web 上传、selectModel 切换、read_image 等能力闸门放行。
5. 异常处理：单张图片解析失败只替换为占位文本，不会中断会话。原始图片仍保存在附件存储中。

使用示例¶

纯文本模型通过本插件“看懂”图片——多模态模型自动放行，纯文本模型触发翻译。

1. 视觉模型描述 UI：视觉模型把 Windows 开始菜单截图翻译成详细描述。
2. 纯文本模型回答：纯文本模型基于描述给出结构化回答。
3. 多类 UI 翻译：DSH 侧边栏与模型下拉菜单截图都能被准确描述。

注意事项¶

• 手动部署：需要手动部署文件到 $DSH_HOME/profiles/node_modules/deepseek-visual-plugin 并在 cordis.patch.yml 中添加配置（ID: deepseek-visual）。
• 热更新限制：修改插件源码后必须重启 dsh web：web 组合禁用了模块级 HMR，配置热更新不会重新加载已变更的插件模块。
• 凭证缺失行为：未配置任何 key 时插件仍会加载：含图片的消息会被占位文本替换并给出日志警告；纯文本对话不受影响。
• 自检脚本：verify.mjs 是本插件的功能自检脚本。运行 npm test（等价 node verify.mjs）可验证功能。

链接¶

• GitHub 仓库：https://github.com/zhangzhimou78-code/deepseek-visual-plugin
• 插件目录：https://www.skillhub.cn/plugins/zhangzhimou78-code/deepseek-visual-plugin