企业官网建设流程全解析

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

第一次接触 opencode 的人，大概率不是被它的功能吸引，而是被一条报错拦住去路：error from provider (console): opencode's free tier can only be used from within opencode。这句话乍看莫名其妙——我明明就在 opencode 里用它，为什么还说"只能在 opencode 内使用"？要回答这个问题，光看文档没用，必须把它的工程结构、会话模型和事件机制拆开看。

opencode 是一个用 TypeScript 写的终端 AI 编程助手，运行在 Bun 之上，整个仓库采用 Monorepo 组织。它和市面上大多数"套壳 CLI"最大的区别在于：它把会话状态和事件流当成一等公民来设计，而不是简单地把用户输入拼成 prompt 丢给模型。这个设计选择直接决定了它的能力上限，也决定了你在使用中遇到的各种"奇怪行为"到底从哪来。

这篇是上篇，聚焦三件事：工程全景（代码怎么组织的）、双会话内核（为什么有两套会话）、事件溯源（状态是怎么被推导出来的）。适合两类人：一类是想基于 opencode 做二次开发或集成的工程师，另一类是单纯好奇"一个现代 AI CLI 内部到底长什么样"的开发者。读完之后，你再看那些报错和配置项，会有一种"原来如此"的通透感。

需要提前说明的是，opencode 迭代很快，本文涉及的目录结构和模块划分基于我实际阅读的版本，具体文件名可能随版本变化，但设计思路和分层逻辑是稳定的，这才是真正值得带走的东西。

2. Monorepo 的目录分层：每个包到底在解决什么问题

2.1 为什么是 Monorepo 而不是单包

很多人第一反应是：一个 CLI 工具，搞 Monorepo 是不是过度设计？我一开始也这么想，直到看到它同时要支撑终端 TUI、VSCode 插件、以及被其他程序调用的 SDK 三种形态。如果做成单包，TUI 的依赖（比如终端渲染库）会污染 SDK 使用者的依赖树，VSCode 插件又需要一套完全不同的构建产物。Monorepo 在这里不是为了"显得专业"，而是物理隔离不同消费场景的依赖边界。

具体来说，核心逻辑必须和展示层彻底解耦。终端渲染、VSCode 的 Webview、未来的 Web 端，都只是核心逻辑的不同"外壳"。这个判断一旦成立，目录结构就顺理成章了。

2.2 典型的分包职责

我把实际读到的包按职责归成几类，这样比死记目录名有用得多：

这里有个很值得学的点：类型包被单独抽出来。在 Monorepo 里，如果类型定义散落在各个包中，很容易出现循环依赖——A 包定义的类型被 B 包引用，B 包又反过来引用 A 包。把共享类型集中到一个零运行时依赖的包里，循环依赖问题从根上消失了。这也是为什么你在热词里会看到"typescript types 文件夹的声明文件如何使用"这类问题，本质是同一类工程困扰。

2.3 Bun 作为运行时带来的实际差异

选 Bun 不只是"图快"。在 opencode 这种场景下，Bun 带来三个实打实的好处：一是原生 TypeScript 执行，省掉了 tsc 编译等待，改一行代码立刻能跑；二是内置的打包器和测试运行器，Monorepo 里跨包引用不需要复杂的构建编排；三是启动速度，CLI 工具对冷启动极其敏感，用户敲下命令后多等 300ms 都是折磨。

但代价也要说清楚：Bun 的生态兼容性不如 Node 完整，某些 Node 原生模块或依赖特定行为的库可能出问题。我在实际项目里踩过的坑是，某个依赖用了 Node 特有的process.binding之类底层 API，在 Bun 下直接崩。所以选 Bun 之前，先确认你的关键依赖链在 Bun 下能跑通，别等到集成阶段才发现。

提示：Monorepo + Bun 的组合，最容易出问题的地方是 workspace 之间的路径解析。如果某个包在开发时能跑、打包后找不到模块，八成是exports字段或 tsconfig 的paths没对齐，先查这里。

3. 双会话内核：一套系统为什么要维护两种会话

3.1 表面现象：为什么会有"两套会话"

