对象关系图
本文档描述 OpenCode 核心对象之间的关系和交互流程。
核心关系图
详细关系说明
1. Project - Session 关系
关系类型: 一对多 (1:N)
说明:
- 一个 Project 可以包含多个 Session
- Session 通过
projectID引用 Project - Session 的
directory可以是 Project 的worktree或某个sandbox
2. Session - Message 关系
关系类型: 一对多 (1:N)
说明:
- 一个 Session 包含多条 Message
- Message 通过
sessionID引用 Session - Messages 按
id排序（标识符包含时间戳）
3. Session - Session 关系（分支）
关系类型: 自引用 (0:1)
说明:
- Session 可以是另一个 Session 的分支
parentID指向父会话- 分支会话继承父会话的部分 Messages
4. Message - Part 关系
关系类型: 一对多 (1:N)
说明:
- 一条 Message 包含多个 Part
- Part 通过
messageID引用 Message - Part 的
id在 Message 内是唯一的
5. Message - Agent 关系
关系类型: 多对一 (N:1)
说明:
- Message 通过
agent字段引用 Agent - Agent 定义了消息的权限、模型和行为
primaryAgent 由用户直接使用，subagentAgent 由其他 Agent 调用
6. Config - 核心对象关系
说明:
- Config 是单例，在项目初始化加载
- 支持多层配置（远程、全局、项目、命令行）
- 配置合并规则：数组字段去重，对象字段深度合并
7. Permission - Agent 关系
说明:
- 每个 Agent 有自己的权限规则集
- 权限规则按优先级：默认 < Agent 特定 < 用户配置
- 权限在工具调用前检查
8. MCP - Tool 关系
说明:
- MCP 服务器可以提供多个工具
- 工具通过 MCP 协议调用
- OpenCode 自动将 MCP 工具转换为内部 Tool 格式
交互流程
完整对话流程
使用工具
会话分支
数据流图
生命周期图
Session 生命周期
Message 生命周期
ToolPart 生命周期
关系约束
唯一性约束
| 约束 | 说明 |
|---|---|
| Session.id | 全局唯一 |
| Message.id | Session 内唯一 |
| Part.id | Message 内唯一 |
| Project.id | 全局唯一（基于 Git root） |
引用完整性
| 引用 | 必须存在 | 约束描述 |
|---|---|---|
| Message.sessionID | Session 必须存在 | 约束到有效会话 |
| Part.messageID | Message 必须存在 | 约束到有效消息 |
| Session.projectID | Project 必须存在 | 约束到有效项目 |
| Session.parentID | Parent 必须存在 | 如果指定，父会话必须存在 |
级联删除
| 对象 | 删除时级联删除 |
|---|---|
| Session | 所有 Message 和 Part |
| Session | 所有子 Session |
| Message | 所有 Part |
| Project | 不删除（多 Session 可以引用同一 Project） |
性能考虑
缓存策略
- Config 缓存: Config 单例，避免重复加载
- Agent 缓存: Agent 定义在运行时缓存
- Model 缓存: 模型列表从本地缓存或远程加载
批量操作
- 批量创建 Part: 使用 Promise.all 并行写入
- 批量读取 Message: 使用列表 API 批量获取
- 批量删除: 先删除子对象，再删除父对象
延迟加载
- Parts 延迟加载: Message 信息不包含 Parts，按需加载
- 快照内容: 快照内容仅在需要时读取
- MCP 工具: MCP 工具列表仅在连接后加载
安全考虑
访问控制
- 权限系统: 所有工具调用受权限控制
- 会话隔离: 不同 Session 使用不同沙箱（可选）
- 文件访问: 读写操作受权限规则检查
数据验证
- Zod Schema: 所有对象使用 Zod 验证
- 类型安全: TypeScript 提供编译时类型检查
- 输入清理: 用户输入在处理前验证