1. 从一次代码重构说起：opencode 到底解决了什么问题
去年年底我接手了一个 TypeScript 单体项目，代码量大概在八万行左右，团队里三个人维护了将近两年。最头疼的不是业务逻辑复杂，而是每次改一个函数，都要靠全局搜索去确认它被哪些地方调用了、有没有副作用、会不会影响某个边缘分支。这种"人肉依赖分析"的效率极低，而且经常漏掉一些动态调用或者间接引用。后来我开始研究 opencode 这个项目，最初只是想看看它的架构设计有没有值得借鉴的地方，结果越看越觉得有意思——它把"代码理解"这件事从传统的静态分析思路，转向了事件溯源和双会话内核的方向，这个思路在工程上非常值得拆解。
opencode 是一个基于 TypeScript 构建的智能体框架，运行在 Bun 运行时之上，采用 Monorepo 组织代码。它的核心目标不是做一个简单的代码补全工具，而是构建一个能够理解工程上下文、追踪操作历史、支持多轮交互的智能编码助手。你可以把它理解成一个"有记忆、有状态、能追溯"的代码协作系统。它适合谁看？如果你正在做 AI 辅助编码工具、智能体框架、或者对事件溯源架构在工程工具中的应用感兴趣，那 opencode 的工程全景和内核设计值得花时间研究。这篇文章是上篇，重点放在工程结构、双会话内核和事件溯源机制上，不涉及具体的模型接入和套餐对比。
我第一次跑 opencode 的时候，最直观的感受是它的启动速度非常快，这跟 Bun 的运行时特性有直接关系。但真正让我决定深入研究的，是它在处理"会话状态"时的设计——它没有用传统的全局状态管理，而是把每一次操作都当作一个事件来记录，然后通过事件回放来重建状态。这个思路在分布式系统里很常见，但用在编码工具里，我确实是第一次见到比较完整的实现。
2. Monorepo 工程全景：包拆分逻辑与依赖流向
2.1 为什么选择 Monorepo 而不是多仓库
opencode 的代码组织方式是一个典型的 Monorepo，根目录下按照功能域拆分了多个 package。我一开始觉得这种拆分有点过度设计，毕竟项目体量看起来没有大到需要这么细的粒度。但仔细看完依赖关系之后，我改变了看法。它的包拆分不是按照"技术分层"来的，而是按照"运行时角色"来的——也就是说，每个包对应的是系统运行时的某一个具体职责，而不是简单的 controller、service、model 这种分层。
这种拆分方式的好处在于，当你需要替换某一个运行时角色的时候，不需要去动其他包的代码。比如它的会话管理、事件存储、工具调用、模型适配这几个核心能力，分别在不同的包里实现，包与包之间通过明确的接口契约通信。我在自己的项目里试过类似的做法，确实能降低模块间的耦合度，但前提是你得把接口设计得足够稳定，否则改一个接口就要动好几个包。
Monorepo 的另一个好处是类型共享。TypeScript 项目里最烦的就是类型定义散落在各处，改一个类型要同步好几个地方。opencode 把核心类型集中在独立的包里，其他包通过 workspace 依赖引用，这样类型变更的影响范围是可控的。不过这里有个坑：如果类型包和实现包之间的版本没有严格对齐，很容易出现"类型对不上但编译能过"的情况。我的经验是，在 Monorepo 里一定要用 workspace 协议来锁定内部依赖版本，不要用语义化版本号去引用内部包。
2.2 核心包的职责边界与依赖流向
我把 opencode 的核心包按照依赖流向整理了一下，大致可以分为三层。最底层是基础能力层，包括类型定义、工具函数、事件存储抽象；中间层是内核层，包括会话管理、事件溯源引擎、工具调度；最上层是应用层，包括 CLI 入口、编辑器集成、模型适配。
这个分层的关键在于：依赖只能从上往下，不能反向。也就是说，内核层不能依赖应用层的任何东西，基础层不能依赖内核层。这个约束看起来简单，但在实际开发中很容易被打破。比如你可能会想在内核层直接调用某个 CLI 的输出格式化函数，这就破坏了分层。opencode 的做法是把这类跨层需求抽象成事件或者回调，通过事件机制来解耦。
我特别留意了它的工具调度模块。这个模块负责把用户的自然语言指令转换成具体的工具调用，比如读文件、写文件、执行命令等。它的设计不是简单的 switch-case，而是用了一个注册表模式——每个工具在初始化时注册自己的描述、参数 schema 和执行函数，调度器根据注册信息来路由。这种设计的好处是新增工具不需要改调度器代码，只需要注册就行。我在自己的项目里也用过类似模式，实测下来扩展性确实好，但要注意注册表的初始化顺序，如果工具有依赖关系，得保证被依赖的先注册。
2.3 Bun 运行时带来的实际收益与限制
opencode 选择 Bun 作为运行时，这个决定在工程上有明显的收益。首先是启动速度，Bun 的冷启动比 Node.js 快不少，这对于一个需要频繁调用的 CLI 工具来说很关键。其次是内置的 TypeScript 支持，不需要额外的编译步骤，直接跑源码就行，开发体验很流畅。还有就是 Bun 的包管理速度，在 Monorepo 里安装依赖的时间能省下不少。
但 Bun 也不是没有限制。我在测试的时候发现，某些 Node.js 原生模块在 Bun 下的兼容性还有问题，特别是涉及到文件系统底层操作和网络协议的部分。opencode 的做法是把这些平台相关的操作抽象成适配层，如果 Bun 不支持就降级到 Node.js 兼容模式。这个适配层的设计思路值得借鉴——不要直接在业务代码里写运行时相关的 API 调用，而是通过一层薄薄的适配层来隔离。
另外，Bun 的调试工具链相比 Node.js 还不够成熟。我在排查一个事件回放的问题时，发现 Bun 的堆栈信息有时候不够完整，最后还是靠加日志才定位到问题。所以如果你打算用 Bun 做生产级工具，建议在关键路径上多埋一些结构化日志，不要完全依赖调试器。
3. 双会话内核：为什么一个会话不够用
3.1 单会话模型的根本缺陷
传统的编码助手通常只有一个会话上下文，用户输入指令，系统执行，返回结果，然后等待下一次输入。这个模型在简单场景下没问题，但一旦涉及到多轮交互和状态累积，就会暴露两个根本缺陷。
第一个缺陷是"状态污染"。当你在一个会话里既做代码分析又做代码修改时，分析阶段产生的中间状态会影响到修改阶段的决策。比如你先让系统分析某个函数的依赖关系，系统在分析过程中加载了一堆文件到上下文里，然后你接着让它修改这个函数，它可能会把分析阶段加载的无关文件也纳入修改范围的判断中。这个问题在实际使用中非常隐蔽，因为表面上看系统"记住了"之前的操作，好像更智能了，但实际上这种记忆是不精确的。
第二个缺陷是"历史不可追溯"。单会话模型通常只保留最近的若干轮对话，更早的操作记录会被截断或者丢弃。当你需要回溯"这个修改是什么时候做的、基于什么上下文做的"时，往往找不到完整的依据。我在实际项目里就遇到过这种情况：一个自动生成的修改引入了 bug，但因为没有完整的操作记录，花了很长时间才定位到是哪一步出的问题。
3.2 双会话的职责划分：交互会话与执行会话
opencode 的双会话内核把会话拆成了两个独立的维度：交互会话和执行会话。交互会话负责管理用户与系统之间的对话流，记录用户的意图、系统的响应、以及对话的上下文。执行会话负责管理具体的操作执行，记录每一步工具调用的输入输出、执行结果、以及状态变更。
这两个会话是独立演进的，但通过事件机制关联。举个例子：用户在交互会话里说"帮我重构这个函数"，交互会话记录这条指令；然后系统在执行会话里发起一系列工具调用——读文件、分析依赖、生成修改、写入文件——每一步都作为执行会话的事件记录下来。交互会话和执行会话之间通过一个关联 ID 来建立映射关系，这样你既能从用户意图的角度看整个对话，也能从操作执行的角度看每一步细节。
这个设计的精妙之处在于，它把"意图"和"执行"解耦了。意图是模糊的、需要解释的，执行是精确的、可验证的。分开管理之后，你可以独立地优化意图理解逻辑和执行调度逻辑，而不会互相干扰。我在自己的项目里尝试过类似的做法，把用户请求解析和实际操作执行分成两个独立的管道，确实能减少很多"意图理解错了导致执行也错了"的连锁问题。
3.3 会话切换时的状态一致性保障
双会话模型带来的新问题是：当交互会话切换上下文时，执行会话的状态怎么保持一致？比如用户在交互会话里从"分析模式"切换到"修改模式"，执行会话需要知道这个切换，并且调整自己的行为。
opencode 的做法是在会话切换时生成一个"状态快照事件"，这个事件包含了切换前的完整状态和切换的原因。执行会话收到这个事件后，不是简单地重置状态，而是根据快照来重建上下文。这个重建过程是幂等的——同样的快照事件回放多次，得到的状态是一样的。这个特性对于调试和恢复非常重要。
我实测下来，这个机制在大多数场景下工作得很好，但有一个边界情况需要注意：如果切换发生在某个工具调用执行到一半的时候，快照可能会捕获到一个"中间状态"。opencode 的处理方式是等当前工具调用完成后再执行切换，而不是立即中断。这个选择是合理的，因为中断工具调用可能会导致文件写入不完整或者命令执行到一半，反而更难恢复。
注意：如果你在自己的项目里实现类似的会话切换机制，一定要定义清楚"切换的原子性边界"。是等当前操作完成，还是允许中断？这个决定会直接影响状态恢复的复杂度。
4. 事件溯源：把每一次操作都变成可回放的历史
4.1 事件溯源的核心思想与适用场景
事件溯源（Event Sourcing）的核心思想是：不存储对象的当前状态，而是存储导致状态变更的所有事件。当前状态通过按顺序回放事件来重建。这个模式在金融交易、审计日志、协作编辑等场景里已经用了很多年，但在编码工具里见到完整实现，opencode 算是比较早的。
为什么编码工具适合事件溯源？因为编码操作天然就是一系列有序的变更。你打开文件、读取内容、修改某一行、保存文件，这每一步都是一个事件。传统的做法是只保留最终的文件内容，中间过程丢弃。但事件溯源把这些中间过程都保留下来，带来的好处是：你可以回放到任意一个历史时间点，看到当时的状态；你可以对比两个时间点的差异，精确知道哪些操作导致了变化；你还可以把事件流导出，用于分析或者重放。
我在实际使用中感受最深的一点是：当自动修改出了问题，我可以直接查看事件流，找到是哪一步操作引入了异常，而不是像以前那样靠猜。这个排查效率的提升是非常明显的。
4.2 事件的数据结构与存储策略
opencode 的事件数据结构设计得比较克制，没有搞得很复杂。一个典型的事件包含这几个字段：事件 ID、事件类型、时间戳、会话 ID、关联 ID、负载数据。事件类型是一个枚举，覆盖了文件操作、命令执行、会话切换、工具调用等主要类别。负载数据是类型化的，不同事件类型有不同的 schema。
存储策略上，opencode 用的是追加写入的方式，事件一旦写入就不修改。这个约束很重要，因为事件溯源的前提就是事件不可变。如果允许修改历史事件，那回放出来的状态就不可信了。存储介质方面，它支持多种后端，包括内存、文件系统、以及可选的数据库。内存存储适合开发和测试，文件系统适合本地使用，数据库适合团队协作场景。
我试过把事件存储切换到文件系统模式，发现它的文件组织方式是按会话 ID 分目录，每个会话一个事件日志文件。这个设计简单直接，但有个问题：如果单个会话的事件量很大，日志文件会变得很大，回放速度会下降。opencode 的缓解方式是定期做快照——把某个时间点的完整状态存下来，回放时从最近的快照开始，而不是从头开始。这个快照机制在事件溯源系统里是标配，但快照的触发策略需要调优。太频繁会浪费存储，太稀疏会拖慢回放。
4.3 事件回放与状态重建的实操细节
事件回放是事件溯源的核心操作。opencode 的回放逻辑是：从事件流的起点（或者最近的快照）开始，按顺序应用每个事件到初始状态上，最终得到目标状态。这个过程听起来简单，但实操中有几个细节需要注意。
第一个细节是事件的顺序保证。在单会话内，事件是按时间戳严格排序的。但在多会话并发的情况下，不同会话的事件可能有交错。opencode 的处理方式是每个会话维护独立的事件流，跨会话的关联通过关联 ID 来建立，而不是依赖全局时间戳排序。这个设计避免了分布式系统里常见的时间戳同步问题。
第二个细节是回放时的副作用处理。有些事件在应用时会产生副作用，比如执行命令、发送网络请求。在回放模式下，这些副作用不应该被真正执行，否则回放就变成了"重放攻击"。opencode 的做法是在事件定义里标记哪些事件是"纯状态变更"，哪些是"有副作用"。回放时只应用纯状态变更事件，有副作用的事件只更新状态标记，不实际执行。
第三个细节是回放的性能。我实测过一个包含几千个事件的会话，完整回放大概需要几百毫秒。这个速度对于交互式使用来说可以接受，但如果事件量再大一个数量级，就需要依赖快照来加速了。我的建议是：如果你的场景里事件量可能很大，一定要在早期就把快照机制设计进去，不要等到性能出问题了再补。
4.4 事件溯源带来的调试与审计能力
事件溯源最大的价值体现在调试和审计上。传统的调试方式是加断点、看变量、单步执行，但这种方式对于"过去发生了什么"的问题是无效的。事件溯源让你可以"时间旅行"——回到任意一个历史时间点，查看当时的状态，然后逐步前进，观察每一步的变化。
我在排查一个自动重构的问题时，就是靠事件回放定位的。系统把一个函数的参数顺序改错了，但表面上看修改逻辑没问题。我通过事件流找到了生成修改的那一步，发现是依赖分析阶段读取了一个过期的缓存文件，导致参数顺序判断错误。如果没有事件流，这个问题可能要花好几倍的时间才能找到。
审计能力方面，事件流天然就是一份完整的操作日志。谁在什么时候做了什么操作、基于什么上下文、产生了什么结果，全部有记录。这对于团队协作场景特别有用——当多个人或者多个智能体同时操作一个代码库时，事件流可以作为冲突检测和合并的依据。
提示：事件溯源虽然强大，但不要滥用。不是所有状态都需要事件溯源。只有那些需要追溯历史、需要审计、需要回放的场景才适合。对于简单的临时状态，用普通的状态管理就够了。
5. 工具调用与事件流的协作机制
5.1 工具注册与调度的实现逻辑
opencode 的工具调用机制是围绕事件流构建的。每个工具在执行前后都会产生事件：执行前产生"工具调用发起"事件，执行后产生"工具调用完成"事件。这两个事件之间通过调用 ID 关联，形成一个完整的事务边界。
工具注册表的设计前面提过，这里补充一个细节：注册信息里除了参数 schema 和执行函数，还有一个"事件类型"字段，用来指定这个工具产生的事件类型。这样调度器在执行工具时，不需要硬编码事件类型，而是从注册信息里读取。这个设计让新增工具变得很简单——实现工具逻辑、注册、指定事件类型，三步搞定。
我注意到它的参数校验是在调度器层做的，而不是在工具内部。调度器根据注册的 schema 校验参数，校验不通过就直接返回错误事件，不会调用工具函数。这个设计的好处是校验逻辑统一，不会出现某个工具忘了校验的情况。但缺点是灵活性稍差，如果某个工具需要特殊的校验逻辑，就得在 schema 里想办法表达，或者绕过调度器直接调用。
5.2 工具执行结果如何写入事件流
工具执行完成后，结果会被包装成一个事件写入事件流。这个事件包含：调用 ID、执行状态（成功/失败）、返回值、执行耗时、以及可能的错误信息。写入事件流之后，会话状态会根据这个事件更新。
这里有个设计选择值得讨论：工具执行结果是同步写入事件流还是异步写入？opencode 用的是同步写入，也就是说工具执行完成后，必须等事件写入成功，才会返回给调用方。这个选择保证了事件流的完整性——不会出现工具执行了但事件没记录的情况。但代价是写入延迟会加到工具调用的总耗时里。对于本地文件系统存储，这个延迟很小，可以忽略。但如果存储后端是远程数据库，延迟就可能变得明显。
我的建议是：如果你的场景对延迟敏感，可以考虑异步写入加确认机制——工具执行完成后立即返回，事件写入在后台进行，但提供一个确认接口让调用方可以查询写入状态。不过这样会增加复杂度，需要权衡。
5.3 工具链式调用时的事件关联
opencode 支持工具链式调用——一个工具的输出可以作为另一个工具的输入。这种情况下，事件流里会出现一串关联的事件。关联的方式是通过"父调用 ID"字段：后续工具的调用事件里记录父调用 ID，这样就能把整条调用链串起来。
这个机制在调试时特别有用。当一条工具链执行失败时，你可以沿着调用链回溯，找到是哪一步出了问题。我在测试一个"读取文件-分析依赖-生成修改-写入文件"的链式调用时，就是通过调用链发现中间的分析步骤用了一个错误的配置参数，导致后续修改全部偏离。
链式调用的事件关联还有一个好处是支持并行分支。如果一条链在某个节点分叉成多个并行调用，事件流里会记录多个子调用，每个子调用有自己的调用 ID 和父调用 ID。回放时可以根据这些关联关系重建整个调用树。这个能力对于复杂的自动化流程非常重要。
6. 实际使用中踩过的坑与应对经验
6.1 事件流膨胀导致回放变慢的处理
我在一个长期运行的会话里遇到了事件流膨胀的问题。那个会话持续了大概三个小时，产生了上万条事件，回放时间从最初的几十毫秒涨到了好几秒。这个问题在开发阶段不容易发现，因为测试会话通常很短。但实际使用中，一个复杂的重构任务可能持续很长时间，事件量会快速增长。
我的应对方式是手动触发快照。opencode 提供了快照接口，可以在关键节点主动创建快照。我在每次大的操作阶段完成后（比如分析阶段结束、修改阶段开始前）触发一次快照，这样回放时只需要从最近的快照开始，而不是从头开始。实测下来，回放时间从几秒降到了几百毫秒。
另一个经验是定期归档旧事件。对于已经完成且不再需要回放的会话，可以把事件流导出到冷存储，然后从活跃存储里删除。这样既保留了审计能力，又不会拖慢活跃会话的性能。opencode 目前没有内置归档功能，需要自己实现，但事件流的追加写入特性让归档变得很简单——直接截断旧文件就行。
6.2 双会话状态不一致的排查思路
双会话模型虽然解耦了意图和执行，但也引入了状态不一致的风险。我遇到过一次：交互会话显示"修改已完成"，但执行会话里对应的工具调用事件还是"进行中"状态。这个不一致导致后续操作基于了错误的状态判断。
排查这个问题的思路是：先确认两个会话的事件流时间线，找到分叉点。具体做法是导出两个会话的事件流，按时间戳对齐，看哪个时间点之后出现了状态差异。我最后定位到的问题是：交互会话在收到工具调用的"完成"事件之前，就先更新了自己的状态，而执行会话的"完成"事件因为写入延迟晚了几毫秒。这个竞态条件在大多数时候不会出问题，但在高负载下就会暴露。
修复方式是在交互会话里增加一个"等待执行会话确认"的步骤，确保执行会话的状态已经更新后再更新交互会话的状态。这个改动增加了少量延迟，但换来了状态一致性。我的体会是：双会话模型里，任何跨会话的状态更新都要考虑时序问题，不能假设两个会话的事件是同时到达的。
6.3 Bun 环境下文件监听事件的兼容性问题
opencode 需要监听文件变化来感知外部修改，这个功能在 Bun 环境下遇到了一些兼容性问题。具体表现是：在某些操作系统上，文件监听事件会丢失或者延迟触发。我测试的时候，手动修改一个被监听的文件，有时候要等好几秒才收到事件，有时候干脆收不到。
这个问题的根源是 Bun 的文件监听实现还在完善中，不同平台的底层 API 行为不一致。opencode 的应对方式是加了一个轮询兜底——除了监听事件，还定期扫描文件状态，如果发现监听事件没触发但文件确实变了，就手动补发一个事件。这个兜底机制增加了少量开销，但保证了可靠性。
我的建议是：如果你在 Bun 环境下做文件监听相关的功能，不要完全依赖监听事件，一定要有轮询兜底。轮询间隔可以根据场景调整，对于代码编辑场景，一两秒的间隔通常够用，再短就浪费资源了。
6.4 事件负载序列化的类型丢失问题
事件需要序列化后存储，反序列化后回放。这个过程中最容易出问题的是类型丢失。TypeScript 的类型信息在运行时是不存在的，序列化成 JSON 之后，原本的 Date 对象变成了字符串，Map 变成了普通对象，自定义类变成了 plain object。反序列化时如果不做类型恢复，回放出来的状态就跟原始状态不一致。
opencode 的做法是在事件定义里声明每个字段的类型，序列化和反序列化时根据声明做转换。这个方案需要维护一份类型映射表，新增字段时要同步更新。我踩过的坑是：有一次新增了一个字段但忘了更新类型映射，结果回放时这个字段一直是 undefined，导致依赖它的逻辑全部失效。排查了很久才发现是序列化的问题。
我的经验是：事件负载的类型定义一定要和序列化逻辑放在一起，改一个就改另一个，不要分开维护。另外，建议在开发阶段加一个校验步骤——序列化后再反序列化，对比结果是否一致。这个校验能提前发现大部分类型丢失问题。
7. 从 opencode 的设计里能带走什么
研究 opencode 的工程全景和内核设计，对我来说最大的收获不是某个具体的技术点，而是一种架构思路：把"状态"和"变更"分开管理，用事件流来记录变更，用回放来重建状态。这个思路在编码工具里适用，在其他需要追溯历史的系统里同样适用。
双会话的设计也给了我很多启发。以前我做类似工具的时候，总是把所有状态塞在一个上下文里，结果就是越做越乱。拆成交互会话和执行会话之后，每个会话的职责清晰了，调试也容易了。当然，拆分的代价是要处理跨会话的一致性，这个成本不能忽略。
事件溯源的部分，我的建议是不要一上来就全盘照搬。可以先从关键操作开始，只对需要追溯的部分做事件记录，其他部分还是用普通状态管理。等验证了效果之后，再逐步扩大范围。全量事件溯源虽然理论上很美，但工程复杂度和性能开销都是实实在在的。
最后说一个实操细节：opencode 的事件流格式是纯文本的，可以直接用文本工具查看和编辑。这个设计看起来不起眼，但在调试的时候非常方便。你可以直接用 grep 搜索事件流，找到特定类型的事件，或者用 diff 对比两个时间点的事件差异。我在排查问题的时候，经常就是靠 grep 事件流快速定位的。如果你的系统也做事件记录，建议用人类可读的格式，不要一上来就上二进制或者压缩格式，可读性在调试阶段的价值远大于存储节省。
