代理系統

摘要

代理（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
    }
  }
}

實戰練習

{
  "agents": {
    "test-writer": {
      "description": "自動化測試撰寫專家",
      "mode": "build",
      "model": "claude-sonnet-4-20250514",
      "prompt": "你是一位測試工程師，專注於撰寫高品質的自動化測試。\n\n原則：\n1. 遵循專案中現有的測試風格與框架\n2. 涵蓋正常路徑、邊界情況與錯誤路徑\n3. 使用有意義的測試名稱\n4. 每個測試只測試一個行為\n5. 避免測試內部實作細節",
      "temperature": 0.3,
      "permission": "ask"
    }
  }
}

{
  "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"
    }
  }
}

opencode agent create refactor-expert