Kilo CLI 贡献指南：从环境搭建到提交高质量 PR 的完整实战手册-平芜编程栈

Kilo CLI 贡献指南：从环境搭建到提交高质量 PR 的完整实战手册

【免费下载链接】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（kilocode）开源仓库根目录的 CONTRIBUTING.md，系统梳理为 Kilo CLI 及周边生态（VS Code 扩展、JetBrains 插件、文档站）贡献代码的完整流程：包括前置环境（Bun、Java 21）、本地开发启动方式、各包级检查命令、代码修改护栏（Guardrails）、本地后端联调、以及提交流程与测试证据要求。读完本文，你将能独立完成从bun install到提交一份符合规范 PR 的全过程，并能用bin/kilodev、bun dev serve等工具在本地复现、验证自己的改动。

说明：本文涉及的仓库路径均以仓库根目录为基准，便于你直接点击跳转核对源码。

一、仓库概况：Kilo CLI 是一个怎样的项目

Kilo 是一个开源的 AI 编码代理（coding agent）平台，核心引擎位于 packages/opencode/，该目录同时承载 CLI、Agent 运行时、本地 HTTP server、会话管理与 TUI。从仓库根目录的 package.json 可以看到，Kilo 采用Turborepo + Bun workspaces的 monorepo 结构，packageManager固定为bun@1.3.14。

与贡献者最相关的几个包（依据 AGENTS.md 的 Monorepo 结构表）：

包路径	包名	职责
packages/opencode/	`@kilocode/cli`	核心 CLI：Agent、工具、会话、服务器、TUI，大多数改动发生在这里
packages/sdk/js/	`@kilocode/sdk`	自动生成的 TypeScript SDK，`src/gen/`不可手改
packages/kilo-vscode/	`kilo-code`	VS Code 扩展，含侧边栏聊天与 Agent Manager
packages/kilo-jetbrains/	`@kilocode/kilo-jetbrains`	JetBrains 插件（Kotlin）
packages/kilo-docs/	`@kilocode/kilo-docs`	文档站
packages/kilo-gateway/	`@kilocode/kilo-gateway`	Kilo 认证、模型路由、API 集成

Kilo CLI 是上游 opencode 的一个 fork，因此贡献规则中特别强调：尽量减少对共享代码的改动，Kilo 专属逻辑优先放在名字含kilocode的目录（如packages/opencode/src/kilocode/），并对共享文件中的改动用kilocode_change标记，以降低与上游的合并冲突（详见下文"代码修改护栏"）。

二、前置环境要求（Prerequisites）

贡献前需要准备两个关键运行时（CONTRIBUTING.md 的 Prerequisites 一节）：

Bun 1.3.14+：所有包统一依赖 Bun，根 package.json 中packageManager: "bun@1.3.14"即最低门槛。
Java 21：仅 JetBrains 插件需要。仓库级命令bun turbo typecheck与bun turbo test:ci会包含@kilocode/kilo-jetbrains，没有 Java 21 会直接失败。

Java 21 的安装方式（SDKMAN 推荐）

文档推荐通过 SDKMAN 安装 Eclipse Temurin 发行版：

# 安装 SDKMAN（如果尚未安装） curl -s "https://get.sdkman.io" | bash # 安装并激活 Java 21（Eclipse Temurin） sdk install java 21-tem sdk use java 21-tem # 验证 java -version

如果你不打算改动 JetBrains 插件，可以绕过 Java 依赖，只跑非 JetBrains 的检查：

bun turbo typecheck --filter=!@kilocode/kilo-jetbrains

补充一个来自仓库的细节：项目通过 Husky 管理 Git hooks，pre-push 钩子只在改动涉及 JetBrains 插件时才运行 JetBrains typecheck（见 packages/kilo-docs/pages/contributing/development-environment.md 的 Git Hooks 一节），所以 VS Code 专属、纯文档或纯 changeset 的推送并不强制要求 Java 环境。

三、本地开发：安装依赖并启动 Kilo CLI

3.1 安装依赖

在仓库根目录执行：

bun install

该命令会安装全部 workspace 包依赖。同时，根 package.json 的postinstall钩子会执行bun run --cwd packages/core fix-node-pty和bun run script/setup-git.ts，后者会在仓库本地设置merge.conflictStyle=zdiff3（AGENTS.md 的 Git conflict style 一节），让冲突包含共同祖先块，便于后续与上游合并时做结构化解析。

