Kilo JetBrains 插件开发全指南从环境搭建、本地构建到发布与调试【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocodeKilo 是面向 JetBrains 系列 IDE 的 AI 编程 Agent 插件kilo.jetbrains采用 IntelliJ 官方推荐的 split-mode前后端分离架构将 UI 放在前端进程、将 CLI 进程管理放在后端进程从而原生支持 JetBrains 远程开发场景。本文以仓库中的 packages/kilo-jetbrains/README.md 为主体结合 RELEASING.md、AGENTS.md 与源码结构展开带你完整掌握该插件的环境准备、构建打包、沙箱运行、开发参数、调试日志与发布流程读完即可在本地跑起一个可调试的插件沙箱并理解 CLI 运行时下载与发布门禁的底层机制。一、插件形态与工程结构从源码结构看这是一个三模块 Gradle 工程根项目名在 settings.gradle.kts 中定义为kilo.jetbrains包含三个子模块模块职责依据 AGENTS.mdshared/定义 frontend ↔ backend 之间的 RPC 接口与跨进程数据类型全部使用kotlinx.serialization的Serializable载荷frontend/承载 UI、输入辅助与延迟敏感特性backend/承载项目模型、索引、分析、执行与 CLI 进程管理在单体非远程模式下三个模块会在同一个 IDE 进程中一起加载split 插件在非远程开发环境下也能正常工作只有在远程开发Remote Development时frontend 运行在客户端机器、backend 运行在宿主机插件才真正发挥 split-mode 的价值。这一点决定了插件的 UI 必须使用标准 Swing IntelliJ Platform 组件SimpleToolWindowPanel、DialogWrapper、Action System 等而不能依赖 JCEFJBCefBrowser或 Compose——JCEF 在远程开发中因前端进程在客户端、显示在宿主而不可用。二、环境准备Prerequisites开发本插件需要三样东西Bun用于执行 package 构建脚本bun run build等仓库根目录的bunfig.toml与package.json均以 Bun 为包管理与脚本运行时。JDK 21Gradle 与 IntelliJ Platform SDK 的硬性要求。用java -version确认版本。推荐的安装方式是 SDKMAN# 安装 SDKMAN若尚未安装 curl -s https://get.sdkman.io | bash # 安装并激活 Java 21Eclipse Temurin 发行版 sdk install java 21-tem sdk use java 21-temIntelliJ IDEA用于把插件跑在沙箱化sandboxed的 IDE 实例中。三、Fresh Worktree 与 Monorepo 集成仓库是一个 Bun workspace 单仓monorepoJetBrains 插件位于packages/kilo-jetbrains/。当你在 git worktree 中工作例如经由 Agent Manager 创建的工作树时在构建或运行 Gradle 任务之前需要先从仓库根目录安装依赖bun install这一步会安装构建脚本所需的 Node 依赖。此外注意 AGENTS.md 中列出的「必须同步变更的文件」package.json中的 CLI 版本要与 backend 下载器消费的 GitHub CLI release tag 保持一致gradle.properties中的kilo.cli.pinned与 Gradle / release 脚本门禁保持一致。四、在 IntelliJ 中打开工程在 IntelliJ IDEA 中打开 monorepo 根目录时packages/kilo-jetbrains/下的 Gradle 工程应通过.idea/gradle.xml被自动识别。若未识别可手动关联File Settings Build Tools Gradle 选择packages/kilo-jetbrains/settings.gradle.kts。五、本地构建5.1 标准本地构建在packages/kilo-jetbrains/下执行bun run build该命令实际运行./gradlew buildPlugin见 package.json 的build脚本。此构建不会把 CLI 二进制打进插件包backend 会在连接connect时按宿主平台下载固定的 Kilo CLI release。插件压缩包输出到build/distributions/。5.2 通过 Turbo 构建也可以从仓库根目录用 Turbo 按包过滤构建bun turbo build --filterkilocode/kilo-jetbrains5.3 生产构建从packages/kilo-jetbrains/执行bun run build:production即bun script/build.ts --production。产物位于build/distributions/kilo.jetbrains-version.zip可通过Settings Plugins Install Plugin from Disk安装到任意 JetBrains IDE。5.4 直接使用 Gradle本地打包bun run build内部为./gradlew buildPlugin。生产验证./gradlew buildPlugin -Pproductiontrue。5.5 CLI 固定Pin机制gradle.properties中两个关键开关共同决定了构建形态依据 gradle.properties 与 AGENTS.md配置项含义kilo.cli.pinnedtrue默认且唯一可发布的状态使用package.json中固定的 CLI releaseOpenAPI 客户端从固定版本生成kilo.cli.pinnedfalse仅限本地开发从本地packages/opencode/源码生成客户端并打包本地构建的 CLI 二进制生产构建与发布脚本会直接失败# packages/kilo-jetbrains/gradle.properties节选 kilo.jetbrains.version7.1.6 kilo.cli.pinnedtrue org.gradle.configuration-cachetrue org.gradle.cachingtrue org.gradle.jvmargs-Xmx4096m -XX:MaxMetaspaceSize512m本地想用仓库里的 CLI 开发时切换kilo.cli.pinnedfalse后执行./gradlew :backend:buildRepoCli它构建packages/opencode/dist/kilocode/cli-os-arch/bin/stageRepoCli会把本地 CLI 打包进插件。注意冷构建时固定 pin 模式generateOpenApiSpec需要联网下载固定的 CLI release。六、运行插件Sandbox6.1 Split Mode 沙箱使用仓库自带的Run IDE (Split Mode)运行配置或直接在命令行执行./gradlew --no-configuration-cache runIdeSplitMode该任务会同时启动 split 模式的 backend 与 frontend 两个进程backend 在首次连接时下载固定的 CLI release。--no-configuration-cache是必须的IntelliJ Platform Gradle Plugin 的 run-IDE 任务在此配置下不兼容 configuration cache同时会传入--purge-old-log-directories避免陈旧的沙箱日志盖住当次的kilo.log*。6.2 单独运行 backend / frontendRun IDE (Backend)或./gradlew --no-configuration-cache runIdeBackend只启动 split 会话的 backend 半边。排障提示如果Run IDE (Backend)启动后很快退出多半是上一次 backend 运行留下了孤儿 Java 进程先找到并结束它再重启。Run IDE (Frontend)或./gradlew --no-configuration-cache runIdeFrontend需要 backend 已在运行时使用用于 frontend JVM 调试。Run IDE (Split Mode)会自行启动 frontend因此不附加 frontend 调试。6.3 单体沙箱runIde只在你需要单体monolithic沙箱 IntelliJ 实例时使用./gradlew runIde。生产打包仍走bun run build:production运行时继续下载宿主平台 CLI。6.4 沙箱运行注意事项依据 AGENTS.md每个runIde*任务都通过 JVM 系统属性强制关闭 IntelliJ 反馈问卷platform.feedbackfalse、csat.survey.enabledfalse、editor.ux.survey.enabledfalse并开启idea.is.internaltrue内部模式从而启用 Split Mode 延迟模拟 widget 与 Internal Actions 菜单。停止沙箱应在沙箱 IDE 内File Exit退出而不是在 Gradle 运行页点 Stop——Stop 只调用CancellationTokenSource.cancel()IDE 永远收不到 forked JVM 的信号这正是孤儿 Java 进程的来源。同一 checkout 下不要同时启动第二个runIde*任务所有 run-IDE 任务共享同一个沙箱容器.intellijPlatform/sandbox/kilo.jetbrains/ide/plugins_runIde*prepareSandbox会重写运行中 IDE 的插件 jar导致热重载失败并报Failed to unload modified plugins: Kilo Code。七、开发 Gradle 属性Development Gradle Properties以下属性通过 Gradle 命令行-P传递或写在运行配置的 script parameters 字段中属性默认值说明kilo.splitModeServerPort0backend split-mode 服务端口。为0或省略时由 IntelliJ Platform Gradle Plugin 在任务运行时挑选空闲端口kilo.dev.storage.isolatedfalse为true时CLI 以XDG_*_HOME指向 worktree 根目录下的.kilo-dev/运行完全隔离开发存储与真实 Kilo 安装。仓库自带的 split-mode 运行配置默认开启kilo.dev.worktree.rootmonorepo 根用于解析.kilo-dev/的 worktree 根目录通常从 Gradle 工程目录自动检测仅在自动检测错误时覆盖示例固定 split-mode 端口并开启调试日志-Pkilo.dev.log.leveldebug -Pkilo.splitModeServerPort12345关闭存储隔离-Pkilo.dev.storage.isolatedfalse八、开发存储隔离Dev Storage Isolation当kilo.dev.storage.isolatedtrue时backend 在启动 CLI 子进程前会设置标准XDG_*_HOME环境变量全部指向 worktree 根目录下的.kilo-dev/.kilo-dev/ data/ - XDG_DATA_HOME (CLI 使用 .../data/kilo 存放 sessions、logs 等) config/ - XDG_CONFIG_HOME (CLI 使用 .../config/kilo 存放全局配置) state/ - XDG_STATE_HOME (CLI 使用 .../state/kilo 存放状态) cache/ - XDG_CACHE_HOME (CLI 使用 .../cache/kilo 存放缓存、bin)这样所有开发数据都与真实 Kilo 安装隔离。.kilo-dev/目录已被 gitignore首次运行自动创建。该实现位于KiloBackendCliManager.buildEnv()/devStorageEnv()测试见KiloBackendCliManagerEnvTest。注意 AGENTS.md 特别强调隔离只使用标准XDG_*_HOME不要引入KILO_DATA_DIR、KILO_GLOBAL_CONFIG_DIR等自定义环境变量——CLI 核心已通过xdg-basedir遵守XDG_*_HOME。仓库自带的Run IDE (Backend)、Run IDE (Frontend)、Run IDE (Split Mode)三个运行配置默认开启该隔离。九、调试日志属性Debug Logging Properties插件支持若干 JVM 系统属性-D用于本地调试在沙箱运行时最有用因为日志会镜像到 frontend 与 backend 各自的kilo.log*文件。9.1kilo.dev.log.level控制 Kilo 调试文件日志级别。支持值DEBUG、INFO、WARN、ERROR、OFF。默认INFO。设为DEBUG可开启详细的聊天追踪与惰性log.debug { ... }摘要。9.2kilo.dev.log.chat.content控制结构化聊天日志中出现多少聊天文本内容。支持值off无文本预览仅元数据preview经过清理、截断的预览full经过清理的完整内容默认off。AGENTS.md 补充说明该模式通过-Pkilo.dev.log.chat.contentmode传入同样支持off/preview/full三档。9.3kilo.dev.log.chat.preview.max当kilo.dev.log.chat.contentpreview时的最大预览大小。默认160AGENTS.md 中说明会被钳制在 1 到 2000 之间。9.4 日志文件位置在沙箱运行中Kilo 会为两端分别写入独立的开发日志文件目录为PathManager.getLogDir()报告的 IDE 沙箱日志目录Frontend 日志sandbox log dir/kilo-frontend/kilo.logBackend 日志sandbox log dir/kilo-backend/kilo.log轮转文件使用数字后缀kilo.log.0、kilo.log.1实践中位于当前运行的log_run*沙箱日志之下若不确定具体沙箱根目录可从运行中的沙箱实例打开 IDE 日志目录再寻找kilo-frontend/与kilo-backend/子目录9.5 推荐组合-Dkilo.dev.log.levelDEBUG -Dkilo.dev.log.chat.contentoff-Dkilo.dev.log.levelDEBUG -Dkilo.dev.log.chat.contentpreview -Dkilo.dev.log.chat.preview.max120建议先用off只有需要提示或工具载荷线索诊断问题时再切到previewfull仅用于短小的本地复现因为日志增长很快。十、CLI 集成协议Server ProtocolAGENTS.md 记录了插件与 Kilo CLI 的进程级协议理解它有助于排查连接与调试问题插件启动kilo serve --port 0由操作系统分配随机端口通过读取 stdout 中的listening on http://...:(\d)发现端口。通过环境变量KILO_SERVER_PASSWORD传入随机 32 字节十六进制密码用于 Basic Auth。每次 spawn 固定设置的环境变量KILO_CLIENTjetbrains、KILO_PLATFORMjetbrains、KILO_APP_NAMEkilo-code、KILO_ENABLE_QUESTION_TOOLtrue、KILO_DISABLE_CLAUDE_CODEtrue、KILOCODE_FEATUREjetbrains-plugin。除非基础环境已提供backend 会设置KILO_CONFIG_CONTENT使 JetBrains 启动的 CLI 进程默认对edit和bash权限发起询问。该协议与 VS Code 扩展packages/kilo-vscode/src/services/cli-backend/server-manager.ts使用的协议相同。会话事件调试可用script/dev/part-update.sh client session-id/backend session-id打印 frontend / backend 的message.part.delta文本追加 file.txt可保存输出。十一、发布流程Releasing完整发布流程见 packages/kilo-jetbrains/RELEASING.md此处提炼核心要点。11.1 两个独立版本JetBrains 插件有两个互相独立的版本号务必区分字段含义packages/kilo-jetbrains/package.json的version固定的 Kilo CLI release用于 OpenAPI 生成与运行时下载packages/kilo-jetbrains/gradle.properties的kilo.jetbrains.versionJetBrains Marketplace 插件版本发布被一个立即创建的jetbrains/vversiontag 锁定再由一个经过评审的 release PR 把关。tag 固定了将要发布的精确源码PR 中维护者评审并编辑版本与 changelog。11.2 发布前检查 CLI Pin发布前运行 pin 检查脚本bun .kilo/skills/release-jetbrains/script/check-pin.ts脚本会报告origin/main将锁定的 CLI、最新已发布的稳定 CLI、最新jetbrains/v*tag 携带的 CLI、kilo.cli.pinned是否为true以及所有运行时资产是否存在。本地测试不同 CLI pinbun .kilo/skills/release-jetbrains/script/set-pin.ts --latest cd packages/kilo-jetbrains ./gradlew typecheck ./gradlew test落地 pin 到main再发布bun .kilo/skills/release-jetbrains/script/set-pin.ts --latest --prset-pin.ts会拒绝其 CLI release 或运行时资产不存在的版本因此不会产生运行时下载 404 的 pin。11.3 创建 Release Tag 与 PR运行prepare-jetbrains-releaseworkflow输入参数输入值kindrcEAP 发布或stable默认 Marketplace 发布versionRC 为x.y.z-rc.n稳定版为x.y.zfrom_tag可选覆盖 changelog 范围的上一个 tag默认范围错误时才填示例kindrc version7.3.13-rc.1kindstable version7.3.1311.4 Changelog 范围默认值发布默认from_tag某版本首个 RC如7.3.13-rc.1最新的稳定 JetBrains tag后续 RC如7.3.13-rc.2同基础版本的上一个 RC稳定版如7.3.13最新的稳定 JetBrains tag忽略 RCfrom_tag只覆盖比较范围不改变发布目标提交。11.5 Review PR 并合并发布workflow 会创建或更新类似jetbrains/release/v7.3.13-rc.1的分支PR 更新两个文件文件用途packages/kilo-jetbrains/gradle.propertieskilo.jetbrains.version中的插件版本packages/kilo-jetbrains/CHANGELOG.md打包进插件的发布说明changelog 会被渲染进 JetBrainschange-notes出现在 Marketplace 与 IntelliJ 插件 UI 中。PR 可以改发布元数据但不会改变被构建的 tag 源码。11.6 合并与发布行为合并 release PR 后publish-jetbrainsworkflow 校验既有 tag 与 release PR 标记jetbrains/vversion然后从该 tag 发布版本Marketplace channelGitHub releasex.y.z-rc.neapPrereleasex.y.zdefaultStable release发布成功后还会触发publish-jetbrains-bundled以-Pkilo.cli.bundledtrue重建同一 tag签名并验证全平台插件 ZIP上传kilo-code-version-bundled.zip到同一个 GitHub Release。Bundled 构建保持kilo.cli.pinnedtrue只是把固定的 CLI release 资产嵌入插件运行时直接解压当前平台 CLI 而不再下载详见 docs/bundled-release-plan.md——该方案的存在是因为 Marketplace 对插件 ZIP 有 400 MB 上限bundle 版通过 GitHub Pages 自建插件仓库分发。11.7 安装 RC 构建RC 发布到eapchannel在 IntelliJ IDEA 中打开Settings Plugins。点击齿轮图标选择Manage Plugin Repositories。添加 EAP channel 仓库地址对应插件 ID。在 Marketplace 标签页搜索Kilo Code。11.8 所需 GitHub Actions Secrets首次发布前需按 RELEASE_TODO.md 完成一次性设置Secret用途KILO_MAINTAINER_APP_ID/KILO_MAINTAINER_APP_SECRET用于创建/更新 release PR 与立即 tag 的 GitHub App 凭据JETBRAINS_MARKETPLACE_TOKENMarketplace API 发布 tokenJETBRAINS_CERTIFICATE_CHAIN/JETBRAINS_PRIVATE_KEY/JETBRAINS_PRIVATE_KEY_PASSWORD插件签名的 PEM 证书链、私钥与密码11.9 手动恢复Manual Recoveryprepare workflow 创建了 tag 但没创建/更新 PR对同一版本重跑 workflow若 tag 仍指向同一锁定提交会被复用。publish 校验报 tag SHA 不符停下来手动检查不要随意移动、删除或重建 release tag。Marketplace 发布成功但 GitHub Release 上传失败手动创建或编辑既有 tag 的 GitHub Release使用合并 release PR 中评审过的 CHANGELOG.md 内容。需要手动创建 tagprepare workflow 无法推送时在合并 release PR 之前于锁定的origin/main提交上创建git fetch origin main git tag jetbrains/v7.3.13 locked-main-sha git push origin jetbrains/v7.3.13十二、常见问题速查Run IDE (Backend)启动即退出清理上一次 backend 的孤儿 Java 进程后重启。runIdeBackend/runIdeSplitMode启动前报coroutinesJavaAgentFile/Collection contains no element matching the predicate.intellijPlatform/ides/下解压的 IDE 不完整。健康检查ls .intellijPlatform/ides/*/lib/*.jar | wc -l应为数百个修复方式是移除.intellijPlatform/ides、.intellijPlatform/localPlatformArtifacts、.intellijPlatform/layoutIndex、.intellijPlatform/coroutines-javaagent.jar后重跑 Gradle 任务。生产构建失败确认kilo.cli.pinnedtrue——false是仅限本地开发的状态生产 Gradle 构建与 release 脚本会硬性失败。冷构建需要联网固定 pin 模式的冷构建通过generateOpenApiSpec下载固定 CLI releaseGradle 缓存命中的增量运行会跳过下载。十三、延伸阅读工程规范与模块放置、RPC 契约、EDT 线程约束见 packages/kilo-jetbrains/AGENTS.md完整发布流程tag、PR、publish、bundled、恢复见 packages/kilo-jetbrains/RELEASING.md首次发布一次性设置清单Marketplace、签名证书、Secrets见 packages/kilo-jetbrains/RELEASE_TODO.mdBundled CLI 全平台签名构建方案见 packages/kilo-jetbrains/docs/bundled-release-plan.md版本与脚本入口见 packages/kilo-jetbrains/package.json 与 packages/kilo-jetbrains/gradle.properties【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考