OpenCode 實戰筆記：知識地圖與導航 (MOC)

「從敲下第一行終端指令，到建構企業級自主代理工作流。」
本書是 OpenCode 實戰落地的實務聖經。全方位收錄代理協同、LSP 語意感知、MCP 工具擴展、代碼重構與團隊防護規範，助你從一般使用者跨越為駕馭 AI 代理的工程專家。

🗺️ 全書六大核心模組導航

🧭 OpenCode 核心作業流全景決策圖

🧭 決策流程樹：OpenCode 實戰筆記：知識地圖與導航 (MOC)

下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 01 章：AI 程式輔助的演進 — 從自動補全到自主代理

你是否曾有過這樣的日常體驗：把終端機噴出的落落長錯誤日誌截圖或複製，貼到瀏覽器的對話框裡問 AI「這段報錯怎麼解」；幾秒鐘後，AI 吐出了一大段修復建議與重構代碼，你再小心翼翼地把代碼複製回編輯器、對齊縮排、手動存檔、重啟測試……結果終端機又跳出另一個新錯誤。

如果你正在經歷這個循環，那麼你並不是在享受 AI 帶來的生產力革命，而是在充當 AI 與真實工程世界之間的「人肉搬運工與打字員」。

AI 輔助寫程式這條路，在短短數年間經歷了翻天覆地的三次質變：
1. 第一階段：自動補全（2021 年前後） — 以早期 GitHub Copilot 為代表。它的本質是「輸入法級的下一行預測」。你寫出函式簽名，它在游標後浮現半透明的幽靈文字。此時的主導權完全在你手上，AI 只是幫你少敲幾次鍵盤。
2. 第二階段：對話式輔助（2022 至 2024 年） — 以 ChatGPT、Claude 網頁端與各類編輯器側邊欄為代表。上下文從游標周遭擴大到了「你貼上的整段文字」。但它與實際專案是斷裂的，它看不見你的完整目錄，跑不了你的編譯指令，建議能不能用全憑你的運氣與搬運功力。
3. 第三階段：自主代理（2025 年至今） — 代理（Agent）徹底重塑了人機協同的邊界。它不再只出張嘴，而是長出了「眼睛」與「雙手」：主動巡航專案目錄、定位相依套件、規劃變更步驟、直接編輯多個檔案、執行單元測試，並在測試失敗時根據錯誤日誌自我修正，直到交付可驗收的成果。

在這個階段，你的角色正式從「敲代碼的施工工匠」升級為「指派任務、審查 Diff 與驗收品質的技術主管（Tech Lead）」。而 OpenCode 正是第三階段最具代表性且徹底開源的自主代理引擎。

為什麼工程師需要堅持開源方案？

面對琳瑯滿目的商業閉源代理工具，將核心開發流程押注在一個黑盒子背後，隱藏著四大不可逆的工程隱患：
- 擺脫供應商鎖定（Vendor Lock-in）：商業產品通常將使用者深度綁定於特定模型供應商。一旦定價倍增、配額限流或服務政策異動，你的工作流瞬間面臨停擺。OpenCode 透過統一模型層支援超過 75 家供應商，架構規劃時用頂級推理模型，跑批量重構時切換高性價比模型，甚至在無網環境無縫切換本地端點。
- 捍衛企業資料主權（Data Sovereignty）：代碼資產是團隊的核心命脈。OpenCode 的會話、日誌與專案歷史全數以標準 SQLite 格式儲存於本地機器（~/.local/share/opencode/），絕不強制上雲，亦可全面接入本地離線模型，做到代碼百分之百不跨出內網。
- 無限可客製的工具鏈邊界：閉源工具的能力極限由商業公司的產品經理決定，而 OpenCode 的能力極限由你的工程想像力決定。從小到終端快捷鍵、提示詞微調，大到自訂 MCP 工具與擴充外掛，每一層都開放源碼供你自由擴展。
- 經得起審視的透明安全：代理具備執行 Shell 指令與編輯檔案的高權限，任何黑箱操作都是資安未爆彈。開源讓每一次工具調用、每一筆權限請求皆攤在陽光下，經受全球資安社群的嚴格審計。

🧭 決策流程樹：第 01 章：AI 程式輔助的演進 — 從自動補全到自主代理

步驟化 SOP 實戰詳解

1. 觸發情境：評估並建立「代理優先」的開發心智

識別訊號：當你需要跨越 2 個以上檔案進行重構、修復需要跑測試才能驗證的 Bug，或是需要為既有模組補齊單元測試時，切忌打開瀏覽器複製貼上，應立即啟動終端 OpenCode。
角色切換：在下達任務前，提醒自己目前的職責是「審查者」而非「打字員」。準備好可被驗證的驗收標準（例如特定的測試檔名、期望的輸入輸出）。

2. 核心操作：指派受控任務的三步閉環

確立退路基準點：進入目標專案後，先在終端執行 git status 確認工作目錄乾淨，確保隨時可透過版本控制完全還原。

啟動 OpenCode 並指派清晰目標：下達指令時務必包含「目標」、「受影響範圍」與「驗收方式」：

請為訂單模組新增取消交易功能：
1. 涉及範圍：src/order/service.py 與 src/order/models.py
2. 業務規則：已出貨訂單禁止取消，取消成功後應釋放庫存
3. 驗收方式：執行 pytest tests/test_order.py 確認全數通過

終端即時審查與驗收：觀察 OpenCode 自動定位程式碼、呼叫編輯工具替換片段、在背景執行測試。透過終端呈現的 Diff 逐行檢驗，確認邏輯符合預期。

3. 踩坑避雷與防護指南

防範黑盒子供應商鎖定：定期檢視專案所依賴的模型接口，避免在專案代碼中硬編碼特定商業供應商的專有語法；優先善用 OpenCode 的多供應商適配特性保持彈性切換能力。
杜絕盲目信任代理：代理並非不會出錯。即使單元測試全部綠燈，也必須親自審查 Diff 是否包含多餘的無效依賴、硬編碼常數或被誤刪的邊界防護代碼。
善用版本控制作為最終防禦網：代理開始大範圍改動前，若無 Git 追蹤，千萬不可直接執行批次寫入任務；隨時保持原子提交（Atomic Commits）習慣。

行動檢核清單（Checklist）

理解從「自動補全」、「對話諮詢」到「自主代理」的人機角色分工轉移
認清開源自主代理在資料主權、供應商解綁與安全性上的核心價值
指派任務前確認已在乾淨的 Git 分支，具備一鍵復原機制
任務描述中具備具體的目標定義、修改邊界與客觀驗收方式
堅持「人是最終把關者」原則，落實每筆 Diff 的人工審查

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 02 章：系統架構總覽 — 核心組件與生命週期

在日常開發中，你是否曾遭遇過這些令人困惑的疑問：
- 為什麼在終端機裡剛聊到一半的會話，切換到 VS Code 或瀏覽器介面時，能夠無縫呈現完全同步的上下文？
- 為什麼可以用輕薄的筆記型電腦，絲滑地遠端操縱公司算力強大的 Linux 工作站執行繁重的編譯與測試？
- 每次與 AI 的對話記錄、工具呼叫過程與暫存狀態，究竟被存放在硬碟的哪一個角落？

多數人使用 AI 工具時只關注眼前跳出的文字，但資深工程師懂得探究「系統的形狀」。唯有掌握 OpenCode 的底層架構，當你遇到連線逾時、多端衝突或排查歷程資料時，才能一眼看穿問題的癥結所在。

主從式架構：分離的「大腦」與「顯示器」

OpenCode 在架構設計上摒棄了傳統單體客戶端的做法，採用了現代標準的主從式架構（Client-Server Architecture）：
- 伺服器核心（Server Core）：系統的真正智能中心。它管理著對話狀態、上下文壓縮、模型呼叫路由、工具授權與 SQLite 資料庫讀寫。
- 前端客戶端（Frontends）：純粹的互動外殼。無論是原生終端機介面（TUI）、VS Code / JetBrains 外掛，還是 Web 介面，它們都只是伺服器狀態的「投影鏡頭」。

這種設計帶來了三大直接優勢：
1. 多前端狀態一致：前端不持有任何持久化狀態。終端機關閉後重新開啟，或在 IDE 與終端機之間切換，看到的永遠是同一份最新的會話歷程。
2. 無頭遠端協同（Headless Operations）：伺服器核心可以完全脫離圖形介面，以無頭模式常駐於遠端伺服器或 Docker 容器中。你只需在本地筆電執行 opencode attach，即可零延遲操縱遠端環境。
3. 自動化整合入口：同一組伺服器 API 提供了標準化的 CLI 入口。透過 opencode run 與 --format json，可以輕鬆將代理任務無縫嵌入 CI/CD 流程或自動化批次腳本中。

技術棧的四根頂樑柱

OpenCode 的底層選型精準兼顧了「執行效能」、「渲染流暢度」、「跨模型適配」與「本地持久化」：

元件名稱	核心技術	扮演角色與工程價值
執行環境	Bun	極速啟動的現代 JavaScript 執行環境與打包器，讓 OpenCode 能以零外部依賴的獨立二進位單檔迅速發布，擺脫傳統 Node.js 笨重龐大的 node_modules 包袱。
終端介面	SolidJS	以細粒度響應式更新（Fine-grained Reactivity）著稱的前端框架。它將終端機 TUI 的畫面重繪成本降至極致，即便在長篇對話與高頻串流輸出時，終端依然滑順如絲、告別惱人閃爍。
模型抽象	Vercel AI SDK	抹平超過 75 家模型供應商 API 格式差異的統一串流層。OpenCode 在其之上構建工具調用標準，確保切換底層大模型時，上層工具鏈與會話無感運作。
本地持久化	SQLite (WAL)	所有會話記錄、訊息日誌與運行狀態皆持久化於 `~/.local/share/opencode/opencode.db`。採用預寫日誌模式（WAL），保證高併發讀寫下的資料完整性與零資料外洩。

「一切皆事件」的心智模型

在 OpenCode 中，任何動態——不管是工程師敲入的指令、模型的內部推理思考、各類工具的參數調用，還是檔案系統的即時變更——都會被封裝為結構化的事件（Events）。

事件順序流經系統，即時寫入本地 SQLite，並透過內部事件匯流排即時廣播給所有連線中的客戶端。這種事件驅動機制使得系統具備極佳的擴展性：會話可以隨時透過 opencode export 匯出為完整 JSON 序列，除錯時能逐幀回放，外掛系統更能精準監聽特定事件掛鉤（Hooks）插入自訂邏輯。

🧭 決策流程樹：第 02 章：系統架構總覽 — 核心組件與生命週期

步驟化 SOP 實戰詳解

1. 觸發情境：部署並切換 OpenCode 的運行模式

識別訊號：當你需要從單純的本機終端開發，擴展到需要使用雲端高配算力機器跑整合測試，或是需要將會話同步至 VS Code 外掛時。
架構準備：確認目標主機已正確配置網路連線與防火牆規則，並準備好存取權限。

2. 核心操作：遠端無頭伺服器架設與客戶端附加

工作站啟動無頭伺服器：在具備強大算力或依賴環境的工作站上，指定主機位址與連接埠啟動服務：
```
opencode serve --port 4096 --hostname 0.0.0.0
```
本機客戶端掛載連接：在你的輕量筆電或工作機上，直接發起遠端附加：
```
opencode attach http://workstation.local:4096
```

本機會話歷程查閱與匯出：即便連線中斷，所有狀態都完整留存在資料庫中。可隨時在終端檢視或備份：

# 列出本機所有歷史會話
opencode session list

# 將特定會話匯出為結構化 JSON 檔案
opencode export <sessionID> > session_backup.json

3. 踩坑避雷與防護指南

認清目錄職責分離：記住資料存放於 ~/.local/share/opencode/（資料庫、授權、日誌），而個人化設定位於 ~/.config/opencode/（配置檔、自訂技能）。手動備份或遷移機器時，切勿混淆兩者。
無頭服務安全暴露防線：在公網或非信任內部網路上執行 opencode serve --hostname 0.0.0.0 時，必須配合防火牆白名單或 SSH Tunnel，嚴禁未經驗證對外暴露端口，防止未授權存取本地執行權限。
多端併發衝突自覺：雖然多前端能看見同一會話，但應避免在多個客戶端視窗同時下達修改指令，以免工具執行順序交錯造成工作目錄衝突。

行動檢核清單（Checklist）

深刻理解主從分離架構：客戶端僅為渲染投影，伺服器與資料庫承載所有智能
掌握 Bun、SolidJS、Vercel AI SDK 與 SQLite 四大技術元件的分工與優勢
熟悉 opencode serve 與 opencode attach 的遠端無頭協同操作流程
明確劃分資料目錄（~/.local/share/）與設定目錄（~/.config/）的路徑職責
掌握 opencode session list 與 opencode export 的會話管理指令

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 03 章：代理系統 — 主代理與子代理協同架構

你是否經歷過這樣的災難性場景：
你對著 AI 輕描淡寫地說了一句：「幫我重構一下購物車的折價券邏輯。」結果下一秒，AI 像脫韁野馬般瘋狂修改了十幾個核心檔案，直接把現有模組改得面目全非，甚至在遇到相依性報錯時自作主張安裝一堆奇怪套件，最後整個專案連編譯都通不過。

或者，你與 AI 進行了一場長達兩小時的深度對話，起初它精明過人，但到了後半段，它開始頻繁忘記先前的約定、出現幻覺，連最基本的檔名都搞錯——這就是典型的「上下文污染與滾雪球崩潰」。

在 OpenCode 中，「代理（Agent）」並不是泛指所有的 AI 功能，而是一個擁有精確定義的架構概念：將特定的系統提示詞（System Prompt）、可用工具集、權限規則與底層模型，封裝成一個可隨時切換的身分。同一顆 AI 核心引擎，穿戴上不同的代理配置，就化身為承擔不同專職的工程夥伴。

四大內建代理與「先 plan 後 build」黃金律

OpenCode 預設提供四個專職代理，各司其職：

代理名稱	核心定位	檔案寫入權限	經典適用場景
build	主力開發者	✅ 可寫入 / 修改	實作新功能、修復 Bug、執行重構等一切需要「動手修改」的工程實作。
plan	架構顧問	❌ 嚴格唯讀	需求前期調研、技術選型評估、多方案利弊權衡與逐步實作計畫擬定。
explore	程式碼偵察兵	❌ 嚴格唯讀	快速回答「某個邏輯寫在何處」、「某個類別如何運作」等專案結構探索。
general	通用研究員	✅ 獨立子會話可寫	被主代理委託執行獨立的多步驟深度調查或專項執行任務。

此外，系統底層還配備了 compaction（自動壓縮上下文）與 title（自動總結會話標題）等內部隱藏代理，由系統背景觸發，無需手動干預。

初學者最常犯的重大失誤，就是把所有需求直接丟給 build 代理。正確的工程協作節奏永遠是「先 plan 後 build」：
1. 構思階段切至 plan：由於 plan 代理被刻意剝奪了寫入工具，它「只能思考，不能動手」。這不是功能閹割，而是對工作區的強力保護——無論 AI 如何大膽試探，絕不會在草案階段意外弄髒你的 Git 工作目錄。
2. 審核確認方案：架構顧問給出詳細的實作步驟、影響範圍評估與潛在風險預警。
3. 實作階段切至 build：拿著已確認的具體步驟清單，讓 build 代理依序精準動刀。

代理委託機制：守護上下文的防火牆

優秀的技術主管絕不事必躬親。主代理透過內建的 task 工具，可以隨時將繁瑣的子任務委託給其他代理，在完全獨立的子會話中執行，完成後僅將提煉後的結論回收至主對話。

這種「委託機制」的核心價值在於上下文隔離（Context Isolation）：
當你需要盤點整個專案中 30 個 API 端點的授權驗證方式時，若主代理親自搜尋，這 30 個檔案的大量無關代碼將瞬間塞爆主會話的 Context Window；而透過委託給 explore 代理，子代理翻山越嶺的探索雜訊全部被鎖定在子會話中，最終只回傳一份精簡的摘要表格給主代理。主會話始終保持清爽高智能，杜絕長對話智能劣化。

權限安全防禦：allow、ask、deny 三層防線

AI 的行動必須始終處於受控圍欄之中。OpenCode 在 opencode.json 的 permission 區塊提供嚴格的三層權限控管：
- allow：完全信任，直接放行，無需人工確認。
- ask：審慎放行，每次執行前彈出終端提示，由工程師按下確認後方可執行。
- deny：絕對禁止，直接阻斷，連詢問視窗都不跳出。

權限設定支援萬用字元（Glob），實戰配置範例：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow",
    "bash": {
      "git status": "allow",
      "git log*": "allow",
      "git push*": "ask",
      "rm -rf *": "deny",
      "npm test*": "allow",
      "*": "ask"
    },
    "webfetch": "allow"
  }
}

🧭 決策流程樹：第 03 章：代理系統 — 主代理與子代理協同架構

步驟化 SOP 實戰詳解

1. 觸發情境：啟動非平凡（Non-trivial）需求開發

識別訊號：凡是修改範圍超過單一函式、涉及系統核心架構變更、或是需求邊界尚不明朗的任務，嚴禁直接下令實作。
前期操作：先在終端切換或宣告使用 plan 代理：
```
/agent plan
```