3.2 启动 CLI

bun dev

根 package.json 中dev脚本的真实展开是：

KILO_CLIENT=cli bun run --cwd packages/opencode --conditions=node src/index.ts

bun dev与bun run dev完全等价，二者都直接运行 packages/opencode/src/index.ts 这份本地源码，不会使用全局安装的kilo二进制。对于 VS Code 扩展，则使用bun run extension（详见第五节）。

四、常用检查命令（Common Checks）

从仓库根目录运行的三个基准命令：

bun install bun run lint bun run typecheck

几点关键说明（源码依据见根 package.json）：

bun run lint实际执行oxlint（使用 oxlint 而非 ESLint 作为默认 lint 器）。
bun run typecheck是对bun turbo typecheck的封装；如需绕过 Turbo 缓存，用bun turbo typecheck --force。
不要在仓库根目录运行bun test：根测试脚本故意输出do not run tests from root并以退出码 1 结束（package.json），强制开发者到各自拥有测试的包内运行。

4.1 CLI 检查

在packages/opencode/目录下：

bun run typecheck bun test bun test ./path/to/file.test.ts

后端/API 校验请参考仓库根目录的 TESTING.md：它详细介绍了用bun dev serve启动本地主分支后端，再用curl驱动验证的方法（详见本文第七节）。注意，改动packages/opencode/src/server/下的服务端端点后，必须从仓库根目录运行./script/generate.ts重新生成 packages/sdk/js/ 中的 SDK 与 OpenAPI 规范（/doc端点与类型化客户端才能保持同步）。

4.2 VS Code 扩展检查

在packages/kilo-vscode/目录下：

bun run typecheck bun run lint bun run test:unit bun run test bun run compile bun run package

其中compile用于开发构建，package用于产出生产扩展包（详见 packages/kilo-docs/pages/contributing/development-environment.md）。

4.3 文档检查

文档站是@kilocode/kilo-docs包，从仓库根目录运行：

bun run --filter @kilocode/kilo-docs test bun run --filter @kilocode/kilo-docs build bun run --filter @kilocode/kilo-docs dev

手动验证文档时，建议本地启动文档站、预览受影响页面，并检查改动链接与渲染内容。

五、开发 VS Code 扩展：构建与隔离启动

构建并启动扩展的核心命令有三条：

bun run extension # 构建并以开发模式启动 bun run extension:isolated # 构建并以持久化隔离状态启动 bun run extension:isolated:clean # 清除隔离状态后再构建启动

根 package.json 中这些脚本均指向packages/kilo-vscode/script/launch.ts（extension:isolated附加--isolated，extension:isolated:clean附加--isolated --clean）。

隔离模式的设计意图

extension:isolated：在独立的 VS Code 进程与独立的 XDG 存储（.kilo-dev/）中运行扩展，不影响你的主 VS Code profile 和真实 Kilo 配置。每次运行复用.kilo-dev/，因此已安装的扩展、VS Code 设置、Kilo 登录态、会话、配置、状态与缓存都会跨启动持久化。
extension:isolated:clean：启动前删除.kilo-dev/，模拟全新安装场景，同时把所有状态仍然保留在本仓库 checkout 内。

launch.ts会自动检测 macOS、Linux、Windows 上的 VS Code，支持以下覆盖方式：

选项	用途
`--app-path PATH`	指定具体 VS Code 可执行文件
`VSCODE_EXEC_PATH`	通过当前 shell 环境变量指定 VS Code 可执行文件
`--insiders`	优先使用 VS Code Insiders
`--workspace PATH`或末尾位置参数	打开指定工作区文件夹

例如测试扩展与示例项目的配合：

bun run extension:isolated -- ../sample-project bun run extension:isolated:clean -- ../sample-project

在 Windows PowerShell 下可通过环境变量指定可执行文件：

$env:VSCODE_EXEC_PATH = "C:\Users\me\AppData\Local\Programs\Microsoft VS Code\Code.exe" bun run extension

六、开发 JetBrains 插件（Kotlin）

JetBrains 插件位于 packages/kilo-jetbrains/，包内package.json定义了typecheck/test/test:ci脚本（packages/kilo-jetbrains/package.json），它们最终都委托给 Gradle。需要Java 21。

在packages/kilo-jetbrains/目录下：

./gradlew typecheck # 编译检查全部 Kotlin 源码 ./gradlew test # 运行全部测试（backend + frontend） ./gradlew --no-configuration-cache runIdeSplitMode # 启动本地 split-mode 沙箱；backend 会下载固定版本 CLI

