本文档是为终端 AI 工具开发新手准备的，会用生动的比喻和实例帮你理解整个架构。
OpenCode 是一个终端 AI 编程助手。想象你有一个聪明的程序员朋友，ta 可以：
- 阅读你的代码（Read 工具）
- 帮你写代码（Edit/Write 工具）
- 运行命令（Bash 工具）
- 搜索文件（Glob/Grep 工具）
- 回答编程问题
而 OpenCode 就是在终端里实现这一切的程序。
用户: "帮我写一个排序函数"
↓
AI: "好的，我来写..."（调用 Write 工具）
↓
用户: "改成从大到小排序"
↓
AI: "好的，我修改一下..."（调用 Edit 工具）
这整个对话过程就是一个 Session。Session 会记住：
- 你说过的话（消息历史）
- AI 用过的工具（工具调用记录）
- 文件的改动（快照和补丁）
AI 模型本身只能"思考"和"说话"，但不能真正操作你的电脑。工具就是 AI 的"手"：
| 工具名 | 做什么 | 现实比喻 |
|---|---|---|
read | 读取文件内容 | 打开文件看一眼 |
write | 创建新文件 | 新建一个文档 |
edit | 修改文件 | 用橡皮擦掉一部分，写上新内容 |
bash | 运行命令 | 在终端里敲命令 |
glob | 搜索文件名 | 在文件夹里找 *.js 文件 |
grep | 搜索文件内容 | 全文搜索"TODO" |
OpenCode 可以连接不同的 AI 模型，比如：
- Anthropic Claude：Anthropic 公司的模型
- OpenAI GPT：OpenAI 公司的模型
- Google Gemini：Google 的模型
每个 Provider 就像不同品牌的"大脑"，你可以选择用哪个。
Agent 定义了 AI 的行为模式：
- build：写代码模式，可以读写文件
- plan：规划模式，只规划不执行
- explore：探索模式，快速浏览代码库
就像同一个人可以是"认真工作"或"头脑风暴"不同状态。
AI 想做某些事情时，可能需要你批准：
allow：直接允许deny：直接拒绝ask：每次都问你
比如删除文件这种危险操作，通常会设为 ask。
MCP 是一个标准协议，让 AI 可以使用外部工具。比如：
- 连接数据库查询
- 调用第三方 API
- 使用专业软件
就像给 AI 装上了各种"插件"。
ACP 让 IDE（如 Zed、VS Code）可以直接与 OpenCode 对话。这样你在 IDE 里就能使用 OpenCode 的全部功能。
┌─────────────────────────────────────────────────────────────────┐
│ 用户界面层 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ CLI │ │ TUI │ │ IDE │ │ Web │ │
│ │(命令行) │ │(终端UI) │ │(编辑器) │ │(浏览器) │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴─────┬──────┴────────────┘ │
│ ↓ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Server (HTTP API) │ │
│ │ /session /project /permission /config /event │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 核心业务层 │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Session 会话 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Message │ │Processor │ │ Prompt │ │Compaction│ │ │
│ │ │ 消息 │ │ 处理器 │ │ 提示词 │ │ 压缩 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Agent │ │ Permission │ │ Tool │ │
│ │ AI 人设 │ │ 权限 │ │ read/write/edit/bash │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 外部连接层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Provider │ │ MCP │ │ LSP │ │
│ │ AI 模型 │ │ 外部工具 │ │ 语言服务器 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ↓ ↓ ↓ │
│ Claude/GPT 数据库/API 代码补全/诊断 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 基础设施层 │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │Storage │ │ Config │ │ Bus │ │ File │ │ Log │ │
│ │ 存储 │ │ 配置 │ │ 事件 │ │ 文件 │ │ 日志 │ │
│ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │
└─────────────────────────────────────────────────────────────────┘
| 目录 | 职责 | 通俗解释 |
|---|---|---|
cli/ | 命令行接口 | opencode run 这类命令的实现 |
acp/ | IDE 通信 | 让 Zed/VS Code 能使用 OpenCode |
ide/ | IDE 集成 | VS Code 插件的后端 |
pty/ | 伪终端 | 支持交互式命令（如 vim） |
shell/ | Shell 执行 | 运行 bash 命令 |
share/ | 分享功能 | 分享对话给别人看 |
| 目录 | 职责 | 通俗解释 |
|---|---|---|
session/ | 会话管理 | 记录对话历史、调用 AI |
agent/ | Agent 配置 | 定义 AI 的行为模式 |
tool/ | 工具集合 | AI 能使用的所有工具 |
permission/ | 权限管理 | 控制 AI 能做什么 |
question/ | 提问机制 | AI 向用户提问 |
skill/ | 技能系统 | AI 的专业技能（如写测试） |
command/ | 内置命令 | /compact/clear 等命令 |
scheduler/ | 任务调度 | 管理多个任务（开发中） |
| 目录 | 职责 | 通俗解释 |
|---|---|---|
project/ | 项目识别 | 识别 Git 仓库、工作目录 |
file/ | 文件操作 | 读写文件、搜索文件 |
worktree/ | Git Worktree | 创建隔离的工作目录 |
storage/ | 数据存储 | 保存会话、配置到磁盘 |
snapshot/ | 文件快照 | 记录文件改动 |
patch/ | 补丁系统 | 生成和应用代码补丁 |
| 目录 | 职责 | 通俗解释 |
|---|---|---|
provider/ | AI 提供者 | 连接 Claude/GPT/Gemini |
auth/ | 认证管理 | 管理 API Key |
mcp/ | MCP 协议 | 连接外部工具 |
plugin/ | 插件系统 | 扩展功能 |
lsp/ | 语言服务 | 代码补全、错误检查 |
format/ | 代码格式化 | 美化代码 |
| 目录 | 职责 | 通俗解释 |
|---|---|---|
server/ | HTTP 服务 | 提供 API 接口 |
bus/ | 事件总线 | 模块间通信 |
config/ | 配置加载 | 读取 opencode.json |
env/ | 环境变量 | 管理环境变量 |
flag/ | 功能开关 | 控制实验性功能 |
global/ | 全局路径 | 管理配置文件路径 |
installation/ | 安装信息 | 版本、升级 |
bun/ | Bun 运行时 | 封装 Bun API |
id/ | ID 生成 | 生成唯一标识符 |
util/ | 工具函数 | 各种通用工具 |
当你输入 opencode run "写一个 hello world" 时，发生了什么？
1. CLI 解析命令
cli/cmd/run.ts → 解析参数，创建 Instance
2. 创建 Session
session/index.ts → 新建会话，分配 ID
3. 构建 Prompt
session/prompt.ts → 拼接系统提示词 + 用户消息
4. 选择 Agent 和 Model
agent/agent.ts → 选择 "build" Agent
provider/provider.ts → 选择 Claude/GPT 模型
5. 调用 AI
session/llm.ts → 发送请求给 AI 模型
6. 处理响应
session/processor.ts → 处理 AI 的回复
7. 执行工具（如果 AI 要写文件）
tool/write.ts → 检查权限 → 写入文件
8. 更新 Session
session/index.ts → 保存消息到 Storage
9. 显示结果
cli/ui.ts → 在终端显示结果
每个子目录都有自己的 README.md，包含：
- 模块的具体职责
- 关键文件说明
- 代码示例
- 常见问题
建议阅读顺序：
session/README.md- 理解会话机制tool/README.md- 理解工具系统provider/README.md- 理解 AI 连接acp/README.md- 理解协议（可选）mcp/README.md- 理解插件（可选）
- 从
index.ts开始，看命令注册 - 找到
cli/cmd/run.ts，看 run 命令实现 - 进入
session/index.ts，看会话创建 - 进入
session/processor.ts，看 AI 调用
- 参考
tool/read.ts的实现 - 在
tool/下新建mytool.ts - 在
tool/registry.ts注册工具
- 查看
provider/models.ts的数据结构 - 在配置文件中添加 provider
- 参考
provider/provider.ts的加载逻辑
| 术语 | 英文 | 解释 |
|---|---|---|
| 会话 | Session | 一次完整的对话 |
| 消息 | Message | 对话中的一条内容 |
| 部件 | Part | 消息的组成部分（文本/工具调用/附件） |
| 工具 | Tool | AI 可调用的功能 |
| 提供者 | Provider | AI 模型服务商 |
| 代理 | Agent | AI 的行为配置 |
| 权限 | Permission | 操作的授权控制 |
| 压缩 | Compaction | 把长对话压缩成摘要 |
| 快照 | Snapshot | 文件状态的记录 |
| 补丁 | Patch | 文件改动的记录 |
继续深入：打开各子目录的 README.md 了解更多细节。