2. 核心操作：「先 plan 後 build」標準協同程序

下達架構諮詢指引：在 plan 模式下要求評估：

我想為使用者模組加入 OAuth2 Google 登入功能：
1. 請盤點既有 auth 模組的進入點與相依性
2. 提出兩種實作架構並分析對現有 session 機制的影響
3. 列出具體可驗收的 4 個實作步驟清單

審查步驟與驗收指標：確認架構顧問輸出的步驟邏輯嚴密，無架構缺陷。

切換 build 逐步動工：切換為開發代理，並嚴格依據清單指派：

/agent build
請依照剛才產出的步驟 1，建立 Google OAuth 的資料表遷移檔與 Model 定義。

善用 task 工具分流繁瑣調查：當需要比對外部文件或專案多處殘留調用時，主動指示代理派工：「請委託 explore 子任務盤點所有呼叫了 legacy_login 的檔案」。

3. 踩坑避雷與防護指南

權限配置「從嚴起步，逐步放行」：初次配置新專案時，bash 工具一律預設為 ask。觀察數天確認常見的安全指令後，再將 git status、pytest 等加入 allow 白名單。切忌一開始全開 allow，把危險的 rm -rf 或強推遠端的隱患暴露在外。
避免在串流輸出中「肉眼盯梢」：終端串流速度極快，人類根本無法即時看清飛掠而過的指令細節。將防護完全交給 opencode.json 的 deny 與 ask 規則，以機器規則取代自以為是的目視檢查。
分清工作區環境級別：個人的玩具專案可以適度寬鬆，但企業級或連線生產庫的專案設定，必須嚴格配置專案層級的 permission 宣告。

行動檢核清單（Checklist）

掌握 build、plan、explore、general 四大內建代理的分工邊界
在複雜需求中落實「先 plan 後 build」的兩階段防護紀律
善用 task 子任務委託機制達成上下文隔離，防止 Context 膨脹劣化
在 opencode.json 中配置清晰的 allow、ask、deny 權限防線
嚴禁對破壞性指令（如 rm -rf 或強制推送）給予全局 allow 放行

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 04 章：工具系統 — 內建工具與權限防護

如果把代理系統比喻為大腦，那麼工具系統就是它伸向真實數位世界的雙手與手術刀。無論底層的大語言模型推理能力多麼登峰造極，若缺乏與作業系統、檔案體系與編譯環境互動的工具，它充其量只是一個善於言辭的聊天機器人。

然而，在日常使用中，你是否曾遇過這些痛苦的現象：
- AI 明明只要修改一個函式中的三行邏輯，卻偏偏把一個 2,000 行的檔案全部重寫一遍，導致所有格式與無關註解被破壞殆盡？
- AI 嘗試替換代碼時，常常因為縮排多了一個空格或引號是雙引號還是單引號，不斷跳出「找不到目標字串」的死循環？
- 讓 AI 去專案裡找某個函式，它直接把沿途所有的檔案全部讀進對話中，導致 Token 額度瞬間枯竭、反應變得極度遲緩？

OpenCode 深刻洞悉了這些工程痛點。它的內建工具家族經過極為克制的收斂，數量精煉卻具備極高的工程殺傷力，並在底層引入了優雅的「多層回退比對」與「供應商適配」黑科技。

內建工具五大分類

OpenCode 將工具體系嚴格劃分為五大維度，各具鮮明的權限屬性與防護要求：

工具維度	代表工具名稱	核心工程功能	權限屬性與安全管控
讀取類	`read`、`glob`、`grep`	檢視檔案內容、依檔名模式探索檔案路徑、以正規表示式搜尋內容。	唯讀安全操作，通常預設直接 `allow` 放行。
寫入類	`edit`、`write`	`edit` 負責局部精準片段替換；`write` 負責全檔建立或覆寫。	具變更副作用，受 `permission.edit` 規則嚴密約束。
執行類	`bash`	執行 Shell 指令：編譯測試、Git 操作、套件安裝與腳本運行。	唯一的任意副作用入口，受 `permission.bash` 最嚴格管控。
網路類	`webfetch`	抓取指定 URL 網頁或 API 內容，自動轉成純文字供代理分析。	外部通訊操作，受 `permission.webfetch` 控管防範資料外流。
委託類	`task`	派發獨立子任務給其他專職代理執行（如委託給 `explore`）。	權限動態繼承自被調用代理本身的權限矩陣。

高效探索的黃金組合：glob、grep 與 read 的分工

許多工程師誤以為 read 可以包辦一切。事實上，大檔案整檔讀入既浪費昂貴的 Context Window，又會大幅增加模型產生幻覺的機率。OpenCode 遵循精準打擊原則：
- glob 探尋路徑：依照檔名模式比對（如 src/**/*.service.ts），用於摸清架構版圖。
- grep 定位行號：依照正規表示式在全文搜尋關鍵字（如 class PaymentGateway），精準標記出所在檔案與行號範圍。
- read 切片讀取：拿到具體行號後，僅讀取關鍵片段前後 50 行，以最小的 Token 成本獲取最充份的上下文。

`edit` 工具的多層回退比對（Fallback Matching）

傳統代碼替換工具最大的盲點在於「剛性匹配」：模型的複製貼上往往存在縮排落差、行尾空白（Trailing spaces）或引號跳脫差異。如果堅持逐字元完全比對，大量合理的修改將無謂報錯；但若使用模糊匹配，又極易改錯相似區塊。

OpenCode 採用了一套多層回退比對機制：
1. 第一層：精確匹配（Exact Match） — 嚴格逐字元比對，保證最高精度。若失敗則自動降級重試：
2. 第二層：忽略縮排差異（Indentation-agnostic） — 只要相對縮排與代碼結構一致，忽略前綴空格差異。若仍失敗則降級：
3. 第三層：忽略跳脫序列與引號風格 — 容忍換行符號（CRLF vs LF）與引號格式的微差。
4. 第四層：報錯並請求人工確認 — 若三層皆無法唯一命中，立即拋出錯誤阻斷，絕不盲目猜測。

這套機制的哲學是：容忍無關緊要的格式噪音，但對「唯一命中目標區塊」絕不妥協！

供應商適配層：抹平模型的手感差異

不同大模型在生態中有各自偏好的編輯習慣。例如 OpenAI GPT 系列擅長以 apply_patch 補丁語法提出改動；Anthropic Claude 系列則習慣整塊替換的 edit 結構。

OpenCode 的供應商適配層（Provider Adaptation Layer）在內部抹平了這些差異。對外，使用者與上層代理面對的是統一的工具協定；而在底層，系統會依當前選用的模型自動轉換為最適配的調用語法，讓你在切換模型時毫無撕裂感，且所有日誌事件維持標準化格式。

🧭 決策流程樹：第 04 章：工具系統 — 內建工具與權限防護

步驟化 SOP 實戰詳解

1. 觸發情境：在大型既有專案中進行定位與修改

識別訊號：專案包含上百個檔案，需要找到某個關鍵設定常數並調整其邏輯。
操作原則：嚴格杜絕讓代理使用 read 全檔瀏覽；強制引導其採用「glob -> grep -> read -> edit」之標準鏈條。

2. 核心操作：標準搜尋與手術刀替換流程

結構探索與精準鎖定：

請先用 glob 找出所有包含 config 的檔案，接著用 grep 搜尋 MAX_RETRY_COUNT 的宣告位置。

切片檢視與邊界確認：

請僅 read 目標檔案該行號的前後 20 行，確認依賴模組與上下文關聯。

發起 edit 替換：
代理自動呼叫 edit 工具，提供唯一的目標舊文字區塊與新邏輯。若因微小縮排差異未命中，底層回退機制將自動平滑補正。
終端審查變更 Diff：
在 TUI 終端檢視即時 Diff，確認無多餘的行尾空白或不小心破壞的括號結構。

3. 踩坑避雷與防護指南

嚴防 bash 的破壞性副作用：bash 是唯一具備不受控執行能力的工具。絕對不要把 rm、git reset --hard 等指令設為 allow。若需要清理暫存檔，建議由工程師手動下達或透過自訂安全腳本執行。
多處命中陷阱：如果一個檔案中有多個相同的變數賦值，edit 工具會因為目標文字不具「唯一性」而主動報錯。此時應指示代理擴大選取舊代碼區塊（將上層函式標頭或相鄰程式碼一併納入），確保替換目標全域唯一。
避免用 write 取代 edit：除非是在建立全新檔案，否則修改既有代碼時嚴禁使用 write 全量覆寫。全量覆寫極易在模型輸出中斷時截斷檔案，造成無法挽回的代碼遺失。

行動檢核清單（Checklist）

掌握讀取（read/glob/grep）、寫入（edit/write）、執行（bash）等五大工具的分工
遵循「glob 摸清結構 -> grep 鎖定行號 -> read 切片閱讀」的上下文節流紀律
理解 edit 工具的三層回退匹配機制，明白其「容忍格式噪音、確保唯一命中」的底層邏輯
修改既有檔案堅持使用 edit，杜絕用 write 全量覆寫造成截斷事故
針對 bash 高危工具落實最小權限原則，嚴禁放行高破壞性 Shell 指令

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 05 章：技能系統 — 按需載入與知識封裝

每個成熟的工程團隊內部，都流傳著一些「不會寫死在代碼邏輯中，但每個新人都必須遵守」的隱性知識：
- 提交代碼時，Git Commit Message 必須符合 Conventional Commits 格式，且末尾要附帶 Jira 票號。
- 每次修改完 Python 代碼，在提交前必須依序執行 linter、格式化工具與單元測試。
- 呼叫內部金流服務時，必須遵循特定的加簽防重送演算法與超時重試機制。

傳統的做法通常是將這些規則寫進冗長厚重的內部 Wiki，或者靠資深工程師在 Code Review 時一次次心累地抓抓抓。而在使用 AI 時，許多開發者不得不每一次開新會話，就手動貼上一大段 Prompt 來「教育」AI，既麻煩又極易遺漏。

OpenCode 給出的工程級答案是技能系統（Skill System）：透過一份份標準化的 Markdown 文件，將團隊的工程知識封裝為「按需載入的作業指導卡」，讓 AI 在需要時自動觸發並嚴格落實。

`SKILL.md` 規範剖析

在 OpenCode 中，一支技能就是一個專屬資料夾加上一份 SKILL.md。其標準結構如下：

---
name: commit-helper
description: 產生符合團隊規範的 git 提交訊息。涉及 commit、提交訊息時使用。
---

# 提交訊息規範

1. 格式為 `<type>: <主旨>`，type 僅限 feat / fix / refactor / docs / test / chore
2. 主旨使用繁體中文，不超過 30 字，句尾不加句號
3. 內文說明「為什麼」而非「做了什麼」，空一行後撰寫
4. 有對應 Issue 時，內文末行加上 `Refs: #編號`

## 範例

feat: 支援報表匯出 CSV

訂單組需要原始資料做月結對帳，網頁列印無法滿足，
故新增後端直出 CSV 的匯出端點。

Refs: #482

YAML Frontmatter 中的兩個欄位是技能的靈魂：
- name：技能的唯一識別碼，必須採用小寫連字號命名（kebab-case），且必須與所屬的資料夾名稱完全一致。
- description：最重要的核心欄位。它是 AI 判斷「當前會話是否該載入本技能」的唯一依據。撰寫訣竅是「做什麼＋何時用＋自然嵌入觸發關鍵詞」。

正文部分則是標準 Markdown。編寫給 AI 執行的作業指導書，切忌空泛的形容詞，而應使用編號清單、明確的可執行指令與真實範例。

漸進揭露（Progressive Disclosure）：零上下文負擔的奧秘

如果系統在啟動時，將專案中的幾十支技能內容全部塞進 System Prompt，會話的 Context Window 將瞬間被撐爆，成本暴增且智能迅速劣化。

OpenCode 採用了精巧的漸進揭露架構：
1. 輕量索引註冊：系統啟動或對話開啟時，僅向大模型註冊所有技能的 name 與 description（每支技能僅消耗微薄的數十個 Token）。
2. 語意特徵偵測：當使用者的提問或當前任務語意精確命中了某支技能的描述情境時，模型才會動態發起調用，將該技能的完整正文即時讀入上下文照章執行。

這意味著你可以在專案中沉澱上百支專業技能，而在日常普通問答中，完全無需付出額外的上下文與計費成本！

雙層配置架構：專案共用與個人全域

OpenCode 支援專案級與全域級兩層技能存放路徑：

層級名稱	物理路徑位置	生效範圍與團隊版控策略
專案級技能	`.opencode/skill/<名稱>/SKILL.md`	僅在當前專案目錄生效。應一併提交至 Git 倉庫，作為全團隊統一共享的工程規範與落地標準。
全域級技能	`~/.config/opencode/skills/<名稱>/SKILL.md`	跨所有專案全局生效。適合放置個人偏好的程式習慣、日常輔助指令或私人專用工作流。

🧭 決策流程樹：第 05 章：技能系統 — 按需載入與知識封裝

步驟化 SOP 實戰詳解

1. 觸發情境：建立「Python 代碼修改後強制檢查」專案技能

痛點訊號：團隊常有成員（或 AI）改完 Python 代碼後未跑 linter 便直接提交，導致 CI 持續亮紅燈。
目標：讓 AI 只要改動 .py 檔案，便主動執行 ruff 與 pytest。

2. 核心操作：五分鐘上線第一支自訂技能

建立專屬目錄：在專案根目錄下建立對應的結構：
```
mkdir -p .opencode/skill/python-checklist
```

撰寫標準化 SKILL.md：建立 .opencode/skill/python-checklist/SKILL.md 並填入內容：

---
name: python-checklist
description: 修改任何 .py 檔案後的品質檢查程序。涉及編輯 Python 程式碼、跑測試、檢查語法時使用。
---

# Python 修改後檢查程序

每次完成 .py 檔案修改後，依序執行下列防護指令：

1. `uv run ruff check --fix <修改的檔案>`：修正所有可自動修復的語法問題
2. `uv run ruff format <修改的檔案>`：統一格式化代碼
3. `uv run pytest tests/ -x -q`：快速執行測試，任何失敗必須立即修復
4. 三步全綠才算完成；若測試無法通過，必須立即停止並回報，嚴禁略過測試

驗證觸發行為：
重啟 OpenCode 或開新會話，給它一個微小任務（例如：「請為 utils.py 新增一個加法函式」）。觀察 AI 改完代碼後，是否主動調用 bash 工具依序執行 ruff 與 pytest。

3. 踩坑避雷與防護指南

description 寫作太簡略導致「不觸發」：如果只寫 description: Python 檢查，AI 往往無法在「幫我改個函式」的語意中建立關聯。務必將具體情境與高頻動作（如「修改代碼」、「跑測試」、「.py 檔案」）完整埋入。
嚴防路徑與 YAML 語法低階錯誤：資料夾名稱必須與 frontmatter 中的 name 完全相同；YAML 中的冒號後面必須有空格（如 name: my-skill 而非 name:my-skill），否則解析失敗將靜默忽略該技能。
軟性技能與剛性指令的界線：技能屬於「以語意提高 AI 做對事的機率」的防線。如果某些流程必須「百分之百不可跳過」（例如正式部署生產環境），應進一步搭配第 12 章的自訂指令（Slash Commands）明確強制叫用，或透過 Git Pre-commit Hook 進行雙重硬性鎖定。

行動檢核清單（Checklist）

理解技能系統如何將團隊隱性規範轉化為 AI 可執行的 SOP
掌握 SKILL.md 的 YAML Frontmatter 必要欄位（name 與 description）
體會「漸進揭露」機制如何在兼顧數十支技能的同時守護 Context Window
明確區分專案級（.opencode/skill/）與全域級（~/.config/opencode/skills/）的存放場景
掌握技能調優心法：以明確關鍵字豐富 description、以步驟化指令撰寫正文

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 06 章：安裝與環境設定 — 跨平台部署與依賴

為什麼同一行指令在同事的機器上跑得行雲流水，到了你的 Windows 或 CI 容器裡卻頻頻噴出相依性錯誤？為什麼好不容易把 OpenCode 叫起來，終端機畫面卻滿地亂碼、圖示全變成問號方塊？

把安裝 OpenCode 比喻成「為一級方程式賽車搭建 Pit Lane 整備維修站」。再強勁的 AI 引擎，如果跑在一條充滿油漬與碎石的跑道上（缺少 Nerd Font 字型、終端未開啟真彩支援）、或者維修團隊給錯了混亂的油料規格（版本未釘死、個人與團隊設定打架）、甚至是把無人賽車丟進一個管線沒接好的密封貨櫃（Docker 遺漏工作目錄掛載或 API 金鑰），你的自主代理就只會在起跑線上打滑空轉。

本章補齊工程落地時的進階必備技術：四種跨平台安裝途徑的選型標準、版本鎖定與升級防護、容器化無狀態部署，以及用十分鐘打造低疲勞、高解析的現代終端環境。

🧭 決策流程樹：第 06 章：安裝與環境設定 — 跨平台部署與依賴

步驟化 SOP 實戰詳解

1. 觸發情境

新工作站或筆記型電腦開發環境建置。
團隊工程標準化：統一全員 OpenCode 執行版本，杜絕「在我電腦上是好的」行為差異。
搭建 GitHub Actions / GitLab CI 的自動化程式碼審查與測試缺口分析容器。

