writing-opencode-plugins

OpenCode プラグインの作成

このスキルを使用して、本番品質の OpenCode プラグインを実装します。プラグイン API は進化しており、公開ドキュメントが遅れている場合があるため、リポジトリで公開されている型とランタイムを信頼できる情報源として扱ってください。

まず確認すること

1. どのランタイムが機能を担うかを判断します。
2. コードを書く前に、関連する公開型を読みます。
3. 同じ API を使用している、リポジトリ内の焦点を絞った例を探します。
4. 対象に特化した最小限のモジュールを実装します。
5. 担当パッケージ内で、読み込み、動作、失敗、クリーンアップをテストします。

必要な機能	プラグインの対象	インポート	設定
フック、ツール、認証、プロバイダー、モデルパラメーター、シェル環境	サーバー	@opencode-ai/plugin	opencode.json または自動検出される .opencode/plugins/*.{ts,js}
コマンド、キー割り当て、ルート、ダイアログ、スロット、テーマ、通知	TUI	@opencode-ai/plugin/tui	tui.json の明示的な plugin エントリー
両方	対象ごとに分けた2つのエントリーポイント	別々のファイルで両方をインポート	パッケージのエクスポートに ./server と ./tui を指定

同じモジュールから server と tui の両方をエクスポートしないでください。インタラクティブな TUI API の代わりに、サーバーイベントフックを使用しないでください。

現在の仕様を確認する

不慣れな動作を実装する前に、以下のファイルを読んでください。

• packages/plugin/src/index.ts：サーバープラグインとフックの信頼できる型定義です。
• packages/plugin/src/tool.ts：カスタムツールのスキーマ、コンテキスト、権限、メタデータ、添付ファイル、結果の型を定義しています。
• packages/plugin/src/tui.ts：TUI API とモジュール型の信頼できる定義です。
• packages/opencode/specs/tui-plugins.md：TUI の読み込み、パッケージ化、ライフサイクル、API の仕様を定義しています。
• packages/opencode/src/plugin/shared.ts：対象の検証、ID、エントリーポイントの解決を定義しています。
• packages/opencode/src/plugin/loader.ts：インストール、互換性、インポートの動作を定義しています。

これらの内容が例やウェブサイトのドキュメントと一致しない場合は、エクスポートされた型とランタイムの動作に従い、必要に応じて古くなったドキュメントを更新してください。

モジュールの構成を選ぶ

新しいサーバープラグインでは、明示的なモジュールオブジェクトを使用してください。

import type { Plugin, PluginModule } from '@opencode-ai/plugin';

const server: Plugin = async ({ client, directory }, options) => ({
	dispose: async () => {},
});

export default {
	id: 'acme.example',
	server,
} satisfies PluginModule & { id: string };

従来のサーバー専用ローカルプラグインでは、プラグイン関数を直接エクスポートできます。従来型のモジュールでは、個別の名前付きエクスポートがすべてプラグインとして扱われるため、無関係な定数をエクスポートしないでください。新しいコードでは、デフォルトのモジュールオブジェクトを使用してください。

TUI プラグインでは、常にデフォルトのモジュールオブジェクトを使用します。

/** @jsxImportSource @opentui/solid */
import type { TuiPlugin, TuiPluginModule } from '@opencode-ai/plugin/tui';

const tui: TuiPlugin = async (api) => {
	api.ui.toast({ message: 'Plugin loaded' });
};

export default {
	id: 'acme.example-tui',
	tui,
} satisfies TuiPluginModule & { id: string };

ファイルプラグインには、安定した空でない id が必要です。npm プラグインではパッケージ名から ID を導出できますが、名前空間付きの明示的な ID を指定すると、状態管理、診断、衝突処理が明確になります。

エンジニアリングのルール

• TypeScript を使用し、公開プラグイン型に対して satisfies で型を検証します。
• options を解析して検証します。options は未検証の Record<string, unknown> として渡されます。
• プラグイン ID、コマンド ID、ルート名、モード、スロット名、共有 KV キーには名前空間を使用します。
• process.cwd() ではなく、プラグインまたはツールのコンテキストから提供されるディレクトリを使用します。
• 長時間実行される処理やキャンセル可能な処理では、AbortSignal に対応します。
• 構造化されたサーバーログには、console.log ではなく client.app.log() を使用します。
• 影響の大きい処理や機密性の高いカスタムツール処理の前に、権限を要求します。
• 通知ではプライバシーを保護し、プロンプト、シークレット、パス、コマンド、未加工のエラーを公開しないでください。
• 必要なフックと UI リソースだけを登録します。特定のフックがある場合は、広範なイベント購読を避けてください。
• クリーンアップは、時間に上限を設け、冪等にし、一部だけ初期化された状態でも安全に実行できるようにします。
• 所有権の競合を解決するために、文書化されていない読み込み順序に依存しないでください。

テストのワークフロー

サーバープラグインのテストは、packages/opencode/test/plugin/ または担当するサブシステムに最も近い場所に配置します。TUI ランタイムのテストは packages/opencode/test/cli/tui/ に配置します。コンポーネントレベルの TUI テストは packages/tui に配置する場合があります。

少なくとも、以下をテストしてください。

• 正常な読み込みと、ターゲット／エントリーポイントの選択。
• 設定済みのオプションと、不正なオプション。
• 実装ロジックの重複ではなく、観測可能な動作。
• 中断、失敗、初期化が一部のみ完了した場合の動作。
• クリーンアップまたは破棄。
• 関連する場合は、ID または登録の重複。
• 公開時のローカルファイルおよび npm パッケージングの動作。

テストはパッケージディレクトリから実行し、リポジトリのルートからは実行しないでください。型チェックには、担当するパッケージで bun typecheck を実行してください。

レビューチェックリスト

• 機能が適切なサーバーまたは TUI ランタイムに配置されています。
• モジュールの形式とインポートパスがターゲットと一致しています。
• サーバーと TUI のエントリーポイントが分かれています。
• ID と永続キーが安定しており、名前空間で区分されています。
• オプションと外部データが検証されています。
• フックの出力を変更する際に、他のプラグインによる変更が保持されています。
• ツールがコンテキストディレクトリ、権限、メタデータ、中断を適切に扱っています。
• 意図的にグローバルにする場合を除き、TUI のキーバインドがモードに応じて制限されています。
• TUI のリソースとカスタム副作用が破棄されています。
• パッケージのエクスポート、engines.opencode、設定ターゲットが正しく設定されています。
• テストで動作とライフサイクルがカバーされています。

参考資料

• サーバープラグイン：フック、カスタムツール、ライフサイクル、使用例。
• TUI プラグイン：キーマップ、ルート、ダイアログ、スロット、状態、ライフサイクル。
• パッケージングとテスト：設定、パッケージのエクスポート、互換性、テストの配置場所。