企业官网建设流程全解析

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 版本而不动核心逻辑。

具体来说，我观察到的包划分大致是这样的：

这种划分的好处是依赖方向单一。cli 依赖 core，core 依赖 tools 和 providers，tools 和 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 两条会话如何同步

双会话最大的难点是同步。用户会话和模型会话虽然独立，但在某些时刻必须对齐。比如用户按下 Ctrl+C 中断，两条会话都要进入终止状态；比如工具调用完成，模型会话要继续推理，用户会话要更新界面。

opencode 用的是事件广播 + 各自订阅的模式。核心是一个 EventBus，任何状态变化都先发事件，两条会话各自订阅自己关心的事件类型。这样解耦之后，新增一条会话流（比如日志会话）不需要改动现有代码。

我踩过的一个坑是事件顺序。在异步环境下，事件到达顺序不保证和发出顺序一致。opencode 的解法是给每个事件带一个单调递增的 sequence number，订阅方按序号排序后再处理。这个细节在文档里没写，是我读源码时发现的。如果你自己实现类似架构，这一点务必注意，否则会出现"界面显示工具调用完成、但模型还在等待"的诡异状态。

4. 事件溯源：把后端思想搬进 CLI

4.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 的入口文件很薄，大概只做三件事：解析命令行参数、加载配置、启动核心运行时。我顺着入口读下去，启动流程大致是：

1. 解析 argv，识别子命令（如run、chat、config）
2. 读取配置文件（全局配置 + 项目级配置，后者覆盖前者）
3. 初始化 EventBus 和事件存储
4. 根据配置加载 Provider
5. 注册工具
6. 启动 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): Promise<ToolResult>; }

注册时把工具实例塞进一个 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): AsyncIterable<ChatChunk>; listModels(): Promise<ModelInfo[]>; }

用 AsyncIterable 而不是 Promise 是因为要支持流式响应。模型逐 token 返回时，上层可以边收边渲染，用户体验更好。这个选择在实现上比 Promise 复杂，但值得。

Provider 的注册也是插件式的，配置文件里指定用哪个 Provider，运行时动态加载。这样新增一家模型支持不需要改核心代码。我实测过接入一个自定义 Provider，大概只花了半小时，主要是把请求格式转换写对。

6. 实操：把 opencode 跑起来并读懂启动日志

6.1 环境准备与安装

我用的环境是 Ubuntu 22.04，Bun 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_LEVEL=debug。我建议第一次读源码时开 debug，能看到事件流的完整轨迹。

日志里我关注几个关键点：EventBus 初始化完成、Provider 加载成功、工具注册数量、会话存储路径。这几个信息能帮你确认系统是否正常启动。如果 Provider 加载失败，通常是 API key 没配或网络问题；如果工具注册数量为 0，说明工具层加载有问题。

6.3 用事件流调试会话

最实用的调试技巧是实时看事件流。会话文件是 JSONL，你可以用：

tail -f ~/.opencode/sessions/<session-id>.jsonl | jq

这样每产生一个事件你都能看到。当模型行为不符合预期时，看事件流能快速定位是哪个环节出了问题——是模型没理解指令，还是工具调用参数错了，还是结果解析失败。

我踩过的一个坑是：事件流里看到tool_call但没看到tool_result，排查半天发现是工具执行超时被静默取消了。后来我在工具执行层加了超时日志，这类问题就好定位了。这个经验告诉我，事件溯源系统里，缺失的事件和错误的事件一样重要。

6.4 常见启动问题速查

7. 架构启示：哪些设计值得抄，哪些要绕开

7.1 值得借鉴的三个模式

第一，双会话分离。任何需要同时维护"用户可见状态"和"内部推理状态"的系统，都可以用这个模式。比如客服机器人、游戏 AI、自动化测试工具。分离之后，两边可以独立演进，互不干扰。

第二，事件溯源 + 快照。这个组合适合需要审计、回放、恢复的场景。实现成本比传统状态序列化高，但长期收益大。关键是快照必须可从事件重建，否则就退化成普通的状态存储了。

第三，工具插件化。工具用统一接口 + 注册表管理，新增工具零侵入。这个模式在扩展性上优势明显，尤其适合工具数量会持续增长的场景。

7.2 需要谨慎的两个点

Bun 的生态风险。Bun 快是快，但生态还在追赶 Node。如果你的项目依赖大量原生模块或冷门 npm 包，迁移到 Bun 可能踩坑。建议先在非关键路径上试点，验证兼容性后再全面切换。

事件存储的查询瓶颈。JSONL 适合小规模，但事件量上去之后查询会变慢。如果你的场景需要复杂查询（按时间范围、按类型、聚合统计），早点上 SQLite 或专用事件存储，别等到性能出问题再迁移。

7.3 我自己的实践体会

我在自己的一个内部工具里复用了 opencode 的双会话 + 事件溯源架构，代码量比原来的状态机方案多了大概 30%，但调试时间减少了一半以上。最大的收益是可观测性——任何时候出问题，我都能回放事件流，看到完整的因果链。这种"事后能查清楚"的能力，在复杂系统里比性能优化更值钱。

当然也有代价。事件溯源的心智负担比传统状态管理高，团队新人需要时间理解。我的建议是：如果系统状态简单、不需要审计和回放，别上事件溯源，杀鸡用牛刀。但如果系统状态复杂、出问题难排查，那这个投入是值得的。

下篇我会展开讲工具调用的完整链路、Provider 适配的细节、以及如何接入自定义模型。如果你在跟着读源码，建议先把 core 包的事件总线和会话状态机吃透，那是理解整个系统的钥匙。