opencode 双会话与事件溯源：AI 编码助手的内核运行机制

开头先说个事：我是在排查一次“模型回答循环重复”的问题时，被逼着把 opencode 的源码和日志翻了个底朝天。之前我一直把它当成一个普通的 AI 编码助手在用，能写代码、能改文件、能跑命令，仅此而已。但那次问题里，同一个输出被连续推了四遍，界面上的消息一直在滚动，模型调用记录却只有一次——这种“界面状态和实际状态对不上”的现象，让我意识到它内部一定有一套比我想象中复杂得多的状态管理机制。后来我把它拆开看了一遍，才发现 opencode 的工程全景、双会话内核和事件溯源这三件事，才是它跟“套壳对话工具”拉开差距的根本原因。这篇就按我自己的理解，把这三个层面拆开讲清楚。

这篇文章适合谁看？如果你正在用 opencode，想搞明白它的配置项、目录结构、报错信息到底在说什么；或者你想基于它做二次开发、接入自己的模型服务、写 Skill 扩展，那这篇应该能帮你少走不少弯路。我会尽量不以“官方文档复读机”的姿态写，而是结合我在 Ubuntu 环境里的实际部署、VS Code 集成、以及踩过的几个报错坑来讲。

1. opencode 工程全景：它不是一个聊天框，而是一套流水线

1.1 核心链路：从“用户敲下回车”到“文件被修改”

先建立一个整体认知：opencode 表面上是一个命令行聊天界面，你在终端里敲一段自然语言，它回一段回答，顺便帮你改改代码。但这只是它最外面的一层皮。真正的核心链路是一条“输入 → 上下文组装 → 模型调用 → 工具执行 → 结果回写”的流水线，每一段都有独立模块负责：

• 输入层：读取用户在 TUI 里的输入，以及来自 VS Code 扩展、HTTP 接口的外部输入。
• 会话层：维护“当前在聊什么”和“当前这个请求在干什么”两份状态，也就是标题里说的双会话。
• Provider 层：把统一的请求体翻译成各家模型服务的 API 格式，处理鉴权、重试、配额。
• 工具层：决定模型能不能改文件、跑命令、搜代码，以及这些动作以什么粒度被执行和回滚。
• 事件层：把上面所有环节产生的状态变化，全部追加到一条持久化的事件流里。

我当初看源码之前最大的误解，是以为 opencode 的核心是“模型调用”。看完全景之后才发现，模型调用只是流水线中间的一段。它真正花心思设计的，是“如何安全地让模型操作你的工程”，以及“如何把每一步操作都记录下来供回溯”。

1.2 仓库模块地图：CLI、服务端、Provider 层和工具层

我第一次 clone 仓库之后，对着目录结构愣了一会儿，因为它的组织方式和我想的“一个主程序包打天下”完全不一样。按我的归纳，核心模块大致可以分成四块：

这个拆分在工程上有个直接好处：你可以在不开 TUI 的情况下，通过 HTTP 接口或插件去驱动同一个内核；也可以在完全不换内核的情况下，换掉 Provider 层去接不同的模型服务。我后来用脚本来批量跑它，走的就是不走界面的方式，依赖的正是这种分层。

1.3 一次完整调用的数据路径

为了说明这条流水线怎么串起来，我画了一条自己理解的调用路径（用文字描述，不依赖任何图表工具）：

1. 用户在 TUI 输入一句话，回车。
2. 输入层把这句话封装成一个 user 消息，追加到当前会话。
3. 会话层取出历史消息，加上系统提示词、工程上下文、Skill 描述，组装成一次模型请求。
4. Provider 层把请求发出去，拿到流式输出，边收边往事件流里写。
5. 模型输出里如果带了工具调用指令（比如"修改这个文件"），工具层会执行它，并把结果作为 tool 消息追加回会话。
6. 会话层把工具结果再次提交给模型，模型继续给出下一段输出。
7. 上面的步骤循环，直到模型输出结束标记。

整个过程里，界面只是把事件流里的一部分渲染给你看。你看到的消息顺序，本质上就是事件流里事件的顺序。这让我明白了为什么单独改界面上的文字没有用——因为真正决定行为的是事件流和会话状态，UI 只是投影。

