DeepSeek Harness 플러그인, 어떻게 써야 할까

DeepSeek Harness가 출시된 지 이틀도 안 돼 GitHub Star가 10만에 육박했다.

하나의 Agent Harness가 이렇게 높은 관심을 받는다면, 나 역시 그것이 대체 무엇이 다른지 살펴보고 싶어진다.

그것에는 매우 눈에 띄는 설계 선언이 하나 있다.

Everything is a plugin.

모든 것이 플러그인이다.

여기서 말하는 "모든 것"은 우리가 익히 아는 도구와 확장만을 뜻하지 않는다.

모델은 플러그인이고, 세션은 플러그인이며, Agent는 플러그인이고, 타이머 역시 플러그인이다.

모델과 세션은 분명 있어도 그만인 부가 기능이 아니다. 이런 Agent의 기본 구성 모듈마저 플러그인이라고 부른다면, 그럼 그 메인 프로그램에는 도대체 무엇이 남는 걸까?

로컬에 설치해 실행한 뒤 「설정 → 플러그인 → 플러그인 목록」에 들어가면, 그 안에서 llm, session, agent, timer, api-gateway 등 이미 활성화된 플러그인을 한 무더기 볼 수 있다.

하지만 대화 상자로 돌아오면, 나는 통일된 "플러그인 진입점"을 찾을 수도 없고, 모델에게 직접 "session 플러그인을 호출해 달라"고 말할 수도 없다. 어떤 기능은 도구 호출 기록에 나타나고, 어떤 것은 페이지를 바꾸며, 또 어떤 것은 처음부터 끝까지 보이지 않지만 계속 백그라운드에서 작동한다.

이것은 Chrome 플러그인 스토어와는 전혀 다른 이야기이고, 우리가 평소 말하는 Tool, Skill, MCP와도 다르다.

그렇다면 이렇게 "활성화됨"으로 표시된 플러그인들을, 사용자는 도대체 어떻게 경험해야 하는 걸까?

어떤 플러그인들이 있는가?

이런 내장 플러그인 외에도, 커뮤니티에는 이미 다수의 DSH 확장이 등장했다. GitHub의 dsh-plugin Topic 아래에는 이미 4k개가 넘는 관련 리포지터리가 모여 있다.

Awesome DSH Plugin도 바로 설치할 수 있는 플러그인을 적잖이 정리해 두었다. 다만 이는 커뮤니티가 유지·관리하는 플러그인 색인이며, 공식 추천과 같지는 않으니 설치 전에는 소스 코드와 의존성, 권한을 여전히 살펴봐야 한다.

이들은 모두 플러그인이라고 불리지만, 설치한 뒤 가져오는 변화는 서로 같지 않다. 플러그인이 DSH에 등록하는 주요 기능에 따라, 대략 다음과 같은 몇 가지 방향으로 이해할 수 있다.

- Tool : 모델에 CSV, JSON, 정규식, 이미지 이해, 컴퓨터 조작 등 새로운 동작을 추가한다.

- UI / Web Client : Web 페이지에 작업 보드, Git 그래프, 파일 패널, 테마와 통계 정보를 추가한다.

- Service / Provider : 모델, 검색, 파일 시스템, Shell 또는 샌드박스에 새로운 하부 구현을 제공한다.

- Command : 모델이 호출 여부를 판단할 필요 없이, 사용자가 직접 실행할 수 있는 명령을 추가한다.

이 외에도 새로운 애플리케이션 진입점을 제공하거나, 여러 기능을 하나의 완전한 시나리오로 조합하는 플러그인도 있다. 예를 들어 dsh-TUI는 터미널 인터페이스를 제공하고, DSH Automation은 예약 작업·세션·관리 페이지를 하나로 조합하며, dsh-minigames는 미니 게임을 Web UI 안에 넣는다.

