4.1 Session 数据模型

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

---

Session（会话）是 OpenCode 的核心抽象。每一次用户与 AI 的对话都发生在一个 Session 中——它管理着对话的完整生命周期：从创建、消息交换、工具调用，到压缩、分享和归档。

4.1.1 Session.Info 的 Zod Schema 定义

Session 的数据模型定义在 session/index.ts 中，使用 Zod Schema：

export const Info = z.object({
  id: Identifier.schema("session"),    // 会话唯一标识
  slug: z.string(),                     // 人类可读的短链接标识
  projectID: z.string(),                // 所属项目 ID
  directory: z.string(),                // 工作目录
  parentID: Identifier.schema("session").optional(), // 父会话 ID

  title: z.string(),                    // 会话标题
  version: z.string(),                  // OpenCode 版本号

  summary: z.object({                   // 文件变更摘要
    additions: z.number(),
    deletions: z.number(),
    files: z.number(),
    diffs: Snapshot.FileDiff.array().optional(),
  }).optional(),

  share: z.object({                     // 分享信息
    url: z.string(),
  }).optional(),

  time: z.object({                      // 时间戳
    created: z.number(),
    updated: z.number(),
    compacting: z.number().optional(),   // 正在压缩的时间
    archived: z.number().optional(),     // 归档时间
  }),

  permission: PermissionNext.Ruleset.optional(), // 会话级权限规则
  revert: z.object({                    // 回滚信息
    messageID: z.string(),
    partID: z.string().optional(),
    snapshot: z.string().optional(),
    diff: z.string().optional(),
  }).optional(),
})

关键字段解读：

• id：使用降序 ULID（Universally Unique Lexicographically Sortable Identifier）。降序意味着新创建的 Session 的 ID 在字典序上排在前面——这让按 ID 排序自然就是按时间倒序。

• slug：短链接标识符，用于分享 URL，比完整的 ULID 更短更友好。

• parentID：标记父子关系。当主 Agent 通过 Task 工具创建子 Agent 时，子 Agent 的 Session 会设置 parentID 指向父 Session。

• permission：会话级别的权限覆盖。允许在运行时动态修改某个会话的权限规则。

• revert：回滚标记。当用户触发回滚操作时，记录回滚到的 messageID 和对应的 Snapshot。

4.1.2 父子会话关系：parentID 与 Sub-agent 会话

OpenCode 支持多层会话嵌套。最典型的场景是 Task 工具创建子 Agent：

主会话 (session_001, agent: build)
├── 用户: "帮我重构 auth 模块"
├── AI: 调用 task 工具 → 创建子会话
│
└── 子会话 (session_002, parentID: session_001, agent: explore)
    ├── 系统: "搜索 auth 相关代码"
    └── AI: 返回搜索结果

父子关系的意义：

1. 追溯性：通过 parentID 可以追溯子任务的来源

2. 资源隔离：子会话有独立的消息历史和权限

3. 生命周期管理：父会话结束时可以清理子会话

4.1.3 会话的 Fork 机制

Session.fork() 允许从已有会话的某个时间点分叉出一个新会话：

export const fork = fn(
  z.object({
    sessionID: Identifier.schema("session"),
    messageID: Identifier.schema("message").optional(),
  }),
  async (input) => {
    const original = await get(input.sessionID)
    const title = getForkedTitle(original.title) // "xxx (fork #1)"
    const session = await createNext({ directory: Instance.directory, title })

    const msgs = await messages({ sessionID: input.sessionID })
    for (const msg of msgs) {
      if (input.messageID && msg.info.id >= input.messageID) break
      // 复制消息和 Parts 到新会话
    }
    return session
  },
)

Fork 的使用场景：

• 用户想回到对话的某个历史点重新开始

• 想要尝试不同的方案而不丢失之前的对话记录

• 标题格式为 "原标题 (fork #N)"，N 递增

4.1.4 Session 事件

Session 模块通过 Bus 发布以下事件：

export const Event = {
  Created: BusEvent.define("session.created", z.object({ info: Info })),
  Updated: BusEvent.define("session.updated", z.object({ info: Info })),
  Deleted: BusEvent.define("session.deleted", z.object({ info: Info })),
  Diff:    BusEvent.define("session.diff", z.object({
    sessionID: z.string(),
    diff: Snapshot.FileDiff.array(),
  })),
  Error:   BusEvent.define("session.error", z.object({
    sessionID: z.string().optional(),
    error: MessageV2.Assistant.shape.error,
  })),
}

这些事件驱动了 TUI/Web UI 的实时更新——每当会话状态变化，前端就会收到通知并刷新界面。