# 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 安装（推荐）

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

### 方式 B：从源码拷贝

```sh
# 把本仓库拷贝到你的 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. 放到插件目录并加执行权限：

```sh
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）

```sh
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 对应文件），追加：

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

### 配置 VLM API Key（`describe_image` 需要）

任选其一：

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

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

Key 从你的 VLM 提供商控制台获取（默认阿里云百炼：[bailian.console.aliyun.com](https://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`）：

```yaml
- 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](./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 <image> -Json
  ```
  > 注：该脚本在 macOS 上开发，未在 Windows 实测，欢迎提交 issue/PR。
- **VLM 通道**：Node >= 18（内置 `fetch`），全平台可用。

## 许可证

[MIT](./LICENSE)