09·隨時查
速查表
現場卡住先翻這頁。找不到對應操作時，按 ctrl+p 開啟指令面板。
最常用的五件事
| 你想做什麼 | 怎麼做 |
|---|---|
| 開始工作 | cd <專案資料夾> 然後 opencode |
| 問一個問題就好，不進 TUI | opencode run "問題" |
| 讓它動手（非互動） | opencode run --auto "任務" |
| 看錯誤的真正原因 | 加上 --print-logs --log-level ERROR |
| 確認設定有沒有生效 | opencode debug config |
opencode CLI
| 指令 | 作用 |
|---|---|
opencode | 在目前資料夾啟動 TUI 互動模式 |
opencode run "訊息" | 非互動執行一次。權限設 ask 的動作會被自動拒絕 |
opencode run --auto "訊息" | 同上，但事先答應所有未被明確拒絕的權限 |
opencode run -c "訊息" | 接續上一個 session |
opencode models | 列出目前可用的模型 |
opencode auth list | 看有哪些已登入的 provider |
opencode debug config | 顯示合併後的最終設定（排查設定問題的第一站） |
opencode debug paths | 顯示設定、資料、快取的實際路徑 |
opencode debug agent <名字> | 顯示某個 agent 的設定細節 |
opencode agent list | 列出可用的 agent |
opencode mcp list | 列出 MCP server 與連線狀態 |
opencode stats | token 用量與費用統計 |
opencode upgrade | 升級到最新版 |
忘記指令的時候
任何一層都可以加 --help：opencode --help、opencode run --help、opencode debug --help。
TUI 斜線指令
在 opencode 互動畫面裡打 / 會跳出清單。下面列出課程會用到及可以再探索的指令，實際清單以你的畫面為準。
| 指令 | 作用 | 工作坊會不會用到 |
|---|---|---|
/new | 開新 session（別名 /clear） | 會 換題目就用 |
/sessions | 切換 session（別名 /resume、/continue） | 會 回到舊對話 |
/diff | 開 diff 檢視器 | 會 看它改了哪幾行 |
/models | 切換模型 | 會 確認是 Big Pickle |
/editor | 開編輯器打長訊息 | 會 貼長指令時 |
/exit | 離開 | 會 請用這個離開 |
/help | 說明 | 忘記按鍵時 |
/agents | 切換 agent（Build / Plan） | 按 Tab 更快 |
/review | 讓 agent 檢查改動 | 進階 |
/themes | 換配色 | 想換再說 |
/init | 引導式建立 AGENTS.md | 不用 已經有了 |
/connect | 連接 provider | 不用 big-pickle 免登入 |
/mcps /skills /status /debug /move | 其他 | 不用 |
在自己的介面裡找功能
找不到斜線指令時，按 ctrl+p 搜尋功能名稱。壓縮、還原等操作也可以用下面的快捷鍵。
常用快捷鍵
| 按鍵 | 作用 |
|---|---|
ctrl+p | 開指令面板（找不到斜線指令時來這裡） |
ctrl+x c | 壓縮 context（取代 /compact） |
ctrl+x u | 復原（取代 /undo） |
ctrl+x x | 匯出對話（取代 /export） |
ctrl+x l | session 清單 |
Esc（按兩次以上） | 打斷 agent。第一次只會顯示 esc again to interrupt |
ctrl+j | 訊息內換行（shift+Enter 有些終端機吃不到） |
Tab | 切換 Build / Plan agent |
ctrl+c（輸入框為空時） | 直接離開，沒有確認。小心誤按 |
指令面板裡跟 session 有關的項目要先有對話才會出現。
剛開的空白畫面搜 compact 會顯示 No results found，那是正常的。
uv
| 指令 | 作用 |
|---|---|
uv sync | 依 pyproject.toml 建立／更新環境 |
uv run python <檔案> | 在專案環境裡執行 Python（本工作坊一律用這個） |
uv run python -c "..." | 執行一行 Python |
uv add <套件> | 加入套件並更新 pyproject.toml |
uv remove <套件> | 移除套件 |
uv --version | 看版本 |
不要用的指令
pip install、python xxx.py、conda activate 可能用到不同的 Python 環境；本教材統一用 uv run python，讓套件與程式都來自 uv 管理的 .venv 裡。
git 最小組合
| 指令 | 作用 |
|---|---|
git init | 開始追蹤這個資料夾（只做一次） |
git add -A | 把所有變動納入這次存檔 |
git commit -m "說明" | 存檔 |
git diff | 看工作目錄相對暫存區，尚未 git add 的修改 |
git status | 現在有哪些檔案被動過 |
git restore . | 從暫存區還原目前目錄下的已追蹤檔案，丟棄未暫存修改；不刪未追蹤檔案 |
git log --oneline | 看存檔歷史 |
核心工作流只有三步：動手前 git commit → 讓 agent 改 → git diff 檢查。
檢查前先不要 git add；確認不要未暫存修改時才用 git restore .。已暫存的變更用 git diff --cached 查看。詳見第 07 章。
常見錯誤與解法
| 訊息／症狀 | 怎麼辦 |
|---|---|
command not found: opencode無法辨識 'opencode' |
PATH 沒重新載入。關掉終端機重開。Windows 用 PowerShell 不要用 cmd。 |
permission requested: edit ...; auto-rejecting |
opencode run 是非互動模式，沒人能回答權限詢問。加 --auto，或改用互動模式（直接打 opencode）。 |
Error: Internal server error |
看不到原因。加 --print-logs --log-level ERROR 重跑。 |
Unrecognized request argument supplied: prompt_cache_key |
上游的已知偶發問題。重試一次通常就好。 |
UnknownError / Unexpected server error |
多半是換到了需要 API key 的模型。確認 opencode.json 的 model 是 opencode/big-pickle。 |
agent 用 python 而不是 uv run python |
AGENTS.md 沒被讀到。確認它跟 opencode.json 在同一個資料夾，且你在該資料夾裡啟動。用 opencode debug config 確認。 |
| agent 說「應該正確」但沒真的跑 | 在 AGENTS.md 裡明確要求「必須實際執行並印出結果」。詳見第 06 章。 |
| agent 開始「修」一個沒壞的程式 | 按 Esc 打斷它，然後問它一個能戳破錯誤前提的問題。不要放任它亂改。 |
| 回答愈來愈短、開始忘記前面講過的事 | context 快滿了。換題目就 /new；同一題按 ctrl+x c 壓縮（不是 /compact，1.18.30 沒有那個斜線指令）。壓縮前先把結論寫進 notes/。 |
/compact、/undo、/share、/export 打了沒反應 |
1.18.30 沒有這幾個斜線指令。改用 ctrl+x c／ctrl+x u／ctrl+x x，或 ctrl+p 開指令面板搜尋。 |
按 Esc 停不下來 |
要按兩次以上。第一次只會顯示 esc again to interrupt。 |
| opencode 突然關掉了 | 輸入框空的時候按 ctrl+c 就是離開，沒有確認。重開後用 opencode -c 接回上一個 session。離開請用 /exit。 |
ModuleNotFoundError |
套件沒裝或沒用 uv run。先跑 uv sync，再確認指令前面有 uv run。 |
| 圖沒出現 | 終端機環境沒有視窗，plt.show() 不會有效果。要用 plt.savefig("figs/xxx.png")。 |
下指令的四個習慣
想自己寫一份完整任務，或讓中斷的工作繼續，請看需求與續作練習。
| 習慣 | 差別 |
|---|---|
| 說清楚存到哪 | 「畫個圖」→ 你不知道它存去哪了。 「畫成兩張並排的圖存到 figs/lab1.png」→ 你找得到。 |
| 要求印出中間結果 | 「驗證一下」→ 它會說「已驗證，結果正確」。 「印出每一項的實際數值與 PASS/FAIL」→ 你看得到證據。 |
| 先推導再寫程式 | 直接要程式 → 你沒有獨立的對照組。 先要推導 → 那份推導就是你檢查程式的依據。 |
| 禁止它抄捷徑 | 「手刻 PCA」→ 它可能直接呼叫 sklearn。 「手刻 PCA，不可以呼叫 sklearn，它只能當對照組」→ 才是你要的。 |
三個實作怎麼判讀結果
下面是課程設定下的參考結果。先核對資料、參數與比較方式；浮點數用容差比對，不要求每一位都相同。
| Lab | 項目 | 參考值 |
|---|---|---|
| 1 | silhouette 最高的 k | 9（分數 0.1893） |
| k=10 的 silhouette | 0.1825 | |
| 2 | 前 3 個特徵值 | 179.0069 163.7177 141.7884 |
| 重建 MSE（K=10） | 4.9142964257 | |
| 直接相減 components_ 最大差 | 0.9411（不代表錯） | |
| 分母寫成 n 時，關卡 5 的差 | 0.0996 | |
| 3 | 梯度檢查最佳步長 | h ≈ 1e-4（誤差 7.2e-12） |
| 幾何間隔 | 1.174682e-02（> 0，故線性可分） | |
| 手刻 vs sklearn 的 ‖w‖ | 19.14 vs 97.90（準確率都 1.0） |