如果你用 opencode 用得久了，大概率会有一种感觉：它看起来只是一个跑在终端里的 AI 编码助手，但内部的结构远比“调一下大模型、然后把结果贴出来”要复杂得多。从用户视角看，你输入一句话，它在终端里改文件、跑命令、调接口、读日志，整个流程像是一个流畅的自动化闭环。但一旦你开始关心“它是怎么做到这些的”，就会发现这里藏着三个绕不开的词：工程全景、双会话内核、事件溯源。

这三个词基本概括了 opencode 最值得研究的架构底色。我准备分上下两篇来讲，上篇先把工程全景和核心机制讲清楚，也就是“它内部长什么样、双会话到底双在哪、事件溯源是怎么把整个 Agent 运行过程变成可回放的时间线的”。如果你之前在别的工具里接触过 Agent 循环、事件总线、会话管理这些概念，你会发现 opencode 的很多设计相当典型，但又有些非常独到的取舍。这篇文章适合两类人：一是想深入理解 opencode 工作原理的日常用户，二是想自己设计或改造 Agent 工具、想借鉴成熟架构的开发者。

1. 工程全景：一个终端应用如何长成一套完整架构

1.1 表层能力与底层分层的平衡

opencode 的定位从来不是一个“聊天壳”。它更像是一个以 Agent 循环为内核的编程环境：用户通过自然语言下发目标，内核负责拆解目标、调用工具、观察结果、循环推进，直到任务完成或条件终止。你看到的终端交互界面只是最外面一层，真正的核心能力全都沉淀在它底层的模块划分里。

从工程结构上看，opencode 大致可以拆成这几层：CLI 启动与界面层、Provider 适配层、会话内核层、工具执行层、以及事件系统层。CLI 层负责解析命令、启动交互界面、渲染输出；Provider 适配层负责对接不同的模型服务商，把统一的请求格式转换成各家 API 的调用格式；会话内核层维护着整个 Agent 循环的状态和上下文；工具执行层则封装了文件读写、终端命令、代码检索、LSP 交互等能力；事件系统层贯穿所有模块，负责把每一步操作变成可追溯的事件流。

这个分层结构其实很有讲究。如果所有逻辑都堆在界面层里，那 opencode 就是一个“能用但很难扩展”的玩具；但它把工具能力独立出来，把模型调用独立出来，把会话状态独立出来，这样每一层都可以单独替换和迭代。比如 Provider 适配层的存在，让你今天用某个模型、明天换另一个模型，上层逻辑几乎不用改动。工具执行层独立设计，也意味着你可以往里面挂新的工具，而不需要动内核代码。

1.2 模块边界与数据流主线

理解一个系统最好的方式不是看它的目录结构，而是看数据是怎么流动的。opencode 的数据流主线大致是下面这个循环：

用户输入 → 会话内核打包上下文 → Provider 调用模型 → 模型返回决策（文本或工具调用） → 工具执行层执行对应操作 → 执行结果作为观察回传 → 会话内核更新状态 → 进入下一轮循环。

整个循环的核心驱动者是会话内核。它不只是简单地“把消息发给模型”，而是要维护一个动态更新的上下文窗口，决定哪些历史信息要保留、哪些子任务结果要摘要化、工具调用产生的中间输出要如何折叠。换句话说，模型只是推理引擎，会话内核才是那个“知道现在该干什么”的大脑外围系统。

代码检索和 LSP 交互也是 opencode 工具执行层里非常重要的一环。AI 编码助手要做对事情，前提是它“看得见”代码。opencode 通过 LSP 通道与语言服务器通信，能够拿到语法诊断、符号定义、引用跳转、类型信息等结构化数据。这些数据比单纯的全文搜索要准确得多。这里的选择很聪明：它没有自己去实现一套代码理解引擎，而是尽量复用语言社区已有的 LSP 生态。好处是每新支持一种语言，只需要适配对应的语言服务器，不需要从零训练或者实现解析器。

结合模块边界的梳理，下面这个表格可以帮你快速建立整体印象：

在我看来，opencode 工程上的核心“产品意识”是：它把 Agent 运行过程当成一个可以观察、可以回流、可以恢复的时间序列来建模，而不是简单地当成“请求-响应”来处理。这个意识直接引导了后续所有关键设计，包括双会话内核和事件溯源。

2. 双会话内核：主会话与子代理会话的协作模型

2.1 两个会话各自承担什么职责