2. 双会话内核：管理会话与请求会话为何必须分层

2.1 两层会话各自的职责边界

opencode 里最让我觉得“设计得聪明”的地方，就是把会话拆成了两层，而不是像普通聊天工具那样只有一个会话对象。我按自己的理解给它起了名字：管理会话（Session）和请求会话（Turn / Request Session）。

管理会话对应的是“用户视角的对话”，它的生命周期从你启动 opencode 开始，到你退出为止。它负责的事情包括：记住你在这个工程里聊过哪些话题、维护消息列表、保存会话 ID 以便你下次回来继续。它关心的粒度是“对话”。

请求会话对应的是“模型视角的一次干活流程”，它的生命周期从你提交一条指令开始，到模型完成所有工具调用、给出最终回答为止。它关心的粒度是“这个任务执行到哪一步了、下一步要调用什么工具、要不要把控制权交回用户”。

换句话说，管理会话回答的是“我们在聊什么”，请求会话回答的是“当前这轮任务该怎么推进”。两者是包含关系：一次管理会话里，可以有一个或多个请求会话；而每个请求会话内部，又可能因为工具调用产生多轮模型来回。

2.2 消息跨会话流转的顺序

这个双会话结构不是摆设，它直接影响你在 TUI 里看到的每一条消息。我把一次“帮我重构一下这个函数”的完整流转列在下面：

• 第 1 步：用户消息进入管理会话，追加一条 user 消息。
• 第 2 步：内核基于管理会话的历史，创建一个新的请求会话，并生成一个新的请求 ID。
• 第 3 步：请求会话调 Provider 拿模型输出，输出以 assistant 消息暂存。
• 第 4 步：模型请求改文件，工具层执行，返回 tool 结果。
• 第 5 步：工具结果直接回到请求会话，不经过管理会话的“历史消息”层。
• 第 6 步：请求会话把最终结果回写管理会话，此时管理会话里才会看到一条完整的回合。

这样做最直接的效果是：历史消息里不会混入工具调用的内部噪音。如果你只看管理会话，会觉得“模型很干净地改了个文件”；而如果你进到请求会话层，才能看到那次工具调用传了什么参数、返回了什么报错。排障的时候这两层缺一不可。

2.3 双会话设计的三个直接收益

我实际用下来，双会话至少带来三个好处，这些好处在单会话模型里是拿不到的：

第一，上下文可控。管理会话的上下文可以按需裁剪，但请求会话的内部上下文必须完整。如果混在一起，历史一长就会被截断，而截断往往会切掉关键工具执行记录。分层之后，截断只影响“闲聊记忆”，不影响“任务执行记忆”。

第二，并发隔离。我在脚本里同时开多个请求时，每个请求会话拥有独立的状态。即使其中一个请求因为模型超时报错，也不会污染管理会话里另外正在进行的任务。

第三，回滚容易。请求会话记录了一个任务完整执行过的工具动作序列。如果模型在中途干了蠢事，比如删错了文件，我可以根据请求会话的事件列表，精确知道要回滚哪些操作。这比单会话结构里靠人工翻聊天记录定位要可靠得多。

3. 事件溯源：为什么 opencode 要把所有动作都变成追加式事件

3.1 事件流的组织方式：追加日志、不可变性、订阅重放

事件溯源（Event Sourcing）这个词听起来唬人，其实核心思想很朴素：不保存“当前状态是什么”，而是保存“发生过什么”。每次状态变化都作为一条新事件追加到日志末尾，只增不改。当前状态可以从事件流按顺序重放出来。

opencode 的会话状态、消息列表、请求进度，全都走了这条路径。我在它的数据目录里翻了半天，发现它并不维护一个“最新消息对象”的单一存储，而是有一长串事件记录，每条都带有类型、会话 ID、时间戳、载荷。

用我的话说就是：把“程序的状态”降维成了一组“已经发生的事实”。你不需要考虑状态怎么被修改，只需要考虑怎么追加事实。这跟数据库里的 Binlog、Git 里的提交记录是同一个思想——它们记录的也都不是最终结果，而是变化过程。

3.2 事件流里跑着哪些类型的事件

我在实际排查中归纳过，opencode 里出现频率最高的几类事件大致如下：