2. 核心操作

跨平台安裝選型與執行：
- Linux / macOS 獨立執行檔：
```
curl -fsSL https://opencode.ai/install | bash
```
- Windows 及 Node.js 開發者：
```
npm install -g opencode-ai
```
- macOS Homebrew 集中管理：
```
brew install opencode
```
團隊基準版本鎖定：
- 嚴禁生產專案使用 latest 浮動標籤，明確指定團隊共識版本：
```
npm install -g opencode-ai@1.18.21
opencode --version
```
- 升級評估SOP：先查閱官方 Release Notes 確認有無設定檔（Config Schema）破壞性變更，再手動執行 opencode upgrade。

無狀態 Docker 容器化執行：

核心兩要素：-v 雙向掛載工作目錄、-e 注入大模型供應商金鑰：

docker run -it --rm \
  -v "$PWD":/workspace -w /workspace \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  ghcr.io/opencode-ai/opencode:latest \
  opencode run "檢查這個專案的測試覆蓋缺口"

終端機環境 10 分鐘優化：
- 字型裝備：終端機必裝 Nerd Font（推薦 JetBrainsMono Nerd Font 或 FiraCode Nerd Font），徹底消除 TUI 檔案清單與 Git 符號方框問題。
- 柔和配色：在 TUI 輸入 /themes 即時切換預覽，選定後寫入全域設定檔 ~/.config/opencode/opencode.json：
```
{
  "tui": {
    "theme": "opencentured"
  }
}
```
- 終端模擬器建議：Windows 唯一推薦 Windows Terminal（搭配 WSL2 體驗最佳）；macOS 推薦 Ghostty、iTerm2 或 kitty。

3. 踩坑避雷與防護指南

解除安裝資料遺留避坑：
- opencode uninstall 會移除二進位執行檔與相關軟體鏈結。
- 若需保留珍貴的會話歷史與上下文日誌，請勿清空 ~/.local/share/opencode/ 目錄（內部儲存 SQLite 本地資料庫）；反之若需全新重置，需手動清理該資料夾。
Windows CP950 編碼踩雷：
- Windows 原生 CMD 預設編碼為 CP950，極易引發字元截斷與換行錯誤。強烈建議在 Windows Terminal 內使用 PowerShell 7+ 或 WSL2，並確保終端支援 24-bit TrueColor（真彩模式）。
容器權限與揮發陷阱：
- 容器執行時，若未加上 -w /workspace 與 -v "$PWD":/workspace，AI 產生的所有程式碼修改將只留在容器內層，容器結束時立即蒸發。

行動檢核清單（Checklist）

依作業系統生態選用正確安裝途徑（Windows 採 npm、macOS 採 brew 或腳本）
團隊內部文件明確釘死基準版本號（例如 @1.18.21），禁用浮動版本
終端模擬器已安裝啟用 Nerd Font，確認狀態圖示與 Git 分支符號無亂碼方塊
完成 /themes 視覺主題設定，確保長時間使用無高對比刺眼問題
CI/CD 容器部署已完整綁定工作目錄掛載與供應商 API 金鑰變數

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 07 章：專案初始化 — 專案配置與自訂指令集

同一個 AI 模型、同一套運算架構，為什麼在專案 A 能精準調用內部封裝模組、產出符合架構哲學的高品質代碼，但在專案 B 卻會胡亂覆寫已上線的資料庫遷移檔、拿浮點數計算金額，甚至擅自修改底層核心共用庫？差別從來不是運氣或隨機抽樣，而在於專案有沒有在進入點把「這裡的規矩與邊界」交待得清清楚楚。

把 AGENTS.md 與 .opencode/ 比喻成「新進工程師的入職作戰手冊與工牌門禁卡」。AI 代理不是通靈師，沒有入職指引，它就只能依靠從全網開源代碼學來的統計平均值來盲猜你的業務慣例；但如果你在門口發給它一份明確的專案作戰手冊與安全權限卡，它從敲下第一行代碼開始，就是完全熟悉你團隊技術棧的資深工程師。

這是全書投資報酬率最高的一章：AGENTS.md 解決代理的「長期認知」，.opencode/ 解決代理的「行動邊界與工具裝備」。

🧭 決策流程樹：第 07 章：專案初始化 — 專案配置與自訂指令集

步驟化 SOP 實戰詳解

1. 觸發情境

新專案剛完成 git init，準備導入 OpenCode 作為核心開發主力。
既有大型既有專案（Legacy Codebase）引入自主代理，急需建立安全防護隔離與架構導航。
團隊工程師發現 AI 反覆在某些技術邊界（如命名風格、單元測試規範、資料庫異動）犯下低級錯誤。

2. 核心操作

編寫 AGENTS.md 五大黃金骨架：
在專案根目錄建立 AGENTS.md，字元力求精煉且具強制約束力：

# AGENTS.md

## 專案概要
本專案為電商交易後端服務。採用 Go 1.22 + PostgreSQL 16 + Redis。
主要對外暴露 gRPC 與 REST API，部署目標為 Kubernetes 叢集。

## 常用指令
- 本地編譯：make build
- 單元測試：make test（等價於 go test -v -race ./...）
- 資料庫遷移：make migrate-up
- 代碼風格檢查：golangci-lint run

## 目錄導覽
- cmd/server/：應用程式進入點，僅做依賴注入與伺服器啟動
- internal/service/：核心業務領域邏輯，新功能代碼主要寫在這裡
- internal/handler/：傳輸層協定處理，嚴禁在此包含核心業務規則
- migrations/：僅允許新增遷移檔，已合併遷移檔絕對嚴禁修改

## 慣例與紅線
- 金額計算一律使用 shopspring/decimal 套件，嚴禁使用 float32/float64
- 修改既有代碼前，必須先跑 make test 確認基準為全綠通過
- 所有新增匯出函式（Exported Function）必須附帶繁體中文 docstring

## 驗收標準
- 本地 make test 全數通過且覆蓋率不低於 85%
- 新增業務功能必須同時提供表驅動測試（Table-Driven Tests）

配置專案層安全防護網 .opencode/opencode.json：
建立 .opencode/opencode.json，鎖死危險系統調用，團隊成員共享同一份安全邊界：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "allow",
    "bash": {
      "git push*": "ask",
      "rm -rf *": "deny",
      "make *": "allow",
      "*": "ask"
    }
  }
}

建立專案級資產結構：

.opencode/
├── opencode.json      # 專案層設定（權限優先覆蓋全域）
├── skill/             # 專案領域技能（如特定 API 串接規格）
├── agent/             # 特殊專用代理定義
└── command/           # 團隊高頻自訂捷徑指令

3. 踩坑避雷與防護指南

百科全書式過載陷阱：
- 嚴禁把整份數十萬字的系統架構書直接複製貼進 AGENTS.md。AI 需要的是高度濃縮的「規則手冊」，而非龐大的歷史文件；過長的上下文會稀釋注意力，導致關鍵紅線被忽視。
過期進度資訊污染：
- 嚴禁在 AGENTS.md 記錄 Sprint 待辦事項、個人 TODO 或暫時性進度（那是 Jira/GitHub Projects 的職責）。資訊一旦過期，將成為誘導 AI 產生幻覺的元兇。
- 嚴禁空泛口號，例如「保持程式碼優雅」毫無操作性；改為「函式行數不超過 50 行，圈複雜度不大於 10」方具實戰意義。
多層設定優先權踩雷：
- 全域設定（~/.config/opencode/opencode.json）代表個人操作習慣，專案層設定（.opencode/opencode.json）代表團隊規範。衝突時以專案層優先。
- 將 AGENTS.md 與 .opencode/ 納入 Git 進行版控，任何規範修改必須經過 Code Review。

行動檢核清單（Checklist）

儲存庫根目錄已建立 AGENTS.md 並包含五大黃金骨架區塊
常用指令已包含完整的建置、測試與 Linting 精確命令
專案核心紅線已明確標註（包含資料庫遷移與禁止使用的型別/語法）
.opencode/opencode.json 已封堵高危指令（如 rm -rf 設為 deny）
AGENTS.md 與 .opencode/ 已納入 Git 版控，確保新人 clone 即可零門檻上工

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 08 章：基本互動精修 — 提問模式與高效提示

為什麼當你隨口丟出一句「幫我修好這個 Bug」，AI 代理卻大動干戈改了十幾個完全不相干的模組，甚至擅自重構了整個狀態管理機制？為什麼在同一個對話框聊了十幾輪後，AI 開始變遲鈍、遺忘先前的設定，甚至給出前後矛盾的幻覺代碼？

把與自主代理的互動比喻成「在手術室為外科主刀醫師傳遞手術器械」。如果實習助手只在門口大喊一聲「快救人！」，主刀醫師只能依照本能狂亂翻找托盤；但如果你清晰指示「出血點在右腹第三肋下動脈側、預期止血壓力為 80 mmHg、請先遞上 4 號止血鉗，在我確認止血前絕對禁止動刀縫合」，整場手術就能在精準可控的節奏中完成。

與 AI 的互動品質直接決定了交付成果的上限。把 AI 當成一位極度聰明、程式功底深厚，但「對你目前專案架構完全陌生」的新同事——你怎麼在日常中帶新人，就該怎麼在終端中下指令。

🧭 決策流程樹：第 08 章：基本互動精修 — 提問模式與高效提示

步驟化 SOP 實戰詳解

1. 觸發情境

遭遇非預期例外或疑難 Bug，需要代理協助定位根因。
進行跨模組新功能開發，需要先進行技術架構規劃再動工。
前端 UI 與設計稿不符，需透過截圖快速對齊邊距、字級與配色。

2. 核心操作

有效提問的「四要素結構」：
遇到重大任務時，嚴格按照四要素組裝提示詞：

【現象】購物車在優惠碼疊加時金額計算錯誤，滿額 1000 元套用 9 折碼與免運碼後，預期折扣 100 元，實際只折抵 30 元。
【重現路徑】
1. 購物車加入 SKU-888 商品（金額 1000 元）
2. 輸入折扣碼 DISCOUNT90
3. 輸入免運碼 FREESHIP
【線索範圍】
核心計算邏輯應位於 src/cart/discount.ts，相關單元測試在 tests/cart/discount.test.ts。
【完成定義】
請先深入分析計算邏輯並向我回報錯誤根因，暫時絕對不要修改任何代碼。

三大黃金工程句型靈活套用：
1. 方案先行：「請先列出修改計畫與影響檔案，在我確認同意前不要動手改寫代碼。」（Plan-before-build 鐵律）
2. 決策留手：「如果針對快取失效有多種處理策略，請列出各自的效能、複雜度利弊，由我來決定最終選型。」
3. 閉環驗證：「修改完成後，請主動執行 npm run test:cart，用全綠的測試日誌向我證明修復完畢。」
圖片輸入的最佳實務：
- 支援將截圖路徑貼入或剪貼簿直接貼上至 TUI。
- 必須附帶文字約束與邊界：
  > 「附圖 checkout_error.png 為購物車跑版截圖。按鈕與文字重疊，請參考 src/components/Checkout.tsx 進行修正。注意：只調整 Tailwind 樣式，絕對不要更動資料流邏輯。」

3. 踩坑避雷與防護指南

「一句話派工」的毀滅性後果：
- 丟出「幫我修 Bug」等模糊指令，AI 為了嘗試修復會大規模搜尋整個專案，不但消耗數萬 Token，還極易誤解架構而引發全域代碼回退。
長對話 Context 滾雪球盲點：
- 當一個問題解決後，若接續討論另一個完全不相干的功能，舊對話的歷史錯誤日誌與廢棄代碼會持續充斥在上下文視窗中，引發嚴重的注意力稀釋與模型幻覺。
- 治理口訣：同一個任務的細節微調用「增量修正」（如：「方向對，但變數名改用 camelCase」）；任務一旦切換或完成驗收，立刻開闢新會話（或執行對話壓縮）。
長期規範與即時素材混淆：
- 長期團隊規則寫進 AGENTS.md，通用流程寫進 skill/，只有當次任務的日誌與截圖才在對話內臨時提供，嚴禁反覆在對話框手動張貼通用規範。

行動檢核清單（Checklist）

複雜任務提示詞已完整具備「現象、重現、線索、完成定義」四要素
涉及架構與多檔案變更時，強制加上「先說方案再動手」約束句
要求交付時明確約定「跑測試/建置命令」作為完成閉環證明
傳入截圖時已精準劃定「只調樣式、不動邏輯」的操作邊界
議題切換時主動建立新會話，嚴防 Context 滾雪球與記憶污染

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 09 章：LSP 整合 — 語言伺服器協議與型別感應

為什麼 AI 在網頁聊天室產出的程式碼看似邏輯嚴密、結構工整，但一貼進專案終端機，編譯器卻立即噴出幾十行型別不符或符號未定義的刺眼紅字？當你需要重構一個關鍵函式的參數型別時，代理如何保證散落在十幾個不同模組的調用點沒有被靜默改壞？

把傳統的檔案文字搜尋（Grep / Regex）比喻成「盲人摸象」，摸到了粗糙表面只知道它是一根圓柱，卻分不清那是大象的腿、羅馬柱還是枯木樹幹；而 LSP（Language Server Protocol，語言伺服器協定）則是「全身 3D 電腦斷層掃描（CT）」，它精確穿透表面文字，徹底掌握每一條型別定義、符號作用域與跨模組調用的深層神經網絡。

OpenCode 透過深度的內建 LSP 整合，讓自主代理在寫下代碼的當下，背後就站著一位嚴苛的編譯器專家。這一章拆解 LSP 的語意架構、零設定自動代管機制，以及如何利用「診斷回饋迴圈」讓低級語法錯誤在送達你面前之前就被自主消滅。

🧭 決策流程樹：第 09 章：LSP 整合 — 語言伺服器協議與型別感應

步驟化 SOP 實戰詳解

1. 觸發情境

進行跨模組重構（如修改核心實體屬性、更換函式參數型別）。
陌生代碼庫導航，需要釐清某個抽象介面在整個系統中的具體實作與呼叫分佈。
多語言混合專案（如 TypeScript 前端 + Python/Go 後端），杜絕跨模組介面調用落差。

2. 核心操作

LSP 四大語意能力盤點：
1. 即時診斷（Diagnostics）：在存檔瞬間提供型別檢查、未宣告變數與語法錯誤警告。
2. 定義跳轉（Go to Definition）：精確鎖定類別、函式與常數的真實聲明處，而非同名註解。
3. 引用查找（Find References）：找出專案內所有真正調用該符號的確切檔案與行號。
4. 符號大綱（Document Symbols）：快速解析檔案的層級骨架（Class, Interface, Method）。
零設定自動載入與狀態盤查：
- OpenCode 內建支援 40+ 種主流語言（Python 的 pyright、TypeScript 的 typescript-language-server、Go 的 gopls 等）。
- 在 TUI 終端隨時輸入指令檢查健康度：
```
/status
```
  確認各語言伺服器處於 Ready 狀態，避免在伺服器建立快取時盲目動手。
- 查看使用者決策紀錄檔：
```
cat ~/.config/opencode/lsp-install-decisions.json
```
驅動代理啟動「診斷回饋迴圈」：
在下達重構指令時，明確要求代理結合 LSP 驗證：
> 「請將 OrderService.checkout 的第二個參數改為 CheckoutOptions 物件。完成修改後，主動調用 LSP 診斷檢查所有調用點，確認全專案無任何型別錯誤後再回報。」

3. 踩坑避雷與防護指南

冷啟動索引空窗期陷阱：
- 大型百萬行單體架構在首次打開時，語言伺服器需要數十秒到數分鐘解析依賴並建立 AST 符號索引。
- 避坑原則：若在此時急躁下達修改指令，LSP 回報的資訊可能是殘缺的；務必先透過 /status 確認狀態已變為 Ready。
文字比對（Grep）的致命假象：
- 嚴禁放任代理使用純文字全域取代重命名變數。例如變數名為 id 或 status，grep 替換會將不相干的字串、SQL 片段或註解全數破壞；必須強制依賴 LSP 語意重命名或引用定位。
靜態無錯不等於動態正確：
- LSP 只能防守「編譯期與靜態型別」（Compile-time），無法察覺業務邏輯錯誤或執行期死鎖（Run-time）。
- 堅持「LSP 把關靜態、單元測試把關動態」的雙層防禦矩陣，兩者兼備才算驗收完成。

行動檢核清單（Checklist）

進入專案後已透過 /status 確認目標語言的 LSP 伺服器已正常載入且處於 Ready
重構跨模組符號前，要求代理透過 LSP 引用查找（References）掌握完整影響半徑
代理編輯代碼時已自動觸發診斷回饋迴圈，杜絕低級語意與拼寫報錯
靜態診斷全綠後，主動執行測試指令（如 pytest 或 go test）驗證執行期動態邏輯
多語言專案確認各語言伺服器各自獨立運作且未發生進程衝突

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 10 章：MCP 伺服器 — 模型上下文協議擴充

如果你的 AI 代理只能讀取本地磁碟上的純文字原始碼，那麼當工程需求涉及「查詢生產環境資料庫的真實 Schema 與索引」、「讀取 GitHub Issue 的驗收標準並直接在 PR 提交審查評論」、或是「驅動無頭瀏覽器抓取渲染後的網頁 DOM」時，難道你還要像人肉搬運工一樣，在資料庫管理軟體、瀏覽器與終端機之間來回手動複製貼上？

