企业官网建设流程全解析

1. 从一条报错信息说起：为什么要啃 opencode 的源码

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

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

这句话信息量其实很大。它说明 opencode 不只是一个命令行工具，它内部有一套"调用来源校验"机制——免费额度只在它自己的运行环境里生效，一旦你试图从外部脚本、第三方客户端或者别的编辑器插件去蹭这个额度，就会被拦下来。很多人看到这条报错的第一反应是去搜"opencode 免费额度怎么绕过"，但正确的思路应该是：先搞清楚 opencode 的运行边界在哪里，它凭什么判断"你是不是在 opencode 里面"。

这就是我决定深入读 opencode 源码的起点。它不是一个简单的 CLI 包装器，而是一个用 TypeScript 写的、跑在 Bun 运行时上的 Monorepo 工程，内部有双会话内核、事件溯源机制、provider 抽象层、以及一套相当克制的类型系统设计。关键词里出现的 opencode、TypeScript、Bun、Monorepo、事件溯源，基本就是这篇要拆的全部内容。

这篇是上篇，聚焦三件事：工程全景（它到底由哪些包组成、怎么组织）、双会话内核（为什么一个 AI 编程工具需要两套会话模型）、事件溯源（它的状态是怎么被记录和重放的）。下篇会讲 provider 抽象、免费额度校验、以及和 VSCode 的集成方式。适合谁看？如果你写过 TypeScript、用过 Bun、对 AI 编程工具的架构好奇，或者你正在自己造一个类似的 agent 工具，这篇能帮你少走很多弯路。如果你只是想找 opencode 使用教程，那这篇可能偏硬核，但读完你对它的行为会有一层"可预测"的理解，而不是靠试错。

我读源码的习惯是先不看 README，直接看目录结构和 package.json，因为工程组织方式往往比文档更能暴露作者的意图。opencode 的目录结构第一眼就让我确认了一件事：这不是玩具项目。

2. 工程全景：Monorepo 的包划分与依赖流向

2.1 为什么是 Monorepo，而不是单包

opencode 用 Monorepo 不是跟风。它的核心矛盾在于：同一个内核要同时服务 CLI、TUI、以及编辑器集成三种消费方。如果做成单包，CLI 的依赖会污染编辑器插件，编辑器插件的类型又会反向约束内核。Monorepo 让每个消费方只依赖它真正需要的那部分。

我实测下来，它的包划分大致遵循"内核下沉、消费方上浮"的原则。核心逻辑放在底层包，CLI 和 TUI 只是薄薄的一层壳。这种结构的好处是：当你想给 opencode 写一个新的前端（比如一个 Web UI），你只需要依赖内核包，不用把整个 CLI 拖进来。

判断一个 Monorepo 是否健康，我有个土办法：看依赖图里有没有环。opencode 的依赖流向是单向的——底层包不知道上层包的存在。这一点在 TypeScript 里尤其重要，因为一旦出现循环依赖，类型推断会变得极其脆弱，tsc报的错会指向莫名其妙的位置。

2.2 Bun 作为运行时：选它的真实理由

关键词里有 Bun，很多人会问：为什么不用 Node？我的判断是三个原因叠加。

第一是启动速度。opencode 是一个交互式工具，用户敲下命令到看到界面，中间不能有明显的卡顿。Bun 的冷启动比 Node 快一个量级，这对 CLI 体验是实打实的提升。

第二是内置能力。Bun 自带 TypeScript 转译、包管理、测试运行器、打包器。opencode 这种工程如果跑在 Node 上，需要额外配 tsx、vitest、esbuild 一堆东西，版本兼容性就是一场噩梦。Bun 把这些收敛成一个工具，配置面小了很多。

第三是文件 IO 和子进程。AI 编程工具要频繁读写文件、拉起子进程执行命令，Bun 在这块的 API 设计比 Node 更直接。

但 Bun 不是没有代价。我在实际项目里踩过的坑是：某些 Node 原生模块在 Bun 下行为不一致，尤其是涉及底层系统调用的。opencode 规避这个问题的方式是尽量用纯 JS/TS 实现，减少对原生模块的依赖。这个取舍值得学——如果你打算用 Bun，先把依赖树里带原生扩展的包列出来，逐个验证。

2.3 TypeScript 配置里藏着的工程哲学

opencode 的 tsconfig 有几个细节值得单独拎出来说。

它用了"moduleResolution": "bundler"，而不是传统的node。这个选择意味着它假设代码最终会被打包器处理，而不是直接跑在 Node 的模块解析规则下。配合 Bun 的运行时，这个配置是自洽的。

