DeepSeek Harness v0.1 개발자 미리보기 가이드
DeepSeek가 **DeepSeek Harness(dsh)**를 공식적으로 오픈소스화했습니다. 이는 에이전트 애플리케이션을 위한 오픈소스 프레임워크로, 현재 v0.1 개발자プレビュー 버전이 MIT 라이선스에 따라 배포되고 있습니다. 이는 새로운 대형 언어 모델(LLM)이 아니며 단순한 채팅 웹페이지도 아닙니다. 대신 모델을 도구, 파일 시스템, 샌드박스, 세션 및 사용자 인터페이스(UI)에 연결하는 실행 레이어입니다.
DeepSeek V4를 이해와 추론을 담당하는 ‘두뇌’로 본다면, Harness는 모델이 프로젝트를 읽고, 도구를 호출하고, 명령을 실행하며, 작업 상태를 저장하고 지속적인 작업을 완료할 수 있게 하는 ‘작업대(Workbench)’ 역할을 합니다. 이 글은 홍보성 구호를 다루지 않으며, DeepSeek Harness가 무엇인지, 어떻게 작동하는지, 어떤 시나리오에 적합한지, 그리고 일반 사용자가 어떻게 선택해야 하는지에 초점을 맞춥니다.
DeepSeek Harness란 무엇인가?
일반적인 채팅 애플리케이션은 보통 ‘사용자 질문 — 모델 답변’의 방식으로 동작합니다. 반면 에이전트 작업은 몇 단계를 더 거칩니다: 모델이 다음 행동을 판단하고, 도구를 호출하며, 실행 결과를 읽고, 필요시 재계획하여 작업이 완료될 때까지 이어집니다. 이 흐름을 관리하는 시스템이 바로 Agent Harness입니다.
DeepSeek Harness는 DeepSeek AI에서 개발했으며, 하위에는 Cordis 메타 프레임워크를 사용합니다. 공식적으로 제시된 핵심 개념은 간단합니다: Everything is a Plugin(모든 것은 플러그인이다). 모델 어댑터, 도구 레지스트리, 세션 로그, Agent Loop, 심지어 UI와 승인 정책까지 모두 플러그인으로 로드, 교체 또는 조합할 수 있습니다.
이는 팀이 모델을 바꾸거나 샌드박스/도구 시스템을 변경하더라도 에이전트 전체를 다시 작성할 필요가 없음을 의미합니다. 하나의 구성은 웹 애플리케이션을 조합하고, 다른 구성은 헤드리스 자동 작업을 실행할 수 있으며, 비즈니스 코드와 하부 능력 사이의 경계가 더 명확해집니다.
그것은 DeepSeek V4 및 DeepSeek 공식 사이트와 어떤 관계인가?
이 세 가지 개념은 종종 혼동되지만, 아래의 표로 구분할 수 있습니다:
| 이름 | 주요 역할 | 적합한 대상 |
|---|---|---|
| DeepSeek V4 | 언어 이해, 추론, 코드 생성 등 모델 능력 제공 | 모델 능력이 필요한 개인 및 개발자 |
| DeepSeek 공식 사이트 및 채팅 진입점 | 바로 사용할 수 있는 온라인 대화 경험 제공 | 빠르게 질문하거나 글쓰기, 번역, 자료 처리를 원하는 사용자 |
| DeepSeek Harness | 모델, 도구, 세션, 파일 시스템 및 실행 흐름을 결합하여 에이전트 구성 | 에이전트 시스템을 구축, 커스터마이즈 또는 연구하려는 개발자 |
따라서 Harness는 모델을 대체하지 않습니다. 이는 ‘모델이 어떻게 신뢰할 수 있게 실제 작업에 참여하는가’를 해결합니다. 단순히 모델의 경험을 원한다면 당 사이트의 DeepSeek 공식 사이트 진입점에서 시작할 수 있습니다. 기본 사용법을 알고 싶다면 DeepSeek 튜토리얼 및 웹 버전 사용 가이드를 계속 읽어보시기 바랍니다.
‘모든 것은 플러그인’은 어떤 문제를 해결하는가?
기존의 에이전트 프로젝트는 모델 호출, 도구 실행, 세션 상태 및 UI 로직을 단일 코드베이스에 작성하기 쉽습니다. 기능이 적을 때는 문제가 드러나지 않으나, 모델을 교체하거나 원격 샌드박스를 연결하거나 승인 규칙을 추가해야 할 때 한 부분을 건드리면 전체 시스템이 흔들리는 부작용이 생깁니다.
DeepSeek Harness는 능력을 교체가 가능한 인터페이스로 분리합니다. 공식 아키텍처 문서에서는 이 경계를 capability seam이라고 부르며, 일반적으로 세 가지 역할을 포함합니다: 인터페이스를 정의하는 Service Definition, 능력을 구현하는 Service Provider, 그리고 능력을 호출하는 Consumer. 파일 시스템을 예로 들면, 로컬 디렉터리, 원격 컨테이너 및 제한된 샌드박스가 동일한 유형의 인터페이스를 제공할 수 있으며, 상위 도구는 파일이 실제로 어디에 있는지 알 필요가 없습니다.
| 플러그인 레이어 | 담당 내용 | 교체 가능한 가치 |
|---|---|---|
| 모델 어댑터 | 모델 요청, 메시지 및 스트리밍 출력 | 다양한 모델이나 호환 엔드포인트 연결 가능 |
| 도구 및 권한 | 도구 등록, 호출 전 검사, 실행 및 결과 처리 | 시나리오에 따라 읽기/쓰기, 명령, 네트워크 권한 제한 가능 |
| 세션 및 로그 | 메시지, 도구 호출, 결과 및 상태 변화 저장 | 복구, 재생(Fireplay), 포킹(Fork) 및 감사 지원 |
| 파일 시스템 및 샌드박스 | 파일 읽기/쓰기, 명령 실행 및 격리 환경 | 로컬과 원격 실행 환경 간 전환 가능 |
| Agent Loop | 모델 요청, 도구 호출 및 후속 작업 조직화 | 작업 루프 및 종료 조건 커스터마이즈 가능 |
| Web 또는 Headless | 브라우저 UI 제공 또는 헤드리스 실행 방식 제공 | 동일한 능력을 인터랙티브와 자동화에 모두 활용 가능 |
플러그인화의 진정한 가치는 ‘플러그인 수가 많다’는 것이 아니라, 교체 비용을 낮추는 것입니다. 개발자는 에이전트 전체를 복제하고 유지보수하는 대신, 단일 능력 공급자만 교체하면 됩니다.
DeepSeek Harness는 어떻게 한 번의 작업을 완료하는가?
공식 문서에서 사용자 작업은 Turn으로 불리며, 하나의 Turn에는 여러 개의 Step이 포함될 수 있습니다. 각 Step은 모델 요청 및 해당 요청에 의해 트리거된 도구 실행을 의미합니다. 간소화된 흐름은 다음과 같습니다:
- Harness는 사용자 메시지를 수신하고 시스템 프롬프트, 히스토리 메시지 및 현재 사용 가능한 도구를 조립합니다.
- 모델이 직접 답변해야 하는지, 파일/터미널/검색 등 도구를 호출해야 할지 판단합니다.
- 도구 호출은 권한 정책과 실행 파이프라인을 통과하며, 결과는 세션 로그에 기록됩니다.
- 도구 결과가 모델의 추가 처리를 요구할 경우, Harness는 다음 Step을 시작합니다.
- 대기 중인 도구 또는 새 입력이 없으면 해당 Turn의 작업이 종료됩니다.
세션 로그는 이 아키텍처의 중요한 부분입니다. 모델이 본 내용은 로그에서 재구성해야 하며, 메시지, 도구 호출, 스트리밍 출력 및 상태 변화 모두 영속성 이벤트(Persistent Event)가 될 수 있습니다. 이는 작업을 복구하거나 오류를 추적하는 데 유리하며, 향후 재생(Replay)과 감사를 위한 확실한 근거를 남깁니다.
어떤 시나리오에 DeepSeek Harness가 적합한가?
1. 프로젝트 읽기/쓰기가 필요한 프로그래밍 에이전트
작업이 단순한 코드 생성을 넘어 저장소 이해, 여러 파일 수정, 검사 실행 및 오류에 따른 계속적인 수리가 필요한 경우, Harness는 파일 시스템, 터미널, LSP, 계획 및 승인을 하나의 흐름으로 결합할 수 있습니다. 이는 일회성 코드 Q&A보다 지속형 작업에 더 적합합니다.
2. 기업 내부 도구 및 프로세스 자동화
팀에서 비즈니스에 필요한 도구만 로드하고 민감한 작업을 승인 절차 뒤에 배치할 수 있습니다. 예를 들어, 자료 검색 에이전트는 읽기 권한만 개방하고, 배포 에이전트만이 특정 디렉터리에 쓸 수 있습니다. 권한은 도구와 샌드박스 경계에서 비롯되며, 프롬프트 내에 “파일을 수정하지 마라”고 작성하는 것보다 관리하기가 훨씬 쉽습니다.
3. 다중 모델 또는 다중 실행 환경 실험
다양한 모델, 도구 조합 및 샌드박스 구현을 비교해야 할 때, 플러그인 구조는 중복 엔지니어링을 줄여줍니다. 개발자는 작업과 UI를 그대로 유지한 채 모델 어댑터나 실행 백엔드만 교체하고 성공률, 소요 시간 및 오류 유형을 관찰할 수 있습니다.
4. 장기 작업, 백그라운드 작업 및 다중 에이전트 협업
복잡한 작업은 종종 분할, 외부 결과 대기 또는 서브 에이전트 위임이 필요합니다. Harness는 세션, 목표, 백그라운드 작업 및 서브 에이전트 관련 능력을 통합 아키텍처 내에 배치했으며, 복구 가능하고 관찰 가능한 장 흐름을 구축하는 데 적합합니다. 다만 v0.1은 여전히 개발자プレ뷰이므로 프로덕션 사용 전 충분한 테스트가 필요합니다.
5. 에이전트 프레임워크 및 플러그인 연구
프레임워크 작성자에게 DeepSeek Harness의 가치는 실제 코드베이스를 제공한다는 점에 있습니다: Agent Loop, 세션 이벤트, 도구 실행, 능력 인터페이스 및 UI를 어떻게 분할하는지. 연구자는 MIT 라이선스에 따라 디자인을 읽고 수정하며 검증할 수 있으며, 개념 문서에만 의존할 필요가 없습니다.
언제 사용하지 않아야 하는가?
모든 DeepSeek 사용자가 Harness를 설치해야 하는 것은 아닙니다.
- 단순히 질문, 글쓰기, 번역 또는 자료 정리를 한다면 온라인 채팅이 더 간편합니다.
- 모델 API를 한 번만 호출하고 도구 루프나 영속 세션이 필요 없다면 일반 SDK로 충분합니다.
- 팀에 Node.js, 샌드박스, 권한 및 플러그인 유지보수 경험이 없을 경우,プレ뷰 버전을 즉시 핵심 프로덕션 프로세스에 투입하는 것은 권장되지 않습니다.
- 요구사항이 매우 고정되어 있고 기존 자동화 스크립트가 안정적으로 작동한다면, 에이전트로의 마이그레이션이 반드시 수율을 가져다주지 않을 수 있습니다.
판단 기준은 간단합니다: 작업에서 모델이 여러 단계를 거쳐 도구를 사용하고, 상태를 읽으며, 결과에 따라 계속 행동해야 하는가? 만약 아니오라면, 새로운 개념 추종으로 시스템 복잡성을 늘릴 필요가 없습니다.
DeepSeek Harness 빠른 입문 튜토리얼
현재 가장 직접적인 방법은 npm을 통해 Web UI를 시작하는 것입니다. 지원되는 Node.js 버전을 설치한 후 다음 명령어를 실행합니다:
npx @deepseek-ai/dsh web기본적으로 웹 인터페이스는 http://127.0.0.1:3080에서 실행됩니다. 인터페이스에 진입하면 다음과 같은 단계를 따릅니다:
- 설정의 Models를 열어 DeepSeek API Key를 입력하고 저장합니다.
- 작업 디렉터리를 선택합니다; 워크스페이스 선택 전까지 작업 입력창은 활성화되지 않습니다.
- 새 세션을 만들고, 먼저 “이 저장소를 요약하고 주요 디렉터리 설명”과 같은 읽기 전용 작업으로 시작합니다.
- 각 도구 조작에 대한 승인 프롬프트를 확인하여 권한 범위가 예상과 일치하는지 확인합니다.
- 그 후 파일 수정, 테스트 실행 또는 서브 태스크 분해와 같은 복잡한 시도를 시도합니다.
소스에서 직접 실행하려면 공식 저장소를 클론한 후 의존성을 설치하고 빌드합니다:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web시험용 디렉터리를 실제 프로덕션 디렉터리와 분리하고, 권한 정책을 이해하지 못한 채 민감한 파일, 인증 정보 또는 고위험 명령어에 대한 접근 권한을 부여하지 마십시오. 다른 기본 진입점은 당 사이트의 DeepSeek 공식 사이트 사용 설명을 참조하시기 바랍니다.
사용 전 주의해야 할 제한 사항
DeepSeek 공식 측에서는 현재 버전이 Developer Preview이며, 향후 빠르게 반복되고 호환성을 깨는 변경사항이 발생할 수 있음을 명시하고 있습니다. 따라서 설정 파일, 플러그인 인터페이스 또는 실행 방식에 조정 가능성이 있습니다.
본격적 도입 전에는 최소한 네 가지를 확인해야 합니다: 테스트한 버전 잠금; 격리 환경에서 플러그인 검증; 쓰기, 명령 및 네트워크 작업에 대한 승인 설정; 세션 로그 보존 및 민감 정보 처리. 오픈소스와 MIT 라이선스는 2차 개발을 용이하게 하지만,プレ뷰 버전이 프로덕션 환경에 필요한 안정성과 보안 조치를 갖췄음을 의미하지는 않습니다.
요약
DeepSeek Harness의 포지셔닝은 다음과 같이 요약할 수 있습니다: 모델 능력을 실행 가능하고 확장 가능하며 복구 가능한 에이전트 시스템으로 조직화합니다. 그것은 Cordis를 기반으로 모델, 도구, 세션, 샌드박스, 파일 시스템, Agent Loop 및 UI를 모두 플러그인 체계에 넣습니다. 커스텀 에이전트, 실행 환경 전환 또는 에이전트 아키텍처 연구가 필요한 개발자에게 이는 깊이 읽을 만한 오픈소스 시작점을 제공합니다. 일반 사용자에게는 DeepSeek V4 온라인 채팅을 직접 사용하는 것이 여전히 더 간단한 선택입니다.
DeepSeek V4의 대화, 코드 및 자료 처리 능력을 먼저 경험해보고 싶다면 아래 진입점에서 시작하세요.