2026 DeepSeek Harness 플러그인 업데이트는 어떻게 단계적으로 배포할까요?

이번 주에 적용할 단계별 배포 일정

현재 공식 저장소는 DeepSeek Harness를 개발자 미리보기로 표시하며, 호환성을 깨는 변경이 발생할 수 있다고 명시합니다. dsh-v0.1.0-rc.7 태그는 2026년 8월 17일에 게시되었지만, 새 릴리스가 있다는 사실만으로 모든 서드파티 플러그인의 호환성이 보장되지는 않습니다. 공식 저장소의 개발자 미리보기 안내와 rc.7 태그 기록을 기준으로 매번 다시 확인해야 합니다.

업데이트 전에 실행 조합을 복구 가능한 상태로 고정합니다

플러그인 이름만 적어 두면 롤백 자료로 부족합니다. 같은 이름의 플러그인이라도 커밋, 패키지 잠금 상태, Harness 빌드, Node 실행 환경, 설정 파일이 달라질 수 있기 때문입니다. 특히 DeepSeek Harness는 모든 기능을 플러그인 단위로 구성하고 Cordis를 기반으로 동작하므로, 한 구성 요소의 변경이 Host와 Client 양쪽의 시작 과정에 영향을 줄 수 있습니다. 공식 README의 플러그인 구조 설명과 공식 Cordis 저장소를 함께 확인해야 합니다.

소스 체크아웃으로 운영한다면 업데이트 전 다음과 같이 증거를 남길 수 있습니다.

git rev-parse HEAD
node --version
pnpm --version
git status --short
sha256sum pnpm-lock.yaml

공식 개발 문서는 현재 개발 환경에서 Node.js 22.19 이상 또는 24 계열을 지원하고, 저장소가 pnpm 버전을 고정한다고 설명합니다. 따라서 검증면과 정식면에서 Node 버전과 패키지 관리자 버전이 달라지면 플러그인 결과를 그대로 비교할 수 없습니다. 공식 개발 안내의 실행 조건과 설치 절차를 기준으로 환경 증거를 보관해야 합니다.

자동 업데이트도 이 시점에 멈춰야 합니다. 정기 작업이 실행되는 동안 의존성이 바뀌면 문제가 플러그인 자체인지, Harness인지, 간접 의존성인지 분리하기 어렵습니다. 잠금 파일은 재현성을 높이지만 영구적인 안정성을 보장하지는 않으므로, 잠금 파일과 함께 정기적인 재검증 조건을 기록해야 합니다.

검증면은 정식 실행면과 경계를 분리합니다

두 번째 실행면이 없다면 유일한 정식 환경을 업데이트하지 않는 것이 원칙입니다. 가장 좋은 방법은 독립 작업 공간이나 별도 원격 맥에 필요한 설정 구조만 복사하는 것입니다. 실제 고객 자격 증명, 결제 정보, 삭제나 배포처럼 되돌리기 어려운 작업은 복사하지 않습니다.

검증면은 정식면과 다음 조건을 같게 맞춰야 합니다.

• 같은 설치 경로 논리와 시작 명령을 사용합니다.
• 같은 Host와 Client 구성을 사용합니다.
• 같은 플러그인 탐색 경로를 사용합니다.
• 비밀값은 별도 테스트 자격 증명으로 대체합니다.
• 외부 전송, 삭제, 배포 도구는 처음부터 비활성화합니다.

공식 실행 예시는 npx @deepseek-ai/dsh web이며, 기본 웹 화면은 127.0.0.1:3080에서 제공됩니다. 소스 방식은 저장소 복제 후 pnpm install, pnpm run build, pnpm dsh web 순서입니다. 이 명령은 임의의 설정 키를 추측하지 않고 공식 실행 경로를 재현할 때 사용합니다. 공식 사용자 안내와 공식 README의 실행 절차를 참고하면 됩니다.

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

검증면을 만들 수 없는 상황에서 유일한 실행면을 종료하고 새 조합을 설치하는 것은 회색 배포가 아닙니다. 그것은 중단을 감수한 직접 교체입니다. 장기 에이전트가 실행 중이라면 두 번째 원격 맥을 먼저 확보하거나, 작업을 안전하게 중지하고 이전 조합을 즉시 복원할 수 있는 상태를 만든 뒤 진행해야 합니다. NodeMini의 클라우드 맥 안정·검증 환경 안내를 함께 검토하면 단기 검증면을 별도로 두는 구성을 판단하기 쉽습니다.

로딩과 설정 계약부터 확인합니다

