1. 从一条报错说起为什么我要啃 opencode 的源码第一次接触 opencode 的人大概率不是被它的功能吸引而是被一条报错拦住error from provider (console): opencodes free tier can only be used from within opencode这句话看着像绕口令实际含义是免费额度只在 opencode 自己的运行环境里生效你拿它的 key 去别的客户端调会被直接拒绝。很多人卡在这一步以为是安装问题反复重装、换 Node 版本、翻文档最后才发现是调用来源校验。我当初也是这么过来的所以决定不再停留在“能用就行”的层面直接把它的工程结构、会话模型和事件机制拆开看一遍。这篇是上篇只聊三件事工程全景、双会话内核、事件溯源。这三个词听起来抽象但它们是理解 opencode 一切行为的底座。搞懂之后你再看它的配置文件、插件机制、模型切换、额度计算都会觉得顺理成章。适合谁看写过 TypeScript、用过 Bun、对 Monorepo 有基本概念并且想从“使用者”进阶到“能改、能调、能排查”的人。如果你只是想装个工具跑起来那opencode安装那部分速查表也够你用但如果你想真正吃透它往下读。opencode 是一个用 TypeScript 写的智能体框架运行在 Bun 上代码组织成 Monorepo。这三个技术选型不是随便定的后面我会逐个解释它们各自解决了什么问题以及为什么换成别的方案会难受。先把结论放前面Bun 负责启动速度和内置工具链TypeScript 负责类型安全和跨包契约Monorepo 负责把 CLI、核心内核、插件、SDK 拆成可独立演进的单元。理解了这三点你就理解了 opencode 的“骨架”。2. 工程全景Monorepo 里到底装了什么2.1 为什么是 Monorepo而不是一个大包很多人第一次 clone opencode 会懵根目录下packages/里一堆子包每个都有自己的package.json。为什么不干脆写成一个包因为 opencode 的边界天然就是分裂的。CLI 层负责参数解析、终端交互、进程管理它不该关心模型怎么调。核心内核会话管理、事件总线、工具调度这是最重的一块。Provider 适配层对接不同模型服务每家的鉴权、流式协议、错误码都不一样。插件/SDK 层给外部扩展用的稳定接口不能跟着内核天天变。如果全塞一个包里改一个 provider 的错误处理可能连带把 CLI 的构建产物也重新打一遍测试范围失控。Monorepo 的价值就在这每个包有独立的版本、独立的测试、独立的发布节奏但共享一套 TypeScript 配置和构建脚本。这就是typescript types文件夹的声明文件 如何使用这类问题在 opencode 里特别常见的原因——跨包引用全靠类型声明文件撑着。2.2 目录结构与职责划分我按自己的理解把核心目录梳理成一张表你对照着看会清晰很多目录/包核心职责改动频率依赖方向packages/cli命令入口、终端 UI、进程生命周期中依赖内核packages/core会话、事件、工具调度高被所有包依赖packages/provider-*各模型服务适配中依赖 core 的接口packages/sdk对外稳定 API低依赖 corepackages/plugin-*官方插件示例低依赖 sdk这张表最关键的一列是“依赖方向”。core 永远不反向依赖 cli 或 provider这是保证内核可测试的前提。你在读源码时如果发现某个 provider 的逻辑渗进了 core那基本可以判定是设计走味了。2.3 Bun 在这里扮演的角色opencode安装之所以比很多同类工具简单很大程度是因为 Bun。Bun 同时是运行时、包管理器、打包器、测试 runner。这意味着不需要ts-node或tsx做 TS 转译Bun 直接跑.ts。不需要单独装 Jest/Vitestbun test内置。不需要 esbuild/rollup 配一堆bun build直接出产物。我实测过同样的 Monorepo用 Node pnpm tsc vitest 的组合冷启动跑测试要十几秒换成 Bun两三秒就起来了。对于 opencode 这种需要频繁跑集成测试的项目这个差距是实打实的效率。但要注意一个坑Bun 的某些 Node API 兼容层还在补齐如果你在插件里用了冷门的node:模块可能在 Bun 下行为和 Node 不一致。我的建议是插件里尽量用 Web 标准 APIfetch、ReadableStream、AbortController少碰 Node 私有 API。2.4 TypeScript 类型声明文件的正确用法热词里反复出现typescript 类型声明文件(.d.ts) 怎样编写这在 opencode 的 Monorepo 里是个高频痛点。跨包引用时你有两种做法源码直引import { Session } from opencode/core靠tsconfig的paths映射到源码。声明文件core 构建时产出.d.ts其他包引用声明。opencode 走的是第一种为主、第二种为辅。开发时用paths直连源码享受即时类型反馈发布时产出.d.ts给外部消费者。这里有个容易踩的坑paths映射和package.json的exports字段必须保持一致否则会出现“本地能编译、发布后找不到类型”的诡异问题。我排查过一次就是因为exports里漏了一个子路径导致 SDK 用户拿不到类型提示。{ exports: { .: { types: ./dist/index.d.ts, import: ./dist/index.js }, ./session: { types: ./dist/session.d.ts, import: ./dist/session.js } } }提示每次新增子路径导出务必同步更新exports和tsconfig的paths两边不一致是 Monorepo 里最隐蔽的 bug 来源之一。3. 双会话内核一个被低估的设计3.1 什么是“双会话”opencode 的会话模型不是单一的。它同时维护两类会话交互会话interactive session和执行会话execution session。名字是我根据行为起的方便理解。交互会话面向用户负责接收输入、渲染输出、维护对话历史。它的生命周期长可能横跨几十分钟甚至几小时。执行会话面向工具调用和模型请求每次任务派发时创建任务结束就销毁。它的生命周期短通常几秒到几分钟。为什么要拆成两个因为它们的关注点完全不同。交互会话关心“用户看到什么”执行会话关心“这次调用成不成功”。如果混在一起会出现两个问题一是长会话里累积的上下文会污染单次执行的判断二是执行失败时很难干净地回滚因为状态和用户历史缠在一起。3.2 双会话如何协作我用一个生活类比交互会话像“前台接待”执行会话像“后台工单”。你到前台说“帮我查下这个文件”前台记录你的需求生成一张工单丢给后台后台干完活把结果交回前台前台再展示给你。前台不关心后台用了什么工具、调了哪个模型后台也不关心前台怎么排版。具体到代码层面交互会话持有一个sessionId执行会话持有executionId两者通过事件关联。一次用户输入可能触发多个执行会话比如并行调多个工具但最终都汇聚回同一个交互会话。这种一对多的关系是 opencode 能支持复杂任务编排的基础。3.3 会话状态机的关键状态执行会话的状态流转是排查问题的核心。我整理成表状态含义可转移至常见触发pending已创建未开始running,cancelled排队等待running正在执行completed,failed,cancelled模型请求中completed正常结束终态收到完整响应failed异常结束终态网络/鉴权/解析错误cancelled主动取消终态用户中断或超时这张表的价值在于当你看到error from provider时先确认执行会话处于哪个状态。如果是failed看错误码如果是cancelled看是谁触发的取消。很多人一看到报错就慌其实先定位状态排查范围立刻缩小一半。3.4 为什么不用单会话加锁有人会问单会话加个互斥锁不就行了我试过这种思路在小规模下能跑但一旦涉及并行工具调用就崩。因为锁的粒度很难把握锁太粗并行变串行性能掉一半锁太细状态竞争防不住。双会话本质上是用结构隔离替代锁竞争把并发问题在架构层面消解掉而不是靠运行时同步。这是我认为 opencode 设计里最聪明的一处。3.5 会话与额度的关系回到开头那条报错。免费额度的校验发生在执行会话创建阶段而不是交互会话。也就是说校验的是“这次执行从哪来”而不是“你是谁”。这解释了为什么opencodes free tier can only be used from within opencode——它检查的是调用来源的上下文标识这个标识只在 opencode 自己的执行会话里才会被注入。你换个客户端执行会话不是它创建的标识缺失自然被拒。理解这一点你就不会再纠结“为什么我 key 是对的却用不了”。4. 事件溯源opencode 的记忆机制4.1 事件溯源到底解决了什么传统做法是“存最终状态”会话表里存当前对话内容工具表里存执行结果。问题是一旦状态出错你只能看到“现在是什么样”看不到“怎么变成这样的”。事件溯源反过来不存状态只存导致状态变化的事件。当前状态由事件序列重放得出。opencode 用这套机制好处有三个可回放任何一次会话都能从头重放复现 bug 变得可行。可审计每个事件带时间戳和来源谁在什么时候做了什么一目了然。可扩展新增一种事件类型不影响已有逻辑老事件照常重放。4.2 事件的结构一个典型事件长这样我按常见实践补全了字段interface OpencodeEvent { id: string; // 事件唯一标识 type: string; // 事件类型如 session.created sessionId: string; // 所属交互会话 executionId?: string; // 所属执行会话可选 timestamp: number; // 发生时间 payload: unknown; // 事件负载类型由 type 决定 version: number; // 事件版本用于兼容旧事件 }version字段容易被忽略但它是长期演进的关键。当事件结构变化时靠版本号做迁移而不是直接改老事件。我在实际项目里踩过坑早期没加版本号后来改字段导致历史事件全部解析失败只能写一次性迁移脚本很痛苦。4.3 事件类型的分层opencode 的事件大致分三层会话层session.created、session.updated、session.closed执行层execution.started、execution.completed、execution.failed工具层tool.invoked、tool.result、tool.error分层的好处是订阅者可以按需监听。比如你只想做日志订阅会话层就够想做性能分析订阅执行层想调试工具订阅工具层。这种“按层订阅”比“一个大事件总线全收”要清晰得多。4.4 重放与快照的平衡纯事件溯源有个致命问题事件多了之后重放一次要很久。opencode 的解法是定期打快照。每 N 个事件或每隔一段时间把当前状态序列化存一份重放时从最近的快照开始而不是从第一个事件开始。这里有个参数要调快照间隔。太短存储涨得快太长重放慢。我的经验值是每 100 到 200 个事件打一次快照具体看事件产生速率。如果一次会话动辄上千事件就取小一点如果会话很短取大一点甚至不打。4.5 事件溯源与调试实战我最喜欢事件溯源的一点是排查问题时可以“时间旅行”。比如用户反馈“第三步结果不对”我可以把事件序列拉到第三步之前逐步重放看是哪一步的 payload 出了问题。这比在代码里打断点高效得多因为断点只能看当前事件能看历史。具体操作上我会先把某次会话的事件导出成 JSON然后用脚本过滤出关键类型# 假设事件已导出为 events.json cat events.json | jq .[] | select(.type | startswith(execution))这样能快速定位执行层的异常。如果发现某个execution.failed的 payload 里有 provider 错误码再顺着executionId找对应的工具事件链路就清楚了。5. 实操从安装到跑通第一条链路5.1 安装与环境准备opencode安装在不同系统上略有差异。Ubuntu 下我一般这么走# 确认 Bun 已安装 bun --version # 全局安装 opencode bun install -g opencode # 验证 opencode --version如果bun没装先装 Bun。这里有个细节Bun 的安装脚本会改 shell 配置装完记得source一下或者重开终端否则opencode命令找不到。我见过不少人卡在这以为是安装失败其实是 PATH 没刷新。5.2 与 VSCode 的配合热词里vscode怎么和opencode工作问得很多。opencode 本身是 CLI 工具和 VSCode 的配合主要靠终端集成。我的做法是在 VSCode 里开集成终端直接跑opencode。把常用命令配成 VSCode task一键触发。如果需要看事件流开第二个终端跑日志监听。不建议一上来就折腾深度集成插件先把 CLI 用顺再考虑编辑器层面的优化。顺序反了容易本末倒置。5.3 跑通第一条执行链路安装完跑一个最小任务验证链路opencode run 列出当前目录的文件这条命令会触发交互会话创建 → 执行会话创建 → 工具调用列目录→ 结果回传 → 交互会话渲染。如果中间任何一环断了你会看到对应的错误。第一次跑通这条链路比读十遍文档都有用因为它把双会话和事件流都串起来了。5.4 观察事件流想直观看到事件可以开调试模式具体开关以实际版本为准常见做法是设环境变量OPENCODE_DEBUG1 opencode run 列出当前目录的文件你会看到一串事件按时间顺序打印。对照第 4 节的事件分层你能清楚看到会话层、执行层、工具层各自的事件。这一步做完你对“事件溯源”就不再是抽象概念而是亲眼见过的东西。6. 常见问题与排查技巧实录6.1 免费额度报错怎么定位回到那条最烦人的报错。排查顺序我总结成表现象可能原因排查动作free tier can only be used from within opencode调用来源非 opencode 执行会话确认是否用官方 CLI 发起额度突然归零多模型分开计额度查各模型用量明细换模型后报鉴权错provider 配置未同步检查 provider 适配层配置opencode go 套餐是每种模型分开计算额度吗这个问题从双会话设计看额度校验发生在执行会话创建时而执行会话是绑定具体模型的所以大概率是按模型分开算。具体以官方说明为准但理解机制后你至少知道该去哪查。6.2 类型报错排查Monorepo 里最常见的类型报错是“找不到模块声明”。排查三步确认tsconfig的paths指向正确。确认目标包的exports字段包含该子路径。确认目标包已构建如果走声明文件模式。三步走完还不行就bun install重装依赖清掉可能的缓存。6.3 事件重放对不上如果重放结果和实际不符先查快照。快照和事件序列不一致是重放错乱的头号原因。检查快照生成的时间点是否在事件写入之后顺序反了就会丢事件。6.4 实操心得三条先跑通再优化别一上来就研究插件机制先把 CLI 跑顺。事件日志常开调试期把事件日志留着出问题能回溯。类型声明同步改改exports必改paths养成肌肉记忆。7. 双会话与事件溯源如何支撑扩展理解了双会话和事件溯源你再看 opencode 的扩展能力就通透了。插件本质上是在事件总线上挂监听器工具执行前监听tool.invoked做参数校验执行后监听tool.result做结果加工。因为事件是分层的插件可以只订阅自己关心的层不会干扰其他逻辑。oh my opencode如何安装这类扩展走的也是同一套机制。它不修改内核而是通过 SDK 注册事件处理器。这种“内核稳定、扩展外挂”的模式是 opencode 能持续演进又不失控的关键。你如果打算自己写扩展记住一条永远通过事件和 SDK 交互不要直接改 core 的内部状态。前者是契约后者是耦合。至于opencode 与 deepseek hermes 哪个好这种对比我的看法是选型看的是你的使用场景和扩展需求而不是单纯比功能列表。opencode 的优势在于工程结构清晰、事件机制完善适合想深度定制的人如果你只是要个开箱即用的对话工具那可能不需要这么重的架构。工具没有绝对好坏匹配需求才是关键。下篇我会接着聊 provider 适配层的细节、流式响应的处理以及插件开发的具体步骤。这篇先把骨架立住骨架稳了后面填肉才不会塌。