DeepSeek Harness 플러그인 개발은 먼저 도구, 모델 제공자, 웹 화면, 워크플로 중 하나를 고른 뒤 단일 기능의 최소 플러그인으로 시작해야 합니다. 이번 주에는 공식 저장소의 현재 master 문서와 package.json을 기준으로 환경을 고정하고, 설정·권한·호환성 검사를 별도 산출물로 남기는 방식이 가장 안전합니다. DeepSeek Harness는 현재 개발자 미리보기 단계이며 호환성을 깨는 변경이 발생할 수 있습니다. 공식 저장소 README

이 글은 내부 스크립트를 도구로 바꾸려는 AI Agent 엔지니어, 팀 게이트웨이나 사용자 정의 모델 단말을 연결하려는 개발자, 공통 원격 개발 환경과 플러그인 검수 절차를 맡은 기술 책임자를 위한 글입니다.

마지막 업데이트: 2026년 8월 18일. 공식 저장소 README, 구조 문서, 개발 안내서, 기여 안내서, package.json을 다시 확인했습니다.

01

먼저 확장 목표를 네 가지로 나눕니다

DeepSeek Harness는 Cordis를 기반으로 하며, 모델 어댑터·도구 등록부·세션 기록·에이전트 루프까지 플러그인으로 구성됩니다. 따라서 기존 코어 파일을 직접 고치는 방식보다, 필요한 기능을 별도 플러그인으로 장착하는 방식이 구조에 맞습니다. 플러그인이 해제되면 등록 효과도 되돌릴 수 있다는 점이 핵심입니다. 공식 아키텍처 문서

  • 도구 호출: 파일 검색, 사내 API, 배포 명령처럼 입력과 출력이 분명한 기능입니다. 단일 도구 플러그인으로 시작하기 좋습니다.
  • 모델 제공자: API 키, 기본 단말, 모델 목록, 요청 변환을 담당합니다. 일반 도구 플러그인과 섞지 않는 편이 좋습니다.
  • 웹 화면과 원격 기능: 브라우저 화면, 서버 API, 원격 호출 계약이 함께 필요합니다. 호스트와 클라이언트의 경계를 먼저 정해야 합니다.
  • 워크플로 조합: 여러 도구와 정책을 특정 작업 방식으로 묶습니다. 기능 코드를 복사하기보다 프로필과 번들 조합으로 관리해야 합니다.

다음 조건이면 플러그인을 하나로 묶어도 됩니다.

  • 같은 권한을 사용합니다.
  • 같은 배포 주기를 가집니다.
  • 한 기능이 빠져도 전체 기능을 독립적으로 끌 필요가 없습니다.

반대로 모델 인증과 셸 실행처럼 권한이 다르면 분리해야 합니다. 웹 화면과 장시간 실행 워크플로도 별도 플러그인으로 나누는 편이 장애 범위를 줄입니다.

02

도구 플러그인은 최소 계약부터 검증합니다

내부 스크립트를 dsh-plugin으로 포장할 때 가장 흔한 실패는 처음부터 여러 도구를 등록하는 것입니다. 첫 버전은 하나의 도구, 하나의 입력 형식, 하나의 출력 계약만 가져야 합니다.

권장 순서는 다음과 같습니다.

  1. 저장소 루트에서 현재 공식 개발 안내서의 Node.js와 pnpm 조건을 확인합니다.
  2. 공식 저장소를 복제하고 의존성을 설치합니다.
  3. package.json의 dsh 관련 설정과 기존 플러그인 예제를 확인합니다.
  4. 입력 스키마에서 필수값, 허용값, 길이 제한을 정합니다.
  5. 등록 진입점에서 도구 이름과 실행 함수를 연결합니다.
  6. 성공 결과와 실패 결과를 서로 다른 구조로 반환합니다.
  7. 타입 검사와 최소 실행으로 등록 여부를 확인합니다.

공식 개발 안내서는 Node.js 22.19 이상 또는 24 이상을 지원 범위로 설명하고, 저장소는 pnpm 11.7.0을 고정합니다. 새 복제본에서는 pnpm install 뒤 pnpm run typecheck가 첫 확인 신호입니다. 공식 개발 안내서

도구 플러그인의 성공 신호는 세 단계로 기록하십시오.

  • 플러그인이 프로필에 로드됩니다.
  • 도구 이름과 입력 설명이 도구 목록에서 발견됩니다.
  • 정상 입력은 결과를 반환하고, 실패 입력은 원인·대상·복구 방법을 포함한 오류를 반환합니다.