이런 이름들은 플러그인이 주로 어떤 기능을 제공하는지를 설명하는 것이지, 서로 배타적인 고정 유형이 아니다. 하나의 플러그인이 Tool과 UI, Service를 동시에 포함할 수 있다.

몇몇 인기 있는 플러그인을 살펴보면, 플러그인이 최종적으로 어떻게 사용자에게 경험되는지 직관적으로 이해할 수 있다.

DSH Web UI

DSH Web UI는 플러그인이라기보다는, DSH Web 버전을 둘러싸고 개발된 확장 모음에 가깝다.

그것은 DSH의 기존 페이지에 새로운 인터페이스와 기능을 더한다. 예를 들어 작업 보드, Git 그래프, 파일 미리보기, 실시간 Token 통계, 테마 스킨과 데스크톱 펫 등이다. 그중 원격 연결과 SSH 플러그인은 DSH의 사용 범위를 다른 기기나 머신으로까지 확장할 수도 있다.

그림에서 몇 가지 변화를 바로 확인할 수 있다. 왼쪽에는 작업 보드와 세션 작업 공간이 추가되었고, 가운데 세션 페이지는 새로운 스킨으로 바뀌었으며 데스크톱 펫이 표시된다. 입력창 아래에는 TPS, 모델 소요 시간, 컨텍스트 점유, Token 수량 등 실시간 정보도 추가되었다.

이것이 UI 플러그인과 Tool 플러그인의 가장 직관적인 차이다.

UI 플러그인이 확장하는 것은 DSH의 웹 인터페이스이며, 모델에 dsh-web-ui라는 이름의 도구를 추가하지는 않는다. 설치하고 활성화한 뒤에는, 사용자가 페이지에서 새로 추가된 진입점을 직접 클릭하거나 그것이 표시하는 정보를 확인하면 되고, 대화 상자에서 모델에게 "DSH Web UI를 호출해 달라"고 말할 필요가 없다.

작은 변화 하나만 관찰하고 싶다면, 실시간 통계 플러그인을 단독으로 설치할 수 있다.

npx @deepseek-ai/dsh plugin --profile web add @linxin666/dsh-live-stats

설치가 끝나면 다시 시작한다.

npx @deepseek-ai/dsh web

아무 대화나 한 번 시작해, 입력창 아래에 TPS, 모델 소요 시간, 컨텍스트 점유, Token 수량 등의 정보가 나타난다면 플러그인이 이미 작동한 것이다. 그것이 어떻게 web Profile에 들어가고, 또 어떻게 인터페이스를 기존 페이지에 걸어 놓는지에 대해서는, 뒤의 원리 부분에서 Bundle과 Web Client 진입점을 통해 설명하겠다.

여기서는 기본으로 UI 플러그인 전체 세트를 설치하는 것은 권하지 않는다. 그 모음에는 SSH, 모바일 원격, 공용 터널 등의 기능도 포함되어 있어 권한과 의존성 범위가 분명히 더 크므로, 필요에 따라 개별 플러그인을 선택할 수 있다.

ModLens

ModLens는 현재 커뮤니티에서 인기가 높은 비(非) UI 플러그인 중 하나다. 그것이 해결하는 문제는 아주 직접적이다. 순수 텍스트 모델에 이미지 이해 능력을 보완해 준다.

사용자는 오류 화면 캡처 한 장을 붙여 넣고, 곧바로 질문할 수 있다.

이 스크린샷을 읽고, 오류 내용과 가장 가능성 높은 원인을 알려줘.

사용자가 Tool 이름을 기억할 필요는 없다. ModLens는 DSH에 modlens_read_image를 등록하고, 모델이 이미지를 읽어야 한다고 판단하면 이 도구를 호출한다.

