图像理解 shaking/dsh-vision

dsh-vision

为 DeepSeek Harness（dsh）插件与 Claude Code（MCP）提供视觉能力的工具：本地 OCR（macOS / Windows）+ 云端 VLM（多供应商）图片理解。

DeepSeek 的模型 API 目前不支持图像输入，read_image 因此无法使用。本插件提供两个工具绕过这个限制：

| 工具 | 能力 | 成本 |
| read_image_text | 识别图片中的文字（macOS Vision / Windows 内置 OCR，免费离线，中英文） | 免费 |
| describe_image | 理解图片的画面内容（云端 VLM，多供应商，OpenAI 兼容端点） | 按量付费 |

特性

- 🔒 本地 OCR：macOS 基于 Vision.framework，Windows 基于内置 OCR 引擎，图片不出本机，隐私安全
- ☁️ 云端 VLM：默认阿里云百炼 qwen3-vl-flash（快且便宜），OpenAI 兼容接口，可换成任意提供商
- 🖼️ 自动压缩：VLM 调用前用 sips 把大图压到 2048px / JPEG 85%，省钱省流量
- 🔑 灵活取 Key：环境变量或 ~/.dsh/.credentials.yaml
- 🧪 零依赖单测：核心逻辑用 Node 内置 node:test 覆盖（13 用例）
- 🌏 多供应商 VLM：内置百炼 / 硅基流动 / 智谱 / 火山方舟，OpenAI 兼容可加任意家
- 🔌 双形态：既是 dsh 插件，也是 MCP server（Claude Code 等 MCP 客户端直接用）
- 📋 剪贴板贴图：复制图片即贴给 agent（macOS 监听 + 前端提示条 + 多图支持），无需手动存文件
- 🪟 Windows 支持：附 PowerShell OCR 后端（Windows.Media.Ocr），VLM 通道跨平台

安装

方式 A：从 npm 安装（推荐）

dsh plugin --profile web add @floatingsk/dsh-vision

方式 B：从源码拷贝

把本仓库拷贝到你的 dsh profile 插件目录
cp -R dsh-vision ~/.dsh/profiles/node_modules/dsh-vision

方式 C：从 GitHub Release 下载预编译二进制（免编译，推荐）

维护者在打 v tag 时，GitHub Actions 会自动在两种 macOS 架构上编译并附到 Release：

1. 打开本仓库的 Releases 页面，选择最新版本
2. 按你的 Mac 架构下载：
- Apple Silicon（M 系列）：vision-ocr-arm64
- Intel Mac：vision-ocr-x86_64
3. 放到插件目录并加执行权限：

cp vision-ocr-arm64 ~/.dsh/profiles/node_modules/dsh-vision/bin/vision-ocr
chmod +x ~/.dsh/profiles/node_modules/dsh-vision/bin/vision-ocr

编译 OCR 二进制（macOS 需要 Xcode Command Line Tools）

cd ~/.dsh/profiles/node_modules/dsh-vision
显式指定 clang 模块缓存目录（沙箱/受限环境下必需） swiftc -Xcc -fmodules-cache-path="$PWD/.cache" -O bin/vision-ocr.swift -o bin/vision-ocr

在 profile patch 中启用插件

编辑 ~/.dsh/profiles/web/cordis.patch.yml（你的 profile 对应文件），追加：

- insert:
- id: dsh-vision
name: 'dsh-vision'

配置 VLM API Key（describe_image 需要）

任选其一：

方式 A：环境变量
export DASHSCOPE_API_KEY=sk-xxx

方式 B：写入 dsh 凭据文件
echo 'DASHSCOPE_API_KEY: sk-xxx' >> ~/.dsh/.credentials.yaml

Key 从你的 VLM 提供商控制台获取（默认阿里云百炼：bailian.console.aliyun.com）。

重启 dsh

重启后工具即可用。注意：需要新开一个对话，工具列表在会话开始时注入。

使用

在对话中把图片保存到磁盘，告诉 agent 路径即可：

看下 /path/to/image.png 里有什么读取 /path/to/截图.png 中的文字

Agent 会自动选择合适的工具（读文字走 OCR，看画面走 VLM）。想指定 VLM 供应商时，可让 agent 传 provider 参数（如 bailian / siliconflow / zhipu / volcengine）。

配置

通过 cordis.patch.yml 中 dsh-vision 节点的 config 覆盖默认值。

多供应商 VLM

内置五家供应商（默认 DeepSeek 原生视觉，最便宜），describe_image 可传 provider 参数选择（留空用 defaultProvider）：

