企业官网建设流程全解析

1. 从一条报错信息说起：为什么要拆解 opencode 的工程结构

第一次接触 opencode 的人，大概率不是被它的功能吸引，而是被一条报错拦住：

error from provider (console): opencode's free tier can only be used from within opencode

这句话信息量其实很大。它说明 opencode 不只是一个命令行工具，它内部有一套"调用来源校验"机制——免费额度只在它自己的运行环境里生效，一旦你试图从外部脚本、第三方客户端或者别的入口去蹭这个额度，就会被拦下来。很多人第一反应是"这怎么绕过"，但真正值得琢磨的是：它凭什么知道请求是从哪来的？这个校验逻辑藏在工程的哪一层？

这就是我决定把 opencode 的源码结构完整拆一遍的起点。它不是一个简单的 CLI 包装器，而是一个用 TypeScript 写、跑在 Bun 运行时上、以 Monorepo 组织、内核采用"双会话 + 事件溯源"设计的完整工程。这几个关键词——TypeScript、Bun、Monorepo、事件溯源——不是堆砌的标签，它们每一个都直接决定了这个项目的能力边界和扩展方式。

这篇是上篇，只做一件事：把工程全景和内核机制讲透。具体包括目录怎么分层、包之间怎么依赖、为什么选 Bun 而不是 Node、双会话到底指哪两个会话、事件溯源在这个场景里解决了什么真实问题。下篇再讲插件、Provider 适配、配置体系和实际使用中的坑。

适合谁看：正在用 opencode 想搞明白它内部怎么跑的人；想拿它当 TypeScript 大型 Monorepo 学习样本的人；以及准备基于它做二次开发、写插件或者接自定义模型的人。如果你只是想装完就用，这篇可能偏重，但看完你对它的行为会少很多"玄学"困惑。

先说结论性的判断：opencode 的架构选择不是炫技，每一个决定背后都有明确的工程动机。Bun 是为了启动速度和内置工具链，Monorepo 是为了把 CLI、内核、Provider、插件拆成可独立演进的单元，事件溯源是为了让会话状态可回放、可审计、可恢复。理解了这三层动机，后面所有细节都能对上号。

2. Monorepo 的目录分层：每个包到底负责什么

2.1 顶层结构不是随便分的

opencode 用 Monorepo 组织代码，这一点从它的依赖管理方式就能看出来——根目录一份统一的依赖声明，各个子包通过 workspace 协议互相引用。这种结构在 TypeScript 项目里越来越常见，但 opencode 的分包粒度值得单独说。

典型的顶层会分成这么几类目录：packages/放核心包，apps/或者等价的目录放可执行入口，根级放共享的 tsconfig、构建脚本和 workspace 配置。关键在于packages/下面怎么切。opencode 的切法是按"职责边界"而不是按"技术层次"——也就是说，它不会搞一个utils包把所有工具函数塞进去，而是让每个包对应一个明确的领域概念。

我见过的很多 Monorepo 失败案例，都是因为分包按技术分层（controller、service、model 各一个包），结果改一个功能要横跨四五个包，依赖图变成一团乱麻。opencode 避开了这个坑，它的包边界基本和运行时概念对齐：会话是一个包，Provider 抽象是一个包，事件系统是一个包，CLI 是一个包。这样改会话逻辑就只动会话包，不会牵连一片。

2.2 核心包之间的依赖方向

依赖方向是判断一个 Monorepo 设计好坏的核心指标。opencode 的依赖大致是单向的：底层是类型定义和事件内核，中间是会话管理和 Provider 抽象，上层是 CLI 和具体 Provider 实现。

这里有个细节值得注意：类型定义往往被单独抽成一个包。这跟热词里"typescript types 文件夹的声明文件如何使用"是同一个问题域。把类型独立出来，好处是上层包可以只依赖类型而不依赖实现，编译时不会把实现代码拖进来，构建产物体积和编译速度都能受益。你在读源码时会发现，很多跨包引用其实只引了类型，运行时依赖是零。

Provider 抽象层的位置也很讲究。它夹在会话内核和具体模型实现之间，向上暴露统一的调用接口，向下屏蔽不同模型服务的差异。这样会话内核完全不需要知道底层接的是哪家模型，换 Provider 不影响内核逻辑。这个分层直接解释了为什么 opencode 能同时支持多种模型来源——不是靠 if-else 堆出来的，是靠抽象层隔离出来的。

