빠른 웹 화면 검증에는 npm 실행 경로가 적합합니다. 핵심 패키지를 수정하거나 플러그인 경계를 디버깅할 때만 소스 작업 공간을 추가하고, 원격 팀 운영은 안정 환경과 개발 환경을 나누는 이중 경로가 안전합니다.
빠른 웹 화면 검증에는 npm 실행 경로가 적합합니다. 핵심 패키지를 수정하거나 플러그인 경계를 디버깅할 때만 소스 작업 공간을 추가하고, 원격 팀 운영은 안정 환경과 개발 환경을 나누는 이중 경로가 안전합니다.
실행만 확인하려는데 설치 항목이 늘어나고, 소스 빌드는 어디서 실패했는지 찾기 어렵습니다.
가장 빠른 해법은 웹 화면과 기본 에이전트 작업만 검증할 때 npm 경로를 쓰고, 핵심 패키지 수정이나 플러그인 경계 디버깅이 필요할 때만 소스 빌드로 전환하는 것입니다.
이 글은 딥시크 하니스를 처음 시험하는 개발자, 외부 플러그인을 만드는 기여자, 원격 맥 환경을 반복 배포하는 플랫폼 팀을 대상으로 합니다. 성능이 더 높다는 이유로 소스 빌드를 선택하는 글이 아닙니다. 두 경로의 유지 책임과 복구 가능성을 기준으로 판단합니다.
마지막 업데이트: 2026년 8월 18일. 공식 저장소의 실행 안내, 개발 안내, package.json의 엔진과 패키지 관리자 선언을 다시 확인했습니다.
딥시크 하니스는 현재 개발자 미리 보기 단계이며, 공식 문서도 호환성이 깨지는 변경이 있을 수 있다고 명시합니다. 따라서 npm 경로가 자동으로 안정적인 것은 아니며, 소스 경로가 성능을 높여 주는 것도 아닙니다. 차이는 주로 배포 단위와 수정 권한에 있습니다. 공식 실행 안내는 npm 실행과 저장소 실행을 별도 경로로 설명합니다.
판단은 다음처럼 나누면 됩니다.
빠른 시험의 성공 기준은 설치가 끝났다는 문장이 아닙니다. 같은 시작 디렉터리에서 웹 화면을 열고, 모델을 연결하고, 작업 공간을 선택한 뒤, 기본 작업 하나가 재현되는지 확인해야 합니다.
공식 안내의 기본 실행 명령은 다음과 같습니다.
npx @deepseek-ai/dsh web
웹 화면은 기본적으로 로컬 주소에서 제공됩니다. 실행한 디렉터리가 기본 파일 시스템 위치로 사용되지만, 새 웹 화면에서는 작업 공간을 별도로 선택해야 합니다. 모델 설정에는 API 키가 필요하며, 작업 승인이 필요한 동작은 현재 권한 정책에 따라 확인 절차가 나타납니다. 웹 화면 사용 안내에서 이 순서를 확인할 수 있습니다.
npm 경로에서 먼저 기록할 항목은 네 가지입니다.
이 기록이 없으면 같은 명령을 다시 입력해도 다른 패키지를 받을 수 있습니다. 특히 개발자 미리 보기 단계에서는 최신 배포본이 이전 실행 결과와 호환된다고 가정하면 안 됩니다.
플러그인을 설치한다고 해서 하니스 전체를 소스에서 실행해야 하는 것은 아닙니다. 먼저 배포된 실행 패키지에서 플러그인이 로드되고, 필요한 기능이 호출되며, 오류가 무플러그인 설정에서 재현되는지 확인합니다.
소스 환경이 필요한 시점은 더 좁습니다.
외부 플러그인만 만드는 경우에는 독립 저장소와 공개 인터페이스를 우선하는 편이 관리 범위가 작습니다. 반대로 공식 저장소의 패키지 변경을 시도한다면 전체 작업 공간의 Node.js, pnpm, 타입 검사와 빌드 순서를 맞춰야 합니다. 공식 개발 안내는 pnpm@11.7.0을 저장소 설정에 고정하고, Node.js 조건을 22.19 이상 또는 24 이상으로 제시합니다. 이 조건은 미리 보기 버전에 따라 바뀔 수 있으므로 설치일의 문서를 다시 확인해야 합니다. 공식 개발 안내와 현재 package.json을 함께 대조해야 합니다.
주의: 플러그인 오류를 고치다가 안정 작업 공간의 설정까지 바꾸지 않아야 합니다. 무플러그인 구성, 이전 패키지 버전, 마지막으로 성공한 기본 작업을 별도로 보존해야 복구가 가능합니다.
소스 빌드는 다음 명령으로 시작합니다.
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
이 경로는 단순히 파일을 내려받는 방식이 아닙니다. 저장소의 현재 선언에 따르면 패키지 관리자는 pnpm@11.7.0으로 고정되어 있고, Node.js 엔진은 ^22.19.0 || >=24.0.0입니다. 또한 첫 설정 뒤 타입 검사를 통과해야 작업 공간이 준비된 것으로 봅니다. 공식 package.json의 엔진과 스크립트에 명시된 조건입니다.
소스 경로에서 발생하는 숨은 비용은 다음과 같습니다.
공식 개발 안내는 호스트와 클라이언트 집계를 별도로 관리하며, 타입 검사와 빌드가 일정한 순서를 따른다고 설명합니다. 그러므로 소스 빌드를 선택할 때는 “수정할 수 있다”보다 “실패한 작업 공간을 누가 다시 만들 것인가”를 먼저 정해야 합니다.
원격 맥에서 실행할 때는 설치보다 재구축 검증이 중요합니다. 다음 순서를 권장합니다.
원격 배포에서 “최신 npm 버전”은 답이 아닙니다. 정답은 팀이 실제로 검증한 버전입니다. 버전이 공개되어 있어도 Node.js 조건, 플러그인 호환성, 설정 형식이 함께 바뀔 수 있습니다. 안정 환경에는 고정 버전을 쓰고, 업데이트는 별도 환경에서 검증한 뒤 승인해야 합니다.
맥을 직접 관리하지 않고 반복 배포해야 한다면 클라우드 맥 환경 선택 기준처럼 접속 방식과 환경 보존 조건을 먼저 확인하는 편이 좋습니다. 지역별 원격 응답과 운영 책임이 중요하다면 한국 원격 맥 환경도 같은 기준으로 비교할 수 있습니다.
소스 빌드가 실패했을 때 기존 환경을 덮어쓰는 방식은 가장 위험합니다. 실패 원인이 코드 변경인지, Node.js 차이인지, pnpm 의존성 해석인지 구분할 수 없기 때문입니다.
복구는 다음 조건으로 설계합니다.
이중 경로는 비용을 두 배로 만드는 방식이 아니라 책임을 분리하는 방식입니다. 안정 경로는 재현 가능한 실행에 집중하고, 개발 경로는 플러그인과 핵심 코드 변경에 집중합니다. 두 환경을 같은 작업 디렉터리나 같은 세션 저장 위치로 연결하면 분리 효과가 사라집니다.
다음 조건에서 하나라도 해당하면 npm 경로가 우선입니다.
다음 조건이 모두 필요할 때만 소스 경로로 이동합니다.
위 두 그룹이 동시에 필요하면 이중 경로를 선택합니다. 안정 작업은 고정된 npm 실행으로 유지하고, 소스 작업 공간은 연구와 검증에만 사용합니다.
| 평가 항목 | npm 실행 | 소스 빌드 | 이중 경로 |
|---|---|---|---|
| 첫 실행 단순성 | 우리 평가 5점 | 우리 평가 2점 | 우리 평가 3점 |
| 핵심 코드 수정 | 우리 평가 1점 | 우리 평가 5점 | 우리 평가 5점 |
| 버전 고정 | 우리 평가 4점 | 우리 평가 5점 | 우리 평가 5점 |
| 빌드 실패 범위 | 우리 평가 5점 | 우리 평가 2점 | 우리 평가 3점 |
| 빠른 복구 | 우리 평가 4점 | 우리 평가 2점 | 우리 평가 5점 |
| 인수인계 난이도 | 우리 평가 4점 | 우리 평가 2점 | 우리 평가 3점 |
이 점수는 성능 측정값이 아니라 유지 책임을 비교한 편집 평가입니다. 소스 빌드가 더 빠르거나 npm 실행이 더 안정적이라고 단정하는 표가 아닙니다.
팀에 넘길 때는 다음 항목을 빠뜨리지 않아야 합니다.
딥시크 하니스의 공식 저장소는 현재 개발자 미리 보기이며 호환성이 깨지는 변경 가능성을 명시하고 있습니다. 따라서 기록이 없는 원격 배포는 설치에 성공해도 운영 환경으로 보기 어렵습니다. 공식 저장소의 현재 상태와 기여 안내를 배포 승인 기준에 포함하는 것이 좋습니다.
시험만 하는 개인이라면 소스 작업 공간을 미리 만들 필요가 없습니다. 반대로 장기적으로 플러그인과 핵심 기능을 함께 관리하는 플랫폼 팀이라면 소스 환경을 안정 환경과 분리해야 합니다. 현재 방식이 매번 Node.js를 다시 맞춰야 하고, 최신 패키지로 자동 이동하며, 실패한 업그레이드에서 돌아갈 증거도 없다면 장비를 직접 유지하는 것보다 원격 맥 환경을 독립적으로 구성하는 편이 관리하기 쉽습니다. VNCMac의 맥 렌탈은 npm 안정 실행과 소스 개발을 분리해야 하는 경우에 임시 검증 환경으로 검토할 수 있지만, 장기간 고정 부하나 물리 장치 연결이 핵심이라면 직접 보유한 맥이 더 적합합니다.