OpenCode · 第 7 章 Session 核心:执行引擎的演进

OpenCode · 第 7 章 Session 核心:执行引擎的演进

章节摘要:前面六章铺垫的所有抽象——分层、Agent、工具、LLM——都在这一章汇成一条河:一次对话在内核里到底怎么跑的。OpenCode 的会话(Session)核心正处在一个有意思的时期:它有一套正在运行的 V1(一个单体循环,把组装系统提示、调 AI SDK、流式处理工具调用、权限询问、压缩、续跑全塞在一个大函数里),同时有一套正在建设的 V2(用事件溯源把「持久化录入」和「模型执行」彻底分离,引入 durable 收件箱、回合协调器、Location 作用域)。这种双轨并存不是技术债,而是一次刻意的架构演进。本章要讲清两件事:V1 单体循环是怎么编排出一次完整对话的(它是当前可运行的真相),以及 V2 为什么要做这次演进——把录入与执行分离换来了什么(durable、可恢复、可并发),Location 作用域又为未来的多节点留下了什么缝。这是全书最硬核的章节之一,读懂它,你就读懂了 OpenCode 的心脏。

学习目标

阅读完本章,你应当能够:

1. 描述 V1 单体循环的完整编排:系统提示组装 → 模型流式调用 → 工具调用处理 → 权限询问 → 压缩判断 → 续跑,指出每一步做什么。
2. 解释 V2 的核心分离:为什么把「持久化录入」(durable 收件箱)和「模型执行」(回合 runner)拆开,这种分离换来了什么(durable、可恢复、可并发、可重放)。
3. 讲清回合协调器(SessionRunCoordinator):它如何合并同一会话的多次唤醒、如何协调提示词的「插队(steer)」与「排队(queue)」语义。
4. 说明 Location 作用域:为何模型/工具/权限/文件系统服务是 Location 级缓存的,而执行协调是进程级的;「移动会话」为何会清空上下文纪元。
5. 理解 V1→V2 演进的工程动机,能评价这次重构是否值得。

核心概念速览

一句话总结:V1 把一切塞进一个循环换来了简单直接,V2 把录入与执行分离换来了 durable 与并发——这不是推翻,而是把「能跑」升级成「能恢复、能并发、能演进」,Location 作用域则为未来的分布式埋下了缝。

子章节导航

01 V1 单体循环:系统提示组装与流式处理

讲 V1 的完整编排。一个超大函数如何:组装系统提示(含 Agent 指令、工具描述、权限提示)、调用底层 AI SDK、流式处理文本增量与工具调用、在工具执行前做权限询问、判断是否需要压缩、决定是否续跑。这一节是当前可运行真相的拆解。

02 V2 的核心分离:持久化录入 vs 模型执行

讲 V2 最关键的架构决策:把「用户提示如何进入系统」(录入到 durable 收件箱,产生事件)与「模型如何执行这一回合」(runner)彻底分开。重点讲这种分离换来了什么——durable(录入不会丢)、可恢复、可并发、可重放。

03 回合协调器与 drain 协调

讲 V2 的进程级协调器:它如何合并同一会话的多次唤醒(coalesce)、如何处理提示词的两种提升语义——「插队(steer,在下一个安全边界插队)」与「排队(queue,直到会话即将空闲才提升)」。还要讲清「drain 是进程内协调,不是 durable 实体」这个关键不变量。

04 Location 作用域与会话移动

讲 Location(目录 + 工作区 + VCS + 项目)为何是模型/工具/权限/文件系统服务的缓存键,而执行协调是进程级、按会话 ID 路由的。重点解释「移动会话」为何会清空上下文纪元——以及这个设计为未来多节点 clustering 留下了什么缝。

子章节之间的逻辑关系

本章遵循「看清现状 → 理解演进 → 掌握协调 → 认识作用域」的深入路径:

V1 单体循环 (01) ──当前可运行的真相
   │
   ▼
V2 核心分离 (02) ──为何要演进,换来了什么
   │
   ▼
回合协调器 (03)  ──V2 如何协调并发与续跑
   │
   ▼
Location 作用域 (04) ──服务缓存键与未来分布式的缝
   │
   ▼
第 8 章:会话里的「上下文」如何被管理
​

V1 是基础(它现在还在跑),V2 是演进方向,协调器与 Location 是 V2 的两个关键机制。理解这四节,你才完整掌握 OpenCode 的心脏——以及它正在长成什么样。

前置知识与后续延伸

前置知识:

• 第 2 章分层架构(领域核心层是 Session 核心的家)
• 第 5 章工具系统(工具调用如何被会话循环调度)
• 第 6 章 LLM 抽象层(会话每一回合调用的就是 LLM 请求)
• 「事件溯源」「CQRS」等架构模式的基本概念会有帮助,但非必需

本章为后续章节奠定的基础:

• V2 的录入与执行分离是第 8 章 System Context 在「安全回合边界」插入系统消息的前提
• Location 作用域解释了第 8 章「移动会话清空纪元」的根因
• 续跑与压缩判断为第 9 章上下文压缩的触发条件铺垫