好，今天我们聊一个非常带劲的话题：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 模块返回一个dict，B 模块期望一个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 的核心数据模型，我用一张表先给你列出来，后面逐个解释。
| 模型名称 | 核心字段 | 用途说明 |
|---|---|---|
SessionContext | session_id, workspace_root, current_file, cursor_position, selected_text | 描述一次会话的完整上下文状态 |
Message | message_id, session_id, role, content, token_count, timestamp | 表示一条对话消息，区分用户/助手角色 |
TaskAction | action_id, action_type, target_file, content_diff, confidence | 描述一个具体的代码修改操作 |
ContextBundle | session_info, file_snapshot, symbol_index, diagnostics | 聚合多源上下文，供模型调用 |
AgentPlan | plan_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 把每个任务的合法状态迁移做成了一张显式的表：
| 当前状态 | 可迁移到 | 触发条件 |
|---|---|---|
pending | running,cancelled | 调度器开始执行 / 用户手动取消 |
running | completed,failed,cancelled | 执行成功 / 执行抛出异常 / 超时或用户取消 |
completed | reviewed | 用户确认修改结果 |
failed | pending | 允许自动重试（限定次数） |
为什么要显式维护这么一张表，而不是每个地方自由 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 的能力，这条路大概率是顺的。
