dsh-vision

Herramienta que aporta capacidades visuales al plugin DeepSeek Harness (dsh) y a Claude Code (MCP): OCR local (macOS / Windows) + VLM en la nube (multiproveedor) para comprensión de imágenes.

La API de modelos de DeepSeek no admite actualmente entrada de imágenes, por lo que read_image no está disponible. Este plugin proporciona dos herramientas para sortear esta limitación:

Características

• 🔒 OCR local: basado en Vision.framework en macOS y en el motor OCR integrado de Windows; la imagen no sale del equipo, privacidad garantizada

• ☁️ VLM en la nube: por defecto usa Alibaba Cloud Bailian qwen3-vl-flash (rápido y barato), interfaz compatible con OpenAI, se puede cambiar a cualquier proveedor

• 🖼️ Compresión automática: antes de llamar al VLM usa sips para reducir imágenes grandes a 2048px / JPEG 85%, ahorrando coste y tráfico

• 🔑 Obtención flexible de claves: variable de entorno o ~/.dsh/.credentials.yaml

• 🧪 Pruebas unitarias sin dependencias: la lógica central está cubierta con node:test integrado de Node (13 casos)

• 🌏 VLM multiproveedor: incluye Bailian / SiliconFlow / Zhipu / Volcano Ark; compatible con OpenAI, se puede añadir cualquier otro

• 🔌 Doble forma: es tanto un plugin de dsh como un servidor MCP (para clientes MCP como Claude Code)

• 🪟 Soporte Windows: incluye backend OCR en PowerShell (Windows.Media.Ocr); el canal VLM es multiplataforma

Instalación

Opción A: instalar desde npm (recomendado)

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

Opción B: copiar desde el código fuente

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

Opción C: descargar binario precompilado desde GitHub Release (sin compilar, recomendado)

Cuando el mantenedor crea un tag v*, GitHub Actions compila automáticamente en las dos arquitecturas de macOS y lo adjunta al Release:

1. Abre la página de Releases de este repositorio y selecciona la versión más reciente

2. Descarga según la arquitectura de tu Mac:

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

   • Intel Mac: vision-ocr-x86_64

3. Colócalo en el directorio de plugins y dale permiso de ejecución:

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

Compilar el binario OCR (macOS requiere 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

Activar el plugin en el patch del perfil

Edita ~/.dsh/profiles/web/cordis.patch.yml (el archivo correspondiente a tu perfil) y añade:

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

Configurar la clave API del VLM (necesaria para describe_image)

Elige una de las siguientes opciones:

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

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

La clave se obtiene de la consola de tu proveedor de VLM (por defecto Alibaba Cloud Bailian: bailian.console.aliyun.com).

Reiniciar dsh

Tras reiniciar, las herramientas estarán disponibles. Nota: es necesario abrir una conversación nueva, ya que la lista de herramientas se inyecta al inicio de la sesión.

Uso

En la conversación, guarda la imagen en el disco e indica la ruta al agente:

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

El agente elegirá automáticamente la herramienta adecuada (leer texto con OCR, ver la imagen con VLM). Para especificar un proveedor de VLM, puedes pedir al agente que pase el parámetro provider (por ejemplo, bailian / siliconflow / zhipu / volcengine).

Configuración

Los valores por defecto se sobrescriben mediante la sección config del nodo dsh-vision en cordis.patch.yml.

VLM multiproveedor

Incluye cuatro proveedores nacionales; describe_image acepta el parámetro provider para seleccionar (si se deja vacío, usa 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

Para cambiar de proveedor: modifica defaultProvider, o especifica el parámetro provider en la llamada; para añadir un proveedor nuevo: añade cualquier nombre de clave bajo providers (cualquier endpoint compatible con OpenAI sirve).

Modelos de visión recomendados (Alibaba Cloud Bailian)

Uso con Claude Code / MCP

Este repositorio incluye un servidor MCP sin dependencias (mcp/server.js) que permite usar estas dos herramientas desde Claude Code (y cualquier cliente compatible con MCP), incluso si tu Claude Code está conectado a un modelo sin soporte visual (como DeepSeek).

Conexión con 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" }
#     }
#   }
# }

La prioridad de lectura de la clave API de describe_image es: variable de entorno > ~/.dsh/.credentials.yaml. Al usar .mcp.json, se puede configurar directamente en env.

Verificación

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

El servidor MCP es una implementación pura en Node (JSON-RPC sobre stdio), sin dependencias de terceros; basta con Node >= 18.

Desarrollo

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

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

Soporte de plataformas

• OCR en macOS: depende de Vision.framework. El repositorio no incluye artefactos compilados (ver .gitignore):

  • Apple Silicon: compilar con npm run build:ocr, o descargar vision-ocr-arm64 desde GitHub Release

  • Intel: compilar con npm run build:ocr, o descargar vision-ocr-x86_64 desde Release

  • Al crear un tag v* y subirlo a GitHub, Actions compila automáticamente en ambas arquitecturas y lo adjunta al Release

• OCR en Windows: bin/vision-ocr.ps1 (motor OCR integrado de Windows 10/11, requiere instalar el paquete de idioma OCR chino); el ocrBin del plugin debe apuntar a él:

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

  Nota: este script se desarrolló en macOS y no se ha probado en Windows; se aceptan issues/PRs.

• Canal VLM: Node >= 18 (fetch integrado), disponible en todas las plataformas.

Licencia

MIT