把 MCP（Model Context Protocol，模型上下文協議）比喻成「電腦主機的標準化 USB Type-C 擴充介面卡」。在過去，AI 工具要連接 N 個外部系統（GitHub、Notion、PostgreSQL、Figma），開發者必須編寫 M × N 次破碎且難以維護的特規 API 膠水代碼；而 MCP 帶來了即插即用的全球開放標準，將複雜度化簡為 M + N。OpenCode 作為 Host 主機，只要插上任何支援 MCP 的伺服器，對方的查詢能力與外部動作便能瞬間無縫納入代理的工具箱。

然而，擴充外部能力意味著系統副作用半徑的幾何級放大。本章拆解 MCP 的核心架構、本地與遠端傳輸模式、精確到萬用字元的權限防禦網，以及避免「工具過載稀釋」的選型法則。

🧭 決策流程樹：第 10 章：MCP 伺服器 — 模型上下文協議擴充

步驟化 SOP 實戰詳解

1. 觸發情境

任務需要依據真實資料庫的 Schema 結構進行 SQL 最佳化或 ORM 模型撰寫。
工單驅動開發（Issue-Driven Development）：讓代理直接讀取 GitHub / Linear 工單並在修復完成後更新狀態。
前端與 E2E 測試：透過 Playwright / Puppeteer 驅動瀏覽器抓取畫面或排查 UI 狀態。

2. 核心操作

傳輸模式選型與設定檔宣告：
在 opencode.json 中配置 mcp 模組：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/srv/shared_data"],
      "enabled": true
    },
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "enabled": true
    }
  }
}

CLI 快速管理與認證互動：
- 新增伺服器：opencode mcp add <名稱>
- 列出當前啟用列表：opencode mcp list
- 完成第三方 OAuth 登入：opencode mcp auth github
- 連線異常診斷：opencode mcp debug github

權限防禦網（Permission Guardrails）配置：
在 opencode.json 的 permission 區塊明確約束外部工具權限，萬用字元遵循 [伺服器]_[工具] 格式：

{
  "permission": {
    "mcp": {
      "github_list*": "allow",
      "github_create_issue*": "ask",
      "database_query*": "allow",
      "database_update*": "ask",
      "*_delete*": "deny",
      "*_drop*": "deny"
    }
  }
}

3. 踩坑避雷與防護指南

寫入型操作全域放行（盲目 allow）之禍：
- 嚴禁在未經實測前將資料庫或寫入型 MCP 設為 allow。寫入型操作一律從 ask 起步，由工程師在終端機人工按確認，觀察一週確認其行為軌跡符合預期後，方可針對特定唯讀操作升級。
高危權限外洩與 Token 膨脹：
- 為 MCP 建立 API Token 時，務必貫徹「最小權限原則」（Least Privilege）。若僅需讀取 Issue，嚴禁給予具備 Repository Admin 或全域刪除權限的 Token。含金鑰之設定絕對禁止提交進 Git 版控。
「工具過載」與決策稀釋陷阱（Tool Dilution）：
- 千萬不要把社群看到的幾十個 MCP 伺服器通通掛上去。每新增一個 MCP 工具，模型在思考時就需要閱讀該工具龐大的 JSON Schema 描述；工具過多不僅浪費大量 Context Token，更會造成模型推理混亂、引發「工具調用幻覺」。
- 黃金法則：日常專案保持 3 至 5 個核心高頻伺服器即可（如 Filesystem, GitHub, Database, Playwright），其餘低頻需求按需開啟。

行動檢核清單（Checklist）

依服務型態正確選用 local（stdio）或 remote（HTTP/SSE）傳輸機制
外部服務 Token 嚴格遵循最小權限原則，敏感設定已妥善隔離於環境變數
permission.mcp 已配置精確門禁，高危刪除操作（如 *_delete*）已設為 deny
寫入與修改型動作預設採用 ask 人工確認機制，杜絕靜默覆寫
專案掛載之 MCP 伺服器總數控制在 3~5 個高頻工具內，避免決策稀釋

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 11 章：會話管理 — 上下文控制與歷史復原

你是否曾經歷過這種挫折：一早開啟終端機與 AI 協同，從「修復登入逾時 Bug」一路聊到「重構購物車折抵」，到了下午，AI 開始語無倫次、丟三落四，甚至把早上剛寫好的函式當作垃圾刪除？或者當一條重構思路走到死胡同，你想退回兩小時前的狀態，卻發現對話歷史已被幾十層除錯雜訊淹沒，進退兩難？

新手把會話（Session）當成「無限延長的草稿紙」，把所有大小任務塞進同一個上下文；而頂尖工程師則把會話當成「精密的組裝產線」——一條產線只交付一個明確目標。會話不僅是聊天視窗，更是包含對話歷史、工具呼叫、檔案快照與權限狀態的獨立執行單元。

掌握會話管理的核心，在於上下文隔離、分岔回溯（Forking）與資產化攜帶。當你學會像分支管理程式碼一樣管理對話，AI 代理就能隨時保持在最高專注度，不再受歷史雜訊污染。

🧭 決策流程樹：第 11 章：會話管理 — 上下文控制與歷史復原

步驟化 SOP 實戰詳解

1. 觸發情境：啟動多會話並行與 Worktree 隔離

核心操作：
1. 分頁快速切換：在 TUI 介面中按 <Tab> 即可快速開啟空白乾淨的新會話；輸入 /sessions 可瀏覽所有歷史會話並切換。
2. CLI 命名指定：養成開會話即命名的紀律，避免充斥難以辨識的隨機時間戳：
```
opencode run --title "修購物車折抵Bug" "排查 CartService 中的折扣計算邏輯"
```
3. 目錄實體隔離：若需要同時開多個終端分頁並行跑不同任務，嚴禁讓兩個會話在同一個工作目錄寫入程式碼。正確做法是利用 git worktree：
```
git worktree add ../feature-checkout feature/checkout
cd ../feature-checkout && opencode
```
踩坑避雷與防護指南：並行提速的本質是「利用代理跑長測試或建置的等待時間推進另一件事」。若多個會話都需要你高頻做架構裁決，只會導致工程師注意力碎片化與嚴重返工。

2. 觸發情境：平行宇宙探索 — `--fork` 分岔實驗

核心操作：
1. 當遇到架構分歧（例如猶豫要採用「繼承」還是「策略模式」），切勿在原對話反覆推翻修改：
```
opencode session list
opencode run --fork --session ses_c4a89 "換個方向：改用策略模式重構折扣邏輯"
```
2. --fork 會從原會話的當前時間節點複製出一條全新的平行分支，保有所有前置探索背景，但之後的所有對話與修改完全獨立。
踩坑避雷與防護指南：分岔探索後，擇優保留其中一條路徑，並對失敗的路徑進行 git worktree remove 或清理檔案，避免留下多套未完成的爛尾程式碼。

3. 觸發情境：會話協同共享與成本資產化

核心操作：
1. 一鍵生成診斷頁面：遇上棘手 Bug 需要同事支援時，在 TUI 輸入 /share，OpenCode 會將完整對話、推導步驟與 diff 封裝為只讀網頁，直接將網址貼在 PR 或 Slack。
2. 事件序列導出與遷移：需要跨機器轉移上下文或存入企業知識庫時：
```
opencode export ses_c4a89 > bug-analysis.json
opencode import bug-analysis.json
```
3. 消耗審計：週期性執行 opencode stats，檢查每個專案與會話的 Token 用量及成本分佈，及時調整高耗能模型的分配策略。
踩坑避雷與防護指南：在涉及機密金鑰或敏感客戶資料的企業專案中，嚴禁公開使用 /share；應於全域或專案設定中明確禁用分享端點，改以內網匯出 JSON 審查。

行動檢核清單（Checklist）

養成任務前開新會話習慣，絕不將無關工作揉入既有會話
執行平行任務時，已透過 git worktree 建立實體檔案隔離防線
遇到重大重構分歧時，主動使用 --fork 建立對話分支，保留原始回退點
定期執行 opencode stats 審查 Token 成本，防範異常死循環開銷
在 PR 提交時，將重要決策會話（/share 或匯出檔）作為佐證資料留存

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 12 章：設定系統 — 優先順序與分層配置

許多開發者在調校 AI 工具時常會遇到令人費解的幽靈現象：明明在全域設定裡指定了輕量便宜的模型，為何一進專案又被切換成高資費模型？為什麼辛辛苦苦寫好的自訂工具，隊友 pull 下來後卻完全沒有生效？當多個設定來源交織在一起時，到底由誰來拍板定案？

OpenCode 的設定系統哲學是「開箱即用，但允許深度雕琢」。它就像一套「軍事指揮體系」——越靠近當前執行現場的指令，權限層級越高。從最底層的內建預設，到最高層的終端 CLI 旗標，共有七層覆蓋順序。

理解這七層架構，不僅能讓團隊共識（如程式碼審查規範、權限白名單）透過版控自然落地，更能讓你隨心所欲地將重複性流程封裝為「自訂斜線命令（/command）」，打造完全符合個人工程手感的終端作業中樞。

🧭 決策流程樹：第 12 章：設定系統 — 優先順序與分層配置

步驟化 SOP 實戰詳解

1. 觸發情境：專案級規格化配置與 Schema 宣告

核心操作：
1. 在專案根目錄建立 .opencode/opencode.json，第一行務必宣告官方 JSON Schema，取得編輯器欄位補全與型別防錯：
```
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-3-5-sonnet-20241022",
  "permission": {
    "allow_shell": ["git status", "npm test", "uv run pytest*"],
    "deny_shell": ["rm -rf *", "drop database*"]
  }
}
```
2. 版控納管：將 .opencode/ 目錄提交至 Git，確保團隊所有成員、CI 機器人與新進同事享有完全一致的代理防護標準。
踩坑避雷與防護指南：切勿將個人 API 金鑰寫入 .opencode/opencode.json。專案設定檔屬於公共資產，敏感金鑰一律留存於本機環境變數或不受版控的 .env 中。

2. 觸發情境：將繁複流程固化為「自訂斜線命令」

核心操作：

建立專案專屬指令：在 .opencode/command/ 下建立 Markdown 檔案，檔名即為命令名稱（例如 review.md 對應 /review）。

撰寫具結構約束的指令內容：

---
description: 全面審查未提交變更並產出風險評估報告
---
請以資深架構師視角檢查目前的 git 未提交變更：
1. 逐檔列出修改摘要與潛在破壞性風險（高/中/低）
2. 檢查邊界條件處理與型別宣告完整度
3. 比對是否具備對應測試，缺少則給出建議測試案例
4. 僅提供審查建議，嚴禁直接修改任何原始碼。

在 TUI 中輸入 /review 即可一鍵喚醒高品質審查。

踩坑避雷與防護指南：區分「自訂指令（Command）」與「技能（Skill）」——指令是用戶顯式主動叫用的固定 SOP，技能則是代理自主按需比對觸發的背景知識，兩者切勿混為一談。

3. 觸發情境：設定衝突排查與快捷鍵改造

核心操作：
1. 七層排查法：當設定未按預期生效時，請依據話語權大小「由上而下（7 到 1）」逆向審核：
  - 第 7 層：終端 CLI 旗標（--model, --verbose）
  - 第 6 層：特定代理/模式定義（Agent override）
  - 第 5 層：--config 外部指定檔案
  - 第 4 層：專案設定（.opencode/opencode.json，專案層級永遠壓過個人層級）
  - 第 3 層：XDG 相容環境變數
  - 第 2 層：全域個人設定（~/.config/opencode/）
  - 第 1 層：系統內建預設值
2. 高頻快捷鍵改裝：於 ~/.config/opencode/tui.json 綁定高頻操作：
```
{
  "keybinds": {
    "leader": "<a-x>",
    "switch_agent": "<leader>a",
    "session_new": "<leader>n"
  }
}
```
踩坑避雷與防護指南：快捷鍵改造切忌貪多，先記錄自己一週內每天點擊超過 10 次的動作，精準映射至最舒適的鍵位。

行動檢核清單（Checklist）

專案設定檔已配置 $schema 以防手民誤植欄位
專案級共識（工具、安全白名單）已納入 .opencode/ 並提交 Git
敏感憑證一律透過環境變數隔離，未洩漏進設定檔
將團隊高頻 SOP 提煉為 /command，減少提示詞重複打字
熟記七層覆蓋順序，排查問題由最外層 CLI 旗標與專案檔查起

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 13 章：IDE 整合 — VS Code 外掛與介面聯動

終端機是工程師最純粹的高速公路，但當面臨跨檔案複雜重構、逐行比對幾十處 diff，或是需要與圖形化偵錯面板協同作業時，純終端介面有時難以提供直觀的視覺張力。反之，如果每換一套編輯器就得重新配置 AI 助手、重載上下文，開發心流勢必支離破碎。

OpenCode 的核心優勢在於其主從式解耦架構（Client-Server Architecture）。終端 TUI、VS Code 外掛、JetBrains 面板或 Neovim 插件，本質上都只是同一顆後端引擎的「不同外殼」。你在終端機開啟的任務會話，下午切換進 VS Code 可以無縫接續，所有的記憶、修改紀錄與工具狀態完全互通。

本章將剖析三大主流編輯環境的整合方案，並介紹標準化代理協議 ACP（Agent Client Protocol），助你在圖形化審閱與終端機極速生產力之間取得完美平衡。

🧭 決策流程樹：第 13 章：IDE 整合 — VS Code 外掛與介面聯動

步驟化 SOP 實戰詳解

1. 觸發情境：VS Code 與 Cursor 的分割視圖視覺審查

核心操作：
1. 在擴充套件市集搜尋 OpenCode 一鍵安裝（Cursor 完全相容 VS Code 插件架構）。
2. 喚起 OpenCode 分割面板：左側展示即將變更的程式碼檔案，右側保持代理對話交談區。
3. Diff 行級裁決：當代理提議修改程式碼時，左側編輯器會即時標註色彩對比（綠色新增、紅色刪除），直接點擊 [接受] 或 [拒絕] 完成細緻把關。
4. 共享會話銜接：若早上在 CLI 下達了長任務，打開 VS Code 外掛面板直接於 Session 清單點選該會話，即可在編輯器內查看生成過程。
踩坑避雷與防護指南：在 IDE 接受 diff 之後，若有手動微調代碼，建議在右側對話視窗簡短回報「我手動調整了變數命名」，避免 AI 代理在後續推論中產生認知落差。

2. 觸發情境：JetBrains 家族原生工具鏈無縫嫁接

核心操作：
1. 在 IntelliJ IDEA、PyCharm 或 WebStorm 的 Plugin Marketplace 搜尋安裝 OpenCode。
2. 外掛會自動停靠於右側工具列，與專案的 Git 版本控制、終端機面板並列共存。
3. 比對檢視會自動調用 JetBrains 強大的原生三方對比視窗，保留你最熟悉的快捷鍵組合與代碼高亮習慣。
踩坑避雷與防護指南：JetBrains 系列外掛的更新發布節奏通常略晚於終端 CLI 版本。若需要使用最新的實驗性代理旗標或 MCP 工具，建議保留終端 TUI 作為快速切換的後備武器。

3. 觸發情境：Neovim 與 Emacs — 走開放標準 ACP 協議

核心操作：
1. 啟動 ACP 服務端點：在終端機執行：
```
opencode acp
```
2. 編輯器客戶端串接：
  - Neovim：配置社群 ACP 外掛（如 CodeCompanion），將端點指向本地運行的 ACP 進程。
  - Emacs：使用 gptel 或專用 ACP package 建立連線。
3. 這意味著你不需要依賴閉源商業編輯器，只要任何客戶端實作了 ACP 規範，就能享有完整語意上下文與工具呼叫能力。
踩坑避雷與防護指南：ACP 走標準 JSON-RPC / 標準輸入輸出傳輸，若遇到連線逾時，先檢查本地防火牆是否有攔截本機通訊埠，或確認 opencode 是否為最新版本。

行動檢核清單（Checklist）

確立任務分工：細緻比對 diff 用 IDE 分割視圖，長任務批次跑用終端 TUI
善用「主從架構」特性，在終端與 IDE 間無痛接續同一會話上下文
VS Code / Cursor 使用者熟練運用分割視圖之 Accept / Reject 快捷操作
終端派開發者掌握 opencode acp 標準協議，保有客製化設定主控權
手動修改代碼後，及時在對話中同步背景，確保代理認知與實體代碼一致

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 14 章：程式碼探索與理解 — 陌生專案巡航策略

在軟體工程現場，最考驗工程師功力的場景往往不是「從零寫全新功能」，而是「接手一個數萬行、沒有文檔的前人遺產代碼庫」。如果你試圖從第一行逐檔翻閱，不出半天就會陷入資訊過載的泥淖；若完全依賴直覺修改，更可能觸發隱蔽的副作用與架構災難。

面對陌生專案，正確的做法是將 AI 當成「全天候待命的資深引路人」。OpenCode 提供了專屬的唯讀子代理 explore，它能像無人偵察機一樣在專案上空盤旋，為你繪製全景地形圖，並沿著具體業務脈絡抽絲剝繭。

