---
title: "03 · 終端 TUI 工作流"
description: "理解 OpenCode 的 TUI：檔案引用、shell 命令、斜槓命令、Plan/Build 雙模式、會話、壓縮與 attach。"
verifiedAt: "2026-05-09"
---

OpenCode 的主戰場是終端 TUI（terminal UI，文本介面）。TUI 不是把網頁聊天框搬進終端，而是讓 agent 站在你的專案目錄裡，能讀檔案、跑命令、看輸出、繼續會話、撤銷改動。

這一篇不背快捷鍵清單，而是講日常工作流：什麼時候用 `@` 給上下文，什麼時候用 `!` 跑命令，什麼時候用 `/` 控制會話，什麼時候按 **Tab** 切 Plan / Build 模式，什麼時候壓縮上下文，什麼時候 attach 到 server。

> [!NOTE]
> **這一篇解決什麼問題**：把 TUI 理解成“任務控制台”。讀完你應該能在一個真實專案裡完成：限定檔案閱讀、執行測試、檢視工具詳情、壓縮長會話、撤銷誤操作，並知道哪些命令不能隨便交給 agent。

## 1. TUI 不是聊天框，是控制台

你在 TUI 裡做的不是“問一句，等一句”。更準確的動作鏈是：

```mermaid
flowchart LR
    Ask["描述任務"] --> Context["指定上下文"]
    Context --> Act["允許讀檔案 / 跑命令 / 改檔案"]
    Act --> Inspect["看工具詳情和 diff"]
    Inspect --> Decide["繼續 / 修正 / 撤銷 / 壓縮"]

    style Context fill:#dbeafe,stroke:#3b82f6
    style Inspect fill:#fef3c7,stroke:#f59e0b
    style Decide fill:#fee2e2,stroke:#ef4444
```

這個鏈條裡最重要的是兩個控制點：

- 你要主動給上下文，不要讓模型在大專案裡亂猜。
- 你要主動看工具執行結果，不要只看最終回覆。

> [!IMPORTANT]
> **TUI 的核心能力是可觀察**：你能看到它讀了什麼、跑了什麼、改了什麼。第一次上手時，先把 `/details` 開啟，習慣看工具細節。

## 2. 用 `@` 明確上下文

OpenCode 支援在訊息中用 `@` 引用檔案。官方文件說明，`@` 會在當前工作目錄裡做 fuzzy file search，並把檔案內容加入對話。

```text
解释 @src/server.ts 的启动流程，并指出配置从哪里读取。
```

不要把上下文管理完全交給模型猜。尤其是 monorepo、大型前端專案、後端服務和多語言專案，顯式引用檔案會大幅降低跑偏。

更穩的寫法是把“檔案、目標、動作順序”一起寫清楚：

```text
只阅读 @src/auth.ts 和 @src/routes/login.ts。
判断登录失败时错误是在哪里被吞掉的。
先解释，不要修改。
```

這條提示詞同時做了三層限制：

| 限制 | 作用 |
| --- | --- |
| 只閱讀兩個檔案 | 降低無關上下文 |
| 判斷一個具體問題 | 防止泛泛解釋程式碼 |
| 先解釋，不要修改 | 保持第一輪只讀 |

## 3. 用 `!` 把命令輸出帶回對話

在 TUI 裡，訊息以 `!` 開頭可以執行 shell 命令。命令輸出會作為工具結果進入上下文。

```bash
!git status --short
!pnpm test
!pnpm run lint
```

這讓 agent 不只是“猜測測試是否透過”，而是能看到真實輸出再繼續判斷。

適合用 `!` 的命令：

- `git status`、`git diff`、`git log` 這類只讀 Git 命令。
- 測試、型別檢查、lint、format check。
- 專案自帶診斷指令碼。
- 檢視目錄和配置的只讀命令。

不適合直接交給 agent 自由執行的命令：

| 命令型別 | 風險 |
| --- | --- |
| `rm -rf`、刪除目錄 | 資料不可恢復 |
| `git reset --hard`、強制 checkout | 可能回復使用者改動 |
| 全儲存庫格式化 | 淹沒真實 diff |
| 修改全域性配置 | 影響當前專案外的環境 |
| deploy / publish / push | 進入釋出邊界 |
| 生產資料庫寫操作 | 可能造成真實損失 |

> [!WARNING]
> **新手坑**：不要用“幫我排障，隨便跑你需要的命令”。更好的寫法是“先列出你準備執行的命令和原因，我確認後再跑會修改環境的命令”。

