深入解析 opencode：双会话与事件溯源架构

如果你跟我一样，平时写代码不习惯开一整套图形化编辑器，而是更愿意窝在终端里解决问题，那你多半已经接触过 opencode 这类 AI 编程代理。说白了，opencode 就是一个跑在终端里的智能编程助手，它把自然语言对话、代码修改、命令执行这些能力全部收拢进一个统一框架，让你能像给同事派活一样，用大白话驱动整个开发流程。但很多人对它的理解停在“能聊天、能补代码”这个层面，真到自己想改造、想定制、想排查深层 bug 的时候，就完全摸不清门道了。

这篇文章想做的事很简单：把 opencode 的工程骨架拆开，挑最核心的三个部分讲透——工程全景、双会话内核、事件溯源。这三个概念看起来各管一摊，实际上是一条完整链路：会话负责“状态从哪里来、到哪里去”，事件溯源负责“状态为什么是这样、能不能重来”。搞懂这条链，你再看这个项目的源码，或者想给它写插件、接私有模型、加自定义工具，都会顺手非常多。

1. 工程全景：先把 opencode 的骨架摸清楚

1.1 opencode 到底在解决什么问题

先说立场。AI 编程助手大致分三条路线：一条是做成 IDE 插件，深度绑定编辑器的 UI 和操作习惯；一条是做成网页聊天，你复制代码进去，再把结果粘回来；还有一条就是 opencode 这种，直接扎根终端，用 TUI（Text User Interface）的方式和用户交互。

选择终端这个形态，是因为它天然贴合命令行工作流。你不需要在编辑器里找到某个入口，不需要把代码片段来回搬运，opencode 直接运行在你原本就在用的 shell 里。它能读取你当前目录的文件结构、git 状态、运行日志，然后把 AI 模型生成的结果转成实际的文件修改和命令执行。换句话说，它不是一个“帮你写字的输入法”，而是一个“能自己动手干活的代理”。

这个定位直接决定了它的架构走向。工具要想真正干活，就不能只维护一个对话框，它必须长期跟踪“当前工作区发生了什么”“用户刚才提了什么需求”“上一步操作的结果是什么”。这些状态如果散落在各个模块里，很快就会变成一锅乱粥。于是“会话”和“事件”这两个概念，就成了整个项目的基石。

1.2 宏观架构：三层模型，各管一摊

从我读源码和做二次开发的实际体感来看，opencode 的整体架构可以简化为三层：

• 展示与交互层：负责渲染 TUI 界面，接收用户的键盘输入，显示模型输出和工具执行结果。这一层关心的是“看起来怎么样”，不关心内部状态怎么流转。
• 编排内核层：负责理解用户意图、维护会话上下文、调度模型调用、决定下一步执行什么工具。这是整个系统的大脑，也是双会话内核所在的位置。
• 工具执行层：负责真正干活，比如写文件、修改代码、执行命令、读取日志、发网络请求。工具不直接修改会话状态，而是返回结果，由内核层决定如何处置这些结果。

很多开源项目的问题在于层与层之间边界模糊，工具执行到一半直接改界面，界面渲染时偷偷调模型，最后代码耦合成一团。opencode 之所以值得深入，是因为它强制约束了数据流向：用户输入进交互层，变成事件进内核，内核调度工具执行，执行结果再变成事件回到内核，最终通过投影渲染到界面。这个“单向数据流”非常重要，它是后面所有机制能够成立的前提。

1.3 核心模块与一条完整的数据流

在这个三层模型里，有几个模块是你阅读源码时一定会遇到的：

• 会话管理器：负责创建、切换、销毁会话，维护每个会话的上下文状态。
• 事件总线：所有模块之间不直接调用，而是通过发布和订阅事件来通信。
• 事件存储：把不可变的事件记录追加写入本地存储，保证状态可以追溯和重放。
• 模型适配器：把不同模型厂商的 API 统一成一套接口，正常情况下你不会关心底层调的是哪个模型。
• 工具注册表：维护可用的工具列表，名称、参数、权限、执行逻辑都在这一层注册。

以一次最简单的对话为例，完整流程是这样的：

