📖 开篇导读

一、Session 的三层架构

OpenCode 的 Session 设计遵循"Schema → Core → Application"的三层分离：

二、Schema 层：会话的类型骨架

packages/schema/ 定义了 Session 相关的所有类型，共 64 个文件，其中直接关联 Session 的核心文件包括：

Session ID 使用 ulid 库生成时间排序的唯一标识符。V2 消息系统引入了序列号（seq）机制，每条消息在 SQLite 中按序列号严格排序，确保事件溯源的一致性。

三、Core 层：Effect 驱动的会话引擎

packages/core/src/session/ 是 Session 的核心实现，基于 Effect 函数式编程范式构建。以下是关键模块：

3.1 SessionStore — 会话数据存取

packages/core/src/session/store.ts 定义了 SessionStore.Service，提供四个核心接口：

interface Interface {
  get(sessionID: ID) → SessionSchema.Info | undefined
  context(sessionID: ID) → SessionMessage.Message[]
  runnerContext(sessionID: ID, baselineSeq: number) → Message[]
  message(messageID: ID) → { sessionID, message } | undefined
}

context() 通过 SessionHistory.load() 加载完整会话历史；runnerContext() 则加载从指定基线序列号之后的消息，用于 V2 Runner 增量加载。两者都考虑了压缩（compaction）边界——压缩后的历史只保留最新压缩点之后的消息。

3.2 SessionExecution — 执行路由

packages/core/src/session/execution.ts 定义了 Session 执行的抽象接口：

interface Interface {
  active() → ReadonlySet<SessionID>      // 当前活跃会话
  resume(sessionID) → void               // 恢复/加入执行
  wake(sessionID) → void                 // 注册新工作
  interrupt(sessionID) → void            // 中断执行
}

execution/local.ts 实现了本地执行路由：通过 LocationServiceMap 找到 Session 所属位置的 SessionRunner，再通过 SessionRunCoordinator 编排执行流。设计注释明确指出"未来远程放置（remote placement）将在此扩展"。

3.3 SessionRunCoordinator — 执行协调器

packages/core/src/session/run-coordinator.ts 实现了每个 Session 串行执行、不同 Session 并发执行的关键策略：

3.4 SessionRunner — V2 Runner 实现

packages/core/src/session/runner/llm.ts 是 V2 Runner 的核心，约 500+ 行代码。文件头部注释清晰地列出了实现进度清单（TODO checklist）：

/**
 * Runs one durable coding-agent Session until it settles.
 *
 * - Session ownership and controls
 *   - [x] Coordinate one local active drain per Session
 *   - [ ] Replace local ownership with durable multi-node
 *   - [ ] Mark busy/retrying/idle/interrupted/terminal status
 *   - [x] Honor optional agent step limits
 *
 * - One provider turn
 *   - [x] Translate V2 Session message → LLM messages
 *   - [x] Stream exactly one llm.stream(request) turn
 *   - [x] Persist text/usage/reasoning/tool-call events
 *
 * - Tool settlement and continuation
 *   - [x] Record tool call before side effects
 *   - [x] Authorize & execute via core-owned registry
 *   - [x] Persist typed success/failure outcomes
 *   - [x] Reload projected history after tool results
 *   - [x] Continue for durable user steering
 */

Runner 的依赖注入链展示了完整的 Effect 服务网络：

3.5 SessionInput — 用户输入准入

packages/core/src/session/input.ts 实现了"持久化 Prompt 准入"机制。用户输入通过 admit() 方法写入 session_input 表并触发 PromptAdmitted 事件，随后由 Runner 在安全边界将其提升（promote）为可见的用户消息。这一设计确保了"持久化准入"与"模型执行"的分离。

3.6 SessionCompaction — 上下文压缩

packages/core/src/session/compaction.ts 实现了 V2 上下文压缩逻辑。核心常量：

const DEFAULT_BUFFER = 20_000        // 默认缓冲 token 数
const DEFAULT_KEEP_TOKENS = 8_000    // 保留最近 token 数
const TOOL_OUTPUT_MAX_CHARS = 2_000  // 工具输出截断长度
const SUMMARY_OUTPUT_TOKENS = 4_096  // 摘要输出 token 限制

