DeepSeek Harness (dsh)

DeepSeek Harness(dsh)란 무엇인가요?

DeepSeek Harness(dsh)는 DeepSeek AI가 개발한 오픈소스 에이전트 런타임 및 프레임워크입니다. Cordis 플러그인 커널을 기반으로 구축되었으며, AI 모델과 도구부터 세션, 샌드박스, 그리고 에이전트 루프 자체에 이르기까지 모든 구성 요소가 교체 가능한 플러그인입니다. dsh는 새로운 AI 모델이 아닙니다. 오히려 모델에 작업 공간, 도구, 권한, 메모리, 그리고 구조화된 실행 환경을 제공하여 작업을 완수할 수 있도록 하는 "하네스"입니다.

DeepSeek Harness의 주요 기능

DeepSeek Harness는 유연성과 소유권을 위해 설계된 모듈식, 플러그인 우선 아키텍처를 통해 차별화됩니다.

• 모든 것이 플러그인입니다: dsh의 핵심 원칙입니다. 모델 어댑터, 도구 레지스트리, 세션 로깅, 샌드박싱, 심지어 사용자 인터페이스와 같은 기능들도 플러그인으로 구현됩니다. 이를 통해 모놀리식 코어를 수정하지 않고도 에이전트 시스템의 어떤 계층이든 교체하거나 확장할 수 있습니다.

• 구성 가능한 런타임: 사용자는 플러그인의 "번들"을 쌓고 구성 "패치"를 적용하여 자신의 에이전트 런타임을 조립할 수 있습니다. dsh는 동일한 플러그인 코어를 공유하지만 서로 다른 기능을 노출하는 여러 사전 정의된 에이전트 "프리셋"(Standard, Code, Minimal, Creator)을 제공합니다.

