DeepSeek Harness プラグイン設定:Config と Schemastery

greet ツールは挨拶文をコードにハードコーディングしているため、デプロイ環境ごとに変えたい場合はコードを変更する必要がある。

この章では、プラグインが cordis.yml から渡された設定を受け取れるようにし、「設定とコードの分離」を実現します。


Config 型と同名の schema をエクスポート

プラグインで Config インターフェースと同名の Schemastery schema をエクスポートします。

デフォルト値は schema のフィールドに直接記述します。

例

// ファイルパス:scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'my-plugin'

// Config インターフェース:プラグインが受け付ける設定項目を定義
export interface Config {
  greeting: string    // 挨拶文
  maxRetries: number  // 最大再試行回数
  verbose?: boolean   // 詳細ログを出力するかどうか(オプション)
}

// 同名の Config schema:デフォルト値はここに記述
export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
  verbose: Schema.boolean().default(false),
})

// apply の第 2 引数は検証後の設定
export function apply(ctx: Context, config: Config) {
  // 出力されるのはユーザーが渡した値または schema のデフォルト値
  console.log(config.greeting)
}

インターフェースは TypeScript の型を提供し、schema は実行時バリデーションとデフォルト値を提供します。

両者を同名にするのは Cordis の規約です。

通常のオブジェクトを Config としてエクスポートしないでください。

それは Cordis が要求する Standard Schema インターフェースを満たしていません。


cordis.yml で設定を渡す

新しく挿入したローカルプラグインの行に config フィールドを追加します。

例

# ファイルパス:scratch-plugin/cordis.yml
- insert
:
    - id
: hello
      # プラグインパスは絶対パスである必要があります(第 7 回参照)
      name
: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
      config
:
        greeting
: 'Hi there, サンプル!'
        maxRetries
: 5

プラグインのロード時、Cordis はエクスポートされた schema を使用して設定を検証し、提供されていないフィールドにはデフォルト値を入力します。

上記の設定では verbose を記述していないため、schema のデフォルト値 false が使用されます。


Schema バリデーション

より厳密な検証が必要な場合は、Schemastery で制約を表現します。

例

// ファイルパス:scratch-plugin/src/validated-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'validated-plugin'

export interface Config {
  apiKey: string                 // 必須
  timeout: number                // タイムアウトのミリ秒数
  mode: 'fast' | 'accurate'      // この 2 つの値のいずれかのみ
}

export const Config = Schema.object({
  apiKey: Schema.string().required(),
  timeout: Schema.number().default(30000),
  mode: Schema.union(['fast', 'accurate']).default('fast'),
})

export function apply(ctx: Context, config: Config) {
  // config は検証済みで、型安全
}

Schema はプラグインのロード時にバリデーションを実行します。

設定が不正な場合、プラグインはロードに失敗し、明確なエラーメッセージが表示されます。


設計原則:ハードコーディングなしの調整可能パラメータ

Harness の規約では、デプロイ環境によって異なる値を必要とする可能性があるパラメータは、すべて設定フィールドとして定義する必要があります。

誤った書き方と正しい書き方

// 誤り:タイムアウト時間をハードコーディングしている
const TIMEOUT = 30000

// 正しい:設定フィールドとして定義し、デフォルト値は schema が提供する
export interface Config {
  timeoutMs: number  // デフォルト 30000
}

判断基準を一言で言うと、コードを変更せずに cordis.yml でこの値を変更できるかどうかです。

できれば合格の調整可能なパラメータです。できなければ、設定フィールドに昇格させる必要があります。

ハードコーディング本来調整可能であるべき値をコードに固定で書き込むことです。

これにより「設定の変更」が「コードの変更と再デプロイ」になり、本番障害の一般的な原因となります。


設定エラーは明確に通知する

schema に自己完結的な制約を表現し、無効な設定がプラグインのロード時に失敗するようにします。

サービスや登録済みリソースへの参照には依存性注入が必要です。この規約はサービスのチュートリアルで紹介されます。


HMR との連携:設定のホットリプレース

設定の変更はプラグインのホットリプレース(HMR)を引き起こします。

cordis.yml でプラグインの config を変更すると、フレームワークは古いインスタンスをアンロードし、新しいインスタンスをロードします。

登録はすべて effect に属し自動的にクリーンアップされるため、置き換え後も古いインスタンスの登録は残りません。

配置校验与 HMR 流程


まとめと自己テスト

Config インターフェースと同名の schema をエクスポートし、デフォルト値は schema に記述します。設定はロード時に検証され、すべての調整可能なパラメータは設定に含めます。

1. なぜデフォルト値をコードではなく schema に記述するのですか?

2. 設定が不正な場合、何が起こりますか?

3. 「ハードコーディングなし」を判断する基準は何ですか?

その他の拡張