另一个细节是它对types文件夹的处理。关键词里有人搜"typescript types 文件夹的声明文件 如何使用"，这其实是个高频困惑点。opencode 的做法是：全局类型声明放在独立的 types 目录，通过 tsconfig 的include引入，而不是靠typeRoots自动加载。这样做的好处是显式——你一眼能看出哪些类型是全局注入的，哪些是模块内的。自动加载虽然省事，但排查类型冲突时会让你抓狂，因为你不确定某个全局类型是从哪冒出来的。

提示：如果你在自己的项目里用全局声明文件，建议给每个.d.ts文件加一行注释说明它的用途和注入范围。半年后回来改代码，你会感谢当时的自己。

2.4 构建产物与开发态的双轨

opencode 在开发态和发布态走的是两条路径。开发态直接用 Bun 跑 TypeScript 源码，不做预编译，改完即生效。发布态则打包成单文件或少量文件，减少安装体积。

这个双轨设计的关键在于：源码里不能有依赖构建时替换的逻辑。比如你不能用process.env.NODE_ENV去分支一些核心行为，否则开发态和发布态的行为会不一致，bug 只在发布后出现。opencode 把环境差异收敛到配置加载层，内核逻辑对运行环境是无感的。这是个很成熟的工程习惯，值得抄。

3. 双会话内核：一个工具为什么需要两套会话模型

3.1 先搞清楚"会话"在 AI 编程工具里指什么

在普通聊天工具里，会话就是一段对话历史。但在 AI 编程工具里，会话要复杂得多：它要记录用户说了什么、模型回了什么、模型调用了哪些工具、工具返回了什么、文件被改成了什么样。这些信息不是平铺的，而是有嵌套结构的——一次用户输入可能触发多轮工具调用，每轮工具调用又可能产生子任务。

opencode 的双会话内核，我理解下来是这样分工的：一套负责"对话语义"，一套负责"执行轨迹"。对话语义那套关心的是消息的角色、顺序、上下文窗口怎么裁剪；执行轨迹那套关心的是每一步操作的前置状态、后置状态、以及失败时的回滚点。

为什么要分开？因为它们的生命周期不一样。对话语义需要长期保留（用户可能几天后回来继续），执行轨迹只需要在任务进行期间有效，任务结束就可以归档甚至丢弃。如果混在一套模型里，你会被迫为执行轨迹也做长期存储，成本和复杂度都上去了。

3.2 两套会话如何同步

分开容易，同步难。两套会话模型最大的风险是状态漂移——对话语义认为任务已经完成，但执行轨迹里还有未提交的操作。

opencode 的处理方式是用一个统一的会话 ID 作为锚点，两套模型都挂在同一个 ID 下，但各自维护自己的状态机。对话语义的状态机是"等待输入 → 生成中 → 等待工具 → 完成"，执行轨迹的状态机是"待执行 → 执行中 → 已提交 / 已回滚"。两者通过事件总线通信，而不是直接互相调用。

这个设计的好处是解耦。你可以单独测试执行轨迹的回滚逻辑，不用拉起整个对话流程。我在自己项目里试过直接耦合的写法，结果是每加一个工具就要改对话逻辑，很快就变成一团乱麻。

3.3 会话的持久化格式

opencode 的会话持久化用的是结构化格式，不是简单的 JSON 数组。每条消息带时间戳、角色、以及一个指向执行轨迹的引用。这样做的代价是文件体积变大，收益是可以按时间点重放。

我实测过一个场景：任务执行到一半，模型给出了一个错误的文件修改。如果只有平铺的对话历史，你只能看到"模型说要改这个文件"，看不到"改之前文件是什么样"。有了执行轨迹的引用，你可以精确回滚到修改前。这个能力在调试 agent 行为时是刚需。

注意：持久化格式一旦发布就很难改，因为老会话文件还要能读。opencode 在格式里留了版本号字段，这是必须的。你自己设计类似系统时，第一版就要把版本号加上，别等出问题再加。

3.4 上下文窗口裁剪与会话模型的关系

AI 编程工具绕不开上下文窗口限制。opencode 的裁剪策略和它的双会话模型是绑定的：裁剪只作用于对话语义层，执行轨迹层不参与裁剪。

这个决策很关键。因为执行轨迹是结构化的、可压缩的，它可以用摘要形式保留关键信息，不需要占用宝贵的 token。而对话语义层是自然语言，压缩会丢信息，所以只能按策略裁剪。

具体裁剪时，opencode 优先保留最近的消息和系统提示，中间的历史按重要性打分。打分依据包括：是否包含工具调用结果、是否被后续消息引用、是否是用户显式输入。这套打分逻辑不是拍脑袋，而是从实际使用数据里调出来的。如果你自己实现，建议先做一个简单版本（比如只保留最近 N 轮），跑一段时间收集数据后再优化。

4. 事件溯源：状态是怎么被记录和重放的

