1. 项目缘起为什么我要啃 opencode 这块硬骨头第一次接触 opencode 是在一个深夜当时我正在给团队选型一个能跑在终端里的 AI 编程助手。市面上的方案要么是 IDE 插件形态、要么是云端 SaaS真正能塞进 CI 流水线、能在 SSH 会话里直接调用的工具少得可怜。opencode 出现在视野里的时候我第一反应是又一个套壳 CLI但翻完它的仓库结构之后我改主意了——这东西的工程化程度明显不是周末项目级别。opencode 是一个用 TypeScript 写的、跑在 Bun 运行时上的终端 AI 编程智能体。它的核心卖点有三个双会话内核、事件溯源架构、以及基于 Monorepo 的模块化工程布局。这三个词听起来很唬人但拆开看其实都是很实在的工程决策。我花了大概两周时间把它的源码从入口一路读到核心调度层中间踩了不少坑也积累了一些理解。这篇上篇主要聊工程全景和内核设计下篇再展开讲工具调用、Provider 抽象和实际接入。如果你正在做智能体框架、想理解一个生产级 CLI Agent 是怎么组织的或者单纯想搞清楚事件溯源这种后端概念怎么被搬到前端工具里那这篇内容应该对你有用。我会尽量把每个设计决策背后的为什么讲清楚而不是只罗列目录结构。读完之后你至少能做到两件事一是能自己把 opencode 跑起来并读懂它的启动流程二是能判断它的架构里哪些部分可以抄、哪些部分要绕开。需要提前说明的是opencode 迭代很快我读的版本和你看的可能有差异但核心架构思路是稳定的。另外本文涉及的所有代码结构分析都基于公开仓库不涉及任何私有实现。2. 工程全景Monorepo 布局与模块边界2.1 为什么是 Monorepo 而不是多仓库opencode 用的是典型的 Monorepo 结构根目录下packages/里躺着十几个子包。很多人第一反应是一个 CLI 工具至于拆这么多包吗我一开始也这么想直到我看到它的依赖关系图才明白过来。拆包的核心动机是运行时边界。opencode 不是一个单体进程它至少包含这几类角色终端 UI 层、核心调度层、工具执行层、Provider 适配层、以及共享的类型定义层。如果全塞在一个包里TypeScript 的类型检查会变得极慢而且 Bun 打包时无法做 tree-shaking 优化。拆成独立包之后每个包可以独立编译、独立测试UI 层甚至可以单独替换成 Web 版本而不动核心逻辑。具体来说我观察到的包划分大致是这样的包名职责是否可独立发布core会话调度、事件总线、状态机是tui终端渲染、键盘交互否强依赖 coretools文件读写、命令执行、搜索等工具实现是providers各家模型 API 适配是shared类型定义、常量、工具函数是cli命令行入口、参数解析否这种划分的好处是依赖方向单一。cli 依赖 corecore 依赖 tools 和 providerstools 和 providers 依赖 shared没有任何反向依赖。我在读代码的时候只要顺着依赖方向走就不会迷路。这一点比很多看起来拆了包、实际上互相 import的伪 Monorepo 强太多。2.2 Bun 作为运行时的取舍选 Bun 而不是 Node 是个很有意思的决定。Bun 的优势在于启动速度快、内置 TypeScript 支持、自带打包器和测试运行器。对于一个 CLI 工具来说启动速度是用户体验的第一道门槛——你敲下命令到看到界面如果超过 500ms用户就会觉得卡。我实测过opencode 冷启动到出现交互界面大概在 200ms 左右同样的代码用 Node tsx 跑要 600ms 以上。这个差距在频繁调用的场景下非常明显。Bun 内置的Bun.file、Bun.spawn这些 API 也比 Node 的对应实现更简洁工具层写起来省事不少。但 Bun 也有坑。最大的问题是生态兼容性。有些 npm 包依赖 Node 特有的 API在 Bun 下会报错。opencode 的应对策略是在 providers 层做了适配封装把可能出问题的调用隔离起来。我在自己项目里复现这个模式时发现只要把第三方依赖集中在少数几个包里Bun 的兼容性问题基本可控。提示如果你打算用 Bun 跑 opencode 的源码务必确认 Bun 版本在 1.1 以上。早期版本对node:worker_threads的支持不完整会导致工具执行层挂起。2.3 TypeScript 配置的细节opencode 的 tsconfig 有几个值得注意的设置。首先是moduleResolution: bundler这是配合 Bun 的必要配置让 TypeScript 按打包器的解析规则找模块。其次是strict: true加上一堆额外的严格检查比如noUncheckedIndexedAccess这个选项会让数组访问返回T | undefined逼着你处理边界情况。我一开始觉得这些检查太啰嗦写起来到处要加!或判空。但读到 core 层的事件处理代码时我改观了——正是因为强制判空事件队列的边界处理才没有隐藏 bug。这种写的时候烦、读的时候爽的配置在长期维护的项目里是值得的。另外它的类型声明文件组织方式也值得一提。shared包里有一个types/目录里面按领域拆成session.d.ts、event.d.ts、tool.d.ts等。这种拆分让类型定义和实现分离其他包引用类型时不会意外引入实现代码。如果你在写库这个模式可以直接抄。3. 双会话内核一个被低估的设计决策3.1 什么是双会话为什么需要它双会话内核这个词是我自己总结的opencode 官方文档里没有这个说法。我指的是它内部同时维护两条独立的会话流一条是面向用户的交互会话一条是面向模型的推理会话。这两条流共享底层的事件总线但生命周期和状态管理是分开的。为什么要这么设计我举个实际场景你就懂了。当你在终端里输入帮我重构这个函数用户会话记录的是你的输入、界面的滚动位置、当前光标状态。而模型会话记录的是完整的对话历史、工具调用结果、token 消耗。如果只有一条会话流这两类状态会互相污染——比如模型需要看到完整历史但用户界面只需要显示最近几条模型会话可能因为工具调用而暂停但用户界面必须保持响应。分开之后用户会话可以随时被中断、回滚、重放而不影响模型会话的连续性。这个设计在实现撤销上一步功能时特别有用——你只需要回滚用户会话的状态模型会话的历史保持不变重新发起请求时模型看到的上下文是一致的。3.2 会话状态机的实现每条会话本质上是一个状态机。我读到的状态定义大致有这几个idle、thinking、tool_calling、waiting_user、error。状态之间的转换由事件驱动而不是直接调用方法。这种设计的好处是可测试性。因为状态转换是纯函数式的给定当前状态和事件返回新状态你可以写单元测试覆盖所有转换路径不需要启动整个应用。我在自己的项目里模仿这个模式后会话相关的 bug 减少了大概一半。状态机的核心代码在 core 包里大致长这样我做了简化type SessionState | { status: idle } | { status: thinking; requestId: string } | { status: tool_calling; toolName: string; args: unknown } | { status: waiting_user; prompt: string } | { status: error; message: string }; function transition(state: SessionState, event: SessionEvent): SessionState { switch (state.status) { case idle: if (event.type user_input) { return { status: thinking, requestId: event.id }; } return state; case thinking: if (event.type tool_request) { return { status: tool_calling, toolName: event.name, args: event.args }; } if (event.type response_complete) { return { status: idle }; } return state; // ... 其他分支 } }注意这里没有用任何类或继承全是 discriminated union switch。这种写法在 TypeScript 里类型收窄非常自然编译器能帮你检查是否漏了分支。相比之下用 class 继承的写法在状态多的时候会变得难以追踪。3.3 两条会话如何同步双会话最大的难点是同步。用户会话和模型会话虽然独立但在某些时刻必须对齐。比如用户按下 CtrlC 中断两条会话都要进入终止状态比如工具调用完成模型会话要继续推理用户会话要更新界面。opencode 用的是事件广播 各自订阅的模式。核心是一个 EventBus任何状态变化都先发事件两条会话各自订阅自己关心的事件类型。这样解耦之后新增一条会话流比如日志会话不需要改动现有代码。我踩过的一个坑是事件顺序。在异步环境下事件到达顺序不保证和发出顺序一致。opencode 的解法是给每个事件带一个单调递增的 sequence number订阅方按序号排序后再处理。这个细节在文档里没写是我读源码时发现的。如果你自己实现类似架构这一点务必注意否则会出现界面显示工具调用完成、但模型还在等待的诡异状态。4. 事件溯源把后端思想搬进 CLI4.1 事件溯源到底解决了什么问题事件溯源Event Sourcing的核心思想是不存储当前状态而是存储导致状态变化的所有事件需要状态时通过重放事件计算出来。这个概念在后端领域很成熟但用在 CLI 工具里我是第一次见。opencode 用它解决的核心问题是会话的可恢复性和可审计性。传统做法是把会话状态序列化成 JSON 存盘恢复时反序列化。但这种方式有几个问题一是状态结构变化后旧存档无法读取二是无法回答这个状态是怎么变成这样的三是并发写入时容易冲突。事件溯源把这些问题都绕开了。每个事件是一个不可变的记录追加写入即可不存在并发冲突。状态结构变化时只要事件格式不变重放逻辑可以适配新结构。而且因为保留了完整事件流你可以随时回放某个会话看模型每一步在想什么、调了什么工具。4.2 事件的数据结构设计我观察到的事件结构大致包含这几个字段interface BaseEvent { id: string; // 唯一标识 seq: number; // 单调递增序号 timestamp: number; // 毫秒时间戳 sessionId: string; // 所属会话 type: string; // 事件类型 payload: unknown; // 类型相关数据 }这里有几个设计细节值得说。seq字段是全局单调递增的不是每个会话独立。这样跨会话的事件也能排序方便做全局审计。sessionId让事件可以按会话过滤重放时只取相关事件。payload用 unknown 而不是 any强制消费方做类型收窄。事件类型我见到的有session_created、user_message、model_request、model_response、tool_call、tool_result、error、session_closed。每种类型的 payload 结构不同但都遵循只追加、不修改的原则。4.3 重放机制与快照优化纯事件溯源的问题是重放慢。如果一个会话有上万条事件每次恢复都要从头重放用户体验会很差。opencode 的解法是定期快照每 N 条事件或每隔一段时间把当前状态序列化存一份恢复时从最近的快照开始重放后续事件。快照的粒度是个权衡。太频繁会拖慢正常操作太稀疏则恢复慢。我看到的实现是每 100 条事件或每 5 分钟做一次快照具体阈值可能可配置。这个数字不是拍脑袋定的——100 条事件大约对应一次完整的对话轮次5 分钟是用户能容忍的恢复时间上限。注意快照只是优化不是真相来源。任何时候删除所有快照系统都应该能从事件流完整恢复。如果你实现类似机制务必保证快照可以从事件重建否则快照就成了隐藏的状态源违背事件溯源的初衷。4.4 事件存储的选型存储层我看到的实现是追加写的 JSONL 文件每个会话一个文件放在用户目录下的.opencode/sessions/里。选 JSONL 而不是 SQLite 的理由很实际JSONL 是纯文本用户可以直接查看、grep、甚至手动编辑写入是 append-only不需要事务跨平台没有二进制兼容问题。代价是查询效率低。如果要按时间范围或事件类型查询得全文件扫描。但 CLI 工具的会话量通常不大这个代价可以接受。如果哪天需要支持大规模查询再迁移到 SQLite 也不难因为事件结构是独立的。我在自己项目里试过用 SQLite 存事件结果发现调试时远不如 JSONL 方便。用tail -f实时看事件流的感觉比开个数据库客户端强太多。这个经验分享给正在选型的你。5. 核心模块拆解从入口到调度5.1 CLI 入口的启动流程opencode 的入口文件很薄大概只做三件事解析命令行参数、加载配置、启动核心运行时。我顺着入口读下去启动流程大致是解析 argv识别子命令如run、chat、config读取配置文件全局配置 项目级配置后者覆盖前者初始化 EventBus 和事件存储根据配置加载 Provider注册工具启动 TUI 或执行单次命令这个顺序有讲究。EventBus 必须在 Provider 之前初始化因为 Provider 加载过程本身会产生事件。工具注册必须在会话启动之前否则模型请求工具时会找不到。这些依赖顺序在代码里没有显式声明是靠调用顺序保证的。如果你重构要特别小心别打乱。5.2 配置系统的分层设计配置分三层默认配置代码内置、全局配置用户目录、项目配置当前目录。合并规则是深合并项目配置优先级最高。这个设计让用户可以设置全局偏好比如默认模型同时在特定项目里覆盖比如这个项目用另一个模型。我注意到一个细节配置合并时会做schema 校验不合法的配置会报错而不是静默忽略。这个选择我一开始觉得太严格后来发现它避免了很多配置写了但没生效的困惑。相比之下很多工具静默忽略错误配置用户排查半天才发现是拼写错误。配置的 schema 定义在 shared 包里用 TypeScript 类型 运行时校验双重保证。运行时校验我猜是用 zod 或类似库因为错误信息格式很像。这种类型 运行时双保险的模式在配置这种外部输入场景下是必要的。5.3 工具注册与发现机制工具层的设计我特别喜欢。每个工具是一个独立模块导出统一的接口interface Tool { name: string; description: string; parameters: JSONSchema; execute(args: unknown, context: ToolContext): PromiseToolResult; }注册时把工具实例塞进一个 Map模型请求工具时按 name 查找。这个设计的好处是工具之间完全解耦新增工具不需要改任何现有代码只要在注册表里加一行。工具的描述和参数 schema 会作为 prompt 的一部分发给模型所以写描述时要考虑模型的阅读理解。我见过很多工具描述写得像 API 文档模型根本看不懂。opencode 内置工具的描述写得比较口语化比如文件读取工具的描述是Read the contents of a file at the given path简单直接。5.4 Provider 抽象层Provider 层负责和各家模型 API 打交道。抽象的核心是一个统一的接口把不同厂商的请求/响应格式归一化。我看到的接口大致是interface Provider { name: string; chat(request: ChatRequest): AsyncIterableChatChunk; listModels(): PromiseModelInfo[]; }用 AsyncIterable 而不是 Promise 是因为要支持流式响应。模型逐 token 返回时上层可以边收边渲染用户体验更好。这个选择在实现上比 Promise 复杂但值得。Provider 的注册也是插件式的配置文件里指定用哪个 Provider运行时动态加载。这样新增一家模型支持不需要改核心代码。我实测过接入一个自定义 Provider大概只花了半小时主要是把请求格式转换写对。6. 实操把 opencode 跑起来并读懂启动日志6.1 环境准备与安装我用的环境是 Ubuntu 22.04Bun 1.1.30。安装步骤不复杂# 安装 Bun curl -fsSL https://bun.sh/install | bash # 克隆仓库 git clone https://github.com/opencode-ai/opencode.git cd opencode # 安装依赖 bun install # 构建 bun run build # 运行 bun run dev第一次跑可能会遇到依赖下载慢的问题可以配置镜像源。构建过程大概 30 秒比 Node 项目快不少。6.2 读懂启动日志opencode 启动时会输出一些日志默认级别是 info。如果你想看详细流程可以设置环境变量OPENCODE_LOG_LEVELdebug。我建议第一次读源码时开 debug能看到事件流的完整轨迹。日志里我关注几个关键点EventBus 初始化完成、Provider 加载成功、工具注册数量、会话存储路径。这几个信息能帮你确认系统是否正常启动。如果 Provider 加载失败通常是 API key 没配或网络问题如果工具注册数量为 0说明工具层加载有问题。6.3 用事件流调试会话最实用的调试技巧是实时看事件流。会话文件是 JSONL你可以用tail -f ~/.opencode/sessions/session-id.jsonl | jq这样每产生一个事件你都能看到。当模型行为不符合预期时看事件流能快速定位是哪个环节出了问题——是模型没理解指令还是工具调用参数错了还是结果解析失败。我踩过的一个坑是事件流里看到tool_call但没看到tool_result排查半天发现是工具执行超时被静默取消了。后来我在工具执行层加了超时日志这类问题就好定位了。这个经验告诉我事件溯源系统里缺失的事件和错误的事件一样重要。6.4 常见启动问题速查现象可能原因排查方法启动即退出配置文件格式错误检查~/.opencode/config.json的 JSON 合法性Provider 加载失败API key 未设置检查环境变量或配置文件中的 key 字段工具调用无响应工具执行超时开 debug 日志看工具执行耗时会话无法恢复事件文件损坏检查 JSONL 文件是否有截断行TUI 渲染错乱终端不支持换用支持真彩色的终端或设置TERMxterm-256color7. 架构启示哪些设计值得抄哪些要绕开7.1 值得借鉴的三个模式第一双会话分离。任何需要同时维护用户可见状态和内部推理状态的系统都可以用这个模式。比如客服机器人、游戏 AI、自动化测试工具。分离之后两边可以独立演进互不干扰。第二事件溯源 快照。这个组合适合需要审计、回放、恢复的场景。实现成本比传统状态序列化高但长期收益大。关键是快照必须可从事件重建否则就退化成普通的状态存储了。第三工具插件化。工具用统一接口 注册表管理新增工具零侵入。这个模式在扩展性上优势明显尤其适合工具数量会持续增长的场景。7.2 需要谨慎的两个点Bun 的生态风险。Bun 快是快但生态还在追赶 Node。如果你的项目依赖大量原生模块或冷门 npm 包迁移到 Bun 可能踩坑。建议先在非关键路径上试点验证兼容性后再全面切换。事件存储的查询瓶颈。JSONL 适合小规模但事件量上去之后查询会变慢。如果你的场景需要复杂查询按时间范围、按类型、聚合统计早点上 SQLite 或专用事件存储别等到性能出问题再迁移。7.3 我自己的实践体会我在自己的一个内部工具里复用了 opencode 的双会话 事件溯源架构代码量比原来的状态机方案多了大概 30%但调试时间减少了一半以上。最大的收益是可观测性——任何时候出问题我都能回放事件流看到完整的因果链。这种事后能查清楚的能力在复杂系统里比性能优化更值钱。当然也有代价。事件溯源的心智负担比传统状态管理高团队新人需要时间理解。我的建议是如果系统状态简单、不需要审计和回放别上事件溯源杀鸡用牛刀。但如果系统状态复杂、出问题难排查那这个投入是值得的。下篇我会展开讲工具调用的完整链路、Provider 适配的细节、以及如何接入自定义模型。如果你在跟着读源码建议先把 core 包的事件总线和会话状态机吃透那是理解整个系统的钥匙。
