01사전 준비

시작하기 전에 다음을 확인하세요:

• 공식 README의 run-from-source 절차에 따라 deepseek-ai/deepseek-harness 저장소를 checkout하고 의존성을 설치했습니다;
• pnpm 사용 가능 — Harness가 의존성과 시작 명령을 관리하는 데 사용합니다;
• TypeScript를 작성할 수 있는 에디터.

02플러그인 프로젝트 생성

저장소 루트에 scratch-plugin 디렉터리를 만들고, 플러그인 코드는 src 아래에 둡니다:

cd /path/to/deepseek-harness
mkdir -p scratch-plugin/src

최종 구조는 다음과 같으며, 이 튜토리얼의 모든 파일이 여기에 들어갑니다:

scratch-plugin/
├── cordis.yml
└── src/
    └── my-plugin.ts

03첫 플러그인 작성

scratch-plugin/src/my-plugin.ts를 만듭니다:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

플러그인은 본질적으로 apply 함수를 내보내는 TypeScript 모듈입니다. 프레임워크는 플러그인을 로드할 때 apply를 호출하고 ctx 컨텍스트를 전달합니다. 플러그인과 Harness의 모든 상호작용이 이것을 통해 이루어집니다. name은 플러그인의 고유 식별자로, 로그와 의존성 관리에 사용됩니다.

04플러그인 등록

Harness는 아직 이 파일의 존재를 모릅니다. patch 설정으로 등록해야 합니다. 먼저 저장소 루트에서 pwd를 실행해 절대 경로를 얻은 뒤, scratch-plugin/cordis.yml을 만듭니다:

- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

05로드하고 확인하기

--patch로 방금 작성한 설정을 가리키고 Harness Web 인터페이스를 시작합니다:

pnpm dsh web --patch ./scratch-plugin/cordis.yml
# http://127.0.0.1:3080 열기

터미널 시작 시 플러그인 로드 로그가 출력됩니다. [hello-plugin] plugin loaded!가 보이면 플러그인이 성공적으로 로드된 것입니다. 브라우저에서 http://127.0.0.1:3080에 접속하면 인터페이스가 정상적으로 시작되었는지 확인할 수 있습니다.

06라이프사이클과 자동 정리

플러그인이 자원(타이머, 리스너, 연결)을 가지고 있다면 언로드 시 해제해야 합니다. ctx.effect는 함수를 받고, 그 반환값이 정리 함수가 되어 플러그인 언로드 시 실행됩니다:

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  const timer = setInterval(() => {
    console.log('[hello-plugin] heartbeat')
  }, 5000)

  // 반환된 정리 함수는 플러그인 언로드 시 실행됩니다
  ctx.effect(() => {
    return () => clearInterval(timer)
  })
}

더 나아가, ctx로 등록한 리스너, 타이머 등은 프레임워크가 언로드 시 자동으로 정리해 주므로 직접 해제 코드를 작성할 필요가 없습니다. ctx.effect는 ctx를 거치지 않고 직접 만든 자원을 관리할 때 사용합니다.

07의존성 주입

플러그인은 Harness의 내장 서비스(예: 도구 서비스 tools)가 필요할 때가 많습니다. inject로 의존성을 선언하면, 프레임워크는 이 서비스들이 준비될 때까지 기다렸다가 플러그인을 로드합니다:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  // 여기서는 tools 서비스가 준비되어 안전하게 호출할 수 있습니다
  ctx.tools.register(/* ... */)
}

inject가 없으면 플러그인이 즉시 로드되며, 이때 ctx.tools에 접근하면 아직 준비되지 않은 서비스를 받을 수 있습니다. 의존성을 선언하는 것이 이런 타이밍 문제를 없애는 표준적인 방법입니다.

08세 가지 플러그인 형태

지금까지는 함수 형태만 사용했습니다. Harness는 객체 형태와 클래스 형태도 지원합니다:

// 객체 형태: 메타데이터와 로직을 하나의 기본 내보내기로 모음
export default {
  name: 'hello-plugin',
  inject: ['tools'],
  apply(ctx: Context) {
    console.log('[hello-plugin] loaded!')
  },
}

// 클래스 형태: 다른 플러그인에 서비스를 제공할 때 사용
import { Service } from '@deepseek-ai/cordis'

export default class MyService extends Service {
  static inject = ['tools']

  constructor(ctx: Context) {
    super(ctx, 'myService')
  }
}

09문제 해결

첫 플러그인 실행은 보통 네 가지 문제 중 하나에서 막힙니다. 아래 순서대로 하나씩 확인하세요.

cd /path/to/deepseek-harness
pwd
# 출력 예: /Users/you/code/deepseek-harness
# 그 뒤에 scratch-plugin/src/my-plugin.ts를 붙입니다

lsof -i :3080

pnpm dsh web --patch ./scratch-plugin/cordis.yml