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