intellij-platform-sdk

IntelliJ Platform SDK スキル

モダンな v2 SDK に基づく IntelliJ Platform プラグイン開発には、このスキルを使用してください。

このスキルは、メインファイルを小さく保ち、タスクに関連する資料だけをモデルが読み込めるよう、目的別のリファレンスに分割されています。

このスキルでできること

• IntelliJ Platform プラグインの作成や更新
• build.gradle.kts、settings.gradle.kts、plugin.xml の設定
• アクション、サービス、ツールウィンドウ、設定、通知の実装
• PSI、参照、インデックス作成、VFS、ダムモードの操作
• カスタム言語サポートの構築
• インスペクション、インテンション、クイックフィックス、コード補完、フォーマット、ドキュメントの実装
• 実行構成、プログラムランナー、実行コンソールの実装
• ライブテンプレート、ファイルテンプレート、後置補完の提供
• IDE テーマや配色の作成・拡張
• プラグイン開発での Language Server（LSP）の統合
• MCP ツールやツールセットの提供
• プラグインのテストと Marketplace での公開準備
• バージョン互換性への対応と Gradle プラグインの移行

このスキルの使い方

まず、ユーザーの実際のタスクを特定してください。その後、関連するリファレンスファイルだけを読みます。

タスクが以下に関する場合は references/getting-started.md を読んでください

• 新しい IntelliJ Platform プラグインプロジェクトの作成
• プラグインプロジェクト向けの IntelliJ Platform Gradle Plugin 2.x のセットアップ
• プラグイン開発で対象とする IDE やバンドルプラグインの選択
• plugin.xml でのオプションのプラグイン／モジュール依存関係の追加（<depends> の全仕様については plugin-registration.md も参照）
• プラグインプロジェクトの plugin.xml メタデータの作成や修正（概要については、完全な要素／属性リファレンスを記載した plugin-registration.md を参照）

タスクが以下に関する場合は references/plugin-registration.md を読んでください

• plugin.xml 記述子の構造の作成や修正
• <idea-plugin> ルート属性（url、require-restart）
• メタデータ要素（<id>、<name>、<vendor>、<description>、<change-notes>、<product-descriptor>）
• <idea-version> の since/until/strict-until-build と Gradle の pluginConfiguration の関係
• <depends> の必須／任意、config-file のマージ仕様、追加の記述子の命名、<incompatible-with>
• 宣言型リスナー（<applicationListeners>／<projectListeners> の <listener> 属性）
• <actions> のすべてのサブ要素（<add-to-group>、<mouse-shortcut>、<override-text>、<synonym>、<abbreviation>、<reference>、<separator>）
• <extensionPoint> の qualifiedName／area／<with> と、<extensions> の id／order／os の基本属性
• <resource-bundle>、<xi:include>、サービス登録 XML（testServiceImplementation／headlessImplementation）
• 動的プラグイン登録の要件、require-restart、有料プラグインの制限
• プラグインロゴファイルの配置（pluginIcon.svg／pluginIcon_dark.svg）

タスクが以下に関する場合は references/platform-basics.md を読んでください

• AnAction、アクショングループ、メニュー、ツールバー
• サービス（@Service、プロジェクト／アプリケーション／モジュールサービス）
• ロギング（Logger、logger<T>()、thisLogger()）
• バックグラウンドタスク（Task.Backgroundable、ProgressManager、ProgressIndicator）
• 更新のデバウンスとバッチ処理（DebouncedUpdates、2026.2 以降）
• Virtual File System（VirtualFile、VFS リスナー）
• スレッド処理、読み取り／書き込みアクション、ダムモード、モダリティ
• プラグインでの Kotlin コルーチンのパターン（readAction、writeAction、CoroutineScope）
• 動的なプラグインの読み込み／アンロード
• Disposable のライフサイクル管理
• メッセージング基盤（MessageBus、Topic）
• 一般的なプラグインアーキテクチャの判断
• 分割モードの概念とモジュール型プラグインの構成（RPC／フロントエンドとバックエンドの詳細については split-mode-rpc.md を参照）
• Workspace Model の概要（API リファレンス全体については workspace-model.md を参照）

タスクが以下に関する場合は、references/split-mode-rpc.md を読んでください