첫 번째 검증에서는 기능이 좋아졌는지 평가하지 않습니다. 플러그인이 발견되는지, 설정을 읽는지, Host와 Client가 함께 시작되는지만 봅니다. 이 단계에서 쓰기 도구를 실행하면 로딩 문제와 외부 부작용이 한 번에 섞입니다.

실행 로그는 성공 메시지만 저장하지 말고 실제 오류를 원문으로 남겨야 합니다. 예를 들어 다음 항목을 비교합니다.

plugin discovery: found
configuration load: passed
host startup: passed
client startup: passed
session creation: passed

반대로 plugin not found, 설정 파일 경로 오류, Host 등록 실패, Client 번들 누락이 나타나면 두 번째 단계로 넘어가지 않습니다. 플러그인 이름이 검색된다는 사실도 등록 성공과 같지 않습니다. 설정 카드나 도구 목록이 화면에 보이는지, 실제 세션에서 호출 가능한지까지 확인해야 합니다.

설정 키와 동작은 현재 공식 문서와 대상 플러그인 소스를 기준으로 대조합니다. 커뮤니티 글이나 플러그인 이름만 보고 키를 만들어 넣으면, 오래된 예제와 현재 API가 섞일 수 있습니다. Cordis 자체도 API가 안정되지 않았고 예고 없이 바뀔 수 있다고 안내하므로, Cordis의 현재 문서와 해당 플러그인의 소스 계약을 함께 봐야 합니다.

최소 작업과 권한 경계를 분리해 회귀합니다

두 번째 검증에는 작업을 두 종류만 선택합니다. 하나는 읽기 전용 작업이고, 다른 하나는 결과를 되돌릴 수 있는 제한된 쓰기 작업입니다. 두 작업 모두 고객 데이터가 아닌 테스트 저장소나 임시 디렉터리에서 수행합니다.

읽기 작업에서는 다음을 확인합니다.

• 예상한 도구가 등록되는지 확인합니다.
• 도구 설명과 입력 형식이 업데이트 전후에 달라졌는지 비교합니다.
• 승인 없이 실행되는 도구가 늘어나지 않았는지 봅니다.
• 결과가 세션에 정상적으로 반환되는지 확인합니다.

쓰기 작업에서는 빈 파일 생성이나 임시 브랜치 수정처럼 회수 가능한 동작만 허용합니다. 삭제, 외부 메시지 발송, 공개 배포, 비밀값 접근은 이 단계의 성공 증거로 사용하지 않습니다.

능력 목록은 텍스트로만 비교하지 말고 변경 전후 스냅샷으로 저장합니다.

before: read, search, inspect, approved-write
after:  read, search, inspect, approved-write, external-send

위와 같이 새 권한이 보이면 기능이 정상 동작하더라도 배포를 중지해야 합니다. 권한 확대는 호환성 문제가 아니라 별도 보안 승인 항목입니다. 플러그인이 기본 도구를 조용히 추가하거나 승인 단계를 우회한다면, 버전이 작동한다는 이유로 공유 환경에 넣어서는 안 됩니다.

세션 지속성과 재시작을 별도 증거로 남깁니다

세 번째 검증에서는 새 세션과 기존 세션을 구분합니다. 프로세스를 다시 시작한 뒤 새 세션이 만들어지는 것과, 중단된 원래 작업이 같은 상태에서 이어지는 것은 전혀 다른 결과입니다.

다음 순서로 확인합니다.

1. 이전 버전에서 기준 작업을 시작하고 세션 식별자와 상태를 저장합니다.
2. 새 플러그인 조합에서 새 세션을 만들어 설정과 도구 목록을 확인합니다.
3. 검증면 프로세스를 정상 종료합니다.
4. 같은 설정으로 다시 시작합니다.
5. 새 세션이 이전과 같은 계약을 제공하는지 확인합니다.
6. 지속 작업은 별도 테스트에서만 재개 가능성을 검사합니다.

설정 지속성은 파일이 남아 있는지만 보면 안 됩니다. 재시작 뒤 실제로 같은 프로필이 읽히는지, 플러그인 상태가 중복 등록되지 않는지, Host와 Client의 등록 순서가 달라지지 않는지 확인해야 합니다. 공식 개발 문서도 Host와 Client를 별도 집계 대상으로 관리하며, 하나의 패키지가 어느 집계에 등록되는지가 빌드와 실행 결과에 영향을 줄 수 있다고 설명합니다. 공식 아키텍처 및 개발 구조를 기준으로 플러그인 작성자는 양쪽 등록 경로를 점검해야 합니다.

