SuperAPI AI 工具集

jetbrains-arch

编程与开发

查看项目

更新于 11-02 03:25

技能介绍

该技能是 packages/kilo-jetbrains/ 的详细参考,说明模块边界、RPC、线程和依赖规则的“如何与为何”,硬性限制摘要见该目录下 AGENTS.md。

一、模块放置与架构 JetBrains 参考模板的结构为:根项目组装最终插件,shared 保存契约,frontend 保存 UI,backend 保存项目本地逻辑;可参考其 split-mode 接线与 RPC 布局,但不照搬其 Compose UI 方案。单机 IDE 模式下三个模块在同一进程加载,split 插件无需远程开发也可工作。backend 模块承载项目模型、索引、分析与 CLI 进程管理;frontend 承载 UI、输入辅助和延迟敏感功能;shared 定义双方使用的 RPC 接口与数据类型。需要 XML 注册的非 light 服务放在 kilo.jetbrains.backend.xml 的 applicationService 或 projectService 下。

二、RPC 契约与载荷 前后端通过 shared/ 中定义的 RPC 接口通信,载荷必须使用 kotlinx.serialization。RPC API 用 @Rpc、RemoteApi<Unit> 和 suspend 方法定义;跨进程载荷必须 @Serializable,shared 保持轻量,不引入仅前端或仅后端的 API。RPC 提供者在 backend 实现,通过 com.intellij.platform.rpc.backend.remoteApiProvider 注册。新增 split 功能需要 RPC 时,可参照模板接线。

三、前后端规则与远程开发体验 只能从前端协程调用 RPC,绝不在 EDT 上调用,也不用阻塞包装器掩盖;长时 RPC 调用与 flow 用 durable {} 包裹以在重连和后端重启后存活;后端向前端推送优先用 Remote Topics 而非轮询。UI 先渲染空状态再逐步填充数据,不阻塞首屏;避免频繁 RPC,对 UI 事件去抖、批量请求、适当缓存、大数据集分页。新增或移动 split 代码时运行 Plugin DevKit | Code | Frontend and Backend API Usage 检查。

四、IntelliJ 平台源码查询 查找平台 API 用法、扩展点、服务、动作、检查、PSI/VFS/编辑器行为或插件模式时,优先真实 IntelliJ 源码而非 Gradle 缓存、下载 jar、生成解析产物或反编译类。先检查 $INTELLIJ_REPO 是否指向可读的 IntelliJ Community 检出并优先搜索其中 platform/、plugins/、java/、xml/、json/、jvm/ 等模块;不要假设检出位于当前仓库同级。未设置或不可读时提示用户设置,例如 export INTELLIJ_REPO=/path/to/intellij-community,不要硬编码机器绝对路径;本地不可用可回退到 https://github.com/JetBrains/intellij-community。不得已才检查 Gradle 缓存、jar、反编译类等。不要使用源码库中标记为 internal 的平台 API,改用公共 API 或受支持的扩展点;实验性 API 可用但需提醒用户。

五、线程、服务与协程 线程与协程上下文注解位于 com.intellij.util.concurrency.annotations:@RequiresEdt 要求 EDT,@RequiresBackgroundThread 要求非 EDT,@RequiresReadLock 要求读或写锁,@RequiresWriteLock 要求写锁,@RequiresReadLockAbsence 要求不持锁,@RequiresBlockingContext 要求非 suspend 上下文(仅源码保留,无运行时断言)。五个 Requires* 注解均支持 generateAssertion=false 以只记录意图。自定义 IO 安全或非阻塞调度器用 org.jetbrains.annotations 的 @BlockingExecutor / @NonBlockingExecutor;协程中的阻塞 I/O 在被调方内用 withContext(Dispatchers.IO) 切换,BlockingMethodInNonBlockingContextInspection 覆盖此类问题。所有 Swing UI 创建、修改和访问必须在 EDT 上进行,涉及 Swing 组件或 SessionModel 的方法标注 @RequiresEdt,用 invokeLater 或 withContext(Dispatchers.Main) 切回,工具窗口任务用 ToolWindowManager.invokeLater()。