- insert:
- id: dsh-vision
name: 'dsh-vision'
config:
defaultProvider: 'deepseek' # 默认供应商 providers: deepseek: # DeepSeek 原生视觉（V4-Flash-Vision-Exp，约0.001元/张） baseUrl: 'https://api.deepseek.com' model: 'deepseek-v4-flash-vision-exp' apiKeyEnv: 'DEEPSEEK_API_KEY' bailian: # 阿里云百炼 baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1' model: 'qwen3-vl-flash' # 或 qwen3-vl-plus / qwen-vl-ocr apiKeyEnv: 'DASHSCOPE_API_KEY' siliconflow: # 硅基流动 baseUrl: 'https://api.siliconflow.cn/v1' model: 'Qwen/Qwen2.5-VL-7B-Instruct' apiKeyEnv: 'SILICONFLOW_API_KEY' zhipu: # 智谱 baseUrl: 'https://open.bigmodel.cn/api/paas/v4' model: 'glm-4v-flash' apiKeyEnv: 'ZHIPU_API_KEY' volcengine: # 火山方舟（豆包） baseUrl: 'https://ark.cn-beijing.volces.com/api/v3' model: 'doubao-seed-1.6-vision' apiKeyEnv: 'ARK_API_KEY' 自定义 OCR 二进制路径（默认插件 bin/vision-ocr） ocrBin: '' 上传前压缩最长边（像素） vlmMaxImageDim: 2048

更换供应商：修改 defaultProvider，或在调用时指定 provider 参数；添加新供应商：在 providers 下添加任意键名（任何 OpenAI 兼容端点均可）。

推荐的视觉模型（阿里云百炼）

| 模型 | 特点 |
| qwen3-vl-flash（默认） | 快、便宜，日常够用 |
| qwen3-vl-plus | 质量更高，稍慢稍贵 |
| qwen-vl-ocr | 纯文字识别专用，比本地 OCR 更强（需联网） |

Claude Code / MCP 使用

本仓库附带一个零依赖的 MCP server（mcp/server.js），让 Claude Code（以及任何支持 MCP 的客户端）也能用这两个工具——即使你的 Claude Code 接的是不支持视觉的模型（如 DeepSeek）。

接入 Claude Code sh 全局接入（所有项目可用） claude mcp add dsh-vision -- node /path/to/dsh-vision/mcp/server.js

或者只给当前项目（在项目根目录建 .mcp.json）： {
"mcpServers": {
"dsh-vision": {
"command": "node",
"args": ["/path/to/dsh-vision/mcp/server.js"],
"env": { "DASHSCOPE_API_KEY": "sk-xxx" }
}
}
}

describe_image 的 API Key 读取优先级：环境变量 > ~/.dsh/.credentials.yaml。用 .mcp.json 时可在 env 里直接配。

验证 sh claude mcp list # 应看到 dsh-vision claude mcp test dsh-vision # 或直接问 Claude：看下 /path/to/xxx.png 里是什么

MCP server 为纯 Node 实现（stdio JSON-RPC），无第三方依赖，Node >= 18 即可。

剪贴板贴图（copy-to-agent）

配套工具集（clipboard/）：复制图片 → 直接贴给 agent，不用手动存文件、不用给路径。
sh
cd clipboard && bash install.sh # 一键安装：LaunchAgent 自启 + 状态服务 + 前端提示

复制图片后，dsh web 右下角显示 [图片已就绪]，对 agent 说“看下我刚贴的图”即可。支持连续多张、Finder 多选。详见 clipboard/README.md。

开发 sh 运行单元测试
node --test test/

重新编译 OCR 二进制 swiftc -Xcc -fmodules-cache-path="$PWD/.cache" -O bin/vision-ocr.swift -o bin/vision-ocr

平台支持

| 能力 | macOS (Apple Silicon) | macOS (Intel) | Windows |
| 本地 OCR | ✅ 已编译 | ✅ 自编译或用 Release 二进制 | ✅ PowerShell 后端（Windows.Media.Ocr，未实测） |
| 云端 VLM | ✅ | ✅ | ✅（纯 Node） |

- macOS OCR：依赖 Vision.framework。仓库不含编译产物（见 .gitignore）：
- Apple Silicon：npm run build:ocr 自编译，或下载 GitHub Release 的 vision-ocr-arm64
- Intel：npm run build:ocr 自编译，或下载 Release 的 vision-ocr-x86_64
- 打 v tag 推 GitHub 时，Actions 自动在两种架构编译并附到 Release
- Windows OCR：bin/vision-ocr.ps1（Windows 10/11 内置 OCR 引擎，需装中文 OCR 语言包），插件 ocrBin 指向它即可： powershell powershell -ExecutionPolicy Bypass -File bin/vision-ocr.ps1 -Json

注：该脚本在 macOS 上开发，未在 Windows 实测，欢迎提交 issue/PR。
- VLM 通道：Node >= 18（内置 fetch），全平台可用。

许可证

MIT