1. 从工程全景看一个终端编码助手的骨架第一次接触 opencode 这个项目是在一个终端里敲下启动命令之后。当时我的第一反应是这东西不像一个普通的命令行工具更像一个被塞进终端里的完整应用。它的目录结构、模块划分、状态管理方式都带着明显的工程化痕迹。这篇上篇我想先把它的工程全景、双会话内核和事件溯源这三块讲透因为这三块是理解后续所有功能的地基。opencode 本质上是一个运行在终端里的编码助手。你在终端里跟它对话它能读你的代码、改你的文件、跑你的命令还能在多个会话之间保持上下文。它解决的问题很直接把和 AI 一起写代码这件事从网页聊天框搬到了你真正干活的地方——终端和代码仓库里。适合谁来读如果你是想理解一个现代终端 AI 工具内部怎么设计的开发者或者你自己想做一个类似的东西那这篇内容会对你有用。如果你只是想用那也可以看看知道它内部怎么转的用起来心里更有底。我先把结论摆出来opencode 的工程结构不是随便堆的它的分层非常清晰核心可以拆成入口层、会话层、工具层、存储层四块。而它最有意思的设计是双会话内核和事件溯源这两件事。前者决定了它怎么同时处理你看到的对话和它内部的推理后者决定了它怎么记录、回放、恢复每一次操作。下面我一块一块拆。1.1 为什么终端工具需要工程全景思维很多人做终端工具习惯从一个main.go或者index.js开始把所有逻辑塞进去能跑就行。但 opencode 这类工具不一样它要处理的东西太多了多轮对话、文件读写、命令执行、会话切换、状态持久化、错误恢复。如果不用工程化的方式组织代码会在两周内变成一团乱麻。我自己的经验是凡是涉及状态和多轮交互的工具都必须先想清楚分层。opencode 的分层逻辑我理解下来是这样的入口层负责解析命令行参数、初始化配置、启动终端 UI。这一层不碰业务逻辑只做把用户带进来这件事。会话层这是核心。它管理对话的上下文、消息历史、当前活跃的会话。双会话内核就在这一层。工具层所有具体能力比如读文件、写文件、执行命令、搜索代码都封装成一个个工具。会话层决定什么时候调用哪个工具工具层负责怎么执行。存储层负责把会话、消息、事件持久化到磁盘。事件溯源主要落在这一层。这么分的好处是每一层只关心自己的事。你想换一个终端 UI只动入口层你想加一个新工具只动工具层你想换存储方式只动存储层。层与层之间通过明确的接口通信不会互相污染。提示如果你自己要做类似工具强烈建议先把这四层画出来哪怕只是写在纸上。我见过太多项目因为一开始不分层后期加一个功能要改五个文件。1.2 目录结构里藏着的设计意图opencode 的目录结构我第一眼看的时候觉得有点碎但用久了发现每一块都有明确归属。大致可以分成这么几类命令入口相关处理 CLI 参数、子命令分发。比如opencode直接启动opencode run执行一次性任务这些分发逻辑都在这里。会话与消息相关定义会话结构、消息结构、会话管理器。双会话内核的实现就在这块。工具相关每个工具一个文件或一个目录比如文件读取工具、命令执行工具、代码搜索工具。工具有统一的接口定义。存储相关事件日志的写入、读取、回放。事件溯源的核心逻辑在这里。UI 相关终端渲染、输入处理、状态展示。这一层和业务逻辑解耦得比较干净。这种按职责分目录而不是按技术分目录的做法我觉得是对的。很多项目喜欢按controllers/、services/、models/分结果一个功能要横跨三个目录。opencode 这种分法你找会话相关的东西就进会话目录找工具就进工具目录心智负担小很多。1.3 技术选型背后的取舍opencode 用的是 TypeScript 加 Node.js 这套组合。为什么不是 Go 或者 Rust我推测有几个原因第一终端 UI 的生态。Node.js 这边有比较成熟的终端渲染库做交互式界面省事。第二和 AI 服务对接的 SDK 大多优先支持 JS/TS集成成本低。第三开发迭代速度快类型系统又能兜住大部分低级错误。但 Node.js 也有代价启动速度、内存占用、并发处理都不如编译型语言。opencode 的应对方式是——把重活交给外部命令和工具自己只做编排。比如执行 shell 命令它不自己实现一个 shell而是调用系统 shell读文件不自己搞一套 IO而是用 Node 的 fs。这样它本体保持轻量能力又不受限。这个取舍思路值得学不要用你的主语言去重造所有轮子把边界划清楚让专业的东西干专业的事。2. 双会话内核一个你看到的一个它自己用的双会话内核这个词是我自己总结的因为 opencode 内部确实维护了两套会话状态。理解这一点是理解它所有行为的关键。我先讲现象再讲原理。现象是你在终端里跟 opencode 对话你看到的是一来一回的消息。但实际上它内部同时维护着用户可见的对话会话和系统内部的推理会话。这两者不是一回事。你看到的对话是经过整理、裁剪、格式化的内部推理会话则保留了更原始、更完整的信息包括工具调用的中间结果、失败的尝试、被丢弃的分支。2.1 为什么需要两个会话而不是一个如果只有一个会话会发生什么我试过用单会话的方式做过类似的东西问题很快就来了上下文爆炸工具调用的原始输出往往很长比如读一个大文件、跑一个输出几百行的命令。如果全塞进用户可见的对话里上下文窗口很快就被撑爆。信息污染内部推理过程中会有很多试错比如先尝试一个方案失败了再换一个。这些试错对用户来说是噪音但对系统来说是宝贵的决策依据。展示与存储需求不同用户想看到的是清晰的对话流系统需要的是完整的事件链。两者的数据结构天然不同。所以双会话的本质是把展示层和推理层解耦。用户可见会话负责好看、好读、好理解内部推理会话负责完整、可追溯、可恢复。2.2 两个会话之间怎么同步这是双会话设计里最难的部分。两个会话不能各玩各的必须保持一致性。opencode 的做法我理解是这样的用户发一条消息这条消息先进入用户可见会话同时触发内部推理会话开始工作。内部推理过程中产生的工具调用、中间结果先记录在内部会话里。当推理告一段落系统把值得展示的部分提炼出来追加到用户可见会话。关键在于提炼这一步。不是所有内部事件都往用户会话里塞而是有选择地同步。比如工具调用成功且结果重要 → 同步摘要到用户会话工具调用失败但已重试成功 → 只在内部记录用户会话只显示最终结果需要用户确认的操作 → 必须同步到用户会话等待用户输入这种选择性同步的机制保证了用户看到的对话是干净的同时内部又保留了完整的决策链。注意双会话同步最容易出的 bug 是状态不一致——用户会话显示成功了内部会话其实还在重试或者内部已经完成用户会话没更新。排查这类问题的关键是看事件日志后面讲事件溯源时会细说。2.3 会话的生命周期管理一个会话从创建到销毁经历几个阶段初始化、活跃、空闲、归档或删除。opencode 对每个阶段都有处理。初始化阶段会话会加载配置、恢复历史如果是续接之前的会话、建立内部推理会话的初始状态。活跃阶段就是正常对话两个会话都在更新。空闲阶段是指一段时间没有交互系统可能会做一些压缩或整理把不必要的事件归档。归档阶段则是把会话持久化释放内存。我特别想说的是空闲阶段的压缩。这个设计很聪明当会话不活跃时系统有机会把内部推理会话里那些冗长的中间结果压缩掉只保留关键节点。这样下次恢复会话时加载速度快上下文也不会太臃肿。2.4 双会话带来的实际好处用了这么久我总结双会话设计带来的实际好处有这么几个第一上下文利用率高。用户可见会话保持精简同样的上下文窗口能装下更多轮有效对话。第二可恢复性强。内部会话完整记录了每一步即使程序崩溃也能从事件日志恢复到一个一致的状态。第三调试友好。出问题时你可以直接看内部会话知道系统当时在想什么而不是只看到用户界面的表象。如果你自己做类似工具我强烈建议考虑双会话或者类似的分层。单会话看起来简单但一旦功能复杂起来会变成技术债。3. 事件溯源让每一次操作都可回放事件溯源这个词听起来很重但它的核心思想很简单不存当前状态而是存导致状态变化的所有事件。当前状态可以通过重放事件算出来。opencode 用事件溯源来管理会话状态。每一次消息、每一次工具调用、每一次状态变更都作为一个事件被记录下来。这样做的好处我在实际使用和排查问题时体会很深。3.1 事件溯源和传统状态存储的区别传统做法是状态变了就把新状态覆盖写到数据库。比如会话有 10 条消息第 11 条来了就把 11 条一起写进去。事件溯源不这样它只追加第 11 条消息到达这个事件前 10 条不动。这两种方式的区别用一个类比就清楚了。传统方式像每次拍照覆盖上一张事件溯源像拍一部连续的视频。你想知道现在长什么样看最后一张照片你想知道怎么变成现在这样的看视频。对比维度传统状态存储事件溯源存储内容当前完整状态状态变更事件序列写入方式覆盖更新追加写入历史追溯需要额外审计日志天然完整恢复能力依赖备份重放事件即可存储开销随状态增长随操作次数增长调试友好度一般高opencode 选事件溯源我理解主要是看中了可追溯和可恢复这两点。一个编码助手操作是有副作用的——它可能改了你的文件、跑了你的命令。如果出了问题你必须能知道它到底做了什么、按什么顺序做的。事件溯源天然满足这个需求。3.2 事件的结构设计一个事件要记录什么opencode 的事件结构我推测包含这几部分事件 ID唯一标识用于去重和引用。时间戳事件发生的时间用于排序和回放。事件类型是消息、工具调用、状态变更还是错误。负载事件的具体内容比如消息文本、工具参数、执行结果。关联 ID关联到哪个会话、哪条消息、哪次工具调用。这个结构的关键是关联 ID。有了它你才能把散落的事件串成一条链。比如一次工具调用会有调用开始事件、调用参数事件、执行输出事件、调用结束事件它们通过同一个关联 ID 绑在一起。提示设计事件结构时时间戳一定要用单调递增的时钟不要用系统墙上时钟。墙上时钟可能因为时区、校时而回退导致事件顺序错乱。我踩过这个坑回放时事件顺序乱了排查了半天。3.3 事件日志的写入与读取写入方面事件日志是追加写的不修改已有记录。追加写的好处是快而且天然并发安全多个写入者只要保证追加的原子性即可。opencode 应该是把事件写到本地文件按会话分文件或者分目录。读取方面有两种模式全量回放和快照加增量。全量回放是从头重放所有事件算出当前状态。快照加增量是先加载一个快照某个时间点的状态再重放快照之后的事件。后者快很多适合会话很长的情况。opencode 我推测两种都用日常恢复用快照加增量需要完整审计时用全量回放。这种快照 事件的组合是事件溯源系统的标准做法。3.4 事件溯源在排查问题时的实战价值讲个我实际遇到的场景。有一次 opencode 改一个文件改出来的结果和我预期的不一样。如果只有最终状态我根本不知道它为什么这么改。但因为有事