opencode 是一个让我愿意长期留在终端里的开源 AI 编程助手。这篇（上篇）我会围绕工程全景、双会话内核和事件溯源三条主线，把它的内部骨架讲清楚。你可能用过它，也可能只是听过名字；不管哪种，了解这些底层设计都能帮你更好地理解 Agent 类工具到底是怎么工作的。
终端里的 AI 编程助手已经不是一个新鲜概念了。但你真正把它们当主力工具用过之后，会发现这类工具的天花板不在模型有多聪明，而在工程底盘是否扎实：它能不能长期稳定地维护上下文，能不能在复杂任务里准确地调用工具，能不能在崩溃之后快速恢复现场。opencode 正是把这几件事做得比较到位的一个开源项目。
一句话描述它的定位：一个以终端为交互界面、以 Agent 方式工作的 AI 编程助手。你不需要像传统聊天机器人那样把代码复制粘贴给它，它会自己打开项目里的文件、定位相关的引用、修改代码、运行测试，然后根据结果决定下一步动作。它能做的，本质上是一个"能使用工具的模型在代码仓库里自主推进任务"的过程。
这篇文章是"深入 opencode"的上篇，我会把代码层面最值得先理解的三块讲透：工程全景、双会话内核、事件溯源。适用读者是两类人：一类想搞明白这类 Agent 工具内部是怎么运转的，另一类打算基于 opencode 做二次开发、写插件或者把它集成到自己的工具链里。读完之后你至少能回答一个问题：为什么这个项目敢把"会话"这种看起来很简单的概念做成一套事件驱动的复杂系统。
1. 工程全景：先认清这个项目的骨架
1.1 它是什么，解决了什么问题
聊工程之前，得先对齐一下 opencode 到底解决什么问题。传统的代码问答工具是"你问我答"：你把一段报错贴进去，它给你一段解释，然后你自己动手改。如果想让模型真正替你干活，就必须把它从聊天窗里放出来，给它读文件、写文件、执行命令的能力，并且让它能根据工具的返回结果自主决定下一步。
opencode 就是在这个方向上做得非常完整的一个实现。它底层是一个终端 UI，上面跑的是一套 Agent 执行循环。用户的角色从"每一步都下达指令"变成了"给定一个目标，在旁边看着它推进"。它不再是一个问答工具，更像一个能使用工具、能自我纠错、能把多步任务串起来的执行引擎。
这种定位带来的工程挑战是传统聊天机器人没有的。聊天机器人只需要维护一问一答的短上下文，而 Agent 类工具需要维护一个动态扩张的消息历史，这个历史里不仅有人类对话，还有工具调用、工具结果、系统约束、任务目标。更麻烦的是，这个过程随时可能被打断、被恢复、被并行查看，甚至被远程连接。这些问题都在倒逼架构做出选择，而 opencode 的选择就是下面要讲的这几件事。
1.2 技术栈与顶层模块划分
先说技术栈。opencode 是一个 TypeScript 项目，代码全部由 TypeScript 编写，运行时和构建依赖 Bun。这个选择很务实：TypeScript 让整个项目的类型关系可搜索、可维护，而 Bun 提供的运行时和打包能力让它能把整个 CLI 编译成跨平台二进制，用户不需要预先安装一大堆依赖。界面层用的是 Ink，你可以把它理解成 React 的终端渲染器，用组件状态驱动终端 UI 的变化。这件事对后面讲"双会话"非常关键，因为前端界面本质上就是一个 React 状态树。
从模块划分上看，项目明显分成了几层。最外层是 CLI 入口，负责解析参数、读取配置、启动程序。往里走是核心层，负责模型调用、会话管理、Agent 循环和工具注册。再往上是 TUI 层，负责把核心层的状态渲染成终端界面。底层还有一个存储层，专门负责把会话事件持久化到本地文件。各层之间通过定义良好的接口和事件协议通信，而不是互相直接调用函数。这种分层最大的好处是：TUI 可以换，核心层不用动；存储方式可以换，Agent 逻辑不用动。
强调一下，模块分层不是摆设。我见过不少工具把参数解析、状态管理和 UI 渲染揉在一个文件里，前两百行还能看，后面就彻底没法维护了。opencode 这种分层方式属于"一开始多花一点成本，后面长期受益"的典型。
1.3 从启动到交互：一次完整的运行链路
读这种项目，我建议先别去抠每个函数实现，而是在脑子里把一次完整交互跑通。把链路理清楚，之后看任何代码都能对号入座。
完整流程大致是这样：你在终端输入启动命令，CLI 入口先解析参数和配置，然后加载项目级配置、插件配置；接着启动或连接核心服务；核心服务扫描用户数据目录，找出历史会话列表；TUI 启动后，展示会话列表或者直接进入默认会话。你输入消息并回车，TUI 把消息转成一个新事件追加到当前会话，同时把事件交给 Agent 循环。Agent 循环开始调用模型，模型可能返回文本，也可能返回工具调用请求。如果返回的是工具调用，Agent 会找到对应的工具去执行，把执行结果变成一条事件写进会话，然后再带着新增结果继续调模型。模型最终输出结束语或达到某种终止条件后，Agent 进入空闲状态，前端收到事件后结束"正在思考"的状态。整个过程中，几乎每一步状态变化都会产生事件，既推给前端，也写进本地存储。
这条链路里有两个很容易被忽略的关键点。第一，事件是异步产生和消费的，前端不会阻塞等待 Agent 完成，而是一直在监听事件并重新渲染。第二，会话恢复不是从内存里拿，而是把历史事件流重新加载内存，如果你没看完本文第三部分，后面遇到会话异常就会比较难排查。
2. 双会话内核：UI 会话与 Agent 执行会话如何分工
2.1 为什么需要"双会话"
"双会话"这个词，我第一次看到时也以为是产品层面的两个窗口，实际研究源码后才发现它指的是内核层面的职责分离：界面层维护的会话和执行层维护的会话，是两条独立的状态流，只是恰好共享同一个展示框架。
其中一条是"用户视角的会话"，关心的是消息怎么展示、哪个会话处于选中状态、模型输出到哪了、等待动画要不要继续。另一条是"Agent 视角的会话"，关心的是完整的上下文消息数组、系统提示词、工具调用历史、最大步数限制、上下文窗口大小。两者的数据在内容上高度重合，但生命周期和更新方式完全不同。
举一个最能说明问题的场景：你在界面里按 Ctrl+C 中断模型输出。前端会话立刻停止渲染，当前消息停留在半截状态。但后端的 Agent 循环可能正在等待一个工具结果返回，或者已经准备发起下一次模型调用。此时如果不区分两条会话，简单地把"会话状态清掉"，那么 Agent 那边到底应该取消还是继续就会变成一个两难问题。有了双会话，前端只是取消消费事件，后端则单独处理取消信号，两边各归各的，互不干涉。
2.2 前端会话：只管"人看到的"那部分
前端会话的任务可以概括成一句话：把事件变成能看的东西。它不拼 prompt，不关心模型内部怎么规划工具调用，也不需要知道系统提示词里写了什么。它维护的是渲染友好、交互友好的数据：当前会话列表、当前选中项、消息气泡如何排列、助手消息按什么样式展示、工具调用是否可折叠、等待动画的开关、当前用户正在输入的草稿内容、滚动位置等等。
这些看起来琐碎，但对整体体验影响巨大。比如模型流式输出时，每来一小段增量，前端就要更新一次渲染区域。如果前端直接去拉取 Agent 的完整上下文再重新渲染，终端 UI 很快就会卡顿。而基于事件增量更新，前端每次只需要处理一小块最新数据，渲染压力明显小得多。
前端会话还有一个容易被忽略的职责：本地交互态的维护。用户在输入框里打字，这件事在没有发送之前，不应该流到 Agent 那边。所以前端需要一份独立的输入草稿状态，等到用户确认发送时，才把消息转成事件丢给后面的执行链路。这一小块逻辑如果混在 Agent 会话里，会让"未发送的草稿"和"已发送的消息"搅在一起，后续所有关于历史上下文的计算都会变得很难搞。
2.3 Agent 会话：真正干活的循环
Agent 会话的核心是一个消息循环，我习惯叫它"跑腿循环"。只要 Agent 没有达到终止条件，它就会持续运行：把当前上下文发送给模型，模型返回一段内容；如果内容里包含工具调用，Agent 就去执行对应工具，把工具执行结果塞回上下文；然后带着新增结果继续调用模型。反复这个过程，直到模型给出了最终答案，或者触发了某种终止条件，比如达到最大轮数、用户手动取消、上下文窗口长度超出限制。
这个循环里最关键的设计是：工具执行结果不是简单地拼进字符串，而是作为一种结构化消息，和普通用户消息、助手消息一起构成上下文。模型在下一轮能看到完整的工具名、传入参数、返回值或错误信息。这样模型就能自己判断下一步行动：如果上一个工具返回错误，它可以换个方式再试；如果结果够了，它可以停下来写最终总结。整个过程并不需要人为干预。
另外，Agent 会话还要负责处理"意料之外"。比如某个工具执行超时、某个文件不存在、模型返回了格式错误的工具参数。这些异常在普通程序里会被抛出去，但在 Agent 循环里，它们会变成上下文的一部分，交给模型去解决。这既是能力来源，也是不确定性来源：你永远不知道模型会用哪种方式绕过这个坑，所以调试时一定要保留完整的事件记录。
2.4 双会话如何同步：事件总线与快照
两条独立会话要协调工作，靠的不是直接调用对方的方法，而是事件总线。Agent 会话每前进一小步，就产生一个事件；前端会话订阅这些事件，按需更新自己的状态。事件是两者之间唯一的真实连接。
具体来说，模型开始输出时，Agent 会话发出"助手消息更新"事件，带上内容增量；前端收到后，在当前助手消息的渲染区域追加内容。工具开始执行时，Agent 会话发出"工具开始"事件；前端收到后，把对应的工具条目从"待执行"变为"执行中"。整个过程术语上是订阅/发布，但行为上更像一个现场直播：后端是主播，前端是观众，所有信息都通过事件流传递。
这种设计有一个很大的好处：前端甚至不需要和后端运行在同一个进程里。opencode 支持本地服务模式，你可以理解成核心服务跑在一台机器上，终端界面跑在另一台机器上，二者之间用一套事件协议同步。前端重启、切换设备都不会打断 Agent 的进度，只要事件流没有断，现场就能恢复。
不过事件总线也有它自己的坑。事件丢失、乱序、重复订阅都可能造成前端展示和后端实际状态脱节。这个我在第五部分会专门展开，因为这是实际使用中最容易遇到的一类问题。
3. 事件溯源：把会话变成一条可重放的事件流
3.1 什么是事件溯源，为什么适合这里
事件溯源是一种数据建模思路：不保存"当前状态"作为唯一真相，而是把产生状态变化的每一个事件都存下来，当前状态只是事件流重放的结果。用记账来类比，传统做法是只存账户余额，事件溯源则是存每一笔收支明细。余额算错了，或者想知道三个月前的某笔交易为什么出现，直接翻流水就行。
那为什么 Agent 编程助手特别适合事件溯源？因为 Agent 会话的状态变化极其频繁，而且每一步都可能成为未来调试的依据。模型收到什么上下文、决定调用哪个工具、工具返回了什么结果、结果如何影响下一步，这些信息如果只存最终结论，一旦任务中途出现问题，根本没法复盘。事件溯源天然把"过程"保存了下来，让整个会话变成一个可回放、可审计、可恢复的记录。
当然，事件溯源也有代价。它需要更复杂的存储设计、更严谨的事件版本管理，以及重放机制。如果这些不做扎实，单纯事件多只会让系统更脆弱。opencode 整体给我的感觉是，它的复杂度投入换来了值得的可靠性回报。
3.2 opencode 里的事件流模型
具体到 opencode，一个会话就是一组按时间排序的事件。我梳理出来，核心事件大致分为几类：会话生命周期事件、用户消息事件、助手消息事件、工具调用事件、会话结束事件。每类事件都至少包含会话 ID、事件类型、时间戳和具体载荷。
| 事件类型 | 出现时机 | 主要载荷 |
|---|---|---|
| session.created | 新会话建立 | 会话 ID、工作目录、创建时间 |
| user.message.created | 用户提交消息 | 消息内容、附件引用 |
| assistant.message.started / updated | 模型开始/增量输出 | 内容片段、token 计数 |
| tool.call.started | 工具被触发 | 工具名、参数快照 |
| tool.call.completed | 工具执行结束 | 返回值或错误堆栈 |
| session.idle | Agent 进入空闲 | 结束原因、耗时统计 |
这里有个细节值得注意：模型输出是流式的，所以"助手消息"很可能会被拆成多个事件，而不是一次性写完。这样做的好处是，即使模型生成到一半崩溃了，之前的输出片段已经落盘，重启后至少能恢复大部分内容。代价是事件顺序对最终重建结果影响很大，乱序重放会产生错误上下文。
工具调用事件是另一个重点。模型决定调用工具时会发出工具参数快照，这些参数可能很长，包含文件路径、命令内容。事件存储会完整保留这些信息，方便后续审计。工具执行结束后，返回值和错误都会被记录成另一个事件，作为上下文的一部分回填给模型。
3.3 存储与恢复：从事件流重建会话
物理存储上，事件流通常以 JSONL 形式落盘。JSONL 每行一个 JSON 对象，行和行之间没有嵌套关系，追加写入效率很高，读取时按行反序列化即可。这也方便直接用终端命令查看。底层存储会为每个会话维护独立的事件文件，格式就是 JSONL。
恢复会话时，系统从事件文件第一行开始重放，把所有事件还原进内存，重建出完整的会话上下文。这个过程是确定性的：同一份事件流，无论重放多少遍，得到的状态都应该完全一致，这就是调试时可以依赖的"可复现性"。
会话时间长了以后，事件文件会变得很大，全量重放可能变得有点慢。所以常见的做法是配合快照：每隔一段时间或在某个事件阈值后，把当前会话状态压缩成一个快照文件。恢复时先加载最近快照，再重放快照之后新增的事件。这样既保留了事件溯源的完整历史，又避免了每次启动都从头扫到尾。opencode 在这个方向上的设计也是类似的思路。
3.4 事件溯源带来的实际收益
把会话变成事件流，最直接的好处是审计能力。你可以翻出任意一个历史会话，精确知道它当时调用了哪些工具、工具参数是什么、返回了什么结果。这对于排查"模型为什么改了那个文件"这类问题至关重要。
其次是回放能力。遇到奇葩行为，你不需要让用户复现，只要拿到对应会话的事件文件，重新放一遍，就能看到当时模型和工具之间完整的交互序列。这种"留证据"的能力是普通数据库存最新状态做不到的。
第三是崩溃恢复。Agent 任务经常一跑就是很长时间，断点续传靠的就是事件流。只要服务没有把尾部事件写坏，重启后就可以从磁盘恢复上下文，继续推进任务，不需要用户重讲一遍需求。
最后是可扩展性。插件系统、统计系统、权限系统都可以挂在事件流上。插件想记录"所有工具调用"很简单，订阅对应事件即可，不用去改核心代码。
代价我也要提一下：磁盘占用、写入频率、事件 schema 演进。后面常见问题里我会说怎么处理磁盘膨胀。
4. 深入源码与实操中的关键细节
4.1 阅读源码之前的准备
先准备环境。这个项目基于 Bun，你本地需要装好对应的运行时和包管理器。把代码仓库克隆下来之后，先跑通项目自带的安装命令，然后跑一遍测试套件，确认环境没问题再做后续研究。我个人的习惯是先把单元测试里跟 Agent 循环相关的用例单独跑一遍，这些用例通常覆盖了最核心的交互路径，看它们能让你快速建立"事件从哪来、到哪去"的直觉。
准备一个专门用于测试的干净工作目录，并且把 opencode 的用户数据目录指向一个临时目录。这样你随便造会话、删事件、改配置，都不会影响日常在用的数据。用真实模型调一次简单任务，把日志打开，对比事件文件和终端输出，感受一下从前端到后端的信息流动。
4.2 代码阅读路径推荐
很多朋友一上来就从 UI 组件开始读，结果在渲染逻辑里绕了半天。我建议换一个顺序，按下面这张表来走。
| 阅读对象 | 主要解决什么问题 |
|---|---|
| 类型定义 | 消息、会话、工具、事件的数据结构长什么样 |
| Agent 循环入口 | 一次模型调用到工具执行之间如何编排 |
| 工具注册表 | 内置工具如何被发现、参数如何解析 |
| 事件写入模块 | 事件如何被序列化、如何落盘 |
| TUI 事件订阅 | 前端如何订阅事件并驱动组件更新 |
这个顺序是自底向上的：先知道数据结构长什么样，再知道数据怎么流动，最后看 UI 如何呈现。读类型定义时不要只看字段名，要把字段之间的关系画出来。比如一条助手消息里怎么携带工具调用、工具结果以什么形式回填到上下文、事件载荷如何关联到具体的工具参数快照。这些关系是所有上层逻辑的基础，也是你后面排查任何问题时最先要确认的东西。我大概花了一个多小时只画类型关系图，后面读代码的速度反而快了不少。
4.3 现场观测技巧
看代码永远不如看真实运行。我建议你给 opencode 布置一个会触发多个工具的小任务，比如"找到过滤函数，把它改成分页实现，然后跑测试"。任务执行过程中，打开会话事件文件，实时观察事件顺序。你会发现模型先发出一个工具调用请求，然后出现工具开始事件，之后是工具完成事件，再往后又是助手消息更新事件。观察几个轮回之后，你对 Agent 循环的理解会比读十遍代码都深。
想验证恢复逻辑，可以做一个破坏性实验：把事件文件末尾复制到另一个文件里，手动截掉最后半行 JSON，再启动 opencode 打开该会话，看它是否能跳过损坏行并恢复剩余内容。注意，操作前一定备份，这个实验要在临时数据目录里做，别拿正式会话开玩笑。
想开发插件的人，重点研究事件订阅接口。插件拿到的应该是事件快照或订阅流，而不是核心对象。搞懂"事件从哪里来、插件能订阅什么、不能直接改什么"，你就能写出不依赖内部实现的稳定插件。
5. 常见问题与排查技巧实录
5.1 历史会话打不开或内容空白
这类问题的第一嫌疑就是事件文件损坏。可能的原因是程序异常退出时最后一条事件没写完、磁盘写入中断、或者被其他程序误修改。排查方法很直接：找到对应会话的事件文件，用文本工具打开最后几行，看有没有明显不完整或格式错误的 JSON。如果找到了，把损坏的那一行备份出来，再把它从文件里移除。
操作上有两个铁律：第一，修复前必须备份；第二，必须在 opencode 完全退出之后再做修改。如果修完还打不开，再看是不是事件重放逻辑本身出错，比如某类事件在处理时抛了异常。这种情况需要抓日志定位，单纯修文件解决不了。
5.2 前端显示和 Agent 实际状态脱节
典型场景是模型已经停止输出很久，界面还卡在"正在思考"。按照事件溯源的思路，排查顺序很清晰：先看事件文件里有没有对应的结束事件。如果没有结束事件，说明 Agent 执行链路确实还没走完，可能是模型侧的问题；如果有结束事件但前端没更新，那问题大概率出在事件订阅或事件传输环节。
还有一种情况是事件乱序。在某些远程模式下，事件经过中间传输层，可能出现先收到后面的、再收到前面的。如果前端简单地把最新事件当成唯一真值，就可能显示错乱。这类问题要从事件携带的序列号或时间戳入手检查，而不是盲目重启。
5.3 会话文件占用越来越大
事件溯源的上限是磁盘空间。一个会话跑得越久、工具调用越多，事件文件增长越快。如果你的使用频率高，用户数据目录膨胀几乎是必然的。处理办法不是关闭事件持久化，而是做归档策略。
我的做法是：日常只保留最近一段时间的完整事件流，更老的会话压缩成归档包，放在一个单独的目录里。当你需要看历史会话时，再解压并临时恢复。这样既保留了可审计性，又不让磁盘无限膨胀。别直接删除所有旧会话文件，有些上下文你当时觉得没用，后面可能要花几倍时间重新生成。
5.4 修改配置之后行为没变
配置不生效，先确认加载顺序。有些配置项支持全局配置和项目配置叠加，如果同名配置在更高优先级的位置被设置过，你改的低优先级配置就会被覆盖。从现象上看就是"改了等于没改"。
想进一步确认，可以从事件载荷里找线索。发起一个新会话，让 Agent 做一个简单任务，然后查看新会话的事件文件里配置相关字段的值。如果写进去的还是旧值，说明配置在更早阶段就被覆盖；如果连字段都没有，那可能是配置加载环节本身出了问题。这两种情况排查方向完全不同，别一上来就怀疑 Agent 逻辑。
暂时就想到这么多。最后再分享一个个人习惯：我每次接触一个新的 Agent 类项目，都会第一时间找到它的会话存储格式。这个格式基本能反映一个项目的架构成熟度。你能从事件类型看出它的能力边界，从存储方式看出它的可靠性设计。opencode 这套双会话加事件溯源，整体是让我觉得"这个项目值得继续投入时间"的架构。
我把这套架构从头到尾捋完，最大的感受是：opencode 的"双会话加事件溯源"并不是为了架构而架构，而是 Agent 类工具在真实使用场景里被逼出来的结果。前端要保持响应，后端要持续干活，中间还需要可恢复、可审计，如果不用事件把每一步串起来，最后很容易变成一堆补丁叠补丁的状态管理灾难。尤其是事件溯源那部分，一开始我觉得存 JSONL 很朴素，真到排查问题时才发现，能逐条回放现场信息比什么都管用。上篇先写到这里，下篇我打算接着聊工具调用链的实现细节、系统提示词的组装顺序，以及插件系统怎么把自己挂进事件流。有兴趣的朋友可以先照着我上面给的路径把代码翻一遍，等下一篇出来的时候，你已经有足够上下文跟上节奏了。
