dsh-vision

DeepSeek Harness（dsh）プラグインと Claude Code（MCP）に視覚能力を提供するツール：ローカルOCR（macOS / Windows）+ クラウドVLM（マルチベンダー）画像理解。

DeepSeek のモデル API は現在画像入力をサポートしておらず、read_image は使用できません。本プラグインはこの制限を回避する2つのツールを提供します：

特徴

• 🔒 ローカル OCR：macOS は Vision.framework、Windows は内蔵 OCR エンジンに基づき、画像は端末から出ず、プライバシー安全

• ☁️ クラウド VLM：デフォルトは Alibaba Cloud Bailian qwen3-vl-flash（高速・低コスト）、OpenAI 互換インターフェース、任意のプロバイダーに変更可能

• 🖼️ 自動圧縮：VLM 呼び出し前に sips で大きな画像を 2048px / JPEG 85% に圧縮、コストと通信量を節約

• 🔑 柔軟な Key 取得：環境変数または ~/.dsh/.credentials.yaml

• 🧪 ゼロ依存単体テスト：コアロジックを Node 内蔵 node:test でカバー（13 テストケース）

• 🌏 マルチベンダー VLM：Bailian / SiliconFlow / Zhipu / Volcano Engine を内蔵、OpenAI 互換なら任意のベンダーを追加可能

• 🔌 デュアルフォーム：dsh プラグインとしても、MCP server としても動作（Claude Code などの MCP クライアントで直接使用可能）

• 🪟 Windows サポート：PowerShell OCR バックエンド（Windows.Media.Ocr）付属、VLM チャネルはクロスプラットフォーム

Related MCP server: DeepSeek Vision Bridge

インストール

方法 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* タグを打つと、GitHub Actions が自動的に2種類の 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 プロバイダーのコンソールから取得します（デフォルトは Alibaba Cloud Bailian：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

国内4社のプロバイダーを内蔵しており、describe_image に provider パラメータを渡して選択できます（空欄の場合は defaultProvider を使用）：

- insert:
    - id: dsh-vision
      name: 'dsh-vision'
      config:
        defaultProvider: 'bailian'          # 默认供应商
        providers:
          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 互換エンドポイントなら何でも可）。

推奨ビジョンモデル（Alibaba Cloud Bailian）

Claude Code / MCP での使用

本リポジトリにはゼロ依存の MCP server（mcp/server.js）が付属しており、Claude Code（および MCP をサポートする任意のクライアント）でもこの2つのツールを使用できます——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 で動作。

開発

# 运行单元测试
node --test test/

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

プラットフォームサポート

• 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* タグを打って GitHub にプッシュすると、Actions が自動的に2つのアーキテクチャでコンパイルし 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