장기 작업은 앞선 검증이 모두 통과한 뒤에만 넣습니다. 재시작 후 서비스가 살아났다는 사실만으로 원래 작업이 이어진다고 기록하면 안 됩니다. 실제 재개 지점, 중복 실행 여부, 중간 결과 보존 여부가 확인되지 않았다면 해당 작업은 업데이트 전에 중지하거나 이전 실행면에서 계속해야 합니다.

원격 맥은 위험도에 따라 나누어 전환합니다

원격 맥을 한꺼번에 바꾸지 말고, 먼저 장애 영향이 낮은 작업이 실행되는 그룹에서 시작합니다. 첫 그룹에서 로딩, 최소 작업, 권한, 재시작을 모두 확인한 뒤 관찰 시간을 둡니다. 그 시간 동안 오류가 없었다는 사실보다, 실제 세션과 작업 결과가 정상이라는 증거를 우선합니다.

팀이 플러그인 버전을 통일해야 하는지 판단할 때는 “모두 최신인가”보다 “승인된 조합을 재현할 수 있는가”를 봐야 합니다. 공유 환경은 Harness, 플러그인, 의존성 버전을 하나의 릴리스 단위로 관리하는 편이 안전합니다. 반면 개발자의 실험 환경까지 같은 버전으로 묶으면 새 기능 검증이 느려질 수 있으므로, 실험 조합은 별도 프로필이나 원격 맥으로 격리합니다.

플러그인과 Harness와 의존성이 함께 바뀌었다면 일부 패키지만 이전 버전으로 내리지 않습니다. 업데이트 전의 전체 잠금 파일과 전체 플러그인 조합으로 돌아가야 합니다. 부분 롤백은 새 Host가 이전 Client와 연결되거나, 이전 플러그인이 새 Cordis 계약을 기대하는 혼합 상태를 만들 수 있습니다.

마지막으로 다음 정보를 배포 기록에 남깁니다.

• 승인된 Harness와 플러그인 조합
• 변경 담당자와 검토자
• 사용한 검증면
• 통과한 기준 작업
• 롤백 위치와 복구 명령
• 다음 재검토 조건

DeepSeek Harness는 빠르게 바뀌는 개발자 미리보기이며, dsh-plugin은 공식 주제 목록에서 플러그인 검색을 돕는 표식일 뿐 호환성 인증서가 아닙니다. 공식 dsh-plugin 주제 목록에서도 플러그인별 관리 주체와 버전이 다르므로, 이름이 같다는 이유로 안전한 조합이라고 판단하면 안 됩니다.

현재 방식과 원격 맥 운영을 비교해 선택합니다

유일한 로컬 맥에서 직접 업데이트하는 방식은 장비를 하나만 관리하면 된다는 장점이 있지만, 실행 중인 공유 Agent를 멈추고, 실패한 플러그인과 설정 변경을 분리하기 어렵고, 복구 중 작업 상태가 사라질 수 있습니다. 개인 개발자가 짧은 읽기 작업만 수행한다면 직접 업데이트도 가능하지만, 장기 작업과 팀 공유가 섞인 환경에는 적합하지 않습니다.

반대로 검증용 원격 맥을 따로 두면 실행면을 보존하면서 새 조합을 시험할 수 있고, 원격 접속 기록과 세션 재시작을 독립적으로 확인할 수 있습니다. 다만 네트워크 지연, 접근 권한, 비용, 비밀값 전달 정책을 별도로 관리해야 합니다. 따라서 매일 안정적인 장기 부하를 하나의 장비에서 계속 처리해야 하거나 물리 장치 접근이 필수라면 자체 장비가 더 맞을 수 있습니다.

업데이트 기간에만 두 번째 실행면이 필요하고, 새 플러그인 조합을 빠르게 확인해야 한다면 NodeMini의 맥 미니 주문 및 원격 환경 안내를 검토할 수 있습니다. 기존 방식의 중단 위험과 혼합 버전 문제를 줄이면서, 검증용 환경을 별도로 유지하는 선택지입니다.

이번 배포에서 가장 중요한 기록은 “새 버전이 실행됐다”가 아닙니다. 이전 조합으로 즉시 돌아갈 수 있고, 검증면에서 권한과 세션 동작을 확인했으며, 각 원격 맥 그룹의 전환 결과를 설명할 수 있다는 증거입니다. 두 번째 실행면이 없다면 먼저 그 환경을 확보한 뒤 업데이트를 시작하는 편이 안전합니다.