01前提条件

始める前に、以下を確認してください：

• 公式 README の run-from-source の手順に従って deepseek-ai/deepseek-harness リポジトリをチェックアウトし、依存関係をインストール済みであること；
• 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 UI を起動します：

pnpm dsh web --patch ./scratch-plugin/cordis.yml
# http://127.0.0.1:3080 を開く

ターミナルには起動時にプラグインの読み込みログが表示されます。[hello-plugin] plugin loaded! が見えれば、プラグインの読み込みは成功です。ブラウザで http://127.0.0.1:3080 にアクセスし、UI が正常に起動していることを確認してください。

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 がまだ準備できていない可能性があります。依存関係を宣言することは、この種のタイミングの問題を解消する標準的な方法です。

083つのプラグイン形式

ここまでは関数形式を使ってきました。Harness はオブジェクト形式とクラス形式もサポートしています：

// オブジェクト形式：メタデータとロジックを1つのデフォルトエクスポートにまとめる
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トラブルシューティング

初めてプラグインを動かすときによく詰まる4つの問題を、次の順番で確認してください。

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