4.1 事件溯源不是"记日志"

很多人把事件溯源理解成"把操作记下来"，这是误解。事件溯源的核心是：状态不是被存储的，而是被事件重放出来的。当前状态 = 初始状态 + 所有事件的依次应用。

opencode 用事件溯源，我判断是为了解决三个问题：可审计、可回滚、可重放。可审计是说每一步操作都有据可查；可回滚是说能回到任意历史点；可重放是说同样的输入能复现同样的输出，这对调试 agent 至关重要。

代价也很明显：读状态要重放所有事件，性能会随事件数量增长。opencode 的缓解方式是定期做快照，快照之后的事件才需要重放。快照的时机选择是个权衡——太频繁浪费存储，太稀疏重放慢。

4.2 事件的数据结构设计

opencode 的事件结构大致包含：事件 ID、类型、时间戳、载荷、以及一个指向前置事件的引用。前置引用形成链式结构，这让事件可以分支——同一个前置事件可以有多个后续事件，对应不同的执行路径。

这个分支能力在实际使用中很有用。比如模型生成了两个候选方案，你可以把两个方案都作为事件记录下来，用户选择其中一个后，另一个分支就标记为废弃。如果不用事件溯源，你得自己维护一套"候选方案"的数据结构，很容易和主流程脱节。

事件类型的设计上，opencode 走的是"少而通用"的路线，而不是"多而具体"。比如它不会为"读取文件"和"写入文件"分别定义事件类型，而是定义一个通用的"工具调用"事件，具体是读还是写放在载荷里。这样做的好处是新增工具时不用改事件类型定义，坏处是类型收窄要靠载荷的判别字段。TypeScript 里可以用可辨识联合（discriminated union）来处理，这也是关键词里"typescript interface 怎么继承"这类问题的实际应用场景。

4.3 重放时的幂等性保证

事件溯源最怕的是重放产生副作用。如果重放"写入文件"事件时真的又写了一次文件，那就出大问题了。

opencode 的做法是把事件分成两类：纯事件和副作用事件。纯事件重放时只更新内存状态，不碰外部世界；副作用事件重放时只读取记录的结果，不重新执行。这个区分必须在事件定义时就确定，不能运行时判断。

我在自己项目里踩过的坑是：一开始没区分，重放时真的重新调了 API，结果账单翻倍。后来改成"副作用事件记录结果，重放时直接读结果"，问题才解决。这个教训很贵，希望你别重复。

4.4 事件存储的选型考量

opencode 的事件存储用的是文件系统，不是数据库。这个选择初看很朴素，但仔细想是合理的：AI 编程工具的事件量不大，单机场景下文件系统足够，而且文件系统天然支持用户直接查看和备份。

用数据库的话，你得处理连接管理、迁移、并发写入，对一个本地工具来说是过度设计。文件系统的问题是并发写入需要加锁，opencode 通过单进程模型规避了这个问题——同一时间只有一个进程在写事件。

如果你要做的工具是多进程的，那文件系统就不够了，得考虑 SQLite 或者嵌入式 KV 存储。选型的关键是看你的并发模型，而不是看哪个技术更"高级"。

5. 类型系统在 opencode 里的实际用法

5.1 声明文件的组织方式

回到关键词里那个高频问题："typescript types 文件夹的声明文件如何使用"。opencode 的实践是：声明文件按领域分目录，每个目录一个 index.d.ts 做聚合导出。

比如 provider 相关的类型放一个目录，session 相关的放另一个。这样做的原因是，声明文件如果全堆在一个目录，随着项目变大，找类型会变成体力活。按领域分目录后，你根据功能就能定位到类型定义。

另一个细节是，opencode 尽量避免在声明文件里写实现逻辑。声明文件只描述形状，不描述行为。行为放在实现文件里。这个边界如果模糊了，类型和实现会互相纠缠，改一处动全身。

5.2 类型继承与重写的处理

关键词里有"typescript static 继承 重写"和"typescript interface 怎么继承"，这两个问题在 opencode 里都有实际对应。

interface 继承方面，opencode 用接口组合而不是深层继承。比如一个"工具"接口，基础部分定义通用字段，具体工具通过交叉类型（intersection）扩展，而不是 extends 一个基类。这样做的好处是避免继承链过深，类型推断更快，报错也更清晰。

static 继承重写方面，opencode 用得比较克制。静态成员在 TypeScript 里的继承行为容易让人困惑，尤其是静态方法里访问 this 时，this 指向的是调用方而不是定义方。opencode 的规避方式是尽量用工厂函数代替静态方法，把"创建实例"的逻辑显式化。

提示：如果你在 TypeScript 里大量用静态方法做工厂，建议改成独立的工厂函数。静态方法的 this 绑定问题在重构时是个隐形炸弹。

