Kilo 开发模式指南：从架构边界到贡献决策的完整实践手册

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 文件做大范围改动。修改既有模块时，遵循邻近代码风格。

使用本指南的标准流程：

1. 在架构文档中确定改动所属的子系统；
2. 选择能够承载该改动的最窄源码边界；
3. 当公共表面（public surface）变化时，更新生成产物或跨仓库契约；
4. 运行最小相关检查以及受影响的仓库守卫（guards）。

改动应该落在哪里

「位置决策表」是本页最核心的速查工具，它把改动形态映射到推荐位置与理由：

以仓库现状验证：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 自有目录与包：

这条边界策略的收益是双向的：Kilo 专属逻辑可以自由演进，而上游同步时冲突面被限制在少数显式标记的接缝点。

共享 OpenCode 文件与 kilocode_change 标记

当 Kilo 专属代码必须修改共享上游文件时，使用kilocode_change标记。标记形式取决于改动形状：

标记豁免（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 boundaries）；packages/opencode/src/agent/agent.ts中大量出现带注释说明的块标记，例如// kilocode_change start - rename build→code, add debug/orchestrator/ask, patch plan/explore。

相关守卫（Guards）

从实现看，check-opencode-annotations.ts 的头部注释明确描述了三种覆盖规则：行内标注（inline annotation）、start/end 块标注（block annotation）、以及// kilocode_change - new file顶部标注，还包含豁免路径逻辑与revert检测（当 diff 移除标记时给出提示），印证了表格中「单行 / 多行块 / 新文件」三种标记形态的判定标准。

CLI 服务器 API

CLI 服务器基于 EffectHttpApi构建，发布兼容 OpenAPI 的 HTTP + SSE 表面，供 JavaScript SDK 与 JetBrains 构建期本地 Kotlin client 消费。

仓库现状与这两条路径完全对应：共享路径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 契约 描述了生成管线的全部细节，贡献者只需遵守几条短规则：

这条规则的含义是「生成文件是产物、手写文件是源头」：任何端点形状变化都必须回流到生成器重新产出，否则 SDK 与服务器契约会脱节。

CLI 配置 Schema

运行时配置加载与编辑器校验是两条独立路径。新增 Kilo 专属配置键需要两处改动：

1. Kilo-Org/kilocode仓库中的 CLI Effect Schema；
2. Kilo-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 中重复逻辑。

构建系统

文档改动规范

新增或移动文档页面时：

• 在pages/下创建页面；
• 更新lib/nav/中对应的导航文件；
• 删除或移动路由时添加重定向；
• 使用紧凑的 markdown 表格，单元格不要填充空格；
• 文档图片路径使用/docs前缀。

这与仓库结构吻合：packages/kilo-docs/lib/nav/下有 12 个导航 TS 文件，packages/kilo-docs/pages/下是 Markdoc 内容目录。

源码地图

以下路径相对于仓库根目录，帮助你快速定位各类代码：

上游合并工作流

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