dsh-vision-plugin

为 DeepSeek Harness 添加图片理解能力的插件，让纯文本模型（如 DeepSeek）也能理解图片——完全免费，依赖 OpenRouter 的免费视觉模型。

免费：使用 OpenRouter 的 :free 多模态模型，零 API 成本
依赖 OpenRouter：只需一个 OpenRouter API Key

当前功能

describe_image 工具：读取磁盘上的图片文件，调用 OpenRouter 视觉模型返回文字描述
自动图片处理：粘贴/上传的图片会原样显示在聊天界面；如果当前模型不支持图片，llm/stream 钩子会在发送前自动调用 OpenRouter 视觉模型把图片转成文字描述交给当前模型（描述不进会话、不显示）；如果当前模型支持图片，则原样发送

flowchart TD
    A[用户粘贴/上传图片] --> B[图片原样显示在聊天界面<br/>会话保留 image 块]
    B --> C{llm/stream 钩子<br/>当前模型支持图片}
    C -->|是| D[图片原样发送给模型]
    C -->|否| E[调用 OpenRouter 免费视觉模型<br/>生成文字描述]
    E --> F[描述注入 LLM 请求<br/>不进会话、不显示]
    D --> G[主模型基于描述回答]
    F --> G

安装方式

方式一：--patch（从插件目录运行）

cd dsh-vision-plugin
npm install
dsh web --patch ./cordis.yml

注意：cordis.yml 里的插件路径是绝对路径（指向本机），clone 后需要改成你自己的路径。

方式二：安装为 bundle（推荐）

dsh plugin --profile web add https://github.com/Agents365-ai/dsh-vision-plugin
dsh web

安装后无需 --patch，直接 dsh web 即可使用。

注意：若安装时报 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED，说明拉到了旧版本（带 prepare 构建脚本）。更新到最新版本即可，新版已移除该脚本。

卸载

dsh plugin --profile web remove dsh-vision-plugin

（方式一 --patch 安装的无需卸载，去掉 --patch ./cordis.yml 启动参数即可。）

可选：同时删除 $DSH_HOME/settings.yaml 中的 deepseek-vision provider 配置（卸载后为死配置，留着也无害）。

配置 OpenRouter

启动前设置 API Key（只从环境变量读取，未设置时插件会直接报错提示你配置）：

export OPENROUTER_API_KEY=your_openrouter_api_key

让 DeepSeek 允许粘贴图片

Harness 特征：粘贴图片后无法发送、提示"当前模型不支持图片"，是 Harness 在 API 代理层（dsh-host-apiproxy 的 prompt 处理）做的准入检查——它发生在 agent loop 之前，auto-vision 插件根本来不及运行。检查依据是 resolveModelInfo 返回的 inputModalities，与模型实际能力无关，只取决于配置里声明的 input。

注意：官方 deepseek provider 是纯文本的，不要给它声明图片输入（modelOverrides）——那会掩盖模型真实能力，正常行为就是拒绝图片。图片理解必须通过下面的自定义 provider。

deepseek-vision provider（自动配置）

插件首次启动时会自动在 $DSH_HOME/settings.yaml 写入默认的 deepseek-vision provider（指向 OpenRouter），无需手动配置。你可以随时修改或删除它：

llm-pi-ai:
  providers:
    deepseek-vision:
      apiKeyEnv: OPENROUTER_API_KEY
      api: openai-completions
      baseURL: https://openrouter.ai/api/v1
      reasoning: high
      models:
        - id: deepseek/deepseek-v4-pro
          input: [text, image]
          reasoningEfforts:
            off:
            high: high
            max: max
        - id: deepseek/deepseek-v4-flash
          input: [text, image]
          reasoningEfforts:
            off:
            high: high
            max: max

然后在 Web UI 的模型选择器里选择这个 Provider 下的 DeepSeek 模型。

auto-vision 插件已内置上面两个别名模型 id 作为默认强制转换列表（DEFAULT_FORCE_MODELS），不需要再设置环境变量。

只有当你另外创建了其他"声明支持图片、实际纯文本"的别名时，才需要追加：

export AUTO_VISION_FORCE_MODELS=provider/other-alias-model

（环境变量中的模型会与内置默认列表合并使用。）

已知限制

图片会话切换模型：会话里已有图片时，切换到不支持图片的模型（如官方 deepseek）会被 Harness 拒绝（model-unavailable）。这是 Harness 的安全特性，不是 bug。需要切换时请开新会话。
图片 + 工具同消息：当前 prompt 含图片时工具会被剥掉（避免弱模型反射性搜索文件），所以"看图 + 同时用工具"需要分两步：先问图片，再让模型用工具。
视觉模型质量：免费视觉模型偶尔返回安全判定（如 User Safety: safe）或过短描述，插件会自动换下一个模型重试。