Kilo 平台架构全景：从本地 CLI 运行时到云端执行边界的完整地图

Kilo 平台架构全景从本地 CLI 运行时到云端执行边界的完整地图【免费下载链接】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 官方架构文档packages/kilo-docs/pages/contributing/architecture/index.md为骨架系统梳理 Kilo 的仓库定义架构本地运行时与编辑器客户端、Kilo Cloud 共享服务、以及托管产品运行时三大层的职责划分与调用关系。读完本文你将掌握kilo serve服务器、本地守护进程、Cloud Agent 会话运行时、Kilo Gateway 等核心边界如何协同工作并能在实际贡献代码时快速定位自己改动属于哪一层、该看哪份子系统文档。文档范围说明架构文档约定的是稳定的系统边界与跨贡献者的契约。特性级实现细节以源码为准静态源码展示的是代码路径与可部署面不代表生产环境的启用开关、流量、留存策略或供应商配置。如何阅读这些架构页面架构页面覆盖两个仓库、多个子系统。按你正在进行的改动类型选择阅读路径贡献者路径建议阅读顺序本地 CLI 或编辑器客户端架构总览 → CLI Runtime → VS Code Extension 或 JetBrains Plugin托管平台或自动化架构总览 → Cloud Platform → Automation Services安全评审架构总览 → Cloud Platform → Cloud Security面向架构的实现对应架构页面 → Development PatternsCLI 配置归属或关键变更CLI Runtime → CLI Config Schema → Development Patterns仓库边界架构跨越两个仓库架构文档明确声明一个容易忽略的前提Kilo 的架构页面跨越两个独立仓库。当前仓库GitHub_Trending/ki/kilocode对应文档中的Kilo-Org/kilocode而Kilo-Org/cloud仓库承载全部托管端服务。仓库内容Kilo-Org/kilocode即当前仓库Kilo CLI 运行时、本地守护进程、Kilo Console、VS Code 扩展、JetBrains 插件、JavaScript SDK、代码库索引、Kilo Gateway 客户端、遥测、文档与共享 UI 包Kilo-Org/cloudWeb 控制平面、Kilo Gateway 路由、Cloud Agent 会话运行时、自动化、生成式应用预览与部署服务、KiloClaw、Gas Town、计费及支撑 Workers注意本文所有包路径均相对当前仓库根目录cloud仓库内的路径仅作命名引用不在此仓库内。三大架构层本地、云共享服务、托管运行时层职责典型边界本地运行时与客户端运行本地编码会话并将编辑器界面连接到同一个本地 agent 引擎Kilo CLI 运行时、kilo serve服务器、本地守护进程、Kilo Console、VS Code 扩展、JetBrains 插件Kilo Cloud 共享服务处理托管身份、授权、模型路由、计费、编排与共享产品服务Web 控制平面、Kilo Gateway、Workers、队列、Durable Objects、持久化托管产品运行时与自动化运行编码、应用生成、助手、安全分析与多 agent 编排等有界的云工作Cloud Agent、Automation Services、App Builder、Security Agent、KiloClaw、Gas Town、Wasteland核心原则本地执行与托管执行是相互独立的边界。编辑器客户端只与本地kilo serve服务器通信只有真正需要云端编码工作时托管自动化才会启动 Cloud Agent 执行会话。贯穿全文的核心术语术语含义Kilo Code覆盖本地客户端、Kilo CLI 运行时与 Kilo Cloud 服务的总产品Kilo CLI 运行时位于packages/opencode/的本地 agent 引擎掌管工具、会话、配置、持久化与 provider 路由kilo serve服务器面向编辑器客户端与 Kilo Console 的本地 HTTP SSE 进程部分面向浏览器的路径也使用 WebSocket本地守护进程daemon由kilo daemon命令管理的、可复用的分离式kilo serve服务器目录上下文Directory context用于选择本地运行时状态的规范化本地文件系统目录本地运行时实例单个 Kilo CLI 进程内按目录键控的运行时上下文本地路由工作区可解析到本地目录或远程目标的可选路由上下文Worktree 目录用作隔离并发工作的目录上下文的备用 git worktree 路径Web 控制平面承载身份、组织授权、计费、产品配置与 API 编排的 Kilo Cloud 应用层Kilo Gateway第一方托管的模型路由边界Cloud Agent托管编码会话能力一个 Cloud Agent 执行会话即一次托管运行当前会话运行时实现在services/cloud-agent-next/cloud 仓库核心执行脊柱一条脊柱两条执行路径三大层呈现为两种主要执行形态本地客户端请求与托管云工作。整体调用关系如下Mermaid 图为架构文档原图两条执行路径对比路径起点运行位置要点本地编码Kilo CLI、Kilo Console、VS Code 或 JetBrains开发者机器上的 Kilo CLI 运行时编辑器客户端与本地kilo serve服务器通信本地运行时拥有编码会话直接或经 Kilo Gateway 发送模型请求托管工作Webhook、源码托管事件、命令、调度或托管产品Kilo Cloud 服务需要编码时由 Cloud Agent 执行云服务负责协调工作只有需要仓库变更的流程才启动 Cloud Agent 执行会话这一区分至关重要使用编辑器并不会把编码会话搬进 Cloud Agent。云服务还可以在不启动 Cloud Agent 的情况下路由模型请求、投递聊天事件、分发通知、托管生成式应用并协调相邻托管边界。相邻托管边界核心脊柱之外的云产品目录核心执行脊柱并不是完整的云产品目录。以下服务族与托管运行时附着在脊柱上服务于特定产品流程边界角色拓扑或工作流安全评审Automation Services将命令、源码托管事件、标签、Webhook 与调度转化为有界工作Automation ServicesTrust boundariesApp Builder协调生成式应用的编码、预览、构建与部署边界Cloud PlatformPreview and deploymentSecurity Agent同步安全发现并分析风险选定的深度分析可启动 Cloud AgentCloud PlatformSync and cleanupKiloClaw协调 owner 作用域内的托管助手运行时Cloud PlatformKiloClaw ingressGas Town 与 Wasteland协调多 agent 仓库工作与协作公共路径Cloud PlatformTrust boundaries本地入口点与客户端一个引擎多种表面以下本地表面均位于当前仓库。每个入口共享同一个packages/opencode/运行时引擎但有着不同的进程模型与连接策略表面当前仓库中的包运行时模型Kilo CLI TUIpackages/opencode/交互式本地客户端支持守护进程 attach 与 worker 后备两条路径kilo runpackages/opencode/无头 prompt 执行支持显式 attach、守护进程 attach 或内嵌后备kilo servepackages/opencode/面向本地客户端的 HTTP SSE 服务器Kilo Console已废弃packages/kilo-console/packages/opencode/由启动或复用的本地守护进程在/console提供的浏览器 UIVS Code 扩展packages/kilo-vscode/扩展宿主启动一个共享的编辑器自有kilo serve服务器经 HTTP 全局 SSE 路由 webviewSDK 目录选择本地运行时实例JetBrains 插件packages/kilo-jetbrains/分离式 Swing 插件后端模块启动一个编辑器自有kilo serve服务器并按目录缓存工作区客户端从源码看kilo serve的启动契约kilo serve命令实现位于 packages/opencode/src/cli/cmd/serve.ts。关键行为命令描述为starts a headless kilo server并通过withNetworkOptions注入网络参数服务按请求经x-kilo-directory头加载实例因此启动时无需预先存在全局的项目InstanceContext源码注释明确标注instance: false若未设置KILO_SERVER_PASSWORD会输出Warning: KILO_SERVER_PASSWORD is not set; server is unsecured.警告启动后打印三种地址urls.bind绑定地址、urls.local本地地址与 bind 不同时打印、urls.network网络地址提供优雅关闭路径注册 parent watchdog编辑器宿主被硬杀时进程退出、KiloSessions.drainIngestForShutdown()排空会话摄取、InstanceRuntime.disposeAllInstances()释放全部实例并监听SIGTERM/SIGINT/SIGHUP三个信号。serve与run共用的网络参数定义在 packages/opencode/src/cli/network.ts参数默认值说明--port0随机端口监听端口--hostname127.0.0.1监听主机名--mdnsfalse启用 mDNS 服务发现会默认把 hostname 改为0.0.0.0--mdns-domainkilo.localmDNS 自定义域名--cors[]额外允许 CORS 的域名参数解析遵循显式 CLI 参数优先于全局配置config.server.*的规则例如mdns与port只有在命令行显式出现时才覆盖全局配置否则回退到配置值见resolveNetworkOptionsNoConfig实现。kilo run的三种连接模式kilo run [message..]的实现位于 packages/opencode/src/cli/cmd/run.ts源码注释概括了三种模式非交互默认发送单条 prompt将事件流输出到 stdout会话空闲即退出交互式本地kilo --mini以进程内服务器无外部 HTTP启动分离式底部输入模式交互式 attachkilo --mini --attach连接正在运行的 kilo server 并对其执行交互模式。常用参数摘自 yargs builder--continue/-c继续最近会话、--session/-s按 ID 继续、--fork分支会话、--model/-m以provider/model格式选择模型、--format json输出原始 JSON 事件、--attach url显式连接运行中的服务器如http://localhost:4096、--password/--username提供 Basic Auth默认取KILO_SERVER_PASSWORD/KILO_SERVER_USERNAME或kilo、--dir指定运行目录attach 模式下为远端路径、--auto自动批准未被显式拒绝的权限危险、--file/-f附加文件到消息attach 模式下单文件上限 10 MiB。云服务族托管端的职责划分托管服务族位于 cloud 仓库。下表呈现文档给出的边界划分边界主要源码路径cloud 仓库角色Kilo Cloudapps/web/services/承载身份、计费、路由、产品配置、自动化与有界执行服务的托管平台仓库Web 控制平面apps/web/授权、配置与 API 编排的托管应用层Kilo Gatewayapps/web/src/app/api/gateway/apps/web/src/lib/ai-gateway/本地集成在本仓库packages/kilo-gateway/第一方模型路由边界与本地客户端集成Cloud Agentservices/cloud-agent-next/托管编码会话能力按策略选择沙箱分配Automation Servicesservices/code-review-infra/、services/auto-triage-infra/、services/auto-fix-infra/、services/security-auto-analysis/、services/security-sync/、services/webhook-agent-ingest/触发器驱动的评审、分流、修复、安全与配置化 Webhook 流程相邻托管边界services/app-builder/、services/kiloclaw/、services/gastown/、services/wasteland/及支撑服务App Builder、KiloClaw、Gas Town、Wasteland、聊天、通知与支撑服务支撑包本仓库内的辅助能力当前仓库包角色packages/kilo-indexing/Kilo CLI bridge 背后的按目录异步代码库索引引擎packages/sdk/js/面向本地服务器 API 的生成式 JavaScript 客户端与手写包装层packages/kilo-gateway/Kilo CLI 运行时使用的本地 Kilo Gateway 客户端集成packages/kilo-console/由本地守护进程在/console提供的已废弃浏览器 UISDK 契约链路摘自 CLI RuntimeEffectHttpApi组定义于packages/opencode/src/server/routes/instance/httpapi/public.ts 将公共 OpenAPI 归一化为兼容旧版的请求与响应形状packages/sdk/js/script/build.ts从 CLI OpenAPI 生成 TypeScript v2 客户端packages/sdk/js/src/v2/client.ts 中的createKiloClient()包装器提供目录与工作区路由、Electron/Node fetch 兼容性。修改服务器端点后必须重新生成受检的 JavaScript SDK 产物不要手改生成文件。架构页面索引继续深入的地图系统边界页面页面覆盖内容CLI Runtime本地执行模式、守护进程、服务器认证、路由、持久化、快照、SDK、配置、SSE、Kilo Console 与索引VS Code Extension共享本地kilo serve归属、webview bridge、Agent Manager、PTY、恢复、打包资源与构建产物JetBrains Plugin分离式模块、RPC、打包本地kilo serve生命周期、Kotlin SDK、恢复与远程开发约束Cloud Platform托管服务清单、Cloud Agent 拓扑、共享云边界与相邻托管运行时Automation Services触发器驱动的 Workers、队列、回调、归属与有界执行路径Cloud Security云信任边界、数据流、持久化、隔离、控制与第三方分类开发页面页面覆盖内容Development Patterns代码归属决策、共享文件接缝、SDK 生成、校验守卫与 fork 维护CLI Config Schema跨仓库配置契约的运行时加载与编辑器校验分离路径相关页面CLI Runtime — 本地运行时、服务器、路由、持久化与 SDK 契约Cloud Platform — 托管层、Cloud Agent 拓扑与相邻托管边界Cloud Security — 跨切面信任边界、控制与共享责任Development Patterns — 代码归属决策与贡献者工作流Development Environment — 环境搭建指南Ecosystem — 相关项目与集成落地建议面向贡献者的导航清单先判断改动落在哪一层本地引擎改动走packages/opencode/与 CLI Runtime托管逻辑属于 cloud 仓库编辑器表面分别看 VS Code Extension 与 JetBrains Plugin。涉及配置键时按 CLI Runtime 确认配置优先级再按 CLI Config Schema 同步 CLI 源码与编辑器校验 schema。涉及服务器契约时修改packages/opencode/src/server/routes/instance/httpapi/后重新生成 SDK并确认 public.ts 的兼容层无需调整。涉及认证时区分三条凭据边界——本地kilo serve访问、出站 provider 认证、远程 MCP OAuth分别追踪请求路径。涉及安全评审时以 Cloud Security 的信任边界为基准不要以本文的静态源码路径断言生产配置。已废弃提醒Kilo Console 浏览器界面及其kilo console启动器已被标记为废弃将在未来版本中移除涉及该模块的改动应优先评估迁移方案。【免费下载链接】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），仅供参考