DeepSeek Harness: 실용적인 플러그인 우선 에이전트 가이드

DeepSeek 의 최신 오픈소스 릴리스는 또 다른 모델 체크포인트가 아닙니다. DeepSeek Harness(별칭 dsh) 는 "모든 것이 플러그인"아키텍처를 통해 에이전트를 실행하기 위한 개발자 프리뷰 환경입니다. 이 구분이 중요합니다. 더 강력한 모델은 답변을 개선할 수 있지만, Harness 는 답변이 도구에 도달하고, 컨텍스트를 운반하며, 상태를 기록하고, 행동으로 전환되는 방식을 변화시킵니다.

공식 저장소는 2026 년 8 월에 등장했으며 빠르게 발전하고 있습니다. DeepSeek 는 호환성을 깨뜨리는 변경 사항이 발생할 것이라고 명시적으로 경고합니다. 적절한 대응은 프로젝트를 무시하거나 생산 에이전트 스택을 하룻밤 사이에 교체하는 것이 아닙니다. 플러그인 경계가 워크플로우를 검사하고 변경하기 쉽게 만드는지 테스트하는 실험실로 취급하세요.

본 가이드에서 검토한 소스: DeepSeek Harness 공식 저장소.

에이전트 Harness 가 실제로 제어하는 것

채팅 모델은 메시지를 수신하고 토큰을 반환합니다. 에이전트 Harness 는 해당 루프를 운영 결정으로 감쌉니다.

모델이 호출할 수 있는 도구;
도구 스키마가 노출되는 방식;
대화 및 작업 상태가 저장되는 위치;
로그에 기록되는 이벤트;
플러그인이 서로를 발견하는 방법;
도구 실패 후 발생하는 상황;
그리고 사용자가 실행을 감독하는 데 사용하는 인터페이스.

DeepSeek Harness 는 Cordis 와 플러그인 시스템을 중심으로 이러한 관심사를 구축합니다. "모든 것이 플러그인"이라는 말은 모든 통합이 자동으로 안전하다는 약속이 아니라 구성 가능성 주장으로 읽어야 합니다. 플러그인에는 기능, 구성, 수명 주기 동작 또는 UI 표면이 포함될 수 있습니다. 이점은 교체 가능성입니다. 평가자, 도구 어댑터 또는 저장소 계층은 전체 호스트의 재작성을 강제하지 않고도 진화할 수 있습니다.

가장 작은 로컬 파일럿으로 시작하세요

공식 빠른 시작은 의도적으로 짧습니다.

npx @deepseek-ai/dsh web

이는 기본적으로 127.0.0.1:3080에서 로컬 웹 인터페이스를 시작합니다. 이는 탐색에 유용하지만, 책임 있는 파일럿에는 몇 가지 추가 경계가 필요합니다.

합성 파일로 임시 워크스페이스를 만드세요. 첫 번째 실행을 홈 디렉토리, 생산 저장소, 클라우드 자격 증명 또는 고객 문서로 지정하지 마세요. 개발자 프리뷰는 세션 간에 동작이 변경될 수 있으므로 패키지 버전과 날짜를 기록하세요. 읽기 전용 도구로 시작한 다음, 이벤트 추적 로그를 이해한 후에야 하나의 되돌리기 가능한 쓰기 도구를 추가하세요.

유용한 첫 번째 작업은 평범한 것입니다. 에이전트에게 작은 샘플 프로젝트를 스캔하고, 중복된 구성 값 세 개를 식별하며, 적용하지 않고 패치를 제안하도록 요청하세요. 이는 파일 발견, 추론 및 제시 기능을 검증하면서 영향 범위를 작게 유지합니다.

Explore DeepSeek in MidassAI

편의성이 아닌 권한을 중심으로 플러그인을 설계하세요

가장 중요한 플러그인 경계는 권한입니다. 비밀을 읽고, 파일을 편집하며, 임의의 명령을 실행하고, 변경 사항을 게시할 수 있는 단일 "워크스페이스"플러그인을 피하세요. 권한별로 기능을 분리하세요.

읽기 전용 저장소 검사기;
제한된 포맷터 또는 검증기;
테스트 워크스페이스로 제한된 패치 작성기;
명시적 승인이 필요한 별도의 배포 또는 메시징 기능.