“双会话”是 opencode 内核设计里最容易忽略、但实际作用最大的一个点。很多 AI 编程工具只有一条会话通道：用户说什么，模型答什么，状态都挤在同一个上下文里。opencode 不是这样，它在内部维护了两个层次不同的会话通道。

第一个是主会话，也就是面向用户的那条通道。用户的每一句话、Agent 对用户的重要回答、任务的整体进度，都会被放进主会话里。主会话负责维护“我们在做什么、进行到哪一步、用户的真实意图是什么”这个全局视图。可以把它理解成项目经理的笔记本，上面记录的是整个项目的目标、进展、决策。

第二个是子代理会话。它不是一个直接面向用户说话的通道，而是内核在执行某个具体子任务（比如检索代码、批量替换、生成测试用例、做一次独立分析）时临时创建的工作会话。子代理会话有自己独立的上下文窗口、独立的工具调用范围、独立的观察结果。它像一个被临时请来的专家，只负责解决一个问题，解决完就离开，不会把自己思考的细节全部倒进主会话里。

子代理会话最典型的应用场景是代码检索和 LSP 探测。当主 Agent 需要了解某个符号在项目里的引用关系时，如果这个信息直接灌进主会话的上下文里，不仅消耗 token，还会干扰主模型对整体任务的理解。opencode 的做法是开一个子代理会话，让它去执行检索任务，然后把最终结论整理成紧凑的结果返回给主会话。主会话只拿到“结果摘要”，至于子代理中间访问了哪些文件、看了哪些符号定义，这些过程细节对主会话来说是隔离的。

2.2 双会话要解决的三个核心问题

双会话设计并不是为了炫技，它非常务实地解决了 Agent 系统里的三个老大难问题。

第一个是上下文污染问题。单会话模式下，子任务的中间输出会混入主上下文，导致模型越来越难分辨哪些信息是当前决策真正需要的。越到长任务后期，这种污染越严重，甚至会出现模型被无关节点的信息带偏的情况。双会话通过物理隔离子任务的上下文，让主会话始终保持“高信息密度、低噪声”的状态。

第二个是 token 膨胀问题。大模型上下文窗口虽然一直在扩大，但 Agent 任务往往是长时间多轮次的。如果每一次函数调用结果、每一次文件读取返回都留在主上下文里，几轮下来上下文就会膨胀到不可接受的程度。子代理会话处理完独立任务后就结束，它的内部上下文也随之释放，从根源上控制了主会话的长度。

第三个是并行度问题。主会话在处理用户输入的同时，子代理会话可以在后台执行异步任务。比如主 Agent 一边在进行代码修改，一边派一个子代理去验证外部接口的状态。这种并行能力让 opencode 在复杂任务中的表现更像是“多角色协作”，而不是单线程的问答机。

这三个问题，本质上都属于同一个工程命题：如何让一个 Agent 在长时间的运行中保持决策质量。你可以想象一下，如果所有信息不加区分地堆在一条会话里，模型很快就会陷入“信息过载”的状态，就像让一个人同时记住所有会议细节，结果真正做决策时反而抓不住重点。

2.3 会话之间如何通过事件解耦

很多人会好奇，双会话之间到底是“调用”关系还是“通信”关系？如果是直白的函数调用，那主会话和子代理会话就会耦合得很深：主会话必须等待子代理执行完，子代理的中间状态也必须直接暴露给主会话。opencode 的做法明显更偏向“事件通信”。

主会话需要某个子任务时，不是直接去调用子代理的某个函数，而是发出一个事件，事件里描述了任务目标、输入材料、期望返回方式。子代理会话监听这类事件，拿到任务后开始自己的工作，完成后把结果封装成另一个事件，投回主会话的时间线。主会话收到结果事件后，再决定下一步动作。

这个通信模型带来一个很大的好处：两侧的生命周期完全解耦。子代理会话可以被创建、被挂起、被回收，而主会话不需要关心这些状态管理细节，它只需要能够理解“发出事件、接收事件”就够了。这种事件驱动的方式也更符合 Agent 系统“异步推进”的本质——毕竟真实世界里，子任务就是可能比主任务更慢完成，也可能提前失败，必须有一种机制让双方能够在不同步的节奏下协作。

从可观察性角度来看，事件通信也比直接调用更优。因为每一次子任务的创建、执行、完成、失败都变成了事件流中的一个个记录点，你可以在事后完整回溯“主会话是在哪一步派出子代理的、子代理返回了什么结果、主会话又如何基于结果做了后续决策”。这种可回溯性在调试复杂 Agent 行为时极其有价值。

