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

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 を使用して、ローカルプラグインディレクトリを現在の query セッションに読み込みます。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.plugins);
複数のローカルプラグインを同時に渡すことができます： 
const q = query({
  options: {
    plugins: [
      { type: 'local', path: '/path/to/plugin-a' },
      { type: 'local', path: '/path/to/plugin-b' },
    ],
  },
});

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

ローカルプラグインは通常以下を含むことができます： 
my-plugin/
  .qoder-plugin/plugin.json
  commands/
  agents/
  skills/
  .mcp.json
.qoder-plugin/plugin.json はプラグイン名、バージョン、説明を宣言するために使用します。その他のディレクトリはファイルタイプに応じて CLI が自動的にスキャンします。

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

プラグイン内の commands/*.md は初期化結果と supportedCommands() に表示されます。 
const commands = await q.supportedCommands();
console.log(commands.map((cmd) => cmd.name));

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

プラグイン内の agents/*.md は初期化結果と supportedAgents() に表示されます。 
const agents = await q.supportedAgents();
console.log(agents.map((agent) => agent.name));

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

プラグイン内の skills/*/SKILL.md はプラグイン修飾名（plugin:skill）で登録されます。メインセッションから呼び出せるようにするには、options.skills で明示的にリストする必要があります。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 リロード

プラグインディレクトリに変更があった場合、同じ query セッション内で reloadPlugins() を呼び出すことで、CLI にプラグインリソースを再スキャンさせることができます。 
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 状態を表示する必要がある場合。

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

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

​
戻り値リファレンス

​
initializationResult()

type SDKControlInitializeResponse = {
  commands?: Array<{ name: string; description?: string; argumentHint?: string }>;
  agents?: Array<{ name: string; description?: string; model?: string }>;
  skills?: Array<{ name: string; description?: string; source?: string }>;
  plugins?: Array<{ name: string; path: string; source?: string }>;
  // Also includes models, account, output_style and other fields
};

​
reloadPlugins()

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;
};

​
ベストプラクティス

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

​
現在の制限事項

  • 一部の qodercli バージョンでは、ローカルプラグインの commands、agents、MCP は初期化結果に正常に表示されますが、プラグイン skills が initializationResult().skills に表示されない場合があります。これは CLI 側の発見パスの問題です。
  • 現在の qodercli 実装では、存在しない --plugin-dir パスは SDK モードでサイレントに無視されます。プラグイン読み込み失敗を明示的に診断する必要がある場合、現在は reloadPlugins().error_count でフォールバックするしかありません。
  • reloadPlugins() は SDK が公開するランタイム制御 API です。現在の CLI バージョンが this._plugins 関連の内部エラーを返す場合は、修正済みの qodercli にアップグレードする必要があります。