如果你最近在关注 AI 编程工具很大概率已经听说过opencode。它不是又一个 IDE 插件也不是一个聊天框套壳而是一个跑在终端里的智能体运行时。你也许已经体验过它的 TUI 界面或者用过几条斜杠命令但真正把源码拉下来读的时候会发现这个工程的复杂程度远超预期。这篇是“深入 opencode”系列的上篇我会把三个最核心的骨架讲透工程全景、双会话内核、事件溯源。适合两类人看一类是被 opencode 勾起了好奇心、想把它当成源码范本研究的同学另一类是正在做自己的 AI 代理工具想找一套成熟架构作为参照的开发者。建议读之前先在终端里正常跑一个opencode会话哪怕只是问一个最简单的问题后面聊到的很多概念会更有实感。1. 工程全景它不是一个 CLI而是一个运行时1.1 从命令行入口看整体定位opencode的外层是一个标准的 CLI 程序你输入opencode回车它会弹出一个全屏 TUI这个过程和很多终端工具没有区别。但如果你只把它当成一个现代化的tmux或者fzf来理解会错过重点。它的真正价值不是交互界面而是怎么把“用户意图”变成“一连串可执行的工具调用”再把结果高效汇总结论。我第一次拉下源码后第一反应是找main入口然后顺着参数解析往下看发现它虽然启动的是终端界面但核心逻辑几乎没有绑定在 UI 上。消息进来之后被放入一个消息总线接着由会话管理器接管再被路由到某个 agent 引擎引擎决定调用什么工具工具执行的结果又变成新的事件回到总线。界面只是订阅了这些事件并渲染成你可看到的样子。这意味着它在设计上其实是一个 headless 优先的运行时TUI 只是其中一个客户端。这种架构带来的直接好处是你可以用同样的内核去接不同的前端。有人用 API 模式直接和它通信有人把它嵌入自己的 CI 流程有人甚至写了一个简单的 Web 页面去连接它。对于想二次开发的人来说这是一个很舒服的边界你不需要重写 AI 逻辑只需要往总线上发消息、订阅事件。1.2 核心模块拆分一张地图我梳理源码时习惯先画模块地图再用代码验证自己的理解。opencode 的工程设计中至少能拆出下面这些相互协作的部分模块主要职责备注CLI 入口参数解析、命令分发、交互模式选择是启动的最小单元逻辑很薄会话注册中心管理所有会话的创建、查找、撤销、生命周期双会话内核的关键依赖消息路由将输入消息投递到正确的会话队列核心是保序和去重agent 引擎循环执行“思考-调工具-观察结果”的过程类似 ReAct 模式的具体实现工具执行层注册、沙箱、执行各类工具文件读写、终端命令、代码搜索等事件总线发布/订阅所有领域事件整个系统解耦的基石投影/状态视图从事件流中重建会话状态、渲染树事件溯源的重要落点存储层追加事件日志、快照、配置文件通常以 JSON Lines 或 SQLite 形式存在这套模块不是各自独立的而是围绕事件流串联起来的。你会发现各个模块之间很少有直接的接口调用大多通过事件广播互相通信。比如模型返回了一段增量文本模型网关并不会直接去更新 UI而是发一个assistant_message_delta事件订阅了该事件的投影器再更新状态UI 再渲染状态。这个后面讲事件溯源的时候还会深入。1.3 关键设计取向本地优先、模型无关、可扩展opencode 作为一个开源项目有几个设计取向值得学习。第一个是本地优先。所有会话记录、事件日志、配置都存放在本地目录它不会强制把数据上传到某个服务端。你在本地启动的智能体读完代码、执行命令的记录都留在你的机器上。数据归用户这在隐私敏感的开发场景下是一个很坚定的立场。第二个是模型无关。它没有把自己绑定在某个大模型 SDK 上而是定义了一套抽象的 Provider 接口。你可以配置 OpenAI 兼容接口、本地推理服务或者其他自定义模型端点。只要实现接口就能替换内核里的大模型。这个设计在我们自研工具时尤其重要因为模型迭代太快有一天想换国内服务商或者公司内部模型不需要动主逻辑只要写个新的 Provider 适配层。第三个是可扩展性。除了内置工具opencode 允许通过配置或者插件机制新增自定义工具。扩展点设计得像积木一样而不是改源码。我在实际项目里加过几个内部工具体验下来这部分的抽象确实做得比较干净你只需要声明工具的名字、参数 schema、执行函数然后重启就能在智能体环境里被调用。2. 双会话内核并行对话与状态隔离2.1 什么是双会话主会话与子会话opencode 最让我眼前一亮的地方是它内部并不是只有一条会话线。它把“你和 AI 的对话”和“AI 为完成任务临时开启的内部对话”区分开我称之为双会话内核。主会话就是你看到的那条会话记录着你和助手的完整聊天历史。它的职责是理解你的需求、展示思考过程、汇总最终结论。子会话则是智能体在执行复杂任务时创建的临时会话用来做局部探索搜索代码、读取文件、运行命令、分析测试结果。子会话和主会话不在同一个上下文窗口里。为什么要这么设计用一个生活类比来解释。主会话像一个项目经理子会话是项目组里的工程师。项目经理不会自己去写每一行代码而是把任务拆给工程师工程师完成后再向项目经理汇报结论。如果项目经理把每个工程师的每一句闲聊、每一步操作都记住那脑袋早就炸了。双会话的核心就是避免无关时刻的细节污染主上下文同时让不同子任务可以并行跑互不干扰。我在实际体验中见过一个很典型的例子你让 opencode 把某个模块的接口从回调改成 Promise。主会话拿到这个需求后大概率会先创建一个子会话去扫描目录结构再创建另一个子会话去搜索所有调用点还可能开一个子会话查看测试用例的现状。每个子会话都只看自己关心的文件都拥有独立的上下文。等它们都结束后主会话把各自的输出汇总成一个改动方案再向你反馈。如果没有双会话机制这些中间状态会全部塞进同一个上下文很快就把窗口打满模型也开始忘掉前面说过什么生成质量直线下降。2.2 子会话的完整生命周期子会话不是临时一发就消失它也有完整的生命周期。理解这个生命周期对你调试程序很有帮助。子会话的创建通常发生在一个 task 类工具被调用时。agent 引擎会首先评估当前主会话的上下文决定需要哪些信息然后向会话注册中心申请一个新的子会话 ID。这个子会话有自己的提示词前缀通常是“你是一个负责搜索代码的助手”“你是一个负责运行测试的助手”之类的系统指令。它会拿到一个受限的工具列表比如只能搜索文件、只能执行测试命令而不能任意修改文件。执行过程中子会话会不断向事件总线发送自己的状态变化。刚开始时是subsession.created然后是一连串tool.result事件。主会话并不关心子会话内部每一句话它只关心最终结果。所以子会话结束后会生成一个结构化的摘要包含目标、执行步骤、关键输出、结论。这个摘要才是被送回主会话的消息内容。子会话的生命周期终结有三种方式正常完成、被父会话取消、异常超时。正常完成会触发subsession.completed事件调用方拿到结果取消一般发生在用户中途打断或者主会话判定任务已经不需要继续时异常超时则依靠调度器设置的时限比如一个搜索任务超过 3 分钟没返回就会收到超时信号强制回滚。2.3 上下文传递与剪裁策略双会话之间传递的不是原始对话记录而是“投影”出来的结论。这一点是最关键的也是最容易被忽略的。如果把子会话的整个日志塞回主会话那和不用双会话没有区别。opencode 的做法是让子会话在结束时产出摘要这个摘要可能是“在 src/modules/ 下找到了 3 个调用点分别位于文件 A、B、C第 57 行和第 89 行”而不是把每一次 grep 结果都贴回去。从工程实现上看这涉及两个方向的剪裁。一个是向下剪裁主会话在给子会话派发任务时会尽量只给它必要的信息而不是把整个当前对话历史丢过去。另一个是向上剪裁子会话返回给主会话的内容也要经过整理去掉过程的噪音只留下结论和依据。我最初用这类工具时踩过一个典型的坑自定义工具返回了非常长的原始结果导致主会话拿到后上下文瞬间消耗掉两三万 token。后来我参照这种双会话思路在自研工具里给每个工具的输出都增加了一个“摘要模式”默认只返回关键命中区域和统计信息。效果立竿见影不仅 token 费用降低对话质量也稳定了很多。2.4 双会话带来的并发机会与风险双会话除了隔离还提供了并发执行的可能。因为子会话之间是独立状态你同时开三个子会话一个查文档、一个写代码、一个跑测试它们在理论上是可以并行推进的。opencode 的调度器里支持这种并发任务组最终等所有子任务返回后再汇总。但并发也带来风险最麻烦的是对共享资源的竞争。比如两个子会话同时修改同一个文件如果没有任何协调机制后完成的一方可能覆盖先完成的一方。opencode 里的解决方式是在工具执行层设置文件锁或者要求每次写操作都基于最新的文件状态进行。我在自己的项目里也借鉴了这一点给每个子会话分配独立的工作目录只有在最终合并阶段才统一写入主目录。这样既避免了竞争又让每个子会话的中间过程可追溯、可回滚。3. 事件溯源把整个系统变成一条可回放的河3.1 为什么选择事件溯源而不是保存状态快照很多应用在存储会话状态时都是直接存一张当前状态表ID、时间、消息列表、token 数之类的字段。opencode 没有走这条路它的内部存储核心是事件日志所有状态变化都被描述为一个又一个不可变的事件按顺序追加到日志里。要把系统恢复到某个时间点只需要从头开始重放事件流一步步重建状态。这就是事件溯源Event Sourcing。用一个最简单的例子说明假设我们要记录“会话 Token 消耗量”。传统做法是维护一个字段每用一点就更新这个字段。事件溯源的做法是不记录当前用量而是存储token_usage_accumulated事件每次模型返回后追加一个事件事件里带着增量。当前总用量由这些增量累加得到。这意味着你永远不会丢失中间过程随时可以回到第 100 条事件发生时看看当时的 token 用量是多少。opencode 选择事件溯源我认为不是追求时髦而是因为它的运行场景太需要可重放性了。一个智能体会话可能长达几个小时期间会调用几十个工具模型流式输出几十次。如果只存最终状态一旦某个环节出了问题你很难还原“当时到底是哪一步导致错误”。事件日志则把整个推演过程完整保留下来了。3.2 领域事件清单系统里都流动着什么在 opencode 的源码中事件不是随便发的每个事件都有明确的类型和结构。我整理了最核心的几类事件类型触发者关键内容主要消费方session.created会话管理器会话 ID、初始化参数UI、存储user.message.posted用户输入入口消息 ID、文本内容、附件引用agent 引擎assistant.message.delta模型网关增量文本、消息 IDUI 渲染器、投影器tool.invocation.requestedagent 引擎工具名、参数 JSON工具执行器tool.result.received工具执行器工具名、输出、执行耗时、状态码agent 引擎、观察器等subsession.created任务调度器父会话 ID、子会话 ID、目标描述事件总线、调度器自身subsession.completed任务调度器子会话 ID、摘要结果、耗时父会话投影器error.occurred任意模块错误类型、堆栈、相关会话 ID日志、监控、故障恢复每一个事件都是一个独立的、不可变的对象通常会带上时间戳、顺序号、唯一事件 ID。我见过的事件结构里至少包含eventId、eventType、occurredAt、sessionId和payload有些还会带parentEventId来记录事件之间的因果关系。3.3 状态是如何从事件流中被“投影”出来的事件溯源里有个专业术语叫“投影”Projection。意思是你维护一个小的状态模型每当事件到来时就更新它。这个状态模型可以被随时丢弃然后重新从所有事件中构建。用伪代码可以很直观地表达这个过程。假设我们要构建会话的当前 UI 树type DomainEvent | { type: session.created; sessionId: string } | { type: user.message.posted; sessionId: string; message: string } | { type: assistant.message.delta; sessionId: string; delta: string } | { type: tool.result.received; sessionId: string; tool: string; summary: string }; class ChatState { messages: Array{ role: user | assistant; text: string } []; recentToolResults: Array{ tool: string; summary: string } []; apply(event: DomainEvent) { switch (event.type) { case session.created: this.messages []; break; case user.message.posted: this.messages.push({ role: user, text: event.message }); break; case assistant.message.delta: // 实际实现中需要对同一个 assistant 消息做追加拼接 this.messages.push({ role: assistant, text: event.delta }); break; case tool.result.received: this.recentToolResults.push({ tool: event.tool, summary: event.summary }); break; } } } // 从零开始重放所有事件 const state new ChatState(); for (const event of eventLog) { state.apply(event); }这段代码可能只有十来行但它是 opencode 内部许多投影器的缩影。真实工程里投影器会分为好几个一个负责消息列表一个负责 token 统计一个负责工具日志一个负责 UI 的折叠面板状态。这样各个投影器只需要订阅自己关心的事件互不依赖也方便独立扩展。3.4 快照与压缩不要让事件日志无限膨胀事件溯源有一个绕不开的问题如果事件量非常大每次重放全部事件来构建状态耗时和存储都会失控。实际工程中的标准解法是定期打快照。快照就像你做笔记时的阶段性总结把从开始到当前时刻的所有事件 “浓缩” 成一个状态对象存储下来。之后再来新事件就从快照状态开始增量应用而不需要从头重放全部。opencode 的存储层里应该存在类似 snapshot 的机制。它每隔一段时间、或者每 N 条事件就把当前会话的关键状态保存一次。重放时先加载最近的快照再应用快照之后产生的事件。这个设计既保证了可回溯性又兼顾了恢复速度。我在自研系统里也这样做过恢复时间从几十秒降到了几百毫秒非常明显。快照的频率需要平衡太频繁会导致写放大太稀有每次恢复都会慢。我自己的经验是每 100 个事件做一次快照是一个合理的起点之后可以根据事件平均大小和恢复耗时的观测数据再调整。3.5 事件溯源带来的额外能力审计、断点续跑、时间旅行除了状态恢复事件溯源还带来了几个意想不到的好处。一是审计能力。因为所有操作都有事件记录你可以精确回答“这个文件是什么时候被谁改过”“那次删除操作是在哪个工具调用中执行”。尤其是团队使用或者需要对外交代时事件日志就是一个不可篡改的证据链。我参与过一个内部工具当时审计要求记录每个 AI 请求是否读取过客户数据事件日志直接帮我们把整个请求链路做好了摘录。二是断点续跑。如果进程意外崩了传统方案恢复后只能拿到一个状态快照或者数据库里最后一次保存的数据之前进行到一半的任务可能就丢了。事件溯源则可以根据最后的已知事件加上 snapshot重建到崩溃前那个时刻的状态然后继续处理剩余的事件相当于给系统加了一个“回滚点”。三是时间旅行。做调试时你可以在事件流上随意移动回到某个事件发生时看看那时的上下文是什么模型为什么在那一步选择了这个工具。这种能力对复现 bug 极有价值。因为 AI 程序有随机性一次运行结果往往不能总复现。但如果把事件流记录下来你可以快速回放同一个事件序列观察不同阶段的行为定位问题出现的边界。4. 实操体会从事件流追踪一次真实会话4.1 打开事件日志感受序列化格式如果你已经装好了 opencode想立刻体验事件溯源最简单的方法是打开它的事件日志。一般在本地数据目录下会话会以 JSON Lines 的格式记录。每一行是一个独立事件例如{eventId:evt_01GQ...,type:user.message.posted,sessionId:sess_01H2...,occurredAt:2025-01-15T10:24:01Z,payload:{message:优化一下首页加载速度}} {eventId:evt_01GQ...,type:subsession.created,sessionId:sess_01H2...,occurredAt:2025-01-15T10:24:05Z,payload:{subsessionId:sub_x21...,goal:分析首页加载流程}} {eventId:evt_01GQ...,type:tool.result.received,sessionId:sess_01H2...,occurredAt:2025-01-15T10:24:09Z,payload:{tool:read_file,summary:读取了 src/frontend/index.html, 共 1320 行}}第一次看到一个真实会话的事件流你会理解什么叫“将一切运行过程都记录在案”。这比只看最终回答要清晰得多。我甚至建议你在调试时直接把终端放在日志文件旁边一边操作一边用tail -f看事件随操作实时流动那种感觉就像在看一个系统的心脏搏动。4.2 一个典型调试追踪流程有一次我想弄明白为什么某次重构建议里它选择了 A 方案而不是我预期中的 B 方案。我没有去看自然语言输出而是直接打开事件日志过滤出subsession.created、tool.result.received和subsession.completed三类事件。很快发现在开子会话之前主会话先调用了一个搜索工具这个工具只在某个特定目录下做了匹配而 B 方案所需要的源码并不在那个目录里。于是智能体在没有找到关键文件的情况下自然选择了 A 方案。这个排查过程如果只看最终对话哪怕反复问“你为什么不选 B”模型也只能根据自己的记忆解释而记忆可能已经模糊了。但事件日志能给你一个无可辩驳的答案就是某一步工具调用范围限制导致的。这让我对事件溯源的调试价值有了非常切实的感受。你也可以写一个小脚本统计事件类型出现的频率。下面是我经常用的一个统计片段用来了解一个会话里模型调用、工具调用和子会话创建的比例import json from collections import Counter counter Counter() with open(session.jsonl, r) as f: for line in f: event json.loads(line) counter[event[type]] 1 for event_type, count in counter.most_common(): print(f{event_type:40s}: {count})这种统计往往能揭示一些隐藏问题。比如你会发现subsession.created很多但subsession.completed很少那大概率是子会话被强制取消或者超时了需要检查一下任务调度器里的超时配置。如果assistant.message.delta事件特别多说明模型输出碎片化严重可能是流式拼接逻辑有优化空间。4.3 怎么调试事件抖动和死锁双会话并发跑起来之后偶尔会遇到会话状态不一致的问题。最常见的症状是主会话界面卡住子会话显示已完成但主会话没有收到结果。这种问题通常出在事件投递或订阅环节可能原因包括事件总线上的消费者抛异常导致后续事件没有继续处理或者父子会话之间的 result 事件没有带上正确的parentEventId被投影器判定为无关事件丢弃了。我在调试这类问题时会先打开 debug 日志在事件总线模块里打印每个事件的投递路径。然后人工构造一个简单场景只创建一个子会话让子会话调用一个立即返回的简单工具观察事件顺序和预期是否一致。如果这一步正常再逐渐增加复杂度很快就能定位是哪一层丢了联系。另外如果事件流里有重复事件投影器最好做幂等处理。实现方式很简单给每个事件带上唯一 eventId消费的时候把已经处理过的 eventId 记在一个集合里重复事件直接跳过。否则在快照恢复或者重放时一个事件被应用两次可能会让计数器翻倍状态就歪了。5. 常见问题与排查技巧实录5.1 会话恢复速度越来越慢如果你发现 opencode 启动或者恢复一个长会话需要很长时间先看看事件日志和快照的比例。如果 1000 个事件里都没有几个快照那每次恢复就要从头重放全部事件肯定会慢。解决思路是增加快照频率。如果你用的是 SQLite 存储还可以检查是否给session_id和event_id建了索引。再往深处想慢不一定在重放本身也可能在投影器里。有些投影器每次应用事件时都会做一些高开销操作比如解析大文本、生成渲染树。如果投影器不是增量的而是每次全量重建那即使有快照也会慢。这时候可以把投影结果也缓存起来只在收到新事件时才更新对应增量部分。5.2 子会话返回结果太大把主会话上下文塞爆这是最容易踩的坑之一。即使采用了摘要机制有些子会话返回的结构化数据依然可能很大尤其是当你让子会话读取了一个超长文件并原样返回内容时。解决办法是在工具层做输出限制。我给自己的工具添加的最实用的限制是默认返回开头和结尾各 50 行中间用省略标记同时附上行数统计。模型看不懂完整内容时会主动决定是否要分段读取。另外在子会话返回主会话前主会话也会应用一个“压缩器”把长文本改写成章节摘要如果它发现负载超过阈值会主动触发一次摘要提炼。5.3 并行的子会话互相覆盖文件这个前面提到过再展开一些具体排查方法。假设两个子会话同时写同一个目标文件你可以在工具执行层维护一个简单的文件锁表工具执行前检查锁如果锁被占用就返回一个明确的冲突错误。更优雅的做法是让子会话只写到一个独特的临时文件等汇总后由主会话统一合并。我发现这个做法还有一个额外好处临时文件路径里可以带上子会话 ID万一写了一半坏了你能精确知道这个残留文件来自哪次任务不会误删其他有效数据。5.4 事件流顺序乱掉并发环境中事件到达总线的顺序可能和实际发生顺序不完全一致。如果投影器直接按到达顺序应用状态很可能把结果搞错。解决办法是为每个事件分配单调递增的序号并让投影器基于序号排序后再应用。这里要小心的是不同会话的事件不能用一个全局序号硬排否则性能会有问题。正确做法是每个会话有自己独立的序号序列跨会话的事件在最终合并时通过parentEventId关联。5.5 日志文件体积失控长时间使用的会话事件日志可能膨胀到几百 MB。除了快照之外你还可以对历史日志做归档压缩超过一定期限的日志可以压缩成.gz后缀存档。如果不需要审计功能甚至可以定期清理过期的子会话事件只保留主会话的关键事件和摘要。这会让存储占用大大缓解而且对于一般调试需求损失的信息不多。最后再说几句我已经在不少自己的小项目里尝试模仿 opencode 的设计思路最大的体会是事件溯源让系统变得透明双会话让系统变得可控但两者都有代价。事件溯源要求你从一开始就约束好事件结构中途再改事件格式会非常痛苦双会话要求你认真设计上下文传递协议否则很容易在其中一层把信息丢得无声无息。这些复杂度值得付出吗我的答案是值得尤其是当一个 AI 工具开始被真实用户使用、需要排查线上问题、需要回放推理过程时前面多花的时间都会连本带利赚回来。这篇先把骨架讲清楚了下一步我打算继续聊模型网关和工具生态包括 provider 抽象的具体实现、插件系统如何注册新工具、以及 agent 引擎里的循环终止策略。这些都是把 opencode 从“能用”推向“好用”的重要拼图我们留在中篇细说。