服务优先用 light services:用 @Service 或 @Service(Service.Level.PROJECT) 注解,避免重构造工作,不缓存服务实例,调用处用 service<T>() 获取。协程作用域推荐构造注入 CoroutineScope,每个服务各自作用域,在应用/项目关闭或插件卸载时取消;支持 MyService(CoroutineScope) 与 MyService(Project, CoroutineScope)。注入作用域上下文含 Dispatchers.Default 与 CoroutineName;阻塞 I/O 切到 Dispatchers.IO。runBlockingCancellable 存在但不推荐,动作中可用 currentThreadCoroutineScope()。

六、测试与超时 修改 UI 状态或依赖 EDT 线程的代码路径必须有测试,基于 BasePlatformTestCase(session 包用 SessionControllerTestBase)获得真实 Application 与 EDT;不要 mock EDT 或线程断言;不要为测试访问添加生产方法或合成接缝,应断言可观察的 UI/动作行为或在 flush 协程并排空 EDT 后断言组件状态。集成测试优先确定性同步(显式状态转换、事件、fake server 钩子、latch、协程完成),超时仅作看门狗;必要时在文件顶部定义一个命名超时/等待辅助并复用,失败时包含最后状态和有用日志;不要用 delay、sleep 或反复轮询猜异步完成。

七、依赖 第三方库必须随插件打包,不依赖平台自带的 OkHttp、Gson、Guava、kotlinx-serialization-json 等,在 build.gradle.kts 中以 implementation 声明使其进入插件 JAR 并由插件类加载器加载。kotlinx.coroutines 是唯一必须例外,由平台提供且不得打包。版本在 gradle/libs.versions.toml 固定并通过 libs.* 引用,不在 build.gradle.kts 硬编码版本字符串。

shared/ 不声明 kotlinx-serialization 依赖,其 @Serializable DTO 绑定平台副本,而 frontend/ 与 backend/ 各自打包 kotlinx-serialization-json,因此从这两个模块访问 shared DTO 的生成序列化器会因两个类加载器解析 KSerializer 而在运行时抛出 LinkageError。在 frontend/ 和 backend/ 中不要调用 Json.decodeFromString<SharedDto>(...)、Json.encodeToString(dto)、decodeFromJsonElement<SharedDto>(...)、SharedDto.serializer();模块本地 @Serializable 类型和 List<String> 等内建类型没问题。当线上格式与 shared DTO 一一对应时,先解码到模块本地 wire 类型再手工映射到 DTO;格式不匹配(判别联合、字段嵌套不同、DTO 字段为计算值)时解析为 JsonObject 手工构造 DTO。Gradle 测试把 shared、被测模块和 kotlinx-serialization 放在扁平类路径上,无法捕获此问题,需在沙箱 runIdeSplitMode 中验证返回 shared DTO 的 RPC 路径。

八、服务器协议 插件启动 kilo serve --port 0(由系统分配随机端口),从 stdout 读取 listening on http://...:(\d+) 发现端口;通过 KILO_SERVER_PASSWORD 环境变量传递随机 32 字节十六进制密码用于 Basic Auth。每次启动固定设置:KILO_CLIENT=jetbrains、KILO_PLATFORM=jetbrains、KILO_APP_NAME=kilo-code、KILO_ENABLE_QUESTION_TOOL=true、KILO_DISABLE_CLAUDE_CODE=true、KILOCODE_FEATURE=jetbrains-plugin。后端不注入 KILO_CONFIG_CONTENT;JetBrains 的 edit: ask 默认值来自 CLI 按客户端区分的默认层,位于用户配置之下,全局 kilo.json、项目 kilo.jsonc、代理权限和插件 Auto-Approve 页面均可覆盖;外部提供的 KILO_CONFIG_CONTENT 原样传递。该协议与 VS Code 扩展相同。

九、适用场景与限制 适用于在 Kilo JetBrains 插件中新增或移动跨模块代码、定义 RPC 载荷、处理线程与服务、排查序列化类加载器冲突和服务器启动协议。限制:部分细节(如具体版本号)需以仓库内文件为准;暂未提供该技能的命令安装步骤、收费信息与平台支持范围。