摘要
代理（Agent）是 OpenCode 的核心執行單元。每個代理都是一個具有特定角色、模型、工具與行為設定的 AI 工作者。本章介紹主代理與子代理的關係、五個內建代理的職責、如何用 JSON 與 Markdown 建立自訂代理，以及進階的代理協作模式。
學習目標
- 理解主代理（Primary）與子代理（Subagent）的差異
- 熟悉五個內建代理的用途與適用場景
- 學會以 JSON 與 Markdown 兩種方式建立自訂代理
- 掌握代理選項的完整設定
- 能夠設計多代理協作工作流
主代理 vs 子代理
OpenCode 的代理系統分為兩層：
- 主代理（Primary Agent） — 與你直接對話的代理。它負責理解你的需求、規劃執行步驟，並在必要時調度子代理。每次對話只有一個活躍的主代理。
- 子代理（Subagent） — 由主代理或 Task 工具啟動的輔助代理。它們在背景獨立運作，處理特定子任務後將結果回傳。多個子代理可以並行執行。
子代理的啟動方式：
# 透過 Task 工具（由主代理自動判斷）
請使用 Task 工具檢查這個函式的測試覆蓋率
# 透過指令指定
/delegate security-audit "檢查登入模組的安全性"內建代理
OpenCode 提供五個主要的內建代理，各自專精於不同領域：
Build 代理
角色：實作者。負責撰寫程式碼、執行指令、建立檔案。是絕大多數開發工作的主要執行者。
- 擅長：程式碼產生、除錯、重構、測試撰寫
- 可用工具：bash、edit、write、read、grep 等
- 適用場景：日常開發、功能實作、錯誤修正
Plan 代理
角色：規劃者。負責在實作前分析需求、設計架構、評估方案。
- 擅長：技術設計、架構規劃、風險評估
- 特點：會先仔細思考再給出建議，不輕易動手改程式碼
- 適用場景：功能設計、重構規劃、技術決策
General 代理
角色：通用助理。處理一般性問題、知識問答、非開發相關任務。
- 擅長：知識問答、概念解釋、文件撰寫
- 工具受限：通常不具備執行 bash 或編輯檔案的權限
- 適用場景：學習、研究、腦力激盪
Explore 代理
角色：探索者。負責深入分析程式碼庫、搜尋資訊、理解系統。
- 擅長：程式碼閱讀、依賴分析、影響範圍評估
- 特點：會大量使用 read 和 grep 工具來理解程式碼
- 適用場景：程式碼審查、技術債評估、入職熟悉專案
Scout 代理
角色：偵察兵。快速掃描專案結構、尋找特定檔案或模式。
- 擅長：快速檔案搜尋、模式比對、專案結構分析
- 特點：輕量、快速，通常使用較小的模型
- 適用場景：找檔案、檢查約定、快速盤點
隱藏代理
除了上述五個，還有一些隱藏代理（如 code、ask、architect、debug 等），可透過 /agent <name> 切換。這些代理是特定場景的專家版本。
自訂代理（JSON 方式）
在 opencode.json 的 agents 欄位中定義：
{
"agents": {
"docs-writer": {
"description": "專業技術文件寫手",
"mode": "build",
"model": "claude-sonnet-4-20250514",
"temperature": 0.4,
"prompt": "你是一位經驗豐富的技術文件工程師。你擅長將複雜的技術概念轉化為清晰、易懂的文件。\n\n寫作原則：\n1. 使用繁體中文\n2. 以讀者角度出發，預期他們的知識背景\n3. 提供具體的程式碼範例\n4. 必要時加入圖表說明（ASCII / Mermaid）",
"tools": {
"enabled": ["read", "write", "grep", "bash"],
"disabled": ["edit"]
},
"permission": "allow",
"hidden": false,
"color": "blue"
}
}
}自訂代理（Markdown 方式）
在 AGENTS.md 或 .opencode/agents/ 目錄下的 .mdc 檔案中定義：
.opencode/
agents/
docs-writer.mdc
security-auditor.mdc
code-reviewer.mdc範例 security-auditor.mdc：
---
name: security-auditor
description: 安全性稽核專家
mode: explore
model: claude-opus-4-20250514:max
temperature: 0.2
color: red
---
你是一位頂尖的應用安全工程師，專注於程式碼安全性稽核。
## 稽核重點
1. **注入攻擊** — SQL、NoSQL、Command、XSS、SSTI
2. **認證與授權** — 權限提升、身分驗證繞過
3. **敏感資料暴露** — 金鑰、憑證、PII
4. **設定不當** — CORS、HTTPS、HTTP headers
5. **依賴漏洞** — 過期套件、已知 CVE
## 回報格式
- 嚴重性（Critical / High / Medium / Low）
- 受影響的檔案與行號
- 漏洞說明與可能影響
- 修復建議與範例程式碼代理選項完整參考
以下是自訂代理可用的所有設定選項：
description— 代理的描述，顯示在代理選擇清單中mode— 代理模式：build（可執行程式碼）、plan（僅規劃）、explore（僅探索）、general（通用）model— 指定模型，支援變體（如claude-opus-4:max）prompt— 系統提示詞，定義代理的角色與行為temperature— 創造力控制（0.0 ~ 1.0）steps— 最大執行步數限制tools.enabled— 允許使用的工具清單tools.disabled— 停用的工具清單permission— 權限級別：allow（自動允許）、ask（每次詢問）、deny（拒絕）hidden— 是否從代理清單中隱藏color— 代理在 TUI 中的顏色標示group— 代理分組，用於組織多個代理
建立代理指令
OpenCode 提供 opencode agent create 指令，可透過互動式引導建立代理：
# 互動式建立
opencode agent create
# 直接指定名稱
opencode agent create my-agent指令會引導你設定代理的各項屬性，並自動產生對應的設定檔。
其他代理管理指令：
# 列出所有代理
opencode agent list
# 刪除代理
opencode agent delete my-agent
# 切換代理（TUI 中）
/agent docs-writer文件代理與安全稽核代理範例
文件代理（Documentation Agent）
{
"agents": {
"doc-agent": {
"description": "自動產生專案文件",
"mode": "explore",
"model": "claude-sonnet-4-20250514",
"prompt": "你是專業的技術文件撰寫者。你的任務是：\n1. 先探索專案結構與程式碼\n2. 理解每個模組的功能與職責\n3. 產生結構化的 Markdown 文件\n4. 確保文件涵蓋：API 說明、使用範例、注意事項",
"temperature": 0.3,
"tools": {
"enabled": ["read", "grep", "write", "glob"]
},
"color": "green",
"group": "production"
}
}
}安全稽核代理（Security Audit Agent）
{
"agents": {
"security-agent": {
"description": "自動化程式碼安全性稽核",
"mode": "explore",
"model": "claude-opus-4-20250514:max",
"prompt": "你是一位資深的白帽駭客，專注於原始碼安全審計。\n\n檢查重點：\n- OWASP Top 10 漏洞\n- 敏感資訊洩露（金鑰、token、密碼）\n- 不安全的第三方套件使用\n- 認證與授權邏輯缺陷\n\n每次稽核後需輸出：\n1. 發現總數與嚴重程度分布\n2. 每個漏洞的詳細說明與位置\n3. 修補建議與範例程式碼",
"temperature": 0.15,
"tools": {
"enabled": ["read", "grep", "glob", "bash"]
},
"color": "red",
"hidden": false
}
}
}實戰練習
練習 1：建立測試專用代理
建立一個專門負責撰寫測試的代理：
{
"agents": {
"test-writer": {
"description": "自動化測試撰寫專家",
"mode": "build",
"model": "claude-sonnet-4-20250514",
"prompt": "你是一位測試工程師，專注於撰寫高品質的自動化測試。\n\n原則：\n1. 遵循專案中現有的測試風格與框架\n2. 涵蓋正常路徑、邊界情況與錯誤路徑\n3. 使用有意義的測試名稱\n4. 每個測試只測試一個行為\n5. 避免測試內部實作細節",
"temperature": 0.3,
"permission": "ask"
}
}
}切換到測試代理後，請他為專案中的某個函式撰寫測試。
練習 2：建立多代理 code review 流程
組合多個代理形成完整的 code review pipeline：
{
"agents": {
"review-quality": {
"description": "程式碼品質審查",
"mode": "explore",
"model": "claude-sonnet-4-20250514",
"prompt": "審查程式碼品質：命名、架構、設計模式、程式碼異味。",
"color": "yellow"
},
"review-security": {
"description": "安全性審查",
"mode": "explore",
"model": "claude-opus-4-20250514:max",
"prompt": "審查程式碼安全性：OWASP Top 10、注入、認證問題。",
"color": "red"
},
"review-perf": {
"description": "效能審查",
"mode": "explore",
"model": "claude-haiku-4",
"prompt": "審查程式碼效能：演算法複雜度、資料庫查詢、記憶體使用。",
"color": "blue"
}
}
}試著對同一段程式碼分別使用三個代理審查，比較他們的發現。
練習 3：使用指令建立代理
使用 opencode agent create 指令建立一個「重構專家」代理：
opencode agent create refactor-expert依照互動提示設定：
- 描述：程式碼重構專家
- 模式：build
- 模型：claude-sonnet-4-20250514
- 溫度：0.3
- 權限：ask
建立完成後，用 /agent refactor-expert 切換並測試。