本章將提供一套標準化、高重現性的「四步巡航法」與「三項依賴健檢」，助你在半小時內建立足夠動手修改的精確心智模型，同時恪守「信任但要驗證」的工程防線。

🧭 決策流程樹：第 14 章：程式碼探索與理解 — 陌生專案巡航策略

步驟化 SOP 實戰詳解

1. 觸發情境：初次 Clone 專案之四步快速巡航

核心操作：
1. 先跑起來，再談理解：切勿一開始就陷入原始碼細節。先讓代理閱讀說明文件並給出啟動處方：
  > 「剛 clone 這個專案。請讀一下 README 和設定檔，告訴我本地啟動需要哪些前置依賴（資料庫、Node/Python 版本、環境變數？），並列出你建議的啟動步驟。」
2. 調用 explore 代理繪製三分鐘全景圖：
  > 「切到 explore 代理。掃描這個儲存庫，回答：1. 技術棧與主要框架版本 2. 頂層目錄各自的職責（一句話一個） 3. 程式進入點在哪 4. 有無明顯的分層架構（如 Clean Architecture 或 MVC）？」
3. 沿著一條主業務走到底（強調帶檔名與行號）：
  > 「追蹤『使用者送出購物車結帳』的完整呼叫鏈：從 HTTP 路由進來後經過哪些 Controller/Service、寫入哪些資料表、發送哪些事件？輸出成一份帶精確檔案路徑與行號的步驟清單。」
4. 沉澱資產進版控：將探索所得更新至 AGENTS.md 的專案導覽章節，避免下次 AI 重新耗費 Token 摸索。
踩坑避雷與防護指南：explore 是唯讀代理，委託給它的大規模檢索雜訊會被隔離在子會話中，不會污染主對話視窗。

2. 觸發情境：架構腐化排查與循環依賴健檢

核心操作：
1. 依賴方向逆流檢查：在分層架構中，最忌諱底層核心引用外層介面：
  > 「檢查 internal/domain/ 目錄下是否有任何檔案 import 了 internal/api/ 或 internal/infra/？若有，列出完整清單與行號，標註違反架構原則之處。」
2. 循環依賴視覺化偵測：
  > 「分析 src/modules/ 下各模組間的引用關係，若存在 A -> B -> A 等循環引用，請用純黑白 Mermaid 圖畫出環狀路徑並提出解耦建議。」
3. 改動影響受害面評估：
  > 「我想把 PaymentGateway 的 process() 介面參數增加一個貨幣欄位，請結合 LSP 引用分析，列出全專案所有直接與間接呼叫的檔案與行號。」
踩坑避雷與防護指南：修改核心抽象介面前，務必利用 LSP 做全域交叉校驗，切勿單憑全文搜尋（Regex Search）臆測影響範圍。

3. 觸發情境：實踐「信任但要驗證」的審查原則

核心操作：
1. 無出處即無效：凡是 AI 給出的架構論斷（例如「該模組使用 Redis 實作分散式鎖」），若沒有附帶具體檔案名稱與行號，一律要求補齊：「請指明該邏輯在具體哪個檔案的哪幾行實現？」
2. 抽查關鍵假設：隨機抽查 AI 指出的 2~3 處程式碼行號，確認是否與本地實體代碼一致。
3. 重大決策親自過目：對於資料庫遷移腳本、高併發鎖機制與金鑰傳遞路徑，無論 AI 解釋得如何頭頭是道，人類工程師必須親自肉眼閱讀對應原始碼。
踩坑避雷與防護指南：AI 容易對結構產生過度自信的幻覺。強制其在回應中輸出行號，是逼迫代理在底層確實呼叫工具讀取原始檔案的最佳制約手段。

行動檢核清單（Checklist）

遵循「先跑起來、再談理解」原則，確認本地服務已成功啟動
善用唯讀的 explore 代理進行全域掃描，避免污染主對話脈絡
追蹤核心業務流程時，強制要求輸出帶檔名與行號（path:line）之調用鏈
動手修改前已完成依賴反轉健檢與循環依賴掃描
堅持「信任但驗證」底線，抽查關鍵行號並將理解沉澱至 AGENTS.md

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 15 章：功能開發 — 規範驅動與循序漸進

功能開發是 AI 程式輔助最耀眼的舞台，卻也是實務上最容易引發翻車災難的重災區。翻車的根本原因往往不是模型智商不足，而是「工程流程失控」——直接對 build 代理下達「做個 CSV 匯出功能」，等於將「架構選型」、「改動邊界」、「異常防護」與「驗收標準」全部讓渡給 AI 的隨機直覺。其結果通常是：AI 興奮地順手重構了周邊五個模組、引進不必要的肥大依賴，最後留下一地無法通過編譯的爛攤子。

合格的工程開發就像一場嚴謹的外科手術：動刀之前必須先做詳細的術前會診。在 OpenCode 中，這條鋼鐵紀律體現為「Plan 模式先行」與「小步快跑迭代」。

本章將傳授如何運用三層提示詞結構引導唯讀的 plan 代理輸出高品質工程藍圖，並透過四道審查防線與收尾三部曲，確保每一次功能交付都精準、可控且具備百分之百的測試防護。

🧭 決策流程樹：第 15 章：功能開發 — 規範驅動與循序漸進

步驟化 SOP 實戰詳解

1. 觸發情境：Plan 模式需求結構化提煉（三層結構法）

核心操作：
1. 切換為唯讀代理：切入 plan 代理，其天生具備唯讀屬性，絕不會擅自變動實體代碼，專注產出可供審查的工程文件。
2. 提示詞三層結構範本：
  > 【需求】：訂單列表頁面需要支援匯出 CSV 功能。
  > 【背景】：目前列表由 OrderListPage.tsx 調用後端 /api/orders 分頁端點呈現。
  > 【限制】：
  > - 單次最多匯出上限為 5,000 筆資料。
  > - 匯出欄位必須與目前畫面展示的表頭欄位完全一致。
  > - 由後端直接串流輸出（Stream），嚴禁前端在記憶體拼接巨大字串。
  > 【輸出要求】：請產出完整實作計畫，包含：擬修改檔案清單、各檔案改動摘要、單元測試規劃、以及你預見的風險點。先不要修改任何代碼。
踩坑避雷與防護指南：如果提示詞沒有限制「不要動代碼」，某些代理可能會迫不及待地直接產出半成品，務必在文末重申審查原則。

2. 觸發情境：工程實作計畫之四道審查防線

核心操作：
在核准 Plan 代理產出的計畫前，人類工程師必須逐項過濾以下四個檢查點：
1. 改動範圍合理性：是否改動了超出預期的無關檔案？如果預期只改 2 個檔案卻列出 7 個，通常代表 AI 理解失焦。
2. 測試計畫具體性：空泛的「補寫測試」一律打回重寫；必須具體標明測試檔名與測試邊界（例如：「建立 tests/test_order_export.py，覆蓋零筆訂單、欄位跳脫、與達 5,000 筆上限截斷案例」）。
3. 風險評估誠實度：宣稱「毫無風險」的計畫極不可信；合格的計畫會誠實揭露記憶體峰值、連線逾時或舊版相容性風險。
4. 嚴查偷渡重構（Scope Creep）：順手修改變數名稱或搬移目錄是 AI 的天性，計畫階段發現必須立即斬斷。
踩坑避雷與防護指南：在計畫審查階段多花 2 分鐘，能為後續除錯節省 2 小時。

3. 觸發情境：迭代小步快跑與收尾三部曲

核心操作：
1. 前置驗收指令：切回 build 代理時，在下達步驟的同時明訂驗收標準：
  > 「照計畫執行第 1 步（後端端點串流）。完工判定條件：執行 uv run pytest tests/test_order_export.py -q 測試全綠，且 curl -I http://localhost:8000/api/orders/export 回傳正確 Content-Type。」
2. 單步快照提交：每完成一個步驟且驗證通過，立即要求建立 Git Commit。
3. 遇異狀立即煞車：若實作中發現既有代碼邏輯與計畫不符，代理必須立即停止並回報，嚴禁自作主張繞路修改。
4. 收尾三部曲交付：
  - 全量測試防護：執行全專案全量測試套件，確保新代碼未破壞任何既有功能。
  - 真人走廊測試：工程師親自在瀏覽器或 Postman 點擊實測一趟真實流程。
  - 語意化提交日誌：彙整 commit 歷史，依 Angular/Conventional Commits 規範提交 PR。
踩坑避雷與防護指南：切勿僅跑新寫的測試；很多回退（Regression）往往發生在未被修改卻間接相依的舊模組中。

行動檢核清單（Checklist）

堅持「先 Plan 後 Build」，未審查通過計畫絕不動刀修改代碼
提示詞具備「需求、背景、限制」三層結構，限制條件清晰明確
通過四道計畫防線審查，嚴格攔截範圍膨脹與偽造的空泛測試
開工前已將具體驗收指令前置，步步驗證並及時保存 Git 快照
交付前完成收尾三部曲（全量測試、人工驗證、規範提交）

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 16 章：程式碼重構 — 安全重構流程與防護

你是否曾遇到過這種驚悚場面：請 AI 幫忙「把這個兩千行的控制器整理乾淨」，它在三十秒內重構了模組、抽出了七個類別，還貼心地回報「所有測試均通過」；直到系統上線，訂單金額全部變成零，你才驚覺它不僅修改了邏輯，甚至順手把斷言失敗的測試代碼也改了？

在軟體工程中，重構的定義始終是「在不改變外部可觀察行為的前提下，改善程式碼內部結構」。這聽起來簡單，但在自主代理的時代，重構卻是翻車率最高的深水區。

AI 代理就像一位手腳快如閃電但缺乏痛覺神經的外科醫生。只要你沒有架設好連續心電圖（行為特徵測試）並釘死安全防線（Git 快照與測試凍結令），它很容易在整理血管時順手切斷動脈。要駕馭 AI 完成高品質重構，關鍵不在於祈求模型變聰明，而在於建立鋼鐵般的工程紀律：精準分級重構策略、測試裁判絕對凍結、小步遷移與嚴禁行為夾帶。

🧭 決策流程樹：第 16 章：程式碼重構 — 安全重構流程與防護

步驟化 SOP 實戰詳解

1. 依風險光譜劃分重構策略

觸發情境：準備對既有代碼進行清理、模組解耦或架構調整。
核心操作：
1. 機械式重構（低風險）：如變數方法改名、檔案搬移、局部抽取共用函式。直接委託代理執行，並強烈要求利用 LSP 語意感知（References / Rename）確認所有下游引用同步更新，最後執行測試驗證。
2. 結構性重構（中風險）：如收斂跨模組邏輯（例如將散落於多個 Handler 的驗證規則集中至 Validator 模組）。在 Prompt 中明確要求「拆成可獨立驗收的遷移序列」，一次只搬移一個 Handler，搬完立即跑測試並 commit。在指令中必須明示：「這次是純搬家，中途不得順手修改任何業務語意」。
3. 行為邊界重構（高風險）：涉及 API 介面協議更換、資料結構翻新。嚴禁直接改碼；第一步必須要求代理針對既有行為撰寫特徵測試（Characterization Test），將邊界條件與現有輸出完全鎖定，確認測試全綠後才核准重構。
踩坑避雷：切勿將「代碼重構」與「功能修訂/修 Bug」混在同一批變更中。混合變更會讓 Code Review 陷入噩夢，一旦線上出事更無法藉由二分法定位根因。嚴格要求拆成兩個獨立 PR！

2. 架設雙層防護安全網

觸發情境：在敲下重構的第一行指令之前。
核心操作：
1. 第一層（Git 快照路標）：確保工作區完全乾淨（git status 無未追蹤或未提交修改），建立專用分支（如 git checkout -b refactor/order-validator）。重構中嚴格遵循小步提交紀律，每完成一個遷移單位即 commit 一次，形成密集且可單步回退的里程碑。
2. 第二層（測試裁判絕對凍結）：在重構開始前，向代理宣讀不可逾越的紅線：「重構全程 tests/ 目錄絕對凍結，禁止做任何修改。任何測試失敗皆視為你的代碼引入了非預期行為變化，必須修改業務代碼修復，嚴禁修改測試。」
避雷指南：防範 AI 的典型「假通過」陷阱——當代理重構後測試報錯，它常會擅自推斷「是測試程式寫得太死板」，進而竄改測試斷言讓它變綠。凍結測試是杜絕此類靜默劣化的唯一真理。

3. 推進遷移序列與故障熔斷機制

觸發情境：執行多步驟結構性重構時。
核心操作：
1. 單步推進：按照規劃序列逐一實作，每一步皆由凍結的測試套件進行機器判定。
2. 故障熔斷處置：若重構過程中測試轉紅且 AI 在連續兩次修正內無法復原全綠，立即停止盲目嘗試。
3. 快照回退：使用 git checkout . 或 git reset --hard HEAD 直接還原到上一版乾淨的 commit 快照，避免在污染的代碼堆上繼續滾雪球。需要跨步定位時，搭配 git bisect run <test-command> 精確揪出引入問題的提交節點。

行動檢核清單（Checklist）

