我最近一直在折腾终端里的 AI 编程助手，前后试过好几个，最后还是把主要精力放在了一个叫 opencode 的开源项目上。先说结论：它不是又一个套壳 CLI，而是一个把“会话”和“事件”这两个概念做到极致的 Agent 引擎。这篇上篇，我不打算贴一堆源码逐行讲，而是从工程视角把 opencode 的骨架拆开看：它怎么组织代码、为什么引入双会话内核、事件溯源在里头到底解决了什么问题。全文偏架构和原理，下篇再聊模型接入与工具系统。
如果你正准备写自己的 AI Agent，或者想深入理解 Claude Code 这类工具的内部设计，这篇应该能给你一张比较清晰的地图。
1. opencode 工程全景：它到底是一个什么样的项目
先给没接触过的朋友打个底。opencode 是一个跑在终端里的 AI 编程代理，你把自然语言指令丢给它，它能自己读代码、改文件、执行命令、跑测试，遇到卡住还会跟你确认下一步。这类工具现在不少，但 opencode 比较特别的地方在于：它从一开始就被设计成一个事件驱动的可编程平台，而不是一条 prompt 打天下的脚本。
1.1 定位：从“执行指令的工具”到“可编程的 Agent 平台”
很多人第一次用它，会觉得“这不就是终端版聊天机器人吗”。实际上它的定位更接近一个平台：会话是核心抽象，事件是流转语言，工具和模型都可以替换。这意味着你可以改它的行为逻辑、接入自己的模型、挂自定义工具，甚至把它嵌入别的系统。
这个定位决定了工程实现的基因。你去看它的代码分层，能明显感觉到设计者没有把“和模型聊天”当成主逻辑，而是把“管理一段持续发生的事件流”当成主逻辑。每一次消息、每一次工具调用、每一次用户中断，都是一条事件，被记录、被派发、被消费。UI 只是事件流的投影，模型只是事件流的消费者之一。
我自己的体会是，这种“事件优先、渲染靠后”的思路，解决了一个很实际的痛点：终端 Agent 往往要长时间运行，过程中用户会插话、工具会失败、模型会被中断，各种状态交错，如果代码里全是回调地狱，早就崩了。事件模型让这些复杂交互变成了有序的流水账。
1.2 技术栈与目录形态：一张架构地图
先看看 opencode 选型：
- 语言与运行时：TypeScript + Bun。TypeScript 保证类型安全，Bun 提供了快的启动速度和内置的测试、打包能力。
- 终端 UI：基于 Ink。Ink 是 React 在终端里的渲染层，你可以用组件思维写 CLI 界面，这让 TUI 那层代码非常好维护。
- 状态管理：XState 状态机。会话的状态流转不是散落的 if/else，而是集中定义的状态机，事件驱动迁移。
- 存储：事件日志文件。整个会话过程被持久化成 append-only 的事件记录，这是事件溯源的地基。
项目内部大体可以分成这么几块：
| 模块 | 职责 | 对应概念 |
|---|---|---|
| core | 事件定义、状态机、会话存储 | 事件溯源核心 |
| session | 用户会话与 Agent 会话的管理 | 双会话内核 |
| provider | 各类模型服务接入，统一请求格式 | 模型抽象层 |
| tool | 内置工具与自定义工具注册 | 工具系统 |
| tui | 终端交互界面、渲染、输入 | 视图层 |
| server | 提供给外部调用的服务端能力 | API 层 |
这个分层最聪明的一点，是把“会话语义”和“具体模型”“具体界面”彻底隔开了。core 层根本不管你是 GPT 还是 Claude，也不管你是终端还是 Web，它只负责维护“事件流 + 状态机”。模型坏了换一个，UI 换了重写，核心不用动。
1.3 为什么这样分层：解耦带来的实在好处
我最早写 Agent 是“屎山堆叠式”：一个循环里又调模型又跑工具又改界面，看起来热闹，改起来想哭。opencode 这种分层的价值，一句话总结就是：让复杂系统变得可以推理。
具体好处有三点：
- 可测试性。因为状态迁移是纯函数式的，喂一组事件，断言最终状态，测试写起来非常顺。很多核心逻辑不需要启动完整 TUI 就能测。
- 可替换性。模型 Provider 是插拔的，今天用 Claude，明天换本地模型，配置改一下就行。工具也是注册制的，新增工具不影响核心逻辑。
- 可回放性。事件日志让整个会话变成可重放的录像。出 bug 了，把事件喂回去，一步步看状态怎么变的，比瞎打日志高效太多。
这个架构地图看懂之后，接下来要进入核心了：所谓“双会话内核”到底是怎么回事。
2. 双会话内核：两套状态机如何协同工作
“双会话”这个词是我读完源码后自己提炼的说法，我觉得也是 opencode 设计里最值得学的一点。它内部其实维护着两条并行推进的会话线，各自有状态机，通过事件总线沟通。理解了这个，才算真正摸到了内核。
2.1 所谓“双会话”，是哪两条线？
先说结论：一条是用户交互会话，对应你敲命令、看输出、随时打断的那个人机对话；另一条是Agent 任务会话，对应模型收到任务后自行规划、调用工具、不断循环直到完成的内部过程。
这两条线的时间尺度完全不同。用户会话是“你一句、它一答”的慢节奏；Agent 会话则是毫秒级决策和调用的快节奏。如果混在一个状态机里，用户打断、工具超时、模型重试这些情况很难梳理。分开之后，每种干扰都变成两条会话之间的一个同步事件。
用生活化类比：用户会话像餐厅前台，Agent 会话像后厨。前台下单、催菜、退菜；后厨按订单切配、炒菜、出餐。两边各干各的，通过传菜窗口（事件总线）交互。订单变化了，前台下个事件通知后厨，后厨调整节奏即可。
2.2 状态机设计：每个会话各自有哪些状态
以 Agent 会话为例，我从代码里理出来的关键状态大概是这样一条链：
idle：空闲，等待任务输入。processing：已把任务交给模型，等待模型响应。awaiting_tool：模型要求调用某个工具，等待工具执行结果。awaiting_user：需要用户确认或补充信息，挂起等待。completed：任务正常结束。aborted：任务被用户或策略中断。
用户会话的状态则简单些：idle、input_expected、rendering、paused。
状态迁移不是随便跳的，每个迁移都有对应事件触发。比如“模型返回了 tool_use 请求”，事件是tool_requested，状态就从processing迁到awaiting_tool。“工具执行完成”，事件是tool_executed，状态回到processing，并重新把结果交给模型。XState 的好处在这就体现出来了，非法迁移根本不可能发生，因为你在定义状态机时就不允许那种跳转。
2.3 双会话如何桥接：中断、确认与并发控制
两条会话各有状态机，那它们怎么配合？答案是事件总线 + 队列。
举个例子，Agent 正在awaiting_tool，执行一个耗时很长的命令，这时候你想插一句话，让模型等会儿换个思路。这个操作不会直接修改 Agent 会话状态，而是先产生一个user_interrupt事件，用户会话暂停正常输出渲染，进入特殊输入模式。然后这个事件被转发给 Agent 会话，Agent 判断当前工具是否可以安全取消，能取消就发出tool_cancel_request，等工具退出后，把“用户插话内容 + 上次结果”打包成一个新的 context，再交给模型继续。
这段逻辑如果写在一个状态机里，状态数量会爆炸。拆成双会话之后，每一侧的状态都很少，复杂的是“两者之间的事件编排”，而这恰好是事件总线擅长的活。
我在自己写 Agent 时也学着这么拆，收获很大。之前总想把“用户能不能打断”这种语义塞进工具执行循环里，结果全是竞态。用双会话模型重写之后，用户打断就是“向另一边发个事件”，对方决定怎么处理，边界清楚了，bug 也少了。
但双会话只是骨架，真正的血肉在于：所有状态变化是如何被可靠记录的。这就轮到事件溯源登场了。
3. 事件溯源：一切状态都是事件的投影
如果说双会话内核是 opencode 的“经”，事件溯源就是它的“纬”。没有事件溯源，双会话之间传的消息只是内存里转瞬即逝的临时变量；有了事件溯源，每一帧状态都留下了证据，可以重放、可以追溯、可以共享。
3.1 为什么不用传统状态存储
传统做法是：把“当前状态”存在数据库里，改了就直接覆盖。比如记录一个会话的标题、消息列表、当前 pending 的工具调用，每次都 UPDATE。这看起来简单，但有几个致命的坑：
- 丢失过程：只存结果，不存原因。“为什么这个会话最后变成了 aborted？”数据库里没有答案。
- 并发冲突：双会话并发更新时间一长，锁竞争改得人崩溃。
- 复现困难：bug 出现时，你拿到的是最后状态，不知道是哪个操作序列把系统推到了那个状态。
- 扩展受限：以后想加“撤销”“分支”“对比”功能，没有历史是无法实现的。
事件溯源换了个思路：不存当前状态，只存变化本身。你不需要记录“现在处于 awaiting_tool”，你只需要记录“有一条 tool_requested 发生了”。当前状态永远可以从事件序列推导出来，过程本身被完整保留。
我用一个表格来对比更直观：
| 维度 | 传统状态存储 | 事件溯源 |
|---|---|---|
| 写入方式 | 覆盖更新 | 追加事件日志 |
| 当前状态 | 直接读取 | 重放事件推导（可加速） |
| 历史过程 | 丢失 | 完整保留 |
| 审计能力 | 弱 | 极强 |
| 调试复现 | 难 | 回放即可 |
| 实现成本 | 低 | 相对高 |
代价是读状态变麻烦了，不能直接 select，得把事件跑一遍。但 opencode 用的是“快照 + 增量重放”的策略：“快照”定期保存某个时点的完整状态，重放时从最近的快照开始，再补后面的事件，开销完全可以接受。
3.2 事件协议与持久化设计
事件是事件溯源的地基，所以事件结构的设计非常关键。opencode 的事件我简化一下，大概长这样：
interface Event { id: string; // 全局唯一 ID sessionId: string; // 属于哪个会话 parentId: string | null; // 父事件，用于追踪因果链 type: string; // 事件类型 payload: unknown; // 具体数据 timestamp: number; // 发生时间 sequence: number; // 会话内递增序号 }每个事件都带sessionId和sequence，目的是保证“每个会话内部的事件是严格有序的”。parentId则记录了因果链，比如一条tool_result的父事件是它的tool_call。
存储端很简单，就是 append-only 的日志文件，通常 JSONL，一行一个事件，结尾只能追加，旧事件绝不修改。这个设计有两个好处：
- 崩溃安全：就算程序崩了，已经写到文件里的事件不会丢。
- 天然审计：谁在什么时候干了什么，事件文件就是完整证据链。
3.3 从事件重建状态：重放与现场恢复
理解了事件记录，再看“恢复现场”就很简单了。
假设程序崩溃重启。启动时，内核扫描会话目录，找到对应的事件日志，按顺序重放事件，重建出完整的内存状态。这个过程看起来像是在快进播放一段录音：系统从空白开始，一条一条把事件“吃”回去，最终恢复到你上次中断时的样子。
这里有两个关键实现细节：
- 幂等性：重放必须幂等。同一个事件喂一百次，结果都必须一样。这就要求事件 payload 里放的是“描述性数据”，而不是“操作命令”。比如事件是
file_updated: { path, content }，而不是run_command: "cp a b"。 - 快照机制：如果事件量太大，每次都从头重放会慢。opencode 的做法是定期计算快照，重放时从最近快照开始，只补尾部增量。快照本身也可以理解为一种缓存，底层还是事件流。
除了恢复，事件回放还能用来测试。我在调试 opencode 时，经常把一个异常会话的事件日志导出，用脚本重放，再打印每个事件后的状态变化。这种调试方式有多爽？就好比你调的账目每笔都有凭证，对账时直接翻凭证，而不是靠猜。
3.4 事件溯源带来的几个隐藏好处
写到这里，我额外说几个事件溯源带来的非显性收益：
- 撤销与分支：既然旧事件都还在，就可以“回到过去某个时间点”分叉出新的会话线，这在 AI 调试中非常实用。比如某次尝试跑偏了，我不需要推倒重来，只需要从偏航前的最后一个事件重新发一条分支。
- 会话共享：事件日志是纯文本，我能把一个会话的完整事件文件发给同事，对方本地重放就能看到同样的现场。
- 增量渲染：TUI 渲染更新时，只需要渲染新事件产生的 diff，不用每次全量重绘。这也是终端 UI 能做到流畅体验的原因之一。
事件溯源理论上讲得再多，都不如看一条实际会话怎么跑起来。下一部分我把关键链路完整拆一遍，顺便给一些可以直接抄的配置。
4. 实操拆解：一次完整会话的关键链路
前面讲的是骨架和理论，现在我把视角降到地面：从你敲下opencode命令那一刻起，系统内部到底发生了什么。这部分内容既能帮你看懂源码，也能在你写类似系统时当作参考实现。
4.1 启动阶段：加载配置与恢复会话
启动流程可以分为几步：
- 读取本地配置文件（比如
opencode.json），确定要加载哪些 Provider、哪些工具、默认模型是什么。 - 扫描历史会话目录，找到最近的会话事件文件。
- 如果存在上次未结束的会话，尝试重放事件恢复状态，否则新建一个空白会话。
- 启动 TUI，渲染初始界面，进入用户会话的
idle状态。
这里有个极其重要的细节：恢复会话不是把历史对话打印一遍就完了，而是要把 Agent 会话的状态也恢复到现场。这意味着最后一个未完成的工具调用、模型上下文、待确认事项，都要按事件重新构建。否则在崩溃恢复后，Agent 会“失忆”，不知道为什么自己停在半路。
配置例子我贴一个简化版，方便你理解配置在启动链路中的位置：
{ "model": "claude", "agent": "build", "tools": { "read": true, "edit": true, "bash": true }, "provider": { "local": { "type": "ollama", "model": "qwen2.5-coder:14b" } } }这里的model指定默认模型，agent指定使用哪种 Agent 行为模式，tools开启哪些内置工具，provider注册自定义的模型来源。整个 opencode 的定制都从这里开始。
4.2 用户发言到模型输出：核心处理循环
用户在输入框敲下内容并回车后，主循环大致是这样：
- 构造事件：生成
user_message_created事件，写入日志。 - 更新用户会话状态：从
idle切到rendering，界面显示用户气泡。 - 转发给 Agent 会话：产生一个内部通知事件，Agent 状态从
idle切到processing。 - 构造 LLM 请求：把当前事件流里与模型相关的部分翻译成 messages，注意这里并不是把整个事件流直接丢给模型，而是投影成模型需要的结构（system + user + assistant + tool 序列）。
- 等待模型输出：模型可能直接返回文本，也可能返回工具调用请求。
- 处理工具调用：如果返回了
tool_use，Agent 迁到awaiting_tool，执行对应工具，把结果写成tool_result事件，再回到第 4 步，把新事件补进上下文继续调模型。 - 循环收敛：直到模型认为任务完成，输出总结文本，整个 Agent 会话迁到
completed。
这个循环听起来简单，坑却非常深。其中最容易踩的是第 4 步：把事件流翻译成模型消息时，必须处理好历史消息的裁剪和工具结果的拼接。如果事件流里有用户中断，而你又把旧上下文原封不动传给模型，模型会被绕晕。
4.3 工具调用机制：Agent 的“手”和“眼”
opencode 内置了一组工具，比如读文件、写文件、执行 shell、搜索、做编辑 diff。每个工具都是一个独立的模块，声明了自己的参数和描述，模型通过结构化输出引用工具名和参数，核心引擎负责校验和派发。
我自己在扩展工具时总结了一个小模板，你照着写基本不会出错：
import { z } from "zod"; const ReadFileArgs = z.object({ path: z.string().describe("文件路径"), offset: z.number().optional().describe("读取偏移量"), }); export const readFileTool = { name: "read_file", description: "读取指定路径的文件内容，支持偏移量", argsSchema: ReadFileArgs, async execute(args) { // 核心引擎会负责把结果转换成 tool_result 事件 return readFileContent(args.path, args.offset); } };实现工具时要特别注意两点：
- 参数校验别偷懒。模型生成参数经常不符合预期，校验不到位，错误会传导到事件流里，很不好查。
- 执行要幂等。同一个工具调用因为超时可能被重试两次，如果工具本身有副作用（比如写文件），重复执行就会出问题。建议在工具实现里加上“如果目标状态已达成，直接返回当前状态”这种保护。
4.4 事件流视角：把整个会话看成一张有向图
上面这套流程，如果只盯着“调模型、跑工具”看，会觉得很杂。但我切换到事件流视角后，整个系统瞬间清晰了：
- 每个事件是一个带时间戳、因果序号、来源会话的节点。
- 事件与事件之间通过
parentId连成因果链。 - 一张完整会话就是一张有向无环图，节点是事件，边是因果。
- 用户会话和 Agent 会话在图上表现为两条主线，交叉点就是那些“同步事件”。
有了这张图，所有复杂场景都可以重新描述：中断 = 用户会话向 Agent 会话插入一个并行分支；撤销 = 从某个节点剪掉后续分支；并发冲突 = 两条主线试图同时修改同一个资源。事件溯源加双会话，本质上是把“并发与交互的复杂性”从控制流里抽出来，变成了“数据的结构”。
4.5 调试会话的一个实用方法：直接看事件流
你不需要依赖 TUI 的界面来理解发生了什么，直接把事件日志导出来看就行。我自己调试时会用一个小脚本把事件流打印成缩进列表，一眼就能看到因果链：
# 把最近会话的事件日志导出，并按序预览 opencode session export --last > session.jsonl # 然后用 jq 处理成可读格式 jq -r '.sequence + " | " + .type + " | " + (.payload | tostring)' session.jsonl | head -50看到输出的那串事件序列，你就知道会话进行到哪一步、卡在哪里。这也是我强烈建议所有用 opencode 的人养成的一个习惯：遇到诡异问题，先看事件流，不要只盯着终端输出。终端输出是渲染过的、裁剪过的，事件流才是原汁原味的现场。
5. 常见问题与排查技巧实录
讲了原理和套路，最后放点我在实际折腾中遇到的真问题。这部分我会不断更新，目前先记录最典型的几个。
5.1 高频问题速查表
| 症状 | 可能原因 | 排查与解决思路 |
|---|---|---|
| 会话恢复后模型“失忆” | 事件重放不完整，或快照过期 | 检查事件日志尾部是否完整，重新触发快照生成 |
| 工具调用结果没有被模型感知 | tool_result 事件没有正确挂到因果链 | 确认parentId是否正确指向对应的 tool_use 事件 |
| 用户中断后模型响应错乱 | 中断事件没有正确注入上下文 | 人工在消息序列里补充“用户/系统中断提示”，再重发模型请求 |
| 本地模型响应很慢 | Provider 层没有启用流式接口 | 开流式输出，或者调低 max_tokens，看核心链路卡在哪个事件 |
| 双会话状态不同步 | 事件总线有丢包或重复消费 | 检查消费逻辑是否做了幂等，事件 ID 去重 |
| 扩展工具报参数错误 | 工具参数 Schema 和模型输出不匹配 | 用日志定位是模型格式问题还是工具校验问题，先单独调工具再挂到 Agent 上 |
5.2 三条避坑经验（写完这几个我亏过的）
第一，别让用户会话和 Agent 会话共享可变对象。
我早期试着给两个会话共用一个内存对象来存“当前正在编辑的文件路径”，以为能省点事。结果用户一打断，Agent 那边的状态直接把文件路径改掉了，用户界面上显示的还是旧路径，两边数据全乱。后来学乖了：两边只通过事件传递数据，任何共享状态都要改成显式同步事件。脐带式的隐式共享，在双会话模型下就是定时炸弹。
第二，工具超时不一定是模型问题，先查事件日志时间戳。
某次我排查“Agent 卡在 awaiting_tool”，第一反应是模型响应被卡住。结果导出事件日志一看，tool_requested事件发生了，但tool_executed事件压根没生成，说明是工具本身的问题而不是模型。后来发现是工具内部做了个大文件扫描，超出预期耗时。从那以后，我给每个工具执行都加了超时上限，超时就发tool_timeout事件，让核心引擎决定重试还是失败。
第三，恢复会话时，别只重建状态，还要重建“待确认列表”。
正常流程里，Agent 有时会产出“下一步计划”让用户确认。这类 pending 状态如果不在事件里记录好，恢复会话时就丢了。结果用户从崩溃恢复后，看到的是“Agent 直接执行了计划”，完全没经过确认。这个问题比较隐蔽，症状看起来像“Agent 自作主张”，根因却是“确认态没有事件化”。解决办法是在设计状态机时，把“等待用户确认”显式建模成一个状态，并且有对应的事件进入和离开这个状态。
5.3 一条被低估的高级玩法：事件流作为团队协作协议
最后分享一个我最近在探索的方向。既然整个会话都是事件流，那就意味着会话是可以当作协作基础设施来用的。
比如你把一个会话的事件文件放到共享目录里，另一个人拉下来重放，就能直接看到你的完整操作过程。如果再配合自定义事件类型，还可以让一个 Agent 的事件流被另一个 Agent 监听，这就能实现多 Agent 协作的消息总线雏形。
我现在的一个模拟项目里，就是用类似思路做了两个 Agent：“研究型 Agent”负责查资料、输出结论事件；“执行型 Agent”订阅这些事件，拿到结论后直接动手改代码。两者没有直接函数调用，完全靠事件解耦。这套玩法的上限，我觉得比“一个 Agent 里塞更多工具”要高得多。
关于 opencode 的上篇先写到这儿，双会话内核和事件溯源这两根主线，应该能让想深入的朋友按图索骥了。我个人在实际使用中最大的体会是：这类 Agent 项目最难的不是模型调得多花哨，而是把交互、并发、恢复这些工程问题理清楚。事件溯源把“过程”留下来，双会话把“不同步调”切开，这两点配合，直接决定了一个 Agent 系统的上限。下篇我会继续拆模型接入层和工具系统，到时候见。