3. 事件溯源：让 Agent 的每一步都有据可查

3.1 事件溯源的本质与在 opencode 里的落地形态

事件溯源（Event Sourcing）并不是 opencode 首创的概念，它在后端领域已经被广泛应用了很多年。它的核心思想是：不把“当前状态”当作唯一真相，而是把所有导致状态变化的事件按顺序保存下来，当前状态只是这些事件回放后的投影。

用生活化的方式理解：传统记账方式保存的是“银行账户当前余额”，事件溯源保存的则是“每一笔存取款记录”。余额当然重要，但它随时可以重新算出来，而存取款记录才是真正不可丢弃的事实。opencode 把这一思想搬到了 Agent 会话管理中，于是整个会话不再只是一个“消息列表”，而是一条不断追加的事件时间线。

在这个时间线上，你会看到：用户发出的指令是一个事件，模型返回的一段文本被切成流式事件，Agent 调用某个工具是一个事件，工具返回的执行结果是另一个事件，文件发生了修改也被记录成事件。整个 Session 本质上就是一个 append-only 日志结构，永远只追加、不修改、不删除。

这个设计对 Agent 系统来说有天然的优势。因为模型输出本身就是流式的，工具执行也是异步的，Agent 运行过程的“事实”本来就是一系列离散动作的组合。与其想办法把这些离散动作压缩成一个“当前状态”，不如直接把它们原样保存成事件序列，让状态变成事件流的派生结果。

3.2 事件流如何驱动整个 Agent 循环

在 opencode 的内部实现里，事件不只是存储格式，还承担着驱动循环的责任。会话内核本身可以看作一个事件处理引擎：它接收外部输入事件，经过一系列归约逻辑处理后，产出新的事件；新的工具结果事件又会被消费，触发下一轮模型调用。

这里有一个很关键的细节：事件是有序的。有序性是事件驱动系统能够保持一致性的前提。如果两个事件乱序到达，内核可能基于一个过期的工具结果做决策，或者把一个已经被撤销的文件修改误认为是有效状态。opencode 在事件分配上使用增量序号来保证全局有序，每一轮新的 Agent 循环阶段都能拿到比上一轮更靠后的事件段，从而保证状态投影不会错乱。

事件流与 Agent 循环的衔接，大致可以描述为：模型每完成一次推理，内核会把这次推理中新出现的工具调用意图转化成工具请求事件；工具执行层消费这些请求事件，把真实执行结果包装成观察事件；观察事件回传到内核，内核把它们追加到会话时间线，同时更新上下文窗口供下一轮模型推理使用。整个循环的每一步都有事件记录，这个特性极大地增强了系统的可调试性和可追踪性。

流式响应在这里玩得很转。用户看到的不是整段一次性渲染的文本，而是一串不断追加的事件拼接出来的结果。因为一切都是事件，前端界面可以任意重新渲染某一段、或者按某种过滤条件只看工具调用事件，这是传统“一次性返回完整结果”的模式做不到的。

3.3 从事件到状态的投影与恢复

事件溯源并不是只要“不断追加日志”就够了，还需要一套机制把事件流投影成可供查询和决策的状态。在 opencode 里，这个投影过程可以理解为：内核基于事件流重建出“当前会话上下文”，包括各类消息记录、工具执行状态、文件变更状态、任务进度等。

为什么“重建状态”这么重要？因为 Agent 系统经常需要断点恢复。比如说一个长时间运行的 Agent 任务跑到一半，进程崩溃重启了，如果没有事件溯源，那整个会话状态可能就丢了，所有上下文要从头再来。而事件溯源让恢复变得极其自然：你只需要把持久化的事件序列重新回放一遍，就能恢复到崩溃之前的状态，而且恢复过程中的每一步都还是可验证的。

此外，项目增量补全（Streaming）和服务重启恢复也依赖这条事件时间线。新发起一轮任务时，如果需要让新模型“了解”之前发生了什么，不需要重新传一大堆原始文本，只需要从事件存储中拉取关键事件序列，甚至可以让事件的摘要版参与上下文构建，从而大幅降低恢复成本。

从这个意义上说，事件溯源不只是一个存储技术选择，更是 opencode 整体可观测性架构的地基。有了它，Agent 的每一步都可以回溯、可以审计、可以复现。对于一个运行在终端、经常要跟长时间任务打交道的 AI 编码助手来说，这几乎是必不可少的工程决策。

接下来，把事件溯源与普通状态存储做个对比，你会更清楚这套方案的取舍：

