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

# 全局接入（所有项目可用）
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 里直接配。

验证

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，不用手动存文件、不用给路径。

cd clipboard && bash install.sh   # 一键安装：LaunchAgent 自启 + 状态服务 + 前端提示

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

开发

# 运行单元测试
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 -ExecutionPolicy Bypass -File bin/vision-ocr.ps1 <image> -Json

  注：该脚本在 macOS 上开发，未在 Windows 实测，欢迎提交 issue/PR。

• VLM 通道：Node >= 18（内置 fetch），全平台可用。

许可证

MIT