OpenCode 一小時教學計劃
整體目標
讓學員理解 OpenCode 是什麼、如何安裝設定、掌握 TUI 基本操作與 Plan / Build 工作流程，並實際完成一次小任務。
課程結構總覽
| 段落 | 主題 | 時間 |
|---|---|---|
| 第一段 | 開場與定位 | 5 分鐘 |
| 第二段 | 安裝與環境設定 | 12 分鐘 |
| 第三段 | TUI 介面與基本操作 | 10 分鐘 |
| 第四段 | Plan 與 Build 工作流程 | 10 分鐘 |
| 第五段 | 實機演練 | 15 分鐘 |
| 第六段 | 總結與後續資源 | 8 分鐘 |
第一段：開場與定位｜5 分鐘
OpenCode 是什麼？
OpenCode 是開源、終端機優先的 AI 編碼代理工具，可以自由選擇模型供應商，例如 Anthropic、OpenAI、Gemini、Bedrock、OpenRouter 等。
它不像訂閱制工具把模型費用包進月費裡，而是使用者自帶 API Key，依實際用量付費給供應商。
與 Claude Code 的對照
| 項目 | Claude Code | OpenCode |
|---|---|---|
| 核心理念 | 終端機裡讀寫檔案、跑指令、修 bug | 終端機裡讀寫檔案、跑指令、修 bug |
| 模型選擇 | 較依賴特定供應商 | 可自由選擇多個模型供應商 |
| 開放性 | 產品工具 | 開源、可檢視、可擴充 |
| 適合對象 | 使用特定工具鏈的開發者 | 想掌控工具鏈與模型選擇的開發者 |
第二段：安裝與環境設定｜12 分鐘
1. 安裝方式
依作業系統選擇一種方式現場示範即可。
| 安裝方式 | 說明 |
|---|---|
| 官方 curl 一行安裝腳本 | 適合快速安裝 |
| npm 安裝 | 適合熟悉 Node.js / npm 的使用者 |
| brew 安裝 | 適合 macOS / Homebrew 使用者 |
2. 認識設定檔
設定檔位置：
~/.config/opencode/opencode.jsonc
此全域設定檔可用來指定預設模型、provider、agent 行為等。
JSONC 格式允許加註解與結尾逗號，適合一邊調整一邊寫說明。
3. 確認安裝成功
啟動：
opencode
確認能看到 TUI 歡迎畫面。
4. 連接模型供應商
在 TUI 中執行：
/connect
選擇要使用的 LLM 供應商並完成認證。
5. 認識 OpenCode Zen
OpenCode Zen 是由 OpenCode 團隊維護的「策展式」模型清單，團隊會先測試、基準化各模型與供應商組合，挑出表現穩定、適合編碼代理任務的模型。
| 項目 | 說明 |
|---|---|
| 使用方式 | 單一 API Key |
| 計費方式 | 按用量計費 |
| 適合對象 | 剛入門、不想管理多組供應商金鑰的學員 |
在 /connect 中選擇 OpenCode Zen 即可使用。
6. 選擇模型
執行：
/models
從目前已連接供應商，或 OpenCode Zen 提供的清單中選擇模型。
7. 認識 Web 版
OpenCode 也提供瀏覽器版介面，適合不方便操作終端機，或想快速做簡單示範時使用。
第三段：TUI 介面與基本操作｜10 分鐘
1. 啟動 TUI
啟動：
opencode
進入 TUI 後，導覽整體介面：
| 區域 | 說明 |
|---|---|
| 對話區 | 顯示使用者與 AI 的對話 |
| 輸入區 | 輸入指令或需求 |
| 檔案 / 工具呼叫顯示區 | 顯示 AI 讀寫檔案、執行工具或指令的過程 |
2. 基本指令
| 指令 | 功能 |
|---|---|
| /init | 讓 AI 讀懂專案結構，建立 context |
| /sessions | 在不同對話 session 之間切換 |
| /compact | 手動壓縮目前對話上下文，釋放空間 |
3. Session 管理
Session 會持久化儲存在本地 SQLite 資料庫中，可同時開多條任務線。
| Session | 用途 |
|---|---|
| Session A | Debug |
| Session B | 開發新功能 |
| Session C | 撰寫說明文件 |
第四段：Plan 與 Build 工作流程｜10 分鐘
1. Plan 模式
AI 會先針對需求提出修改計畫，但不會直接動到檔案，方便使用者先審閱方向是否正確。
| 模式 | 說明 |
|---|---|
| Plan 模式 | 先提出修改計畫，不直接修改檔案 |
2. Build 模式
AI 會實際執行檔案修改，並跑相關指令，例如編譯、測試或修 bug。
| 模式 | 說明 |
|---|---|
| Build 模式 | 實際修改檔案並執行相關指令 |
3. 示範完整來回
| 步驟 | 操作 |
|---|---|
| 1 | 用 Plan 模式詢問：「這個專案結構是什麼？如果要加一個新功能，該怎麼做？」 |
| 2 | 帶學員 review AI 提出的計畫 |
| 3 | 確認方向沒問題後，切換到 Build 模式 |
| 4 | 讓 AI 實際修改 |
4. 迭代式工作流
完成第一輪修改後，可以直接接著說：
再加上分頁。
補上單元測試。
AI 會理解既有上下文，接續修改，不需要重新描述整個專案背景。
第五段：實機演練｜15 分鐘
1. 演練專案選擇
找一個小型、學員熟悉的程式碼範例。
| 範例專案 | 可練習內容 |
|---|---|
| 簡單 API 專案 | 加上參數驗證、修正 bug |
| 學員自己的小型專案 | 讀懂結構、修改小功能 |
| 小型工具程式 | 補文件、調整功能 |
2. 實作流程
| 步驟 | 操作內容 |
|---|---|
| 1 | 啟動 opencode |
| 2 | 執行 /init，讓 AI 讀懂專案結構 |
| 3 | 用 Plan 模式請 AI 解釋某個函式或模組 |
| 4 | 請 AI 規劃新增一個小功能 |
| 5 | Review 計畫後切換 Build 模式 |
| 6 | 觀察 AI 修改檔案、執行 build / test 指令 |
| 7 | 用 /sessions 開第二條 session 處理另一個任務 |
| 8 | 選用：示範 /compact 的效果 |
3. 小需求範例
| 小需求 | 說明 |
|---|---|
| 為 API 加上參數驗證 | 示範 Plan → Build 流程 |
| 修正已知小 bug | 示範 AI 協助 debug |
| 撰寫說明文件 | 示範平行 session |
| 補上單元測試 | 示範迭代式修改 |
4. 平行任務練習
使用：
/sessions
開第二條 session，在不影響第一條任務的情況下，處理另一個小任務。
5. 選用：上下文管理
當對話變長時，示範：
/compact
並說明它與自動壓縮機制的差異。
第六段：總結與後續資源｜8 分鐘
1. 快速回顧
| 主題 | 重點 |
|---|---|
| 安裝與設定 | opencode.jsonc、/connect、OpenCode Zen、/models |
| TUI 基本操作 | /init、/sessions、/compact |
| 核心工作流程 | Plan 模式 → Build 模式 → 迭代式修改 |
| 進階入口 | Web 版介面，可作為終端機之外的替代使用方式 |
2. 後續學習資源
| 資源 | 連結 |
|---|---|
| 官方文件 | opencode.ai/docs |
| OpenCode Zen 說明 | opencode.ai/zen |
3. 課後建議
| 練習 | 說明 |
|---|---|
| 在常用專案中執行 /init | 讓 AI 讀懂專案 |
| 觀察 AGENTS.md | 確認是否符合專案實際情況 |
| 依需求調整 AGENTS.md | 讓 AI 後續更理解專案規則 |
4. Q&A
開放提問。
