目标：熟悉 OpenCode 终端界面的每个区域和操作
TUI 界面概览
┌─────────────────────────────────────────────────────┐
│ OpenCode [计划] 模型: claude │ ← 顶部状态栏
├─────────────────────────────────────────────────────┤
│ │
│ 💬 你可以问我任何关于代码的问题 │ ← 对话区域
│ │
│ 🤖 我来分析一下这个项目... │
│ │
│ ✅ 已完成分析，创建了 AGENTS.md │
│ │
├─────────────────────────────────────────────────────┤
│ > _ │ ← 输入框
│ 计划模式 │ Ctrl+Enter 发送 │ Tab 切换模式 │ ← 底部提示
└─────────────────────────────────────────────────────┘
界面布局图
模式切换状态机
界面区域详解
1. 顶部状态栏
显示当前状态信息：
- 模式指示器 —
[计划]或[构建]，显示当前模式 - 当前模型 — 正在使用的 LLM 模型名称
- 项目名称 — 当前工作目录
2. 对话区域
显示你与 OpenCode 的完整对话历史：
- 你的消息 — 右侧，带 💬 图标
- AI 回复 — 左侧，带 🤖 图标
- 代码块 — 可折叠的语法高亮区域
- 文件修改 — 显示 diff（增删改）
快捷键：
| 快捷键 | 功能 |
|---|---|
↑ / ↓ | 滚动对话历史 |
PageUp / PageDn | 快速翻页 |
Home / End | 跳到顶部/底部 |
3. 输入框
底部输入区域，支持：
- 多行输入 — Shift+Enter 换行
- 文件引用 —
@键搜索并引用文件 - 图片上传 — 拖拽图片到终端窗口
4. 底部提示栏
显示当前可用的快捷键提示。
两种工作模式
按 Tab 键在两种模式间切换：
计划模式（Plan Mode）
┌─────────────────────────┐
│ [计划] 模型: claude │ ← 左上角显示 [计划]
└─────────────────────────┘
- AI 只分析不修改
- 输出详细的执行计划
- 你可以审查、反馈、调整
- 适合：复杂功能开发、架构调整
使用流程：
- Tab 切换到计划模式
- 描述需求
- AI 输出计划（步骤 1 → 步骤 2 → ...）
- 你审查计划，提出修改意见
- 满意后 Tab 切回构建模式执行
构建模式（Build Mode）
┌─────────────────────────┐
│ [构建] 模型: claude │ ← 左上角显示 [构建]
└─────────────────────────┘
- AI 直接执行修改
- 自动编辑文件、运行命令
- 适合：简单修改、快速修复、已确认的计划
文件引用（@）
在输入框中按 @ 键，会弹出文件搜索框：
> @src/ ← 输入路径或文件名
📄 src/lib/auth.ts
📄 src/lib/db.ts
📁 src/components/
> @src/lib/auth.ts ← 选择后引用该文件
引用后，AI 会自动读取该文件内容作为上下文。
技巧：
@后输入文件名的一部分即可模糊搜索- 可以引用多个文件：
@file1.ts @file2.ts - 引用目录：
@src/components/（AI 会读取目录结构）
快捷键速查表
全局快捷键
| 快捷键 | 功能 | 使用频率 |
|---|---|---|
Tab | 切换计划/构建模式 | ⭐⭐⭐ |
Ctrl+C | 取消当前操作 / 退出 | ⭐⭐⭐ |
Ctrl+L | 清屏 | ⭐⭐ |
输入框快捷键
| 快捷键 | 功能 | 使用频率 |
|---|---|---|
Enter | 发送消息 | ⭐⭐⭐ |
Shift+Enter | 换行 | ⭐⭐⭐ |
↑ / ↓ | 浏览历史输入 | ⭐⭐ |
@ | 文件引用 | ⭐⭐⭐ |
/ | 命令列表 | ⭐⭐ |
对话浏览快捷键
| 快捷键 | 功能 | 使用频率 |
|---|---|---|
↑ / ↓ | 上下滚动 | ⭐⭐⭐ |
PageUp / PageDn | 翻页 | ⭐⭐ |
Home / End | 顶部/底部 | ⭐⭐ |
Space | 向下翻页 | ⭐⭐ |
模式特定
| 快捷键 | 功能 | 模式 |
|---|---|---|
Ctrl+Enter | 发送（部分终端） | 全局 |
Esc | 取消当前输入 | 全局 |
Tab | 自动补全命令 | 输入 / 后 |
鼠标操作指南
虽然 TUI 主要使用键盘，但部分终端支持鼠标操作：
| 操作 | 效果 | 支持终端 |
|---|---|---|
| 滚轮滚动 | 滚动对话历史 | WezTerm, Kitty, iTerm2 |
| 点击对话 | 聚焦对话区 | 部分终端 |
| 选中文字 | 复制（需终端支持） | 大多数 |
| 右键粘贴 | 粘贴剪贴板 | 大多数 |
拖拽图片上传
支持视觉模型（如 Claude 3.5 Sonnet、GPT-4o）：
- 拖拽图片到终端窗口
- 或粘贴图片（如果终端支持）
- AI 会分析图片内容并加入上下文
使用场景：
- 上传设计稿，让 AI 按设计实现
- 上传错误截图，让 AI 分析报错
- 上传架构图，让 AI 理解系统结构
命令列表
在输入框中输入 / 查看所有可用命令：
| 命令 | 说明 | 使用频率 |
|---|---|---|
/init | 初始化项目，创建 AGENTS.md | ⭐ 首次 |
/connect | 添加/管理 API 密钥 | ⭐ 首次 |
/models | 查看/切换可用模型 | ⭐⭐ |
/undo | 撤销最近一次修改 | ⭐⭐⭐ |
/redo | 重做撤销的修改 | ⭐⭐ |
/share | 生成对话分享链接 | ⭐⭐ |
/clear | 清空对话历史 | ⭐⭐ |
/help | 查看帮助 | ⭐ |
/quit | 退出 OpenCode | ⭐ |
命令自动补全
输入 / 后按 Tab 可以自动补全命令：
> /u<Tab> → 自动补全为 /undo
> /c<Tab> → 自动补全为 /connect（或 /clear）
> /m<Tab> → 自动补全为 /models
避坑指南
终端兼容性
如果界面显示异常（乱码、错位）：
- 换终端 — 使用 WezTerm、Ghostty 等现代终端
- 换字体 — 使用支持 Unicode 和 Nerd Font 的字体
- 检查终端大小 — 确保窗口足够大（建议 80×24 以上）
模式误操作
- 计划模式下 AI 不会修改文件 — 如果你发现 AI 只说话不干活，检查是不是在计划模式
- 构建模式下 AI 会直接修改 — 重要操作前先
/undo备份或 Git 提交
常见显示问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 界面乱码 | 字体不支持 Unicode | 换用 JetBrains Mono、Fira Code |
| 颜色异常 | 终端不支持真彩色 | 升级终端或关闭真彩色 |
| 布局错位 | 窗口太小 | 放大到至少 100×30 |
| 鼠标无效 | 终端未启用鼠标支持 | set -g mouse on (tmux) |
真实场景案例
案例 1：分屏工作流
场景：需要对照 AI 的修改建议查看原代码。
操作：
# 使用 tmux 分屏
tmux new-session -s opencode -d
tmux split-window -h -t opencode
tmux send-keys -t opencode:0.0 'cd project && opencode' Enter
tmux send-keys -t opencode:0.1 'cd project && vim src/lib/auth.ts' Enter
tmux attach -t opencode- 左屏：OpenCode TUI
- 右屏：代码编辑器
- AI 给出修改建议后，右屏实时查看和编辑
案例 2：快速文件导航
场景：项目中文件很多，需要快速找到并引用多个相关文件。
操作：
🤖 帮我分析 @src/lib/auth.ts @src/middleware/auth.ts @src/app/login/page.tsx
这三个文件的认证流程是否一致
使用 @ 快速引用，AI 自动读取并分析关联。
案例 3：视觉模型辅助调试
场景：前端样式异常，截图给 AI 分析。
操作：
- 使用系统截图工具截取异常区域
- 在支持拖拽的终端（如 WezTerm）中，将截图拖入 OpenCode
- 发送消息：
🤖 这个按钮在悬停时没有变色，但代码中写了 hover 样式，
请检查 @src/components/Button.tsx
AI 结合截图和代码，快速定位是 CSS 优先级问题。
下一篇：05. 基础工作流