opencode 这个名字，最近在终端 AI 编程这个圈子里出现频率越来越高。简单说，它是一个跑在终端里的开源 AI 编码代理，不依赖 IDE，直接在命令行里跟你协作改代码。我花了一段时间把它的源码从头到尾捋了一遍，越看越觉得这项目在工程架构上有不少值得聊的设计。这篇先写“上篇”，重点讲三件事：整个工程的模块全景、它那套独特的双会话内核机制，以及驱动所有状态流转的事件溯源系统。如果你正准备读它的源码，或者想自己做一个类似的终端 AI Agent，这文章能帮你省不少翻代码的时间。
1. 工程全景：一个模块边界清晰的分层架构
1.1 从整体看，opencode 不是单体应用，而是“微内核 + 对策层”
先别被“微内核”这个说法吓到。我的理解是，opencode 的代码组织方式很像操作系统里的微内核设计：核心引擎只负责状态管理和事件分发，具体的工具调用、模型交互、界面渲染全部解耦到外围模块。你打开它的仓库，第一眼会看到packages目录下分成好几个独立包，比如opencode、core、tools、agent、ui等，包与包之间通过定义良好的接口通信，而不是互相直接 import 一团乱麻。
这种分层带来的直接好处是：你想理解某一块逻辑时，不需要关心其他模块的内部实现。比如我只想搞清楚“用户输入一行命令之后，系统是怎么把它变成 AI 消息的”，那我就只需要看输入处理层和会话层的交互，不需要碰 UI 渲染的代码。这种边界感对阅读源码来说太重要了。
具体分层可以这么划分：
- UI 层：基于 xterm.js 的终端界面，负责键盘输入捕获、ANSI 序列渲染、鼠标事件，这里不包含任何业务逻辑。
- 会话内核层：管理持久会话和短生命周期会话的创建、恢复、销毁，以及会话之间的状态传递。
- 事件总线层：整个应用的中枢神经系统，所有模块之间的通信都通过事件进行。
- Agent 运行时层：执行具体任务，包括模型调用、工具调用、代码编辑、命令执行。
- 外部服务层：模型 API 客户端、语言服务协议（LSP）集成、文件系统监听等。
每一层只依赖下一层的抽象接口，不反向依赖。这个架构的后果是，即使未来把 UI 从终端换成网页或者桌面应用，内核层可以完全不动。
1.2 包结构拆解：哪里是入口，哪里是核心引擎
逐个包看的话，几个关键位置的职责非常清晰：
apps/opencode：这是启动入口，负责读取用户的配置文件（opencode.json之类）、初始化全局状态、拉起 TUI。packages/core：核心引擎所在，包含事件定义、状态管理、会话生命周期、消息流水线的抽象。packages/agent：AI 智能体的具体实现。它监听来自核心的事件，调用模型 API，维护模型上下文窗口。packages/tools：工具注册中心。所有可以被模型调用的能力都注册在这里，比如文件读取、代码搜索、终端命令执行、网页抓取。每个工具都是一个独立模块，上层只暴露一个统一的接口。packages/ui：终端 UI 组件，包括会话列表、消息流、输入框、diff 视图等。
如果你拉下源码，想快速定位“用户输入到输出响应”这条链路，从入口一直追到 UI 渲染会经过core的几个关键类。我建议你先读core里的事件定义文件，对整个系统里可能发生的事有个全局印象，再去追执行链，这样不容易迷路。
提示：读这一类事件驱动架构的代码，不要从上往下逐行读。先找“事件类型清单”，再找“订阅者”，再反推“发布者”。顺序对了，效率会高很多。
2. 双会话内核：持久会话与短生命周期会话的协作机制
2.1 为什么需要两套会话？一个管理长期状态，一个处理即时任务
opencode 最迷惑人的地方在于，它同时维护两套完全不同生命周期的会话对象。我在阅读初期反复踩坑，就是因为没搞清楚“会话”这个词在代码里到底指什么。
第一套是持久主会话（Main Session）。它在一次运行中只存在一个，负责保存用户与 AI 之间的核心对话历史、项目级上下文、模型设置的全局状态。这个会话的生命周期和整个 TUI 的生命周期一致，甚至支持从磁盘恢复——也就是说，你退出 opencode 之后，主会话的摘要和历史还能留着。
第二套是短生命周期会话（Sub/Agent Session）。它几乎是“用完即焚”的，每次某些特定操作（比如生成一条临时命令、执行一次自动补全、运行一个快捷任务）都会创建一个新的独立对话上下文，完事后自动销毁。
为什么这么设计？我个人的理解是，长对话和即时任务是两种完全不同的上下文需求。主会话需要保持一致性，不能被临时任务污染；短会话需要轻量和隔离，不能让数以千计的临时交互塞进主对话历史里。把两者混在一起，模型上下文很快就会被无关消息撑爆，token 成本飙升，回答质量也会下降。
2.2 两条会话的创建和执行流程
在主会话层面，启动流程大概是：
- 读取配置和服务器状态。
- 初始化
MainSession实例。 - 将主会话 id 注册到全局状态。
- 通过事件
session:init向系统广播“主会话可用”。
而每一次触发短会话时，比如用户执行了一次“自动补全”，系统会走另一条链路：
- UI 层发出请求事件，携带当前编辑区的上下文内容。
- 内核层根据这次请求的用途，判断是需要一个全新会话还是复用某个临时会话。
- 如果需要新会话，创建一个
SubSession，把可能需要的上下文（文件内容、光标位置、最近改动）注入进去。 - 短会话执行完之后，结果通过事件回传给调用的地方。
- 短会话被标记为销毁或回收，等待垃圾清理。
这里有个很精妙的地方：短会话虽然生命周期短，但它也会把关键信息写回主会话。比如自动补全完成后，最终的补全结果会作为一条消息追加到主会话的上下文中，而补全过程中产生的中间 tool call 则不会。这样既不会污染上下文窗口，又能让用户在主对话里看到“刚才补全了什么”。
2.3 会话状态传播机制：事件驱动的状态机
这两种会话之间的状态同步，走的是事件流加全局状态机。具体而言，每个会话都有自己独立的session state文件或内存对象，包含会话 ID、创建时间、拥有的消息列表、关联的模型配置。所有状态变更都会通过事件广播出去。
订阅方包括 UI 层（用来刷新界面）、持久化层（用来落盘）、以及 agent 层（用来选择上下文）。因为状态是单向流动的，所以不存在“两个模块同时改一个变量”的并发问题。这一点对前端来说可能稀疏平常，但对一个同时有异步 I/O、子进程、模型流式响应的应用来说，是避免状态错乱的关键设计。
实际读代码时要注意：不要一看到
session就以为是主会话。源码里session这个命名经常出现在不同上下文里，比如某个工具调用也有自己的“session”概念。务必先看它挂在哪个生命周期节点下，再判断它是主还是子。
2.4 双会话带来的工程挑战
聊完了机制，也得说说这套设计的代价。最大的挑战是上下文切换时的数据一致性。短会话执行时，主会话可能同时在进行流式输出，两个会话同时写同一个项目目录下的不同文件，就容易碰到文件锁和 Git 冲突。opencode 的解决方式是，在短会话执行期间对主会话的会话语义加上一个“忙碌”标记，UI 上也能看到对应提示，避免用户并发触发冲突操作。
另外，短会话频繁销毁也会带来性能压力。好在他的创建和销毁都是异步的，且对象池做了复用，实测频繁触发补全并不会让内存暴涨。这部分代码在agent包里，有兴趣可以从内存分析和 session 复用两个方向去读。
3. 事件溯源：让一切状态变化都有迹可循
3.1 事件溯源如何解决状态同步的难题
opencode 有一个很关键的工程决策：所有跨模块的状态变更，不通过直接调用，而是全部通过事件发布与订阅来完成。这套机制跟我之前见过的状态管理方案不太一样，它的核心理念是“每个事件本身，就是状态变化的历史记录”。
举个例子，输入一行文字并回车。这个动作会产生一个message:send事件，消息内容、目标会话、时间戳都被打包进球。下游的 agent 模块订阅到这个事件后，把消息送入模型。模型返回内容时，又会发出message:update事件，把 AI 的流式回复逐段推给 UI。全程没有任何一个模块直接改动另一个模块的内部状态。所有东西都是“响应事件然后重新计算”。
这么设计最大的好处是，调试一个 bug 时，你只要看事件流日志，就能还原整个系统的运行轨迹。任何诡异的状态异常，大概率能从事件链路上找到哪个环节没有按预期发出事件。这就是“事件溯源”四个字的本质：状态是时间的函数，而不是某时刻的随机快照。
3.2 核心事件类型一览
源码里定义了几大类事件，我根据使用频率整理如下：
| 事件类别 | 典型事件名 | 触发时机 | 主要订阅方 |
|---|---|---|---|
| 会话生命周期 | session:init、session:destroy | 会话创建/销毁 | UI、状态管理器、持久化层 |
| 消息流 | message:send、message:update、message:complete | 用户发消息、AI 流式回复更新、回复完成 | Agent 层、UI 渲染层 |
| 工具调用 | tool:start、tool:result、tool:error | 模型调用某个工具时 | 工具注册中心、UI 日志面板 |
| 配置变更 | config:update、config:reload | 配置被修改/重载 | 会话内核、agent 上下文 |
| 文件操作 | file:change、file:watch | 文件系统监听发现变动 | 上下文注入模块 |
读源码时，我建议先从message:send开始追踪一条完整链路：UI 输入 → 事件总线 → agent 订阅 → 模型请求 →message:update流式返回 → UI 渲染。这一条链路打通了，整个事件系统的大半逻辑就清楚了。
3.3 事件系统的进阶机制：Properties 与双异步级联
opencode 的事件系统里有一层容易被忽略的机制，就是properties。它本质上是一套全局可读写的键值存储，事件总线会监听 property 的变化。跟普通事件不同，property 是一种“状态值”，你可以直接读取当前值，也可以订阅它的变更。
我举个例子：会话的当前模型 ID 是一个 property。当用户切换模型时，内核层直接写入session.modelID，所有订阅了这个 property 的模块（比如 UI 的模型标签、agent 的上下文构造器）会自动收到通知。这在传统事件系统里需要手动管理“事件 → 新状态”的映射，而 property 机制把这个映射简化成了一次赋值。
这带来一个特性叫“双异步级联”。第一个异步是事件发布与订阅的异步，第二个异步是property 变更后的回调异步。两个异步叠加，在实际运行中容易产生时序问题。比如一次输入触发message:send事件，这个事件的处理是异步的，在处理过程中又修改了某个 property，而 property 的回调可能再次发事件。稍不小心，同一个用户输入就会产生两次下游处理。
3.4 事件溯源对调试和测试的启发
这套事件机制的另一个实际价值体现在测试上。因为系统所有副作用都挂在事件和 property 上，测试时只需要“发一个事件，断言另一个事件是否产生”，就能完成行为验证。我在读源码配套的测试时，发现大量用例都是这种模式：
- 向事件总线写入
message:send - 等待一次 tick
- 断言
tool:start是否被触发 - 断言会话状态是否更新为预期值
这样写测试有一个明显优点：不依赖具体实现细节，只依赖对外行为。即使将来把内部工具替换成完全不同的实现，只要触发的事件不变，测试仍然成立。
调试经验分享：这套系统里最容易出诡异的 bug 就是“事件在订阅前被发出”。因为订阅是异步建立的，初始化阶段顺序不当，会导致先发的事件无人接收，状态静默丢失。我排查过几次问题，最后都是在这个环节找到的。建议调试时在关键事件名称上加上一次性日志，观察发布与订阅的顺序。
4. 实操视角：跟着事件链路走一遍输入输出全流程
4.1 从一次“自动补全”触发，追完整条链路
为了把抽象的东西落到实处，我用一次最常见的操作来串一遍源码里的执行流程：用户在编辑器里输入了一段代码，按下自动补全快捷键。
第一步，UI 层 xterm 捕获到按键，把光标位置、当前行的代码片段整理成一个上下文包，然后向事件总线发出一个请求补全的事件。
第二步，内核层收到事件后，判断当前需要创建一个短生命周期会话。它先从主会话中取出当前文件路径、当前字段名、最近改动的代码片段，注入到新会话的初始消息里。这一步非常关键，它决定了补全能“看”到多少信息，也直接决定补全质量。
第三步，agent 层订阅到该会话的新消息，开始组装模型请求。它会根据当前模型类型决定是否启用流式输出，将上下文包序列化，发起 API 调用。
第四步，模型逐字返回结果时，agent 层将内容封装成流式更新事件推回 UI，UI 在终端的输入框上方渲染一个候选列表。
第五步，用户接受补全后，UI 层发出确认事件，内核层把最终结果写入文件，并将这段补全追加到主会话的对话历史里。
第六步，短会话进入销毁流程，事件总线广播会话销毁事件，清理内存引用。
整条链路从头到尾，没有一个模块直接调用了另一个模块的对象方法。他们只是“发一个事件”“听一个事件”“改一个状态”“被通知状态变了”。
4.2 事件时序中的隐藏细节
如果你照着事件链路走会发现，属性（property）的读取时机和事件回调的执行顺序，比想象中的更微妙。举个例子，message:send事件里携带的消息 ID 需要后续的message:update引用，这两个事件之间没有顺序保证。因此代码里通常不依赖消息 ID 的硬编码，而是通过会话 ID 和消息索引共同定位一条消息。
我在实际调试中遇到过一个很典型的时序问题：UI 在等待message:complete事件刷新自定义状态栏，但某次流式输出异常中断，这个事件迟迟不来，导致 UI 一直处于“生成中”的假死状态。最后查原因，是 agent 层在流式中断了连接后，只发了message:error而不是message:complete，UI 层没订阅message:error。这个问题本质上是事件类型设计不完整，但也暴露了实际操作中“考虑所有终止分支”的重要性。
如果你自己基于这套架构做开发，建议先从事件定义层面把所有终止路径想完整：正常完成、用户取消、网络错误、模型超限、工具异常。每个终止路径都要对应一个独立事件，否则下游监听方永远无法覆盖全部场景。
4.3 子进程与工具调用的安全边界
opencode 里工具调用是一个重点，尤其当模型需要执行终端命令时。这里有一个安全的边界设计，让我印象深刻。
模型本身不直接操作终端。它只会发出“请求执行命令”的事件，工具运行时模块接手后，创建一个独立子进程，用 shell 解释器执行命令，并把输入输出 buffer 起来。整个过程有几个硬性限制：超时时间上限、输出长度上限、危险命令拦截列表。这些限制不是 AI 自己决定的，是工具注册层在编译期写在配置里的。
这种设计把“模型的权限”和“系统的安全边界”分离了。模型只是意图的表达者，真正的执行权限依然掌握在本地工具层手里。即使模型被恶意提示词诱导发出一个危险命令，工具层仍然有机会拦截。从工程角度说，这比“模型直接获得终端权限”安全了不止一个量级。
实操建议：如果想要修改工具的超时时间或输出限制，不要去改 agent 层的模型调用代码，去改工具的注册配置里对应的参数。模块边界帮你把这类需求限制在了很小的改动范围内。
4.4 配置加载与热更新流程
再聊聊配置文件这块。opencode 的配置不是启动时读一次就完事。它支持热更新，也就是说，你改了opencode.json，运行中的进程会在下次相关操作时重新读取。
这套实现同样走事件链路。文件系统监听器发现配置变更 → 发出config:update事件 → 内核更新配置模块的 property → 所有订阅配置的模块收到通知 → 会话内核判断哪些会话需要重建上下文。这个过程里，最费时的是“重建上下文”，因为现有会话的模型上下文需要重新整合。并非所有配置变更都触发重建，内核会对比变更前后配置的指纹，只有影响上下文的字段（比如系统 prompt、工具开关）变了，才会重建。
如果你在复现一些“改配置不生效”的 bug，多看看这个对比指纹的逻辑。很多时候不是没热更新，而是你的配置变更被判定为“不需要重建上下文”，所以表现上像是没生效。
4.5 性能与资源占用关注点
opencode 的事件系统带来灵活性的同时，也有性能代价。我实际跑过中等规模项目，观察系统资源占用，几个地方值得注意：
- 每个事件都要走 JSON 序列化和广播，高频工具调用时会明显占用 CPU。
- 流式模型响应会拆成十几条
message:update事件，如果 UI 层消耗过慢会造成事件队列积压。 - 文件系统监听在大目录（如
node_modules）下会触发大量文件变更事件，处理不及时会拖慢整个系统。
所以源码里针对性地做了几件事：文件监听默认忽略依赖目录和.git；事件总线支持背压，订阅者消费不过来时会暂缓发布；属性缓存减少重复计算。
性能优化的思路值得参考。任何事件驱动的应用，第一件事不是优化单次事件的处理速度，而是降低无效事件的产生频率。把高频无意义的事件挡在源头，比后端加再多的缓存都管用。
5. 双会话与事件溯源的组合拳，带来了什么开发体验
说句实话，这套架构在最初接触时是有学习成本的。因为你要同时理解“两个会话”“一套事件总线”“一个全局状态存”三个概念，它们不是互相独立而是交织在一起。但一旦适应了，开发体验会顺畅很多。
具体体现为几个“没有”：
- 没有“改 A 模块却要连带改 B 模块”的连锁反应。模块只对事件负责，不对其他模块的实现负责。
- 没有“状态存在哪里都找不到”的困惑。全局状态就集中在属性存储里，事件历史一查就有。
- 没有“会话 A 的上下文被会话 B 改乱”的隐患。主会话和短会话天然隔离，只在需要时显式传递局部上下文。
我自己在实际尝试中，按照这套思路给一个内部工具添加了一个新功能：自定义快捷指令。整个流程走得很顺：先定义一个新事件（command:trigger），再在 UI 层绑定快捷键发事件，最后在 agent 层订阅事件并套用已有的短会话机制。全程只改了三个文件，没有动任何其他模块。这种体验在大型前端项目里是比较奢侈的。
我个人很推荐一个读源码的方法：准备一个笔记本，把事件名、发布者、订阅者列成三栏。每读一个模块，就把它的订阅关系补进去。读到五六个模块之后，整个系统怎么转的，那张表会直接给你答案。
6. 常见问题与排查技巧实录
6.1 问题速查表
我在调试和重新实现的过程中，遇到了一些很具体的问题。简单整理成一张表，方便你参考。
| 现象 | 可能原因 | 检查思路 |
|---|---|---|
| UI 收不到模型回复 | message:update事件未发布 | 确认 agent 流式回调是否触达事件总线；检查事件订阅是否在初始化之后 |
| 自动补全内容错乱 | 短会话注入的上下文过期 | 查看注入上下文时是否读取了当前文件的实时内容，而非缓存 |
| 切换模型后对话历史丢失 | 模型配置 property 变更触发了会话重建 | 检查重建逻辑中历史消息的持久化是否覆盖所有状态 |
| 配置改了不生效 | 配置指纹对比判定无需重建 | 确认改动字段是否属于上下文相关字段 |
| 命令执行超时 | 工具超时配置过短 | 调整工具注册配置中的超时时间，而非模型请求超时 |
| 大量文件监听事件卡顿 | 忽略规则未生效 | 检查文件监听是否真的排除了依赖目录 |
6.2 一个典型的“会话错乱”案例复盘
有一次我尝试在同一个目录开两个 opencode 实例，同时操作一个项目，结果出现了 Git 暂存区状态互相覆盖的问题。排查发现，两个实例的短会话同时执行git add，因为共享一个.git目录，第二次 add 会把第一次的暂存内容覆盖掉。
这个问题的根本原因不在 opencode 的事件系统，而在于两个独立进程共享工作区时的外部资源竞争。但事件系统的日志给了我很好的线索：两个实例的文件监听事件互相触发，导致上下文不断刷新。最终的解决方法是：外部任务锁，在同一工作区只允许一个实例执行写操作。这也是分布式系统里常见的思想，在单机多进程场景同样适用。
6.3 调式中的三个实用技巧
第一，开启详细日志。opencode 的内部日志文件会记录所有事件发布和订阅顺序，这个信息量远大于 UI 上看到的内容。遇到奇怪问题，优先看日志而非猜测。
第二，用最小复现法缩短事件链。不要在一个复杂的多文件操作中去追问题，而是把操作简化为一次最简单的消息发送，看事件链路是否完整。链路断在哪个环节，问题就在哪个环节。
第三，隔离外部因素。很多问题看起来是事件系统的问题，实际是模型 API 不稳定或网络延迟造成的。我在调试时会用一个本地回环 mock 模型，确保每次返回都是确定的序列，再跑事件链路测试。这个习惯帮我区分了很多“系统 bug”和“上游问题”。
写在最后的小经验
花时间把 opencode 的源码读透之后，我最大的感受是：这个项目把“事件驱动”这四个字贯彻得很彻底，甚至可以说不妥协。它带来的直接结果是，系统的复杂度没有随着功能增加而成倍爆炸，因为每加一个功能，都是在事件图里加一个节点，而不是在全局状态里加一个 if。
如果你也想在自己的项目里用类似的思路做架构，我给的建议很朴素：先从事件类型清单开始设计，再补状态模型，最后才写业务逻辑。顺序反了，最后大概率会改成四不像。
这篇上篇主要聚焦在工程结构和核心机制上。关于模型上下文如何组装、工具调用如何编排、以及 token 成本优化的部分，涉及的内容还要再多拆几层，后续再单独开一篇慢慢聊。