단순히 예외를 문자열로 던지면 원격 환경에서 진단하기 어렵습니다. 인증 실패, 입력 오류, 외부 API 시간 초과, 권한 거부를 구분해야 합니다. 도구 자체가 불안정하면 해당 도구만 비활성화할 수 있도록 분리하고, 기존 프로필로 되돌리는 회귀 경로를 준비하십시오.

주의: 개발자 미리보기에서는 커뮤니티 플러그인이 동작한다고 해서 공식 API 계약으로 볼 수 없습니다. 검증한 커밋과 패키지 버전을 함께 기록하고, 문서가 이동하거나 타입이 바뀌면 같은 테스트를 다시 실행해야 합니다.

03

모델 제공자 플러그인은 자격 증명과 기능을 분리합니다

모델 제공자 플러그인은 도구 플러그인과 책임이 다릅니다. 도구는 작업을 실행하지만, 모델 플러그인은 단말 주소와 모델 선택, 인증 정보, 요청 형식을 관리합니다.

API 키와 사용자 정의 단말 주소를 소스 코드에 넣으면 다음 문제가 생깁니다.

  • 깃 기록에 비밀값이 남습니다.
  • 팀원마다 다른 모델 설정을 코드 수정으로 해결하게 됩니다.
  • 테스트와 운영 환경의 설정이 섞입니다.
  • 키 교체 때마다 플러그인을 다시 배포해야 합니다.

공식 개발 안내서는 DEEPSEEK_API_KEY를 환경 변수 또는 저장소 루트의 무시 대상 .env에서 읽는 방식을 제시하며, 실제 키가 없으면 실 API 종단 간 테스트가 건너뛰어질 수 있다고 설명합니다. DEEPSEEK_BASE_URL은 사용자 정의 단말에 사용할 수 있지만 실제 자격 증명은 커밋하면 안 됩니다. 환경 변수 안내

모델 플러그인에는 다음 기록을 남기면 좋습니다.

  • 필요한 환경 변수 이름과 필수 여부
  • 기본 모델과 사용자 정의 모델의 차이
  • 요청 실패 시 재시도 여부
  • 모델 목록을 고정할지 동적으로 읽을지
  • 키가 없을 때 표시할 진단 메시지

이 구성을 일반 도구 플러그인에 함께 넣으면 권한 검토가 어려워집니다. 모델 교체가 필요할 때 모델 플러그인만 바꾸도록 경계를 유지하십시오.

04

웹 기능은 호스트와 클라이언트의 빌드 경계를 지킵니다

웹 화면을 추가하는 플러그인은 서버 코드와 브라우저 자원을 한 파일처럼 다루면 안 됩니다. 공식 구조는 Host와 Client를 별도 집계로 관리하며, 일반 패키지는 한쪽 집계에 등록됩니다. api/remotes처럼 양쪽 진입점이 필요한 예외 패키지도 있으므로, 이를 모든 플러그인의 기본 구조로 복사해서는 안 됩니다. Host와 Client 구조 안내

빌드 순서도 중요합니다.

  1. Host 타입을 검사합니다.
  2. Host 실행 결과와 원격 계약을 생성합니다.
  3. Client 타입을 검사합니다.
  4. Client 번들과 브라우저 자원을 빌드합니다.
  5. 웹 빌드와 실제 화면 동작을 확인합니다.

공식 문서에 제시된 저장소 전체 빌드 순서는 Host tsc, Host tsdown, Client tsc, Client tsdown, 웹 빌드입니다. 이 순서를 무시하고 브라우저 코드만 먼저 확인하면 원격 타입이 아직 생성되지 않아 잘못된 오류나 누락을 놓칠 수 있습니다.

웹 플러그인의 회귀 기준은 화면이 뜨는지에 그치지 않습니다. 서버가 시작되는지, 브라우저가 원격 API를 호출하는지, 권한 승인이 필요한 동작이 차단되는지, 서버 중단 뒤 오류가 설명 가능한지까지 봐야 합니다. 웹 화면 문제를 다루는 팀이라면 DeepSeek Harness Web UI 장애 점검 가이드와 함께 브라우저 콘솔·서버 로그·프로필 설정을 나눠 확인하는 편이 빠릅니다.

05

워크플로는 프로필과 번들로 조합합니다

프로필은 실행할 플러그인과 번들을 쌓는 이름 있는 구성입니다. web과 headless 같은 기본 템플릿이 있고, 각 프로필은 자체 cordis.patch.yml을 가질 수 있습니다. 번들 목록, 프로필 패치, 홈 수준 패치, 실행 시 오버레이가 순서대로 적용됩니다. 프로필과 번들 설명

특정 프로필에 플러그인을 연결할 때는 먼저 실제 구성을 확인하십시오.

dsh --profile web --dump-config