이 구조는 실패를 분류하기 쉽게 만듭니다. 연구 플러그인이 쓸 수 없다면, 문서 내의 프롬프트 인젝션 시도가 저장소를 직접 변경할 수 없습니다. 배포 플러그인이 검증된 아티팩트 식별자만 허용한다면, 일반 쉘로 악용될 수 없습니다.

플러그인 설명도 API 계약과 마찬가지로 검토해야 합니다. 플러그인이 무엇을 하는지, 절대 하지 않는 것, 예상 입력 및 부분 실패를 보고하는 방법을 설명하세요. "프로젝트 관리"와 같은 모호한 설명은 권한 남용을 초대합니다. "선택된 패키지 하의 TypeScript 파일을 읽고 편집 없이 진단을 반환합니다"는 모델과 검토자 모두에게 방어 가능한 경계를 제공합니다.

관찰 가능한 작업으로 Harness 를 평가하세요

데모가 유창해 보이는지로 Harness 를 점수 매기지 마세요. 측정 가능한 결과가 있는 작업을 사용하세요. 실용적인 평가 세트에는 다음이 포함될 수 있습니다.

작업	통과 조건	포착해야 할 실패
저장소 검색	모든 알려진 픽스처 찾기	파일 누락 또는 범위 오류
검증 실행	정확한 종료 상태 반환	경고 숨김 또는 오류 잘림
패치 제안	허용된 파일만 변경	관련 없는 편집
도구 실패	중지 또는 승인된 대체 선택	묵시적 재시도 루프
장기 작업	단계 간 상태 유지	완료된 작업 반복

각 사례를 동일한 모델 설정으로 여러 번 실행하세요. 도구 호출 수, 경과 시간, 거짓 성공률 및 필요한 인간 수정량을 비교하세요. Harness 는 단순히 더 많은 행동을 가능하게 할 때가 아니라 행동을 더 예측 가능하게 만들 때 가치가 있습니다.

개발자 프리뷰 위험을 주시하세요

변경 사항 중단에 대한 공식 경고는 아키텍처에 영향을 미쳐야 합니다. 패키지 버전을 고정하세요. 플러그인 코드를 별도의 통합 계층에 유지하세요. 중요한 실행 데이터를 사용자가 제어하는 형식으로 내보내세요. 프리뷰 특정 구조 내부에만 대체 불가능한 상태를 저장하지 마세요.

강력한 도구를 활성화하기 전에 저장소의 안전 공지 사항도 읽어야 합니다. 로컬호스트 자체로는 보안 경계가 아닙니다. 브라우저 확장 프로그램, 다운로드된 파일, 복사된 프롬프트 및 기타 프로세스는 여전히 적대적인 콘텐츠를 도입할 수 있습니다. 모든 외부 아티팩트를 데이터로 취급하고, 에이전트의 권한을 확장할 수 있는 명령으로 취급하지 마세요.

합리적인 도입 결정

DeepSeek Harness 는 이미 긴밀하게 결합된 에이전트 코드에서 마찰을 느끼는 팀에게 가장 흥미롭습니다. 모든 새 도구가 오케스트레이션, UI, 로깅 및 상태 관리 전반에 걸쳐 변경을 필요로 한다면, 플러그인 우선 구성은 해당 비용을 줄일 수 있습니다. 유일한 요구 사항이 두 개의 안정적인 도구를 사용한 단일 모델 호출이라면, 빠르게 변화하는 Harness 를 도입하면 제거되는 것보다 더 많은 관리 부담을 초래할 수 있습니다.

가장 좋은 단기 사용법은 병행 파일럿입니다. 기존 저위험 워크플로우 하나를 재현하고, 현재 구현을 기준선으로 유지하며, 출력 품질뿐만 아니라 유지 보수성도 측정하세요. 각 권한을 소유한 플러그인과 되돌릴 수 없는 행동 전에 인간이 보는 증거를 문서화하세요.

DeepSeek Harness 는 주목할 만합니다. 논의를 "어떤 모델이 가장 똑똑한가?"에서 "에이전트 기능을 어떻게 조립하고 거버넌스해야 하는가?"로 이동시키기 때문입니다. 이는 더 건강한 엔지니어링 질문입니다. 개발자 프리뷰는 파일럿이 고정되고, 관찰 가능하고, 폐기하기 쉬운 한 이 질문에 답하는 데 이미 유용합니다.