하지만 이것이 순수 텍스트 모델이 갑자기 네이티브 시각 능력을 얻었다는 뜻은 아니다. 이미지는 먼저 ModLens에 설정된 비전 엔진에 넘겨져 OCR, 페이지 레이아웃, 의미 등 구조화된 근거를 얻고, 그 결과를 다시 원래의 텍스트 모델에 넘겨 분석을 이어간다. 비전 엔진은 별도로 설정한 API일 수도 있고, 사용자가 권한을 부여하면 본기에 이미 있는 Agent CLI를 재사용할 수도 있다.

스크린샷은 해당 비전 서비스로 전송될 수 있으니, API Key, 계정 또는 고객 데이터가 담긴 민감한 이미지를 업로드해서는 안 된다.

이 두 예시를 나란히 놓고 보면, 서두의 그 질문에 답이 나온다.

- DSH Web UI는 페이지와 클라이언트 기능을 등록하며, 설치 후 인터페이스에서 바로 사용한다.

- ModLens는 이미지 읽기 도구와 그에 대응하는 Web Client 기능을 등록하며, 사용자가 이미지를 붙여 넣고 평소처럼 질문하면 모델이 필요할 때 그것을 호출한다.

- session, timer 같은 기본 플러그인은 주로 백그라운드에서 작동하며, 사용자는 진입점을 아예 보지 못할 수도 있다.

플러그인 목록은 그저 알려줄 뿐이다. 이번에 시작한 DSH가 어떤 컴포넌트를 로드했는지를. 그것은 당신이 하나씩 클릭하기를 기다리는 기능 메뉴가 아니다. 어떤 플러그인을 어떻게 사용하는지 알고 싶다면, 그것이 기능을 어디에 두었는지를 봐야 한다.

「모든 것이 플러그인」은 어떻게 구현되는가?

DSH Web UI가 바꾸는 것은 페이지이고, ModLens가 추가하는 것은 이미지 이해 능력이다. 기능은 다르지만, 둘은 같은 방식으로 DSH에 진입한다. 차이는 그것들이 어떤 고정된 플러그인 유형에 속하는지가 아니라, 로드된 뒤 시스템에 어떤 기능을 등록했는지에 있다.

플러그인을 설치하면 무슨 일이 일어나는가?

설치 명령을 실행하면, DSH는 먼저 플러그인의 npm 패키지를 지정된 web Profile에 내려받는다. npm 패키지는 코드와 설정 파일의 운반체일 뿐이며, 그것이 실제로 어떻게 DSH에 진입하는지를 결정하는 것은 패키지 안에 선언된 Bundle이다.

평범한 npm 패키지는 다운로드에 성공하더라도 자동으로 DSH 플러그인이 되지는 않는다. 그것이 dsh.bundle을 통해 DSH에 어디에서 설정을 읽을지 알려줘야만, 설치 도구가 그것을 현재 Profile에 어떻게 연결할지 알게 된다.

Bundle은 이 패키지가 기여하는 한 층의 설정이라고 이해할 수 있다. 그것은 npm 패키지의 package.json 안에 있는 dsh.bundle로 선언하여, DSH에 어떤 Plugin을 설정 트리에 추가해야 하는지 알려준다. 설치 도구가 이 선언을 인식하면, 이 Bundle을 web Profile의 Bundle 목록에 덧붙인다.

여기서 Profile은 이번 시작에 어떤 Bundle을 조합할지를 나타낸다. 그것은 DSH의 기본 기능, Web 애플리케이션을 포함할 수 있고, ModLens 같은 서드파티 플러그인을 넣을 수도 있다. 시작할 때 DSH는 이 Bundle들의 설정을 순서대로 적용해, 최종적으로 실제로 로드할 하나의 플러그인 트리를 얻는다.

그다음에야 Plugin 차례가 된다. Plugin은 실제로 로드되어 기능을 제공하는 모듈이다. Cordis는 DSH의 플러그인 실행 기반으로, 설정에 따라 플러그인을 로드하고 의존성을 처리하며 플러그인 생명주기를 관리하는 역할을 맡는다. 플러그인이 언로드될 때, Cordis를 통해 등록한 도구·서비스·이벤트는 함께 취소되고, 플러그인이 스스로 만든 타이머나 연결은 그에 대응하는 정리 로직을 제공해야 한다.

