Kilo CLI 运行时架构全解析本地 Agent 引擎的守护进程、服务、持久化与 SDK 契约【免费下载链接】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/kilocodeKilo Code 的 CLIpackages/opencode/是项目的本地 Agent 引擎负责 Agent 执行、工具、会话、Provider 集成、配置、本地持久化、目录路由以及供编辑器客户端和 Kilo Console 使用的 HTTP 接口。本文以packages/kilo-docs/pages/contributing/architecture/cli-runtime.md为骨架结合仓库源码与实现细节完整梳理 CLI 运行时的核心概念、命令入口、多目录上下文隔离、认证边界、守护进程生命周期、持久化方案、SDK 契约与配置优先级帮助你在本地环境中理解、排查与二次开发 CLI 运行时。说明本文描述的是仓库定义的本地运行时行为不是云部署配置清单也不是对外部 API 的端点目录。Kilo CLI 本地运行时与托管的 Cloud Agent 会话是两套体系后者不属于本文范围。核心概念本地执行的基础术语理解 Kilo CLI 运行时需要先掌握一组与本地执行相关的术语。这些概念彼此关联构成了后续所有章节的基础。术语含义Kilo CLI 运行时packages/opencode/中的本地 Agent 引擎kilo serve服务器供编辑器客户端与 Kilo Console 使用的本地 HTTP 与 SSE 进程部分面向浏览器的路径也使用 WebSocket本地守护进程Local daemon由kilo daemon命令管理、可复用的独立kilo serve服务器目录上下文Directory context用于选择本地运行时状态的、经过规范化的本地文件系统目录本地运行时实例Local runtime instance单个 Kilo CLI 进程内、以目录为键的运行时上下文本地路由工作区Local routing workspace可选的路由上下文可解析到本地目录或远程目标Worktree 目录用作目录上下文的备用 git worktree 路径用于隔离并发工作进程共享状态Process-shared state单个 Kilo CLI 进程内、所有目录上下文共享的运行时服务状态Modes可配置的 Agent 预设控制工具、提示词、限制与行为MCP用于扩展 Agent 工具的协议关键边界是一个kilo serve进程可以托管多个本地运行时实例。目录键控的状态directory-keyed state彼此隔离而进程共享的服务状态process-shared service state则不隔离。这一区分是理解后面多目录上下文与快照慢速守卫等机制的前提。命令入口从 TUI 到编辑器托管服务器的七种启动路径CLI 运行时通过多个命令入口被拉起各自的运行时模型不同。下表按入口列出命令、调用方与运行时模型入口命令或调用方运行时模型交互式 TUIkilo可用时挂载到本地守护进程否则启动 Bun worker通过 RPC 发送 SDK 形态请求无头运行kilo run可用时使用 daemon attach否则回退到内嵌服务器 fetch附加运行kilo run --attach url定向连接显式运行中的kilo serve服务器显式 API 服务器kilo serve为外部本地客户端启动 HTTP SSE 服务器本地守护进程kilo daemon start启动可复用的独立kilo serve子进程浏览器控制台kilo console启动或复用本地守护进程并打开守护进程托管的/consoleUI编辑器托管服务器VS Code 或 JetBrains 客户端启动捆绑的kilo serve --port 0子进程归编辑器客户端所有不受守护进程管理器管理其中 TUI 的回退路径并非从 UI 线程直接调用内嵌 fetch。UI 线程启动worker.tsworker 的 RPC 方法构造请求后调用Server.Default().app.fetch()并把全局事件转发回 UI 线程。这条链路把UI 线程与服务器执行解耦避免阻塞渲染线程。从源码看kilo run的--attach选项在 run.ts 中声明为attach to a running kilo server (e.g., http://localhost:4096)且--attach模式下不需要本地实例instance: (args) !args.attach--dir指定的目录在附加模式下被解释为远端服务器上的路径。守护进程客户端在 client.ts 中通过KILO_NO_DAEMON环境变量决定是否启用自动挂载maybe()在守护进程不可用时记录警告并回退到内嵌服务器。一个服务器承载多个目录上下文每个运行中的编辑器宿主只启动一个编辑器托管的kilo serve服务器。该服务器可以同时处理工作区根目录以及额外 worktree 目录的编码会话不会为每个目录单独启动服务器进程。请求处理的三个阶段步骤发生什么为什么重要发送请求编辑器客户端在本地 API 请求中携带目录信息CLI 可以区分工作区根目录与 worktree 目录选择状态InstanceStore规范化目录并选择目录键控的本地运行时实例备用目录的会话保持隔离的运行时状态返回事件服务器通过共享的/global/eventSSE 流发布带目录元数据的事件编辑器客户端将事件路由到匹配的目录与会话视图这一区分对 Agent Manager worktrees 和 JetBrains 工作区缓存至关重要。目录键控状态保持隔离而进程级事件流与服务器持有的服务状态保持共享——快照慢速守卫snapshot slow-track guard就是一个典型例子。在实现层面InstanceStore位于 instance-store.ts它以Mapstring, Entry作为缓存Entry内保存一个DeferredInstanceContext用于去重并发启动——多个请求同时加载同一目录时只执行一次 boot其余请求等待同一个 deferred任何退出包括中断都会通过onExit完成 deferred 并清理失败条目避免遗留永不解析的条目导致后续 load/reload 永久挂起。实例销毁时通过注册的 cleanup hooksrunDisposers释放目录状态并发布server.instance.disposed总线事件。认证边界三重凭据体系各司其职CLI 运行时中存在三个相互独立的凭据边界。追踪请求路径或修改认证代码时务必把它们分开对待。边界保护对象归属方本地kilo serve访问对本地服务器的 HTTP、SSE 与部分 WebSocket 访问Kilo CLI 服务器与发起方本地客户端出站 Provider 认证模型 Provider、Kilo Gateway、目录catalog与索引访问Kilo CLI Provider 路由器与认证存储远程 MCP OAuth远程 MCP 服务器的浏览器授权与凭据Kilo CLI MCP 运行时本地kilo serve访问服务器 Basic Auth 是可选的当KILO_SERVER_PASSWORD非空时变为必需。默认用户名为kilo可用KILO_SERVER_USERNAME覆盖。在 serve.ts 中启动时若未设置KILO_SERVER_PASSWORD会打印警告KILO_SERVER_PASSWORD is not set; server is unsecured.路径或模式认证行为普通 HTTP 与 SSE配置了服务器密码时使用 BasicAuthorization头浏览器 WebSocket使用auth_token查询参数携带 base64 的username:password浏览器 WebSocket 构造函数无法设置任意请求头公共 UI 资源部分 manifest 与 icon 的 GET 路径绕过 Basic Auth使浏览器元数据可以加载PTY ticket 签发已认证的POST /pty/{ptyID}/connect-token需要预期的 ticket 头与允许的 OriginPTY ticket 连接GET /pty/{ptyID}/connect?ticket...绕过 Basic 中间件在 PTY handler 中消费单次使用、作用域绑定的 ticketPTY shell 子进程从派生出的用户 shell 环境中移除KILO_SERVER_PASSWORD与KILO_SERVER_USERNAMEPTY 连接支持两种面向浏览器的模式由当前 Console 与 VS Code Agent Manager 使用的 loopback 查询凭据模式auth_token以及由服务器 API 暴露的短时 ticket 模式。出站 Provider 认证Provider 认证记录使用api、oauth或wellknown变体存放在${Global.Path.data}/auth.json文件权限为0600。KILO_AUTH_CONTENT可提供进程内本地认证 JSON。此外还存在一个独立的 v2 多账号认证存储服务于面向账号的流程。路径行为直连 Provider使用 Provider 专属密钥、OAuth 记录、环境变量值与配置的端点Kilo Gateway通过 Gateway 客户端解析 Kilo 模型访问与模型目录匿名 Kilo若不存在 Kilo 密钥Provider loader 将 API 密钥值设为anonymousGateway 模型目录可回退到公共的免认证端点组织目录从配置、认证或环境变量解析出组织 ID 后Kilo 模型获取会携带组织 ID模型缓存Provider 模型结果缓存五分钟加载失败会使缓存失效以便重试自定义端点Provider 配置可覆盖端点与凭据选项索引认证先解析索引专属的 Kilo 配置再依次回退到 Provider 配置、认证记录、Provider 选项以及KILO_API_KEY/KILO_ORG_ID环境变量远程 MCP OAuth远程 MCP OAuth 归属 CLI 运行时。静态头仍然受支持对于 OAuth 服务器CLI 负责浏览器授权并将凭据存储在受保护的本地状态中编辑器客户端调用 CLI 拥有的流程而不是自行存储 MCP 凭据。目录路由与本地运行时实例实例路由按以下顺序选择目录上下文directory查询参数x-kilo-directory请求头服务器进程的 cwd。本地路由工作区的选择是独立的。会话工作区、workspace查询参数和KILO_WORKSPACE_ID可以选定工作区上下文。配置了KILO_WORKSPACE_ID时请求保持绑定在当前工作区运行时其他被选中的工作区通过工作区路由适配器解析到本地目录或远程目标。请求计划行为本地Local向请求处理器提供已解析的目录与可选的 workspace ID远程Remote将 HTTP 或 WebSocket 请求代理到适配器目标缺失工作区Missing workspace返回 workspace-not-found 响应工作区路由-本地Workspace-routing local将选中的本地路由与/console保留在本地服务器不代理远程 HTTP 代理响应可携带同步栅栏元数据sync fence metadata路由器在返回前会等待匹配的同步进度。InstanceStore会规范化目录键、通过 deferred 条目去重并发启动并通过注册的 cleanup hooks 释放目录状态。上述路由中间件位于 workspace-routing.tsWorkspaceRoutingMiddleware读取directory与workspace查询参数在 groups 中每个端点查询 schema 中展开构造Local / Remote / MissingWorkspace / InvalidWorkspace四种RequestPlan并为处理器提供WorkspaceRouteContext含 directory 与可选 workspaceID。forkTargetDirectory与workspaceProxyURL等辅助函数分别处理 fork 的显式目标目录与代理 URL 解析。核心子系统运行时内部的服务拼图子系统用途Agent 运行时编排消息、模型调用、权限、提问与多步执行工具注册表加载内置工具、Kilo 专属工具、MCP 工具以及就绪门控readiness-gated的语义搜索工具LSP 客户端提供诊断与语言智能配置服务合并全局、项目、组织、托管与运行时输入实例存储缓存规范化后的、按目录作用域的运行时上下文SQLite 与存储服务持久化结构化记录与剩余 JSON 持有的数据快照服务跟踪基于 git 的文件基线用于 diff 与回滚流程Provider 路由器解析直连 Provider、Kilo Gateway、自定义端点与凭据HTTP 服务器发布 REST、WebSocket 与 SSE 接口HTTP API 分组集中在 packages/opencode/src/server/routes/instance/httpapi/groups涵盖 config、control、event、file、global、instance、mcp、permission、project、provider、pty、question、session、sync、tui、workspace 等约 20 个分组中间件目录 middleware 中的 authorization、compression、cors-vary、error、fence、instance-context、proxy、schema-error、workspace-routing 共同构成请求管线。守护进程生命周期kilo daemon start|status|stop|restart管理一个独立的本地kilo serve子进程裸命令kilo daemon等价于kilo daemon start。kilo console调用相同的 start 路径因此会复用健康的守护进程而不是再派生第二个进程kilo console stop则别名到kilo daemon stop。区域行为状态文件${Global.Path.state}/daemon.json写入权限0600日志文件${Global.Path.log}/daemon.log创建权限0600端口分配对--port 0扫描4097..4116并选择可用端口子进程独立detached的kilo serve --hostname host --port port进程前台模式--foreground/-f保持调用命令挂在前台SIGINT、SIGTERM 或 SIGHUP 只停止它启动或复用的那个守护进程身份健康检查以 2 秒超时探测已认证的/global/health复用条件仅当进程存活、健康检查通过且安装版本匹配时才复用守护进程清理存在陈旧进程时先终止、清除陈旧状态再启动替代进程退出开关KILO_NO_DAEMON禁用客户端的自动挂载显式 daemon 命令仍可管理守护进程守护进程凭据与编辑器托管服务器的凭据不同。当前守护进程源码在 daemon.ts 中状态结构Daemon.State保存 pid、hostname、port、url、username、password、token、version、startedAt 与日志路径每次启动用randomUUID()生成新密码并写入 base64 Basic token。文件权限保护这条本地凭据记录而编辑器客户端则为每个托管服务器生成随机密码。实现细节还体现在端口扫描PortRange { start: 4097, end: 4116 }port()对--port 0逐个尝试端口监听测试全部占用时抛出 No available daemon ports in 4097-4116 错误进程锁所有 start/stop 通过Flock.withLock(kilocode-daemon, ...)串行化锁目录在状态目录下locks/超时 15 秒、陈旧 30 秒日志等待launch()以 detached 方式 spawn 子进程注入KILO_SERVER_USERNAME/KILO_SERVER_PASSWORD/KILOCODE_FEATUREdaemon环境变量随后通过正则匹配日志中的 kilo server listening on http://... 判断就绪默认 10 秒超时终止策略Windows 使用taskkill /pid /T类 Unix 使用进程组process.kill(-pid, ...)先 SIGTERM 等待 5 秒再 SIGKILL复用判定matches()会显式拒绝密码仍为默认kilo的旧状态并对 hostname、port、mdns、cors 等网络选项做逐项比对。持久化SQLite 为主、JSON 兜底SQLite 是默认的结构化存储。区域行为默认数据库${Global.Path.data}/kilo.db覆盖KILO_DB相对路径在数据目录下解析接受:memory:运行时 pragmaWAL journal、normal sync、5 秒 busy timeout、foreign keys、passive checkpoint、有界缓存Schema 变更Drizzle 迁移从编译二进制的捆绑 journal 或开发模式的迁移目录加载主要表Projects、sessions、messages、parts、todos、permissions、session messages、workspaces、sync events、accounts 与 account state遗留迁移首次建库时CLI 对 projects、sessions、messages、parts、todos、permissions 与 shares 执行一次性 JSON 到 SQLite 迁移数据库路径解析与 pragma 设置可在 db.ts 中确认KILO_DB为:memory:或绝对路径时直接使用否则拼接在Global.Path.data下连接建立后执行PRAGMA journal_mode WAL、PRAGMA busy_timeout 5000、PRAGMA foreign_keys ON等。部分 JSON 后备存储仍然保留会话 diff 仍使用session_diff存储路径配置、认证与部分本地状态文件各有归属方快照存储与 SQLite、JSON 存储相互独立。快照状态边界按 worktree 隔离的 git 基线快照基线为每个项目 worktree 使用独立的 git 目录${Global.Path.data}/snapshot/project-id/worktree-hash快照实现状态通过InstanceState按目录键控。一个Snapshot.Service同时拥有目录缓存之外的进程共享慢速快照守卫状态——当多个 Agent Manager worktrees 共用同一个kilo serve进程时这一区分至关重要。慢速初始跟踪具有守卫行为条件行为快速跟踪正常返回快照哈希慢速交互跟踪默认 10 秒后可提示继续等待或为该项目禁用快照托管 Agent Manager 回合发送snapshotInitialization: wait等待时不弹出内联提问使并发启动的会话保留基线可见的长跟踪短暂延迟后添加临时进度 part、更新 spinner完成时移除 part禁用选择将snapshot: false写入项目配置不销毁进行中的回合已忽略或未命中的超时中断或跳过跟踪并在活动服务作用域内抑制重复提示SDK 契约从 OpenAPI 到多语言客户端的生成管线CLI 服务器契约经由生成层与手写层流动位于packages/opencode/src/server/routes/instance/httpapi/的 EffectHttpApi分组定义路由packages/opencode/src/server/routes/instance/httpapi/public.ts将公共 OpenAPI 规范化为遗留兼容的请求与响应形态Kilo 专属 API 分组与处理器位于packages/opencode/src/kilocode/server/httpapi/通过狭窄的注入接缝进入共享 APIpackages/sdk/js/script/build.ts从 CLI OpenAPI 生成 TypeScript v2 客户端packages/sdk/js/src/v2/client.ts增加createKiloClient()包装器提供目录与工作区路由、Electron 与 Node 的 fetch 兼容性以及更清晰的空响应错误根目录./script/generate.ts运行 SDK 生成、输出被跟踪的 OpenAPI 产物、更新 CLI 文档并格式化输出JetBrains Gradle 构建生成构建本地 OpenAPI、规范化并生成 Kotlin OkHttp 客户端。服务端端点变更后必须重新生成已检入的 JavaScript SDK 输出不要手工编辑生成的客户端文件。配置优先级后加载者覆盖先加载者实例配置加载时后列出的来源覆盖先前的值顺序来源1遗留 Kilo 迁移2组织 modes3认证记录中的.well-known/opencode远程配置4全局配置文件5显式KILO_CONFIG文件6项目kilo.json[c]与opencode.json[c]文件及发现的配置目录7KILO_CONFIG_DIR目录8KILO_CONFIG_CONTENT9生效中的 Kilo Cloud 组织配置10托管配置目录11macOS 托管偏好12由运行时 flag 派生的权限、工具、压缩与插件行为全局配置文件从${Global.Path.config}加载。项目更新时优先更新在祖先.kilo或遗留.kilocode目录中发现的现有配置文件其次更新项目根目录的现有配置文件最后创建.kilo/kilo.json。全局索引设置可以携带 Provider 与存储默认值但全局indexing.enabled会被剥离使项目启用状态保持在有效实例配置中保持本地化。登录组织的 modes 在加载时成为普通 Agent 配置它们覆盖迁移后的遗留 modes且仍可被表中更靠后的配置源覆盖。运行时配置加载与面向编辑器的 JSON Schema 发布相互独立云端托管的 schema 用于改善kilo.json与kilo.jsonc的校验和补全但不会加载、应用或覆盖生效的运行时配置。新增或修改配置键时应遵循 CLI Config Schema 保持 CLI 源码与云端 overlay 对齐。全局与实例 SSE 事件流流作用域载荷/event单个本地运行时实例总线直接事件载荷直到实例销毁/global/event进程级多路复用总线带载荷的包装以及可用的目录、项目与工作区元数据两条流都会发送初始server.connected事件并每 10 秒发送一次心跳。VS Code 与 JetBrains 消费/global/event因此一个服务器连接即可为多个目录路由事件。Kilo Console已弃用已弃用。Kilo Console 浏览器界面及其kilo console启动器将在未来版本中移除。kilo console启动或复用守护进程、打开/console并打印 Console 启动 URL。浏览器启动 URL 内嵌守护进程 Basic 凭据使首次请求即可完成认证。区域行为前端packages/kilo-console/中的 Solid/Vite 应用服务器路由/console资源由 CLI UI handler 解析发布构建CLI 可执行文件构建将 Console 资源复制到二进制旁的bin/consoleSDKConsole 通过createKiloClient()调用生成的 JavaScript SDK发现机制Console 扫描4097..4116loopback 守护进程 URL对健康命中的进行排序然后回退尝试缓存 URL源码开发时可以从包输出目录托管构建好的 Console 资源或按需构建——这是开发行为不代表生产部署结论。代码库索引异步启动的语义搜索引擎packages/kilo-indexing/拥有索引引擎。CLI 桥默认注入索引插件除非默认插件被禁用然后在实例引导期间按规范化目录异步启动索引。区域行为引导KilocodeBootstrap派生索引初始化使实例启动不被阻塞Worker专用索引 worker 持有CodeIndexManager与搜索调用缓存CLI 桥按目录缓存 worker 条目并随实例一起销毁状态GET /indexing/status与indexing.status总线事件暴露进度工具仅当索引报告就绪后才注册semantic_search工具WorktreesAgent Manager 的.kilo/worktrees/与遗留.kilocode/worktrees/路径返回禁用状态空 VS Code 窗口扩展设置KILO_DISABLE_CODEBASE_INDEXINGvscode-no-workspace桥报告禁用状态Embeddings支持 Kilo、OpenAI、Ollama、OpenAI-compatible、Gemini、Mistral、Vercel AI Gateway、Bedrock、OpenRouter 与 Voyage 配置向量存储支持 Qdrant 与 LanceDB索引相关的桥接逻辑分布在 indexing.ts、indexing-worker.ts 与 indexing-worker-client.ts 中索引插件默认注入点位于 CLI 引导链路的KilocodeBootstrap。源码地图快速定位各子系统下表汇总 CLI 运行时各关注点在仓库中的源码位置关注点源码路径CLI 入口packages/opencode/src/cli/cmd/守护进程packages/opencode/src/kilocode/daemon/HTTP 服务器packages/opencode/src/server/目录与工作区路由packages/opencode/src/server/routes/instance/httpapi/middleware/workspace-routing.tsSQLitepackages/opencode/src/storage/db.ts快照packages/opencode/src/snapshot/index.ts、packages/opencode/src/kilocode/snapshot/track.tsSDKpackages/sdk/js/、script/generate.tsConsolepackages/kilo-console/、packages/opencode/src/kilocode/console/索引packages/kilo-indexing/、packages/opencode/src/kilocode/indexing.ts实际探索时cli/cmd 下同时存在serve.ts、run.ts、tui.ts、attach.ts、daemon相关命令及debug/子目录daemon 目录 含daemon.ts生命周期实现与client.ts客户端挂载逻辑。CLI 入口的命令实现分散在cmd/下数十个文件中可结合kilo --help按需深入。相关页面Architecture Overview —— 本地与托管执行的整体地图VS Code Extension —— 扩展宿主所有权、Agent Manager 与 webview 桥JetBrains Plugin —— 分体式客户端、捆绑服务器生命周期与工作区缓存Development Patterns —— API 生成、代码归属接缝与 fork 维护规则CLI Config Schema —— CLI 配置键的编辑器校验契约提示文中所有路径均为仓库根目录下的相对路径例如packages/opencode/src/kilocode/daemon/daemon.ts直接阅读这些文件可获取比本文更细的实现级信息。【免费下载链接】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），仅供参考