1. 你在输入框敲下“帮我给项目加一个 .gitignore”，这是“意图事件”。
2. 内核层把这条消息和历史内容一起打包，发送给模型服务商。
3. 模型返回结果，可能是一段解释，也可能包含工具调用请求。
4. 内核层把工具请求发给执行层，执行层在工作区中创建文件。
5. 执行结果以“工具完成事件”的形式回到内核层。
6. 内核层把结果再次交给模型，模型确认收尾。
7. 整个过程中的每一步都作为事件追加写入存储。

看到没有，这里没有任何一步是直接修改某个“全局变量”的。所有状态变化都靠事件传递。这就是事件溯源和会话机制能够共存的原因：会话给你一个“当前视角”，事件给你一条“完整历史”。

提示：阅读 opencode 源码时，不要先看 UI 渲染代码，那是最不核心的部分。先把“事件发布”和“事件订阅”两个入口找到，整个系统的调用链就清晰了。

2. 双会话内核：两个会话，各司其职

2.1 为什么需要一个会话还要拆成两个

很多人第一次看到“双会话”这个概念时会很困惑：直接维护一个会话，里面既存对话历史，又存执行状态，不行吗？

技术上完全可以，但工程上会很难受。因为你把“聊天的记录”和“执行的记录”混在一起，会面临三个棘手问题：

• 上下文窗口是有限的。模型能接收的历史消息就那么多，你不能把每一次命令执行的完整输出都塞进去。
• 对话是你主动发起的，执行是模型主动发起的。两者的生命周期不同，聊天可以随时结束，但一个耗时的构建任务不应该因为对话切走就被干掉。
• 界面展示需求不同。对话框里你需要的是“人话”，任务区里你需要的是“原始日志”。混在一起会让双方都变得不可读。

opencode 的解法是拆分：交互会话和任务会话。一个面向人和模型的对话，一个面向工具和状态的执行。两者共享工作区的核心事实，但在各自独立的生命周期中运行。

2.2 交互会话：轻量、临时、以对话为中心

交互会话是你看得到的那一层。每次你打开 opencode 输入消息，它都在交互会话里工作。它的核心特征有三个：

一是上下文敏感。它会管理最近 N 轮对话内容，并负责在超出模型上下文窗口时做压缩或裁剪。你不需要手动清理历史，它会根据 token 预算自动决策。

二是意图导向。这里保存的不是原始操作细节，而是“用户想要什么”。比如你告诉它“帮我排查构建失败的原因”，这条意图是留在交互会话里的，而具体执行了哪些命令、结果是什么，则沉淀到任务会话里。

三是轻量易失。交互会话可以随时从头开始，新开一个对话，旧内容可以被归档。它不追求持久化所有细节，只保证当前交互的流畅性。

2.3 任务会话：重量、持久、以工作区变更为中心

任务会话则是你看不到但一直干活的那一层。它关注的是“状态到底发生了什么变化”。我倾向于把它理解成一个“长生命周期的工作台账”。

只要 opencode 进程在跑，任务会话就会持续记录工具的执行状态。有一次我连续跑了五个小时，期间切换了七八次对话主题，旧对话都归档了，中间执行过的代码修改、命令输出、文件读写记录却全部还在。这带来的实际好处是：你可以随时问它“你之前到底改了哪些文件”，它能从任务会话中还原出一条完整的工作记录，而不是只记得你上一句话。

任务会话的实现有几个关键设计：

• 它不假设自己属于某个具体的聊天话题。它属于当前工作区。
• 它记录的是“事实”，而不是“摘要”。命令是否成功执行、哪个文件被改动、改动时间点是什么，都以结构化方式保存。
• 它可以被查询和过滤。你可以只看“文件变更”“命令输出”或“错误信息”，不必把所有内容揉在一起。

2.4 双会话如何协同：共享事实，隔离噪声

两个会话不是各干各的，它们通过一个“状态桥”协同：

交互会话提出了一个意图，内核层判断这个意图需要落地执行时，就把具体操作派发到任务会话；任务会话执行完毕后，把结果摘要返回交互会话。这样一来，交互会话不用背负一大堆系统输出，任务会话也不用被“人话”干扰。

用一个例子来说明：如果你说“看看测试为什么挂了”，交互会话里只保存了这句话；任务会话里则会记录“运行了 pytest 的某条用例”、“失败输出片段”、“退出码 13”这些事实。当模型需要判断下一步时，它读取的是任务会话提供的结构化结果，而不是一个塞满了乱七八糟日志的聊天记录。

