☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
Kilo JetBrains 插件开发全指南：从环境搭建、本地构建到发布与调试
2026/9/13 9:46:27 网站建设 项目流程

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/kilocode

Kilo 是面向 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.md）
shared/定义 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 等），而不能依赖 JCEF（JBCefBrowser）或 Compose——JCEF 在远程开发中因前端进程在客户端、显示在宿主而不可用。

二、环境准备（Prerequisites）

开发本插件需要三样东西：

  1. Bun：用于执行 package 构建脚本（bun run build等），仓库根目录的bunfig.toml与package.json均以 Bun 为包管理与脚本运行时。

  2. JDK 21+：Gradle 与 IntelliJ Platform SDK 的硬性要求。用java -version确认版本。推荐的安装方式是 SDKMAN：

    # 安装 SDKMAN（若尚未安装） curl -s "https://get.sdkman.io" | bash # 安装并激活 Java 21（Eclipse Temurin 发行版） sdk install java 21-tem sdk use java 21-tem

  3. IntelliJ IDEA：用于把插件跑在沙箱化（sandboxed）的 IDE 实例中。

三、Fresh Worktree 与 Monorepo 集成

仓库是一个 Bun workspace 单仓（monorepo），JetBrains 插件位于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 --filter=@kilocode/kilo-jetbrains

5.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 -Pproduction=true。

5.5 CLI 固定（Pin）机制

gradle.properties中两个关键开关共同决定了构建形态（依据 gradle.properties 与 AGENTS.md）：

配置项含义
kilo.cli.pinned=true默认且唯一可发布的状态：使用package.json中固定的 CLI release，OpenAPI 客户端从固定版本生成
kilo.cli.pinned=false仅限本地开发：从本地packages/opencode/源码生成客户端并打包本地构建的 CLI 二进制；生产构建与发布脚本会直接失败
# packages/kilo-jetbrains/gradle.properties（节选） kilo.jetbrains.version=7.1.6 kilo.cli.pinned=true org.gradle.configuration-cache=true org.gradle.caching=true org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m

本地想用仓库里的 CLI 开发时，切换kilo.cli.pinned=false后执行./gradlew :backend:buildRepoCli；它构建packages/opencode/dist/@kilocode/cli-<os>-<arch>/bin/，stageRepoCli会把本地 CLI 打包进插件。注意冷构建时（固定 pin 模式）generateOpenApiSpec需要联网下载固定的 CLI release。

六、运行插件（Sandbox）

6.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 / frontend

  • Run 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.feedback=false、csat.survey.enabled=false、editor.ux.survey.enabled=false），并开启idea.is.internal=true（内部模式），从而启用 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.level=debug -Pkilo.splitModeServerPort=12345

关闭存储隔离：

-Pkilo.dev.storage.isolated=false

八、开发存储隔离（Dev Storage Isolation）

当kilo.dev.storage.isolated=true时，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.content=<mode>传入，同样支持off/preview/full三档。

9.3kilo.dev.log.chat.preview.max

  • 当kilo.dev.log.chat.content=preview时的最大预览大小。
  • 默认：160（AGENTS.md 中说明会被钳制在 1 到 2000 之间）。

9.4 日志文件位置

在沙箱运行中，Kilo 会为两端分别写入独立的开发日志文件，目录为PathManager.getLogDir()报告的 IDE 沙箱日志目录：

  • Frontend 日志：<sandbox log dir>/kilo-frontend/kilo.log
  • Backend 日志：<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.level=DEBUG -Dkilo.dev.log.chat.content=off
-Dkilo.dev.log.level=DEBUG -Dkilo.dev.log.chat.content=preview -Dkilo.dev.log.chat.preview.max=120

建议先用off；只有需要提示或工具载荷线索诊断问题时再切到preview；full仅用于短小的本地复现，因为日志增长很快。

十、CLI 集成协议（Server Protocol）

AGENTS.md 记录了插件与 Kilo CLI 的进程级协议，理解它有助于排查连接与调试问题：

  • 插件启动kilo serve --port 0（由操作系统分配随机端口），通过读取 stdout 中的listening on http://...:(\d+)发现端口。
  • 通过环境变量KILO_SERVER_PASSWORD传入随机 32 字节十六进制密码，用于 Basic Auth。
  • 每次 spawn 固定设置的环境变量：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。
  • 除非基础环境已提供，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/v<version>tag 锁定，再由一个经过评审的 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 pin：

bun .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 --pr

set-pin.ts会拒绝其 CLI release 或运行时资产不存在的版本，因此不会产生运行时下载 404 的 pin。

11.3 创建 Release Tag 与 PR

运行prepare-jetbrains-releaseworkflow，输入参数：

输入值
kindrc（EAP 发布）或stable（默认 Marketplace 发布）
versionRC 为x.y.z-rc.n，稳定版为x.y.z
from_tag可选，覆盖 changelog 范围的上一个 tag，默认范围错误时才填

示例：

