TUI 基礎操作

摘要

本章將深入探索 opencode 的 TUI（Terminal User Interface） 操作方式。你將學會如何啟動 opencode、提出需求、使用 @ 參照檔案、執行 !bash 指令、活用斜線指令，以及理解 Plan 與 Build 兩種模式之間的區別。這些是每天使用 opencode 時最核心的操作。

學習目標

• 熟練啟動與退出 opencode
• 學會在對話中提出有效需求
• 掌握 @ 檔案參考語法
• 學會使用 !bash 執行 shell 指令
• 熟悉所有斜線指令
• 理解 Plan 與 Build 模式的差異
• 學會使用 /undo 和 /redo 回溯操作

啟動與基本操作

啟動 opencode

在你的專案目錄中執行以下指令即可啟動：

opencode

啟動後，終端機會進入 TUI 模式，畫面分為幾個區域：

• 對話區域：顯示你與 opencode 的對話記錄
• 輸入列：底部輸入你的訊息或指令
• 狀態列：顯示當前模式、模型、工作階段等資訊

退出 opencode

在輸入列中輸入以下任一方式可退出：

/exit

或直接按下 Ctrl+C。

提出需求

在輸入列中直接輸入自然語言即可。建議遵循以下原則：

• 明確具體：告訴 opencode 你想要什麼結果
• 提供上下文：附上相關檔案或錯誤訊息
• 指定範圍：說明哪些檔案需要修改、哪些不要動

請幫我在 src/utils 目錄下新增一個 date-helper.ts 檔案，
裡面包含 formatDate 和 parseDate 兩個函式，並加上 TypeScript 型別

@ 檔案參考

@ 符號是 opencode 中非常重要的功能，讓你可以直接將指定檔案的內容作為上下文提供給 AI。

基本用法

請幫我檢查 @src/app.ts 這個檔案，看看有沒有潛在的問題

當你輸入 @ 後，opencode 會自動彈出檔案搜尋選單，方便你快速選取。

多檔案參考

請比較 @src/utils/helper.ts 和 @src/utils/helper.test.ts 之間的差異

資料夾參考

請幫我了解 @src/components 這個資料夾的結構與功能

參考資料夾時，opencode 會列出該資料夾的內容摘要。

使用提示

• 善用 @ 讓 AI 理解你的專案上下文
• 不需要手動複製貼上檔案內容——@ 會自動處理
• 可以同時參考多個檔案與資料夾

!bash 指令執行

! 前綴讓你可以直接在 opencode 中執行 shell 指令，而不用離開 TUI。

執行單一指令

!git status
!npm test
!ls -la

在對話中混合使用

!npm run build
# 然後問 opencode
看起來建置失敗了，請幫我檢查錯誤訊息並修復

搭配管線與變數

!echo "當前目錄：$(pwd)"

執行結果會直接顯示在對話中，opencode 可以讀取這些輸出並根據內容做出回應。

斜線指令總覽

opencode 提供一系列以 / 開頭的快捷指令，協助你管理工作階段與專案設定：

Plan 與 Build 模式

opencode 提供兩種協作模式，適用於不同的工作階段：

Plan 模式

在 Plan 模式下，opencode 會先分析你的需求並提出實作計畫，但不會直接修改檔案。這個模式適合：

• 探索複雜功能的最佳實作方式
• 在動手前先討論架構設計
• 讓初學者理解實作步驟
• 進行程式碼審查（Code Review）

Build 模式

在 Build 模式下，opencode 會直接執行任務——建立、修改檔案、執行指令。這是預設模式，適合：

• 日常開發工作
• 明確知道要做什麼的任務
• 需要快速迭代的場景

切換模式

你可以在對話中隨時切換模式：

/plan   # 切換到 Plan 模式
/build  # 切換到 Build 模式

在 Plan 模式下，opencode 回覆後會等待你的確認，你覺得計畫可行時再切回 Build 模式執行。

/undo 與 /redo 實戰

為什麼需要 /undo？

當 AI 修改檔案後，結果可能不如預期。/undo 讓你可以一鍵復原最近一次操作，回到修改前的狀態。

使用場景

# opencode 修改了多個檔案
# 你發現修改方向不對
/undo

# 復原後重新下達更明確的指示
請改用另一種方式實作...

注意事項

• /undo 只能復原最近一次操作
• 連續使用 /undo 可以逐步回退多次操作
• 使用 /redo 可以重新套用被復原的修改
• 請注意 undo/redo 的歷史在開啟新對話（/new）後會清空

實戰練習