DeepSeek Harness プラグイン設定:Config と Schemastery
greet ツールは挨拶文をコードにハードコーディングしているため、デプロイ環境ごとに変えたい場合はコードを変更する必要がある。
この章では、プラグインが cordis.yml から渡された設定を受け取れるようにし、「設定とコードの分離」を実現します。
Config 型と同名の schema をエクスポート
プラグインで Config インターフェースと同名の Schemastery schema をエクスポートします。
デフォルト値は schema のフィールドに直接記述します。
例
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 フィールドを追加します。
例
- 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 で制約を表現します。
例
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 に属し自動的にクリーンアップされるため、置き換え後も古いインスタンスの登録は残りません。
まとめと自己テスト
Config インターフェースと同名の schema をエクスポートし、デフォルト値は schema に記述します。設定はロード時に検証され、すべての調整可能なパラメータは設定に含めます。
その他の拡張1. なぜデフォルト値をコードではなく schema に記述するのですか?
2. 設定が不正な場合、何が起こりますか?
3. 「ハードコーディングなし」を判断する基準は何ですか?