压缩模板要求 LLM 输出结构化的 Markdown 摘要，包含 Goal、Constraints、Progress、Key Decisions、Next Steps、Critical Context、Relevant Files 七个固定章节。工具输出超过 2000 字符时自动截断并添加 [truncated] 标记。

3.7 SessionContextEpoch — 上下文纪元

packages/core/src/session/context-epoch.ts 管理"上下文纪元"——记录系统上下文（SystemContext）的基线序列号和快照。当检测到上下文变化（如代码修改）或压缩发生后，自动重新初始化纪元，确保 Runner 始终使用正确的系统上下文基线。

3.8 SessionRevert — 会话回退

packages/core/src/session/revert.ts 支持将 Session 回退到指定消息边界。通过扫描目标消息之后的所有 assistant 消息中的 snapshot，收集受影响的文件列表，实现精确回滚。

3.9 SessionTodo — Todo 管理

packages/core/src/session/todo.ts 管理会话级别的 Todo 列表，存储在 todo 表中，支持 content、status、priority、position 四个字段，通过事务批量更新。

四、应用层：LLM 流式处理

packages/opencode/src/session/ 包含了 V1 兼容层和 LLM 流式处理逻辑：

4.1 SessionProcessor — 消息处理器

packages/opencode/src/session/processor.ts 是 V1 会话的流式处理器，定义了 Handle 接口用于管理工具调用生命周期：

interface Handle {
  message: SessionV1.Assistant
  updateToolCall(toolCallID, update) → ToolPart
  completeToolCall(toolCallID, output) → void
  process(streamInput) → Result  // "compact" | "stop" | "continue"
}

DOOM_LOOP_THRESHOLD = 3 防止工具调用陷入死循环。处理器内部维护 ProcessorContext，包含工具调用映射、阻塞状态、压缩标志、当前文本和推理映射。

4.2 LLM 流式服务

packages/opencode/src/session/llm.ts 定义了 LLM.Service，其 stream() 方法接收 StreamInput（包含用户信息、模型、Agent、权限、系统提示、消息、工具等），返回 Stream<LLMEvent>。支持三种 LLM 后端：

4.3 溢出检测

packages/opencode/src/session/overflow.ts 实现了上下文溢出检测：

const COMPACTION_BUFFER = 20_000

function usable(input) {
  const reserved = cfg.compaction?.reserved
    ?? Math.min(COMPACTION_BUFFER, maxOutputTokens(model))
  return model.limit.input
    ? Math.max(0, model.limit.input - reserved)
    : Math.max(0, context - maxOutputTokens(model))
}

function isOverflow(input) {
  if (cfg.compaction?.auto === false) return false
  const count = tokens.total || tokens.input + tokens.output
    + tokens.cache.read + tokens.cache.write
  return count >= usable(input)
}

当总 token 数超过"可用上下文"（模型上下文窗口减去输出预留）时触发压缩。

五、SQLite 数据模型

packages/core/src/session/sql.ts（176 行）定义了 6 张核心表：

注意 session_message 表有 4 个索引，包括按 (session_id, seq) 的唯一索引和按 (session_id, type, seq) 的联合索引——这是高性能事件溯源查询的基础。

六、执行流程图

七、关键设计洞察

1. 持久化优先（Durable-first）

Session 的每个阶段——输入准入、消息记录、工具调用、压缩——都先写入 SQLite 再执行。崩溃后可以从 session_input 表的 admitted_seq 恢复未处理的用户输入。

2. V1 与 V2 并存

message 和 part 表存储 V1 格式，session_message 表存储 V2 格式。V2 引入了序列号（seq）和类型化的消息结构，支持更高效的事件溯源。Runner 注释中明确标注了 V2 的 TODO 清单。

3. 位置感知（Location-aware）

LocationServiceMap 将 Session 绑定到特定工作区位置，每个位置有独立的 Effect 服务层。这为未来的分布式部署（remote placement）预留了架构空间。

4. 压缩策略的平衡

V1 压缩（opencode/src/session/compaction.ts）使用 PRUNE_MINIMUM = 20000 和 PRUNE_PROTECT = 40000 保护最近对话不被过度修剪。V2 压缩（core/src/session/compaction.ts）使用 LLM 生成结构化摘要，保留关键决策和文件引用。

八、总结

📚 系列导航