dsh-vision —— DeepSeek Harness 外挂识图模型插件 为 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。 bash # 在 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 段： | 字段 | 默认值 | 说明 | |---|---|---| | apiBase | https://api.openai.com/v1 | 识图模型地址（按所选协议填到基础路径即可） | | apiKey | 空 | API 密钥（secret，不回显） | | model | gpt-4o-mini | 模型名称 | | protocol | auto | 协议：auto / openai-chat / openai-responses / anthropic / gemini / custom | | prompt | 见下 | 识图提示词（skill），可自定义 | | proxy | 空 | 可选 HTTP 代理，如 http://127.0.0.1:65532 | | timeoutMs | 60000 | 单次识图超时（毫秒） | | requestTemplate | 空 | 仅 custom：请求体 JSON 模板 | | responsePath | 空 | 仅 custom：响应文本取路径，如 choices.0.message.content | 默认识图提示词： > 你是一名专业的图像识别助手。请仔细观察用户提供的图片……（详细描述 + 逐字转录文字 + 截图场景重点描述） ## 使用 - 发送图片识图：打开一个会话后，点右下角鲸鱼按钮 → 面板点「📤 发送图片」选图。识别期间右上角显示「外挂模型正在识图当中」，完成后自动把识别文本发回当前会话。 - 模型自主识图：直接对模型说「看看我现在屏幕上的报错」，模型会调用 screenshot 截图、再调用 recognize_image 识图并继续。 ## API 协议自动适配 protocol 默认 auto，按 apiBase 自动识别；也可手动指定： | 协议 | 识别条件 / 用法 | 请求要点 | 响应取文本 | |---|---|---|---| | openai-chat | 默认；apiBase 填到 /v1 | POST /chat/completions，image_url 内嵌 data URL | choices[0].message.content | | openai-responses | apiBase 含 /responses | POST /responses，input_image | output[].content[].text | | anthropic | apiBase 含 anthropic | POST /v1/messages，x-api-key 头，source.base64 | content[].text | | gemini | apiBase 含 gemini/generativelanguage/googleapis | POST /models/{model}:generateContent，inline_data，x-goog-api-key 头 | candidates[0].content.parts[].text | | custom | 手动指定 | 按 requestTemplate 构造 | 按 responsePath 取路径 | ### custom 模板协议 custom 用于适配上述四种之外的长尾接口： - requestTemplate：请求体 JSON 模板。占位符必须裸写（不带引号），替换时会自动补上 JSON 引号。支持的占位符： - {{model}} → 模型名 - {{prompt}} → 识图提示词 - {{image}} → 图片纯 base64（不含 data: 前缀） - {{dataUrl}} → 完整 data:image/...;base64,... - {{mime}} → 图片 MIME 类型 示例（等价于 OpenAI Chat）： json {"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 非法。请保持裸写。 ## 故障排查 | 现象 | 处理 | |---|---| | 识图失败：HTTP 401/403 | apiKey 未填或填错，去面板重新保存密钥 | | 识图失败：HTTP 404 | apiBase 拼错或与协议不匹配；确认填到基础路径（如 OpenAI 填到 /v1，Anthropic 填 https://api.anthropic.com，Gemini 填到 /v1beta） | | 识图失败：结果为空 | 协议识别不对时手动指定 protocol；custom 协议检查 responsePath 是否正确 | | 外网直连不通 | 在 proxy 填 http://127.0.0.1:65532（或你自己的代理） | | 点「发送图片」没反应 | 确认已打开一个会话；确认右下角有鲸鱼按钮（client 插件已挂载） | | 模型不调用识图工具 | 确认 tool.js 已加进 preset 的 agent.cordis.yml，且该会话使用该 preset | | 截图失败 | Windows 下需 PowerShell 可用（System.Drawing）；macOS 用 screencapture；Linux 需 ImageMagick import |