dsh-vision

一句话定位

dsh-vision 是 DeepSeek Harness 的外挂识图能力扩展插件。它把任意支持视觉的第三方模型接入 DSH，让原本不识图的模型能看懂图片与屏幕：用户可以在网页面板里点选图片自动识图，模型也可以自己截图后调用识图。

核心能力

• 网页右下角浮动鲸鱼按钮（可拖动），点击打开配置面板填写 API 地址、密钥、模型与提示词
• 在面板内点「📤 发送图片」选图，自动调第三方识图 API 并把识别文本作为消息发回当前会话
• 自动按 API 地址探测 OpenAI Chat / OpenAI Responses / Anthropic / Gemini 四种协议，另支持 custom 模板适配长尾接口
• 为 agent 注册 screenshot 与 recognize_image 两个工具，让模型能自主「截图 → 识图 → 等待结果」
• 提供「连接拉取」按钮，一键拉取目标 API 支持的模型列表（含协议）并回填到面板
• 通过 proxy 字段支持 HTTP/HTTPS 代理，避开外网直连限制

技术实现

• 语言: JavaScript (Node.js ESM + 浏览器原生 JS)
• 关键依赖: @deepseek-ai/schemastery（配置 schema）、node:http/node:https（外发 HTTP 请求）、node:child_process（截图）、@deepseek-ai/cordis（host 平面注入）
• 架构模式: 三平面注入——host 平面（lib/index.js，提供 settings namespace 与 ctx.vision 服务，挂载 HTTP 路由）、client 平面（lib/client.js，注入浏览器 UI）、agent 平面（lib/tool.js，挂载到 preset 提供工具）；通过 dsh.bundle.patch 自动接入 profile layer
• 入口文件: lib/index.js（host，export name='vision'）/ lib/client.js（client bundle，id='@linenxi-ctrl/dsh-vision'）/ lib/tool.js（agent，export name='vision-tool'）

适用场景

当你用的 DeepSeek 模型本身不识图（或想用更便宜的识图模型替代默认视觉模型）时，可以用它把 GPT-4o、Claude、Gemini 或自托管的 Qwen-VL 等任何支持视觉的 API 接进来。典型用途：让模型解读用户截图里的报错、自动识别网页内容、把图片里的代码或表格转录成文字，或用更便宜的识图模型降低主对话成本。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:linenxi-ctrl/dsh-vision

配置项

常见问题

Q: 需要准备什么才能用？

A: 需要一个支持图片输入的模型 API（OpenAI、Anthropic、Gemini 或自建兼容服务），在网页右下角鲸鱼按钮的面板里填入 API 地址、密钥和模型名即可。

Q: 一定要装 npm 包吗？能不能离线用？

A: 不必。仓库自带 install.bat / install.sh，安装脚本会自动从国内镜像下载免安装版 Node.js，免 pnpm 也能跑，适合内网或不想装 npm 工具链的环境。

Q: 装好了为什么模型还是不会自己识图？

A: 网页面板按钮（client）和识图服务（host）默认会一起挂载；如果想让模型自己截图识图，还需要在 agent preset 的 agent.cordis.yml 里追加 lib/tool.js 的挂载行，让 screenshot / recognize_image 进入该 preset 的工具清单。

Q: 面板里的「发送图片」和 DeepSeek 默认拖图行为冲突吗？

A: 不冲突。插件不拦截整页拖图，DeepSeek 原生的图片理解流程完全不受影响，只有面板里点「发送图片」才走外挂识图。

Q: 协议选 auto 还是手动指定好？

A: 默认 auto 会按 API 地址自动探测（识别 anthropic / gemini / /responses 路径）。复杂场景下可以点「连接拉取」让插件列出 API 支持的模型并自动选协议，省得手填。

Q: 怎么适配长尾接口？

A: 把协议切到 custom，在「自定义请求模板」里按 {{model}} / {{prompt}} / {{image}} / {{dataUrl}} / {{mime}} 占位符拼 JSON 模板，并在「响应文本路径」里用点号路径（如 choices.0.message.content）指到返回文本位置。注意占位符必须裸写不要加引号。

Q: 截图功能需要哪些系统组件？

A: Windows 需要 PowerShell（自带），macOS 自带 screencapture，Linux 需要安装 ImageMagick（提供 import 命令），否则 screenshot 工具会失败。

Q: 怎么完全卸载？