• 分割／リモート開発用のプラグインモジュール（共有／フロントエンド／バックエンド）のセットアップ
• @Rpc インターフェース、RemoteApi、RemoteApiProviderService、サイド間通信のための durable {}
• フロントエンド、バックエンド、共有のどこに各 API を配置するか
• 分割モードにおける PSI／インデックス／VFS／実行の制約
• シリアライズ可能な ID 型（ProjectId、VirtualFileId、EditorId）
• バックエンドからフロントエンドへのプッシュに使うリモートトピック（ApplicationRemoteTopic／ProjectRemoteTopic）
• DTO のパターンと kotlinx-serialization のバージョン互換性
• Gradle の分割モード設定（各サイドの splitMode、pluginInstallationTarget、bundledModule）
• 分割モードのデバッグ（runIdeBackend／runIdeFrontend、レイテンシのエミュレーション）

タスクが以下に関する場合は、references/workspace-model.md を読んでください

• WorkspaceModel.getInstance(project).currentSnapshot を使ったプロジェクト構造の読み取り
• workspaceModel.update("label") { builder -> ... } によるエンティティの変更
• 外部システムからのプロジェクト構造の一括置換（replaceBySource()）
• @EntityProperty を使ったカスタム @Entity 型の宣言
• エンティティソース（JpsFileEntitySource、ExternalEntitySource、GradleEntitySource）
• WorkspaceModelTopics.CHANGED によるイベントのリスニング
• Workspace Model エンティティと従来の Module／Library／Facet API の連携
• エンティティ間参照のための VirtualFileUrl と SymbolicEntityId

タスクが以下に関する場合は、references/psi-and-indexing.md を読んでください

• PSI の走査または変更
• 参照、解決、名前変更、使用箇所の検索、安全な削除
• PSI ファクトリーを使ったコード生成
• ファイルベースのインデックス、スタブインデックス、gists
• ファイルビュー・プロバイダー（単一ファイル内の複数言語の PSI ツリー）
• IndexNotReadyException、ダムモード、PSI のパフォーマンス
• PSI クックブック（Java 固有の一般的な操作）
• CachedValuesManager によるキャッシュ

タスクが以下に関する場合は、references/language-support-and-analysis.md を読んでください

• カスタム言語プラグイン
• レキサー、パーサー、ParserDefinition
• 構文ハイライト、アノテーター、コード補完
• インスペクション、インテンション、クイックフィックス
• 名前変更リファクタリング、名前変更の検証、安全な削除
• フォーマッター、折りたたみ、構造ビュー、ドキュメント・プロバイダー
• パラメーター情報、スペルチェック、ナビゲーションバーとの統合
• インレイヒント、コードビジョン
• 言語インジェクション
• Symbols API と宣言／参照モデル
• Web フレームワークのメタデータ向け Poly Symbols と Web Types
• DocumentationTarget API
• OptPane、宣言型のインスペクションオプション、OptionController
• コード補完／参照コントリビューター向けの要素パターン（PlatformPatterns、PsiElementPattern）
• 配色の管理、TextAttributesKey の依存チェーン

タスクが以下に関する場合は、references/ui-settings-and-toolwindows.md を読んでください

• Kotlin UI DSL v2（panel { row { } }、BoundConfigurable）
• ダイアログと IntelliJ UI コンポーネント
• ツールウィンドウ
• 設定／構成可能項目（親 ID／設定グループの階層を含む）
• 永続状態
• 通知
• ポップアップ（JBPopup、ListPopup、選択ポップアップ）
• 新規プロジェクトウィザード、モジュールタイプ、プロジェクトビューとの統合
• ステータスバーウィジェット
• エディター通知バナー
• 機密データの永続化（PasswordSafe）
• 埋め込みエディターコンポーネント（EditorTextField）
• 国際化（i18n）とローカライズ
• アクセシビリティ（キーボード操作、スクリーンリーダー）
• プラグインの UX 原則

タスクが以下に関する場合は、references/testing-and-publishing.md を読んでください

• テストフィクスチャとプラグインのテスト
• 統合テストまたは UI テスト
• Starter／Driver ベースのテストセットアップ
• パーサー／コード補完／インスペクションのテスト
• プラグインベリファイア
• verifyPluginProjectConfiguration／verifyPluginStructure
• Marketplace への署名と公開

タスクが以下に関する場合は、references/compatibility.md を読んでください

