好今天我们聊一个非常带劲的话题Kilo Code 项目整体结构设计。不整那些虚头巴脑的领域介绍我直接说人话。Kilo Code 是一个对话驱动的本地代码助手说得再直白一点它要做的事情是你在一个对话框里用自然语言提需求它去理解你的项目结构、读代码、甚至直接动手改代码然后给你一个可验证的结果。这类项目这两年特别火但大多数做出来的东西都停留在“套壳调用大模型接口”的阶段——能聊天、能写点小片段但一碰到真实的工程场景就露怯。原因很简单没有整体结构设计。我写这篇文章就是想从项目结构的视角把 Kilo Code 这类工具从“能用”拉到“好用”的层面上拆解一遍。文章会覆盖分层思路、模块边界、核心数据结构、任务状态机这些关键点也会把我实际踩过的坑串进去。适合正在做代码助手、Agent 工具、或者想把大模型能力揉进本地工具链的开发者参考。1. 项目设计的第一性问题对话驱动的代码工具到底难在哪动工之前我建议所有准备做类似项目的人都先想清楚一个问题你做的不是一个聊天机器人你做的是一台“有手”的机器。聊天机器人只需要把话接住就行而代码助手必须对代码库产生真实影响——它要读文件、改文件、创建文件这个过程还会跨多轮对话持续进行。这就带来三个普通聊天项目根本不会遇到的难题。第一个难题是状态一致性。用户在对话框里说“把这个函数的错误处理完善一下”你不能真的只盯着那一个函数看你得知道用户当前打开的是哪个文件、光标在什么位置、这个函数依赖了哪些模块、上一次对话里你改了什么。这些信息分散在编辑器、文件系统、LSP 诊断、对话历史好几个地方如果没有一个统一的地方把它们攒起来你的助手就会“失忆”。Kilo Code 的解决方案是引入一个独立的上下文收集层把散落的状态聚合成一个上下文包往下游传。第二个难题是任务的不确定性。模型生成一段修改代码很容易但“修改一个文件”可能涉及多个步骤先定位符号、再生成 diff、再执行写入、再验证语法。每个步骤可能成功也可能失败还可能因为用户中途改了主意被打断。这种流程管理不能靠在大模型调用后面硬接几行代码来实现你需要一个显式的任务状态机让每一步的迁移都有据可循。第三个难题是安全边界。一个能写文件的 Agent如果没有权限控制就是一颗定时炸弹。Kilo Code 必须知道“当前这个会话有没有资格修改这个项目”还要保证 A 项目的上下文不会串到 B 项目。这个能力必须在项目结构设计时预留位置而不是事后再打补丁。我之所以把这三个问题叫“第一性问题”是因为它们是这个项目的根。根如果歪了后面长得再茂盛也撑不住。下面所有的模块拆分、数据流设计本质上都是在回应这三个问题。2. 整体架构分层与核心数据流设计2.1 四层架构依赖方向比命名更重要Kilo Code 的整体架构我归纳成了四层UI 层负责渲染对话界面、文件改动预览、任务进度展示。这一层只做展示和交互不承载任何业务判断。Agent 核心层包含会话管理器、事件总线、任务调度器。这一层是大脑负责理解用户意图、拆分任务、调度工具去执行。基础服务层包含上下文提供器ContextProvider、LSP 客户端、文件操作器。这一层是手脚负责拉取项目信息、执行真实读写。数据源层包括工作区文件、Git 状态、符号索引、LSP 诊断输出。这一层是外部世界的映射也是 Agent 感知项目的窗口。另外还有一个横切的安全与合规层Session 权限校验、上下文隔离、审计日志。它不是独立的一个竖向层次而是横穿中间三层的一层防护网。之所以用“依赖方向”来讨论分层是因为每一层的职责是单向的。UI 层只能调用 Agent 核心层Agent 核心层只能调用基础服务层基础服务层只能读取数据源层。如果你在设计时发现 UI 层直接读了数据库说明你已经破了一层设计上的铁律。Kilo Code 里空我看到不少人把状态管理直接塞进 UI 层当时图方便后面改一个字段牵一发而动全身痛得很。2.2 消息流转与事件驱动设计分层之后最关键的逻辑就是消息怎么流转。Kilo Code 是一个对话驱动的编码助手用户每发一句话背后要经过“输入解析 → 上下文组装 → 计划生成 → 任务分发 → 结果汇总 → 响应渲染”这样一条固定的链路。我在设计的时候把这条链路抽成了事件流而不是简单的函数调用。为什么要用事件驱动而不是直接调用举个例子用户在对话框里输入“帮我把这个函数的错误处理加上”。如果采用直接调用那么 UI 层就要知道“错误处理加在哪里、用什么方式加、加完之后怎么验证”这等于把整个业务逻辑都耦合在了 UI 层。而事件驱动的方式是UI 层只发布一个UserMessageSubmitted事件事件里带上消息文本和当前会话 ID剩下的活交给 EventBus 去调度UI 层不用关心是谁在处理、怎么处理。整个链路里最容易被忽视的是“上下文组装”这一步。Kilo Code 要给出准确的修改建议必须知道用户当前打开的是哪个文件、这个文件里有哪些符号、光标停留在哪个位置、最近的对话里提到了什么。这些信息如果每次都在一个方法里手工拼非常容易漏。所以我把“上下文收集器”做成了一个独立组件它会按优先级去拉取“会话信息 → 文件快照 → 符号索引 → LSP 诊断结果”再统一打包成一个ContextBundle对象往下游传。每一步的数据源变了只要收集器内部做适配下游完全不用改。2.3 模块通信协议与数据契约分层和事件流都定了剩下的就是模块之间“说同一种语言”。我见过很多项目死在数据结构不统一上——A 模块返回一个dictB 模块期望一个NamedTuple接口联调的时候全靠人肉翻译。Kilo Code 在这一点上做得比较坚决所有跨模块传递的核心对象一律使用 Pydantic 模型定义并且放在一个独立的schema.py里统一管理。比如SessionContext这个模型里面包含session_id、workspace_root、current_file、cursor_position、selected_text这几个字段。任何模块要用到会话信息直接 import 这个模型不要自己再造一个。又比如TaskAction它描述一个具体的修改任务包含action_type是编辑还是新建还是删除、target_file、content_diff、confidence。这几个字段的意义是所有模块公认的不允许某个模块私自增加含义。这里想重点说一个经验数据契约要控制“宽度”不要控制“深度”。也就是说你定义好字段名和类型就够了但不要过度约束字段内部的结构。比如content_diff我定义成字符串具体是 unified diff 格式还是自定义 JSON 格式由产出方决定消费方只要把它当成不透明字符串处理就行。这样既保证了接口稳定又给模块内部留下了灵活性。3. 核心模块拆解与职责边界3.1 会话管理器SessionManager会话管理器是 Kilo Code 里所有对话状态的“唯一事实来源”。它主要做三件事维护会话生命周期、管理上下文窗口的 Token 配额、生成和校验会话级权限。生命周期方面一个会话从用户创建开始经历idle → active → paused → closed几个状态。状态迁移不是随意跳转的比如paused状态下不能直接接收新的用户消息必须先回到active。这个约束在SessionManager里通过一个状态机表统一管控而不是在业务代码里到处判断。这样做的好处是后续如果要加“会话超时自动挂起”的功能只需要在状态机里加一条迁移规则不用改动业务代码。Token 配额是很多人容易漏掉的点。大模型对话有上下文长度限制Kilo Code 在会话管理器里维护了一个 Token 计数器每条消息进来都会估算 Token 占用当累计超过阈值时会自动触发上下文裁剪策略比如丢弃最早的非关键消息或者把前几轮对话压缩成摘要。这个策略如果放在会话管理器之外很容易造成状态不一致——你这边裁剪了那边计数没更新。权限校验这块我建议在会话管理器里只做“粗粒度”的校验判断当前会话是否有权访问某个工作区目录。细粒度的文件级校验放在安全与合规层里做。这样的分层逻辑是会话管理器不关心文件内容它只关心“用户有没有打开过这个项目”。3.2 事件总线EventBus与异步任务队列事件总线是整个 Kilo Code 的“血管”。我在设计它的时候用一个基于asyncio.Queue的简单实现接了一个发布订阅机制没有引入额外的消息中间件。Kilo Code 是本地优先的工具没有必要为了事件调度去部署 Redis 或者 RabbitMQ用 Python 原生的异步队列就够了而且天然契合异步编程模型。事件总线的核心接口有三个publish(event_type, payload)、subscribe(event_type, handler)、unsubscribe(event_type, handler)。实现上要注意两点一是事件的 payload 必须是不可变对象或者深拷贝后的对象防止多个订阅者之间互相污染数据二是订阅者的异常不能影响其他订阅者所以我在总线的调度循环里给每个 handler 都加了try/except异常只记录日志不中断整个事件分发。异步任务队列和事件总线通常是配合使用的。Kilo Code 里有一个典型的场景用户请求“重构整个模块”这个任务不能在前台同步执行需要投递到后台队列里慢慢跑同时通过事件向 UI 层推送进度。我用的是异步任务加一个任务注册表任务跑完、失败、取消都通过事件广播出去UI 层只需要订阅这些事件就能更新界面不需要轮询。这里有一个我踩过的坑任务队列里的任务在取消的时候子任务不一定跟着取消。比如一个重构任务派生出了三个子任务主任务被取消子任务还在跑结果就出现了“改了半个文件”的脏状态。后来我在任务注册表里维护了父子关系取消主任务时级联取消所有子任务才算把这个坑填上。3.3 辅助工具层ContextProvider、LSP 客户端、文件操作器Kilo Code 不是只靠大模型回答问题的它需要真正操作代码库。辅助工具层就是干这个的包括 ContextProvider上下文提供器、LSP 客户端和 FileOperator文件操作器三个组件。ContextProvider 的职责是“按需组装上下文”。它默认提供四类数据工作区文件树、当前文件内容、Git 变更状态、符号定义位置。每一类数据都有独立的 Provider 实现通过注册机制挂在 ContextProvider 上。这样设计的好处是插件化——社区如果想加一个“数据库 Schema 查看器”不需要改核心代码只需要实现一个协议然后注册进去就行。LSP 客户端负责和语言服务器通信拿到补全建议、诊断错误、跳转定义这类需要深度代码理解的结果。Kilo Code 选用了成熟的协议实现但为了保持模块独立性我把 LSP 交互封装在客户端内部对外只暴露get_diagnostics(file_uri)、get_definition(symbol)这类高层次的接口。这样上层业务永远不会感知到initialize、shutdown这些协议细节。FileOperator 是所有文件读写的唯一出口。所有模块要读写磁盘上的文件必须通过 FileOperator不允许直接调用open()。这个约束一开始很多人觉得小题大做但后来发现这是 Kilo Code 能在“代理式编辑”场景下不出乱子的关键——所有写操作都可以被拦截、审查、回滚所有读取都可以走缓存。4. 关键数据结构与状态设计4.1 数据模型总览Kilo Code 的核心数据模型我用一张表先给你列出来后面逐个解释。模型名称核心字段用途说明SessionContextsession_id, workspace_root, current_file, cursor_position, selected_text描述一次会话的完整上下文状态Messagemessage_id, session_id, role, content, token_count, timestamp表示一条对话消息区分用户/助手角色TaskActionaction_id, action_type, target_file, content_diff, confidence描述一个具体的代码修改操作ContextBundlesession_info, file_snapshot, symbol_index, diagnostics聚合多源上下文供模型调用AgentPlanplan_id, steps, status, priority, dependency_ids表示一次 Agent 规划的完整计划4.2 SessionContext 与消息记录设计SessionContext是整个对话系统的“锚点”。为什么这么说因为消息记录本身是线性的、递增的但你一旦要基于“用户开了哪个文件”“光标在哪一行”去生成回答光靠消息记录就不够了。所以SessionContext不存消息内容它只存“环境状态”。环境状态和消息流分离是 Kilo Code 消息设计的关键决策。具体字段我这么定session_id是主键UUID 格式workspace_root是绝对路径所有相对路径都在它的基础上解析current_file和cursor_position是高频变动的字段每次用户切换文件或移动光标都会更新selected_text是用户选中的代码段通常在“解释这段代码”或“优化这段代码”的场景下使用。消息记录设计上我坚持一条消息一个Message模型不做“合并存储”。每条消息都要记录token_count因为后续 Token 裁剪需要依赖这个字段。这里有不少人图省事只在会话级别记录总 Token 数不要这样做——一旦你要做“丢弃某条消息”或者“压缩某轮对话”没有单条消息的 Token 数就完全无法实现。4.3 任务状态机设计TaskAction和AgentPlan这两个模型直接对应 Agent 的行为控制。我认为 Agent 系统最容易出问题的就是任务状态的流转。Kilo Code 把每个任务的合法状态迁移做成了一张显式的表当前状态可迁移到触发条件pendingrunning,cancelled调度器开始执行 / 用户手动取消runningcompleted,failed,cancelled执行成功 / 执行抛出异常 / 超时或用户取消completedreviewed用户确认修改结果failedpending允许自动重试限定次数为什么要显式维护这么一张表而不是每个地方自由 if-else因为我发现自由 if-else 最终都会演变成“到处都在判断状态”改一个迁移规则要全局搜索。状态机表把迁移规则集中管理什么时候加一条规则比如“reviewed状态下允许reopen回到running”只需要改一处。AgentPlan在任务状态机之上又加了一层“计划编排”。一个计划包含多个步骤步骤之间可能有依赖关系步骤 B 依赖步骤 A 的输出。我在计划模型里加了一个dependency_ids字段调度器执行时先解析依赖关系再决定并行还是串行。这块内容在 Kilo Code 里其实已经很接近“自主 Agent 编排”了设计上一定要留好扩展位。5. 实施节奏与扩展方向建议5.1 分阶段落地路径建议如果你现在是零基础开始仿照 Kilo Code 做整体设计我不建议一上来就铺开全部模块。我的建议是分四条阶段走每一条阶段有明确的产出物。第一阶段搭骨架。先把事件总线、会话管理器、消息模型的骨架写出来用一个“回声机器人”做端到端联通验证——用户发什么系统回什么。这一步看着简单实际上是把数据流跑通的关键。很多项目死在这里因为连最基础的事件流转都没有跑顺。第二阶段接入真实上下文。把 ContextProvider 和 FileOperator 实现出来让系统能够读取真实项目的文件结构并在消息中引用“当前文件”信息。这一步做完系统已经能感知用户的工作环境了不再是“盲人摸象”。第三阶段接入大模型能力。选一个支持工具调用的模型把对话能力和 Agent 工具调用结合起来让模型能通过工具读写文件、获取诊断信息。这是从“玩具”走向“可用”的关键一步。注意这个阶段你才会真正理解为什么前面要把任务状态机设计好——模型随时可能给出一个“看起来合理但实际无法执行”的计划如果你的任务层没有兜底整个会话就乱套了。第四阶段加安全与稳定性。补上权限校验、审计日志、任务取消级联、Token 裁剪策略。这些功能在原型阶段不显眼但一旦你想拿它去处理真实业务缺一不可。我见过太多原型项目死在这一步——Demo 跑得欢一到真实仓库上就各种越权、脏写、半截子修改。5.2 未来可扩展的方向Kilo Code 的架构将来如果要演化我看好这几个方向。第一个方向是插件化治理。目前的工具层已经保留了注册机制的雏形——ContextProviderProtocol 可以注册未来 FileOperator、LSP 客户端、甚至整个 AgentPlan 调度器都可以做成插件化。一旦做成了社区生态就能长出来。第二个方向是多模型适配。现在很多代码助手只适配某一个模型换一个模型就要改核心代码。Kilo Code 的架构里模型调用被隔离在独立的适配层协议统一成“输入 ContextBundle输出 AgentPlan”。谁符合这个协议谁就能接入这为未来切换模型或者并行使用多个模型铺平了路。第三个方向是本地知识库持久化。本地优先工具的最大优势是上下文可以做得更私密、更连续。未来可以把会话的历史、项目变更的记录、用户偏好都存成本地知识库每次启动时加载让助手越来越懂这个项目。这个方向做深了Kilo Code 就从一个“通用代码助手”变成了“专属项目协作者”。5.3 给新入坑读者的一句话心得我自己在代码助手类项目里折腾了不少时间有一个体会想分享给刚开始设计的读者先把数据流和状态机画清楚再动手写代码。很多人一上来就调模型、写 Prompt结果调通了模型发现整个工具无法处理“多轮对话中文件改了一半”这种真实场景。Kilo Code 的架构设计里最核心的价值不是“用了什么新技术”而是把“对话”“上下文”“任务”这三件事的边界划清楚了。先有边界再有 Agent 的能力这条路大概率是顺的。