这种设计的妙处在于，“记忆”和“推理”分开管理。推理需要短时记忆，所以放在交互会话中，保持快速、可裁剪；行动需要长时记录，所以放在任务会话中，保持完整、可追溯。两者借助内核的调度逻辑形成配合，既避免了上下文爆炸，又保留了可审计的执行证据。

注意：如果你想给 opencode 扩展一个自定义工具，尽量在工具执行结果里提供结构化输出（比如 JSON），而不是一坨字符串日志。因为只有结构化输出，任务会话才有办法做后续的筛选、摘要和事件入库。

3. 事件溯源：让状态变化具备完整时间线

3.1 事件溯源到底是个什么思路

事件溯源（Event Sourcing）听起来很学术，但我可以用一个特别日常的例子解释：假设你记流水账，每一笔收入和支出都按时间顺序写在账本上，而不是只记一个最终余额。到了月底，你把账本从头翻一遍，就能算出当前余额是多少。如果哪笔账记错了，你只改那一笔，然后重放一遍账本，新的余额就出来了。

opencode 对内部状态的管理就是这么干的。它不会把会话的当前状态直接覆盖式存储，而是把所有状态变化都作为一条条不可变的事件追加到存储中。系统当前是什么状态，不靠某一个“最新值”来定义，而靠“从初始状态开始，重放所有事件”来推算。

这个选择的盈利点在于：你永远能从事件流中恢复出任意时刻的历史状态。调试时想搞清楚“这个文件是什么时候被改的、是谁让它改的、上一个版本是什么”，直接查事件记录就行，而不是去翻各种日志文件。

3.2 事件模型：一切状态变化的原子单位

在 opencode 里，一个事件通常包含几类基本字段：

• 事件类型：比如“消息已创建”“工具已调用”“工具已完成”“命令已输出”“文件已写入”。
• 目标范围：事件属于哪个会话、哪个消息、哪个工具调用。
• 时间戳：事件发生的时间。
• 载荷数据：具体的结构化信息，比如消息内容、工具参数、输出摘要、文件路径。

我随手举个例子。某一次用户让模型优化一个函数，这个过程中的核心事件大致长这样（这是逻辑结构，实际格式可能随版本变化）：

{ "event_type": "message.created", "session_id": "interactive-session-a1b2c3", "timestamp": "2025-06-12T14:23:10.812Z", "payload": { "role": "user", "content": "优化一下 orderService 里的查询逻辑" } }

接着是工具执行事件：

{ "event_type": "tool.invoked", "session_id": "task-session-9f8e7d", "timestamp": "2025-06-12T14:23:11.420Z", "payload": { "tool": "edit_file", "params": { "path": "src/orderService.ts", "range": [42, 67] } } }

再接着是执行完成事件：

{ "event_type": "tool.completed", "session_id": "task-session-9f8e7d", "timestamp": "2025-06-12T14:23:12.055Z", "payload": { "tool": "edit_file", "success": true, "summary": "已将查询逻辑改写为索引优先访问" } }

这三条事件合在一起，就构成了一段完整可回放的操作历史。

3.3 存储策略：追加写入，永不覆盖

事件溯源的存储策略和传统数据库完全不同。传统数据库是“最新值覆盖旧值”，事件存储是“只追加，绝不修改历史”。这个策略带来两个直接结果：

第一，写路径特别简单。因为不需要更新已有记录，不需要做行级锁，只需要一个追加写入的通道。opencode 的事件存储后端可以看作一个本地追加日志，顺序写，性能非常稳。

第二，历史永远完整。每次操作都会留下审计痕迹，出了问题上查一下事件流，基本能还原出完整的操作路径，这对调试模型工具调用逻辑有巨大帮助。

但追加写入也会带来一个现实问题：文件会越来越大。这也是为什么需要下一节说的快照机制。

3.4 快照与重放恢复：在完整性与效率之间找平衡

如果事件流无限制增长，每次重建状态都要重放十万条事件，那系统会慢到没法用。会有两个直接后果：启动慢，内存消耗高。所以 opencode 需要在“事件完整性”和“启动效率”之间找一个平衡点，做法就是快照。

快照的本质是“当前状态的一个压缩存档”。系统会定期或在达到某个事件数量阈值时，把当前所有事件重放一遍，然后把最终状态生成一份快照。以后要恢复状态，只需要加载最近一份快照，再重放快照之后的新事件，不用从零开始扫全量历史。

用公式理解就是：

当前状态 = 最近快照 + 快照之后的事件流

