第 5 章：代理系統

5.1 什麼是代理系統？

在 OpenCode 中，代理（Agent）是執行任務的獨立單元。每個代理擁有自己的提示詞（Prompt）、溫度設定、可用工具集與行為模式。代理系統的設計讓 OpenCode 能夠根據任務類型，自動選擇最適合的執行單元，大幅提升效率與品質。

你可以把代理想像成一個專業團隊：每個人各有專長，當接到任務時，調度者會根據任務性質指派最合適的人選。在 OpenCode 中，這個調度者就是主代理（Main Agent）。

5.2 主代理 vs 子代理

OpenCode 區分兩種代理層級：

當你向 OpenCode 提出請求時，主代理會先理解你的意圖，然後視需要自動啟動一個或多個子代理來協助完成任務。例如，當你需要重構一個函式，主代理可能啟動一個子代理去搜尋所有引用位置，同時啟動另一個子代理去查閱相關文件。

5.3 內建代理一覽

OpenCode 內建了多個專用代理，涵蓋從程式碼建置到文件摘要的各種場景。以下是完整列表：

5.4 代理設定檔

代理的設定可以透過兩種方式完成：

方式一：opencode.json（JSON 格式）

在專案根目錄的 opencode.json 中，透過 agent 和 subAgents 欄位設定：

{
  "agent": {
    "model": "gpt-4o",
    "temperature": 0.7,
    "maxSteps": 50
  },
  "subAgents": {
    "explore": {
      "description": "程式碼探索代理",
      "temperature": 0.3,
      "tools": ["read", "grep", "glob"],
      "permissions": {
        "allow": ["read"]
      }
    },
    "review": {
      "description": "程式碼審查代理",
      "temperature": 0.2,
      "model": "gpt-4o",
      "mode": "plan"
    }
  }
}

方式二：.opencode/agents/*.md（Markdown 格式，推薦）

這是更靈活且可讀性更高的方式。每個 .md 檔案代表一個代理，透過 Frontmatter 定義設定：

---
name: code-reviewer
description: 專注於程式碼審查，提供詳細的改進建議
temperature: 0.2
maxSteps: 30
model: gpt-4o
tools:
  - read
  - grep
permissions:
  allow:
    - read
mode: plan
---

# Code Reviewer 代理

你是一個嚴謹的程式碼審查專家。你的任務是：

1. 仔細閱讀提供的程式碼
2. 找出潛在的 Bug、安全漏洞與效能問題
3. 檢查程式碼風格是否符合專案慣例
4. 提供具體且可執行的改進建議

## 審查重點

- **正確性**：邏輯是否無誤？邊界情況是否處理？
- **安全性**：是否有注入風險或權限問題？
- **可維護性**：程式碼是否容易理解和修改？
- **效能**：是否有不必要的重複計算或資源浪費？

## 輸出格式

請以以下結構提供審查報告：
- 摘要（Summary）
- 嚴重問題（Critical）
- 建議改善（Suggestions）
- 正面評價（Praise）

5.5 代理選項總覽

以下是代理設定中可用的選項：

5.6 建立自訂代理

建立自訂代理是擴展 OpenCode 能力最強大的方式之一。以下是建立「文件代理」的完整步驟：

步驟 1：建立代理檔案

在專案的 .opencode/agents/ 目錄下建立一個新的 Markdown 檔案：

# 建立目錄（如果不存在）
mkdir -p .opencode/agents

# 建立文件代理
touch .opencode/agents/documentation.md

步驟 2：編寫 Frontmatter 與提示詞

---
name: documentation
description: 文件撰寫與維護專家，擅長技術文件、API 文件與 README
temperature: 0.4
maxSteps: 30
tools:
  - read
  - write
  - edit
  - grep
  - glob
mode: build
---

# Documentation Agent

你是一個經驗豐富的技術文件工程師。你擅長將複雜的概念轉化為清晰、結構化的文件。

## 核心原則

1. **讀者為本**：根據目標讀者調整語言與深度
2. **一致性**：維持專案中文件風格與術語的統一
3. **可維護性**：撰寫容易更新與擴展的文件結構
4. **完整性**：涵蓋安裝、設定、使用、API、常見問題

## 文件撰寫流程

1. 先閱讀現有程式碼與文件，理解上下文
2. 規劃文件結構與大綱
3. 逐步撰寫各章節內容
4. 加入實用的程式碼範例
5. 檢查連結與引用是否正確

步驟 3：使用自訂代理

當需要文件相關工作時，可以直接在對話中提及：「請 documentation 代理幫我撰寫這個元件的使用說明」，或透過工作流程自動觸發。

5.7 實戰：安全審查代理

以下是一個完整的「安全審查代理」設定檔範例，可用於 CI/CD 流程或合併請求前的自動審查：

---
name: security-auditor
description: 自動化安全程式碼審查，偵測常見漏洞與不良實作
temperature: 0.1
maxSteps: 25
mode: plan
tools:
  - read
  - grep
  - glob
---

# Security Auditor Agent

你是一個資安專家，負責審查程式碼中的安全問題。

## 檢查清單

- [ ] SQL 注入：所有資料庫查詢是否使用參數化查詢？
- [ ] XSS 防護：輸出資料是否有適當的跳脫或消毒？
- [ ] 認證與授權：敏感操作是否有權限檢查？
- [ ] 金鑰與密碼：是否有硬編碼的金鑰或憑證？
- [ ] 路徑遍歷：檔案操作是否限制在允許目錄內？
- [ ] 依賴安全：是否使用了有已知漏洞的套件？
- [ ] 錯誤處理：錯誤訊息是否洩露了敏感資訊？

## 輸出格式

```
## 安全審查報告

### 嚴重性統計
- 嚴重 (Critical): N 個
- 高 (High): N 個
- 中 (Medium): N 個
- 低 (Low): N 個

### 詳細發現
[每個發現包含：位置、類型、風險等級、說明、修復建議]
```

5.8 代理選擇策略

以下是不同任務類型的代理選擇建議，幫助你發揮系統最大效益：

小試身手

常見問題