이 과정을 하나로 이으면 이렇게 된다.

npm 패키지 다운로드 → 패키지 안의 Bundle 선언 읽기 → Bundle을 web Profile에 추가 → 시작 시 각 층의 설정을 적용해 플러그인 트리 형성 → Cordis가 그중의 Plugin을 로드 → Plugin이 DSH에 기능을 등록

혼동하기 쉬운 네 가지 개념도 이 사슬 위에서 각자의 자리를 갖는다.

- npm 패키지 : 코드와 설정 파일의 운반체.

- Bundle : DSH에 이 패키지가 어느 층의 설정을 기여하는지 알려준다.

- Profile : 이번 시작에 어떤 Bundle을 조합할지 기록한다.

- Plugin : 실제로 로드되어 기능을 제공하는 모듈.

등록된 기능이 플러그인이 사용자에게 어디서 보이는지를 결정한다

Plugin은 로드된 뒤 런타임에 서로 다른 기능을 등록할 수 있다.

- Web Client → 페이지에 패널, 버튼 또는 통계 정보가 나타난다.

- Tool → 모델이 작업에 따라 도구 호출을 시작할 수 있다.

- Service → 다른 플러그인에서 사용하며, 사용자는 직접적인 진입점을 보지 못할 수 있다.

- Command → 사용자가 모델의 판단 없이 직접 명령을 실행할 수 있다.

이것들은 네 가지 배타적인 플러그인 유형이 아니라, 몇 가지 흔한 확장 위치다. 하나의 Plugin이 여러 기능을 동시에 등록할 수 있으며, ModLens는 Web Client와 Tool을 동시에 포함한다.

따라서 DSH Web UI는 설치 후 주로 페이지가 변화하는 것으로 나타나고, ModLens는 사용자가 붙여 넣은 이미지를 받아야 할 뿐만 아니라 modlens_read_image를 모델에 제공해야 한다. 둘이 DSH에 진입하는 방식은 같지만, 최종적인 사용 진입점은 다르다.

Preset은 플러그인 설치 사슬에 속하지 않는다

Tool이 DSH 런타임에 등록된 뒤, 모델이 현재 세션에서 그것을 볼 수 있는지는 이 Agent가 어떤 능력을 얻었는지에 따라 달라진다. 공식 아키텍처 문서는 Agent Preset을 서로 다른 세션 능력 집합을 조립하는 한 가지 방식으로 설명하며, 어떤 Agent가 사용하는 도구·Skill·규칙을 조합할 수 있다.

그래서 Preset은 npm 패키지, Bundle, Profile, Plugin의 설치 주 사슬에 두어서는 안 된다. 그것은 오히려 설치가 끝난 뒤의 능력 조합에 가깝다. 플러그인이 먼저 Tool을 런타임에 등록하고, 구체적인 세션이 자신의 능력 설정에 따라 그것을 사용한다.

이것은 또한 플러그인 목록이 "활성화됨"으로 표시된다고 해서, 반드시 현재 대화의 모델이 이미 그것을 호출할 수 있다는 뜻은 아닌 이유를 설명해 준다.

ModLens를 예로 들면, 한 번의 이미지 읽기는 어떻게 일어나는가?

사용자가 Web 페이지에서 오류 화면 캡처 한 장을 붙여 넣고 질문하면, Web Client가 이미지를 받아 이미지 경로와 질문을 DSH Agent에 넘긴다. DSH는 현재 질문과 사용 가능한 도구를 텍스트 모델에 넘기고, 모델이 이미지를 읽어야 한다고 판단하면 modlens_read_image를 호출한다.

ModLens는 다시 이미지를 이미 설정된 비전 엔진에 넘겨 OCR, 페이지 레이아웃, 의미 등 구조화된 근거를 얻는다. 근거가 DSH Agent에 반환된 뒤, 원래의 텍스트 모델이 분석을 이어가며 최종 답변을 구성한다.

