deepseek-visual-plugin

DeepSeek Harness 视觉理解插件：把用户消息与工具结果中的图片翻译成文字描述，交给纯文本任务模型（如 DeepSeek）。多模态模型（原生支持 image 输入）自动放行，不经过翻译。

DeepSeek Harness 的插件是 Cordis 插件（TypeScript/ESM）。本插件按原生协议实现：拦截含图片的消息，自动判断当前模型是否原生支持 image：

• 纯文本模型：调用视觉模型生成详细描述，再把图片块替换为描述文本。
• 多模态模型：图片块原样进入模型请求，插件不介入。

替换发生在内容写入会话日志之前，模型请求与日志始终一致。

安装

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

Windows（PowerShell）

# 1. 部署插件代码（与已在运行的安装共享 $DSH_HOME/profiles/node_modules 解析回退）
$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 中加入（不存在则创建；该文件被每个 profile 加载并被 HMR 监听）：
# - insert:
#     - id: deepseek-visual
#       name: deepseek-visual-plugin
#       config:
#         model: <视觉模型名>
#         baseUrl: <OpenAI 兼容端点>
#         apiKeyEnv: <凭证引用名，如 DOUBAO_API_KEY>

Linux / macOS（Bash / Zsh）

# 1. 部署插件代码（与已在运行的安装共享 $DSH_HOME/profiles/node_modules 解析回退）
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 中加入（不存在则创建；该文件被每个 profile 加载并被 HMR 监听）：
# - insert:
#     - id: deepseek-visual
#       name: deepseek-visual-plugin
#       config:
#         model: <视觉模型名>
#         baseUrl: <OpenAI 兼容端点>
#         apiKeyEnv: <凭证引用名，如 DOUBAO_API_KEY>

正在运行的 dsh web 会通过 home 补丁热更新自动挂载；若未生效，重启 dsh web 即可。修改插件源码后必须重启 dsh web：web 组合禁用了模块级 HMR，配置热更新不会重新加载已变更的插件模块。修改后重新执行第 1 步复制即可生效。

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

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

配置

cordis.patch.yml 已用默认值挂载该行。可调参数：

字段	默认值	说明
model	qwen3.7-plus	视觉模型名（OpenAI 兼容端点上的模型 ID）
baseUrl	DashScope 兼容端点	留空时回退 QWEN_BASE_URL / DASHSCOPE_BASE_URL / OPENAI_BASE_URL
apiKey	空	API Key 的显式覆盖（可选，不推荐明文写进配置）
apiKeyEnv	空	凭证引用名（如 DOUBAO_API_KEY），通过 dsh 的 credentials 服务（~/.dsh/.credentials.yaml）解析
imagePrompt	内置中文提示词	图片描述提示词
timeoutMs	60000	单次视觉请求超时

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

在 profile 的 cordis.patch.yml 中按行 id 覆盖配置（必须重述全部键）。未配置任何 key 时插件仍会加载：含图片的消息会被占位文本替换（提示无法解析），并给出一次日志警告；纯文本对话不受影响。

效果示例

以下截图来自真实运行中的 DeepSeek Harness。纯文本模型通过本插件"看懂"图片——多模态模型自动放行，纯文本模型触发翻译。

1. 视觉模型把 Windows 开始菜单截图翻译成详细描述

2. 纯文本模型基于描述给出结构化回答

3. 多类 UI 截图都能稳定翻译

插件会自动识别当前模型是否原生支持 image：多模态模型直接放行，纯文本模型触发翻译。例如下面的 DSH 侧边栏与模型下拉菜单截图都能被准确描述：

行为说明

• 自动识别模型能力：插件查询当前模型是否原生支持 image。纯文本模型（如 DeepSeek chat-completions 适配器）触发翻译；多模态模型（如 GPT-4o、Claude、Qwen-VL 等原生支持 image 的模型）直接放行。
• 模型判断依据是「当前实际模型」，而非 agent 创建时的 seed 模型：agent.options 是 agent 创建时固定的初始模型，不随用户在 UI 切换模型而更新；真实请求的模型由 modelSelection 在 system-prompt/assemble 阶段快照到 assembly.variables.provider/model。插件监听该事件缓存每个 agent 的「当前实际模型」，agent/pre-step 与 tools/post-execute 据此判断，缓存缺失时才回退到 agent.options。
• 覆盖两处图片入口：agent/pre-step（Web UI 粘贴/拖拽图片、客户端消息）与 tools/post-execute（read_image 等工具结果）。
• 图片准入：插件包装 ctx.llm.resolveModelInfo / listModels，为所有 provider 声明 ['text','image']，使 Web 上传、selectModel 切换、read_image 等能力闸门放行；对于纯文本模型，图片随后在 agent/pre-step 被翻译成文字，实际请求不会携带图片块；对于多模态模型，图片块原样进入请求。卸载插件时声明自动恢复。
• 单张图片解析失败只替换为占位文本，不会中断会话。
• 原始图片仍保存在附件存储中；纯文本模型的会话历史中显示的是文字描述而非图片，多模态模型的会话历史中保留原始图片。
• DSH 的消息格式目前只有图片块（无视频块），视频抽帧逻辑未移植。
• verify.mjs 是本插件的功能自检（模拟 llm/attachments/credentials/fetch，不依赖真实 Harness）。先 npm install 安装 devDependencies，再运行 npm test（等价 node verify.mjs）确认。

开发与自检

npm install   # 安装 devDependencies（@deepseek-ai/schemastery），用于本地跑自检
npm test      # 等价于 node verify.mjs，运行功能自检

verify.mjs 模拟了 ctx.llm / ctx.attachments / ctx.credentials / fetch，在无需真实 Harness 的情况下驱动 apply()，验证：图片准入 patch、纯文本模型翻译、多模态模型放行、system-prompt/assemble 模型快照、无图快路径、失败占位、卸载恢复等。

卸载

Windows（PowerShell）

Remove-Item -Recurse -Force "$env:USERPROFILE\.dsh\profiles\node_modules\deepseek-visual-plugin"
# 并从 $DSH_HOME/cordis.patch.yml 中删除 deepseek-visual 行

Linux / macOS（Bash / Zsh）

rm -rf "$HOME/.dsh/profiles/node_modules/deepseek-visual-plugin"
# 并从 $DSH_HOME/cordis.patch.yml 中删除 deepseek-visual 行

若改用 bundle 方式安装过，另行 dsh plugin --profile <name> remove deepseek-visual-plugin。