opencode架构解析：双会话内核与事件溯源

最近一个月我一直在啃一个代号为 opencode 的项目。如果你只看它的命令行界面大概率会以为它又是一个“AI 编码助手外壳”能聊代码、能调用工具、能看到 diff。但真正把源码一层层剥开后你会发现它最值钱的部分根本不是 UI也不是模型调用策略而是藏在底层、很少被人单独拿出来讲的三样东西工程全景、双会话内核与事件溯源。这篇文章是“深入 opencode”的上篇我打算把这三块完整拆开。为什么工程全景要先讲因为模块拓扑决定了这套系统能长多大。为什么双会话是内核因为它把“用户想干什么”和“执行器实际做了什么”彻底分裂成两个可独立恢复的会话。为什么事件溯源值得单独写因为 opencode 几乎把所有状态变化都建模成不可变事件这决定了它的可观测性、崩溃恢复能力和插件生态上限。如果你已经在用 AI 编程工具或者准备基于这类工具做二次开发或者只是对“agent 系统到底怎么管理状态”感兴趣这篇都能给你一些从源码而不是 demo 里得来的参考。我不打算复述文档只说我看源码时看到的设计决策、权衡取舍以及踩进去再爬出来才算真懂的坑。1. 第一眼迷惑第二眼惊艳为什么 opencode 真正值钱的是会话架构1.1 传统单会话模型的问题我实在见得太多了我最早接触的 agent 编码工具基本都是一个模型对话窗口包打天下用户输入、系统提示词、工具输出、文件 diff、终端日志全挤在同一个上下文字节流里。任务一长就会出现几个很典型的情况。首先是上下文污染。你让模型改完一个模块再改另一个前一个模块的大量中间日志还留在上下文里模型下一个动作可能还在被三个任务之前的报错影响。其次是状态不可恢复。工具执行到一半崩溃重新启动后一切归零用户只能重新描述自己的需求而执行器的“当时状态”——改了哪些文件、跑到哪个步骤、哪些副作用已经发生——全部丢失。最难受的是不可观测。你在界面上只能看到最终输出根本不知道内部到底按照什么顺序发生了哪批事件想排查“为什么模型突然调用了一次危险命令”没有任何审计依据。这不是功能问题是架构问题。只要把“用户对话”和“工具执行”塞进同一个会话对象状态必然会越来越混。1.2 opencode 的整体思路一句话版本我把 opencode 的会话模型归纳成一句话用户有一个会话执行器有另一个会话两者不共享状态只通过事件流交换信息。这个思路乍看很简单但它直接改变了整个系统的生命周期模型。用户侧会话保存的是意图、摘要、对话记录执行侧会话保存的是工作目录、环境变量、工具调用历史、文件变更记录。用户侧可以随时把上下文压缩成摘要丢给模型因为工具执行的大量中间数据本来就不需要给模型看执行侧可以做到精确恢复因为每一个文件读写、每一次命令执行都有事件记录。再往下走就是事件溯源。所有跨会话、跨模块的状态变化都先写进一条 append-only 的事件日志再由订阅方消费。也就是说系统没有一个“唯一的当前状态真源”真源是那段不可变的事件历史任何会话状态都可以从事件历史里计算出来。1.3 这篇上篇只讲骨架不展开执行循环我给自己定的解析范围是工程全景、双会话内核、事件溯源。这三块可以看成 opencode 的“地基”。地基之上还有代理执行循环、工具协议、扩展系统这些我打算放到下篇再单独讲。如果你上来就试图理解 opencode 的插件机制你会发现很别扭因为插件的生命周期和权限都是由双会话边界决定的如果你不理解事件溯源你也没法理解为什么一个工具调用结果可以跨进程恢复。所以这篇的定位就是先把骨架搭明白后续的细节才能挂上去。2. 工程全景代码库围绕“会话生命周期”而不是“功能菜单”来组织2.1 模块拓扑一览我第一次读完 opencode 的源码目录之后最大的感受就是它没有按“编辑功能”“聊天功能”“终端功能”这样的用户功能来分模块而是按“会话生命周期”来组织。所有模块都在为一个核心目标服务——把一次长期运行的编码任务拆成可恢复、可观察、可审计的状态流转。我把核心模块列成了一张表下面这张表基本是我反复读源码后自己画出来的拓扑模块核心职责关键依赖cli命令行入口、参数解析、界面渲染不做任何业务逻辑只依赖 session-coresession-core双会话内核管理会话 A/会话 B 的状态与生命周期无是整个系统的核心稳定层event-store事件存储、索引、快照、重放无只处理事件模型orchestrator编排模型调用、工具调度把两个会话的事件“翻译”给对方session-core, event-storetoolchain工具注册、参数校验、副作用调用、结果归一化session-core 提供的上下文接口runtime沙箱执行环境负责进程生命周期、环境变量、文件系统访问只被 toolchain 调用index代码索引、符号检索、语义查询为模型提供工程上下文可选依赖不介入主链路extensions插件系统的宿主与事件订阅接口大量依赖事件类型定义值得注意的一点是opencode 特意保持了模块之间的单向依赖。cli 和 extensions 都在最外层session-core 和 event-store 被设计成最内层的稳定边界。这意味着你在扩展时很难绕过会话内核去直接改状态所有写操作都必须通过事件接口。对一个插件生态来说这个约束救了大命插件作者不会把内核状态改乱。2.2 一次典型请求的完整数据流我习惯在读代码时把“一次用户请求”从头到尾走一遍比看任何流程图都管用。拿 opencode 里最常见的“让模型帮我改个 bug 并跑测试”来说真实的数据流是这样的用户在 cli 输入文字cli 把一个UserMessageSubmitted事件写入 event-store同时把该事件推给 session-core 的会话 A。会话 A 更新自己的消息列表随后把“有用户新意图”的通知发给 orchestrator。orchestrator 带着会话 A 的摘要上下文去调用模型模型返回的推理结果被流式写成一个序列的ModelTokenGenerated事件。当模型决定调用某个工具时orchestrator 不是直接执行工具而是先构造一个ToolCallRequested事件进入事件存储并把该事件投递给会话 B。会话 B 被视为“执行侧会话”它收到工具调用请求后才真正通过 toolchain 和 runtime 去执行。工具执行完成产生ToolCallSucceeded或ToolCallFailed事件结果写回 event-store并作为一条tool_result追加到会话 A 的消息列表中。会话 A 把工具结果带回给模型上下文模型继续后续推理直到产生最终答复。这里最有价值的点在第 4 步模型说“我要执行工具”系统把它当作一条待办事实写进日志而不是立刻执行。只要写进日志之后就算进程崩溃重启后也可以从“这条工具请求”处继续恢复而不是让模型重新从头推理一遍。2.3 决定全局基调的三个架构约束读这种复杂项目我习惯先总结它的“隐性宪法”。opencode 给我最深的印象是三个约束你可以把这三个约束当成本文后面所有解读的钥匙。第一个约束所有副作用必须先写事件、再改内存状态。哪怕只是记录一个文件读取也要先落事件再让会话状态做对应更新。第二个约束会话状态只能由自己的内核修改外部模块只能通过事件接口请求变更。第三个约束跨模块通信只通过事件总线或明确的消息接口禁止模块之间互相直接调用对方内部方法。这种设计短期看会显得“绕”但长期看收益极大——任何一次异常退出你打开事件日志就能把系统恢复到最后一条事实发生之前任何一次不确定行为也都可以通过事件回放复现。后面我讲双会话和事件溯源时你会发现所有特性都是从这三个约束里长出来的。3. 双会话内核用户看到的会话与工作区会话的边界设计3.1 两个会话到底在管什么双会话是 opencode 最容易被误解的名字。很多人第一反应会以为是“对话窗口”和“终端窗口”其实不是。它指的是两个抽象的会话对象一个我习惯叫它会话 A对话意图会话一个叫会话 B工作区执行会话。会话 A 的生存目标是“理解用户意图维护与模型的上下文”。它保存的是消息序列、上下文摘要、模型参数、工具结果的提炼结论。会话 B 的生存目标是“安全地执行动作维护工程状态”。它保存的是当前工作目录、环境变量、最近的工具调用、文件观察状态、尚未提交的变更。两者差异可以用下面这张表说清楚维度会话 A对话意图会话会话 B工作区执行会话生命周期跟随一段完整任务可长期存在跟随工作区实例可重建核心数据消息序列、上下文摘要、模型输出工具调用链、文件变更、运行时环境谁消费它大模型需要它做推理工具链和执行器需要它做动作恢复方式从事件流重放对话历史压缩摘要从快照 事件日志重建工作区状态对外可见性用户和模型可见对普通用户基本不可见会话 A 的恢复方式最有意思。它不是把全部历史原封不动地塞回模型而是把历史压缩成多层摘要。继续往上叠加新用户消息时模型看到的上下文永远是“早期摘要 最近 N 条完整对话”而不是所有细小工具调用的堆积。这个处理让长时间任务不会因为 token 增长而完全卡死。3.2 协作时序从一个最小示例看边界为了把双会话的边界说清楚我给它们建模成两个简单的接口。这不是直接从源码抄的是我按照 opencode 的设计原则做的等价提炼方便理解。type SessionAState { messages: Message[]; summary: SummaryNode[]; currentModel: string; }; type SessionBState { cwd: string; env: Recordstring, string; toolCallLog: ToolCallRecord[]; pendingChanges: FileChange[]; };它们之间不互相持有对方对象而是通过事件订阅进行协作。代码层面大概长这样// 会话A收到用户消息后广播事件 sessionA.on(userMessage, async (msg) { await eventStore.append({ type: UserMessageSubmitted, payload: { message: msg, sessionScope: A }, }); orchestrator.notify(sessionA.updated); }); // orchestrator监听事件生成工具调用请求 orchestrator.on(toolCallRequested, async (call) { await eventStore.append({ type: ToolCallRequested, payload: { tool: call.tool, args: call.args, requestId: call.id }, sessionScope: B, }); sessionB.enqueue(call); });这里的重点不是代码实现而是“切换”点从会话 A 到会话 B中间隔着一个写入了事件日志的工具调用请求。会话 A 不关心这请求最后由哪个进程执行会话 B 也不关心模型是怎么思考的。两边各自维护自己的状态靠事件记录完成握手。3.3 双会话设计带来的三个隐式收益第一个收益是长任务不“上头”。因为模型上下文由会话 A 管理执行器产生的海量日志不会自动进入模型视野模型只看到经过提炼的工具结果上下文更干净出错概率明显下降。第二个收益是并发和安全边界更清晰。多个工具可以并行运行但它们都在会话 B 的管辖范围内会话 A 同一时间只维护一条主推理链。权限检查也放在会话 B 入口一个插件想去读文件它要面对的是执行上下文的安全校验而不是“会话 A 里的某条消息”。第三个收益是崩溃恢复的粒度完全不同。会话 A 可以从事件日志里重建对话摘要会话 B 可以通过快照和日志重建工作区状态。两个会话可以分开恢复某一侧丢失另一侧还能兜底。这个特性对长时间运行的 agent 任务尤其重要后面我会专门讲恢复流程。4. 事件溯源先把状态放进“事实日志”再谈恢复与可观测4.1 事件模型与核心事件类型事件溯源的核心原则是系统状态不是被覆盖更新而是通过持久化的事件历史推导出来。opencode 把每个有意义的状态变化都定义成一条不可变事件。事件结构我给它最小抽象成如下形式interface EventRecord { id: string; seq: number; // 单调递增序号决定全局顺序 timestamp: Date; type: EventType; payload: Recordstring, unknown; sessionScope: A | B | SYSTEM; version: number; // payload 的结构版本 prevEventId: string | null; }其中seq是最关键的字段它保证了事件有一个全局稳定的先后顺序prevEventId则把事件串成一条链方便从任意位置开始回溯。opencode 核心链路里我梳理出的高价值事件类型大概有这些事件类型触发时机涉及会话关键 payloadUserMessageSubmitted用户输入新消息A原始文本、时间ModelTokenGenerated模型输出 tokenAtoken、推理 idToolCallRequested模型决定调用工具A→B工具名、参数、请求 idToolCallSucceeded工具执行成功B结果摘要、耗时ToolCallFailed工具执行失败B错误码、错误信息FileWritten文件被写入B文件路径、写入方式FileRead文件被读取B文件路径、读取范围SessionSnapshotCreated快照被持久化SYSTEM快照路径、覆盖事件 seqResultSummarized工具结果被提炼成摘要A原始引用、摘要文本这里需要注意ResultSummarized它是连接双会话的关键。执行器在会话 B 产生大量原始输出后会先写原始事件之后会话 A 侧还有一个“摘要事件”用来记录提炼后的版本。模型实际消费的是摘要事件的内容原始输出按引用存到别处。这个设计让我印象很深它其实是把“记录完整事实”和“节约模型上下文”两件事同时做到了。4.2 存储append-only 日志与索引两层结构opencode 的事件存储我把它分成两层理解底层是 append-only 日志段上层是面向会话维度的索引。底层日志只做一件事按seq顺序追加事件。写入必须顺序落盘不允许修改或删除已落盘的事件。这个特性让事件存储天然具备审计价值只要没人删除日志文件历史发生了什么永远查得到。上层索引是为了按会话、按时间范围快速查询。比如我查“会话 B 昨天上午十点的工具调用链”如果只扫日志段会非常慢所以事件存储会在写日志的同时建立二级索引。注意索引本身是可以重建的索引丢了不影响事实正确性重新扫一遍日志就能再建。我在本地测试时试过一个比较极端的场景一次性触发几百次文件操作观察事件写入。opencode 的处理是“先批量攒在内存缓冲再异步落盘”但seq在各自事件创建时就已分配所以回放顺序不会乱。这个异步设计也解释了为什么它可以在高频率工具调用下仍然保持 UI 流畅。4.3 快照与状态恢复恢复不是回放全部而是“快照 增量”事件溯源最大的口头问题是“如果事件积累得非常多回放是不是慢到没法用”答案当然是不能全部回放。所以快照机制就是标配。opencode 的策略我总结成三点快照生成是异步的由一个后台任务定期或按事件数触发。快照内容只是某个 seq 点上的完整状态不包含事件本身。恢复路径为加载最近快照 重放快照后的增量事件。比如一个任务产生了 20000 条事件系统每 5000 条做一次快照。恢复时只需要加载最后一次快照覆盖前 15000 条再重放最后 5000 条增量事件。这个成本基本可以做到秒级恢复用户体验上几乎感觉不到“回到过去”的延迟。快照本身也用SessionSnapshotCreated事件挂到日志里所以快照不是游离在系统之外的东西它也是事实日志的一部分。这个细节我很喜欢整个系统没有一个“事件之外的特殊状态”快照也只是一条可以被审计的事件。4.4 重放流程崩溃后它怎么知道从哪继续假设 opencode 在工具调用过程中进程崩溃了重启后恢复流程大体分三步加载最新的会话快照拿到快照点的 seq。从事件索引定位该 seq 之后的全部事件按顺序重放。重放过程中所有ToolCallSucceeded/ToolCallFailed事件不重新执行工具而是直接把记录下来的结果恢复给对应会话。重点在第 3 步。正因为事件日志记录的是“结果”而不是“过程重跑指令”所以恢复时不会把命令再执行一遍而是直接恢复已经发生的事实。这个细节直接避免了崩溃恢复时的二次副作用——比如一个写文件工具已经执行成功恢复时如果再执行一遍就会产生一次重复写入。opencode 的解法不是让写操作幂等而是让“重放的结果本身就是幂等记录”。我再把这个机制说得更具体一点。假设工具调用写文件 /src/index.ts已经记录为ToolCallSucceeded事件里有文件路径、写入内容引用、最终 hash。重放到这条事件时系统直接把“该写操作已完成”还原到会话 B 的状态里而不是重新调用写文件的函数。去做一次实际操作时需要的是新的意图事件而不是对老事件的重放。这就是“事件作为事实而非指令”的核心差异。4.5 边界控制不是所有东西都值得写进事件日志事件溯源容易走极端以为把一切全都丢进日志才算正确。opencode 在这件事上做了很多裁剪我梳理了四个边界模型原始输入输出默认不写入永久的完整事件只写入摘要和引用完整数据交给本地缓存。原因很现实模型输入输出体积大、token 多全部写进事件日志会让存储失控。终端命令的完整输出不直接进事件只有退出码、报错摘要、以及按行截断的关键输出会变成事件字段。文件 diffs 不会完整写到每个事件里更多时候只记录变化路径具体内容引用工作区对象的存储 ID。快照本身采取全量压缩而不是用事件日志反复追加同样的内容。这个边界的判断标准我一直觉得是进入事件日志的应该是“对后续状态恢复和审计有价值的不可变事实”而“大体积可重算的内容”应该放外部存储事件里只保留引用。如果你自己做类似系统这条边界是最值得抄走的经验。5. 源码阅读中踩到的坑我也替你踩了一遍5.1 事件格式没有版本号三年后就会变成垃圾场第一个坑其实是我在其他事件溯源项目里踩过、opencode 用 version 字段解决了的。事件 payload 结构一定会演进比如早期ToolCallSucceeded的 payload 只有路径和状态后来加了耗时、输出摘要。如果你没有 version 号老事件重放时会读不到新字段或者读爆老字段。opencode 的做法是在每个事件结构里显式声明version并让每个事件的 reducer 按版本做兼容。读取老版本事件时走老版本分支读取新事件时走新分支。这个看起来简单但我在很多项目里没见到导致无数老日志在升级后直接不可回放。我建议所有计划用事件溯源的人第一天就把 version 字段加上哪怕你觉得自己永远不需要它。5.2 快照频率要按“事件体量”而不是“时间间隔”opencode 的快照触发策略里时间不是一个强指标事件数或事件累计体积才是。我一开始尝试按时间做快照比如每半小时一次但实际跑出来的效果很不好空任务时半小时只有几条事件白白生成大快照密集任务时半小时可能已经产生了上万条事件恢复时重放增量太重。按累计体积触发会更合理。比如可以设定“事件日志累计超过 50MB 后触发一次快照”同时对单个大型工具输出做引用式存储避免事件日志虚胖。我给个小建议如果你的系统里事件多是小体积对象按条数阈值触发即可如果像 opencode 这样混有终端输出这类大体积对象按体积阈值更稳。5.3 回放时必须区分“重放结果”和“重新执行”这是事件溯源里最危险的一个点。我在自己的一个模拟项目里写过一个工具执行时会调用外部 API然后在事件里记录这次调用成功。后来做崩溃恢复测试时我把事件重放当成“重新执行任务”了结果外部 API 被连续打了好几次业务方都来投诉了。opencode 靠“执行器只在收到ToolCallRequested事件时真正执行重放时跳过已经存在结果的事件”解决这个问题。也就是说重放系统只恢复会话状态不驱动执行器再次执行。它把“事实的记录”和“动作的触发”分开了。这个原则非常值得强调事件日志绝不应该是命令队列它永远只是事实账本。5.4 排查问题最有效的方式是 dump 事件流最后一条是心得不是坑。当你搞不清楚 opencode 某个动作为什么发生时不要盯着 UI也不要只查会话状态直接把事件流按seq顺序 dump 出来看。因为事件流里记录了系统每一次跨模块交互比日志更完整比状态快照更细粒度。我在本地排查过一次“模型在没有任何用户新输入的情况下突然读取了某个文件”的问题。单看界面完全找不到原因后来把 sessionScopeB 的FileRead事件按时间线展开才发现是会话 B 启动时的文件观察器根据上一次工作区状态自动执行了一次预读取。这件事在最终用户界面上根本不显示但事件流里写得清清楚楚。6. 给想上手的人的一些实跑建议如果你看完这篇跃跃欲试想去读 opencode 源码我建议不要从 cli 目录开始翻因为 UI 代码只会干扰你对核心架构的理解。先读 session-core 和 event-store 两个目录把会话 A、会话 B 的状态对象和事件流跑通然后再读 orchestrator看它怎么把事件从 A 侧翻译到 B 侧。等这三块有了全局图再去看 toolchain 和 runtime最后再碰 extensions。我实际跑下来的体会是opencode 的代码库对“上层扩展者”非常友好但前提是你得先接受它的写作层——所有交互建模成事件。不要试图在代码里找到修改会话状态的全局函数你找不到的你能找到的只有 append 事件、消费事件、重建状态。如果你只是想要一个可恢复的编码 agentopencode 已经做了不少事情如果你是想从它的双会话与事件溯源架构里借鉴设计这篇上篇应该给了你一个相对完整的框架。下一篇我会继续沿事件流往下走深入到代理执行循环、工具协议格式以及扩展开发的实际接入方式。到时会拿一个完整的第三方工具接入示例来说明事件总线上的插件到底是怎么被挂载进去的。