这个设计对用户没什么感知，但如果你做二次开发，理解快照触发时机很重要。合理配置快照策略，可以让“恢复会话”从秒级变成毫秒级。

3.5 事件溯源如何把双会话串联起来

前面说过，交互会话和任务会话是两套独立逻辑。但如果没有一个统一机制把它们黏合在一起，系统很快就会失去整体一致性。事件溯源在这里扮演的就是“黏合剂”角色。

每一次意图确认、每一次模型响应、每一次工具调用和结果返回，全部以事件形式写入存储。交互会话读取事件流，只投影出“对话消息”；任务会话读取事件流，只投影出“工具执行记录”。两个会话没有直接共享可变状态，它们各自从同一份事件流中建立自己的视角。

这个设计妙在哪里？妙在它天然支持回溯。比如一个任务会话因为 bug 挂掉了，系统可以先加载快照，再重放一段时间内的事件，把任务状态恢复出来。在这个过程中，用户不需要重新描述需求，因为历史事件里已经保存了完整上下文。

提示：很多人在二次开发 opencode 时，遇到“状态变了但界面没变”这种问题，十有八九不是渲染逻辑写错了，而是某个事件没有正确发布。先查事件流，再查订阅逻辑，这个顺序千万别倒过来。

4. 本地实操：从跑起来到看清事件流

4.1 初始化：用最少配置先跑通流程

安装方面建议直接走官方脚本或者包管理器，这里不展开了。配置层面，第一次跑 opencode 只需要准备两样东西：一个可访问的模型服务商 API key，以及一个你想让它工作的项目目录。

官方初始化命令大概是这样（具体命令以你安装的版本为准）：

opencode init opencode auth login opencode

启动后你会看到 TUI 界面，先别急着干活，我建议第一件事是把事件日志配置打开。对于本地开发场景，让事件信息落到一个独立的 JSONL 文件里会非常有帮助，这样你能实时观察系统内部发生了什么。

export OPENCODE_EVENT_LOG=~/.opencode/logs/events.jsonl opencode

执行之后，随便发起一条消息，比如“帮我看一下当前目录的代码结构”。然后另开一个终端，用 tail 跟踪日志文件：

tail -f ~/.opencode/logs/events.jsonl

你会看到几乎每一秒都有一条事件写入。一开始你可能觉得这些记录没啥用，但当你开始排查“模型为什么没调用工具”“工具结果为什么没回传”的时候，这个日志就是你的命根子。

4.2 用一条命令吃透事件流

事件日志刚开始可能很乱，因为里面混杂了各种类型。我建议你直接用 jq 做过滤，只关心你关心的部分。

比如只看当前会话里有哪些消息：

jq 'select(.event_type == "message.created") | {role: .payload.role, content: .payload.content}' events.jsonl

只看工具执行链路：

jq 'select(.event_type | startswith("tool.")) | {event_type, tool: .payload.tool, success: .payload.success}' events.jsonl

按会话分组统计事件数量：

jq -r '[.session_id, .event_type] | @tsv' events.jsonl | sort | uniq -c | sort -rn

这套做法能让你快速判断一个会话里到底发生了什么。我实际遇到过一个案例：某个自定义工具执行成功了，但界面始终没有显示结果。当时我第一时间查事件流，发现工具完成事件确实写入了，但是对应的消息事件没有生成，问题一下就定位到内核层的“结果转消息”环节。

4.3 写一个极简事件监听器

如果你对 opencode 的插件机制有了解，写一个监听事件的自定义模块会非常直观。下面是一段极简示例，作用是监听所有工具完成事件，并把成功的工具调用整理成一份摘要：

export const summaryPlugin = { name: "event-summary-plugin", setup(engine) { engine.on("tool.completed", (event) => { if (event.payload.success) { engine.logger.info( `[工具完成] ${event.payload.tool} -> ${event.payload.summary || "无摘要"}` ); } }); }, };

这里的关键不是代码量，而是你要理解它的执行时机——引擎收到工具完成事件时，会同步调用已注册的回调，并把事件载荷传进去。你不需要关心工具本身怎么执行，只需要面向事件编程。

4.4 事件流实时观测的独门技巧

实时观测时，可以给日志加上颜色区分不同类型的事件，比如命令输出用绿色、错误事件用红色、工具调用用蓝色。这个技巧在处理复杂任务时特别有用，一眼就能扫出链路中断的位置。