이제 다시 llm, session, timer, DSH Web UI와 ModLens를 돌아보면, 기능은 완전히 다르지만 공통점은 이것이다. 모두 Cordis를 통해 로드되고, 런타임에 기능을 등록하며, 다른 컴포넌트와 협력하고, 각자의 생명주기에 따라 종료된다.

"모든 것이 플러그인"은 DSH의 조립 방식을 설명한다. 그것은 모든 플러그인에 버튼이 있다거나, 모든 플러그인을 채팅창에서 이름을 불러 호출할 수 있다는 뜻이 아니다.

AI의 힘을 빌려, 실제需求를 TaskDeck 플러그인으로 만들기

DSH의 플러그인 메커니즘을 이해하고 나면, 누구나 AI의 힘을 빌려 자신만의 플러그인을 개발할 수 있다고 생각한다.

마침, 나에게 딱 맞는痛点이 하나 있다. 나는 여러 개발과 조사 작업을 동시에 실행할 때, 어느 작업이 아직 실행 중이고 어느 것이 답변을 기다리고 있으며 어느 것이 이미 실패했는지 확인하려고 서로 다른 세션 사이를 자주 오가야 했다. 작업 수가 많아지면 주의력이 상태를 반복 확인하는 데 쓰인다.

그래서 나는 TaskDeck을 만들고 싶다. 그것은 완전한 프로젝트 관리 시스템이 아니라, DSH Web 페이지 안에 놓는 작업 상황판이다. 실행 중, 사용자 대기, 막힐 가능성, 이미 완료, 실패한 작업을 한데 모아 보여주어, 어떤 작업을 처리해야 하는지 페이지를 열면 바로 볼 수 있게 한다.

현재 이 버전의 TaskDeck은 이미 사이드바에서 열 수 있고, 프로젝트별로 작업을 필터링하며, 「기획 대기, 할 일, 진행 중, 완료, 실패」 다섯 열로 작업을 보여준다. 작업은 DSH 워크스페이스와 연결할 수 있고, 보드에서 실행을 시작하며, 해당 세션의 이벤트에 따라 생성 중, 도구 실행, 사용자 대기, 완료, 실패 등의 상태를 갱신한다.

상단의 상황 영역은 진행 중, 처리 대기, 차단 가능, 실패, 오늘 완료 수량을 집계한다. 작업 기록은 현재 브라우저 로컬에 저장된다. 요구사항 문서에서 계획한 ETA, 등급별 알림, 대기 기간 제안, 지능형 우선순위는 아직 현재 버전에 모두 반영되지 않았다.

먼저 요구사항을 확인하고, 그다음 AI에게 구현하게 하라

플러그인을 개발하는 일은 「나 대신 작업 칸반 보드를 하나 만들어줘」라는 한마디로 명확하게 설명할 수 있는 것이 아니다. 작업을 어떻게 정의할지, 상태는 어디서 오는지, 무엇을 차단이라고 하는지, 플러그인이 어떤 세션 이벤트를 읽어야 하는지, 이런 문제들이 확인되지 않으면 AI는 정적 카드만 있는 평범한 칸반 보드를 만들기 쉽다.

따라서 코딩을 시작하기 전에, 나는 먼저 AI와 요구사항을 거듭 확인하고 requirement.md 한 부로 정리했다. 당신도 같은 방식을 취할 수 있다. 먼저 AI가 질문을 통해 사용 시나리오, MVP, 데이터 출처, 권한 경계와 검수 기준을 명확히 쓰게 하고, 요구사항 문서를 확인한 뒤에 이를 Codex, Claude Code 등 로컬 프로젝트를 읽을 수 있는 코딩 Agent에게 넘기면 된다.