kind=rc version=7.3.13-rc.1
kind=stable version=7.3.13

11.4 Changelog 范围默认值

发布默认from_tag
某版本首个 RC（如7.3.13-rc.1）最新的稳定 JetBrains tag
后续 RC（如7.3.13-rc.2）同基础版本的上一个 RC
稳定版（如7.3.13）最新的稳定 JetBrains tag（忽略 RC）

from_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 会被渲染进 JetBrains<change-notes>，出现在 Marketplace 与 IntelliJ 插件 UI 中。PR 可以改发布元数据，但不会改变被构建的 tag 源码。

11.6 合并与发布行为

合并 release PR 后，publish-jetbrainsworkflow 校验既有 tag 与 release PR 标记jetbrains/v<version>，然后从该 tag 发布：

版本Marketplace channelGitHub release
x.y.z-rc.neapPrerelease
x.y.zdefaultStable release

发布成功后还会触发publish-jetbrains-bundled：以-Pkilo.cli.bundled=true重建同一 tag，签名并验证全平台插件 ZIP，上传kilo-code-<version>-bundled.zip到同一个 GitHub Release。Bundled 构建保持kilo.cli.pinned=true，只是把固定的 CLI release 资产嵌入插件，运行时直接解压当前平台 CLI 而不再下载（详见 docs/bundled-release-plan.md——该方案的存在是因为 Marketplace 对插件 ZIP 有 400 MB 上限，bundle 版通过 GitHub Pages 自建插件仓库分发）。

11.7 安装 RC 构建

RC 发布到eapchannel，在 IntelliJ IDEA 中：

  1. 打开Settings > Plugins。
  2. 点击齿轮图标，选择Manage Plugin Repositories。
  3. 添加 EAP channel 仓库地址（对应插件 ID）。
  4. 在 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 发布 token
JETBRAINS_CERTIFICATE_CHAIN/JETBRAINS_PRIVATE_KEY/JETBRAINS_PRIVATE_KEY_PASSWORD插件签名的 PEM 证书链、私钥与密码

11.9 手动恢复（Manual Recovery）

  • prepare workflow 创建了 tag 但没创建/更新 PR：对同一版本重跑 workflow，若 tag 仍指向同一锁定提交会被复用。
  • publish 校验报 tag SHA 不符：停下来手动检查，不要随意移动、删除或重建 release tag。
  • Marketplace 发布成功但 GitHub Release 上传失败：手动创建或编辑既有 tag 的 GitHub Release，使用合并 release PR 中评审过的 CHANGELOG.md 内容。
  • 需要手动创建 tag（prepare 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.pinned=true——false是仅限本地开发的状态，生产 Gradle 构建与 release 脚本会硬性失败。
  • 冷构建需要联网：固定 pin 模式的冷构建通过generateOpenApiSpec下载固定 CLI release；Gradle 缓存命中的增量运行会跳过下载。

十三、延伸阅读

  • 工程规范与模块放置、RPC 契约、EDT 线程约束：见 packages/kilo-jetbrains/AGENTS.md
  • 完整发布流程（tag、PR、publish、bundled、恢复）：见 packages/kilo-jetbrains/RELEASING.md
  • 首次发布一次性设置清单（Marketplace、签名证书、Secrets）：见 packages/kilo-jetbrains/RELEASE_TODO.md
  • Bundled 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），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

LangChain 1.0与MCP协议：AI工具集成标准化实践
2026/9/13 9:45:38 网站建设

LangChain 1.0与MCP协议：AI工具集成标准化实践

1. LangChain 1.0与MCP协议深度解析LangChain作为当前最热门的AI应用开发框架之一&#xff0c;其1.0版本在工具集成方面做出了重大改进。其中最具突破性的特性就是与MCP&#xff08;Model Context Protocol&#xff09;协议的深度集成。MCP是一种开放协议&#xff0c;它标准化了…...

阅读更多 →
深入解读 OpenObserve 内部 API 公共基础设施：openobserve-api-common 的提取器、通用类型与认证体系
2026/9/13 9:44:34 网站建设

深入解读 OpenObserve 内部 API 公共基础设施：openobserve-api-common 的提取器、通用类型与认证体系

深入解读 OpenObserve 内部 API 公共基础设施&#xff1a;openobserve-api-common 的提取器、通用类型与认证体系 【免费下载链接】openobserve Open source observability platform for logs, metrics, traces, RUM, Session replay, pipelines, SLO and LLM observability. A…...

阅读更多 →
Keep 告警管理指南：一个入口完成告警聚合与根因定位
2026/9/13 9:41:56 网站建设

Keep 告警管理指南：一个入口完成告警聚合与根因定位

Keep 告警管理指南&#xff1a;一个入口完成告警聚合与根因定位 【免费下载链接】keep The open-source AIOps and alert management platform 项目地址: https://gitcode.com/GitHub_Trending/kee/keep Keep 是一个开源的 AIOps 告警管理平台&#xff1a;把 Prometheus…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询