关键设计（CONTRIBUTING.md 的 Developing the JetBrains Plugin 一节）：

推荐使用runIdeSplitMode（split-mode 沙箱）；./gradlew runIde仅用于 monolithic 沙箱。
JetBrains 的开发运行不会构建或打包 CLI 二进制，backend 在连接时自动下载固定（pinned）版本 CLI。
也可以从仓库根目录用 turbo filter 只跑 JetBrains 检查：

bun turbo typecheck --filter=@kilocode/kilo-jetbrains bun turbo test:ci --filter=@kilocode/kilo-jetbrains

七、用本地后端进行联调测试

7.1 定位到不同目录运行 CLI

默认情况下，bun dev在packages/opencode目录运行 Kilo CLI。想针对其他目录/仓库运行：

bun dev <directory>

想在仓库根目录自身运行：

bun dev .

7.2 从任意目录运行：`bin/kilodev`

bin/kilodev 是一个自定位（self-locating）启动器：它通过BASH_SOURCE解析出仓库根目录，然后以--cwd "$dir/packages/opencode" --conditions=browser方式调用本地源码入口（bin/kilodev）。不带参数启动时，它把 TUI 指向调用者所在目录；带参数时原样转发给 CLI。

一次性安装（推荐），在仓库根目录执行：

./bin/kilodev dev-setup

该命令会检测你的 shell、展示将要写入的内容、请求确认，然后向 rc 文件写入幂等块并保存带时间戳的原文件备份。重复执行是安全的——只有当片段发生变化时才重写。

标志	作用
`--yes`	跳过确认提示（适合 CI/容器）
`--print`	只打印片段，不触碰任何文件（便于管道处理）
`--dry-run`	显示将要发生的改动但不写入
`--shell <zsh\\|bash\\|fish\\|powershell>`	覆盖 shell 检测
`--rc <path>`	覆盖 rc 文件路径

手动替代方案（等价、无需调用 CLI）：

Unix：在~/.zshrc/~/.bashrc中添加alias kilodev='/path/to/kilocode/bin/kilodev'，或用fish_add_path /path/to/kilocode/bin。
Windows：将C:\path\to\kilocode\bin加入 PATH（系统环境变量），或在$PROFILE中添加function kilodev { & "C:\path\to\kilocode\bin\kilodev.cmd" @args }。

之后在任何位置使用：

cd ~/some/project kilodev # 打开 TUI，项目 = ~/some/project kilodev dev-setup --print # 打印别名行（用于脚本化） kilodev run --dir "$PWD" "…" # 子命令透传；run/serve 使用 --dir

注意：仓库中还提供了 Windows 版启动器 bin/kilodev.cmd。

7.3 构建本地二进制

编译独立可执行文件：

./packages/opencode/script/build.ts --single

该脚本来自 packages/opencode/script/build.ts，支持--single（单文件）、--skip-install、--baseline、--sourcemaps等标志，并会复制 tree-sitter WASM 资源。构建产物位于：

./packages/opencode/dist/@kilocode/cli-<platform>/bin/kilo

将<platform>替换为你的平台（例如darwin-arm64、linux-x64）。

7.4 理解`bun dev`与`kilo`的关系

开发期bun dev是已构建kilo命令的本地等价物，两者运行同一套 CLI 接口：

# 开发（仓库根目录） bun dev --help # 显示所有可用命令 bun dev serve # 启动无头 API server # 生产 kilo --help # 显示所有可用命令 kilo serve # 启动无头 API server

7.5 对接本地后端：环境变量覆盖

把 CLI 指向本地后端（例如本机 3000 端口的 Kilo API server）：

KILO_API_URL=http://localhost:3000 bun dev

这会重定向全部网关流量（认证、模型列表、模型路由、profile 等）到本地服务器。默认值为https://api.kilo.ai。

变量	默认值	用途
`KILO_API_URL`	`https://api.kilo.ai`	Kilo API（网关、认证、模型、profile）
`KILO_SESSION_INGEST_URL`	`https://ingest.kilosessions.ai`	会话导出 / 云同步
`KILO_MODELS_URL`	`https://models.dev`	模型元数据

VS Code 提示：仓库自带.vscode/launch.json，其中 "VSCode - Run Extension (Local Backend)" 启动配置通过"env": { "KILO_API_URL": "http://localhost:3000" }自动设置该变量（.vscode/launch.json）。

