メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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

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

from qoder_agent_sdk import QoderAgentOptions, QoderSDKClient

options = QoderAgentOptions(
    plugins=[
        {"type": "local", "path": "/path/to/my-plugin"},
    ],
)

async with QoderSDKClient(options) as client:
    info = await client.get_server_info()
    print(info.get("commands"))
    print(info.get("agents"))
    print(info.get("plugins"))
複数のローカルプラグインを同時に渡すことができ、その順序で複数回 --plugin-dir が出力されます。 
options = QoderAgentOptions(
    plugins=[
        {"type": "local", "path": "/path/to/plugin-a"},
        {"type": "local", "path": "/path/to/plugin-b"},
    ],
)
💡 query() は使い切りのメッセージストリームのため、ハンドシェイク後に init レスポンスを取得することはできません。プラグインが提供する command / agent / skill を読み取るには、QoderSDKClient を使用し、connect() の後に get_server_info() を呼び出すか、メッセージストリーム内で SystemMessage(subtype='init') を捕捉して自分で message.data を読み取ってください。

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

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

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

プラグイン内の commands/*.md は get_server_info()['commands'] に表示され、名前は <plugin>:<cmd> の修飾名形式で現れます。 
async with QoderSDKClient(options) as client:
    info = await client.get_server_info()
    for cmd in info.get("commands", []):
        print(cmd["name"], cmd.get("description"))

​
プラグインが提供する agents

プラグイン内の agents/*.md は get_server_info()['agents'] に表示されます。SDK は同期的な便利メソッドも提供しており、このリストを直接取得できます。 
async with QoderSDKClient(options) as client:
    for agent in client.supported_agents():
        print(agent["name"], agent.get("description"))

​
プラグインが提供する skills

プラグイン内の skills/<name>/SKILL.md はプラグイン修飾名（plugin:skill）で登録されます。メインセッションから呼び出せるようにするには、options.skills で明示的にリストする必要があります。Skills ドキュメント を参照してください。

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

プラグイン内の .mcp.json は CLI によって起動され、MCP 状態に組み込まれます。get_mcp_status() で読み取ることができます。 
async with QoderSDKClient(options) as client:
    status = await client.get_mcp_status()
    for server in status["mcpServers"]:
        print(server["name"], server["status"])

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

options.plugins で読み込まれたローカルプラグインはセッションスコープです。現在のセッション内で既にインストールされているプラグインと同名の場合、ローカルプラグインが今回のセッションの機能発見で優先されます。この機能はプラグインの開発、デバッグ、段階的検証に適しています。 
options = QoderAgentOptions(
    # ローカル版はこの query セッション内でのみ有効で、ユーザーのグローバルインストール状態は変更しません
    plugins=[{"type": "local", "path": "./my-plugin-dev"}],
)

​
実行中のプラグインリロード

プラグインディレクトリに変更があった場合、同じ QoderSDKClient セッション内で reload_plugins() を呼び出すことで、CLI にプラグインリソースを再スキャンさせることができます。 
async with QoderSDKClient(options) as client:
    refreshed = await client.reload_plugins()

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

​
Options クイックリファレンス

フィールド型説明
pluginslist[SdkPluginConfig]ローカルプラグインディレクトリを読み込み。現在は {"type": "local", "path": ...} がよく使用されます
settingsstr | Path | dict[str, Any] | NoneCLI に渡す settings。enabledPlugins、pluginConfigs などのフィールドを含むことができます
setting_sourceslist[Literal["user", "project", "local"]] | NoneCLI がどの settings ソースを読み込むかを制御
settings.enabledPlugins、settings.pluginConfigs、settings.allowedChannelPlugins、settings.strictPluginOnlyCustomization などのエンタープライズポリシーフィールドは SDK 型として透過的に渡されますが、実際のパスは具体的な CLI バージョンに依存します。使用前にご自身の環境で検証してください。

​
戻り値リファレンス

​
client.get_server_info() と SystemMessage(subtype='init').data

{
    "commands": [
        {"name": "plugin-a:greet", "description": "...", "argumentHint": "..."},
        ...
    ],
    "agents": [
        {"name": "plugin-a:helper", "description": "...", "model": "sonnet"},
        ...
    ],
    "skills": [
        {"name": "plugin-a:echo", "description": "...", "source": "plugin"},
        ...
    ],
    "plugins": [
        {"name": "plugin-a", "path": "/path/to/plugin-a", "source": "local"},
        ...
    ],
    # models / account / output_style などのフィールドも含まれます
}

​
client.reload_plugins()

ReloadPluginsResponse を返します。 
{
    "commands": list[Any],
    "agents": list[Any],
    "plugins": list[PluginInfo],            # {"name": str, "path": str, "source": str?}
    "mcpServers": list[McpServerStatus],    # mcp.md の McpServerStatus を参照
    "error_count": int,                     # 今回の reload で読み込みに失敗したプラグイン数
}

​
ベストプラクティス

  • ホスト UI ではまず get_server_info() を読み取る：commands、agents、skills、plugins を表示するための安定したエントリポイントです。使い切りの query() でこのデータを取得したい場合は QoderSDKClient に切り替えるか、メッセージストリーム内で SystemMessage(subtype='init').data を読み取ってください。
  • プラグイン開発時は options.plugins を使用：現在のセッションにのみ影響し、ユーザーのグローバルインストール状態を変更する必要がありません。
  • リロード前にユーザープロンプトを準備：reload_plugins() は CLI にディスクの再スキャンをトリガーし、利用可能なリソースリストが一時的に変わる可能性があるため、UI も同期的に更新することを推奨します。
  • エラー診断には error_count を確認：リロード後に error_count > 0 の場合はプラグインリソースの読み込みに失敗があることを示しており、そのソースをユーザーに表示すべきです。

​
現在の制限事項

  • 一部の qodercli バージョンでは、ローカルプラグインの commands、agents、MCP は初期化結果に正常に表示されますが、プラグイン skills が get_server_info()['skills'] に表示されない場合があります。これは CLI 側の発見パスの問題です。
  • 現在の qodercli 実装では、存在しない --plugin-dir パスは SDK モードでサイレントに無視されます。プラグイン読み込み失敗を明示的に診断する必要がある場合、現在は reload_plugins().error_count でフォールバックするしかありません。
  • reload_plugins() は QoderSDKClient が公開するランタイム制御 API です。現在の CLI バージョンが this._plugins 関連の内部エラーを返す場合は、修正済みの qodercli にアップグレードする必要があります。
  • settings.strictPluginOnlyCustomization、settings.allowedChannelPlugins、settings.pluginConfigs.<pid>.options のテンプレート置換はすべて dict として透過的に渡されるフィールドであり、SDK は解析しません。実際に効くかどうかは CLI バージョンに完全に依存します。