dsh-vision

Ein Tool, das Plugins für DeepSeek Harness (dsh) und Claude Code (MCP) visuelle Fähigkeiten verleiht: Lokale OCR (macOS / Windows) + Cloud-VLM (Multi-Anbieter) Bildverständnis.

Die Modell-API von DeepSeek unterstützt derzeit keine Bildeingabe, daher ist read_image nicht verfügbar. Dieses Plugin bietet zwei Tools, um diese Einschränkung zu umgehen:

Funktionen

• 🔒 Lokale OCR: macOS basiert auf Vision.framework, Windows auf der integrierten OCR-Engine; Bilder verlassen das Gerät nicht, Datenschutz und Sicherheit

• ☁️ Cloud-VLM: Standardmäßig 阿里云百炼 qwen3-vl-flash (schnell und günstig), OpenAI-kompatible Schnittstelle, beliebiger Anbieter austauschbar

• 🖼️ Automatische Komprimierung: Vor VLM-Aufrufen werden große Bilder mit sips auf 2048px / JPEG 85% komprimiert, spart Kosten und Datenvolumen

• 🔑 Flexible Key-Auswahl: Umgebungsvariable oder ~/.dsh/.credentials.yaml

• 🧪 Zero-Dependency-Unit-Tests: Kernlogik mit Node-eigenem node:test abgedeckt (13 Testfälle)

• 🌏 Multi-Anbieter-VLM: Integriert 百炼 / 硅基流动 / 智谱 / 火山方舟, OpenAI-kompatibel, beliebige weitere hinzufügbar

• 🔌 Zwei Formen: Sowohl dsh-Plugin als auch MCP-Server (direkt nutzbar mit MCP-Clients wie Claude Code)

• 🪟 Windows-Unterstützung: PowerShell-OCR-Backend (Windows.Media.Ocr) enthalten, VLM-Kanal plattformübergreifend

Installation

Methode A: Installation über npm (empfohlen)

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

Methode B: Aus dem Quellcode kopieren

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

Methode C: Vorkompilierte Binärdatei von GitHub Release herunterladen (ohne Kompilierung, empfohlen)

Wenn der Maintainer einen v*-Tag setzt, kompiliert GitHub Actions automatisch für beide macOS-Architekturen und hängt sie an das Release an:

1. Öffne die Releases-Seite dieses Repositorys und wähle die neueste Version

2. Lade je nach Mac-Architektur herunter:

   • Apple Silicon (M-Serie): vision-ocr-arm64

   • Intel Mac: vision-ocr-x86_64

3. Lege sie in das Plugin-Verzeichnis und füge Ausführungsrechte hinzu:

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-Binärdatei kompilieren (macOS benötigt 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

Plugin im Profile-Patch aktivieren

Bearbeite ~/.dsh/profiles/web/cordis.patch.yml (die Datei, die deinem Profil entspricht) und füge Folgendes hinzu:

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

VLM-API-Key konfigurieren (für describe_image erforderlich)

Wähle eine der folgenden Optionen:

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

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

Den Key erhältst du in der Konsole deines VLM-Anbieters (Standard: 阿里云百炼: bailian.console.aliyun.com).

dsh neu starten

Nach dem Neustart sind die Tools verfügbar. Hinweis: Es muss ein neuer Chat gestartet werden, die Tool-Liste wird beim Beginn der Sitzung injiziert.

Verwendung

Speichere das Bild im Chat auf der Festplatte und teile dem Agenten den Pfad mit:

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

Der Agent wählt automatisch das passende Tool (Text lesen per OCR, Bildinhalt per VLM). Wenn du einen bestimmten VLM-Anbieter festlegen möchtest, kannst du den Agenten den Parameter provider übergeben lassen (z. B. bailian / siliconflow / zhipu / volcengine).

Konfiguration

Überschreibe die Standardwerte über die config des Knotens dsh-vision in cordis.patch.yml.

Multi-Anbieter-VLM

Vier inländische Anbieter sind integriert; describe_image akzeptiert den Parameter provider zur Auswahl (leer lassen verwendet 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

Anbieter wechseln: defaultProvider ändern oder beim Aufruf den Parameter provider angeben; neuen Anbieter hinzufügen: beliebigen Schlüsselnamen unter providers ergänzen (jeder OpenAI-kompatible Endpunkt funktioniert).

Empfohlene Vision-Modelle (阿里云百炼)

Claude Code / MCP-Nutzung

Dieses Repository enthält einen MCP-Server ohne Abhängigkeiten (mcp/server.js), der es Claude Code (und jedem MCP-fähigen Client) ermöglicht, diese beiden Tools zu nutzen – selbst wenn dein Claude Code mit einem Modell ohne visuelle Unterstützung verbunden ist (z. B. DeepSeek).

Claude Code anbinden

# 全局接入（所有项目可用）
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" }
#     }
#   }
# }

Die Priorität beim Lesen des API-Keys für describe_image: Umgebungsvariable > ~/.dsh/.credentials.yaml. Bei Verwendung von .mcp.json kann er direkt in env konfiguriert werden.

Verifizierung

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

Der MCP-Server ist eine reine Node-Implementierung (stdio JSON-RPC), ohne Drittanbieter-Abhängigkeiten, Node >= 18 genügt.

Entwicklung

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

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

Plattformunterstützung

• macOS-OCR: Hängt von Vision.framework ab. Das Repository enthält keine Kompilierungsartefakte (siehe .gitignore):

  • Apple Silicon: npm run build:ocr selbst kompilieren oder vision-ocr-arm64 von GitHub Release herunterladen

  • Intel: npm run build:ocr selbst kompilieren oder vision-ocr-x86_64 vom Release herunterladen

  • Beim Setzen eines v*-Tags und Push zu GitHub kompiliert Actions automatisch für beide Architekturen und hängt sie an das Release an

• Windows-OCR: bin/vision-ocr.ps1 (integrierte OCR-Engine von Windows 10/11, chinesisches OCR-Sprachpaket erforderlich), das Plugin ocrBin darauf zeigen lassen:

  powershell -ExecutionPolicy Bypass -File bin/vision-ocr.ps1 <image> -Json

  Hinweis: Dieses Skript wurde auf macOS entwickelt und nicht unter Windows getestet; Issues/PRs sind willkommen.

• VLM-Kanal: Node >= 18 (integriertes fetch), auf allen Plattformen verfügbar.

Lizenz

MIT