理解这个表，你就能明白一个很反直觉的现象：为什么界面上的消息顺序偶尔和模型实际返回顺序不一致？因为界面渲染的是“多路事件汇合后的结果”，而模型输出只是其中一路。比如工具执行耗费了很久，期间界面可能先渲染了“模型正在思考”事件，等工具结果回来后才渲染“模型继续输出”。这不是 bug，这是事件流的正常表现。

3.3 事件溯源在断点续跑、任务恢复和界面同步中的价值

事件溯源给 opencode 带来的最大实际价值，我觉得是三点：

一是断点续跑。我在 Ubuntu 终端里跑长任务时遇到过会话中断。重连之后，界面能恢复到中断前的样子，靠的不是记忆当前消息，而是重放事件流，把所有已发生的事件按顺序执行一遍，让状态“长回去”。这个能力和“保存-恢复”完全不同：保存只存结果，重放能保留过程。

二是界面多端同步。TUI 和 VS Code 扩展看到的是同一个事件流。不管你在哪个端操作，另一端能迅速感知状态变化，底层就是事件订阅与广播。如果你自己写插件，监听事件流就能拿到任何状态变更，不需要轮询接口，这个体验是真舒服。

三是排障时间旅行。前面说的重复输出问题，我就是把事件流导出来，按时间顺序一条一条看，发现“界面显示第 4 次输出”对应的事件其实是同一条输出事件被不同界面组件重复渲染了。如果没有事件流，这种“状态到底对不对”的争论根本无法解决。

4. 编辑器协同与扩展：把 opencode 接进 VS Code 并搭建自己的 skill

4.1 VS Code 接入的常见方式和权限边界

opencode 和 VS Code 协同这件事，网上的问法五花八门，但归纳起来就两类：一类是“怎么在 VS Code 里用 opencode”，另一类是“怎么让 opencode 操作 VS Code”。

第一类的常规做法是安装 opencode 官方扩展，扩展本质上是把 TUI 搬进了编辑器面板，同时提供一个事件流接口，让编辑器侧能高亮当前正在被修改的文件、展示 diff 预览。我试过之后有一个明显感受：它比我在终端开两个窗口要顺手得多，因为 diff 可以直接在编辑器里看。

第二类要小心。opencode 操作 VS Code 的能力，本质上是它的工具层接入了编辑器的命令接口，比如打开文件、跳转行号、执行重构命令。这里有个权限边界问题：opencode 默认能执行你当前用户的权限内操作。如果你给了它“自动接受编辑器弹窗”的权限，它就能改文件；如果你限制了它只能读，它就只读。我个人的建议是初期不要开全自动，让它改完文件后停在 diff 预览阶段，确认无误再合并，等摸清了它的行为模式再放开。

4.2 Skill 搭建：三步让模型学会你的私有操作流程

Skill 是 opencode 里最实用的扩展机制，它可以理解成“给模型一份可调用的私有操作手册”。网上问“如何通过 opencode 搭建一个 skill”的人不少，我把自己搭建的流程拆成三步，参考了我的实际项目：

• 第一步：写 Skill 描述文件。描述要写清楚“这个 skill 什么时候被触发、它能干什么、你有什么约束”。描述质量直接决定模型会不会自动调它。我最初写得太笼统，模型几乎不触发，后来改成“当用户提到发布部署时，使用此 skill”，触发率立刻上来了。
• 第二步：用自然语言写执行流程。把步骤写成分步指令，同时标注哪些步骤需要用户确认，哪些可以自动执行。比如我写了一个“提交 PR”的 skill，里面明确标注了“推送前必须确认分支名”。
• 第三步：在 opencode 配置里注册 skill 的加载路径。之后在会话里用自然语言提到相关需求，模型就会把 skill 里的步骤当作工具调用序列来执行。

这个机制的本质，是把“模型不知道你的项目规范”这个问题，转化成“把你项目规范写成它能读的步骤清单”。它和你写自动化脚本的区别在于：脚本是固定流程，而 skill 是模型读了之后自己决定怎么执行，所以你写的步骤要留出判断空间，别写太死。

4.3 模型服务配置与额度机制的注意点

