DeepSeek Harness: 플러그인 아키텍처 기반의 오픈소스 AI 에이전트 하네스 및 데스크톱 앱

DeepSeek AI가 공개한 오픈소스 에이전트 하네스 'DeepSeek Harness(dsh)'. macOS와 Windows 데스크톱 앱을 지원하며, 'Everything is a plugin' 구조로 로컬 LLM 연동, 웹 검색, 코드 자동 수정을 손쉽게 확장할 수 있습니다.

tau · 2026년 10월 5일

#DeepSeek #DeepSeekHarness #dsh #AIAgent #AgentHarness #DevTools #OpenSource

DeepSeek Harness: 플러그인 아키텍처 기반의 오픈소스 AI 에이전트 하네스 및 데스크톱 앱

DeepSeek AI가 모듈형 플러그인 아키텍처를 기반으로 설계된 오픈소스 AI 에이전트 하네스 프레임워크인 'DeepSeek Harness(dsh)'를 공식 공개했습니다. MIT 라이선스로 배포되는 이 도구는 핵심 엔진의 경량성을 유지하면서 모든 세부 기능을 플러그인 형태로 조립할 수 있도록 설계되었으며, macOS 및 Windows 전용 독립 데스크톱 패키지와 함께 웹 브라우저 기반 Web UI 구동 환경을 동시에 지원합니다.

DeepSeek Harness(dsh)의 데스크톱 애플리케이션 및 웹 UI 작업 화면과 플러그인 아키텍처 구성도

이미지 출처: @Yacamochi_db / X

최근 LLM 기반 코딩 에이전트와 자율형 작업 환경이 급격히 확산되는 가운데, 기존 에이전트 런타임은 복잡한 커맨드라인 환경 설정이나 경직된 모노리스 구조로 인해 로컬 모델 연결이나 도구 확장에 상당한 진입 장벽이 존재했습니다. DeepSeek Harness는 직관적인 그래픽 인터페이스(GUI)에서 플러그인을 설치하는 것만으로 웹 검색, 작업 워크스페이스 연동, 코드 변경점 검토 등 다양한 에이전트 워크플로우를 구성할 수 있도록 진입 장벽을 낮춘 것이 특징입니다.

'모든 것이 플러그인(Everything is a Plugin)': Cordis 기반 모듈형 에이전트 구조

DeepSeek Harness(dsh)의 핵심 설계 사상은 '모든 것이 플러그인(Everything is a plugin)'이라는 아키텍처 철학입니다. 이 시스템은 시공간적 합성 가능성을 다룬 프로그래밍 패러다임 연구에 기반한 Cordis 프레임워크를 기반 엔진으로 채택했습니다.

에이전트가 수행하는 대부분의 핵심 작업 단위가 독립적인 플러그인으로 추상화되어 있어 사용자는 필요한 기능만 선택적으로 활성화할 수 있습니다.

  • 모듈형 확장 구조: 핵심 코어는 가볍게 유지되며 모델 어댑터, 웹 검색 도구, 파일 처리기 등이 개별 플러그인 패키지로 분리되어 있어 손쉬운 유지보수와 확장을 지원합니다.
  • 워크스페이스 파일 및 코드 변경점 시각화: GUI 화면 우측 패널을 통해 프로젝트 디렉터리 내 파일 목록을 탐색하고 에이전트가 제안한 코드 수정 사항의 차이점(diff)을 실시간으로 직관적으로 검토할 수 있습니다.
  • 다양한 문서 및 작업 분석: 텍스트 파일뿐만 아니라 스프레드시트, PDF 등 다양한 형식의 문서를 워크스페이스에 로드하여 정보 요약, 데이터 분석, 표 및 시각 자료 정리 작업을 수행하도록 지시할 수 있습니다.
  • 코드 자동 수정 지원: 초기 작업 공간 설정 후 에이전트가 지시된 프로젝트의 컨텍스트를 파악해 필요한 코드 수정 작업을 자체적으로 수행하며, 복잡한 프롬프트 엔지니어링 없이도 도구 호출을 이어갑니다.

데스크톱 앱과 Web UI 구동 환경 및 모델 연동 방식

DeepSeek Harness는 데스크톱 환경과 Node.js 런타임 환경 모두에서 유연하게 구동할 수 있도록 다양한 실행 방식을 제공합니다.