7.6 用 curl 驱动本地后端（源自 TESTING.md）

针对后端改动做端到端验证时，推荐用 TESTING.md 的curl工作流（在进程内测试可参考packages/opencode/test/kilocode/server/下的Server.Default().app.request(...)模式）。关键要点：

使用bun dev serve --port 0启动本地主分支后端（kilo serve运行的是$PATH上的生产二进制，不是本仓库代码）。
设置KILO_SERVER_PASSWORD后，用 Basic Auth 头请求：Authorization: Basic $(printf 'kilo:%s' "$KILO_SERVER_PASSWORD" | base64)，用户名固定为kilo。
每次请求需携带x-kilo-directory头（GET 请求则用?directory=<urlencoded>），否则InstanceMiddleware返回 400。
常用端点：GET /global/health（健康检查）、GET /doc（OpenAPI 端点全列表）、POST /session（建会话）、POST /session/$SID/prompt_async（发送消息）、GET /global/event（SSE 事件流，需curl -N关闭缓冲）。
服务器优雅退出由ServeCommand处理SIGTERM/SIGINT/SIGHUP，执行Instance.disposeAll()与server.stop(true)。

其他有用的后端环境变量：KILO_DB=":memory:"（跳过磁盘 SQLite）、KILO_DISABLE_DEFAULT_PLUGINS=true、KILO_WORKSPACE_ID=<id>、KILO_TELEMETRY_LEVEL=off、KILO_CONFIG_CONTENT='{…}'（内联 JSON 配置）。

八、代码修改护栏（Guardrails）

这组规则直接关系 CI 是否通过，务必逐条执行（CONTRIBUTING.md 的 Guardrails 一节）：

用户可见的改动通常需要 changeset：运行bunx changeset add或在.changeset/下添加文件。发布说明直接面向终端用户，应以用户视角、祈使语气撰写（AGENTS.md 的 Changesets 一节）。
改动服务端端点后重新生成 SDK：从仓库根目录运行./script/generate.ts。
改动受保护 URL 后更新源码链接：在packages/kilo-vscode/、packages/kilo-vscode/webview-ui/、packages/opencode/src/中新增或修改被守护的 URL 后，从仓库根目录运行bun run script/extract-source-links.ts，并提交更新后的 packages/kilo-docs/source-links.md。CI 会校验该文件是否过期。
共享packages/opencode/文件的改动要小且打标记：单行用// kilocode_change，代码块用// kilocode_change start/// kilocode_change end。不要在名字含kilocode的路径内添加这些标记（这些目录本身就是 Kilo 的专属新增，不会与上游冲突）。

此外，根 AGENTS.md 还列出了更多 CI 守护检查：bun run knip（未使用导出）、bun run check-kilocode-change、bun run script/check-opencode-annotations.ts --worktree、bun run script/check-workflows.ts等。改动对应区域时按表执行最小相关检查。

九、Issue 模板要求

通过 GitHub Web UI 打开 issue 时会自动套用模板；但通过gh issue create、API 或其他绕过 Web UI 的工具提 issue 时，需要自行补全模板必填字段，否则 compliance bot 可能自动关闭：

Bug report：必须包含Description；尽量补充 Plugins、Kilo 版本、复现步骤、截图和/或分享链接、操作系统、终端。
Feature request：标题以[FEATURE]:开头，勾选"已搜索重复项"复选框，并填写Describe the enhancement you want to request。
Question：填写Question字段。

十、Pull Request 期望

10.1 评审门槛

贡献指南的存在是为了保护维护者的评审时间，聚焦在"已准备好被评估"的工作上：

UI 改动：附上前后对比截图或视频。
逻辑改动：说明你如何验证其工作正常。

10.2 贡献所有权与 AI 协助

AI 与编码 Agent 是允许的，但贡献者对自己的提交负责。请求评审前，必须亲自理解改动、完成适当测试、能解释 diff，并理解改动与受影响包及仓库其余部分的关系。

若使用 Agent，请从仓库根目录启动，确保根 AGENTS.md 可用；改动涉及带独立指导的包时，还需阅读并遵循该包的AGENTS.md。
维护者可以关闭看起来缺乏可信贡献所有权或理解的 PR，包括贡献者无法解释或未认真 review 的 AI 辅助工作。

10.3 自动化与批量操作红线

