# SDK と CLI の互換性 このドキュメントでは、Copilot CLI の機能のうち、SDK を介して利用できるものと CLI 専用のものを説明します。 ## Overview Copilot SDK は、JSON-RPC プロトコルを使用して CLI と通信します。 SDK で使用できるようにするには、このプロトコルを使用して機能を明示的に公開する必要があります。 多くの対話型 CLI 機能はターミナル固有であり、プログラムでは使用できません。 ## 機能の比較 ### ✅ SDK で使用可能 | 特徴 | SDK メソッド | メモ | | ----------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------- | | **セッション管理** | | | | | | | | セッションの作成 | `createSession()` | 完全な構成のサポート | | セッションを再開する | `resumeSession()` | 無限のセッション ワークスペース | | セッションを切断する | `disconnect()` | メモリ内リソースを解放する | | セッション *を破棄する (非推奨)* | `destroy()` | 代わりに `disconnect()` を使用してください | | セッションの削除 | `deleteSession()` | ストレージから削除する | | セッションを一覧表示する | `listSessions()` | すべての保存済みセッション | | 最後のセッションを取得する | `getLastSessionId()` | すばやく再開 | | フォアグラウンド セッションを取得する | `getForegroundSessionId()` | 複数セッションの調整 | | フォアグラウンド セッションを設定する | `setForegroundSessionId()` | 複数セッションの調整 | | **Messaging** | | | | | | | | メッセージの送信 | `send()` | 添付ファイルあり | | 送信して待機する | `sendAndWait()` | 完了するまでブロックする | | ステアリング (イミディエイト モード) | `send({ mode: "immediate" })` | 中止せずに途中ターンを挿入する | | キューイング (エンキュー モード) | `send({ mode: "enqueue" })` | 順次処理用のバッファー (既定) | | 添付ファイル | `send({ attachments: [{ type: "file", path }] })` | 画像の自動エンコードとサイズ変更 | | ディレクトリの添付ファイル | `send({ attachments: [{ type: "directory", path }] })` | ディレクトリ コンテキストをアタッチする | | 履歴を取得する | `getEvents()` | すべてのセッションイベント | | アボート | `abort()` | 進行中のリクエストをキャンセルする | | **ツール** | | | | | | | | カスタム ツールを登録する | `registerTools()` | 完全な JSON スキーマのサポート | | ツールのアクセス許可の制御 | | | | `onPreToolUse` フック | 許可/拒否/要求 | | | ツールの結果の変更 | | | | `onPostToolUse` フック | 結果の変換 | | | 使用可能なツールまたは除外されたツール | | | | `availableTools`、`excludedTools` 設定 | フィルター ツール | | | **Models** | | | | | | | | モデルを一覧表示する | `listModels()` | 機能、課金、ポリシー | | モデルの設定 (作成時) | | | | `model` セッション構成 | セッションごと | | | モデルの切り替え (セッション中) | `session.setModel()` | また、次を介して `session.rpc.model.switchTo()` | | 現在のモデルを取得する | `session.rpc.model.getCurrent()` | アクティブ なモデルのクエリを実行する | | 推論作業 | | | | `reasoningEffort` 設定 | サポートされているモデルの場合 | | | **エージェント モード** | | | | | | | | 現在のモードを取得する | `session.rpc.mode.get()` | 現在のモードを返します。 | | モードの設定 | `session.rpc.mode.set()` | モードを切り替える | | **プラン管理** | | | | | | | | プランを読む | `session.rpc.plan.read()` | plan.mdのコンテンツとパスを取得する | | プランの更新 | `session.rpc.plan.update()` | plan.md コンテンツを書き込む | | 計画の削除 | `session.rpc.plan.delete()` | plan.md の削除 | | **ワークスペース ファイル** | | | | | | | | ワークスペース ファイルを一覧表示する | `session.rpc.workspace.listFiles()` | セッション ワークスペース内のファイル | | ワークスペース ファイルの読み取り | `session.rpc.workspace.readFile()` | ファイルの内容を読み取る | | ワークスペース ファイルを作成する | `session.rpc.workspace.createFile()` | ワークスペースにファイルを作成する | | **Authentication** | | | | | | | | 認証の状態を取得する | `getAuthStatus()` | ログイン状態を確認する | | トークンを使用する | | | | `gitHubToken` オプション | プログラムによる認証 | | | **接続** | | | | | | | | Ping | `client.ping()` | サーバー タイムスタンプを使用した正常性チェック | | サーバーの状態を取得する | `client.getStatus()` | プロトコルのバージョンとサーバー情報 | | **MCP サーバー** | | | | | | | | ローカル/stdio サーバー | | | | `mcpServers` 設定 | プロセスを生成する | | | リモート HTTP/SSE | | | | `mcpServers` 設定 | サービスへの接続 | | | **フック** | | | | | | | | ツール使用前 | `onPreToolUse` | 権限、引数を変更 | | ツール使用後（成功） | `onPostToolUse` | 結果を変更する | | ツール使用後（失敗） | `onPostToolUseFailure` | 失敗したツール呼び出しを観察し、再試行ガイダンスを挿入する | | ユーザー プロンプト | `onUserPromptSubmitted` | プロンプトを変更する | | セッションの開始/終了 | | | | `onSessionStart`、`onSessionEnd` | ソース/理由を含むライフサイクル | | | エラー処理 | `onErrorOccurred` | カスタム処理 | | **イベント** | | | | | | | | すべてのセッションイベント | | | | `on()`、`once()` | 40 以上のイベントの種類 | | | ストリーミング | `streaming: true` | デルタ イベント | | **セッション構成** | | | | | | | | カスタム エージェント | | | | `customAgents` 設定 | 特殊なエージェントを定義する | | | システム メッセージ | | | | `systemMessage` 設定 | 追加または置換 | | | カスタム プロバイダー | | | | `provider` 設定 | BYOK のサポート | | | 無限セッション | | | | `infiniteSessions` 設定 | 自動圧縮 | | | 権限ハンドラー | `onPermissionRequest` | 要求の承認/拒否 | | ユーザー入力ハンドラー | `onUserInputRequest` | ask\_userの処理 | | スキル | | | | `skillDirectories` 設定 | カスタム スキル | | | 無効なスキル | | | | `disabledSkills` 設定 | 特定のスキルを無効にする | | | 設定ディレクトリ | | | | `configDir` 設定 | デフォルト設定の場所を上書きする | | | クライアント名 | | | | `clientName` 設定 | User-Agent でアプリを識別する | | | 作業ディレクトリ | | | | `workingDirectory` 設定 | セッション cwd を設定する | | | **試験段階** | | | | | | | | エージェント管理 | `session.rpc.agent.*` | 現在のエージェントを一覧表示、選択、選択解除、取得する | | フリートモード | `session.rpc.fleet.start()` | 並列サブエージェントの実行。[フリートモード](/ja/copilot/how-tos/copilot-sdk/features/fleet-mode) を参照してください | | 手動圧縮 | `session.rpc.history.compact()` | オンデマンドで圧縮をトリガーする | | 履歴の切り捨て | `session.rpc.history.truncate()` | ある時点以降のイベントを削除する | | セッションのフォーク | `server.rpc.sessions.fork()` | 履歴内のポイントでセッションをフォークする | ### ❌ SDK では使用できません (CLI のみ) | 特徴 | CLI コマンド/オプション | 理由 | | ----------------------------------- | -------------------------- | ------------------------------------------------- | | **セッションのエクスポート** | | | | | | | | \[ファイルへエクスポート] | | | | `--share`、`/share` | プロトコルに含まれていない | | | gist にエクスポートする | | | | `--share-gist`、`/share gist` | プロトコルに含まれていない | | | **対話型 UI** | | | | | | | | スラッシュ コマンド | | | | `/help`、 `/clear`、 `/exit`など。 | TUI のみ | | | エージェント選択ダイアログボックス | `/agent` | 対話型 UI | | \[差分モード] ダイアログ | `/diff` | 対話型 UI | | フィードバック ダイアログ | `/feedback` | 対話型 UI | | テーマ セレクター | `/theme` | ターミナル UI | | モデル選択ツール | `/model` | 対話型 UI (代わりに SDK `setModel()` を使用) | | クリップボードにコピー | `/copy` | ターミナル固有 | | コンテキスト管理 | `/context` | 対話型 UI | | **研究と歴史** | | | | | | | | 詳細な調査 | `/research` | Web 検索を使用した TUI ワークフロー | | セッション履歴ツール | `/chronicle` | 立ち会い、アドバイス、改善、インデックス再作成 | | **ターミナル機能** | | | | | | | | カラー出力 | `--no-color` | ターミナル固有 | | スクリーン リーダー モード | `--screen-reader` | Accessibility | | 豊富な差分レンダリング | `--plain-diff` | ターミナルレンダリング | | スタートアップ バナー | `--banner` | ビジュアル要素 | | Streamer モード | `/streamer-mode` | TUI 表示モード | | 代替画面バッファー | | | | `--alt-screen`、`--no-alt-screen` | ターミナルレンダリング | | | マウスのサポート | | | | `--mouse`、`--no-mouse` | ターミナル入力 | | | **パス/アクセス許可のショートカット** | | | | | | | | すべてのパスを許可する | `--allow-all-paths` | アクセス許可ハンドラーを使用する | | すべての URL を許可する | `--allow-all-urls` | アクセス許可ハンドラーを使用する | | すべてのアクセス許可を許可する | | | | `--yolo`、`--allow-all`、`/allow-all` | アクセス許可ハンドラーを使用する | | | 詳細なツールのアクセス許可 | | | | `--allow-tool`、`--deny-tool` | | | | `onPreToolUse`フックを使用する | | | | URL アクセス制御 | | | | `--allow-url`、`--deny-url` | アクセス許可ハンドラーを使用する | | | 許可されているツールをリセットする | `/reset-allowed-tools` | TUI コマンド | | **ディレクトリ管理** | | | | | | | | ディレクトリの追加 | | | | `/add-dir`、`--add-dir` | セッションで構成する | | | ディレクトリを一覧表示する | `/list-dirs` | TUI コマンド | | ディレクトリの変更 | `/cwd` | TUI コマンド | | **プラグイン/MCP 管理** | | | | | | | | プラグイン コマンド | `/plugin` | 対話型管理 | | MCP サーバー管理 | `/mcp` | 対話型 UI | | **アカウント管理** | | | | | | | | ログイン フロー | | | | `/login`、`copilot auth login` | OAuth デバイス フロー | | | ログアウト | | | | `/logout`、`copilot auth logout` | ダイレクトCLI | | | ユーザー情報 | `/user` | TUI コマンド | | **セッション操作** | | | | | | | | 会話をクリアする | `/clear` | TUI のみ | | 平面図 | `/plan` | TUI のみ (代わりに SDK `session.rpc.plan.*` を使用) | | セッション管理 | | | | `/session`、`/resume`、`/rename` | TUI ワークフロー | | | フリート モード (対話型) | `/fleet` | TUI のみ (代わりに SDK `session.rpc.fleet.start()` を使用) | | **スキル管理** | | | | | | | | スキルを管理する | `/skills` | 対話型 UI | | **タスク管理** | | | | | | | | バックグラウンド タスクを表示する | `/tasks` | TUI コマンド | | **使用状況と統計** | | | | | | | | トークンの使用 | `/usage` | 使用状況イベントを登録する | | **コード レビュー** | | | | | | | | 変更の確認 | `/review` | TUI コマンド | | **委任** | | | | | | | | PR に委任する | `/delegate` | TUI ワークフロー | | **ターミナルのセットアップ** | | | | | | | | シェル統合 | `/terminal-setup` | シェル固有 | | **発達** | | | | | | | | 試験段階の切り替え | | | | `/experimental`、`--experimental` | ランタイム フラグ | | | カスタム命令コントロール | `--no-custom-instructions` | CLI フラグ | | 手順の表示/管理 | `/instructions` | TUI コマンド | | ワークスペースのインデックスを再作成する | `/reindex` | TUI コマンド | | IDE 統合 | `/ide` | IDE 固有のワークフロー | | **非対話型モード** | | | | | | | | プロンプト モード | | | | `-p`、`--prompt` | 単発実行 | | | 対話型プロンプト | | | | `-i`、`--interactive` | 自動実行後に対話型 | | | サイレント出力 | | | | `-s`、`--silent` | スクリプトに対応 | | | セッションの続行 | `--continue` | 最新の状態に再開 | | エージェントの選択 | `--agent ` | CLI フラグ | ## 対処方法 ### フリートモード フリートモードは、より大きな目的のためにランタイムが並列サブエージェントを起動できるようにする SDK アプリケーション向けに、`session.rpc.fleet.start()` を通じて利用できます。 独立したサブタスクを同時に実行し、メイン セッションによって要約できる場合に使用します。 完全なガイドについては、 [フリートモード](/ja/copilot/how-tos/copilot-sdk/features/fleet-mode) を参照してください。 ### セッションのエクスポート `--share` オプションは SDK では使用できません。 回避 策： 1. **イベントを手動で収集** する - セッション イベントをサブスクライブし、独自のエクスポートを作成します。 ```typescript const events: SessionEvent[] = []; session.on((event) => events.push(event)); // ... after conversation ... const messages = await session.getEvents(); // Format as markdown yourself ``` 2. **エクスポートに CLI を直接使用** する - 1 回限りのエクスポートに対して `--share` を使用して CLI を実行します。 ### アクセス許可の制御 SDK では、 **既定で拒否** アクセス許可モデルが使用されます。 アプリが `onPermissionRequest` ハンドラーを提供しない限り、すべてのアクセス許可要求 (ファイルの書き込み、シェル コマンド、URL フェッチなど) は拒否されます。 `--allow-all-paths`または`--yolo`の代わりに、アクセス許可ハンドラーを使用します。 ```typescript const session = await client.createSession({ onPermissionRequest: approveAll, }); ``` ### トークンの使用状況の追跡 `/usage`の代わりに、使用状況イベントをサブスクライブします。 ```typescript session.on("assistant.usage", (event) => { console.log("Tokens used:", { input: event.data.inputTokens, output: event.data.outputTokens, }); }); ``` ### コンテキスト圧縮 `/compact`の代わりに、自動圧縮を構成するか、手動でトリガーします。 ```typescript // Automatic compaction via config const session = await client.createSession({ infiniteSessions: { enabled: true, backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization }, }); // Manual compaction (experimental) const result = await session.rpc.history.compact(); console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`); ``` > \[!NOTE] > しきい値は、絶対トークン数ではなく、コンテキスト使用率の比率 (0.0 から 1.0) です。 ### プランの管理 プログラムによるセッション 計画の読み取りと書き込み: ```typescript // Read the current plan const plan = await session.rpc.plan.read(); if (plan.exists) { console.log(plan.content); } // Update the plan await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" }); // Delete the plan await session.rpc.plan.delete(); ``` ### メッセージ制御 中止せずに、現在の LLM ターンにメッセージを挿入します。 ```typescript // Steer the agent mid-turn await session.send({ prompt: "Focus on error handling first", mode: "immediate" }); // Default: enqueue for next turn await session.send({ prompt: "Next, add tests" }); ``` ## プロトコルの制限事項 SDK は、CLI の JSON-RPC プロトコルを介して公開されている機能にのみアクセスできます。 使用できない CLI 機能が必要な場合: 1. **代替手段を確認する** - 多くの機能には SDK に相当するものがあります (上記の回避策を参照してください) 2. **CLI を直接使用する** - 1 回限りの操作の場合は、CLI を呼び出します 3. **機能を要求する** - プロトコルのサポートを要求する問題を開く ## バージョン互換性 | SDK プロトコル範囲 | CLI プロトコルのバージョン | Compatibility | | ----------- | --------------- | ---------------- | | v2–v3 | v3 | 完全なサポート | | v2–v3 | v2 | 自動 v2 アダプターでサポート | SDK は起動時に CLI とプロトコル バージョンをネゴシエートします。 SDK では、プロトコル バージョン 2 から 3 がサポートされています。 v2 CLI サーバーに接続すると、SDK は `tool.call` と `permission.request` メッセージを v3 イベント モデルに自動的に適合させます。コードの変更は必要ありません。 実行時にバージョンを確認します。 ```typescript const status = await client.getStatus(); console.log("Protocol version:", status.protocolVersion); ``` ## こちらも参照ください * [初めてのCopilot搭載アプリを構築する](/ja/copilot/how-tos/copilot-sdk/getting-started) * [セッション フック](/ja/copilot/how-tos/copilot-sdk/hooks/hooks-overview) * [Using MCP servers with the GitHub Copilot SDK](/ja/copilot/how-tos/copilot-sdk/features/mcp) * [デバッグ ガイド](/ja/copilot/how-tos/copilot-sdk/troubleshooting/debugging)