Skip to main content
ツールと拡張機能

Plugins

options.plugins を使用して、ローカルプラグインディレクトリを現在のセッションに読み込みます。SDK は各ローカルプラグインを --plugin-dir <path> 起動パラメータに変換します。プラグインに含まれる commands、agents、skills、MCP servers はすべて今回のセッションの機能発見の対象になります。

ローカルプラグインの読み込み

import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'List the commands and agents contributed by the current plugins',
  options: {
    plugins: [
      { type: 'local', path: '/path/to/my-plugin' },
    ],
  },
});

const init = await q.initializationResult();
console.log(init.commands);
console.log(init.agents);
console.log(init.skills);

const plugins = await q.listPlugins();
console.log(plugins);
複数のローカルプラグインを同時に渡すことができ、その順序で複数回 --plugin-dir が出力されます。 
const q = query({
  options: {
    plugins: [
      { type: 'local', path: '/path/to/plugin-a' },
      { type: 'local', path: '/path/to/plugin-b' },
    ],
  },
});
💡 Python では query() は単発のメッセージストリームで、ハンドシェイク後に init レスポンスを照会できません。プラグインが提供するコマンド / agent / skill を読むには、QoderSDKClient を使って connect() 後に get_server_info() を呼ぶか、メッセージストリームで SystemMessage(subtype='init') を捕捉して message.data を自分で読んでください。完全な plugin inventory は client.list_plugins() で取得します。

プラグインディレクトリレイアウト

ローカルプラグインは通常以下を含むことができます： 
my-plugin/
  .qoder-plugin/plugin.json
  commands/
  agents/
  skills/
  .mcp.json
.qoder-plugin/plugin.json はプラグイン名、バージョン、説明を宣言するために使用します。その他のディレクトリはファイルタイプに応じて CLI が自動的にスキャンします。 SDK はパスが存在するか / 妥当かを検証しません。
  • 存在しない --plugin-dir パスは SDK モードではサイレントに無視され、セッションは正常に初期化されます。
  • 破損したフロントマター / .mcp.json は init をブロックしません。破損したコマンドは init レスポンスに表示されません。
  • plugin のロード失敗を明示的に診断したい場合、現時点では リロード後の error_count が唯一のフォールバックです。

プラグインが提供する slash commands