4. 这套架构带来什么，以及复制它时要注意什么

4.1 工程收益：可调试、可回放、可观察

从实际使用的角度看，事件溯源和双会话给我最大的感受是“安全感”。Agent 系统的最大风险是它像黑盒：你知道了输入，看到了输出，但中间的过程对你是不可见的。一旦输出不符合预期，你根本不知道是模型推理出了问题，还是工具执行出了问题，或者是上下文管理出了问题。

有了事件时间线后，定位问题的思路清晰了很多。Agent 执行到某一步没有下一步动作，你可以去事件流里看它最后收到的工具结果是什么；模型生成了一个格式错误的工具调用，你也可以在事件流里看到原始输出，直接判断是模型能力问题还是后处理解析逻辑的问题。这种级别的可调试性，在纯“消息往返”式架构里很难达到。

双会话带来的收益则是“省心”。主会话上下文保持精简，子代理会话负责处理脏活累活，整体 token 消耗相对可控，模型决策也不容易被边缘信息带跑。其实你仔细想，人的工作方式也是这样：一个靠谱的负责人不会把所有执行细节都记在脑子里，而是分派出去、只拿回结论。opencode 的双会话不过是把这个朴素逻辑工程化了。

4.2 实操心得：几个容易踩的坑

如果你正在设计自己的 Agent 工具，或者想把 opencode 的架构经验搬到别的项目里，有几个坑我得提前说一下。

第一个坑是：事件溯源不等于“把所有东西都塞进事件流”。如果把什么都记录成事件，最后事件流会变得无比庞大，回放成本也会急剧上升。事件粒度需要设计：哪些事件必须细粒度记录，哪些可以做摘要，哪些只需要保留统计信息。opencode 的取舍是，直接影响 Agent 决策的事件（用户指令、工具调用、关键观察结果）必须精细记录，而一些高噪声过程（比如大段文本检索的逐字输出）则做折叠，让它不再占据核心事件流的空间。

第二个坑是：双会话不能只是“两个上下文对象”这么简单。如果双会话之间没有任何隔离机制，那它们实际上还是共享了底层的状态，隔离就形同虚设。真正的双会话必须做到：上下文隔离（不能互读对方的消息）、生命周期隔离（子任务结束可以释放子会话）、资源隔离（工具调用范围可以被限制）。当你做子代理会话时，一定要给它明确的边界和退出条件，否则很容易出现子任务失控占用大量资源的情况。

第三个坑是：顺序一致性比你想象的重要。事件流系统里最隐蔽的问题是并发事件乱序。比如两个工具几乎同时返回结果，如果事件分发的顺序不对，内核重建出的状态可能和实际执行顺序不一致。我在处理这类问题时的经验是：宁可建立一个串行的事件提交通道，也不要在事件入流阶段搞复杂并发控制，否则排查问题的难度会翻好几倍。

4.3 对后续扩展的影响

架构决定了系统能走多远。opencode 选了双会话和事件溯源这条路线，等于给自己的未来扩展铺好了一条比较清晰的轨道。后续想加新的工具类型，只要能把自己的动作变成事件，就能融入整个循环；想换新的模型服务商，只要 Provider 适配层能输出统一的事件格式就行；想做会话级别的持久化和恢复到不同设备，事件流天然是适合传输和同步的数据结构。

从另一个角度看，这种架构也为团队协作提供了基础。多个开发者可以各自跑自己的 Agent 会话，通过事件流的形式分享执行过程记录。行为审计、复盘、性能分析这些高阶需求，在事件溯源架构里都能很自然地落地，不需要额外再建一套日志体系。

结尾

写到这里，opencode 的上篇核心内容基本讲完了。我个人在实际研究这套架构时，印象最深的并不是哪个单独的模块写得多炫，而是它把“会话”和“事件”这两个概念在整个系统里贯彻得非常彻底。主会话与子代理会话的分离让上下文管理变得清晰，事件溯源让整个 Agent 运行过程有了扎实的可追溯底座。这两件事单拎出来都不算颠覆性创新，但把它们放到一个终端 AI 编码工具里，并且连贯地落地，确实能明显改善 Agent 在长任务中的稳定性和可维护性。

如果你也在设计自己的 Agent 工具，我建议你先别急着堆功能，不妨从这两个机制入手：先把会话边界划分清楚，再把事件时间线建起来。很多后续的调试、恢复、并行能力都会因此变得水到渠成。下篇我会继续往具体实现细节走，聊 opencode 在工具调用、上下文管理与流式事件处理方面的实际工程动作。