그 뒤 다음처럼 프로필을 나누면 됩니다.

  • 실험 프로필: 새 도구와 임시 모델만 적용합니다.
  • 테스트 프로필: 고정된 도구, 가짜 단말, 제한된 권한을 사용합니다.
  • 지속 작업 프로필: 승인 정책과 저장소 경로를 보수적으로 유지합니다.

프로필 파일을 팀원이 동시에 직접 수정하면 설정 충돌과 재현성 문제가 생깁니다. 기능은 플러그인 저장소에 두고, 실행 조합만 프로필에서 관리하십시오. AI Agent 플러그인 개발 환경 검수 기준을 별도 문서로 만들어 Node.js, pnpm, 키 주입, 로그 보존, 권한 범위를 같은 순서로 확인하는 것도 효과적입니다.

06

배포 전 검수는 다음 순서로 진행합니다

  1. 공식 저장소의 현재 커밋과 패키지 버전을 기록합니다.
  2. 깨끗한 작업 폴더에서 의존성을 다시 설치합니다.
  3. TypeScript 타입 검사와 린트를 실행합니다.
  4. 플러그인 로드, 도구 검색, 정상 실행을 확인합니다.
  5. 잘못된 입력과 권한 거부를 확인합니다.
  6. 외부 단말 중단과 네트워크 오류를 재현합니다.
  7. 대상 프로필에서 설정 덮어쓰기를 확인합니다.
  8. Web UI라면 Host와 Client를 순서대로 빌드합니다.
  9. 새 환경에 설치한 뒤 제거하고 기존 프로필로 회귀합니다.
  10. 검증한 커밋, 패키지 버전, Node.js 버전, 재검토 날짜를 배포 기록에 남깁니다.

공식 기여 안내서도 현재 저장소가 초기 단계이며, 공식 패키지가 커뮤니티 패키지보다 우선한다는 보장은 없다고 설명합니다. 따라서 커뮤니티 플러그인을 사용할 때는 공식 기능처럼 가정하지 말고, 자체 검수 결과를 배포 기준으로 삼아야 합니다. 공식 기여 안내서

07

조건별로 구조를 결정하는 빠른 기준

  • 입력과 출력이 하나이고 외부 인증이 없으면 도구 플러그인으로 시작합니다. 실패하면 해당 도구만 비활성화합니다.
  • 모델 주소·키·모델 목록을 바꾸면 모델 제공자 플러그인으로 분리합니다. 실패하면 기본 모델 프로필로 되돌립니다.
  • 브라우저 자원이나 원격 API가 필요하면 웹 플러그인으로 분리합니다. 실패하면 headless 프로필에서 핵심 도구만 검증합니다.
  • 여러 플러그인의 순서와 권한만 조합하면 프로필을 추가합니다. 실패하면 기존 프로필을 수정하지 않고 새 프로필을 폐기합니다.
  • 서로 다른 팀이 독립적으로 배포해야 하면 하나의 대형 플러그인을 만들지 말고 여러 플러그인으로 나눕니다.
08

현재 구조와 선택 기준 비교

확장 목표 기본 구조 먼저 확인할 신호 실패 시 회귀
내부 스크립트 도구 단일 TypeScript 진입점과 입력 계약 로드·검색·정상 및 오류 반환 도구만 해제
사용자 정의 모델 모델 제공자와 환경 변수 키·단말·모델 선택 기본 모델 프로필
웹 화면 Host·Client와 원격 계약 서버·브라우저·권한 승인 headless 검증
장기 워크플로 여러 번들과 프로필 패치 프로필별 재현성 이전 프로필

이 작업을 매번 개인 맥에서만 처리하면 Node.js 버전, pnpm 상태, 키 저장 방식, 빌드 산출물이 사람마다 달라지기 쉽습니다. 반대로 장기간 계속 유지할 개발 장비는 고정 비용과 관리 부담이 생기며, 물리 장치나 상시 고성능 작업이 필요하지 않은 팀에는 과할 수 있습니다. 플러그인 개발이 간헐적이고 여러 명이 같은 환경에 원격 접속해야 한다면 클라우드 맥 지속 개발 환경 구성처럼 보존 가능한 환경을 검토할 만합니다.

특히 현재 방식의 단점이 로컬 환경 분산, 깨끗한 설치 검증의 번거로움, 팀원별 설정 차이로 반복된다면 VpsMesh의 맥 환경을 단기 테스트나 릴리스 검수용으로 비교해 볼 수 있습니다. 반대로 매일 무거운 작업을 장기간 수행하거나 물리 인터페이스가 필요한 경우에는 직접 장비를 소유하는 편이 더 합리적입니다. 플러그인 빌드 빈도와 협업 인원을 먼저 계산한 뒤, 필요할 때만 원격으로 보존되는 환경을 선택하십시오.