> ## 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.

# Plugins

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

<div id="ローカルプラグインの読み込み" />

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

```typescript theme={null}
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);
```

複数のローカルプラグインを同時に渡すことができます：

```typescript theme={null}
const q = query({
  options: {
    plugins: [
      { type: 'local', path: '/path/to/plugin-a' },
      { type: 'local', path: '/path/to/plugin-b' },
    ],
  },
});
```

***

<div id="プラグインディレクトリレイアウト" />

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

ローカルプラグインは通常以下を含むことができます：

```
my-plugin/
  .qoder-plugin/plugin.json
  commands/
  agents/
  skills/
  .mcp.json
```

`.qoder-plugin/plugin.json` はプラグイン名、バージョン、説明を宣言するために使用します。その他のディレクトリはファイルタイプに応じて CLI が自動的にスキャンします。

***

<div id="プラグインが提供する-slash-commands" />

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

プラグイン内の `commands/*.md` は初期化結果と `supportedCommands()` に表示されます。

```typescript theme={null}
const commands = await q.supportedCommands();
console.log(commands.map((cmd) => cmd.name));
```

<div id="プラグインが提供する-agents" />

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

プラグイン内の `agents/*.md` は初期化結果と `supportedAgents()` に表示されます。

```typescript theme={null}
const agents = await q.supportedAgents();
console.log(agents.map((agent) => agent.name));
```

<div id="プラグインが提供する-skills" />

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

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

<div id="プラグインが提供する-mcp-servers" />

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

プラグイン内の `.mcp.json` は CLI によって起動され、MCP 状態に組み込まれます。

```typescript theme={null}
const servers = await q.mcpServerStatus();
console.log(servers);
```

***

<div id="インストール済み同名プラグインの一時的な上書き" />

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

`options.plugins` で読み込まれたローカルプラグインはセッションスコープです。現在のセッション内で既にインストールされているプラグインと同名の場合、ローカルプラグインが今回のセッションの機能発見で優先されます。この機能はプラグインの開発、デバッグ、段階的検証に適しています。

```typescript theme={null}
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' }],
  },
});
```

***

<div id="実行中の-plugins-リロード" />

## 実行中の Plugins リロード

プラグインディレクトリに変更があった場合、同じ query セッション内で `reloadPlugins()` を呼び出すことで、CLI にプラグインリソースを再スキャンさせることができます。

```typescript theme={null}
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 状態を表示する必要がある場合。

***

<div id="options-クイックリファレンス" />

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

| フィールド            | 型                                    | 説明                                                                   |
| ---------------- | ------------------------------------ | -------------------------------------------------------------------- |
| `plugins`        | `SdkPluginConfig[]`                  | ローカルプラグインディレクトリを読み込み。現在は `{ type: 'local', path }` がよく使用されます         |
| `settings`       | `string \| Settings`                 | CLI に渡す settings。`enabledPlugins`、`pluginConfigs` などのフィールドを含むことができます |
| `settingSources` | `('user' \| 'project' \| 'local')[]` | CLI がどの settings ソースを読み込むかを制御                                        |

`settings.enabledPlugins`、`settings.pluginConfigs`、`settings.allowedChannelPlugins`、`settings.strictPluginOnlyCustomization` などのエンタープライズポリシーフィールドは SDK 型として透過的に渡されますが、実際のパスは具体的な CLI バージョンに依存します。使用前にご自身の環境で検証してください。

***

<div id="戻り値リファレンス" />

## 戻り値リファレンス

<div id="initializationresult" />

### `initializationResult()`

```typescript theme={null}
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
};
```

<div id="reloadplugins" />

### `reloadPlugins()`

```typescript theme={null}
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;
};
```

***

<div id="ベストプラクティス" />

## ベストプラクティス

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

***

<div id="現在の制限事項" />

## 現在の制限事項

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