Kilo 開發模式指南從架構邊界到貢獻決策的完整實踐手冊【免費下載鏈接】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 倉庫 contributing/architecture/development-patterns.md 展開面向需要在packages/opencode上游 OpenCode 分支與 Kilo 自有包之間編寫架構敏感代碼的貢獻者。你將掌握如何判斷一次改動應該落在哪個源碼邊界、如何用kilocode_change標記管理對共享上游文件的修改、如何維護 CLI 服務器 API 與 SDK 生成契約以及上游合并upstream merge工作流中zdiff3與mergiraf的實際用法。從架構文檔到貢獻決策Kilo CLI 分叉fork了上游 OpenCode但并非簡單復制——它通過一套清晰的邊界策略把 Kilo 自有行為與上游共享代碼隔離。閱讀本文前建議先瀏覽 Architecture Overview 及相關子系統頁面理解系統分層后再動手修改面向架構的代碼。本頁的默認規則Default rule只有一條優先選擇 Kilo 自有的接縫seam而不是對共享 OpenCode 文件做大范圍改動。修改既有模塊時遵循鄰近代碼風格。使用本指南的標準流程在架構文檔中確定改動所屬的子系統選擇能夠承載該改動的最窄源碼邊界當公共表面public surface變化時更新生成產物或跨倉庫契約運行最小相關檢查以及受影響的倉庫守衛guards。改動應該落在哪里「位置決策表」是本頁最核心的速查工具它把改動形態映射到推薦位置與理由改動形態推薦位置或動作理由新增 Kilo CLI 行為additivepackages/opencode/src/kilocode/讓 Kilo 專屬行為不進入上游擁有的文件Kilo CLI 新增行為的測試packages/opencode/test/kilocode/避免共享測試只編碼 Kilo 行為必須修改共享 OpenCode 文件在共享文件中做小而窄的 import、路由或注入接縫并加kilocode_change標記保持上游 diff 窄小、合并評審一目了然VS Code、JetBrains、docs、indexing、UI、gateway、telemetry 改動既有的 Kilo 自有包這些包完全由 Kilo 擁有不要加kilocode_change標記CLI 服務器端點改動EffectHttpApi路由加 handler然后運行根目錄 SDK 生成器保持服務器契約與生成的 JavaScript SDK 對齊JetBrains API 契約改動修改共享 CLI OpenAPI讓 Gradle 重新生成本地 Kotlin clientKotlin client 在 JetBrains 構建期生成Kilo 專屬配置鍵改動同時更新 CLI Effect Schema 與 cloud JSON Schema overlay運行時接受與編輯器校驗是兩條獨立的跨倉庫路徑Docs 頁面移動或刪除更新導航并添加永久重定向保護外部鏈接與書簽以倉庫現狀驗證packages/opencode/src/kilocode/下確實聚集了大量 Kilo 專屬模塊agent-manager/、memory/、sandbox/、skill/、session/、tool/、server/等而packages/opencode/src/kilocode/server/下的listener.ts、server.ts、sse.ts則承載 Kilo 側服務器邏輯與表中「additive Kilo 行為放 kilocode 目錄」的原則一致。Kilo 自有邊界Kilo CLI 分叉上游 OpenCode新增行為應優先放在 Kilo 自有目錄與包優先除非必要否則避免packages/opencode/src/kilocode/對共享packages/opencode/src/文件的大范圍編輯packages/opencode/test/kilocode/只編碼 Kilo 行為的共享測試packages/kilo-vscode/、packages/kilo-jetbrains/、packages/kilo-docs/、packages/kilo-indexing/把 Kilo 專屬行為移進上游擁有的模塊共享文件中的窄 import / 路由接縫擴大上游合并沖突的重構這條邊界策略的收益是雙向的Kilo 專屬邏輯可以自由演進而上游同步時沖突面被限制在少數顯式標記的接縫點。共享 OpenCode 文件與 kilocode_change 標記當 Kilo 專屬代碼必須修改共享上游文件時使用kilocode_change標記。標記形式取決于改動形狀改動形狀標記形式單行行尾// kilocode_change多行塊// kilocode_change start與// kilocode_change end包裹共享路徑下的新文件文件頂部// kilocode_change - new fileJSX / TSX使用 JSX 注釋等價形式標記豁免marker exemptions適用于已經由 Kilo 擁有的路徑包括路徑名包含kilocode的目錄以及packages/kilo-vscode/、packages/kilo-ui/等 Kilo 包——這些位置不要添加標記。倉庫中的真實示例packages/opencode/src/session/compaction.ts中import 行帶行尾標記如import * as DateTime from effect/DateTime // kilocode_change同時存在// kilocode_change start/// kilocode_change end包裹的多行塊以及帶說明文字的標記如// kilocode_change start - allow safe pruning at cache-invalidating boundariespackages/opencode/src/agent/agent.ts中大量出現帶注釋說明的塊標記例如// kilocode_change start - rename build→code, add debug/orchestrator/ask, patch plan/explore。相關守衛Guards守衛何時運行bun run script/check-opencode-annotations.tsPR 觸及packages/opencode/時校驗共享 OpenCode 的 Kilo 編輯都已標注bun run script/check-opencode-promise-facades.ts服務適配器改動時防止在共享 Effect 服務中新增運行時支撐的 Promise facadesbun run check-kilocode-change在packages/kilo-vscode/內VS Code 或 Kilo UI 改動時確保完全 Kilo 擁有的包中不出現標記bun run script/check-workflows.ts工作流增刪改動時保持工作流 allowlist 顯式從實現看check-opencode-annotations.ts 的頭部注釋明確描述了三種覆蓋規則行內標注inline annotation、start/end 塊標注block annotation、以及// kilocode_change - new file頂部標注還包含豁免路徑邏輯與revert檢測當 diff 移除標記時給出提示印證了表格中「單行 / 多行塊 / 新文件」三種標記形態的判定標準。CLI 服務器 APICLI 服務器基于 EffectHttpApi構建發布兼容 OpenAPI 的 HTTP SSE 表面供 JavaScript SDK 與 JetBrains 構建期本地 Kotlin client 消費。規則理由共享路由定義在packages/opencode/src/server/routes/instance/httpapi/讓路由契約貼近運行時 handler公共規格歸一化在packages/opencode/src/server/routes/instance/httpapi/public.ts在 Effect 遷移期間保持兼容舊版的請求與響應形狀新增的 Kilo 分組與 handler 放在packages/opencode/src/kilocode/server/httpapi/減少對共享上游文件的編輯Kilo API 通過窄共享接縫注入保持上游 diff 小、標記位置清晰保留路由 span 與穩定屬性保持診斷與遙測可理解倉庫現狀與這兩條路徑完全對應共享路徑packages/opencode/src/server/routes/instance/httpapi/下含api.ts、errors.ts、lifecycle.ts、public.ts、server.ts及groups/、handlers/、middleware/Kilo 側packages/opencode/src/kilocode/server/httpapi/則提供groups/18 個分組如agent-builder、memory、sandbox、telemetry、session-import等、對應的handlers/、public.ts、server.ts與session-fork.ts。值得注意的細節Kilo 側的 public.ts 提供matchLegacyKiloOpenApi它對歸一化后的 OpenAPI 規格做運行時調整例如將/config/rules的scope查詢參數約束為const: project、為/kilo/profile的balance、kiloPass等字段包裝 nullable 類型、為/kilo/fim補充 SSE 流式響應結構并遞歸執行rebrand把 OpenCode→Kilo、opencode.local→kilo.local、opencode serve→kilo serve。而 server.ts 展示了接縫注入的典型寫法通過Layer.provide聚合 18 個 handler 分組并在provideListener中疊加errorLayer、compressionLayer、corsVaryFix、fenceLayer、CORS 中間件與KiloViewers.defaultLayer該行以// kilocode_change標注說明它是注入到共享文件中的窄接縫。SDK 生成CLI Runtime 的 SDK 契約 描述了生成管線的全部細節貢獻者只需遵守幾條短規則變更動作新增或修改 CLI 服務器端點路由與 handler 編輯完成后運行根目錄./script/generate.tspackages/sdk/js/src/v2/gen/下的 JavaScript SDK 生成文件不要手工編輯JavaScript SDK 包裝器行為編輯手寫的packages/sdk/js/src/v2/client.tsJetBrains 生成的 Kotlin client讓 Gradle 從歸一化 OpenAPI 重新生成本地 client這條規則的含義是「生成文件是產物、手寫文件是源頭」任何端點形狀變化都必須回流到生成器重新產出否則 SDK 與服務器契約會脫節。CLI 配置 Schema運行時配置加載與編輯器校驗是兩條獨立路徑。新增 Kilo 專屬配置鍵需要兩處改動Kilo-Org/kilocode倉庫中的 CLI Effect SchemaKilo-Org/cloud倉庫中的 JSON Schema overlay。具體工作流參見 CLI Config Schema。這種雙倉庫分工的原因在于運行時是否接受該鍵CLI 側 Schema 校驗與編輯器是否提示該鍵cloud 側 JSON Schema 補全是解耦的改動也必須分別落地。模塊導出模式新增公共 API 時優先在模塊內部使用扁平的 ESM 導出當分組訪問對調用方有幫助時再從 index 文件做命名空間重導出// packages/opencode/src/session/session.ts export const create fn(CreateSchema, async (input) { // ... }) export const list fn(ListSchema, async (input) { // ... }) // packages/opencode/src/session/index.ts export * as Session from ./session實際調用時盡量導入具體導出當需要保留既有 API 或分組訪問能提升可讀性時使用命名空間形態Session.create。既有的 Kilo 命名空間仍然有效不要僅為了風格而重構它們。Tool 實現模式Tool 使用Tool.define(id, Effect.gen(...))定義配合 Effect Schema 校驗與類型化執行export const ExampleTool Tool.define( example, Effect.gen(function* () { return { description: Example tool, parameters: Schema.Struct({ value: Schema.String, }), execute(args) { return Effect.succeed({ title: args.value, metadata: {}, output: args.value, }) }, } }), )在packages/opencode/src/tool/tool.ts中可以找到Tool.define配合Effect.gen的真實實現骨架。實踐要點先復用已有的 tool helpers、權限門permission gates與遙測約定再考慮引入新抽象測試應該驗證實現行為而不是在 mock 中重復邏輯。構建系統領域工具鏈包管理器Bun workspaces任務編排TurborepoCLI 可執行文件packages/opencode/script/build.ts中的 Bun compile 構建VS Code 擴展與 webviewsesbuildJetBrains 插件Gradle、Kotlin JVM toolchain 21、構建期本地 OpenAPI 生成類型檢查通過bun turbo typecheck運行tsgoJetBrains 用 Gradle compile 檢查測試包級 Bun test、Vitest 或 Gradle test視包而定DocsNext.js、Markdoc、Mermaid 與自定義 Markdoc 組件文檔改動規范新增或移動文檔頁面時在pages/下創建頁面更新lib/nav/中對應的導航文件刪除或移動路由時添加重定向使用緊湊的 markdown 表格單元格不要填充空格文檔圖片路徑使用/docs前綴。這與倉庫結構吻合packages/kilo-docs/lib/nav/下有 12 個導航 TS 文件packages/kilo-docs/pages/下是 Markdoc 內容目錄。源碼地圖以下路徑相對于倉庫根目錄幫助你快速定位各類代碼關注點源碼路徑Tool 定義 APIpackages/opencode/src/tool/tool.tsTool 示例packages/opencode/src/tool/read.ts服務器 APIpackages/opencode/src/server/routes/instance/httpapi/公共 OpenAPI 歸一化packages/opencode/src/server/routes/instance/httpapi/public.tsKilo 路由接縫packages/opencode/src/kilocode/server/httpapi/JavaScript SDK 生成packages/sdk/js/script/build.ts與script/generate.tsJetBrains client 生成packages/kilo-jetbrains/backend/build.gradle.kts上游合并自動化script/upstream/上游合并工作流bun install會運行script/setup-git.ts把倉庫本地的合并沖突風格設置為zdiff3。base 感知base-aware的沖突標記讓手工解決與語法感知工具都更有用。script/upstream/下的自動化會在合并前應用 transforms強制合并操作使用zdiff3并對剩余的文本沖突運行mergiraf。合并腳本要求安裝mergiraf。在script/upstream/目錄下使用bun run analyze.ts --version tag bun run merge.ts --version tag --dry-run bun run merge.ts --version tag三個命令分別對應分析某上游 tag 的差異、以 dry-run 方式預演合并、執行實際合并。工作流要點在合并工作落地之前確保 Kilo 專屬邏輯已抽離、共享接縫窄小、標記準確、CI 守衛通過。相關頁面Architecture Overview —— 系統分層與閱讀路徑CLI Runtime —— 本地運行時歸屬與 SDK 契約CLI Config Schema —— 跨倉庫配置鍵工作流【免費下載鏈接】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），僅供參考