아래 이 프롬프트는 플러그인이 반드시 TaskDeck이어야 한다고 제한하지 않는다. 요구사항 문서, DSH 소스 코드, 플러그인 디렉터리와 대상 Profile의 경로만 바꾸면 자신의 플러그인을 개발하는 데 사용할 수 있다.

요구사항 문서와 로컬 DeepSeek Harness 소스 코드에 따라, 설치 가능하고 검증 가능하며 제거 가능한 플러그인을 구현하라. ​ 요구사항 문서: <requirement.md 절대 경로> DSH 소스 코드: <deepseek-harness 절대 경로> 플러그인 디렉터리: <출력 디렉터리 절대 경로> 대상 Profile: <예: web> ​ 요구 사항: ​ - 요구사항 문서에서 확인된 MVP만 구현한다. - 먼저 현재 DSH의 문서, 예제, 타입과 소스 코드를 읽고, 기억에 의존해 API를 추측하지 않는다. - 개발 단계에서는 플러그인 디렉터리만 수정하고, DSH 소스 코드를 수정하지 않으며 node_modules를 직접 편집하지도 않는다. - "설치 확인"을 받은 뒤에만 지정된 테스트 Profile을 수정할 수 있다. 다른 Profile과 기존 설정에 영향을 주지 않는다. - 요구사항이 모호하거나 확장점이 없으면 멈추고 나에게 확인한다. - 테스트 결과가 없으면 기능이 사용 가능하다고 주장하지 않는다. ​ 세 단계로 실행하라: ​ 1. 분석 필요한 Plugin, Web Client, Tool, Service 또는 Command를 확인하고, 실제 API, 파일 계획, 권한 위험과 검증 방법을 나열한다. 코드를 쓰지 말고, 내가 "개발 확인"이라고 답하기를 기다린다. ​ 2. 개발 "개발 확인"을 받으면 플러그인을 구현하고, 타입 검사, 테스트와 빌드를 단계적으로 실행하며, Bundle, 클라이언트 선언과 제거 정리 로직을 갖춘다. 빌드 완료 후 결과와 필요한 권한을 보고하고, 설치하지 말고 내가 "설치 확인"이라고 답하기를 기다린다. ​ 3. 검증 "설치 확인"을 받으면 테스트 Profile에 설치하고, --dump-config로 설정을 검사하며, DSH를 시작하고 요구사항 문서에 따라 검수한다. 마지막으로 사용 방법, 실제 테스트 결과, 알려진 제한과 제거 명령을 제시한다.

TaskDeck을 예로 들면, 최종 생성된 npm 패키지는 Bundle과 Web Client를 동시에 선언했다. Bundle은 그것이 web Profile에 들어가게 하고, Web Client는 사이드바 진입점, 작업 칸반 보드와 상태 정보를 페이지에 추가한다. 따라서 사용자가 보게 되는 것은 채팅창에서 TaskDeck이라는 이름의 Tool을 호출하는 것이 아니라, 새로운 UI 한 조각이다.

TaskDeck은 현재 작업 실행, 상태 인식과 집중 표시만 구현했다. ETA, 시스템 알림과 대기 제안은 여전히 후속 계획이다. DSH도 여전히 빠르게 반복 개발되고 있으므로, 개발 시에는 로컬 버전의 소스 코드와 타입을 읽고, 우선 독립적인 테스트 Profile에 설치해야 한다.

플러그인 목록은 앱 스토어도 아니고 Tool 메뉴도 아니다. 플러그인이 어떻게 Profile에 들어가는지, 무엇을 등록했는지, 사용자가 최종적으로 어디에서 그것을 사용하는지 분명히 보면, 「모든 것이 플러그인」은 더 이상 디자인 구호에 그치지 않는다.

저는 자이샤오녠(宅小年)입니다. 다음 편에서 다시 만나요!

위챗 공식 계정 「宅小年」을 팔로우하고 더 많은 공유 글을 읽어보세요

宅小年

Java

51

글

155k

읽음

214

팬