プラグイン内の commands/*.md は初期化結果に現れ、名前は <plugin>:<cmd> の修飾形式になります： 
const commands = await q.supportedCommands();
console.log(commands.map((cmd) => cmd.name));

プラグインが提供する agents

プラグイン内の agents/*.md は初期化結果に現れます。SDK はこのリストを直接取得する簡便メソッドを提供します： 
const agents = await q.supportedAgents();
console.log(agents.map((agent) => agent.name));

プラグインが提供する skills

プラグイン内の skills/<name>/SKILL.md はプラグイン修飾名（plugin:skill）で登録されます。options.skills でメインセッションでのコンテキスト可視性と呼び出しポリシーを制御できます：修飾名を渡して特定 skill を有効化、'all' で発見済みすべてを有効化、省略で CLI デフォルトポリシー。Skills ドキュメント を参照してください。

プラグインが提供する MCP servers

プラグイン内の .mcp.json は CLI が起動し、MCP 状態に組み込まれます： 
const servers = await q.mcpServerStatus();
console.log(servers);

インストール済み同名プラグインの一時的な上書き

options.plugins で読み込まれたローカルプラグインはセッションスコープです。現在のセッション内で既にインストールされているプラグインと同名の場合、ローカルプラグインが今回のセッションの機能発見で優先されます。この機能はプラグインの開発、デバッグ、段階的検証に適しています。 
const q = query({
  options: {
    // The local version only takes effect for this query session and does not
    // touch the user's global install state.
    plugins: [{ type: 'local', path: './my-plugin-dev' }],
  },
});

実行中の Plugins リロード

plugin ディレクトリが変わった場合、同じセッション内で reloadPlugins() / reload_plugins() を呼ぶと、CLI が plugin リソースを再スキャンします。 
const refreshed = await q.reloadPlugins();

console.log(refreshed.commands);
console.log(refreshed.agents);
console.log(refreshed.plugins);
console.log(refreshed.mcpServers);
console.log(refreshed.error_count);
典型的な用途：
  • プラグイン開発時に commands/*.md を追加・削除した後のリフレッシュ。
  • ローカルプラグインのインストールまたは更新後、ホストアプリケーションを再起動せずに反映。
  • ホスト UI でリロード後の commands、agents、plugins、MCP 状態を表示する必要がある場合。
注意：Python では reload_plugins() は QoderSDKClient（streaming）モードでのみ意味を持ちます。単発の query() ストリームにはランタイム制御チャンネルがありません。

Options クイックリファレンス

フィールド（TypeScript / Python）説明
plugins / pluginsローカル plugin ディレクトリをロード。{ type: 'local', path } が一般的
settings / settingsCLI に透過する settings。enabledPlugins、pluginConfigs などを含められる
settingSources / setting_sourcesCLI が読む settings ソースを制御
settings.enabledPlugins でプラグインの有効状態を制御し、settings.pluginConfigs で MCP server 置換などのプラグイン設定を提供します。

戻り値リファレンス

初期化結果

initializationResult()（TypeScript）/ client.get_server_info()（Python）は、セッションで発見された commands、agents、skills などの初期化リソースを返します。安定した plugin inventory フィールドは含まれません。完全な戻り値型は SDK References を参照してください。 
{
    "commands": [
        {"name": "plugin-a:greet", "description": "...", "argumentHint": "..."},
        ...
    ],
    "agents": [
        {"name": "plugin-a:helper", "description": "...", "model": "sonnet"},
        ...
    ],
    "skills": [
        {"name": "plugin-a:echo", "description": "...", "source": "plugin"},
        ...
    ],
    # Also includes models / account / output_style and other fields
}

プラグインの一覧

listPlugins(): Promise<PluginDetails[]>;
CLI の plugin 一覧と各 plugin のリソースサマリーを読み取ります。ホスト UI で plugin inventory を表示する場合は、初期化結果の plugins フィールドではなくこのメソッドを使ってください。 各項目は PluginDetails で、id、name、source、path、version、scope、enabled、canDisable と、skills、agents、mcpServers、commands、hooks に分類された resources の概要を含みます。

プラグインのリロード

reloadPlugins() / reload_plugins() の戻り値： 
type SDKControlReloadPluginsResponse = {
  commands: Array<{ name: string; description?: string; argumentHint?: string }>;
  agents: Array<{ name: string; description?: string }>;
  plugins: Array<{ name: string; path: string; source?: string }>;
  mcpServers: Array<Record<string, unknown>>;
  error_count: number;  // Number of plugins that failed to load in this reload
};

ベストプラクティス

  • 初期化リソースと plugin 一覧を区別する：発見済みの commands、agents、skills は初期化結果で表示し、plugin inventory は listPlugins() / list_plugins() で表示します。初期化結果の skills は発見リストであり、メインセッションの呼び出し可能セットではありません。
  • プラグイン開発時は options.plugins を使用：現在のセッションにのみ影響し、ユーザーのグローバルインストール状態を変更する必要がありません。
  • リロード前にユーザーへの通知を用意する：リロードは CLI にディスク再スキャンをさせ、利用可能リソースのリストが一時的に変わる可能性があります。UI も同期して更新するのが望ましいです。
  • エラー診断には error_count を確認：リロード後に error_count > 0 の場合はプラグインリソースの読み込みに失敗があることを示しており、そのソースをユーザーに表示すべきです。

現在の制限事項

  • 一部の qodercli バージョンでは、ローカル plugin の commands、agents、MCP は初期化結果に正常に現れる一方、plugin skills が発見リストに現れないことがあります。これは CLI 側の発見チェーンの問題です。
  • 現在の qodercli 実装では、存在しない --plugin-dir パスは SDK モードで黙って無視されます。plugin ロード失敗を明示的に診断するには、現時点ではリロード後の error_count が唯一の手段です。
  • リロードは SDK が公開するランタイム制御 API です。現在の CLI バージョンが this._plugins 関連の内部エラーを返す場合は、修正済みの qodercli にアップグレードしてください。
クイックスタート
基本概念
会話とセッション
ツールと拡張機能
制御と安全性
リファレンス