1. 从一次长任务说起交互与执行为什么要各干各的我印象很深的一次使用经历是让 opencode 跑一个大范围的重构任务——扫描整个服务端模块、批量替换接口签名、再逐文件检查调用链。按照大部分同类工具的惯性这种任务一跑起来整个会话基本就“卡死”了你只能盯着输出等它结束哪怕只是中途想追加一句“别忘了更新测试文件”也得等当前那一步完全停掉。但那次我输入完指令之后居然还能继续在同一个界面里发下一条消息。更离谱的是重构任务还在后台执行时我新发的指令已经被正常接收两条不同性质的对话在同一个会话上下文里并行推进互不阻塞。那一刻我意识到这个项目的内核设计绝不是“一个 for 循环从头跑到尾”的简单调度而是一套有真正设计意图的并发模型。带着这个疑问去读源码我梳理出了这篇上篇的三个核心线索工程全景、双会话内核、事件溯源。简单说工程全景解决的是“整个项目怎么长”的问题双会话内核解决的是“交互和执行怎么并行且互不干扰”的问题事件溯源解决的则是“每一个状态变更怎么被记录、回放和恢复”的问题。这三条线索实际上是一条连贯的主线正是因为有了事件溯源双会话之间才可能做到状态一致正是因为有了双会话隔离交互层才不会被执行层拖垮。这篇文章面向的读者是那些已经用过类似 AI 编程辅助工具、想进一步理解其工作原理的人。我会直接从源码阅读的视角出发把模块边界、数据流、会话生命周期、事件类型讲清楚不堆概念尽量让每个结论都能对应到代码行为上。1.1 一次长任务暴露出的单体会话瓶颈如果只是做一个普通的“请求-响应”式工具单体会话完全够用用户发一句话模型回一段话再触发一次工具调用串行结束。但 opencode 这类工具真正复杂的地方在于一次用户指令往往会产生多条并发的工具调用链——读文件、跑测试、改代码、再读文件而且其中任何一步都可能耗时十几秒甚至几分钟。如果整个会话只有一个执行队列交互层就只能等执行层结束才能响应新消息这是典型的单体瓶颈。我把单体会话的痛点归纳为三点阻塞执行层的长任务占住主循环交互层无法及时响应新指令。无状态隔离工具执行中的中间状态和用户对话上下文混在一起出问题时很难定位是哪个环节引入的。恢复困难如果整个会话是“一次性计算”的产物没有结构化的变更记录想恢复一个断掉的会话就只能重新跑一遍成本极高。这些痛点决定了凡是认真做编码代理的工具最终都会走上“职责分离 事件记录”的路。opencode 的特别之处在于它把这种分离做得比较彻底直接把会话拆成两个内核再用事件流把两者串起来。1.2 双会话和事件溯源不是炫技而是工程必然可能有人会问为什么不直接在线程池里跑工具调用非要搞双会话我的理解是线程池解决的是“并发执行”的问题但解决不了“状态归属”的问题。一个工具调用产生的中间态到底属于用户对话还是属于某个后台任务如果下一次用户指令需要参考上一次工具的输出这个上下文应该从哪里取这些问题用线程模型很难优雅地回答但用“两个会话各管一段 事件流统一记录”的模式却非常自然。所以双会话内核和事件溯源在我的理解里是一对配套设计双会话负责把“交互”与“执行”两种职责在空间上分开事件溯源负责把“发生了什么”在时间上完整记录下来。两者结合工具才能在并行推进的同时保证任意时刻的状态都可以被重建、被审查、被解释。2. opencode 工程全景模块边界与一次请求的完整旅程在深入双会话之前我先用一张“静态地图”把工程结构过一遍。读一个中大型开源项目最忌讳一上来就钻进某个文件里抠细节那样很容易在局部迷失方向。我习惯先找入口、先画模块、先理数据流把骨架搭起来之后再往里填细节。2.1 从整体看opencode 大致分为六块我把当前看到的架构理解整理成了一张表模块职责关键观察点CLI 入口层解析命令、加载配置、启动服务参数定义、配置文件发现规则配置与凭证层管理模型供应商配置、密钥、环境变量配置合并优先级、密钥存储方式会话管理层创建/恢复/销毁会话维护会话列表会话存储目录、会话元数据格式模型网关层统一对接各家模型服务商处理流式输出和工具调用协议消息协议转换、工具结果回传格式工具执行层执行代码操作类指令如文件读写、命令运行、搜索工具注册表、权限提示、超时控制事件存储层记录会话中的所有变更事件支持回放和恢复事件类型定义、持久化格式这张表只是静态分层真正重要的是这些模块之间的动态关系。opencode 的分层思路其实不算特殊特殊的地方在第 3 层的“会话管理”——它是双会话的载体也是事件流的锚点。2.2 一次普通提问数据是怎么流转的我梳理了一下“用户输入一句‘帮我看看 src/main.ts 这个文件’之后数据在内部走的路径”大致是这样的CLI 入口接收输入把原始文本封装成一条用户事件推入事件流。会话管理层把这条事件交给模型网关由网关拼接会话上下文并请求对应的模型服务商接口。模型流式返回结果其中的文本片段被逐渐渲染到界面上如果是结构化响应比如声明要调用某个工具这条声明会作为一条新事件写入事件流。双会话中的执行会话接管工具调用声明校验工具是否存在、参数是否合法并通过权限确认后真正执行文件读取。工具执行结果被包装成一条工具结果事件回传给交互会话再由交互会话把结果追加到上下文触发模型的下一轮回复。整个过程里用户看到的始终是“一个会话在被连续回答”但实际上背后的数据经过了至少两种不同角色会话的切换。这个切换逻辑就是第 3 章要展开的双会话内核。2.3 配置系统和模型网关的抽象逻辑顺带说一下我读配置系统和模型网关时的感受。这两块虽然不直接决定会话内核的成败但它们是工程全景里很容易被忽略的“地基”。配置系统采用的是“分层合并”的常见做法默认配置打底然后叠加用户级配置文件再叠加项目级配置最后允许环境变量覆盖。高优先级覆盖低优先级这套逻辑很朴素但很稳。我几乎没有在配置合并上看到任何花哨设计这在工程上是优点——配置系统越直白越不容易出玄学问题。模型网关的抽象思路更有意思。它没有为每家模型服务商单独维护一套会话逻辑而是用一个统一的“消息序列 工具声明”结构去适配各家 API。也就是说交互会话里保存的并不是某家服务商私有的消息格式而是一套中间表示。模型网关负责翻译而不是负责记忆。从工程全景的角度看这是保证“换模型服务商不换会话结构”的关键设计。3. 双会话内核并发、隔离与协作的关键设计双会话是这篇的核心章节也是我最想展开讲的部分。网上聊 opencode 的文章不少但大多聚焦在“怎么安装、怎么配置、它能干什么”的产品层面很少有把“为什么它这么流畅”的底层逻辑讲透的。这里我尝试把自己读代码时的理解完整还原出来。3.1 双会话不是双线程而是两种职责的物种隔离先说一个容易踩的误区双会话并不是简单地开了两个并发线程一个跑交互、一个跑执行。线程只是执行载体双会话的核心是状态隔离和职责分离。交互会话负责和用户对话、维护 LLM 上下文、处理流式输出。它的状态指向上一次用户消息、模型回复、当前正在等待什么。执行会话负责运行工具调用、管理文件的读写副作用、收集工具返回结果。它的状态指向当前有哪些工具在跑、各自的执行状态如何、中间产生了哪些输出。两者各自持有独立的内部状态。交互会话被用户新消息打扰时不需要关心后台工具跑到哪一步执行会话被长任务阻塞时也不需要关心界面上有没有新输入。这就是“物种隔离”的含义——两类状态从根本上就不放在一起所以它们天然不会互相污染。用个生活化的类比交互会话像是餐厅前台的领位员执行会话像是后厨的灶台。领位员接待新客人时不会因为后厨某个菜还没出锅就停下来干等后厨做菜时也不会因为前厅来了新客人就放下手里的锅。两者各干各的靠一张菜单事件流保持信息同步。3.2 会话的创建与生命周期什么时候拆、什么时候合读双会话实现时我最关注的其实是生命周期管理。一个会话从创建到销毁中间会经历哪些阶段什么情况下需要新建执行会话什么情况下要复用以我目前的理解交互会话的创建通常发生在一个新对话启动时——用户输入第一条消息CLI 初始化一个交互会话给它分配一个全局唯一的会话 ID。执行会话的创建则不一定同步发生。在纯问答场景比如“解释一下什么是依赖注入”工具未必会参与此时可能根本没有执行会话被创建所有流转只在交互会话内部完成。一旦模型声明需要调用工具执行会话才被“按需创建”。这个懒加载设计很妙它避免了大批纯问答场景被无谓地扣上执行会话的开销。执行会话被创建后会绑定到发起它的交互会话上之后同一交互会话里的后续工具调用可以复用同一个执行会话因为执行环境如当前工作目录、已加载的上下文文件是有延续性的。生命周期上执行会话通常会跟随交互会话一起结束但也存在一些特殊情况。比如一个长任务还在后台执行时用户如果主动结束对话工具执行层有一定的机会先把任务收尾避免留下半截文件写入。这个细节我在源码里没有看到太复杂的补偿机制更多是靠事件流记录状态等下次恢复时再决定要不要继续。3.3 双会话之间到底传什么核心是“消息事件”的协作协议双会话协作的关键在于两者之间传的不是“函数调用”而是“消息 事件”。交互会话向执行会话发出的不是“去读这个文件”的指令而是一条“模型已经声明要读取 X 文件”的消息执行会话收到消息后校验并执行再把结果包装成一条事件写回事件流。交互会话看到这条事件后把它追加到上下文中触发下一轮模型推理。这套“消息驱动 事件回传”的协作协议有几个明显好处解耦交互会话不用关心工具具体怎么实现执行会话也不用关心模型上下文的拼接方式。可观察每一次协作都留下事件记录事后可以完整还原“谁什么时候触发了什么工具、结果如何”。可中断因为协作本质是消息传递而非阻塞式函数调用用户新消息可以先进入交互会话不必等待执行会话返回。我在读这个协作协议时特别注意了异常情况的处理。比如工具调用超时或执行出错时执行会话并不会直接打断交互会话的上下文而是把错误包装成一条工具结果事件回传。由交互会话决定是终止整个流程、还是调整策略重试、还是把错误信息原样展示给用户。这种“错误上抛给交互层决策”的设计让职责边界更加清晰执行层只负责“尽量执行好”决策永远是交互层的事。3.4 双会话的同步策略与一致性问题双会话各自独立但不代表它们可以完全不管对方。事件流在这时候充当了“同步总线”。一次工具调用的完整生命周期会被拆成多条事件开始事件、输出增量事件、结束事件含结果、错误事件。无论哪一个会话先看到这些事件最终都汇聚在同一条流上所以两者之间不存在传统意义上的“共享变量竞争”而是通过对同一事件流的先后消费达到最终一致。这个设计也解释了为什么 opencode 在多步骤任务中界面不会乱前厅和后厨各自忙自己的但菜单上的每道菜都有明确的时间戳和归属会话 ID绝不会出现“这条输出到底是用户说的还是工具跑的”这种模糊情况。阅读代码时我特别留意了事件 ID 和时间戳的生成规则确认它们是在全局范围内有序递增的。这件事看似小事却是事件回放和会话恢复正确性的根基。4. 事件溯源把会话变成一条可重放的事件流事件溯源Event Sourcing这个词最早出现在领域驱动设计的语境里核心思想是“不保存状态的当前值而是保存导致状态变化的所有事件”。opencode 把这一套用到会话管理上其实非常自然——因为一次会话本质上就是一个不断累积事件的过程。4.1 为什么不是直接存快照而是存事件流先对比两种方案。如果每次会话状态改变都直接存一个“最新状态快照”实现简单、读取快但代价是丢失了历史过程。比如一次文件修改快照只能告诉你“文件现在是这个内容”但你需要知道“为什么要改成这样前一版是什么改的时候工具输出过什么警告”时快照完全无能为力。事件流方案反其道而行之每次状态变化都追加一条不可变的事件当前状态不直接存需要时通过“重放事件流”投影出来。代价是读取状态时需要一点回放开销收益却是历史完整可追溯。对于编码代理这类工具事件流几乎是必然选择——使用过程中本来就需要回答这类问题“上次会话里它改过哪几个文件”“上一次工具调用为什么会失败”“如果我想从某个中间步骤重新开始应该从哪里切”。4.2 我观察到的核心事件类型读事件定义时我梳理出了几个高频事件类型这里整理成表方便对照事件类型触发时机携带的关键信息会话创建新会话初始化会话 ID、初始配置快照用户消息追加用户发送新消息消息内容、时间戳模型输出增量流式响应逐段返回文本片段、本轮序号模型完成回复一次模型响应结束完整消息、token 用量工具调用开始模型声明调用工具工具名、参数工具输出增量工具执行过程输出流式 stdout/stderr 片段工具调用结束工具执行完成退出码、整理后的输出工具调用错误工具执行异常错误类型、堆栈或描述上下文截断超过上下文窗口被裁剪被移除的消息 ID 列表这套事件类型的划分和我之前见过的一些事件驱动系统相比最大特点是“尽量保留原始事实不在事件里做太强的业务折叠”。比如工具输出增量事件它记录的只是这一小段输出本身而不是“当前累计输出了多少”。累计值完全可以由重放算出不需要事件自己去维护。这种“事件只描述事实、不自带聚合结果”的原则是事件溯源系统不容易跑偏的关键。4.3 投影与回放怎么从事件流还原出一个可用的会话“当前状态不直接存需要时重放”听起来有点吓人——难道每次打开一个历史会话都要把所有历史事件重新跑一遍实际上工程实现不会这么粗暴。opencode 的做法是每个会话在持续运行中维护一份内存里的“投影状态”事件流只是作为持久化备份存在。正常运行时读写都走投影事件流只负责异常恢复和历史查询。只有当会话被中断、需要跨进程恢复时才真正做一次完整的事件重放。重放过程相当于把所有历史事件按顺序重新投影一遍最终恢复出对应的交互会话和执行会话状态。由于事件本身很小主要是文本和元数据几千条事件的重放通常是毫秒级的完全在可接受范围内。这也是为什么 opencode 能比较自信地提供“恢复会话”能力——只要事件流完整状态就能重建。4.4 事件溯源带来的额外红利调试、审计与回放事件溯源看起来只是解决了“状态怎么存”的问题但实际带来的额外红利远超设计本身。首先是调试。工具执行出错时最让人头疼的往往是“当时到底发生了什么”。有了完整事件流可以直接按时间顺序审查每一步哪条消息是用户发的、模型在哪一步决定调用工具、工具接到什么参数、执行到哪一步抛了异常。相当于给整个会话装了一台行车记录仪。其次是审计。在多人协作的项目里让 AI 助手改动代码是有点风险的事。事件流天然提供了“谁在什么时候让 AI 做了什么改动、工具实际执行了什么操作”的完整证据链这对团队评审很有价值。再就是回放调试。我自己就在复现一个问题时用过这个能力某个工具调用的结果在一次特定上下文中表现不对但在普通测试里又是好的。借助事件流把当时的上下文完整重放一遍问题就稳定复现了。没有事件溯源这种“时间旅行”能力基本无从谈起。4.5 边界条件与存储格式的取舍事件溯源也不是没有代价。规模上来之后事件文件会越来越大全量重放的开销也会线性增长。opencode 在这块的处理是引入归档和快照机制会话进行到一定阶段会对累积事件做一个投影快照保存下来后续重放从这个快照开始而不是从零开始。这样既保留了事件的可追溯性又控制了重放成本。存储格式方面我看到的做法是每个会话一个独立的事件文件内部按追加方式顺序写入每条事件自带 ID 和时间戳。这个格式非常朴素甚至没有引入数据库但好处是简单可靠、天然支持增量同步。对一个会话数量级通常在百条以内的工具来说这个选择是务实且合理的。5. 读 opencode 源码的三条主线从入口到事件流最后这部分我分享一下自己实际读源码时的路径建议。opencode 代码量不算小如果没有主线很容易在读了一堆文件之后还是串不起整体。我摸索下来有三条主线比较顺畅分享给有需要的读者。5.1 主线一从 CLI 入口一路追事件流第一条线是从 CLI 入口进去先看一条用户消息从输入到输出的完整链路。这条线能帮你快速理解工程全景和双会话的协作方式。我自己的做法是先找到入口函数确认配置加载和会话初始化的调用点然后断点打在“用户消息追加”这个事件上逐步往后走。走完一遍“用户消息 → 模型响应 → 工具调用 → 工具结果回传”的主循环整个骨架基本上就清楚了。这条线最容易忽略的细节是事件 ID 的生成顺序和消息归属。建议读者在读的时候特别注意每条消息或事件上挂着的会话 ID 是哪个因为这才是区分交互会话和执行会话的关键标识。5.2 主线二从 UI 层反向追渲染依赖第二条线是从界面渲染层反着追。界面上任何一次输出变化背后都对应着某条事件。选一个你经常见到的界面元素比如流式文本输出、工具状态栏反向追它订阅了哪种事件、在哪里做了投影。这条线能帮你真正理解“事件驱动 UI”是怎么落地的也能看出交互会话状态和界面渲染之间的映射关系。我读这条线时最大的收获是发现了渲染层并不直接持有“完整的会话状态”它只需要订阅事件流然后增量地更新可见部分。这让 UI 层非常轻也让双会话并发成为可能——因为界面上根本没有一个需要被锁保护的全局状态。5.3 主线三从测试文件读协议契约第三条线有点取巧是从测试代码反推设计意图。开源项目里的测试往往比实现代码更直白地表达了“这个模块到底该干什么”。我读 opencode 时专门去翻了会话管理和事件存储相关的测试发现测试用例很清晰地覆盖了“会话创建成功后的事件顺序”“工具调用失败时的事件类型”“恢复会话时事件重放的正确性”这些核心场景。从测试读设计的好处是你不用去猜测某个设计是偶然还是刻意——测试会告诉你作者预期什么行为是合法的。个人非常推荐刚接触这个项目的读者先从测试入手读完测试再看实现很多疑惑会自动消解。5.4 后续选题与个人体会这篇是“上篇”我重点拆了工程全景、双会话内核和事件溯源这三块。按照我的阅读计划下篇会重点展开工具调用层的并发控制与权限模型以及模型网关对各家服务商协议差异的适配方式——这两个话题都和“双会话落地时踩到的具体问题”强相关值得单独成篇。最后说一点个人体会。读这个项目之前我以为“双会话”和“事件溯源”是两个独立的设计亮点读完才发现它们在设计上是一套连贯的整体。正因为有了事件溯源双会话才能放心地各自独立、各自推进——所有需要一致性的地方都交给事件流去收敛。如果没有这层基础设施双会话之间要么需要大量同步锁要么会出现各种隐蔽的状态不一致。这种“先设计好事实记录层再放手去并发”的思路是我这次阅读中收获最大的地方。如果你也在做类似的异步协作系统我建议先审视自己的事件记录能力再决定要不要上并行架构。