用 opencode 的时候你会发现，它内部似乎同时存在两种会话概念：一种是你在终端里看到的、有来有回的对话；另一种是更底层、更接近"任务执行"的会话。很多人以为这只是命名混乱，其实这是交互会话和执行会话的刻意分离。

交互会话面向人：它关心的是消息顺序、上下文窗口、用户可见的对话历史。执行会话面向任务：它关心的是工具调用链、每一步的输入输出、失败重试。把这两者混在一起，会导致一个致命问题——当模型调用工具失败需要重试时，重试过程会污染用户看到的对话历史，用户会看到一堆莫名其妙的中间状态。

3.2 分离带来的核心收益

分离之后，交互会话只暴露"最终结果"，执行会话记录"完整过程"。这带来几个直接好处：

• 上下文可控：发给模型的上下文只包含交互会话的干净历史，不会被工具调用的中间态撑爆。
• 可重放：执行会话的每一步都是独立事件，出问题时可以精确重放某一步，而不是从头再来。
• 多宿主复用：TUI 和 VSCode 插件共享同一套执行会话，只是交互会话的呈现方式不同。

这解释了为什么 opencode 能同时支持终端和编辑器——因为真正干活的执行层是统一的，UI 只是不同的观察窗口。

3.3 会话状态机的关键状态

执行会话本质上是一个状态机。我梳理下来，核心状态大致是这几个：idle（空闲）、running（执行中）、awaiting_tool（等待工具返回）、awaiting_user（等待用户确认）、completed（完成）、failed（失败）。状态之间的迁移必须由事件驱动，而不是靠代码里到处if判断。

这里有个实操经验：状态迁移一定要有唯一入口。我见过太多项目，状态在十几个地方被直接赋值，最后没人说得清某个状态是怎么来的。opencode 的做法是所有状态变更都通过事件产生，代码里找不到直接改状态的语句。这个约束看起来麻烦，但排查问题时价值巨大——你只要看事件流，就能还原出完整的状态演变。

3.4 会话与 provider 的关系

回到开头那条报错。opencode's free tier can only be used from within opencode这句话的本质是：免费额度绑定在执行会话的上下文上，provider 需要验证请求确实来自 opencode 的执行环境。当你绕过 opencode 直接调用底层接口，或者在某些非标准集成方式下，这个上下文丢失了，于是报错。

理解这一点后，很多"兼容推理"相关的配置问题也就清楚了：所谓兼容，本质是让执行会话能正确地把请求上下文传递给 provider。配置项不是随便填的，每一项都对应会话状态机里的某个环节。

4. 事件溯源：状态不是"存"出来的，是"推"出来的

4.1 事件溯源到底解决了什么

传统做法是：状态变了就更新数据库里的状态字段。事件溯源反过来——只记录发生了什么事件，当前状态由事件序列推导出来。听起来绕，但解决了一个真实痛点：调试。

当用户报告"我的会话卡住了"，传统做法你只能看到"当前状态是 running"，但不知道它为什么卡在 running。事件溯源下，你能看到完整的事件序列：收到用户消息 → 调用模型 → 模型返回工具调用 → 工具执行超时 → 重试 → 重试也超时。卡住的根因一目了然。

4.2 事件的基本结构

一个设计良好的事件至少包含这些字段：事件类型、时间戳、会话 ID、载荷（payload）、以及一个单调递增的序列号。序列号至关重要，它保证了事件的全序关系，让重放成为可能。