A: npm 安装的先跑 dsh plugin --profile web remove @linenxi-ctrl/dsh-vision，再跑仓库的 uninstall.mjs / uninstall.bat / uninstall.sh 一键清理客户端副本、agent preset 与 cordis.patch.yml 挂载。

上手难度

入门 — 装好插件后只需在网页右下角面板填三项（API 地址、密钥、模型），点「📤 发送图片」就能用；进阶玩法（custom 协议、代理、agent preset 工具挂载）属于可选优化。

已知问题与限制

• 图片大小上限 20MB（base64 解码后），超过会直接抛错（lib/index.js:28）
• custom 协议的鉴权默认走 Authorization: Bearer <apiKey>，需要特殊鉴权头（如 AWS Signature、自定义 HMAC）的接口需要自行改造 lib/index.js 的协议适配层
• 截图工具依赖外部 CLI：Linux 必须先装 ImageMagick，Windows 必须 PowerShell 可用（lib/tool.js:42-60）
• agent 工具（lib/tool.js）强依赖 host 平面的 ctx.vision 服务；若 host 插件未挂载就调工具，会抛「识图服务未安装」错误（lib/tool.js:96）
• recognize_image 单次超时 120 秒、screenshot 单次 30 秒，外挂 API 太慢时会先超时（lib/tool.js:92, 119）
• package.json 必须保存为 UTF-8 无 BOM，否则 Harness 启动会 JSON 解析失败（BUGFIX-NOTES.md:13-42）
• 客户端 bundle 的 __ModuleLoader__.load 注册 id 必须使用完整包名 @linenxi-ctrl/dsh-vision，否则加载会被 Harness 视为未注册（BUGFIX-NOTES.md:44-99）

为 DeepSeek Harness 增加「外挂识图模型」能力：让本来不具备视觉能力的模型，通过一个可自定义地址/密钥/提示词的外部视觉模型来「看懂」图片与屏幕。

功能

1. 网页配置按钮与面板：页面右下角出现一个DeepSeek 鲸鱼圆形按钮（可拖动），点击即可配置外挂识图模型的 API 地址、密钥、模型名、识图提示词（skill）、代理与超时。
2. 发送图片识图并自动回传：点鲸鱼按钮打开面板，点「📤 发送图片」选图，插件会先把它发给外挂识图模型，等识别完成后把识别文本自动作为消息发回当前会话（无需手动复制粘贴），DeepSeek 基于识别文本作答。
3. 模型自己截图 + 识图：插件为 agent 注入 screenshot（截屏）与 recognize_image（识图）两个工具，并注入提示词，模型可自行「截图 → 识图 → 等待结果」。
4. 自动适配识图 API 协议：内置 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Google Gemini 四种协议，并按 apiBase 自动探测；另有 custom 模板协议适配任意长尾接口。

文件结构

dsh-vision/
├── install.bat        # Windows 一键安装（双击）
├── install.sh         # macOS/Linux 一键安装
├── install.mjs        # 安装脚本本体（npm 场景只做 agent 工具平面；目录场景全自动）
├── bootstrap-node.ps1 # Windows 引导脚本：未装 Node.js 时从国内镜像自动下载免安装版
├── package.json       # 包定义（dsh.bundle + dsh.client 声明；tool 为独立子路径）
├── cordis.patch.yml   # 插件挂载声明（dsh.bundle.patch 自动应用到 profile layer）
├── lib/
│   ├── index.js       # host 平面插件：识图服务 + 协议适配 + settings 配置 + HTTP 路由
│   ├── tool.js        # agent 工具插件：recognize_image / screenshot + 提示词注入
│   └── client.js      # 客户端插件：鲸鱼按钮 / 配置面板 / 发送图片识图 / 自动回传
└── README.md

工作原理

[用户点鲸鱼按钮选图]                [模型调用工具]
      │                               │
      ▼                               ▼
  client 转 base64 发送          screenshot 工具截屏
      │                               │
      ▼                               ▼
  POST /api/vision/recognize    recognize_image 工具
      │                               │
      ▼                               ▼
  host 插件 ctx.vision 服务 ──► 协议自动适配后调用外挂识图 API
      │                               │
      ▼                               ▼
  识别文本 → 自动注入当前会话    识别文本返回给模型

识图请求在 host（Node）侧发起，因此不受浏览器 CORS 限制；图片请求走同源 /api/vision/recognize，同样无 CORS 问题。

安装

