03 · 終端 TUI 工作流
理解 OpenCode 的 TUI：檔案引用、shell 命令、斜槓命令、Plan/Build 雙模式、會話、壓縮與 attach。
OpenCode 的主戰場是終端 TUI（terminal UI，文本介面）。TUI 不是把網頁聊天框搬進終端，而是讓 agent 站在你的專案目錄裡，能讀檔案、跑命令、看輸出、繼續會話、撤銷改動。
這一篇不背快捷鍵清單，而是講日常工作流：什麼時候用 @ 給上下文，什麼時候用 ! 跑命令，什麼時候用 / 控制會話，什麼時候按 Tab 切 Plan / Build 模式，什麼時候壓縮上下文，什麼時候 attach 到 server。
這一篇解決什麼問題：把 TUI 理解成“任務控制台”。讀完你應該能在一個真實專案裡完成：限定檔案閱讀、執行測試、檢視工具詳情、壓縮長會話、撤銷誤操作，並知道哪些命令不能隨便交給 agent。
1. TUI 不是聊天框，是控制台
你在 TUI 裡做的不是“問一句，等一句”。更準確的動作鏈是：
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這個鏈條裡最重要的是兩個控制點：
- 你要主動給上下文，不要讓模型在大專案裡亂猜。
- 你要主動看工具執行結果，不要只看最終回覆。
TUI 的核心能力是可觀察：你能看到它讀了什麼、跑了什麼、改了什麼。第一次上手時，先把 /details 開啟，習慣看工具細節。
2. 用 @ 明確上下文
OpenCode 支援在訊息中用 @ 引用檔案。官方文件說明，@ 會在當前工作目錄裡做 fuzzy file search，並把檔案內容加入對話。
解释 @src/server.ts 的启动流程，并指出配置从哪里读取。不要把上下文管理完全交給模型猜。尤其是 monorepo、大型前端專案、後端服務和多語言專案，顯式引用檔案會大幅降低跑偏。
更穩的寫法是把“檔案、目標、動作順序”一起寫清楚：
只阅读 @src/auth.ts 和 @src/routes/login.ts。
判断登录失败时错误是在哪里被吞掉的。
先解释，不要修改。這條提示詞同時做了三層限制：
| 限制 | 作用 |
|---|---|
| 只閱讀兩個檔案 | 降低無關上下文 |
| 判斷一個具體問題 | 防止泛泛解釋程式碼 |
| 先解釋，不要修改 | 保持第一輪只讀 |
3. 用 ! 把命令輸出帶回對話
在 TUI 裡，訊息以 ! 開頭可以執行 shell 命令。命令輸出會作為工具結果進入上下文。
!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 | 進入釋出邊界 |
| 生產資料庫寫操作 | 可能造成真實損失 |
新手坑：不要用“幫我排障，隨便跑你需要的命令”。更好的寫法是“先列出你準備執行的命令和原因，我確認後再跑會修改環境的命令”。
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 官方頁；/editor 和 /export 呼叫的編輯器由系統環境變數 EDITOR 決定（如 export EDITOR="code --wait"）。
三條實用建議：
- 第一次除錯任務，先開
/details，把工具呼叫細節看明白再繼續。 - 長提示詞用
/editor，不要在終端裡寫到一半丟失。 - 涉及原始碼和內部資訊，預設不要
/share——分享出去的連結公開可訪問，詳見 08 安全篇。
5. 用 Tab 切換 Plan / Build 雙模式
OpenCode 與同類終端 AI 程式設計工具最直觀的差異之一，是 Plan mode 和 Build mode 雙模式。在 TUI 任意位置按 Tab 鍵就能切換，TUI 右下角會顯示當前模式。
| 模式 | 模型行為 | 何時用 |
|---|---|---|
| Plan mode | 只輸出"準備怎麼做"，不呼叫 edit / write 工具改檔案 | 第一次面對陌生任務、要先看方案的複雜改動、跨多檔案重構 |
| Build mode | 預設模式，可以讀、改、跑命令 | 已看過計劃、改動範圍明確的小步任務 |
推薦工作流：
按 Tab 进 Plan
↓ 描述任务，让它先列出"我准备改哪些文件、为什么"
看完计划，必要时反馈或补条件
↓ 等它输出最终计划
按 Tab 切回 Build
↓ 让它按计划改這條路徑與第 1 節"TUI 不是聊天框，是控制台"互為表裡——Plan mode 把"先看方案"做成一個鍵，讓"先看再改"成為日常習慣，而不是每次都靠提示詞約束。
Plan mode 不是隻讀模式。它仍然能讀檔案、跑只讀命令（如 git status），所以適合讓模型邊看真實程式碼邊寫計劃，而不是閉眼空想。
6. /undo 不是魔法，要依賴 Git
官方 TUI 文件說明，/undo 會撤銷上一條使用者訊息、後續響應以及檔案改動；檔案改動的撤銷內部依賴 Git，所以專案需要是 Git 儲存庫。
這件事很重要。OpenCode 的安全基線不是“反正能 undo”，而是：
真实项目必须先有 Git 状态
↓
每轮任务前看 git status
↓
每轮任务后看 diff
↓
不满意再 undo 或手动回滚第一輪寫任務前，先讓它跑：
!git status --short如果工作區本來就是髒的，不要讓 agent 直接大改。先讓它只讀解釋現狀，明確哪些改動是使用者已有改動，哪些是本輪可動範圍。
7. 長任務前先準備壓縮快照
長任務會遇到上下文膨脹。OpenCode 提供 /compact，也有 /summarize 別名，用於壓縮當前 session。
壓縮不是“自動安全”。壓縮前最好讓 agent 寫一份狀態快照：
在压缩前，先按这 5 点总结当前状态：
1. 已经读过哪些关键文件。
2. 已经修改哪些文件，每个文件改了什么。
3. 哪些用户已有改动不能碰。
4. 仍未解决的问题是什么。
5. 下一步必须先运行哪些检查命令。這樣壓縮後繼續任務時，關鍵約束不容易丟。
通俗講：壓縮像把桌上資料收進資料夾。收之前先貼標籤，否則下次開啟還是亂。
8. 什麼時候用 opencode run
TUI 適合互動式工作；opencode run 適合短任務和自動化。
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 連線：
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。 - 不暴露到公網。
- 不在包含真實金鑰或客戶資料的專案裡隨便開。
- 結束後確認服務已關閉。
coding agent server = 專案讀寫入口。它不是一個普通文件站，也不是臨時預覽頁面。
10. 一條推薦 TUI 任務模板
把下面這段作為日常任務起手式：
你先只读分析，不要修改文件。
目标：{写清楚问题}
优先阅读：@{关键文件1} @{关键文件2}
请先输出：
1. 你理解的问题边界。
2. 你还需要看的文件或命令。
3. 你准备怎么验证。
等我确认后，再进入修改。這個模板把 OpenCode 從“自由發揮”拉回“受控協作”。等任務穩定後，再把它沉澱成 command。
11. 本章自檢
@檔案引用解決什麼問題？為什麼在 monorepo / 大專案裡特別關鍵？- 哪些命令適合用
!直接跑，哪些必須先讓模型列計劃再確認？ - Plan mode 和 Build mode 的邊界在哪？什麼任務先按 Tab 進 Plan？
- 為什麼
/undo不能替代每輪前後的git status和 diff 檢查？ - attach 到遠端 server 時，最少要滿足哪幾條安全條件？
過關標準：你能用 TUI 完成一次“按 Tab 進 Plan → 明確上下文 → 看完計劃 → 切回 Build → 限定修改 → 看工具詳情 → 檢查 diff → 必要時 /undo”的完整閉環。
接下來去哪
使用 TUI
回到官方 TUI 頁，檢視 `@`、`!`、`/`、`/undo`、`/editor` 和 `tui.json` 的細節。
使用 CLI
繼續理解 TUI、run、serve、web、attach 和 auth/models 的邊界。
配置、Rules 與命令
當同一類提示詞說了三次，就該沉澱進 rules 或 command。
分享會話
如果要把 TUI 會話發給別人，先理解公開連結和敏感資訊邊界。
官方資料
- OpenCode TUI：https://opencode.ai/docs/tui
- OpenCode CLI：https://opencode.ai/docs/cli
- OpenCode Share：https://opencode.ai/docs/share
- OpenCode Server：https://opencode.ai/docs/server