网上关于模型服务的提问里，有一个出现频率很高的问题：“opencode go 套餐是每种模型分开计算额度吗？”我查到的情况是：opencode go 这类聚合套餐，额度通常是按模型分组或按服务商维度计算的，不同模型的额度并不一定共享同一个池子。具体表现为：

• 有的套餐里，基础模型（比如常规对话模型）和增强模型（比如代码专用模型）额度分开统计。
• 如果你在配置里改了模型映射，可能并不是“套餐里所有模型都能随便切”，而是仍然受额度分组限制。
• 所以我建议你不要只看总配额，要看每个模型组自己的剩余额度。我踩过的坑是：我以为换了个小模型能省额度，结果那个模型组根本没有可用额度，直接报错。

另一个高频问题在安装环节。Ubuntu 下安装 opencode 一般是通过包管理或直接跑安装脚本，最常见的问题是脚本下载慢、二进制启动后没有做 shell 环境初始化导致命令找不到。我实装时先检查了 Node.js 版本和网络环境，再执行安装脚本，并用opencode --version验证。如果你在安装后遇到“command not found”，优先检查 PATH 里有没有包含安装目录。

5. 三个高频问题与我的排查路径

5.1 免费额度报错的根因分析

网上关于 opencode 的报错搜索里，最热门的一条是“error from provider (console): opencode's free tier can only be used from within opencode”。我第一次看到这条报错也挺懵，因为它看起来很像“你被禁止使用了”。但其实它的含义是：免费档次的模型服务，只能在 opencode 自身的控制台环境里使用。

换句话说，如果你把 opencode 的密钥或 Provider 配置拿到外部脚本、第三方客户端里直连，服务端校验发现“这不是 opencode 官方环境发来的请求”，就会返回这个错误。排查顺序应该是：

• 第一步，确认你是在 opencode 配置里填的 Provider 信息，还是在外部脚本里手动拼的请求。后者大概率触发此报错。
• 第二步，确认当前环境变量里有没有残留旧密钥，有时候是环境变量优先于配置文件导致的。
• 第三步，检查你是不是把免费档模型和付费档模型搞混了。免费档模型在仅 opencode 环境可用，付费档模型一般没有这个限制。

我最后解决的办法很简单：把外部脚本里的直连方式改成调用 opencode 的本地服务接口，让 opencode 内核去代理模型请求，而不是我自己拼 HTTP 请求去撞鉴权。

5.2 是模型问题还是工具问题？一个判断方法

日常使用里，最让人头疼的是模型报错和工具报错混在一起。模型返回超时、工具执行失败、Provider 鉴权失败，三种问题在界面上可能表现相似，都是“没反应”或“红字”。我的判断方法是看请求会话的事件序列：

这个方法我强烈建议每个经常用 opencode 的人都实践一遍。它不需要你懂源码，只要你能找到 events 日志的目录，按时间段过滤出相关事件就能定位。比对着界面猜要快十倍。

5.3 用事件日志做“时间旅行”式排查

最后这条是我个人最想分享的经验：排障时，把事件日志当作“时间旅行工具”来用，而不是当作“错误列表”来翻。

比如之前遇到一个诡异现象：同样的指令，第一次运行正常，第二次就跑偏，第三次直接报错。单看错误行你根本看不出原因。我把三次运行的事件日志都导出来，按会话并排对比，才发现问题出在第二次运行时旧的工具执行结果没有被正确清理，请求会话带着上一个任务残留的上下文继续执行，导致模型把旧状态当成了新状态。

修复方法是在任务开始前重置请求会话状态，并确保管理会话的关键上下文被重新组装。这种问题，如果你只看“报错文字”是永远定位不到的，必须看事件变化的全过程。这就是事件溯源给我的排障能力带来的最大升级。

我自己的感受是：opencode 这套双会话加事件溯源的设计，让你能像一个“旁观者”一样观察模型和工具的每一次交互，而不是被夹在中间干着急。后续如果有机会，我打算写一篇（下篇），重点讲怎么基于事件流做自定义插件，以及怎么调教 Skill 的触发条件让它更精准。如果你手上也有类似的诡异问题，不妨先打开事件日志，时间顺序从头看一遍，你多半能发现不少藏在界面背后的真相。