两种方式任选：npm 安装（标准，推荐）或手动 / 离线（下载 zip，无需 pnpm）。

方式一：npm 安装（推荐）

需要系统已装 Node.js 18+ 与 pnpm。

# 在 DSH 的 web profile 安装本插件（DSH 自动把 cordis.patch.yml 加入 profile layer）
dsh plugin --profile web add @linenxi-ctrl/dsh-vision

# （可选）配置 agent 工具平面：让模型能自己截图 + 识图
node ~/.dsh/profiles/web/node_modules/@linenxi-ctrl/dsh-vision/install.mjs

安装后无需手动改任何配置文件：package.json 的 dsh.bundle.patch 声明会被 DSH 自动 reconcile 进 profile 的 dsh.profile.bundles，cordis.patch.yml 即成为该 profile 的一个 bundle layer。

方式二：手动 / 离线（无需 pnpm，小白友好）

从 Releases 下载 zip 解压：

1. Windows 双击 install.bat，macOS/Linux 运行 bash install.sh——无需预装 Node.js：脚本检测不到时会自动从国内镜像（npmmirror / 华为云 / 腾讯云）下载免安装版（无需管理员权限）；
2. 脚本会自动：复制英文副本、复制进每个 profile 的 node_modules、在 cordis.patch.yml 加 vision 行、创建 agent preset vision（复制随附 standard 并加入识图工具）并设为默认；
3. 重启 DSH（关闭后重新 dsh web）。

实测要点（DSH 0.1.0-rc.6）：host + client 插件（cordis.patch.yml）的 name 必须用「包名」，插件须在 profile 的 node_modules 下；agent 工具插件（preset）的 name 支持绝对路径（自动转 file://）；agent preset 不能叫 standard（会被随附 standard 遮蔽）。

更新与卸载

更新：先卸载旧版，再安装新版即可（cordis.patch.yml 与 preset 会自动重建）。

一键卸载：

• Windows：双击 uninstall.bat
• macOS/Linux：运行 bash uninstall.sh
• 任意平台：node uninstall.mjs

卸载脚本会自动：删除英文副本与 profile node_modules 里的插件、从 cordis.patch.yml 移除 vision 挂载行、删除 agent preset「vision」、恢复 settings.yaml 的默认 preset。

npm 方式安装的插件，请先用 dsh plugin --profile web remove @linenxi-ctrl/dsh-vision 卸载 npm 包，再跑上面的卸载脚本清理 preset 与设置。

配置

点页面右下角鲸鱼按钮，或直接编辑 $DSH_HOME/settings.yaml 中的 vision 段：

默认识图提示词：

你是一名专业的图像识别助手。请仔细观察用户提供的图片……（详细描述 + 逐字转录文字 + 截图场景重点描述）

使用

• 发送图片识图：打开一个会话后，点右下角鲸鱼按钮 → 面板点「📤 发送图片」选图。识别期间右上角显示「外挂模型正在识图当中」，完成后自动把识别文本发回当前会话。
• 模型自主识图：直接对模型说「看看我现在屏幕上的报错」，模型会调用 screenshot 截图、再调用 recognize_image 识图并继续。

API 协议自动适配

protocol 默认 auto，按 apiBase 自动识别；也可手动指定：

custom 模板协议

custom 用于适配上述四种之外的长尾接口：

• requestTemplate：请求体 JSON 模板。占位符必须裸写（不带引号），替换时会自动补上 JSON 引号。支持的占位符：

  • {{model}} → 模型名
  • {{prompt}} → 识图提示词
  • {{image}} → 图片纯 base64（不含 data: 前缀）
  • {{dataUrl}} → 完整 data:image/...;base64,...
  • {{mime}} → 图片 MIME 类型

  示例（等价于 OpenAI Chat）：

  {"model":{{model}},"messages":[{"role":"user","content":[{"type":"text","text":{{prompt}}},{"type":"image_url","image_url":{"url":{{dataUrl}}}}]}]}
  

• responsePath：从响应 JSON 取文本的点号路径（数字为数组下标），如 choices.0.message.content、data.text、result.0.content。

• 鉴权默认走 Authorization: Bearer <apiKey>（apiKey 为空则不携带）；需要特殊鉴权头的接口暂不支持，可提 issue 扩展。

提示：占位符若误加了引号（写成 "{{image}}"），替换后会得到 ""base64"" 导致 JSON 非法。请保持裸写。

故障排查