2026년 9월 말 공개된 0.2 계열 선행 버전을 통해 macOS(Apple Silicon 포함)와 Windows 환경을 지원하는 독립 설치형 데스크톱 패키지가 출시되었습니다. 사용자는 복잡한 환경 변수나 종속성 설치 없이 일반 데스크톱 애플리케이션 형태로 손쉽게 설치하여 사용할 수 있습니다.

동시에 Node.js 환경(LTS 권장)을 선호하는 개발자를 위해 CLI 패키지도 함께 제공됩니다. 터미널에서 다음 명령어를 입력하면 로컬 브라우저 기반 Web UI가 즉시 실행됩니다.

npx @deepseek-ai/dsh web

이 명령어는 기본적으로 http://127.0.0.1:3080 포트에서 로컬 서버를 기동하고 시스템 기본 웹 브라우저를 자동으로 엽니다. 브라우저 자동 오픈을 원하지 않는 환경에서는 --no-open 플래그를 사용할 수 있으며, --port 옵션으로 포트를 변경할 수 있습니다.

모델 연동 측면에서도 폭넓은 유연성을 제공합니다.

  • 로컬 및 원격 LLM 연결: 설정 파일(config.yaml 또는 GUI의 Settings 메뉴)을 통해 DeepSeek 공식 API뿐만 아니라 로컬에서 구동 중인 OpenAI 호환 엔드포인트(LM Studio, Strata, 로컬 Qwen 모델 등)를 손쉽게 추가할 수 있습니다.
  • 멀티모달 비전 지원: 설정에 input: [text, image] 옵션을 지정하거나 GUI 모델 설정의 Vision 옵션을 활성화함으로써 이미지와 텍스트를 동시에 처리하는 멀티모달 입력 워크플로우를 구성할 수 있습니다.

v0.2.0-rc.1의 주요 개선점과 개발자 프리뷰 도입 시 주의사항

최신 v0.2.0-rc.1 릴리스에서는 실무 사용 편의성과 안정성을 보강하는 여러 개선 사항이 반영되었습니다.

  • 외부 API 키 없는 웹 검색 연동: DeepSeek 계정 모델을 활용할 때 별도의 외부 검색 엔진 API 키 등록 없이도 웹 검색을 즉시 활용할 수 있도록 개선되었습니다. 아울러 로컬 모델 등에서도 'dsh-free-search'와 같은 웹 검색 플러그인을 손쉽게 추가하여 환각(hallucination)을 줄이고 최신 정보 기반의 답변을 얻을 수 있습니다.
  • 정기 자동화 작업의 플러그인 분리: 주기적으로 실행되는 정기 작업(스케줄링 태스크)이 옵션 플러그인 패키지 형태로 분리되어 코어의 무거움을 방지하고 필요한 환경에서만 선택적으로 도입할 수 있도록 개선되었습니다.
  • 윈도우 샌드박스 권한 진단 도구: Windows 환경에서 샌드박스 내부 접근 권한 문제(Access Denied)로 실행이 중단되는 현상을 진단하고 원인을 분리해 복구할 수 있는 전용 도구가 내장되었습니다.
  • 도구 실패 복구 안정화: 외부 도구 실행이 실패했을 때 이전 세션 상태를 유실하거나 무분별하게 재실행되어 부작용을 일으키는 문제를 방지하도록 에이전트 복구 로직이 정교화되었습니다.

도입 시 확인해야 할 제약 사항

현재 DeepSeek Harness v0.2 계열은 공식 README에 명시된 바와 같이 '개발자 프리뷰(developer preview)' 단계입니다. 프레임워크가 빠르게 개선되는 과정에 있으므로, 차후 릴리스에서 설정 파일 포맷이나 플러그인 API 인터페이스의 하위 호환성을 깨는 변경(breaking changes)이 발생할 가능성이 있습니다.

또한 사내망이나 기업 방화벽 환경처럼 아웃바운드 인터넷 접속에 HTTP 프록시가 필요한 네트워크의 경우, 백엔드 Node 런타임의 내장 fetch(undici)가 운영체제의 프록시 환경변수(HTTP_PROXY, HTTPS_PROXY)를 자동으로 반영하지 못해 연결 오류(GitHub Discussion #4448)가 발생할 수 있습니다. 이러한 환경에서는 EnvHttpProxyAgent 등을 활용한 환경 프록시 디스패처 설정 여부를 사전에 점검해야 합니다.

출처