2.3 为什么不用单一包

有人会问，一个 CLI 工具搞这么复杂的 Monorepo 是不是过度设计。我的判断是：如果它只做一件事、只有一个入口，那确实没必要。但 opencode 的定位是"可扩展的编码代理运行时"，它要同时支撑 CLI 使用、插件扩展、多 Provider 接入、以及被其他程序调用。这些场景对包的独立性要求完全不同。

举个具体的：插件开发者只需要依赖插件接口包和类型包，不需要把整个 CLI 和所有 Provider 实现拉下来。如果所有代码在一个包里，插件开发者的依赖树会爆炸。Monorepo 分包让"按需依赖"成为可能，这是可扩展性的物理基础。

另外从构建角度，分包之后可以做到增量构建——只改了一个包，只重新构建受影响的包和它的下游。在 TypeScript 项目里，配合 project references，这个收益在大型项目上非常明显。opencode 的规模还没到"构建要几分钟"的程度，但设计上留了这个余地。

3. 为什么是 Bun：运行时选择背后的真实权衡

3.1 启动速度对 CLI 工具意味着什么

CLI 工具和常驻服务对运行时的要求完全不同。服务可以接受几百毫秒的冷启动，因为只启动一次；但 CLI 每次执行都要冷启动，用户对"敲完命令到看见输出"的延迟极其敏感。超过 300 毫秒就会觉得卡，超过 1 秒就会怀疑是不是卡死了。

Node 的冷启动在大型 TypeScript 项目上一直是个痛点，尤其是要加载大量模块的时候。Bun 用 JavaScriptCore 引擎，冷启动明显更快，而且它内置了 TypeScript 转译，不需要额外的构建步骤就能直接跑.ts文件。对 opencode 这种"用户敲命令就要立刻响应"的场景，这个差异是能直接感知的。

3.2 内置工具链省掉了多少胶水

Bun 内置了包管理、打包器、测试运行器、TypeScript 转译。这意味着 opencode 的工程里可以少装一大堆 devDependencies：不需要 ts-node、不需要单独的打包配置、测试可以直接bun test。工具链统一带来的不只是依赖变少，更重要的是配置面变小——少一个工具就少一套配置文件，少一堆版本兼容问题。

我在实际项目里踩过的坑是：Node 生态里 TypeScript 的转译方案有好几套（ts-node、tsx、swc、esbuild），每套的 ESM/CJS 处理、路径别名解析、装饰器支持都不一样，混用的时候经常出诡异问题。Bun 把这些统一了，虽然牺牲了一部分生态兼容性，但对一个自成一体的项目来说，这个交换是划算的。

3.3 代价与边界

选 Bun 不是没有代价。最大的问题是生态兼容性——有些 Node 原生模块在 Bun 上跑不了，有些库依赖 Node 特有的 API 行为。opencode 作为编码代理，需要调用文件系统、执行子进程、处理网络请求，这些 Bun 都原生支持，所以它的核心功能不受影响。但如果某个第三方依赖踩到了 Bun 的兼容性盲区，就得找替代方案或者打补丁。

另一个隐性成本是调试体验。Bun 的调试工具链相比 Node 还不够成熟，遇到深层问题时，可用的排查手段会少一些。这是选型时必须接受的现实：你换来了启动速度和工具链统一，就要接受生态和调试上的不完善。

提示：如果你要基于 opencode 做二次开发，先确认你的目标依赖在 Bun 上能正常跑。特别是涉及原生扩展、特定 Node API 行为的库，提前验证比事后返工省事得多。

4. 双会话内核：两个会话各自解决什么问题

4.1 "双会话"不是两个聊天窗口

看到"双会话"这个词，很多人第一反应是"能同时开两个对话"。不是这个意思。opencode 的双会话指的是内核层面存在两种不同性质的会话：一种是面向用户的交互会话，一种是面向执行的运行时会话。它们生命周期不同、状态结构不同、持久化策略也不同。

交互会话记录的是"用户和代理之间的对话流"——用户说了什么、代理回了什么、中间调用了哪些工具。运行时会话记录的是"这次执行的实际运行状态"——当前在哪个步骤、哪些工具正在执行、产生了哪些中间结果。把这两者分开，是因为它们的变更频率和一致性要求完全不同。

4.2 为什么要拆开