• ビルドの互換性
• sinceBuild／untilBuild
• レガシー Gradle プラグイン 1.x から 2.x への移行
• プラットフォームバージョン間の API 変更
• Java／Kotlin のバージョン要件
• Workspace Model の移行または新しいプラットフォーム API への移行

タスクが以下に関する場合は、references/extension_points.md を読んでください

• 正確な plugin.xml 登録構文
• 適切な拡張ポイントの特定
• アクショングループ ID と XML パターン
• com.intellij.mcpServer.* などの MCP 拡張ポイント

タスクが以下に関する場合は、references/code_samples.md を読んでください

• 最も近い公式 SDK サンプルを探す
• 公式の実装パターンをコピーする
• JetBrains の各サンプルが示す内容を理解する

タスクが以下に関する場合は、references/lsp.md を読んでください

• IntelliJ Platform プラグインへの Language Server の統合
• LspServerSupportProvider／LspIntegrationProvider、LspServerDescriptor／LspClientDescriptor、または LSP 固有の plugin.xml 依存関係
• プラグイン開発のコンテキストにおける、サポート対象の JetBrains IDE 製品とプラットフォームバージョン向けの LSP 設定
• IntelliJ Platform 内での LSP 機能サポートの時期
• プラグインで LSP 統合とネイティブな IntelliJ 言語サポートのどちらを選ぶか

タスクが以下に関する場合は、references/mcp-and-ai-integration.md を読んでください

• IntelliJ Platform プラグインにおける MCP 関連の統合
• MCP ツールの提供、または MCP ツールセットの定義
• com.intellij.mcpServer.* などの MCP 関連拡張ポイントの理解
• 公式 SDK ドキュメントがまだ少ない領域における MCP のガイダンス

タスクが以下に関する場合は、references/execution-and-run-configs.md を読んでください

• カスタム実行構成（ConfigurationType、RunConfigurationBase）の実装
• 実行構成プロデューサー（コンテキストから構成を自動検出）
• プログラムランナーと実行環境
• 実行コンソールとコンソールフィルター
• 実行構成マクロ
• 起動前／起動後のタスク

タスクが以下に関する場合は、references/webview-jcef.md を読んでください

• IDE 内に Chromium ベースのブラウザー（JBCefBrowser）を埋め込み、HTML やカスタム Web コンポーネントを表示する
• JBCefApp.isSupported() で JCEF の利用可否を確認し、適切なフォールバックを行う
• JS ⇄ Java の双方向通信（JBCefJSQuery、JBCefJavaScriptFunction）
• JCEF のライフサイクル、破棄、スレッド処理（ハンドラーは EDT ではなく専用スレッドで実行されます）
• JCEF の plugin.xml と JBR の要件（com.intellij.modules.jcef モジュールはなく、実際の制約はランタイムの JBR バリアントです）
• リモート開発／Gateway の制約（JCEF はバックエンドではなくシンクライアントで動作します）
• カスタムクライアントとハンドラーを使用した JBCefBrowserBuilder の作成
• JCEF のデバッグ（DevTools の統合、レジストリーキー）
• よくある落とし穴：破棄時のリーク、スレッド違反、破棄後のアクセス

タスクが以下に関する場合は、references/templates.md を読んでください

• プラグインに同梱するライブテンプレートの提供
• カスタムライブテンプレートのマクロ／関数
• ファイルテンプレートとコードテンプレート（Velocity ベース）
• Postfix 補完テンプレート
• Surround With の記述子

タスクが以下に関する場合は、references/themes.md を読んでください

• IDE UI テーマの作成または拡張
• テーマ JSON 記述子の形式
• エディターの配色の統合
• テーマでのアイコンのカスタマイズ
• Islands テーマとの互換性
• テーマプラグインのデプロイと公開

タスクが以下に関する場合は、references/icons.md を読んでください

• プラグインへのアイコンの追加または整理
• アイコンファイルの命名規則（ダークバリアント、HiDPI）
• アイコンホルダークラス（パス指定とクラス指定）
• New UI（expui）のアイコン要件とアイコンマッピング
• アニメーションアイコン（AnimatedIcon、AsyncProcessIcon）
• リソースバンドルを使ったアイコンのツールチップ

タスクが以下に関する場合は、references/patterns.md を読んでください

