04 首次会话与产物观察

04 首次会话与产物观察

本节摘要:跑通之后,本节做一件常被忽略但很有价值的事——看看这次会话在你机器上留下了什么。OpenCode 不是「问完就忘」的,一次会话会留下三类产物:会话记录(持久化的对话历史)、文件改动(如果它执行了写操作)、事件流(可观测的执行轨迹)。观察这些产物,既是对「它真的干了活」的验证,也是为后面章节埋下伏笔——会话记录对应第 7 章的会话核心,文件改动对应第 5 章工具系统的写工具,事件流对应第 12 章的可观测性。本节是第 1 章的收尾,也是全书「从结果反推结构」视角的起点。

一、会话记录:它记住了这次对话

OpenCode 会把每次会话持久化下来——即使你关掉终端、明天再回来,这次对话也还在。会话记录通常存在用户主目录下的一个固定数据目录里,按会话 ID 组织。

用户数据目录
   └── 会话存储
         ├── 会话 A(含完整消息历史)
         ├── 会话 B
         └── ...
​

你可以用「列出会话」「恢复会话」之类的命令去翻看历史。这意味着什么?意味着 OpenCode 的会话不是临时变量,而是持久化实体——这个认知非常重要,它是第 7 章「Session 核心」的预告:会话为什么能恢复、为什么能跨进程协调,都源于它被持久化了。

💡 动手验证:跑完一次对话后,用「列出会话」命令(具体命令以本地版本为准)看看是不是真的多了一条记录。再试着用「恢复会话」把刚才的对话接回来,你会看到历史消息完整保留。

二、文件改动:它动手的痕迹

如果在会话里你让 Agent 改了文件(比如「把这段函数重命名」),那么除了对话记录,工作区里还会有实际的文件改动。这部分产物不在数据目录,而在你的项目目录里——就是它真正改的那些文件。

这一点值得强调,因为它涉及信任与安全:

• 它真的改了你的文件:不是模拟、不是占位,是真的写盘。
• 所以权限系统存在:第 4 章的权限三态(允许/询问/拒绝)正是为了让你能控制「它能不能动手」。第一次让它写时它会问你,就是这个原因。

工作区(你的项目目录)
   ├── 文件甲(被 Agent 改过)
   ├── 文件乙(没动)
   └── ...
​

⚠️ 建议用版本控制:让 Agent 动手前,确保你的工作区在 Git 之类版本控制下。这样它的改动是可回滚的——出了问题 git diff 看改了啥、git restore 撤销。OpenCode 内部也有文件系统快照机制(第 5、12 章会讲),但用户侧的版本控制是最后的安全网。

三、事件流:它怎么干活的轨迹

第三类产物最硬核,也最容易被新手忽略——事件流。OpenCode 在一次会话里会产生一连串事件:模型开始生成、生成了一段文本、请求调用某个工具、工具执行完毕返回了结果、又请求调用下一个工具......这些事件构成了一条完整的执行轨迹。

一次会话的事件流(示意)
   ├─ 文本增量事件(模型开始说话)
   ├─ 工具调用事件(模型请求读文件)
   ├─ 工具结果事件(读到的内容返回)
   ├─ 文本增量事件(模型继续)
   ├─ 工具调用事件(模型请求改文件)
   ├─ 权限询问事件(等你授权)
   ├─ 工具结果事件(改完了)
   └─ 结束事件
​

事件流的价值有三:

• 调试:出问题时,看事件流能精确定位是哪一步崩的。
• 可观测性:OpenCode 用 OpenTelemetry 把这些事件做成可追踪的链路(第 12 章)。
• 理解内核:事件流是第 7 章「会话循环如何编排」最直观的体现——你看到的每一个事件,对应内核里一个明确的阶段。

💡 怎么看到事件流:最简单的方式是在非交互式 run 里加输出格式参数(如指定 JSON 格式输出),你能看到结构化的事件流。TUI 形态下事件流被渲染成了界面上的动画,你看到的是「消费后的样子」。

四、三类产物的对应关系

把这三类产物和后续章节对应起来,你会发现本节其实是全书的一张「预告片」:

所以本节不只是「看看热闹」,它在帮你建立一种视角:OpenCode 的每一次响应,背后都有一套持久的、可观测的、受控的机制在运转。后面十二章都在拆这套机制。

五、第 1 章收尾:你现在站在哪

读完第 1 章,你应该处于这个状态:

• ✅ 装好了 OpenCode,平台二进制匹配正确
• ✅ 知道八种形态里第一次该用哪种(TUI / run / serve)
• ✅ 跑通了第一次响应,让它读过你的代码
• ✅ 看过会话留下的三类产物

换句话说,「能用」这一关你已经过了。从第 2 章开始,我们要从「能用」走向「懂原理」——先从整体架构看起:这套能跑的东西,内部是怎么分层的。

本节要点回顾

1. 会话记录是持久化的,关掉终端再回来对话还在——这是第 7 章会话核心的预告。
2. 文件改动是真的写盘,不是模拟;所以权限系统存在,版本控制是最后的安全网。
3. 事件流记录了「模型说话、调工具、等授权、返回结果」的完整轨迹,是调试与理解内核的钥匙。
4. 三类产物分别对应第 7 章(会话)、第 5 章(工具)、第 12 章(可观测性)。
5. 视角建立:每次响应背后都有持久、可观测、受控的机制在运转——全书都在拆这套机制。
6. 第 1 章结束你已经「能用」,从第 2 章起走向「懂原理」。

第 1 章到这里就结束了。下一章我们退一步,看一眼整套东西的全局架构——它为什么是这样分层的、依赖方向有什么铁律、一次请求如何穿越各层。