如果只有一个会话对象，会发生什么？用户的每条消息、每次工具调用、每个中间状态都往同一个对象里塞，这个对象会迅速膨胀成一个巨大的、职责混乱的状态容器。更麻烦的是并发问题：用户在对话进行中发新消息，同时后台还有工具在执行，两个写入源操作同一个状态对象，很容易出现状态覆盖或者读到中间态。

拆成两个会话之后，交互会话是"用户可见的、相对稳定的"记录，运行时会话是"高频变化的、内部的"执行状态。两者通过事件关联，而不是共享同一个可变对象。这个设计让并发写入的冲突面大大缩小，也让持久化策略可以差异化——交互会话需要长期保存，运行时会话可能只需要在执行期间存在。

4.3 两个会话如何协同

它们之间的协同靠的是事件。运行时会话在执行过程中产生事件（工具开始、工具结束、产生输出），这些事件被投递到交互会话，转化成用户可见的消息或者状态更新。反过来，用户在交互会话里的输入，会触发运行时会话的创建或推进。

这个模式的好处是解耦彻底。运行时会话不需要知道用户界面长什么样，它只管产生事件；交互会话不需要知道工具怎么执行，它只管消费事件。任何一方内部重构，只要事件契约不变，另一方就不受影响。这也是为什么 opencode 能同时支持 CLI、编辑器插件等多种前端——它们都是交互会话的不同消费者。

4.4 状态一致性怎么保证

双会话带来的直接问题是：两个会话的状态可能不一致。比如运行时会话说工具执行完了，但交互会话还没收到事件，用户看到的就是"卡住了"。opencode 用事件溯源来兜底这个问题——状态不是直接改的，而是通过事件重放推导出来的。只要事件序列完整，任何时刻的状态都可以重建，不一致只是暂时的、可恢复的。

5. 事件溯源：让会话状态可回放、可审计、可恢复

5.1 事件溯源到底在解决什么

事件溯源（Event Sourcing）的核心思想是：不存"当前状态"，而是存"导致状态变化的所有事件"，当前状态由事件序列重放得出。这个概念在金融、审计领域很常见，用在编码代理上，解决的是三个具体问题。

第一是可回放。用户想复现一次执行，不需要重新跑一遍模型调用（那既慢又费钱），只要重放事件序列就能还原当时的完整过程。第二是可审计。每个状态变化都有对应的事件记录，出了问题能精确定位是哪一步、哪个事件导致的。第三是可恢复。进程崩溃后，从最后一个检查点重放事件，就能恢复到崩溃前的状态，不需要从头再来。

5.2 事件的结构设计

一个事件通常包含几部分：事件类型、时间戳、关联的会话 ID、以及事件负载。事件类型决定了这个事件怎么被消费，负载里放的是这次变化的具体数据。设计事件结构时最容易犯的错是把太多东西塞进负载——负载越重，事件越难序列化、越难版本兼容。

opencode 的事件设计遵循"事件要小、要自描述"的原则。每个事件只描述一件已经发生的事，用过去时命名（比如"工具调用完成"而不是"调用工具"）。这个命名习惯很重要，它强制你从"已发生的事实"角度思考，而不是从"要执行的动作"角度，后者容易把命令和事件混为一谈。

5.3 重放机制与检查点

纯事件溯源的问题是：事件越积越多，每次重建状态都要从头重放，性能会越来越差。解决办法是引入检查点（snapshot）——每隔一段时间把当前状态存一份，重建时从最近的检查点开始重放，而不是从第一个事件开始。

opencode 在会话层面做检查点，具体策略要看实现，但思路是通用的：检查点太频繁，存储开销大；太稀疏，重放时间长。合理的做法是按事件数量或者时间间隔触发，同时保证检查点本身的一致性——检查点必须对应一个明确的事件边界，不能存一个"重放到一半"的状态。

5.4 事件溯源带来的工程约束

用了事件溯源，就不能随便改历史事件的结构。因为旧事件已经存下来了，新代码重放旧事件时必须能正确解析。这就要求事件结构向后兼容，或者有明确的版本迁移机制。这是事件溯源最容易被低估的成本——它把"改数据结构"这件本来很自由的事，变成了需要谨慎对待的兼容性问题。

另一个约束是事件必须不可变。事件一旦写入就不能修改，只能追加。这保证了重放结果的确定性。如果有人偷偷改了历史事件，重放出来的状态就和当初不一致了，整个审计和恢复能力就崩了。所以事件存储层通常要做成只追加（append-only）的。