不要批量提交 Agent 生成、未测试或弱评审的 PR；优先处理高影响/高优先级 issue，而不是开一堆投机性修复。批量低价值或重复 PR 可能被整体关闭并要求聚焦重提。
不要用自动化/Agent 批量创建 issue：先搜索已有 issue，只在有足够上下文时才开，优先报告最重要的问题。
反复无视贡献指南，或跨 issue/PR 的高量自动化/Agent 垃圾提交，可能导致维护者封禁相关账号。

10.4 测试证据（Testing Evidence）

每个标记为 ready for review 的 PR必须包含测试证据，裸写 "Not tested" 或 "N/A" 不达标。选择与所改文件匹配的检查：

运行相关命令并附结果；视觉类 CLI/扩展改动附截图或视频。
纯文档、纯配置改动也需要具体证据（如相关命令检查或本地预览）。
若无法完成相关命令，需在 PR 中同时给出：你尝试（或本应运行）的命令、阻止完成的阻塞原因、你改用的替代验证。
从 packages/kilo-docs/pages/contributing/development-environment.md 的 Testing Evidence 一节可以看到更多示例；Agent 的限制、本地资源约束、OOM 或"Agent 提示跳过测试"都不能豁免该要求。

一份评审就绪的 PR 描述应说明：解决什么问题、为什么需要、diff 之外评审者无法推断的实现取舍、以及如何测试验证。跳过逐文件清单、占位符等填充内容。

10.5 PR 标题规范

使用 Conventional Commits 风格的标题（AGENTS.md 的 Commits and PR Titles 一节给出有效类型feat、fix、docs、chore、refactor、test）：

feat: add MCP settings tab fix: correct Windows path handling docs: clarify issue template requirements chore: bump TypeScript to 5.8 refactor: extract diff renderer into a hook test: cover ServerManager orphan cleanup

十一、Issue 与 PR 生命周期

为控制积压，仓库会自动关闭一段时间内无活动的 issue 和 PR——这并非对质量的否定，而是因为旧条目容易丢失上下文。如果你仍在推进某项工作，欢迎随时 reopen 或新建 issue/PR。

维护者也可以关闭无视贡献指南、绕过必要上下文、或缺乏可信贡献所有权（尤其是 AI 辅助工作）的 issue/PR。

另外，Kilo 设有bug 赏金（Bug Bounties）：要获得资格，请确保你的 GitHub 账号已在 Kilo 账号中关联。

十二、风格偏好（Style Preferences）

编写代码时遵循以下偏好（CONTRIBUTING.md 的 Style Preferences 一节；根 AGENTS.md 的 Style Guide 一节有更细的强制规则）：

函数：逻辑保持在单个函数内，除非拆出能带来明确复用。
解构：避免不必要的解构（如const { a, b } = obj，直接用obj.a、obj.b保留上下文）。
控制流：避免else，优先提前 return。
类型：避免any。
变量：优先const；仅当单个词在上下文中确实含糊时才使用多词命名。
命名：可行时使用简洁的单词级标识符（pid、cfg、err、dir等）。
运行时 API：优先使用 Bun 辅助函数（如Bun.file()）。
不要留空catch块（AGENTS.md 明确禁止catch {}）；使用Promise.withResolvers<T>()创建 deferred promise。
Markdown 表格不要做列对齐填充（script/check-md-table-padding.ts会在 CI 强制此规则），可运行bun run script/check-md-table-padding.ts --fix自动修复。

十三、常见问题与调试建议

扩展不加载：检查 VS Code Developer Tools（Help > Toggle Developer Tools）中的报错。
Webview 不更新：尝试重载窗口（Developer: Reload Window）。
构建报错：确认已用bun install安装全部依赖。
根目录测试立即失败：这是预期行为，请改在包内运行测试而非根bun test。
调试输出：查看 VS Code Output 面板（View > Output）并选择 "Kilo Code"；Webview 问题可用 webview 内浏览器开发者工具（右键 > Inspect Element）排查。

结语

贡献 Kilo 的核心心法可以概括为：用对的命令在包的层级内验证、用kilocode_change标记保持与上游的合并友好、用测试证据支撑每一次 review-ready。按照本文的环境搭建、包级检查、本地后端联调与 PR 规范流程操作，你的改动就能顺畅地通过 CI 检查并获得评审。如果对后端联调细节需要更多示例，仓库根目录的 TESTING.md 与 packages/kilo-docs/pages/contributing/development-environment.md 是最佳的进一步阅读材料。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考