intellij-platform-sdk

IntelliJ Platform SDK 技能

此技能适用于基于现代 v2 SDK 的 IntelliJ Platform 插件开发。

此技能按主题拆分为多个参考文件，让主文件保持精简，并使模型只加载与任务相关的内容。

此技能的用途

• 创建或更新 IntelliJ Platform 插件
• 配置 build.gradle.kts、settings.gradle.kts 和 plugin.xml
• 实现操作、服务、工具窗口、设置和通知
• 使用 PSI、引用、索引、VFS 和 dumb mode
• 构建自定义语言支持
• 实现检查、意图、快速修复、补全、格式化和文档
• 实现运行配置、程序运行器和执行控制台
• 提供实时模板、文件模板和后缀补全
• 创建或扩展 IDE 主题和配色方案
• 在插件开发场景中集成语言服务器（LSP）
• 贡献 MCP 工具和工具集
• 测试插件并准备发布到 Marketplace
• 处理版本兼容性和 Gradle 插件迁移

如何使用此技能

首先，确认用户的实际任务。然后只阅读相关的参考文件。

任务涉及以下内容时，阅读 references/getting-started.md

• 创建新的 IntelliJ Platform 插件项目
• 为插件项目配置 IntelliJ Platform Gradle Plugin 2.x
• 选择目标 IDE 或插件开发所需的捆绑插件
• 在 plugin.xml 中添加可选插件／模块依赖（另请参阅 plugin-registration.md，了解完整的 <depends> 语义）
• 编写或修复插件项目的 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+）
• 虚拟文件系统（VirtualFile、VFS 监听器）
• 线程、读／写操作、dumb mode、模态
• 插件中的 Kotlin 协程模式（readAction、writeAction、CoroutineScope）
• 动态插件加载／卸载
• Disposable 生命周期管理
• 消息基础设施（MessageBus、Topic）
• 通用插件架构决策
• 分离模式概念和模块化插件组织（完整的 RPC／前端－后端细节请参阅 split-mode-rpc.md）
• Workspace Model 概览（完整 API 参考请参阅 workspace-model.md）

当任务涉及以下内容时，请阅读 references/split-mode-rpc.md

• 设置拆分式／远程开发插件模块（shared/frontend/backend）
• 用于跨端通信的 @Rpc 接口、RemoteApi、RemoteApiProviderService、durable {}
• 确定哪些 API 应放在 frontend、backend 或 shared 中
• 拆分模式下 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 工厂生成代码
• 基于文件的索引、存根索引、gist
• 文件视图提供程序（单个文件中的多语言 PSI 树）
• IndexNotReadyException、dumb 模式、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 组件
• 工具窗口
• 设置／可配置项（包括 parentId／设置组层级结构）
• 持久化状态
• 通知
• 弹出窗口（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 模式
• MCP 扩展点，例如 com.intellij.mcpServer.*

当任务涉及以下内容时，请阅读 references/code_samples.md

• 查找最接近的官方 SDK 示例
• 复制官方实现模式
• 了解每个 JetBrains 示例展示的内容

当任务涉及以下内容时，请阅读 references/lsp.md

• 在 IntelliJ Platform 插件中集成语言服务器
• 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 工具集
• 了解 MCP 相关扩展点，例如 com.intellij.mcpServer.*
• 在官方 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）
• 后缀补全模板
• 环绕代码描述符

当任务涉及以下内容时，请阅读 references/themes.md

• 创建或扩展 IDE UI 主题
• 主题 JSON 描述符格式
• 编辑器配色方案集成
• 主题中的图标自定义
• Islands 主题兼容性
• 部署和发布主题插件

当任务涉及以下内容时，请阅读 references/icons.md

• 在插件中添加或整理图标
• 图标文件命名约定（深色变体、HiDPI）
• 图标持有类（按路径与按类引用）
• New UI（expui）图标要求和图标映射
• 动画图标（AnimatedIcon、AsyncProcessIcon）
• 通过资源包设置图标工具提示

当任务涉及以下内容时，请阅读 references/patterns.md

• 可复用的实现模式
• 编辑器／文档辅助工具（插入符位置、选区、滚动）
• 编辑器坐标系（偏移量、逻辑／视觉位置）
• 编辑器常见问题（获取活动编辑器、监听事件、自定义标签页标题／颜色）
• 进度处理
• 对话框／工具窗口模式
• 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. 在优化行为之前，先遵循线程和 dumb mode的要求。
5. 对结构性代码任务采用感知 PSI的方法。
6. 在面向用户的界面中使用平台 UI 组件和惯例。
7. 尽可能缩小插件依赖范围和目标 IDE 范围。

重要提醒

• AnAction 实现不应在字段中存储特定请求的状态。
• 以 IntelliJ Platform 2022.3 或更高版本为目标时，操作必须实现 getActionUpdateThread()。
• PSI 修改必须在 EDT 上，在写操作和命令中执行；文档更改应与平台使用的 PSI／文档 API 协调。
• 并非所有功能都能在 dumb mode 下安全运行；不要随意标记为 DumbAware。
• 面向 2024.1+ 或更新平台基线的 Kotlin 插件，在适用时优先使用基于协程的读／写 API。
• 轻量服务必须是 final；不支持通过构造函数注入依赖服务，也不应只为了将服务缓存到字段中而在构造函数里查找服务。
• 除非没有可行的公共替代方案且已明确说明权衡，否则应避免使用内部 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