• 再利用可能な実装パターン
• エディター／ドキュメントのヘルパー（キャレット位置、選択範囲、スクロール）
• エディターの座標系（オフセット、論理位置／視覚位置）
• エディターに関する FAQ（アクティブなエディターの取得、イベントのリッスン、カスタムタブのタイトル／色）
• 進捗の処理
• ダイアログ／ツールウィンドウのパターン
• PSI／エディター／VFS のユーティリティ
• アイコンの読み込みと描画のパターン

タスクが以下に該当する場合は、references/troubleshooting.md をお読みください

• 問題がどのトラブルシューティングの分類に当てはまるか、まだ判断できない
• アクションが表示されない
• スレッド関連のアサーション
• サービスの初期化に関する失敗
• PSI の書き込みアクションに関するエラー
• 検証ツールの警告
• テストのセットアップに関する失敗

タスクが以下に該当する場合は、references/troubleshooting-build-runtime.md をお読みください

• Gradle またはリポジトリの解決に関する失敗
• plugin.xml の配線またはクラスの読み込みに関する問題
• アクションの登録や実行時の表示に関する問題
• 検証、署名、リリースに関する失敗

タスクが以下に該当する場合は、references/troubleshooting-psi-ui-testing.md をお読みください

• PSI の有効性または書き込みアクションに関するアサーション
• IndexNotReadyException
• エディターとドキュメントの同期
• UI の更新または EDT へのアクセスに関するエラー
• フィクスチャ、テストデータ、デバッグに関する問題

作業の原則

IntelliJ Platform のタスクに取り組む際は、次の点を守ってください。

1. アドホックなハックよりも、公式のプラットフォームの概念を優先します。
2. 再利用可能なロジックはアクションではなく、サービスに配置します。
3. AnAction.update() は極めて高速に保ちます。
4. 動作を最適化する前に、スレッド処理とダムモードを考慮します。
5. 構造的なコードのタスクには、PSI を考慮した手法を使用します。
6. ユーザー向けの UI には、プラットフォームの UI コンポーネントと規約を使用します。
7. プラグインの依存関係と対象 IDE の範囲は、実用上可能な限り小さく保ちます。

特に重要な注意事項

• AnAction の実装では、リクエストごとの状態をフィールドに保持しないでください。
• IntelliJ Platform 2022.3 以降を対象とする場合、アクションでは getActionUpdateThread() を実装する必要があります。
• PSI の変更は、EDT 上で書き込みアクションとコマンドの中で実行する必要があります。ドキュメントの変更は、プラットフォームが使用する PSI／ドキュメント API と連携させてください。
• すべての機能がダムモードで安全に動作するとは限りません。安易に DumbAware を指定しないでください。
• Kotlin プラグインで 2024.1 以降、またはそれより新しいプラットフォームのベースラインを対象とする場合、適切な場面ではコルーチンベースの読み取り／書き込み API を優先してください。
• ライトサービスは final にする必要があります。依存サービスのコンストラクターインジェクションはサポートされていません。また、コンストラクター内でサービスを検索し、フィールドにキャッシュすることも避けてください。
• 内部 API は、実用的な公開 API の代替手段がなく、そのトレードオフが明確な場合を除き、使用しないでください。

一般的な回答の手順

ユーザーから実装の支援を求められた場合は、次の手順に従ってください。

1. 対象となる機能を特定します。アクション、サービス、PSI、UI、言語サポート、テスト、公開のいずれかを確認します。
2. 該当するリファレンスファイルを読みます。
3. 最も近い公式サンプルまたは拡張ポイントのパターンに従います。
4. IntelliJ Platform の規則に沿った、最小限で正しい解決策を実装します。
5. 公開または互換性が関係する場合は、検証、署名、ビルド範囲に関する項目も確認します。

リファレンスマップ

• references/getting-started.md
• references/plugin-registration.md
• references/platform-basics.md
• references/split-mode-rpc.md
• references/workspace-model.md
• references/psi-and-indexing.md
• references/language-support-and-analysis.md
• references/ui-settings-and-toolwindows.md
• references/testing-and-publishing.md
• references/compatibility.md
• references/extension_points.md
• references/code_samples.md
• references/lsp.md
• references/mcp-and-ai-integration.md
• references/execution-and-run-configs.md
• references/webview-jcef.md
• references/templates.md
• references/themes.md
• references/icons.md
• references/patterns.md
• references/troubleshooting.md
• references/troubleshooting-build-runtime.md
• references/troubleshooting-psi-ui-testing.md