ysr666/dsh-vision-router

dsh‑vision‑router – DeepSeek Harness의 "눈"

무엇인가요

• DeepSeek Harness (DSH) 플러그인으로, 텍스트 전용 에이전트가 이미지를 손실 없이 시각적으로 인식할 수 있게 합니다. 이미지를 단순한 텍스트 설명으로 변환하는 대신, 이 플러그인은 원본 이미지를 비전 모델(또는 무료 비전 백엔드 체인)로 라우팅하고, LLM이 일반 도구처럼 호출할 수 있는 구조화된 결과를 반환합니다.

왜 중요한가요

• 기존 DSH 비전 플러그인의 대부분은 이미지에 대한 손실 있는 설명만 제공합니다. dsh‑vision‑router는 비전 측에서 원본 픽셀을 유지하므로, LLM은 후속 질문, 자르기, 비교, OCR 등을 동일한 이미지에서 수행할 수 있습니다.
• 출시 직후 무료로, Python 의존 없이 작동합니다. Node ≥ 22에서 sharp, potrace, tesseract, 시스템 Chrome을 사용해 모든 작업이 수행됩니다.

주요 기능

기능	제공되는 기능
단일 명령어 설치	npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router (또는 dshpm을 통해) 자동으로 DSH에 필요한 구성 행과 액세스 래퍼를 패치합니다.
무료 익명 폴백	API 키가 필요 없는 OVHcloud 비전 엔드포인트 (IP당 약 2회/분). Zhipu, DashScope, Intern AI 등 무료 제공자들을 추가해 더 높은 제한을 사용할 수 있습니다.
Python 없음	이미지 처리(축소, 그라운딩, 자르기, 픽셀 차이, 팔레트, OCR, SVG 추적, 컷아웃, HTML 스크린샷)는 모두 네이티브 Node 라이브러리와 Chrome으로 수행됩니다.
다단계 이미지 워크플로우	이미지 처리가 일반 도구 호출처럼 작동합니다: vision_ground → vision_crop → vision_describe → vision_pixel_diff … 에이전트는 작업이 완료될 때까지 반복할 수 있습니다.
콘텐츠 해시 기반 캐시	비전 결과는 캐시되며, 후속 텍스트 타ーン에서는 비전 모델을 다시 호출하지 않고 저장된 설명을 재사용합니다.
안정된 도구 스키마	플러그인 시작 시 11개의 비전 도구가 등록되며(또는 progressiveTools:true로 지연 로드 가능). vision_describe, vision_ground, vision_crop, vision_pixel_diff, vision_ocr, vision_trace 등이 포함됩니다.
자동 프로바이더 폴백	프로바이더가 402/429/5xx 오류를 반환하면 체인은 조용히 다음 프로바이더로 전환하고, 최종적으로 익명 OVH 엔드포인트로 폴백합니다.
투명한 UI	업로드된 이미지는 채팅 UI에 그대로 표시됩니다. 비전 도구로의 라우팅은 모델 호출 내부에서만 발생하므로 대화 로그는 깨끗한 상태를 유지합니다.

작동 방식 (고수준)

1. 사용자가 이미지를 업로드하거나 붙여넣기하고, "+ Auto Vision"이 표시된 모델 그룹을 사용하는 경우.
2. DSH는 이미지 타ーン을 감지하고 요청을 재작성하여 비전 모델을 먼저 호출하고, 일반 텍스트 응답 대신 JSON 페이로드(또는 주석이 있는 PNG)를 반환합니다.
3. LLM(DeepSeek)은 도구 결과를 수신하고, 추가 비전 도구 호출, 결과 캐시, 또는 대화 계속 여부를 결정합니다.
4. 비전 체인이 성공하면 최종 응답이 사용자에게 전송됩니다. 모든 프로바이더가 실패하면 도움이 되는 오류 메시지가 표시됩니다.

설치 및 빠른 시작

# 단일 라인 (권장)
npx @deepseek-ai/dsh plugin --profile web add dsh-vision-router

# 로컬 deepseek‑harness 체크아웃을 실행 중인 경우
cd deepseek-harness
pnpm dsh plugin --profile web add dsh-vision-router

1. 플러그인 번들을 감지할 수 있도록 DSH Web을 다시 로드하거나 재시작합니다.
2. 채팅 컴포저에서 모델 선택기를 열고, 이제 "+ Auto Vision" 항목이 있는 모델 그룹(예: opencode-go + Auto Vision)을 선택합니다.
3. 이미지를 붙여넣거나 업로드합니다. 내장된 OVH 폴백은 이미 설정되어 있으므로 API 키가 필요하지 않습니다.
4. 에이전트의 프롬프트에서 다음 중 하나의 비전 도구를 사용합니다. 예:

   vision_ground image="screenshot.png" target="send button"
   vision_crop   image="screenshot.png" region="1067,841,1108,881"
   vision_describe image="crop.png" question="What does this button say?" json=true
   

무료 비전 백엔드 (플러그인 설정의 httpProviders 또는 ~/.dsh/.credentials.yaml에서 추가 가능):

• OVHcloud 익명 엔드포인트 (IP당 약 2회/분) – 기본 폴백.
• OVHcloud 키 기반 엔드포인트 (프로젝트당 400회/분) – 더 높은 제한.
• Zhipu bigmodel.cn (무제한 토큰, 중국 직접 접속).
• DashScope, Intern AI, Groq, Google AI Studio, NVIDIA NIM, OpenCode Zen, OpenRouter – 각각 고유한 무료 제한 있음 (README 표 참조).

일반적인 워크플로우

• UI 검증 – vision_html_screenshot → vision_pixel_diff로 재구성된 UI가 참조 이미지와 일치하는지 확인.
• 폼 자동화 – vision_ground로 버튼 위치 확인, vision_crop으로 확대, vision_ocr로 레이블 읽기, 이후 에이전트를 통해 클릭 전송.
• 문서 추출 – vision_long_screenshot_ocr로 긴 스크린샷을 분할하고 각 청크에 OCR을 실행한 후 Markdown 출력을 연결.

설정 요약

• progressiveTools: false (기본값) – 11개 도구가 즉시 사용 가능.
• cordis.patch.yml에서 progressiveTools: true로 설정하면 시작 시 vision_activate만 노출하고 필요 시 나머지 도구를 지연 로드.
• 비전 프로바이더 행은 비워둘 수 있습니다. OVH 익명 체인은 항상 최종 폴백입니다.
• 캐시된 결과는 첨부 파일 콘텐츠 해시로 저장되어 타ーン 간 "이미지 기억"이 가능합니다.

문제 해결

• 빈 설정 페이지 – v1.4.4에서 수정됨. 해당 버전을 사용 중인지 확인하세요.
• 모델 그룹 선택 – 반드시 "+ Auto Vision" 항목을 선택해야 합니다. 그렇지 않으면 플러그인이 작동하기 전에 DSH가 이미지를 거부합니다.
• 레트 제한 오류 – 키 기반 OVH 엔드포인트 또는 다른 무료 프로바이더를 체인에 추가하세요.

---

결론: dsh‑vision‑router는 DeepSeek Harness에서 이미지 업로드를 피크셀 정확성을 유지하면서도 1차 도구 호출로 전환합니다. 무료 익명 비전 폴백을 제공하며, 시작에는 단일 npm 명령어만 필요합니다. 이는 단순한 데모나 커리레이티드 목록이 아니라, 진정한 프로덕션 대응 AI 도구 플러그인입니다.