Kilo JetBrains 插件 CLI 版本钉住CLI Pin完整指南pin / unpin / regen 工作流与源码级原理【免费下载链接】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导读jetbrains-cli-pin是 Kilo 仓库内一套面向 JetBrains 插件开发与发布的 CLI 版本管理技能它通过bun .kilo/skills/jetbrains-cli-pin/script/cli-pin.ts一条命令即可完成钉住到最新发布版 CLIpin、改用本地仓库 CLIunpin、本地 CLI 快速重建regen与清空全部构建残留clean四种操作并在每次操作前强制清理当前工作树中的所有 CLI 二进制与构建产物避免 pin/unpin 切换时的状态泄漏。读完本文你将掌握两个独立控制项pin 模式与钉住版本的准确含义、四条子命令的完整执行步骤、被清理产物的完整清单、Bun 路径提示文件的作用以及背后 Gradle 任务链generateOpenApiSpec、buildRepoCli、stageRepoCli的实现细节并理解kilo.cli.pinnedfalse仅限开发、不可发布这一硬性约束。本文基于仓库中的 SKILL.md 展开并结合其实现脚本与构建脚本进行源码级佐证。一、两个控制项Pin 模式与钉住版本Kilo JetBrains 插件的 CLI 行为由两个相互独立的值共同决定理解它们是理解整套 pin/unpin 工作流的前提控制项位置含义Pin 模式Pin modegradle.properties 中的kilo.cli.pinnedtrue默认 在构建/连接时下载已发布的 CLIfalse 构建并捆绑本地仓库 CLI钉住版本Pinned versionpackage.json 中的versionpinnedtrue时决定下载并据此生成代码的是哪个 GitHub CLI 发布版本其中钉住到最新pin to latest指的是kilo.cli.pinnedtrue且package.json的version指向最新的稳定 CLI 发布解除钉住unpin指的是kilo.cli.pinnedfalse并捆绑一份新构建的本地 CLI。从源码看cli-pin.ts中的pinned()与setPinned()直接读写gradle.properties中的kilo.cli.pinned行report()则同时读取package.json的version并在操作结束时打印当前状态见 cli-pin.ts。实际仓库中 gradle.properties 的默认配置为kilo.cli.pinnedtrue且文件中的注释明确说明false仅用于本地开发从本地源码生成客户端并捆绑本地二进制不可发布——生产构建遇到false会直接失败。二、命令总览与统一用法所有命令都从你想影响的那个工作树的仓库根目录运行脚本内所有路径均为相对路径因此它们解析到当前工作树而不是主 checkout。bun .kilo/skills/jetbrains-cli-pin/script/cli-pin.ts command [--no-verify]支持的命令如下命令执行步骤pin清理 → 设置kilo.cli.pinnedtrue→ 移除仓库 CLI 的 Bun 路径提示 → 通过set-pin.ts --latest把package.json提升到最新发布该脚本会校验发布资产→ 用一次冷gradlew clean typecheck验证unpin清理 → 设置kilo.cli.pinnedfalse→ 写入仓库 CLI 的 Bun 路径提示 →:backend:buildRepoCli全新构建 CLI→:backend:stageRepoCli→ 断言已暂存的kilo-cli.zip存在 → 用gradlew typecheck验证regen未钉住状态下的快速开发循环刷新仓库 CLI 的 Bun 路径提示 →rm -rf dist→buildRepoCli→stageRepoCli。拒绝在kilo.cli.pinnedfalse之外的状态运行clean仅执行共享的产物清理--no-verify用于跳过 Gradle 验证构建只做文件重写与清理适合离线环境或没有 Java 21 时使用。cli-pin.ts还内置了--help-h输出未传命令或传了未知命令都会打印用法说明并以非零码退出见 cli-pin.ts。三、四条命令的源码级执行细节3.1 pin钉住到最新发布的 CLIpin分支的执行顺序见 cli-pin.tsclean()清理全部 CLI/pin 构建产物setPinned(true)把gradle.properties中的kilo.cli.pinned改为trueremoveBunHint()删除 Bun 路径提示文件——钉住模式下不应依赖本地 Bun调用bun .kilo/skills/release-jetbrains/script/set-pin.ts --latest将package.json的version提升到最新稳定发布除非带--no-verify否则执行冷构建验证./gradlew clean typecheck --no-configuration-cachecwd 为packages/kilo-jetbrains。冷构建会通过generateOpenApiSpec下载钉住的 CLI 发布因此需要网络与 Java 21report()打印最终状态。关于第 4 步set-pin.ts 承担了版本解析与资产校验--latest会调用latest()拉取 GitHub release 列表只保留形如vX.Y.Z、非 draft、非 prerelease 的稳定版本并按 semver 降序取第一个随后missing()会核对 6 个必需的平台资产kilo-darwin-arm64.zip、kilo-darwin-x64.zip、kilo-linux-arm64.tar.gz、kilo-linux-x64.tar.gz、kilo-windows-arm64.zip、kilo-windows-x64.zip是否齐全缺失即报错拒绝见 pin-common.ts。因此cli-pin.ts的注释明确表示不重复实现 release/asset 校验而是复用set-pin.ts。3.2 unpin改用本地仓库 CLIunpin分支见 cli-pin.tsclean()setPinned(false)writeBunHint()写入仓库 CLI 模式所需的 Bun 路径提示./gradlew :backend:buildRepoCli --no-configuration-cache——该任务在内部执行rm -rf dist并产出一份全新的单平台二进制./gradlew :backend:stageRepoCli --no-configuration-cache——该任务设置了upToDateWhen { false }强制重新执行确保暂存的 zip 与本次构建一致断言packages/kilo-jetbrains/backend/build/generated/kilo-cli-res/kilo-cli.zip存在否则抛错除非带--no-verify否则./gradlew typecheck --no-configuration-cache验证report()。3.3 regen未钉住状态下的快速开发循环regen分支见 cli-pin.ts先检查pinned()若仍处于钉住状态则直接抛错regen requires the unpinned state; run unpin firstwriteBunHint()rm -rf packages/opencode/dist——清掉旧平台二进制残留:backend:buildRepoCli→:backend:stageRepoCli断言暂存 zip 存在并report()。它不做gradlew clean因此比unpin快得多适合在本地改完 CLI 源码后反复重建、重暂存、重跑插件。3.4 clean只做清理clean分支只调用clean()并打印状态适合在切换模式前主动重置工作树。四、被清理的产物清单与最危险的泄漏clean()见 clean.ts先执行./gradlew clean --quiet再做兜底的目标删除覆盖以下产物产物路径仓库 CLI 二进制packages/opencode/dist/暂存的 CLI 压缩包packages/kilo-jetbrains/backend/build/generated/kilo-cli-res/kilo-cli.zip生成的属性 / 校验和 / OpenAPI 客户端packages/kilo-jetbrains/backend/build/generated/编译后的资源打进 classpath 的捆绑 zippackages/kilo-jetbrains/backend/build/resources/CLI 下载缓存packages/kilo-jetbrains/backend/build/cli-cache/这些路径全部被 gitignore因此清理永远不会触碰受版本控制的文件。其中暂存的kilo-cli.zip是最危险的泄漏源一旦未钉住构建把它放进backend/build/resources/main/运行时就会优先使用捆绑 zip 而不是下载而增量构建正是让一个过期的kilo-cli.zip在 pin↔unpin 翻转后存活的元凶。因此完整gradle clean是唯一可靠的复位手段。clean.ts的头部注释还特别指出backend/build.gradle.kts中基于条件sourceSets/dependsOn的接线只有在干净的build/目录下才能产出正确包这也解释了为什么每次切换模式都必须全量清理。另一个值得注意的细节clean()对packages/opencode/dist是整树删除rm -rf因为build.ts只对它所构建的平台执行rm -rf dist旧平台目录可能残留。五、Bun 路径提示Bun Path Hint在仓库 CLI 模式下Gradle 的generateOpenApiSpec任务通过bun run --conditionsbrowser ./src/index.ts generate运行本地 CLI 源码。IDE 启动的 Gradle 运行时PATH可能被精简导致解析不到bun。为此unpin/regen会写入一个被 gitignore、仅属于当前工作树的提示文件packages/kilo-jetbrains/.gradle/kilo-cli-pin.properties文件内容为bun.pathabsolute path由 backend/build.gradle.kts 消费Gradle 通过fileContents(...).asText读取该文件解析bun.path行作为仓库 CLI 相关任务的 Bun 可执行路径缺省回退为bun。pin会删除该文件因为钉住模式不应依赖本地 Bun。从 cli-pin.ts 看bunPath()优先取Bun.which(bun)找不到再回退到当前进程的process.execPath。六、底层构建接线Gradle 任务链如何响应 pin 状态理解kilo.cli.pinned如何驱动构建是理解这套脚本设计意图的关键。在 backend/build.gradle.kts 中pinned gradleProperty(kilo.cli.pinned).orElse(true)、repoCli !pinned、bundled gradleProperty(kilo.cli.bundled).orElse(false)、downloadsCli repo !bundled见 L25-L28sourceSets根据模式动态挂载资源目录下载模式挂载generatedChecksums仓库 CLI / 捆绑模式挂载generatedCli见 L43-L50generateOpenApiSpec同时接收cliVersion来自package.json与repo标志钉住时从 GitHub 下载发布资产未钉住时从本地packages/opencode源码生成见 L64-L76buildRepoCli在packages/opencode目录执行bun run script/build.ts --single --skip-install见 L78-L82stageRepoCli将packages/opencode/dist/kilocode/cli-os-arch/bin/打包成kilo-cli.zip并强制outputs.upToDateWhen { false }见 L100-L106compileKotlin与processResources均按模式挂依赖下载模式依赖writeCliChecksums仓库 CLI 模式依赖stageRepoCli见 L181-L194。此外kilo.cli.pinned与kilo.cli.bundledtrue不能同时成立仓库 CLI 模式与发布版 CLI 捆绑模式互斥二者同时开启会直接error(...)见 L52-L54。在运行时层面AGENTS.md 说明默认情况下插件不捆绑 CLI 二进制连接时由 backend 下载package.json钉住版本对应的 GitHub Release 资产backend资源中会包含写有cli.version与cli.pinned的kilo.properties由writeKiloProperties任务生成见 build.gradle.kts供 split-mode RPC 与运行时使用。发布用的捆绑构建则通过-Pkilo.cli.bundledtrue且保持kilo.cli.pinnedtrue实现把所有钉住平台的 CLI 发布资产暂存进kilo-cli.zip运行时检测到该资源后只解压当前平台不再下载。七、验证构建与--no-verify所有验证构建都传--no-configuration-cache确保改动后的kilo.cli.pinned被重新读取而不是由磁盘上的 Gradle 配置缓存直接提供旧值pin的验证是冷构建会通过generateOpenApiSpec下载钉住的 CLI 发布需要网络访问与 Java 21离线环境请使用--no-verifyunpin的验证gradlew typecheck在已有本地构建缓存时可跳过下载但冷构建同样需要 Java 21。八、发布红线kilo.cli.pinnedfalse不可发布kilo.cli.pinnedfalse仅限开发不可发布。生产 Gradle 构建、script/build-version.sh 与发布脚本都会在false时硬失败——build-version.sh会检测到该行并输出 kilo.cli.pinnedfalse is a dev-only mode and cannot be released随后以非零码退出。因此在发布前必须先运行pin恢复为true。从发布协作的角度AGENTS.md 还给出了一套配套的检查/提升命令check-pin.ts检查当前钉住版本是否最新set-pin.ts --version x.y.z --pr或--latest --pr把经过本地验证的版本提升以 PR 形式合并到mainJetBrains 发布会锁定origin/main上已合并的该值。九、与其他技能与文档的关系版本提升与发布门控逻辑位于release-jetbrains技能SKILL.mdjetbrains-cli-pin复用了它的set-pin.ts与pin-common.ts辅助函数构建接线的背景说明见 AGENTS.md 的 CLI Integration 与 CLI Pinning, Unpinning, and Bumping 章节完整的任务编排可对照 cli-pin.ts 与 clean.ts 两个实现脚本逐行阅读。十、快速参考速查表场景命令切换到最新发布版 CLI 并冷验证bun .kilo/skills/jetbrains-cli-pin/script/cli-pin.ts pin同上但离线 / 无 Java 21bun .kilo/skills/jetbrains-cli-pin/script/cli-pin.ts pin --no-verify切换到本地仓库 CLIbun .kilo/skills/jetbrains-cli-pin/script/cli-pin.ts unpin未钉住状态下重建本地 CLIbun .kilo/skills/jetbrains-cli-pin/script/cli-pin.ts regen仅清理全部 CLI/pin 产物bun .kilo/skills/jetbrains-cli-pin/script/cli-pin.ts clean查看帮助bun .kilo/skills/jetbrains-cli-pin/script/cli-pin.ts --help检查钉住版本是否最新bun .kilo/skills/release-jetbrains/script/check-pin.ts钉住到指定版本 / 最新并本地验证bun .kilo/skills/release-jetbrains/script/set-pin.ts --version x.y.z/--latest【免费下载链接】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），仅供参考