## 4. 用 `/` 控制會話和系統動作

斜槓命令是 TUI 的控制面。常用命令不需要全背，先按用途分組記：

- **連線和初始化**：`/connect` 新增 provider 和 API key，`/init` 建立或更新 `AGENTS.md`。
- **模型和觀察**：`/models` 檢視可用模型，`/details` 開關工具執行詳情，`/thinking` 切換是否顯示模型推理過程。
- **上下文和會話**：`/compact`（別名 `/summarize`）壓縮當前會話，`/sessions`（別名 `/resume` `/continue`）檢視和切換會話，`/new`（別名 `/clear`）開新會話。
- **變更控制**：`/undo` / `/redo` 撤銷或重做上一輪訊息和檔案改動。
- **分享**：`/share` / `/unshare` 分享或取消分享會話。
- **匯出和退出**：`/export` 把當前對話匯出為 Markdown 並開啟 `EDITOR`，`/exit`（別名 `/quit` `/q`）退出 OpenCode。
- **輸入、外觀和幫助**：`/editor` 調外部編輯器寫長訊息，`/themes` 切換主題，`/help` 檢視可用命令。

多數命令還有以 `ctrl+x` 為 leader 的快捷鍵（如 `/compact` 是 `ctrl+x c`、`/undo` 是 `ctrl+x u`、`/new` 是 `ctrl+x n`），完整對映看 [Keybinds 官方頁](https://opencode.ai/docs/keybinds)；`/editor` 和 `/export` 呼叫的編輯器由系統環境變數 `EDITOR` 決定（如 `export EDITOR="code --wait"`）。

三條實用建議：

1. 第一次除錯任務，先開 `/details`，把工具呼叫細節看明白再繼續。
2. 長提示詞用 `/editor`，不要在終端裡寫到一半丟失。
3. 涉及原始碼和內部資訊，預設不要 `/share`——分享出去的連結公開可訪問，詳見 08 安全篇。

## 5. 用 **Tab** 切換 Plan / Build 雙模式

OpenCode 與同類終端 AI 程式設計工具最直觀的差異之一，是 **Plan mode 和 Build mode 雙模式**。在 TUI 任意位置按 **Tab** 鍵就能切換，TUI 右下角會顯示當前模式。

| 模式 | 模型行為 | 何時用 |
| --- | --- | --- |
| **Plan mode** | 只輸出"準備怎麼做"，不呼叫 edit / write 工具改檔案 | 第一次面對陌生任務、要先看方案的複雜改動、跨多檔案重構 |
| **Build mode** | 預設模式，可以讀、改、跑命令 | 已看過計劃、改動範圍明確的小步任務 |

推薦工作流：

```text
按 Tab 进 Plan
  ↓ 描述任务，让它先列出"我准备改哪些文件、为什么"
看完计划，必要时反馈或补条件
  ↓ 等它输出最终计划
按 Tab 切回 Build
  ↓ 让它按计划改
```

這條路徑與第 1 節"TUI 不是聊天框，是控制台"互為表裡——Plan mode 把"先看方案"做成一個鍵，讓"先看再改"成為日常習慣，而不是每次都靠提示詞約束。

> [!TIP]
> Plan mode 不是隻讀模式。它仍然能讀檔案、跑只讀命令（如 `git status`），所以適合讓模型邊看真實程式碼邊寫計劃，而不是閉眼空想。

## 6. `/undo` 不是魔法，要依賴 Git

官方 TUI 文件說明，`/undo` 會撤銷上一條使用者訊息、後續響應以及檔案改動；檔案改動的撤銷內部依賴 Git，所以專案需要是 Git 儲存庫。

這件事很重要。OpenCode 的安全基線不是“反正能 undo”，而是：

```text
真实项目必须先有 Git 状态
  ↓
每轮任务前看 git status
  ↓
每轮任务后看 diff
  ↓
不满意再 undo 或手动回滚
```

第一輪寫任務前，先讓它跑：

```bash
!git status --short
```

如果工作區本來就是髒的，不要讓 agent 直接大改。先讓它只讀解釋現狀，明確哪些改動是使用者已有改動，哪些是本輪可動範圍。

## 7. 長任務前先準備壓縮快照

長任務會遇到上下文膨脹。OpenCode 提供 `/compact`，也有 `/summarize` 別名，用於壓縮當前 session。

壓縮不是“自動安全”。壓縮前最好讓 agent 寫一份狀態快照：

```text
在压缩前，先按这 5 点总结当前状态：
1. 已经读过哪些关键文件。
2. 已经修改哪些文件，每个文件改了什么。
3. 哪些用户已有改动不能碰。
4. 仍未解决的问题是什么。
5. 下一步必须先运行哪些检查命令。
```

這樣壓縮後繼續任務時，關鍵約束不容易丟。

> [!TIP]
> **通俗講**：壓縮像把桌上資料收進資料夾。收之前先貼標籤，否則下次開啟還是亂。

## 8. 什麼時候用 `opencode run`

TUI 適合互動式工作；`opencode run` 適合短任務和自動化。

```bash
opencode run "Explain the use of context in Go"
```

`run` 支援指定模型、agent、檔案、輸出格式、session、attach 等引數。它適合：

- 批次解釋檔案。
- 生成簡單報告。
- 在指令碼里做只讀檢查。
- 連線已有 server 減少冷啟動。

但第一次修 bug、重構、排障時，不建議一上來用 `run`。你需要看它讀了什麼、跑了什麼、改了什麼，TUI 更合適。

## 9. attach 與 server 的邊界

OpenCode 可以把 TUI attach 到已經執行的 backend server。官方 CLI 文件給出的典型例子是先啟動 web/server，再用 TUI 連線：

```bash
opencode web --port 4096 --hostname 0.0.0.0
opencode attach http://10.20.30.40:4096
```

這對遠端機器、區域網訪問或 Web 介面很有用。但只要繫結到 `0.0.0.0` 或讓區域網能訪問，就不能當普通網頁服務處理。

最低要求：

- 設定 `OPENCODE_SERVER_PASSWORD` 或對應 basic auth。
- 不暴露到公網。
- 不在包含真實金鑰或客戶資料的專案裡隨便開。
- 結束後確認服務已關閉。

> [!IMPORTANT]
> **coding agent server = 專案讀寫入口**。它不是一個普通文件站，也不是臨時預覽頁面。

## 10. 一條推薦 TUI 任務模板

把下面這段作為日常任務起手式：

```text
你先只读分析，不要修改文件。
目标：{写清楚问题}
优先阅读：@{关键文件1} @{关键文件2}
请先输出：
1. 你理解的问题边界。
2. 你还需要看的文件或命令。
3. 你准备怎么验证。
等我确认后，再进入修改。
```

這個模板把 OpenCode 從“自由發揮”拉回“受控協作”。等任務穩定後，再把它沉澱成 command。

## 11. 本章自檢

- `@` 檔案引用解決什麼問題？為什麼在 monorepo / 大專案裡特別關鍵？
- 哪些命令適合用 `!` 直接跑，哪些必須先讓模型列計劃再確認？
- Plan mode 和 Build mode 的邊界在哪？什麼任務先按 Tab 進 Plan？
- 為什麼 `/undo` 不能替代每輪前後的 `git status` 和 diff 檢查？
- attach 到遠端 server 時，最少要滿足哪幾條安全條件？

> [!TIP]
> **過關標準**：你能用 TUI 完成一次“按 Tab 進 Plan → 明確上下文 → 看完計劃 → 切回 Build → 限定修改 → 看工具詳情 → 檢查 diff → 必要時 `/undo`”的完整閉環。

## 接下來去哪

<Cards>
  <Card title="使用 TUI" description="回到官方 TUI 頁，檢視 `@`、`!`、`/`、`/undo`、`/editor` 和 `tui.json` 的細節。" href="/zh-Hant/docs/opencode/official/00-getting-started/tui" />
  <Card title="使用 CLI" description="繼續理解 TUI、run、serve、web、attach 和 auth/models 的邊界。" href="/zh-Hant/docs/opencode/official/00-getting-started/cli" />
  <Card title="配置、Rules 與命令" description="當同一類提示詞說了三次，就該沉澱進 rules 或 command。" href="/zh-Hant/docs/opencode/understanding/04-config-rules-commands" />
  <Card title="分享會話" description="如果要把 TUI 會話發給別人，先理解公開連結和敏感資訊邊界。" href="/zh-Hant/docs/opencode/official/00-getting-started/share" />
</Cards>

## 官方資料

- OpenCode TUI：[https://opencode.ai/docs/tui](https://opencode.ai/docs/tui)
- OpenCode CLI：[https://opencode.ai/docs/cli](https://opencode.ai/docs/cli)
- OpenCode Share：[https://opencode.ai/docs/share](https://opencode.ai/docs/share)
- OpenCode Server：[https://opencode.ai/docs/server](https://opencode.ai/docs/server)
