4.6 Session 的状态管理

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2025-02-17

---

4.6.1 SessionStatus：会话状态

SessionStatus（session/status.ts）管理每个会话的实时状态，主要有三种：

idle ──► busy ──► idle
              └──► pending (等待用户输入，如权限确认)

• idle：空闲。会话没有活动的 LLM 请求。

• busy：忙碌。LLM 正在生成响应或工具正在执行。

• pending：等待。Agent 需要用户输入（如权限确认或交互式提问）。

状态变化的触发点：

用户发送消息         → busy
LLM 开始流式输出     → busy
权限请求弹出         → pending
用户确认权限         → busy (继续执行)
LLM 完成回复         → idle
用户中止会话         → idle
发生错误            → idle (带 error 信息)

这些状态通过事件总线广播到前端，用于驱动 UI 的加载指示器、输入框禁用等交互。

4.6.2 SessionSummary：diff 摘要生成

SessionSummary（session/summary.ts）在每个 Step 结束后异步生成文件变更摘要：

SessionSummary.summarize({
  sessionID: input.sessionID,
  messageID: input.assistantMessage.parentID,
})

摘要的内容：

• additions：新增行数

• deletions：删除行数

• files：变更文件数

• diffs：各文件的 diff 详情

这些摘要信息被存储在 User 消息的 summary 字段中，用于在会话列表中快速显示"本次对话修改了哪些文件"。

4.6.3 Session 的 Revert 机制

SessionRevert（session/revert.ts）提供了文件回滚能力——将工作目录恢复到会话中某个时间点的状态。

Revert 流程：

1. 用户选择要回滚到的消息/步骤
       ↓
2. 查找该步骤对应的 Snapshot
       ↓
3. Snapshot.restore(snapshotHash)  → 恢复文件
       ↓
4. 记录 revert 信息到 Session.Info
   session.revert = {
     messageID: "...",
     partID: "...",
     snapshot: "...",
     diff: "..."
   }
       ↓
5. 后续消息可以基于回滚后的状态继续

Unrevert：如果用户想撤销回滚操作，可以通过 unrevert API 恢复到回滚前的状态。

Cleanup：每次处理新消息前，SessionRevert.cleanup() 会清理过期的回滚状态，确保不会干扰新的操作。

4.6.4 会话的完整生命周期

把本章的所有内容串联起来，一个 Session 的完整生命周期如下：

创建 (Session.create / Session.createNext)
│   设置 id, slug, projectID, directory, title
│   发布 Session.Event.Created
│
▼
活跃阶段
│   ┌─── 用户发消息 → SessionPrompt.prompt()
│   │       ├── 创建 User Message
│   │       └── 进入 Agentic Loop
│   │             ├── LLM.stream() → 流式生成
│   │             ├── 工具调用 → 执行 → 结果反馈
│   │             ├── Doom Loop 检测
│   │             ├── Snapshot 记录
│   │             └── Compaction 检查
│   │
│   ├─── Token 累积 → Prune → Compaction
│   ├─── 用户回滚 → Revert
│   ├─── 用户分叉 → Fork
│   └─── 循环...
│
▼
分享（可选）
│   Session.share() → 生成分享 URL
│
▼
归档
│   session.time.archived = Date.now()
│
▼
删除
    Session.delete() → 清理数据
    发布 Session.Event.Deleted

---

至此，Session 系统的 6 个核心方面——数据模型、消息模型、入口流程、Agentic Loop、Compaction、状态管理——已经完整覆盖。Session 是 OpenCode 最核心的模块，后续章节的 Tool、Agent、Provider 都是为 Session 服务的"零件"。