zcma11 / dsh-vision-plugin

dsh-vision-plugin

English documentation: README.en.md

DeepSeek Harness 插件：在聊天输入框上传/粘贴图片，发送时用视觉模型（百炼 DashScope）或 Windows 离线 OCR 转述图片内容，并把描述注入消息：

【解析了提供图片，图片内容是<描述>】
<你的原文>

安装

npx @deepseek-ai/dsh plugin --profile web add dsh-vision-plugin

或从 GitHub 直接安装：

npx @deepseek-ai/dsh plugin --profile web add github:<你的用户名>/dsh-vision-plugin

pnpm 9 注意：若 add 报 ERR_PNPM_ADDING_TO_ROOT（workspace root 检查），在命令末尾追加 --workspace-root：

npx @deepseek-ai/dsh plugin --profile web add dsh-vision-plugin --workspace-root

git 源插件需要 pnpm 允许构建脚本（prepare），按 pnpm 打印的提示把包名加入 $DSH_HOME/profiles/web/pnpm-workspace.yaml 的 allowBuilds 后重试。

教程

① 上传 / 粘贴图片

1. 点输入框工具行的 🖼️（视觉转述）或 📝（纯 OCR）选一张图片； 或直接 Ctrl+V 粘贴（QQ 截图、系统截图都行，BMP 自动转 PNG）。
2. 图片出现在输入框上方的预览条——缩略图 + 文件名 + 视觉/OCR 徽标 + 红色 × 删除按钮。 也可以点 🗑️ N 一键清空本会话所有待发图片。
3. 在输入框输入文字（可选），然后回车发送。

② 发送时如何转述

上传方式	转述方式
📝 OCR 按钮	仅 Windows 内置 OCR（离线、不调模型）
🖼️ 按钮 / Ctrl+V 粘贴	仅视觉模型（需先选择模型 + 配置 API Key）

• 转述成功 → 消息正常发送，主模型收到的内容以 【解析了提供图片，图片内容是<描述>】 开头，后接你的原文；预览条随后自动清除。
• 转述失败 → 消息不会发给主模型，顶部弹出红色 toast，准确区分 「视觉模型调用失败」还是「OCR 识别失败」；预览与图片数据保留，可直接重发。
• 转述进行中 → 预览条顶部显示「⏳ 正在解析图片…」，此期间的新发送会被拦截（防止重复/插队）。

③ 设置视觉转述模型

打开 设置 → 通用 → 视觉转述模型，从下拉框选择支持图片输入的模型（如 dashscope/qwen3.6-plus）。

• 必须选择：未选择时，🖼️/粘贴 的视觉转述会报「请先在设置中选择视觉转述模型」。
• OCR 模式不依赖模型，无需设置。

前置要求

• 视觉转述：~/.dsh/.credentials.yaml 中配置 DASHSCOPE_API_KEY（阿里云百炼），并在设置中选择支持图片输入的模型（如 qwen3.6-plus）。
• 纯 OCR：Windows 10+（Windows.Media.Ocr），无需任何配置。
• 平台：Windows（OCR 依赖 PowerShell 5.1 + Windows.Media；视觉转述路径亦在 Windows 上验证）。

结构

dsh-vision-plugin/
├── package.json          # dsh.bundle.patch + dsh.client 声明
├── cordis.patch.yml      # 插件行声明（dsh plugin add 后自动加入 profile bundles）
├── lib/
│   ├── index.js          # Host 半部：内存图片存储、vision/OCR 子进程、pre-step 转述注入
│   └── client.js         # Client 半部：上传/粘贴、预览条、toast、loading、设置项
├── docs/                 # 教程示意图（SVG，GitHub 原生渲染）
└── README.md

关键设计

• 图片只存内存（base64），不写工作区、不落盘；子进程间经 stdin 传输（环境变量上限 ~32KB 放不下几 MB 图片）。
• 视觉调用：Node 子进程用内置 fetch 直连 DashScope OpenAI 兼容端点，图片以 data:image/png;base64,… 放入请求体。
• OCR 调用：PowerShell 子进程，脚本经 -EncodedCommand（UTF-16LE base64）内联，结果以 OCR_B64:（UTF-8 base64）行输出，绕开 PowerShell 5.1 的代码页问题。
• 模式严格路由：OCR 按钮 → 仅 OCR；视觉按钮/粘贴 → 仅视觉模型；不做自动降级，失败原因准确区分。
• 转述期间置 busy：显示「⏳ 正在解析图片…」，并拦截此间的新发送（防插队）。

开发

• 依赖宿主服务：connection（client↔host RPC）、subprocess、credentials、llm、slots、timer（均来自 dsh-base / dsh-web-app 默认 bundle）。
• 本地调试：可直接改 lib/*.js 后重新 dsh plugin --profile web add .（相对路径会被锚定到当前目录）。