5.3 类型收窄在事件处理中的应用

事件处理是类型收窄的典型场景。一个事件载荷可能是多种形状，处理时要先判别再访问字段。

opencode 用的是可辨识联合：每个事件载荷带一个type字段，处理函数用 switch 判别。TypeScript 能根据 switch 的分支自动收窄类型，不需要手动断言。这个模式看起来简单，但要求每个载荷的type字段是字面量类型，不能是宽泛的 string。

我见过很多项目在这里偷懒，把 type 定义成 string，结果类型收窄失效，到处要写 as。这是自找麻烦。字面量类型多写几个字符，换来的是整个处理链路的类型安全。

5.4 类型与运行时的边界

TypeScript 的类型在运行时是不存在的。opencode 在需要运行时校验的地方（比如读取用户配置、解析外部输入），用的是 schema 校验库，而不是靠类型断言。

这个边界必须清楚：类型只保证编译期正确，运行时数据必须单独校验。很多 bug 的来源就是开发者以为类型对了运行时就不会错，结果外部输入不符合预期，程序在运行时崩了。opencode 在配置加载和事件反序列化这两个入口都做了运行时校验，这是必须的。

6. 从源码里能学到的工程习惯

6.1 依赖注入而不是全局单例

opencode 的内核组件基本都通过构造函数注入依赖，而不是用全局单例。这样做的好处是测试时可以替换依赖，不用 mock 全局对象。

全局单例在小型项目里很爽，但一旦要写测试就痛苦。你没法给同一个测试文件里的两个用例配置不同的依赖，因为它们共享同一个单例。依赖注入虽然写起来多几行，但换来的是可测试性。

6.2 错误处理的分层

opencode 的错误处理分三层：底层抛原始错误，中间层包装成领域错误，顶层决定是展示给用户还是记录日志。

这个分层的价值在于：底层不关心错误怎么展示，顶层不关心错误从哪来。中间层做翻译。如果只有一层，你要么在底层写展示逻辑（耦合），要么在顶层处理原始错误（信息不足）。

我在实际项目里见过把错误直接抛到顶层的写法，结果是用户看到一堆堆栈信息，完全不知道发生了什么。分层处理虽然多写代码，但用户体验天差地别。

6.3 配置的加载顺序

opencode 的配置加载有明确的优先级：命令行参数 > 项目配置 > 用户配置 > 默认值。这个顺序不能乱，否则用户会遇到"我明明改了配置为什么不生效"的问题。

实现上，它用的是逐层合并，而不是覆盖。合并意味着高优先级的配置只覆盖它显式设置的字段，其他字段继承低优先级。这个细节很重要，如果做成整体覆盖，用户只改一个字段就会丢掉其他所有配置。

6.4 日志的粒度控制

opencode 的日志分级做得比较细，而且支持按模块开启。调试 provider 问题时只开 provider 的日志，不会被其他模块的日志淹没。

这个能力在排查线上问题时是救命的。如果所有日志混在一起，你得用 grep 一层层过滤，效率极低。按模块分级后，直接开对应模块的 debug 级别就行。

实现上，它用的是带命名空间的 logger，每个模块创建自己的 logger 实例。这个模式在 Node 生态里很常见，Bun 下也能用。如果你还没用，建议尽早引入，越晚改造成本越高。

7. 上篇收尾：几个我踩过的坑

读源码的过程中，我自己动手复现了几个关键模块，踩了一些坑，分享出来。

第一个坑是低估了 Bun 和 Node 的差异。我一开始直接把 Node 项目的代码搬过来跑，结果某些依赖的解析路径不对。后来发现是 Bun 的模块解析规则和 Node 有细微差别，尤其是涉及 package.json 的 exports 字段时。解决办法是显式声明依赖的入口，不依赖自动解析。

第二个坑是事件溯源的重放性能。我一开始没做快照，事件积累到几千条后，每次读状态都要重放，明显卡顿。加上快照后流畅了。快照的间隔我设的是每 100 个事件一次，实测下来是个不错的平衡点。

第三个坑是类型收窄的边界。我在一个 switch 里忘了处理 default 分支，TypeScript 没报错，但运行时遇到了未预期的事件类型，直接崩了。后来加了 exhaustive check，用 never 类型强制编译器检查所有分支都处理了。这个技巧强烈推荐，能挡掉很多运行时错误。

opencode 的工程全景、双会话内核、事件溯源这三块，是理解它行为的基础。下篇我会讲 provider 抽象层怎么设计、免费额度的校验逻辑在哪里、以及它和 VSCode 的集成方式。如果你在跟着读源码，建议先把事件溯源这块吃透，因为后面所有功能都建立在它之上。