注意：如果你在基于 opencode 做扩展，往事件流里加自定义事件时，一定要考虑版本兼容。今天加的事件，明天可能被新版本代码重放，结构设计要留余地。

6. 从报错信息反推：免费额度校验藏在哪一层

回到开头那条报错。现在有了工程全景和内核机制的知识，可以合理推断这个校验的位置了。

opencode's free tier can only be used from within opencode这句话的关键是"from within opencode"。它要判断的是请求的来源是不是 opencode 自己的运行时。这个判断不可能在 Provider 实现层做，因为 Provider 层只关心"怎么调模型"，不关心"谁在调"。它更可能在会话内核或者请求发起的那一层——也就是运行时会话创建请求的时候，带上某种来源标识，服务端校验这个标识。

从事件溯源的角度看，这个校验甚至可能被记录成一个事件——"请求被拒绝"也是一个已发生的事实，值得记录。这样用户排查问题时，能看到完整的请求生命周期，而不是只看到一个孤立的错误。

这个推断的实际价值是：如果你想搞清楚某个行为为什么被限制，不要盯着报错本身，要去事件流里找对应的记录。事件流是 opencode 的"黑匣子"，大部分行为都能在里面找到痕迹。这也是事件溯源设计给使用者带来的直接好处——可观测性。

7. 读源码时容易卡住的几个点

7.1 类型声明文件的组织方式

热词里反复出现"typescript types 文件夹的声明文件如何使用""typescript 类型声明文件(.d.ts) 怎样编写"，说明很多人在读 opencode 源码时卡在类型上。Monorepo 里的类型组织有个常见模式：每个包有自己的src，类型要么和实现放一起，要么单独抽types目录。

读的时候要注意区分两类文件：.ts是会被编译的实现文件，.d.ts是纯类型声明。在 Monorepo 里，跨包引用类型时，如果包配置了正确的types字段和 project references，编辑器能直接跳转到源码；如果配置不对，就只能看到编译后的声明，跳转体验很差。遇到跳转不了的情况，先检查 tsconfig 的paths和包的exports字段。

7.2 接口继承与静态继承的混淆

"typescript interface 怎么继承""typescript static 继承 重写"这两个热词指向的是 TypeScript 里两个容易混的概念。接口继承（interface A extends B）是类型层面的，只影响类型检查，不产生运行时代码。类的静态继承（class A extends B时静态成员的继承）是运行时层面的，涉及实际的属性查找。

在 opencode 这种大量使用抽象类和接口的工程里，这两者经常同时出现。读代码时如果分不清某个extends是类型继承还是运行时继承，就容易误判行为。判断方法很简单：看extends左边是interface还是class。interface 继承纯类型，class 继承有运行时语义。

7.3 事件流和调用栈不是一回事

新手读事件溯源代码时，容易把事件流当成调用栈来理解。调用栈是同步的、嵌套的、执行完就消失的；事件流是异步的、扁平的、持久化的。一个事件产生后，可能被多个消费者处理，处理顺序不保证和产生顺序一致（除非有明确的排序机制）。

理解这一点很重要，否则你会困惑于"为什么这个事件处理完了那个还没处理"。答案往往是：它们本来就是并行的，事件系统不保证跨消费者的顺序，只保证单个消费者内部的处理顺序（如果实现得当）。

8. 上篇收尾：这套架构给你的实际启发

拆完工程全景和内核，我最大的感受是：opencode 的架构选择都很"务实"。它没有为了架构而架构，每个决定都能对应到一个具体的工程问题——启动慢就换 Bun，状态乱就拆双会话，恢复难就上事件溯源。这种"问题驱动"的设计思路，比任何架构模式都值得学。

如果你在做一个类似的、需要长期演进、需要可扩展、需要可观测的工具，这套组合拳是可以借鉴的。但别照搬——事件溯源有它的成本，双会话有它的复杂度，Bun 有它的生态限制。先想清楚你的项目是不是真的需要这些能力，再决定用不用。

下篇我会讲插件机制、Provider 适配的细节、配置体系怎么组织，以及实际使用中那些文档里不会写的坑。如果你在跟着读源码，建议先把事件流这条线摸清楚，它是理解整个 opencode 行为的钥匙。