主题
3.1 TUI 界面详解
OpenCode 的 TUI 不是简陋的命令行问答——它是一个完整的终端图形界面，有对话区、文件变更追踪、会话管理、模式切换。理解界面布局，是高效使用 OpenCode 的第一步。
这一节在讲什么？
很多人一听到"终端里的 AI 助手"，脑子里浮现的就是一个黑底白字的命令行——输入问题，输出回答，完事。OpenCode 的 TUI（Terminal User Interface）远比这丰富——它用 Bubble Tea 框架构建了一个现代化的终端图形界面，有分区布局、快捷键操作、实时文件变更追踪、多会话管理。这一节我们把 TUI 界面的每个区域、每个快捷键、每个交互模式都讲清楚，帮你从"会打字"升级到"会操作"。
界面布局
启动 OpenCode 后，你会看到这样的界面布局：
┌─────────────────────────────────────────────────────────────┐
│ OpenCode ● my-project Build │ 3 msgs │
│─────────────────────────────────────────────────────────────│
│ │
│ 🤖 Assistant │
│ 我来帮你分析这个项目的认证逻辑。首先让我看一下 │
│ 相关文件... │
│ │
│ 📝 File Changes │
│ ~ src/auth/login.ts (+12, -3) │
│ │
│ 🤖 Assistant │
│ 我已经分析了认证逻辑，这个项目使用了 JWT + Refresh │
│ Token 的方案。主要实现在 src/auth/login.ts 中... │
│ │
│─────────────────────────────────────────────────────────────│
│ MCP: github ● supabase ● │
│─────────────────────────────────────────────────────────────│
│ > 帮我检查一下认证逻辑有没有安全问题 _ │
└─────────────────────────────────────────────────────────────┘界面分为四个主要区域：
1. 标题栏（顶部）
显示项目名称、当前模式（Plan/Build）、消息数量。最重要的是模式指示器——它告诉你当前 AI 是在"规划"还是"执行"。
2. 对话区（中部，占大部分空间）
显示你和 AI 的对话历史，支持 Markdown 渲染。AI 的回答会实时流式显示，你可以看到 AI 正在"打字"。当 AI 修改文件时，对话区会显示文件变更摘要（哪个文件、增减了多少行）。
3. 状态栏（底部上方）
显示 MCP 服务器的连接状态。绿色圆点表示已连接，红色表示连接失败。如果你配置了多个 MCP 服务器，这里会全部列出来。
4. 输入区（底部）
你输入问题的地方。支持多行输入（Ctrl+J 换行），支持 @ 文件引用、$ 命令引用、/ 斜杠命令。
Plan 模式 vs Build 模式
这是 OpenCode 最核心的交互概念——Tab 键在两种模式之间切换：
Plan 模式：AI 只分析任务、制定方案，但不执行任何修改。右下角显示 "Plan"。
- AI 会告诉你"我打算这样做：1. 读取 xxx 文件 2. 修改 yyy 函数 3. 添加 zzz 接口"
- 但它不会真的去读写文件、执行命令
- 你审查方案后，切回 Build 模式让它执行
Build 模式：AI 直接执行文件修改和命令。右下角显示 "Build"。这是默认模式。
- AI 会直接调用 READ/WRITE/RUN 等工具
- 文件变更会实时显示在对话区
- 你可以用 /undo 撤销不满意的修改
什么时候用 Plan？什么时候用 Build？
┌─────────────────────────────────────────────┐
│ 任务复杂度 │
│ │
│ 低 ──────────────────────────────── 高 │
│ │ │ │
│ │ Build 直接干 先 Plan 再 Build │ │
│ │ （改个 bug） （重构、新功能） │ │
│ │ │ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────────┘切换方式很简单——按 Tab 键。你会看到右下角的模式指示器在 Plan 和 Build 之间切换。
快捷键大全
OpenCode 的 TUI 有一套精心设计的快捷键，熟练掌握后你的操作效率会大幅提升：
| 快捷键 | 功能 | 说明 |
|---|---|---|
| Tab | 切换 Plan/Build 模式 | 最常用的快捷键 |
| Ctrl+C | 取消当前操作 | AI 正在生成时按此键中断 |
| Ctrl+L | 清屏 | 清空对话区的显示（不清空历史） |
| Ctrl+J | 换行 | 在输入区输入多行文本 |
| Esc | 返回/取消 | 退出当前操作或返回上一级 |
| Enter | 发送消息 | 输入完成后按 Enter 发送 |
| Ctrl+Z | 撤销 | 撤销 AI 的最后一次修改（等同 /undo） |
这些快捷键的设计遵循终端工具的常见约定——如果你用过 Vim 或者其他 TUI 工具，上手会很快。
主题配置
OpenCode 内置了多个主题，你可以在配置文件中设置：
json
{
"theme": "catppuccin"
}内置主题列表：
| 主题 | 风格 | 适合场景 |
|---|---|---|
| tokyo-night | 深色，偏冷色调 | 夜间编码 |
| catppuccin | 柔和暖色调 | 长时间使用，护眼 |
| dracula | 经典深色 | Dracula 粉丝 |
| nord | 北欧冷色调 | 简洁风格 |
| gruvbox | 复古暖色调 | 复古风格 |
主题切换不需要重启 OpenCode——修改配置文件后，TUI 会自动刷新。
文件变更追踪
当 AI 在 Build 模式下修改文件时，OpenCode 会在对话区实时显示变更摘要：
📝 File Changes
~ src/auth/login.ts (+12, -3)
+ src/auth/logout.ts (new)~表示修改了已有文件，括号里是增减的行数+表示创建了新文件-表示删除了文件
你可以直接在对话区看到 AI 改了什么，不需要切换到编辑器查看。如果你想看详细的 diff，可以问 AI："展示一下你刚才的修改详情"。
常见误区
误区一：一直用 Build 模式不切 Plan
这是最常见的低效用法。对于简单任务（修个 bug、加个字段），Build 模式没问题。但对于复杂任务（重构、新功能、跨文件修改），直接 Build 可能导致 AI 做出不理想的修改，你需要反复 /undo。养成习惯：复杂任务先 Plan，简单任务直接 Build。
误区二：不知道 Ctrl+J 换行
很多人在输入区想输入多行文本时，按 Enter 就发出去了——因为 Enter 是"发送"。多行输入应该用 Ctrl+J 换行。这在描述复杂需求时特别有用——你可以把需求分成几行写清楚，再一次性发送。
误区三：Ctrl+C 中断后不继续
Ctrl+C 只是中断 AI 当前的生成，不会丢失之前的对话历史。你可以修改问题后重新发送，或者补充信息后让 AI 继续。不需要开新会话。
误区四：主题只是装饰，不重要
主题不只是好看——好的主题能减少视觉疲劳，让你在长时间编码时更舒适。特别是 catppuccin 这种低对比度主题，长时间使用对眼睛更友好。选择一个你喜欢的主题，这是提升使用体验的简单方式。
小结
这一节我们详细讲解了 OpenCode 的 TUI 界面：四个主要区域（标题栏、对话区、状态栏、输入区）、Plan/Build 双模式的切换策略、快捷键大全、主题配置、文件变更追踪。掌握这些基础知识后，下一节我们学习 TUI 中最强大的交互能力——文件引用、命令引用和斜杠命令。