dsh-vision

Инструмент, предоставляющий возможности зрения для плагина DeepSeek Harness (dsh) и Claude Code (MCP): локальный OCR (macOS / Windows) + облачная VLM (мультивендорная) для изображений.

Модельный API DeepSeek в настоящее время не поддерживает ввод изображений, поэтому read_image недоступен. Этот плагин предоставляет два инструмента в обход этого ограничения:

Возможности

• 🔒 Локальный OCR: на macOS на базе Vision.framework, на Windows — встроенный движок OCR, изображения не покидают устройство, конфиденциальность гарантирована

• ☁️ Облачная VLM: по умолчанию Alibaba Cloud Bailian qwen3-vl-flash (быстро и дёшево), OpenAI-совместимый интерфейс, можно заменить на любого провайдера

• 🖼️ Автоматическое сжатие: перед вызовом VLM большие изображения сжимаются до 2048px / JPEG 85%, экономя трафик и деньги

• 🔑 Гибкое получение ключа: переменная окружения или ~/.dsh/.credentials

• 🧪 Тестирование без зависимостей: основная логика покрыта встроенным node:test (13 тестов)

• 🌏 Мультивендорная VLM: встроенная поддержка Bailian / SiliconFlow / Zhipu / Volcano Engine, можно добавить любого провайдера через OpenAI-совместимый API

• 🔌 Двойная форма: работает и как плагин dsh, и как MCP-сервер (например, для Claude Code и других MCP-клиентов)

• 🪟 Поддержка 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* 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 (соответствующий вашему профилю) и добавьте:

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

Настройка ключа API для VLM (describe_image)

Выберите один из вариантов:

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

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

Ключ можно получить в консоли вашего провайдера VLM (по умолчанию Alibaba Cloud Bailian: bailian.console.aliyun.com).

Перезапуск dsh

После перезапуска инструменты станут доступны. Обратите внимание: необходимо открыть новый диалог — список инструментов внедряется при старте сессии.

Использование

В диалоге сохраните изображение на диск и укажите агенту путь к нему:

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

Агент автоматически выберет подходящий инструмент (чтение текста — OCR, понимание содержимого — VLM). Чтобы указать конкретного провайдера VLM, передайте агенту параметр provider (например, bailian / siliconflow / zhipu / volcengine).

Конфигурация

Через узел dsh-vision в cordis.patch.yml можно переопределить значения по умолчанию в config.

Мультивендорная VLM

Встроенная поддержка четырёх отечественных провайдеров. Для 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-совместимая конечная точка).

Рекомендуемые модели VLM (Alibaba Cloud Bailian)

Использование с Claude Code / MCP

В репозитории прилагается MCP-сервер без внешних зависимостей (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" }
#     }
#   }
# }

Приоритет чтения ключа API для describe_image: переменная окружения > ~/.dsh/.credentials.yaml. При использовании .mcp.json ключ можно указать непосредственно в env.

Проверка

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

MCP-сервер реализован на чистом 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 для самостоятельной компиляции или скачайте vision-ocr-arm64 из GitHub Release

  • Intel: npm run build:ocr для самостоятельной компиляции или скачайте vision-ocr-x86_64 из Release

  • При создании тега v* и пуше в GitHub Actions автоматически компилирует бинарники для обеих архитектур и прикрепляет их к Release

• Windows OCR: bin/vision-ocr.ps1 (встроенный OCR-движок Windows 10/11, требуется языковой пакет для китайского), в плагине ocrBin укажите путь к нему:

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

  Примечание: скрипт разрабатывался на macOS и не тестировался на Windows; приветствуются issue/PR.

• Канал VLM: Node >= 18 (встроенный fetch), работает на всех платформах.

Лицензия

MIT