當前任務已被精確分類為機械式、結構性或行為邊界重構
工作區已提交乾淨並已切出獨立重構分支（refactor/*）
針對行為邊界更動，已預先補齊特徵測試並維持 100% 通過
已在提示詞或全域規範中明確宣告「測試套件凍結，嚴禁修改 tests/」
重構過程嚴格落實「純搬家」，與新功能修改徹底拆分獨立 PR

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 17 章：除錯與問題修復 — 根因定位與驗證閉環

當線上系統突然噴出 500 錯誤時，工程師最常見的反射動作是什麼？把整段 Stack Trace 複製貼進 AI 對話框，然後敲下一句：「幫我修好它」。

結果往往是一場災難：第一輪對話，AI 自作主張加了個全域 try-except 吞掉例外；第二輪對話，它把資料庫連線逾時改大十倍；到了第三輪，它開始胡亂修改業務邏輯，整個系統被改得面目全非，而真正的 Bug 卻依然安好無恙。

除錯是衡量工程師駕馭 AI 功力的終極試金石。

面對同一個 Bug，頂尖高手只需三個精確回合就能直搗核心；新手卻會帶著 AI 在迷宮裡兜圈子、越陷越深。這個巨大落差的根本原因不在於背後的大模型有多聰明，而在於你有沒有逼迫 AI 遵循嚴謹的「科學方法」。

一流的名醫絕不會在病人剛喊胃痛的瞬間就立刻開止痛藥，因為壓制症狀往往會掩蓋真正致命的病灶；名醫會先觀察體徵、提出多種可能病因、安排成本最低的檢驗，確認根因後才精準下刀。在 OpenCode 的除錯實戰中，第一條也是最重要的一條鋼鐵律法是：診斷與治療必須徹底分離。

🧭 決策流程樹：第 17 章：除錯與問題修復 — 根因定位與驗證閉環

步驟化 SOP 實戰詳解

1. 組裝症狀最小完備集（五件套）

觸發情境：發現程式行為異常或接獲錯誤回報。
核心操作：向代理提供線索時，禁止只丟一張截圖或一句「不能動」。必須給齊症狀五件套：
1. 預期行為：清晰描述理想狀態（例如「點擊結帳應建立訂單並轉導成功頁」）。
2. 實際行為：客觀描述異常現象（例如「前端持續轉圈，後端回傳 500 內部錯誤」）。
3. 精準重現步驟：具體操作路徑與 Payload（例如「在地址欄位輸入包含雙引號的特殊字元後點擊提交」）。
4. 運作環境：本地 Docker、Staging 還是 Production，何時開始出現。
5. 已知變化（破案捷徑）：最近合併的 PR、升級的依賴或修改過的設定（80% 以上的 Bug 來自近期變更！）。
踩坑避雷：切勿提供終端截圖，截圖無法被代理作為純文字搜索引用。長日誌應重導向至實體檔案（如 docker logs api > /tmp/api.log），讓代理利用檔案讀取工具精確檢索。

2. 下達科學診斷指令（禁止直接開藥）

觸發情境：在開始任何代碼修改前。
核心操作：
- 使用以下標準化診斷 Prompt 規範代理行為：
  > 「請先不要修改任何程式碼，只進行診斷分析：
  > 1. 列出三個最可能的根因假設。
  > 2. 為每個假設設計一個最小驗證實驗（跑什麼指令、檢查哪行日誌或變數）。
  > 3. 按照驗證成本由低到高排序。
  > 找到確鑿根因前停下來回報，等我確認再動工。」
- 核心價值：「三個假設」能強迫模型發散思考，破除「過早收斂至第一直覺」的認知偏差；「成本排序」則最大化縮短工程師的排查時間。

3. 根因確認的三重黃金標準

判定標準：一個合格的根因必須同時通過以下三項硬指標檢驗：
1. 全症狀解釋力：能邏輯自洽地解釋報錯當下的所有現象與時間差。
2. 實驗可重現性：能透過最小指令或測試案例百分之百穩定重現該錯誤。
3. 副作用免疫力：修補該點後症狀立即消失，且整個系統與既有測試未衍生任何新問題。
踩坑避雷：三者缺一的「修正」，都只是碰巧矇對的止痛藥。特別是在微服務或非同步佇列情境，日誌最末端的錯誤通常只是「連帶受害者」，絕不可把堆疊末尾當成肇事首因！

4. 啟動防瞎槍條款與可觀測性強化

觸發情境：修復未果或日誌資訊不足以判斷。
核心操作：
1. 資訊不足時加觀測，不加猜測：若代理回報無法確定某個中介環節是否有執行，正確作法是在入口與出口處注入結構化日誌（帶有時間戳與 Trace ID），部署後重新觸發以收集鐵證，嚴格禁止「先改改看再說」。
2. 防瞎槍熔斷機制：若代理連續兩次修復皆宣告失敗，立即強制踩煞車！禁止繼續讓它嘗試第三次盲改。要求代理立即停止所有檔案寫入，執行 git checkout . 復原工作區，重新輸出當前已排除的假設清單與剩餘可能性。

行動檢核清單（Checklist）

提交除錯指令前已備齊「症狀五件套」（特別包含最近變更紀錄）
嚴格落實「診斷與治療分離」，要求 AI 先提出三個假設與最小驗證實驗
根因已通過「解釋全症狀、實驗可重現、無連帶副作用」三重黃金檢驗
面對未知資訊時堅持「先補結構化日誌觀測，絕不依賴盲目猜測」
觸發防瞎槍紅線（連續 2 次失敗）時，能立即中斷代碼修改並重置假設清單

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 18 章：Git 與 GitHub 整合 — 版本控制與 PR 自動化

在漫長的開發日常中，許多工程師把最寶貴的專注力消耗在最枯燥的瑣事上：下班前看著暫存區混雜的數十個檔案，為了寫出體面的 Commit Message 想破頭，最後草草打了句「update code」；或者在 GitHub 審查同仁動輒上千行的 PR 時，花了大半天挑出拼字錯誤、邊界遺漏與缺少單元測試，累得精疲力竭，反而沒精力審視最關鍵的系統架構與業務取捨。

如果 Git 是保護程式碼的安全網，那麼 OpenCode 與 GitHub 的深度整合，就是將這個安全網升級為「全天候自動化巡邏隊」。

OpenCode 絕不僅是一個本地編輯輔助工具，它能化身為高效率的審查員、工單處理員與提交文案大師。這就像機場安檢系統的完美分工：AI 擔任 X 光快速透視機，在第一線過濾掉語法瑕疵、遺漏測試與潛在安全破洞；人類資深工程師則擔任海關專家，專注於全局戰略、業務契合度與系統演進方向。雙方各展所長，才能打造堅不可摧的工程護城河。

🧭 決策流程樹：第 18 章：Git 與 GitHub 整合 — 版本控制與 PR 自動化

步驟化 SOP 實戰詳解

1. 建立「AI 初審＋人類終審」雙軌流水線

觸發情境：在 GitHub 儲存庫建立或更新 PR。
核心操作：
1. 安裝授權：在儲存庫中部署 OpenCode 官方 GitHub 整合，代理將作為虛擬團隊成員隨時待命。
2. 留言觸發初審：在 PR 討論串中輸入以 /opencode 開頭的指令，啟動精準審查。
3. 視角化指令設計：禁止泛泛而談的「幫我看看」。高價值的審查必須指定具體視角：
  - 安全性視角：/opencode 以安全性為主軸審查此 PR，特別檢查 SQL 參數化、XSS 與未消毒的輸入驗證。
  - 效能視角：/opencode 請針對記憶體配置與演算法複雜度進行審查，確認無 N+1 查詢且無微幅優化反損可讀性。
  - 邊界條件視角：/opencode 檢查新功能是否缺少邊界測試，並標記與專案既有規範不符之處。
分工價值：AI 迅速挑出語法、測試缺口與慣例不符，作者修正後人類才介入，大幅減輕資深人員的審查心智負擔。

2. 工單領取與分支環境一鍵切換

觸發情境：接獲 GitHub Issue 待辦任務。
核心操作：
- 在終端直接執行：opencode pr <Issue/PR編號>。
- OpenCode 將自動抓取該工單的標題、描述、標籤與對應分支，完成 Checkout 並注入會話上下文，開發者立即可與具備完整工單背景的代理展開對話。
- 進階聯動：結合 GitHub MCP 伺服器，可實現進階指令：「列出標註為 bug 且尚未指派負責人的 Issue，挑選一個適合獨立修復者並擬定方案。」

3. 混雜暫存分批語意化提交

觸發情境：一次重構或功能衝刺後，工作區累積了大量跨領域改動。
核心操作：
- 委派代理進行語意化拆分提交：
  > 「目前暫存區有三類混雜變更：商品結帳新功能、順手修正的型別定義、README 部署文件。請將它們拆分為三個語意獨立的 Git Commit，逐一完成 Staging 與提交。格式嚴格遵循 Conventional Commits（<type>: <主旨>），內文詳述原因，type 僅限 feat/fix/refactor/docs/test/chore。」
踩坑避雷：切勿全量 git commit -a。由代理按檔案區塊分批提交，能保持 Git 歷史線性且清晰，利於未來 git revert 與版本追蹤。

4. 高危操作防護與權限邊界

核心守則：
1. 危險指令維持 Ask 授權：在工具權限設定（第 3、4 章）中，git push、git push --force 與 git reset --hard 必須永久保持為 ask 模式，嚴禁設定為自動放行。
2. 提交內容人工過目：AI 生成的 Commit Message 必須快速掃描，防止代理將無依據的推測寫成既定事實。
3. 最小化 Token 範圍：配置給 OpenCode 的 GitHub Personal Access Token (PAT) 嚴格遵循最小必要權限，公開開源專案嚴禁給予寫入與發布權限。

行動檢核清單（Checklist）

PR 審查建立明確分工：AI 負責邊界/測試/語法初審，人類負責架構與商業邏輯終審
呼叫 /opencode 審查時皆有指定具體視角（安全、效能或邊界覆蓋）
使用 opencode pr 一鍵帶入工單上下文，避免手動搬運資訊
複雜多樣的變更已請代理分批進行 Conventional Commits 語意提交
git push 與破壞性指令嚴格維持 ask 確認，Token 授權已落實最小化

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 19 章：團隊協作 — 共享規範與團隊最佳實踐

一個工程師使用 OpenCode，就像獨行劍客快意恩仇；但當十個人、甚至上百人的研發團隊同時引進 AI 代理時，若缺乏統一的協作架構，往往會演變成一場災難。

有人習慣用函數式風格，有人偏好物件導向；每個人的 AI 代理產出南轅北轍的代碼風格；更可怕的是，有資淺成員在排查問題時，順手使用 /share 將包含公司商業機密與內部 IP 的會話發布至公開網路，引發嚴重的資安合規危機。

獨奏講求個性，交響樂團則依賴總譜。

要在團隊中發揮 OpenCode 的十倍威力，關鍵在於「放大正確做法、封死外流漏洞」。本章的核心準則只有一句話：「能版控的都進版控，不能外流的絕對不出門」。透過分層設定架構、嚴謹的文件治理機制，以及靈活的本機推論分級，讓整個團隊用出同一個頂尖大腦的穩定水準。

🧭 決策流程樹：第 19 章：團隊協作 — 共享規範與團隊最佳實踐

步驟化 SOP 實戰詳解

1. 三層資產分流與版控策略

觸發情境：在專案中新增工具設定、自訂指令或管理敏感金鑰。
核心操作：遵循「黃金判定法則」——這個設定換一個人使用還成立嗎？
1. 團隊專案資產（存入 .opencode/）：凡是團隊成員都該遵守的架構規範、代碼風格、自訂 Commands 與專案特定 Skills，一律納入專案根目錄 .opencode/ 提交進 Git 倉庫，享有完整的代碼審查與歷史追蹤。
2. 個人偏好資產（存入 ~/.config/opencode/）：編輯器外觀配色、個人終端習慣等，僅保留在本地家目錄，各自為政，不干擾團隊。
3. 敏感憑證資產（存入 auth.json 或環境變數）：各大模型 API Keys 與私有 Token 嚴格排除在專案目錄之外，或配置進 .env 並在 .gitignore 明確封鎖。

2. AGENTS.md 與共用技能庫長效治理

觸發情境：團隊規則演進或累積重複性開發流程時。
核心操作：
1. AGENTS.md 變更必走 PR：修改 AGENTS.md 等同於改寫所有團隊成員身邊 AI 的思考邏輯與工程規範，必須提交 Pull Request 經同仁審查通過後合併。
2. 指派文件專責負責人（Owner）：每季定期巡檢，將過時失效的指令剔除，並將近期團隊常踩的雷區補入防護守則。
3. 技能庫收編原則（三次法則）：只要新人向資深同仁請教超過三次的作業流程（如特定資料庫遷移、內部環境驗證），立即將其固化為 Agent Skill。
4. 嚴格命名空間：技能目錄一律使用「領域-動作」命名結構（如 db-migrate、deploy-check），避免語義模糊造成代理誤喚醒。

3. 敏感專案分享禁令與本地模型切換

觸發情境：涉及金融合規、國防醫療或嚴禁代碼上雲的敏感專案。
核心操作：
1. 強制禁用公開分享：在專案根目錄 .opencode/opencode.json 中配置：
```
{
  "share": "disabled"
}
```
  徹底封鎖 /share 指令，杜絕任何成員誤將內部對話上傳至雲端分享平台。
2. 本地模型分級架構：對於核心涉密模組，配置相容於 OpenAI 介面的內網推論伺服器（如 Ollama 或 vLLM）：
```
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://internal-ai.corp:11434/v1" }
    }
  }
}
```
3. 務實分級處理：公開或非機密元件使用雲端旗艦模型以獲取最高品質；法規限制的機密運算切換本地內網模型。

4. 新人快速 Onboarding 與憑證衛生守則

核心操作：
1. 環境標準化：新進成員安裝 OpenCode 後，強制釘選至團隊基準版本（防止語法不相容）。
2. 開箱即用：Clone 專案庫後，.opencode/ 與 AGENTS.md 即刻就位，無需繁複設定。
3. 新人第一課：向代理下達指令：「請帶我閱讀本專案的 AGENTS.md，總結團隊的代碼風格、測試要求與提交規範。」
4. 離職交接與憑證回收：員工離職時，必須同步撤銷其 GitHub 整合授權、內部 MCP 存取 Token 與供應商金鑰，守護最後一道資安防線。

行動檢核清單（Checklist）

專案共用規範（.opencode/）已納入版本控制，個人偏好與憑證已確實隔離
修改 AGENTS.md 與團隊技能皆遵循 PR 審查流程，且有專責 Owner 定期維護
共用技能採用「領域-動作」命名規範，落實「重複三次即收編」原則
涉密或受法規監管之專案已明確配置 "share": "disabled" 封鎖對話外流
離職成員清理作業包含撤銷專案整合 Token、MCP 授權與 API Access Keys

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 20 章：效能優化 — Token 節流與響應加速

在長時間使用 AI 代理的過程中，許多工程師都經歷過這種令人崩潰的轉折：在對話剛開始的前十輪，AI 聰明敏捷、心領神會；但當對話累積到四、五十個回合後，它卻開始頻繁「失憶」——重複詢問十幾分鐘前已經確認過的架構、忘記剛剛定下的命名規則，甚至連修改單行代碼都頻頻報錯。更糟糕的是，到了月底打開雲端供應商帳單，那串龐大的費用數字更是讓人倒吸一口涼氣。

這不是什麼靈異現象，而是「資訊密度崩塌」與「注意力稀釋」的必然結果。

大語言模型的注意力視窗就像一張辦公桌。如果桌面上堆滿了數百條未經篩選的終端輸出、冗長的日誌碎片與歷史雜訊，要從中精確翻出一張便利貼上的關鍵約束，模型自然會捉襟見肘。在自主代理的實戰中，「效能」包含兩個不可分割的面向：一是上下文的純淨度（維持高智商），二是成本與速度的結構（守住預算與敏捷度）。優化效能，就是學會聰明地管理上下文，並建立嚴格的任務選型矩陣。

🧭 決策流程樹：第 20 章：效能優化 — Token 節流與響應加速

步驟化 SOP 實戰詳解

1. 落地「任務 × 成本」模型選型矩陣

觸發情境：在終端啟動任務或分派不同性質的開發工作。
核心操作：遵循兩大鐵則：「錯誤代價決定檔位下限」與「速度即是效能」。
1. 旗艦檔位（如 Claude Opus / GPT-4o / 頂級推理模型）：專門用於系統架構規劃、跨模組解耦、重大安全檢驗與難解 Bug 根因分析。旗艦模型一小時的成本，遠低於線上故障停機十分鐘的損失。
2. 中高階檔位（標準主力模型）：處理日常業務功能編寫、單元測試補充與標準重構。
3. 輕量快速檔位（如 Claude Haiku / Flash 系列 / 本地小模型）：用於高頻、重複性高的工作，如全域變數改名、檔案格式轉換、產生模擬資料。極速的反饋能大幅提升工程節奏。
4. 調用配置：
  - TUI 介面：使用 <Tab> 選單即時無縫切換當前會話模型。
  - CLI 模式：透過參數直接指派：opencode run --model provider/model-name "..."。
  - 代理釘選：在 .opencode/agents/ 中將特定角色（如文檔整理員、批次處理員）寫死為輕量模型。

2. 主動上下文管理「四神技」

觸發情境：進行大型或複雜的專案推進。
核心操作：自動壓縮是最後的保底，主動保持上下文精煉才是高手的標配：
1. 話題切換即換會話：修完一個 Bug 準備開發新功能時，立即開新會話。新會話不僅思維清晰，而且每個 Prompt 攜帶的 Context 最小，最為節省費用。
2. 長任務外部化為計畫檔：將任務清單與進度記錄在實體 Markdown 檔案（如 implementation_plan.md）或 GitHub Issue 中。檔案是最穩定、永遠不會被遺忘的外部記憶體。新會話開場時只需讓代理讀取該計畫檔即可瞬間滿血復活。
3. 大範圍探索委託子代理：閱讀大量程式碼或尋找引用時，調用 explore 或專用子代理。子代理在獨立沙盒內翻找數萬行代碼，最後只將濃縮後的結論回傳給主會話，杜絕雜訊污染主上下文。
4. 日誌餵料精準切片：嚴禁直接傾倒數萬行日誌！先在外部截取關鍵區間（如 sed -n '200,260p' /tmp/api.log），僅餵入發生崩潰前後的關鍵片段。

3. 識別上下文過載「三大警訊」

觸發情境：長對話進行中。
核心判定：一旦出現以下任一徵兆，代表模型注意力已被雜訊淹沒，應立即熔斷並開新會話：
1. 重複犯錯：AI 開始重複出現三輪前剛剛糾正過的語法或架構失誤。
2. 響應延遲暴增：生成速度顯著變慢，思考過程冗長且發散。
3. 脈絡失真：開發者自己也必須在對話紀錄中大幅滾動才能找回關鍵資訊。
操作方式：敲下 /sessions 存檔，建立新會話並貼入上一會話的最終結論，三十秒即可找回百倍產能。

4. 執行 `opencode stats` 定期財務對帳

觸發情境：每週或每月團隊例行檢視。
核心操作：
- 在終端執行 opencode stats，檢查各模型供應商與專案的 Token 消耗分佈。
- 診斷偏差：
  - 是否有用旗艦模型進行大量字串替換與樣板生成的浪費現象？
  - 是否有因在困難除錯時選用過弱的模型，導致無效對話多達數十回合，反而在累計 Token 上花費更多？
- 根據實際對帳數據動態微調選型矩陣與預設配置。

行動檢核清單（Checklist）

依「錯誤代價」與「響應速度」精準匹配任務模型檔位
長任務進度已落實外部化至 Markdown 計畫檔或 GitHub Issue
探索性代碼巡航交由子代理獨立執行，避免污染主會話上下文
終端日誌與測試輸出皆完成精準切片，杜絕整份全量傾倒
當出現重複犯錯或回應延遲時，能在 30 秒內主動優雅換線開新會話

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 21 章：安全與隱私 — 金鑰防護與敏感資料隔離

當我們將 AI 代理引入專案開發時，我們實質上交出了一部分的系統主控權。一個具備代碼修改、檔案寫入與終端機執行能力的代理，究竟是我們專屬的資深外腦，還是一個隨時可能因為幻覺而抹掉資料庫、推爆 Production 環境的隱形實習生？

這不是危言聳聽。給予 AI 代理的權限，本質上就是擴大了系統的攻擊面。如果缺乏嚴謹的權限設計與隔離機制，一次疏忽的授權就可能導致金鑰外洩或災難性的資料覆寫。反之，若過度恐懼而全面開啟確認提示，開發者又會迅速陷入「確認疲勞」（Confirmation Fatigue），最終習慣性地對所有請求按同意，讓安全防線形同虛設。

真正的工程智慧，在於建立一套「縱深防禦」（Defense in Depth）體系。權限控制如同保鑣門禁：唯讀檢查與單元測試自由放行、具備對外副作用的操作逐項詢問、毀滅性破壞指令一律永久焊死；在資料隱私層面，落實「敏感代碼走本地、通用邏輯走雲端」的分級路由；在架構層面，嚴密防範本機 HTTP 伺服器的跨來源未授權調用。本章將為你梳理經實戰校準的安全基線與部署架構。

🧭 決策流程樹：第 21 章：安全與隱私 — 金鑰防護與敏感資料隔離

步驟化 SOP 實戰詳解

1. 建立經過實戰校準的基準權限設定檔

觸發情境：在新專案或團隊環境中初始化 OpenCode 權限架構。

核心操作：
在專案根目錄 .opencode/opencode.json 中配置細粒度權限規則，落實「唯讀與測試放行、對外效果詢問、毀滅性操作直接拒絕」的原則：

{
  "permission": {
    "edit": "allow",
    "webfetch": "allow",
    "bash": {
      "git status": "allow",
      "git diff*": "allow",
      "git log*": "allow",
      "npm test": "allow",
      "make test*": "allow",
      "git push*": "ask",
      "rm -rf *": "deny",
      "git reset --hard*": "deny",
      "*": "ask"
    }
  }
}

踩坑避雷與防護指南：
- Deny 清單優先維護：第一時間將最承受不起的操作釘死（例如 rm -rf、DROP TABLE、生產環境 kubectl）。只要被 Deny 命中，無論上層提示詞如何催眠，工具底層皆會無條件攔截。
- 防範確認疲勞：若發現自己或團隊開始無腦狂按 Enter 同意，代表 allow 清單過於狹窄。適度將高頻且無害的測試與查詢指令加入 allow，把注意力留給真正關鍵的 ask。
- 分層繼承原則：團隊底線必須固定在專案層（Git 納管），個人僅可在全域設定中為自己「加嚴」，嚴禁個人全域覆蓋掉專案層的安全防護。

2. 本地端點部署與資料不出門分級路由

觸發情境：處理涉及高度敏感商業機密、專利代碼或嚴格法規遵循（如 GDPR / 金融醫療）的專案。
核心操作：
1. 本地推論服務選型：
  - Ollama：個人與小團隊入門首選，安裝便捷，模型庫生態豐富。
  - vLLM：企業級高吞吐推論引擎，適合內網伺服器統一對外提供服務。
  - LM Studio：本機圖形化介面，適合本機快速實驗與模型評測。
2. 配置私有 Provider：
  透過 OpenAI 相容介面將 OpenCode 端點切換至本機推論端點：
```
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1"
      }
    }
  }
}
```
踩坑避雷與防護指南：
- 務實的能力預期：開源 7B/8B/14B 本地模型在「理解龐大專案跨檔案關聯並進行複雜協調重構」上，仍顯著落後雲端旗艦。合理的期待排序為：代碼問答與原理分析尚可、單檔微修堪用、大型多檔架構重構吃力。
- 分級路由策略：核心機密業務模組走本地 Ollama，公開演算法或通用腳本走雲端旗艦，兼顧安全邊界與工程交付效率。

3. 服務繫結與縱深防禦防範 CVE 攻擊

觸發情境：啟動 OpenCode 伺服器服務或整合外部 MCP/外掛擴展。
核心操作：
1. 保守繫結位址：執行 opencode serve 時，確保主機位址預設綁定本機環回介面 127.0.0.1，嚴禁直接以 0.0.0.0 暴露給未經信任的區域網路。
2. 安全穿透架構：若確實需要遠端存取開發機上的 OpenCode 實例，務必使用 SSH 隧道或企業 VPN（如 WireGuard / Tailscale）包裹，杜絕裸奔暴露 HTTP 埠。
3. 及時版本升級：養成定期執行 opencode upgrade 的習慣，並訂閱官方 GitHub Security Advisories，快速修補潛在的本地認證繞過缺陷。
踩坑避雷與防護指南：
- 攻擊面等於整合面總和：系統每掛載一個外部 MCP 伺服器或外掛套件，就等於引入一組新的權限進入點。每當新增第三方整合時，必須在設定檔中重新審查其權限範圍（如限制 MCP 僅能讀取特定沙箱目錄）。

行動檢核清單（Checklist）

專案層 .opencode/opencode.json 已配置 rm -rf 等高危指令的 deny 清單
高頻唯讀與測試指令已加入 allow，消除確認疲勞陷阱
涉密程式碼庫已切換為本地模型端點（Ollama/vLLM）落實資料不出門
伺服器服務僅監聽 127.0.0.1，遠端存取一律經過 SSH 隧道保護
軟體版本與安全公告保持最新，定期追蹤已知 CVE 與修補措施

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

第 22 章：問題排除 — 常見故障診斷排查手冊

無論多麼精密的開發工具，在面對紛繁複雜的作業系統環境、多變的網路條件與多元的依賴生態時，總會有鬧脾氣或意外罷工的一天。當終端機突然吐出一段刺眼的紅字報錯，或是按下 Enter 後代理陷入無止盡的載入旋轉，甚至滿心期待產出的代碼改動莫名消失在虛空中，你的第一反應是什麼？是盲目重開機、隨意重裝套件，還是擁有一套條理分明、直搗病灶的系統化除錯思維？

問題排除不是玄學，而是如同急診室醫師的分診作業：面對病患，絕不能一看到發燒就盲目下重藥，而必須先監測基本生命徵象（檢查 PATH 與系統進程）、調閱病歷與儀器數據（查閱 DEBUG 級別日誌）、並逐一隔離各個子系統的健康狀態（透過 /status 檢視 LSP 與 MCP 連線）。

本章是你在使用 OpenCode 征戰工程現場時的隨身急救包。我們將高頻出現的典型故障歸納為速查矩陣，剖析日誌挖掘與內部體檢工具的調用手法，並給出高效求助與會話脫敏分享的最佳實踐，助你在面對任何突發異常時，都能臨危不亂、迅速重返高效節奏。

🧭 決策流程樹：第 22 章：問題排除 — 常見故障診斷排查手冊

步驟化 SOP 實戰詳解

1. 高頻常見故障速查與快速處置

觸發情境：在日常開發中遇到典型錯誤訊息或終端反應異常。
核心操作：參照以下常見錯誤速查矩陣對號入座排查：

異常症狀	最可能成因	標準處置程序
`command not found`	執行檔目錄未加入系統 `PATH`	重啟終端機視窗；若為 npm 安裝，檢查 `npm config get prefix` 之 bin 路徑是否納入 PATH。
啟動卡在載入畫面	模型供應商連線失敗或憑證無效	檢查網路連線與代理伺服器；執行 `opencode providers` 確認 API Key 授權狀態。
回覆中途斷線	上游 API 波動或會話上下文過長	輸入重試；若會話過於冗長導致 Token 溢出，以 `/new` 開啟新會話接續。
TUI 圖示變方框/亂碼	終端機未啟用支援圖示的 Nerd Font	安裝並在終端機字型中切換為 Nerd Font（如 FiraCode NF 或 JetBrainsMono NF）。
改動沒套用或改錯檔案	串連到舊歷史脈絡或不同檔案版本	輸入 `/sessions` 確認當前會話歷史，透過 `git diff` 重新檢視差異變更。
MCP 工具未出現	外部 MCP 伺服器啟動崩潰或未啟用	執行 `opencode mcp list` 與 `/status`；必要時執行 `mcp debug` 觀察啟動標準輸出。
LSP 語意感應沒反應	語言伺服器未安裝或大型專案索引中	輸入 `/status` 查看 LSP 就緒狀態；若為超大型專案，耐心等待背景符號索引完畢。
設定檔改動沒生效	設定值被更高優先順序的階層覆蓋	依循七層覆蓋順序（CLI 旗標 > 代理 > 指定檔 > 專案 > 全域）逐級比對。

2. 日誌挖掘與系統結構化深度診斷

觸發情境：表面症狀無法直觀定位，需要深入觀察執行細節與底層報錯堆疊。
核心操作：
1. 定位日誌檔案：
  OpenCode 預設將會話日誌按時間戳記儲存於本機目錄：
```
ls -la ~/.local/share/opencode/log/
```
2. 啟用最高詳細度（DEBUG 模式）：
  當遇到偶發性崩潰或掛起時，重啟 OpenCode 並注入即時調試參數：
```
opencode --print-logs --log-level DEBUG
```
  注意：DEBUG 級別輸出量龐大且會輕微消耗效能，排查完成後切回標準等級。
3. 利用內部診斷指令快速健檢：
  - 在互動介面輸入 /status：第一時間檢視 LSP、MCP 伺服器及各外掛的就緒狀態（八成以上的「工具消失」皆因背景進程啟動逾時）。
  - 終端機執行 opencode doctor 或 opencode debug：自動對 Node 版本、系統依賴、網路連通性進行全面體檢。

3. 社群求助與會話脫敏分享規範

觸發情境：確定為核心 Bug 或難以解決的底層缺陷，需向開源社群回報。
核心操作：
1. 高效求助第一步：先搜後問：
  進入官方 GitHub Issues（https://github.com/anomalyco/opencode/issues），先以關鍵錯誤訊息搜尋既有討論，往往前人已給出 workaround。
2. 生成標準化復現情報：
  撰寫 Issue 時，切忌只貼一句「壞了」，務必包含五件套：
  - OpenCode 版本（opencode --version）
  - 作業系統與終端架構（macOS / Linux / Windows WSL）
  - 最小復現步驟（Minimal Reproducible Example）
  - 關鍵錯誤日誌片段（精準截取 DEBUG 日誌報錯處）
3. 善用 /share 生成會話連結：
  輸入 /share 可直接產生雲端會話回溯連結，讓除錯者直接看見完整的上下文與工具調用流。若涉及內部專案，請先在乾淨的測試目錄建立脫敏最小復現後再行分享。

行動檢核清單（Checklist）

遇到工具或語意異常時，第一時間輸入 /status 檢查子系統就緒狀態
啟動卡頓時，先以 opencode providers 確認模型端點連通性與額度
疑難雜症重現時，調用 --print-logs --log-level DEBUG 捕捉底層堆疊
設定失效時，自覺對照「CLI 旗標至專案層」的七層覆蓋鏈條排查
向社群發布 Issue 前，完成敏感資料脫敏並附齊版本與最小復現步驟

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

附錄 A：快速鍵完整對照 — 終端快捷操作全覽

終端機開發者追求的最高境界，是思維與代碼之間的「零阻力傳遞」。你是否依然在鍵盤與滑鼠之間頻繁擺盪？為了引用一個檔案路徑，不得不在終端機與檔案總管之間來回切換；或者在代理滔滔不絕產生無效代碼時，手忙腳亂找不到緊急煞車鍵？

熟練掌握 OpenCode 的快捷鍵體系，就像樂器演奏者將音階刻入指尖肌肉記憶。當你不必停下來思考「該按哪裡」，而是憑藉直覺在 Plan 與 Build 模式之間秒級切換（Tab）、敲下 @ 瞬間定位專案深處的目標檔案、按下 Esc 果斷勒住代理韁繩時，AI 代理才真正從一個「外部命令工具」昇華為你大腦思維的自然延伸。

本附錄收錄 OpenCode 終端介面（TUI）的完整快捷鍵矩陣，並詳解如何透過 tui.json 的 Leader Key 前導鍵機制量身打造極速盲打鍵位，助你徹底釋放鍵盤黑客的雙手極限。

🧭 決策流程樹：附錄 A：快速鍵完整對照 — 終端快捷操作全覽

步驟化 SOP 實戰詳解

1. 全域操作與核心控制鍵位速查

觸發情境：在日常對話與代碼生成過程中進行精準控制。
快捷對照矩陣：

快捷鍵	核心作用	實戰情境與注意事項
`Enter`	送出目前輸入	提交當前指令或確認對話框選項。
`Esc`	中斷執行 / 關閉浮層	代理生成偏離方向時一秒急煞；或快速退出浮動彈窗。
`Ctrl+C`（按一次）	清空當前輸入內容	撤銷未發送的長篇文字草稿，避免手動退格。
`Ctrl+C`（按兩次）	徹底離開 OpenCode	安全終止 TUI 服務進程並返回系統 Shell。
`Tab`	切換 Build / Plan 模式	在「動手寫代碼（Build）」與「架構分析規劃（Plan）」間無縫切換。

2. 輸入技巧與高效檔案上下文掛載

觸發情境：精準提供上下文檔案、附加多模態資訊或編寫多行複雜提示。
核心操作：
1. 路徑模糊搜尋（@ 語法）：
  在輸入框中鍵入 @，介面立即彈出專案檔案模糊匹配清單。鍵入檔案前綴（如 @user_service），按 Tab 或 Enter 即可將檔案路徑與語意錨點精準注入上下文，杜絕手動輸入路徑造成的拼寫錯誤。
2. 指令調度呼出（/ 語法）：
  鍵入 / 立即喚出內建命令列表（如 /undo、/status、/models、/sessions），支援鍵盤上下鍵快速選取。
3. 多行提示詞輸入：
  若需撰寫包含條列項的多行複雜指令，可在每行末尾加上反斜線 \ 後按 Enter 換行；亦可透過設定開啟外部編輯器模式（如綁定 Vim/Nano）編寫大篇幅需求。
4. 拖曳附圖多模態解析：
  直接將介面截圖、UI 設計稿或架構圖拖入終端視窗，或使用剪貼簿貼上，代理將自動讀取圖片多模態特徵並參與分析。

3. 會話管理與歷史分岔快捷指令

觸發情境：處理跨任務切換、重構平行實驗或團隊成果分享。
核心操作：
- /new：立即清空當前上下文負擔，開啟乾淨的獨立會話。
- /sessions：開啟互動式會話列表，回溯或切換先前的對話時間線。
- /share：一鍵生成加密分享連結，便於團隊復盤或社群除錯。
- CLI 會話續接與分岔：
  - 續接上次會話：opencode --continue
  - 節點分岔平行探索：opencode --session <session-id> --fork，從指定歷史狀態分岔出全新時間線，進行不同架構方案的並行評測。

4. 客製化鍵位綁定與 Leader Key 配置

觸發情境：打造符合個人打字習慣與人體工學的極速單手工作流。

核心操作：
在使用者設定檔 ~/.config/opencode/tui.json 中配置 keybinds 區塊，引入 Vim 風格的 <leader> 前導鍵機制：

{
  "keybinds": {
    "leader": "<a-x>",
    "switch_agent": "<leader>a",
    "session_new": "<leader>n",
    "toggle_plan": "<leader>p"
  }
}

踩坑避雷與防護指南：
- 角括號語法解析：<a-x> 代表 Alt+X，<c-k> 代表 Ctrl+K，<cr> 代表 Enter。
- 單手盲打原則：不要試圖客製化所有冷門操作。先記錄自己一週內的高頻動作，把每天使用超過 10 次的動作（如開新會話、切換子代理）綁定為左手或右手可單手觸及的 Leader 組合鍵。

行動檢核清單（Checklist）

養成代理生成失控時立刻按 Esc 緊急煞車的直覺反應
引用專案檔案一律使用 @ 模糊搜尋，避免手寫路徑拼錯
善用 Tab 鍵在架構規劃（Plan）與具體實作（Build）間明確切換
探索未知架構時，熟練使用 --fork 分岔指令開展無風險平行實驗
評估個人高頻操作，在 tui.json 中配置一套順手的 Leader 快捷鍵

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

附錄 B：設定選項速查 — 設定檔欄位與參數字典

「為什麼我明明在全域設定裡開啟了這個外掛，在專案裡卻依然被阻擋？」
「為什麼修改了 Bash 權限規則，代理執行時依然跳出確認提示？」

如果你在使用 OpenCode 時產生過上述困惑，那麼九成以上的機率，是你遭遇了設定檔的「分層繼承與覆蓋衝突」。OpenCode 的設定架構採用嚴謹的 JSONC 規格（支援行內註解），並依循清晰的權限階層與語意優先序。它就像一套具備地方自治權的法規體系：中央（全域層）奠定個人基本偏好，而駐紮於程式碼庫根目錄的專案層，則擁有維護團隊安全邊界的最終裁判權。

理解設定檔的欄位字典與覆蓋邏輯，是從「單純使用者」躍升為「工程配置專家」的必修課。本附錄全面收錄 OpenCode 核心設定區塊（permission、mcp、provider、share、tui）的語法典範與欄位字典，並提供一套精確的「七層優先序排查口訣」，讓你的每一行配置都能精準生效。

🧭 決策流程樹：附錄 B：設定選項速查 — 設定檔欄位與參數字典

步驟化 SOP 實戰詳解

1. 核心設定區塊與功能速查總覽

設定檔位置：
- 全域設定：~/.config/opencode/opencode.json（或 ~/.opencode.json）
- 專案專屬設定：[專案根目錄]/.opencode/opencode.json（強烈建議納入 Git 版本控制）
- 介面專屬設定：~/.config/opencode/tui.json（外觀主題、字型、快捷鍵）
主要區塊功能速查表：

設定區塊	核心職責	語法結構型態	預設覆蓋原則
`permission`	宣告各工具與命令的 `allow` / `ask` / `deny` 權限	鍵值對（字串或物件，支援萬用字元）	專案層嚴於全域層；Deny 具備最高絕對優先級
`mcp`	註冊本機或遠端 Model Context Protocol 伺服器	物件陣列（宣告 `type`、`command`、`url` 等）	專案層註冊之 MCP 伺服器僅對該專案生效
`provider`	定義自訂模型供應商與本地推論端點（如 Ollama）	供應商字典（包含 `npm` 套件、`baseURL`、憑證）	專案層可釘選專屬模型，覆蓋全域預設值
`share`	管控會話分享功能與隱私政策	字串（設為 `"disabled"` 可全面封鎖雲端分享）	企業與涉密專案應在專案層設為 `"disabled"`
`tui`	終端介面配色、主題、動畫與前導鍵（Leader Key）	物件（定義 `theme`、`keybinds` 等）	個人全域偏好，不建議納入專案版本庫

2. 精細粒度 Permission 權限設定範例

語意邏輯：
- 字串值：直接將安全等級套用至整個工具類別（如 "edit": "allow"）。
- 物件值：依「指令前綴」或「MCP 伺服器_工具名稱」進行細分匹配。
- 萬用字元 *：支援前綴比對（git push*）與子字串比對（*_delete*）。

實戰範例：

{
  "permission": {
    // 檔案編輯與網路網頁抓取直接放行
    "edit": "allow",
    "webfetch": "allow",

    // Bash 指令實施細緻分流
    "bash": {
      "git status": "allow",
      "git diff*": "allow",
      "npm test*": "allow",
      "git push*": "ask",      // 涉及遠端變更必須人工確認
      "rm -rf *": "deny",       // 破壞性指令絕對禁止
      "drop database*": "deny",
      "*": "ask"                // 其餘未列指令一律詢問
    },

    // MCP 工具權限細分
    "mcp": {
      "github_*": "allow",      // GitHub 唯讀查詢允許
      "*_delete*": "deny"       // 任何包含刪除語意的 MCP 操作一律拒絕
    }
  }
}

3. MCP 擴展與本地 Provider 配置範例

MCP 伺服器註冊（支援本機子進程與遠端 SSE/HTTP）：

{
  "mcp": {
    // 本機沙箱檔案系統 MCP
    "filesystem-sandbox": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "./sandbox_data"],
      "enabled": true
    },
    // 遠端內部企業 MCP 服務
    "internal-knowledge": {
      "type": "remote",
      "url": "https://mcp.internal.company.corp/v1",
      "enabled": true
    }
  }
}

本地 Ollama / OpenAI 相容推論端點接入：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1"
      }
    }
  }
}

4. 排查口訣：七層優先序排查大法

當發現設定參數未按預期生效時，請依以下「由高到低」的七層優先序進行排查：
1. CLI 指令列旗標（最高權重，如 --model, --share=disabled）
2. 代理定義 Frontmatter（自訂 Agent Markdown 內宣告的設定）
3. 額外指定設定檔（透過 CLI --config /path/to/custom.json 注入）
4. 專案層設定（專案根目錄 .opencode/opencode.json）
5. XDG 規範路徑（~/.config/opencode/opencode.json）
6. 全域使用者設定（~/.opencode.json）
7. 系統底層內建預設值（最低優先級，程式碼內建 Fallback）

排查原則：只要在較高層級存在同名鍵值，底層的任何設定皆會被無情覆蓋。

行動檢核清單（Checklist）

專案設定檔使用標準 JSONC 格式，並置於 .opencode/opencode.json
涉及破壞性的 Bash 指令已透過 deny 萬用字元釘死
機密商業專案已在專案層配置 "share": "disabled" 杜絕外流
本地推論端點（Ollama）已正確掛載 OpenAI 相容 Provider
遇到設定異常時，自覺依據「七層優先序」由上而下排查覆蓋源頭

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

附錄 C：內建工具列表 — 工具簽章與權限要求

AI 代理究竟如何感知專案程式碼？它真的能像人類工程師一樣「看見」整個程式碼庫嗎？在你的硬碟上，它的一舉一動究竟透過什麼途徑產生實質影響？

答案就在於代理的「手與眼」——內建工具系統（Built-in Tools）。大型語言模型本質上只能輸出文字 Token，但當它被賦予結構化的工具呼叫協議時，它便具備了探索檔案系統、精確修改代碼、執行編譯測試與發起網路請求的實體行動力。理解各類工具的運作機制與權限邊界，就像外科主刀醫師熟悉手術室內的器械清單：read 是精準的內視鏡，grep 是高速定位的超音波探頭，edit 是毫釐不差的顯微手術刀，而 bash 則是唯一的全身麻醉劑兼任意副作用入口。

濫用工具（例如動輒全量讀取大檔案或盲目覆寫整檔）會迅速耗盡上下文視窗並破壞代碼結構；唯有掌握三段式探索與最小特權操作，才能讓代理在安全受控的軌道上發揮最大威力。本附錄全面解析 OpenCode 內建工具的簽章規範、職責分工與對應的權限管制鍵。

🧭 決策流程樹：附錄 C：內建工具列表 — 工具簽章與權限要求

步驟化 SOP 實戰詳解

1. 內建工具分類字典與權限對照

基準版本：OpenCode v1.18.x 核心工具體系。
工具字典全覽：

工具名稱	工具類別	核心功能說明	關聯 Permission 權限鍵	實戰調用最佳實踐
`glob`	檢索類	依據萬用字元（如 `src/*/.ts`）搜尋匹配路徑	內建唯讀（預設放行）	初入陌生專案時，先探查模組結構與目錄樹。
`grep`	檢索類	透過正規表示式全文搜尋程式碼內容	內建唯讀（預設放行）	快速定位類別定義、函式調用或錯誤字串出現處。
`read`	檢索類	讀取指定檔案內容，支援特定行號區間切片	內建唯讀（預設放行）	嚴禁整檔傾印大檔案；搭配 grep 鎖定行數後局部切片。
`edit`	寫入類	以「精確舊字串 → 新字串」進行局部替換	`permission.edit`	首選代碼修改工具；支援多層比對與失敗復原。
`write`	寫入類	建立全新檔案或進行整檔完整覆寫	`permission.edit`	僅用於新建檔案；若覆寫既有檔案，前置必須先調用 read。
`bash`	執行類	在專案環境執行 Shell 指令並捕獲輸出	`permission.bash`	唯一的任意副作用入口；必須在設定檔嚴格分級限制。
`webfetch`	網路類	下載指定 URL 網頁內容並轉為乾淨 Markdown	`permission.webfetch`	查閱官方第三方文件；受網域白名單與權限管控。
`task`	委託類	開闢全新子會話，將耗時子任務委託子代理	內建架構調度	實現上下文隔離（Context Isolation），避免主會話污染。
`todowrite`	任務類	寫入並更新多步驟工程任務的待辦事項清單	內建狀態管理	長篇架構重構時，外顯任務進度，防止任務中途遺忘。
`todoread`	任務類	讀取當前待辦清單，確認剩餘工程項目的進度	內建狀態管理	子代理交接與回報時同步任務驗收狀態。

2. 最佳實踐：高效「三段式」程式碼探索流

觸發情境：指派代理在大型或陌生程式碼庫中定位並修復特定功能。
核心操作流程：
1. 第一步（宏觀探索）：調用 glob(pattern="**/auth/*.ts") 獲取模組架構地圖，避免盲目翻查。
2. 第二步（精準聚焦）：調用 grep(pattern="function verifyToken", path="src/auth") 獲取符號所在檔案與精確行號。
3. 第三步（微觀閱讀）：調用 read(file_path="src/auth/jwt.ts", start_line=45, end_line=90) 僅載入關鍵邏輯區塊。
效益：消耗 Token 減少 80% 以上，並避免無效雜訊干擾大模型注意力。

3. 精準改寫：`edit` 與 `write` 的安全邊界

edit 的防護哲學：
- edit 採用字串錨定比對。若檔案在代理思考期間已被外部（如開發者手動修改或 Git 切換分支）變更，比對失敗會立即拋出衝突，防止靜默覆蓋他人的代碼。
write 的高危風險：
- write 會不講情面地將新內容完全覆蓋目標檔案。OpenCode 底層強制防護規則：在對既有檔案執行 write 之前，代理必須在本次會話中至少調用過一次 read，杜絕無知盲寫。

4. LSP 語意能力的加成閉環

LSP（Language Server Protocol）並非單純的獨立工具，而是貫穿於代理工作流中的底層守護機制。每當代理透過 edit 寫入代碼後，LSP 會自動在背景執行型別檢查與語意診斷。若代理產生的代碼破壞了 TypeScript 型別或引入了未定義變數，LSP 診斷錯誤會立即作為環境反饋（Environment Feedback）送回大模型，驅動代理發起自我修正迴圈。

行動檢核清單（Checklist）

閱讀大型代碼庫時，貫徹「glob → grep → read 切片」三段式探索原則
代碼修改一律優先使用 edit 精準錨定，嚴禁無意義的整檔 write 覆寫
對 permission.bash 設定細粒度白名單，嚴控唯一具備任意副作用的工具
執行多步驟複雜任務時，善用 todowrite 維護外顯進度條
確認專案已正確掛載語言專屬 LSP，形成自動語意診斷的驗證閉環

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️
***

附錄 D：模型供應商比較表 — 選型評估與性價比矩陣

在當前 AI 大模型百家爭鳴的時代，OpenCode 支援了超過 75 家主流與開源模型供應商。從每百萬 Token 數十美金的頂級推理旗艦，到速度驚人、幾美分甚至完全免費的本機推論端點，面對眼花繚亂的型態與價位，工程師最常面臨的決策困惑是：

「我到底該選哪一個模型？」
「是一味追求最貴的最強旗艦，還是為了省錢全盤採用平價模型或本地部署？」

把模型選型比作「工程車隊調度」：建造跨海大橋的核心地基，你必須出動百噸級的重型吊車與深水打樁機（旗艦檔推理模型），若為求省錢派輕型小貨車，只會造成坍塌重來的災難；但在市區穿梭遞送文件、做格式排版或簡單測試，電動機車（輕量檔模型）不僅成本近乎為零，響應速度更遠超笨拙的大吊車；而當運送的是涉及國家安全或最高商業機密的藍圖時，則必須啟用完全隔離在內網基地的武裝裝甲車（本地私有端點）。

真正的架構師，絕不陷入單一模型的宗教崇拜，而是透過「雙軌分流」與「代理層釘選」，讓不同任務在精確的 ROI 甜區運行。本附錄全面盤點主流供應商的實力矩陣，並提供一套經過實戰驗證的選型決策樹與每月對帳 SOP。

🧭 決策流程樹：附錄 D：模型供應商比較表 — 選型評估與性價比矩陣

步驟化 SOP 實戰詳解

1. 主流模型供應商分類比較矩陣

注意：大模型版本迭代與定價調整極為頻繁，下單前請以各供應商官方控制台現價為準。

類別一：雲端旗艦檔（低頻高難度任務首選）

供應商 / 系列	代表型號	相對成本	核心技術強項與適用場景
Anthropic	Claude 3.5 Sonnet / Opus	高	程式碼綜合能力天花板。超強長上下文理解、複雜多檔協調重構、精準遵循架構規範。
OpenAI	GPT-4o / o1 系列	高	深層邏輯推理。演算法推導、邊界條件攻防、完善成熟的生態工具鏈支援。
Google	Gemini 1.5 Pro	中高	百萬超長上下文視窗。支援將整個大型 Codebase 或厚重架構規格書一次性載入分析。

類別二：性價比與快速檔（高頻日常與大量批次任務）

供應商 / 系列	代表型號	相對成本	核心技術強項與適用場景
Google	Gemini 1.5 Flash	極低	速度與成本的極致平衡。每秒生成速度極快，極度適合代碼探索、註解產生、大量測試樣板生成。
Anthropic	Claude 3.5 Haiku	低	精悍迅捷。具備出色的輕量級推理與上下文感知，適合日常快速對話與微小修復。
OpenAI	GPT-4o-mini	低	平價穩定。響應延遲極低，廣泛適用於日誌清洗、正則產生與語意分類。

類別三：本地私有推論（資料不出門與離線開發）

部署方案	運作形態	部署難易度	核心特點與定位
Ollama	本機背景服務	極簡（一鍵安裝）	個人與小團隊首選；模型庫生態完善，OpenCode 以 OpenAI 相容介面即插即用。
vLLM	企業級推論伺服器	中高（需 Linux/GPU）	高併發高吞吐推論；支援 PagedAttention，企業內網私有雲集權部署首選。
LM Studio	桌面圖形化軟體	極簡（GUI 介面）	本地視覺化測試各類開源權重（如 Qwen2.5-Coder、DeepSeek-Coder）的最佳沙盒。

2. 代理層模型釘選（Subagent Pinning）

觸發情境：在多代理協同架構中，避免讓單一高價模型包辦所有粗活，浪費寶貴預算。
核心操作：
在自訂代理（Custom Agents）中明確指定 model 屬性，實現專才專用：
- 架構規劃代理（Planner）：釘選雲端旗艦（如 claude-3-5-sonnet），專注於高難度模組拆解。
- 程式碼探索代理（Explorer）：釘選輕量快速模型（如 gemini-1.5-flash），以極低成本執行大規模 glob 與 grep 巡航。
- 涉密審查代理（Auditor）：釘選本地私有端點（ollama/qwen2.5-coder），確保機密資料不出門。

3. 數據化對帳：每月 `opencode stats` 審計

觸發情境：定期檢討專案開發成本與模型效益。
核心操作：
1. 在終端執行統計指令：
```
opencode stats --monthly
```
2. 檢視各代理調用次數、Token 消耗總量與費用分佈。
3. 若發現輕量型任務大量調用了旗艦模型，及時修正設定檔中的預設 Provider 或調整代理提示詞路由。

行動檢核清單（Checklist）

核心架構重構與 Production 級變更一律選用雲端旗艦檔（Claude Sonnet / GPT-4o）
高頻代碼探索、測試生成與常規雜活導向輕量檔（Gemini Flash / GPT-4o-mini）
涉密或受規管代碼庫已切換為本地私有推論（Ollama / vLLM）落實資料不出門
在多代理架構中完成模型釘選（Subagent Pinning），杜絕大砲打小鳥
每月定期執行 opencode stats，依據數據回饋持續迭代車隊配置

⏮️ 上一章｜ 🏠 返回目錄｜下一章 ⏭️

OpenCode 實戰筆記：知識地圖與導航 (MOC)

🗺️ 全書六大核心模組導航

第一篇：核心架構與概念演進（第 1–5 章）

第二篇：環境設定與專案啟航（第 6–8 章）

第三篇：深度擴充與協議整合（第 9–13 章）

第四篇：工程開發與重構除錯（第 14–17 章）

第五篇：團隊協作與防護優化（第 18–22 章）

附錄：工程速查指南（附錄 A–D）

🧭 OpenCode 核心作業流全景決策圖

第 01 章：AI 程式輔助的演進 — 從自動補全到自主代理

為什麼工程師需要堅持開源方案？

步驟化 SOP 實戰詳解

1. 觸發情境：評估並建立「代理優先」的開發心智

2. 核心操作：指派受控任務的三步閉環

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 02 章：系統架構總覽 — 核心組件與生命週期

主從式架構：分離的「大腦」與「顯示器」

技術棧的四根頂樑柱

「一切皆事件」的心智模型

步驟化 SOP 實戰詳解

1. 觸發情境：部署並切換 OpenCode 的運行模式

2. 核心操作：遠端無頭伺服器架設與客戶端附加

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 03 章：代理系統 — 主代理與子代理協同架構

四大內建代理與「先 plan 後 build」黃金律

代理委託機制：守護上下文的防火牆

權限安全防禦：allow、ask、deny 三層防線

步驟化 SOP 實戰詳解

1. 觸發情境：啟動非平凡（Non-trivial）需求開發

2. 核心操作：「先 plan 後 build」標準協同程序

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 04 章：工具系統 — 內建工具與權限防護

內建工具五大分類

高效探索的黃金組合：glob、grep 與 read 的分工

edit 工具的多層回退比對（Fallback Matching）

供應商適配層：抹平模型的手感差異

步驟化 SOP 實戰詳解

1. 觸發情境：在大型既有專案中進行定位與修改

2. 核心操作：標準搜尋與手術刀替換流程

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 05 章：技能系統 — 按需載入與知識封裝

SKILL.md 規範剖析

漸進揭露（Progressive Disclosure）：零上下文負擔的奧秘

雙層配置架構：專案共用與個人全域

步驟化 SOP 實戰詳解

1. 觸發情境：建立「Python 代碼修改後強制檢查」專案技能

2. 核心操作：五分鐘上線第一支自訂技能

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 06 章：安裝與環境設定 — 跨平台部署與依賴

步驟化 SOP 實戰詳解

1. 觸發情境

2. 核心操作

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 07 章：專案初始化 — 專案配置與自訂指令集

步驟化 SOP 實戰詳解

1. 觸發情境

2. 核心操作

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 08 章：基本互動精修 — 提問模式與高效提示

步驟化 SOP 實戰詳解

1. 觸發情境

2. 核心操作

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 09 章：LSP 整合 — 語言伺服器協議與型別感應

步驟化 SOP 實戰詳解

1. 觸發情境

2. 核心操作

3. 踩坑避雷與防護指南

行動檢核清單（Checklist）

第 10 章：MCP 伺服器 — 模型上下文協議擴充

步驟化 SOP 實戰詳解

1. 觸發情境

`edit` 工具的多層回退比對（Fallback Matching）

`SKILL.md` 規範剖析

2. 觸發情境：平行宇宙探索 — `--fork` 分岔實驗

1. 建立「AI 初審＋人類終審」雙軌流水線

4. 執行 `opencode stats` 定期財務對帳