• 완전한 로컬 실행: dsh는 원격 서버가 아닌 사용자의 로컬 머신에서 실행됩니다(기본값 http://127.0.0.1:3080). 이를 통해 사용자는 자신의 데이터와 실행 환경을 완전히 제어할 수 있습니다.

• 추가 전용 세션 로그: 모델 프롬프트, 추론, 도구 호출, 결과 등 모든 작업이 불변의 세션 로그에 기록됩니다. 이는 단계별 검사("Trajectory" 뷰), 재실행, 어느 지점에서든 실행 분기, 작업 재개와 같은 강력한 기능을 가능하게 합니다.

• 광범위한 플러그인 생태계: 활발한 커뮤니티가 빠르게 수백 개의 플러그인(GitHub의 dsh-plugin 아래 분류됨)을 개발하여 새로운 도구, 사용자 인터페이스, 브라우저 제어, 대체 에이전트 루프, 샌드박싱 솔루션을 추가하고 있습니다.

• 개발자 중심 및 MIT 라이선스: MIT 라이선스를 가진 개발자 프리뷰 프로젝트로서, dsh는 폐쇄된 호스팅 서비스를 사용하기보다 자신의 에이전트 인프라를 소유하고, 맞춤화하고, 구축하려는 팀과 개발자를 대상으로 합니다.

DeepSeek Harness 사용 방법

DeepSeek Harness 사용에는 로컬 설정, 구성, 그리고 플러그인 시스템을 활용하여 에이전트를 필요에 맞게 조정하는 것이 포함됩니다.

1. 빠른 설치 및 시작

• 필수 조건: Node.js(v22.19+ 또는 v24+)가 설치되어 있는지 확인하세요.

• Web UI 시작: 터미널에서 npx @deepseek-ai/dsh web을 실행하세요. 이 명령어는 dsh Web UI를 다운로드하고 시작하며, http://127.0.0.1:3080에서 접근할 수 있습니다.

• 초기 구성:

  • Web UI를 열고 ### Settings > Models로 이동하세요.
  • DeepSeek API 키(또는 Anthropic나 OpenAI와 같은 다른 지원되는 제공자의 자격 증명)를 추가하세요.

  • 작업 공간 디렉토리(에이전트가 작업할 로컬 폴더)를 선택하세요. 작업 공간이 선택될 때까지 세션 컴포저를 사용할 수 없습니다.

2. 소스에서 실행하기(개발용)

• 저장소 복제: git clone https://github.com/deepseek-ai/deepseek-harness
• 종속성 설치: pnpm install
• 프로젝트 빌드: pnpm run build
• 로컬 빌드 실행: pnpm dsh web

3. 플러그인으로 확장하기

• dsh의 힘은 확장성에 있습니다. 커뮤니티 플러그인을 프로필에 직접 설치할 수 있습니다.
• 예시: Terminal UI 플러그인을 설치하려면 dsh plugin add dsh-cc-tui를 실행하세요.
• 플러그인은 Web UI의 플러그인 설정 패널을 통해 관리하고 검사할 수 있습니다.

4. 런타임 모드 이해하기

• Standard Mode: 파일 편집, 셸, 검색, 스킬, 서브에이전트를 갖춘 완전한 기능의 코딩 에이전트입니다.

• Code Mode: TypeScript SDK를 통해 도구를 노출하여, 모델이 단일 프로그램 내에서 복잡한 다단계 작업을 조율할 수 있도록 합니다.

• Minimal Mode: 지속적인 bash와 파일 편집기만 있는 간소화된 환경으로, AI 모델 벤치마킹에 이상적입니다.

• Creator Mode: Standard Mode에 런타임 검사 도구를 더한 것으로, 새로운 에이전트 프리셋을 작성하고 플러그인 조합을 테스트하기 위해 설계되었습니다.

DeepSeek Harness 가격

DeepSeek Harness 자체는 MIT 라이선스 하에 ### 완전히 무료이며 오픈소스입니다. 소프트웨어에 대한 구독료나 라이선스 비용은 없습니다.

• 고려해야 할 비용:

  • 모델 API 비용: AI 모델(예: DeepSeek, OpenAI의 GPT-4, Anthropic의 Claude)에 대한 자신의 API 키를 제공해야 합니다. 선택한 모델 제공자의 사용량과 가격 책정에 따라 비용이 발생합니다.

  • 인프라: 로컬에서 실행되므로 "인프라"는 사용자 자신의 컴퓨터입니다. 서버 호스팅 비용은 없습니다.

  • 개발 시간: 개발자 프리뷰 프레임워크로서, dsh를 특정 프로덕션 요구 사항에 맞추려면 기술적 투자가 필요합니다.

DeepSeek Harness 사용에 유용한 팁

• Web UI 프리셋으로 시작하세요: web 프로필은 시작하기 가장 쉬운 방법입니다. 합리적인 기본 구성으로 자동 초기화됩니다.

• 구성을 검사하세요: dsh web --dump-config를 사용하여 인스턴스가 부팅되는 정확한 플러그인 트리를 출력하세요. 이는 디버깅과 패치 방법을 이해하는 데 매우 유용합니다.

• Trajectory 뷰를 활용하세요: 실행 후 Trajectory 탭을 사용하여 에이전트 작업의 모든 단계를 검사하세요. 이 투명성은 실패를 이해하고 프롬프트를 최적화하는 데 핵심적입니다.

• 작업 공간을 주의 깊게 관리하세요: 에이전트는 선택한 디렉토리 내에서 작동합니다. 필요한 권한이 있고 작업에 필요한 컨텍스트(코드, 파일)가 포함되어 있는지 확인하세요.

• 플러그인 출처에 주의하세요: 커뮤니티 플러그인은 DeepSeek AI에 의해 감사되지 않습니다. 특히 파일 시스템이나 네트워크 접근을 요청하는 플러그인은 설치 전에 소스 코드를 검토하세요.

• 변경 사항을 예상하세요: 프로젝트는 "개발자 프리뷰" 상태입니다. 실험에는 안정적이지만, 핵심 API와 플러그인에 대한 호환성이 깨지는 변경 사항이 향후 릴리스에서 발생할 수 있습니다. 이러한 변경을 감당할 수 없는 중요한 프로덕션 배포에는 권장되지 않습니다.

자주 묻는 질문(FAQ)

DeepSeek Harness는 DeepSeek의 새로운 AI 모델인가요?

아니요. DeepSeek Harness(dsh)는 모델이 아닙니다. 기존 AI 모델(DeepSeek 자체 모델, Claude, GPT-4 등)이 도구를 사용하고 작업을 완료할 수 있는 환경을 제공하는 프레임워크, 즉 "하네스"입니다.

공식 "DeepSeek Harness"와 Python "deepseek-harness"의 차이점은 무엇인가요?

그들은 우연히 비슷한 이름을 가진 완전히 관련 없는 두 프로젝트입니다. 공식 dsh(이 글의 주제)는 DeepSeek AI의 TypeScript/Node.js 에이전트 런타임입니다. Python deepseek-harness는 DeepSeek V4 API를 위한 독립적인 커뮤니티 구축 클라이언트 라이브러리입니다.

dsh에서 DeepSeek 모델 이외의 다른 모델을 사용할 수 있나요?

네. dsh는 플러그인을 통해 여러 "모델 어댑터"를 지원합니다. DeepSeek, OpenAI, Anthropic 및 OpenAI 호환 API 엔드포인트를 제공하는 다른 제공자에 대한 지원이 포함되어 있습니다.

dsh를 실행하는 것이 안전한가요? 제 파일에 접근하나요?

dsh는 로컬에서 실행되며 명시적으로 선택한 작업 공간 디렉토리 내의 파일에만 접근합니다. 샌드박싱 플러그인은 권한을 더 제한할 수 있습니다. 그러나 코드를 실행하는 모든 소프트웨어와 마찬가지로, 신뢰할 수 있는 콘텐츠가 있는 작업 공간에서만 실행하고 검증되지 않은 출처의 플러그인에 주의해야 합니다.

Claude Code와 같은 호스팅된 에이전트 대신 dsh를 선택하는 이유는 무엇인가요?

데이터 프라이버시(모든 것이 로컬에 유지됨)를 우선시하거나, 에이전트 기능을 깊이 있게 맞춤 설정해야 하거나, 런타임을 소유하고 수정하려 하거나, 내부 플랫폼을 구축 중이라면 dsh를 선택하세요. 더 턴키 방식이고 안정적이며 관리되는 경험과 적은 설정 오버헤드를 원한다면 호스팅된 에이전트를 선택하세요.

플러그인을 어떻게 기여하나요?

Cordis/dsh 규칙에 따라 플러그인을 개발하고, npm이나 GitHub에 게시하고, GitHub에서 dsh-plugin 토픽으로 태그를 지정하여 커뮤니티에서 발견할 수 있도록 하세요.

"개발자 프리뷰"는 무엇을 의미하나요?

소프트웨어가 개발 및 테스트를 위해 공개적으로 사용 가능하지만, API가 아직 안정적이지 않다는 의미입니다. 향후 릴리스에서 호환성이 깨지는 변경 사항이 발생할 수 있습니다. 이러한 변경을 감당할 수 없는 중요한 프로덕션 배포에는 권장되지 않습니다.