한 줄 요약
DeepSeek Harness는 모델 연결, 도구, 세션 로그, 에이전트 루프를 플러그인으로 구성해 작업 환경을 조합하는 에이전트 하네스입니다.
저장소: deepseek-ai/deepseek-harness
코드를 읽는 에이전트에 사내 도구를 하나 붙이려면 무엇부터 나눠 봐야 할까요? 저희 AI 자료실에서 소개한 DeepSeek Harness는 Cordis 기반 플러그인 구조를 제공합니다. 모델 설정과 작업 디렉터리부터 준비하고, 탐색·작은 수정·도구 확장 순서로 살펴보세요.
무엇을 할 수 있나
CLI 이름은 dsh입니다. 모델 어댑터와 도구 레지스트리, 세션 로그, 에이전트 루프까지 플러그인이며 설정에서 교체할 수 있습니다. Web UI에서는 파일 읽기·수정, 명령 실행, 작업 위임, 계획 관리를 사용할 수 있습니다.
다만 현재는 호환성이 깨지는 변경이 있을 수 있는 개발자 프리뷰입니다. 공식 안전 안내는 보안 감사를 받지 않았으며 운영 준비가 된 소프트웨어로 취급하지 말라고 명시합니다. 저희는 민감정보가 없는 전용 환경에서 업무 하나부터 좁혀 보시길 권합니다.
시작하기
Node.js를 설치한 뒤 다음 명령으로 Web UI를 시작합니다.
npx @deepseek-ai/dsh web
기본 주소는 http://127.0.0.1:3080이며 로컬 실행은 브라우저를 엽니다. Settings → Models에서 모델 키를 저장하고, Choose workspace에서 프로젝트 디렉터리를 추가해 선택합니다. 새 UI는 워크스페이스를 선택해야 세션 입력을 사용할 수 있습니다. 키는 설정에만 등록하고 프롬프트에 붙이지 마세요.
활용 시나리오 1: 저장소의 첫 안내 받기
새 프로젝트를 맡았다면 주요 패키지와 실행 흐름부터 요청해 보세요. 공식 Web UI 가이드도 저장소를 요약하고 주요 패키지를 찾는 작업으로 시작합니다. 다음처럼 확인할 범위를 더해 요청할 수 있습니다.
이 저장소의 주요 패키지와 역할을 설명해 주세요.
실행이 시작되는 위치와 패키지 사이 연결을 근거 파일과 함께 정리하고,
아직 확인하지 못한 부분은 따로 적어 주세요. 파일은 수정하지 마세요.
설명에 나온 파일을 직접 열어 대조한 뒤 더 궁금한 경로를 좁혀 질문합니다. 가이드에 따르면 활성 권한 정책에서 승인이 필요한 작업은 UI가 묻습니다. 명령 실행 요청이 나오면 탐색에 필요한지 먼저 확인하세요.
활용 시나리오 2: 실패하는 테스트 조사하기
공식 Python SDK 예제에는 저장소를 조사하고 실패하는 테스트를 수정하도록 요청하는 흐름이 있습니다. Web UI에서도 같은 주제의 작은 과제를 골라 원인 조사부터 요청해 볼 수 있습니다.
현재 저장소에서 실패하는 테스트를 조사하고 싶습니다.
기존 테스트 실행 방법을 먼저 찾고, 실행할 명령을 설명해 주세요.
실패를 확인하면 원인 후보와 최소 수정 범위를 제안하고 승인을 기다려 주세요.
수정 후에는 처음 실패한 조건과 다시 실행한 결과를 함께 봅니다. 공식 SDK 예제는 별도 Harness home과 워크스페이스를 지정하는 구성도 보여 줍니다. 예제의 최소 SDK 프로필은 Web UI와 도구 구성이 다르므로 설정을 그대로 섞지 마세요.
활용 시나리오 3: 사내 도구 연결을 설계하기
플러그인 확장 전에는 에이전트에게 허용할 입력과 출력을 먼저 적어 보세요. 공식 아키텍처는 모델 어댑터와 모델이 호출하는 도구를 서로 다른 확장 지점으로 설명합니다. 읽기 전용 업무 하나를 골라 이렇게 요청해 볼 수 있습니다.
사내 문서 검색을 읽기 전용 도구로 연결하려고 합니다.
도구의 입력과 출력, 허용할 문서 범위, 오류 처리 기준부터 정리해 주세요.
공식 확장 구조에서 연결할 지점을 찾아 설명하고, 설치나 설정 변경은 기다려 주세요.
계획을 받은 뒤 플러그인 출처와 코드를 검토하고, 호출할 API와 노출할 데이터 범위를 정합니다. 도구가 있다는 이유만으로 모든 업무를 연결하기보다 권한 하나가 어디까지 닿는지 확인해 보세요. 실행한 패키지·플러그인 버전과 설정도 함께 남깁니다.
기업 도입에서 확인할 것
장점: 모델과 도구의 확장 지점이 나뉘어 있어 사내 연결을 설계할 때 각각 검토할 수 있습니다. 공식 Web UI 가이드와 SDK 예제를 출발점으로 삼아 필요한 실행 형태를 고르세요.
운영 부담과 보안: 플러그인과 호환성 변경을 관리해야 합니다. 공식 안전 안내는 최소 권한, 폐기 가능한 가상 머신·컨테이너 또는 전용 환경, 파일 백업을 권합니다. 샌드박스와 승인 기능도 격리를 보장하지 않으므로 노출한 파일·네트워크·프로세스·자격증명 범위를 따로 확인합니다.
라이선스: 저장소는 MIT이며 제3자 의존성 고지도 제공합니다. 두 문서를 함께 읽고 모델 API의 이용 조건과 비용은 별도로 검토합니다.
원문과 함께 읽기
- DeepSeek Harness 저장소
- README와 시작 명령
- 공식 안전 안내
- Web UI 가이드
- 아키텍처 문서
- LICENSE, 제3자 고지
- 함께 읽기: OpenCode의 plan·build, mattpocock/skills의 팀 절차
마치며
하이프마크 빌더 커뮤니티는 앞으로도 이렇게 직접 살펴본 AI 도구와 오픈소스를 꾸준히 공유하려고 합니다. 빌더 여러분께 도움이 될 좋은 자료들을 계속 모아 나누겠습니다.