dsh-vision

DeepSeek Harness(dsh) 플러그인 및 Claude Code(MCP)에 시각 기능을 제공하는 도구: 로컬 OCR(macOS / Windows) + 클라우드 VLM(다중 공급업체) 이미지 이해.

DeepSeek의 모델 API는 현재 이미지 입력을 지원하지 않으므로 read_image를 사용할 수 없습니다. 이 플러그인은 이 제한을 우회하는 두 가지 도구를 제공합니다:

특징

• 🔒 로컬 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 클라이언트에서 직접 사용)

• 🪟 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가 자동으로 두 가지 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 공급업체 콘솔에서 가져옵니다(기본값: 阿里云百炼: 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 호환 엔드포인트면 모두 가능).

권장 비전 모델(阿里云百炼)

Claude Code / MCP 사용

이 저장소에는 제로 의존성 MCP server(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" }
#     }
#   }
# }

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가 두 아키텍처에서 자동 컴파일하여 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