interface SessionEvent { id: string; sessionId: string; seq: number; // 单调递增，保证全序 type: EventType; timestamp: number; payload: unknown; }

注意seq和timestamp的区别：时间戳可能因为系统时钟回拨而乱序，seq不会。重放时必须按seq排序，不能按时间戳。

4.3 从事件推导状态的 reducer

状态推导用一个纯函数 reducer 完成：(currentState, event) => nextState。纯函数意味着没有副作用、可测试、可重放。这是整个设计里最优雅的部分——只要事件序列一致，推导出的状态必然一致，与运行环境无关。

function reduce(state: SessionState, event: SessionEvent): SessionState { switch (event.type) { case 'user_message': return { ...state, status: 'running', messages: [...state.messages, event.payload] }; case 'tool_result': return { ...state, status: 'running', toolOutputs: [...state.toolOutputs, event.payload] }; case 'session_completed': return { ...state, status: 'completed' }; default: return state; } }

4.4 事件溯源在实操中的两个坑

第一个坑是事件膨胀。如果每个 token 都记一个事件，事件流会爆炸。正确做法是只记录"有意义的状态变更点"，比如一次完整的模型响应记一个事件，而不是每个字符一个。

第二个坑是快照策略。事件多了之后，每次从零重放会很慢。需要定期生成快照，重放时从最近的快照开始。快照的生成时机很讲究：太频繁浪费存储，太稀疏重放慢。我的经验是按事件数量阈值触发，比如每 1000 个事件打一个快照。

注意：事件一旦写入就不应该修改。如果需要"修正"，只能追加一个补偿事件。这是事件溯源的铁律，破坏它整个模型就失去意义了。

5. 把三块拼起来：一次完整请求的生命周期

5.1 从用户敲下回车到看到回复

把工程结构、双会话、事件溯源串起来看，一次请求的完整链路是这样的：CLI 入口包解析命令 → 创建交互会话 → 交互会话触发执行会话 → 执行会话通过事件总线发出user_message事件 → reducer 更新状态为 running → provider 适配层组装请求（带上执行上下文）→ 调用模型 → 模型返回 → 产生tool_call或assistant_message事件 → 若有工具调用则进入awaiting_tool→ 工具执行 → 产生tool_result事件 → 循环直到session_completed→ 交互会话把最终结果渲染到终端。

这条链路里，provider 适配层是连接内部状态和外部服务的桥梁，也是所有"兼容性"问题的集中地。它负责把内部统一的事件格式翻译成各家 provider 需要的请求格式，再把响应翻译回事件。

5.2 为什么这个架构对二次开发友好

如果你想基于 opencode 做定制，这个架构给了你三个明确的切入点：一是替换 provider 适配层，接入自己的模型服务；二是订阅事件总线，做自己的监控或日志；三是替换 TUI 包，做自己的界面。因为核心逻辑和这些外围是解耦的，你不需要动核心就能实现大部分定制。

5.3 常见集成问题的定位思路

遇到问题时，按这个顺序排查效率最高：先看事件流是否正常产生（确认核心逻辑在跑），再看 provider 适配层是否报错（确认外部调用），最后看 UI 层是否正确渲染（确认展示逻辑）。大部分"看起来是 UI 问题"的故障，根因其实在事件流或适配层。

我在实际排查中总结出一个规律：凡是报错信息里带 provider 字样的，问题基本在适配层或上下文传递；凡是界面卡住不动的，先查事件总线是不是堵了。这个经验帮我省了大量时间。

6. 上篇收尾：几个容易被忽略的工程细节

聊完三大块，补充几个我在阅读和实操中觉得容易被忽略、但很影响体验的细节。

第一，类型包不要放任何运行时逻辑。一旦类型包里出现了函数或常量，它就不再是零依赖的，循环依赖会悄悄回来。保持它纯粹，是维持整个 Monorepo 健康的关键纪律。

第二，事件类型要用可辨识联合（discriminated union）。TypeScript 里用type字段做判别，配合switch能获得完整的类型收窄和穷尽性检查。这比用一堆可选字段的宽接口安全得多，新增事件类型时编译器会提醒你哪里没处理。

第三，会话 ID 的生成要可预测且唯一。我见过用随机数导致碰撞、又难以复现问题的案例。用带前缀的单调 ID 或 UUID v7 这类时间有序的方案，兼顾唯一性和可排序性。

第四，provider 适配层要做超时和重试的兜底。外部服务不可控，适配层必须自己处理超时、限流、重试，不能把这些责任推给上层。重试要区分可重试错误（网络抖动）和不可重试错误（参数错误），无脑重试只会放大问题。

下篇我会接着拆 provider 适配层的具体实现、工具调用协议的设计，以及那些"兼容推理"配置项背后的真实含义。如果你正在基于 opencode 做集成，建议先把这篇里的双会话和事件溯源两块吃透，后面看适配层会轻松很多。