DeepSeek Harness サービスと依存:Service 基底クラスと型宣言

前のいくつかの章では、ctx.tools、ctx.llm、ctx.agents といった組み込みサービスを使ってきました。

この章では、サービス提供側の視点から、どのようにService 基底クラスを使って自分で名前付きサービスを提供し、消費者側が完全な型ヒントを得られるようにするかを見ていきます。


サービスとは

Harness では、tools、llm、agents はすべてサービスです。

サービスは ctx にマウントされた名前付き機能であり、任意のプラグインがサービスを提供し、他のプラグインが利用できるようにします。

サービス:プラグインが他のプラグインに公開する機能。

これは安定した ctx.<key>(ctx.tools、ctx.llm、ctx.sessions など)を占有し、他のプラグインは具体的な実装をインポートするのではなく、キーによってサービスを検索します。

例えば、ctx.tools はツールランタイムサービス、ctx.llm は大規模モデルサービス、ctx.agents はエージェントサービスです。

組み込みサービスのサービス名、公開メソッド、ソースコードの場所は、リポジトリによって各サービスのサブシステムページに自動生成されます。プラグイン開発時は、これらの生成されたブロックとサービスの TypeScript インターフェースを基準にし、手書きの静的サービスリストに依存しないでください。


サービスの使用:inject 宣言

既存のサービスを使用するには、プラグイン内で inject を宣言します。

フレームワークが保証します:apply 実行時には、inject で宣言されたサービスはすべて準備完了しています。

例

// ファイルパス:scratch-plugin/src/use-tools.ts
// tools サービスへの依存を宣言
export const inject = ['tools']

export function apply(ctx: Context) {
  // ctx.tools は必ず存在し、準備完了している
  ctx.tools.register(/* ... */)
}

サービスがまだ準備できていない場合、プラグインは待機し、apply は実行されません。


サービスの提供:Service 基底クラス

Service 基底クラスからサブクラスを派生し、コンストラクタ内でsuper(ctx, 'サービス名')を呼び出して名前付きサービスを登録します。

例

// ファイルパス:scratch-plugin/src/metrics-service.ts
import { Service, type Context } from '@deepseek-ai/cordis'

// サービスも他のサービスに依存でき、静的 inject で宣言する
export default class MetricsService extends Service {
  static inject = ['llm']  // このサービスは llm サービスが先に準備完了している必要がある

  constructor(ctx: Context) {
    // 2番目の引数 'metrics' がサービス名で、ctx.metrics にマウントされる
    super(ctx, 'metrics')
  }

  // 外部に公開するサービスメソッド
  record(event: string, value: number) {
    // ここでメトリクスを1件記録する。例:ツール呼び出し回数
    // 実際の実装ではメトリクスバックエンドに書き込むが、ここでは省略
  }
}

このプラグインをロードすると、消費者は ctx.metrics を通じてアクセスできます。

例

// ファイルパス:scratch-plugin/src/use-metrics.ts
// 消費者が metrics サービスへの依存を宣言
export const inject = ['metrics']

export function apply(ctx: Context) {
  // サービスメソッドを呼び出す:ツール呼び出しを1回記録
  ctx.metrics.record('サンプル_tool_call', 1)
}

型宣言:declare module マージ

TypeScript の宣言マージを使用して、ctx.metrics が正しい型を持つようにします。

これにより、コード作成時に自動補完が効き、コンパイル時にサービス名のスペルミスも検出できます。

例

// ファイルパス:scratch-plugin/src/metrics-service.ts
import { Service, type Context } from '@deepseek-ai/cordis'

// 宣言マージ:TypeScript に Context に metrics フィールドがあることを伝える
declare module '@deepseek-ai/cordis' {
  interface Context {
    metrics: MetricsService
  }
}

export default class MetricsService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'metrics')
  }

  record(event: string, value: number) {
    /* 実装省略 */
  }
}

declare module による宣言マージは、TypeScript が既存のモジュールに型を補完する標準的な方法です。

ここでは ctx.metrics の型と実装を同じファイルに記述し、両者がずれないようにしています。


必須依存とオプション依存

サービスの依存関係には、必須とオプションの2種類があります。

必須依存は inject で宣言し、サービスが存在しない場合、プラグインはまったくロードされません。

オプション依存は inject を省略し、使用箇所でctx.get()ctx.get() を使って照会すると、undefined が返る可能性があります。

例

// ファイルパス:scratch-plugin/src/optional-dep.ts
// 必須依存:サービスが存在しない場合、プラグインはロードされない
export const inject = ['tools']

// オプション依存:inject を省略し、使用箇所で ctx.get() を使って照会する
export function apply(ctx: Context) {
  // ctx.get('metrics') は undefined を返す可能性があるため、オプショナルチェーンで安全に呼び出す
  const metrics = ctx.get('metrics')
  metrics?.record('サンプル_plugin_loaded', 1)
}
依存の種類書き方サービスが存在しないときの動作適用シーン
必須依存export const inject = ['tools']プラグインはロードされず、PENDING のままそのサービスがないと正常に動作しない
オプション依存inject を省略し、ctx.get('metrics') で照会するプラグインは通常どおりロードされ、ctx.get() は undefined を返すサービスはあってもなくてもよく、存在しない場合も正常に動作する必要がある

いつオプション依存を使うのか?サービスがなくてもよく、それが存在しない場合でもプラグインが正常に動作する必要があるときです。


サービスが消えたときの動作

アプリケーションの実行中に必須サービスが消えた場合(例えば、その提供元がアンロードされた場合)、2つのことが起こります:

  1. それに依存するプラグインは自動的に dispose(リソース解放)されます。
  2. サービスが再び現れると、プラグインは自動的に再ロードされます。

これにより、プラグインが存在しなくなったサービスを呼び出すのを防げます。


まとめと自己テスト

Service サブクラスは super(ctx, '名前') で名前付きサービスを提供し、declare module の宣言マージで型を補完し、inject で必須依存を宣言し、ctx.get() でオプション依存を照会します。

自己テストしてみましょう:

  1. サービスは ctx 上でどのような形で存在しますか?サービス名はどのパラメータで決まりますか?
  2. ctx.metrics に型ヒントを持たせるにはどうすればよいですか?
  3. 必須依存とオプション依存のコードの書き方の違いは何ですか?
その他の拡張