另外一个常用的技巧是“事件回放”。如果你改了插件代码，想测试它在某次历史会话里的表现，可以重放相应的事件流，而不需要把模型重新调用一遍。这个动作在内部实现上其实就是先加载快照，再按顺序丢事件。理解了这个原理，你就能用自己的方式做回归验证。

5. 常见问题与排查思路实录

5.1 会话状态与事件流不一致

这类问题表现是：界面显示的状态和实际事件记录对不上，比如文件已经改了，但会话消息里还显示“计划中”。

排查思路很简单，先确认是“没发布事件”还是“订阅方没收到”，还是“状态投影错了”。在实际排查时，优先查事件文件，看“工具已完成”事件是否真实存在。如果事件存在但界面没更新，问题在投影层；如果事件不存在，问题在更早的执行层。

这类问题最常见的原因是插件或者自定义工具直接修改了内部状态对象，绕过了事件发布。只要跨过了事件总线，状态一致性就很难保证。

5.2 事件风暴与性能劣化

当你并行执行大量工具调用时，事件会像连珠炮一样涌入存储和总线，可能造成界面卡顿、日志文件快速膨胀。这种场景我见过不少，特别是在让模型做“批量处理多个文件”任务时。

应对方式有三种：

• 批量事件合并：把同一批次的工具执行结果合并成一条汇总事件，而不是逐条写入。
• 降低快照间隔：事件多的时候，更频繁地生成快照，避免重放路径过长。
• 异步写入：事件写入不需要阻塞主流程，可以先进队列，再异步落盘。

5.3 长会话的上下文膨胀

双会话机制虽然缓解了上下文压力，但也不是万能的。长时间使用后，交互会话的历史消息仍然会增长。这时需要依赖上下文压缩策略，把早期消息摘要化，而不是继续原样保留。如果自己实现模型适配器，需要特别留意 token 预算，不要等到模型报错再处理。

这里有个比较实用的心得：不要只压缩“消息文本”，还要压缩“工具结果”。工具结果往往比正常对话内容更占 token，把结果压缩成一句摘要，能省出大量空间。

5.4 工具执行结果没有回写事件流

有些第三方工具或者自定义脚本执行完成后，只在终端里打印了结果，没有以事件形式回传。这会导致模型不知道工具“已经完成了”，从而重复调用或者错误等待。

解决这类问题的思路是搞清楚工具结果回传的标准路径。你不需要自己手动构建一个完整事件，只需要调用引擎提供的完成回调，把结构化结果丢进去就行。如果你发现有些内置工具也有这个问题，先检查版本更新说明，很大概率是已经被修复的旧版缺陷。

这里也顺带分享一个我自己的排查经验：当某个工具“看起来执行了但模型就是不理它”，先去事件日志里搜这个工具的名字。如果事件日志里连调用的记录都没有，那问题出在“模型根本没决定调用它”；如果调用记录有、执行完成记录没有，那就是工具回传链路的问题；两种问题修法完全不同。

5.5 几个值得注意的工程细节

实操中还有几个小细节，听起来不起眼，但很影响体验。

第一，事件载荷尽量小。大字段（比如完整的文件内容）不应该直接塞进事件里，事件里应该只放路径、范围、摘要，必要内容用文件系统去读取。

第二，尽量保证事件顺序。在单进程里这个还好控制，但一旦有异步工具并发执行，事件到达顺序可能和发起顺序不一致。处理这类问题时，要么给事件加序列号，要么在投影层做排序缓冲。

第三，别忘了清理历史快照。快照虽然可以恢复，但也不能无限积累。定期清理旧快照、只保留最近几个版本，能避免磁盘空间被大量中间态占满。

6. 在实操中沉淀下来的一些体会

这几轮折腾下来，我最大的感触是：opencode 的架构设计不是炫技，每一步都有明确的工程目的。双会话把“交互的轻”和“执行的稳”分开，事件溯源让所有状态变化都能回到起因。理解这两条主线之后，阅读其他模块的效率会高很多。

如果你正准备二次开发，我的建议是按这个顺序来：先花半小时跑通事件日志，确认自己能看到完整事件流；然后找一个最简单的内置工具，从事件发起一路追到执行完成；最后再开始写自己的第一个插件，不要一上来就碰复杂的 UI 或 Provider 层。事件流跑熟了之后，大部分问题都难不倒你。