OpenCode 核心对象架构文档

本文档详细描述 OpenCode 的核心对象设计、属性、事件和使用场景。

目录

核心领域对象

• Session - 会话对象，表示一个完整的对话上下文
• Message - 消息对象（MessageV2），表示用户或助手的对话
• Part - 消息部分，消息的基本组成单元
• Project - 项目对象，表示工作目录
• Agent - Agent 配置，定义 AI 助手的行为
• Command - 命令对象，定义可执行的命令模板
• Skill - Skill 对象，可重用的任务技能
• Prompt - Prompt 系统，处理用户输入和生成系统提示词

配置和管理

• Config - 配置系统，支持多层合并
• Plugin - 插件系统，动态扩展功能
• Permission - 权限系统，管理工具访问控制
• MCP - MCP（Model Context Protocol），连接外部工具和资源

计费和认证

• 计费和认证系统 - 计费、认证、订阅、BYOK 等完整架构
• 匿名访问和免费试用 - 匿名访问机制和 IP 级别试用限制
• Provider 管理 - Provider 加载、认证、选择和模型初始化

系统功能

• SessionCompaction - 消息压缩系统，性能优化
• SessionRevert - 版本控制和回滚系统
• FileWatcher - 文件监听系统

数据和状态

• Snapshot - 快照系统，文件系统状态管理
• Provider/Model - AI 模型提供商和模型配置
• SessionStatus - 会话状态，跟踪运行状态

交互组件

• Question - 问题系统，AI 向用户询问信息
• PTY - 虚拟终端（Pseudo Terminal），支持在 TUI 中运行命令

系统级

• LLM - LLM 调用系统
• Client-Server Communication - 客户端-服务器通信机制和事件总线
• Storage - 存储架构，键值持久化
• Events - 事件总线，组件间通信

关系和架构

• Relationship - 对象关系图和交互流程

TUI 文档

• TUI 概览 - TUI (Terminal User Interface) 完整文档

快速导航

按对象类型

按使用对象类型

对象关系概览

Project (1)
  └── Session (N)
      ├── Message (N)
      │   └── Part (N)
      ├── children (N, self-reference)
      └── parent (1, self-reference)

Config (1)
  ├── Agent (N)
  ├── Command (N)
  ├── MCP (N)
  └── Plugin (N)

Storage
  ├── Project
  ├── Session
  ├── Message
  └── Part

Task Tool
  ├── Session (creates child)
  ├── Agent (invokes)
  ├── Bus (listens to events)
  └── Context (returns result)

核心概念

Session（会话）

表示一次完整的对话交互，包含 Messages、快照、分享信息等。

Message（消息）

表示单次对话交换，分为 User 和 Assistant 两种角色。

Part（部分）

Message 的内容单元，可以是文本、文件、工具调用、推理等多种类型。

Agent（智能体）

定义 AI 的行为模式、权限和模型配置。

Project（项目）

表示工作目录，可以是 Git 仓库或普通目录。

开始使用

1. 阅读 Session 了解会话概念和父子关系
2. 阅读 Message 和 Part 理解消息结构
3. 阅读 Agent 了解如何配置 AI 行为和 Agent 通信
4. 阅读 Prompt 了解如何处理用户输入和生成系统提示词
5. 阅读 Storage 了解数据持久化
6. 阅读 Tools 了解可用工具和它们的功能
7. 阅读 Task 了解如何启动子 Agent 处理复杂任务
8. 阅读 Client-Server Communication 了解客户端-服务器通信机制
9. 阅读 Billing/Auth 了解计费和认证系统
10. 阅读 Anonymous Access 了解匿名访问和免费试用机制

版本信息

• OpenCode 版本：见 packages/opencode/package.json
• 文档版本：1.0.0
• 最后更新：2026-01-26

贡献

如需贡献或报告问题，请访问：

• GitHub Issues
• Contributing Guide
• Style Guide