---
title: 子代理管理
description: 在 Verdent 中理解與管理子代理
---

子代理是專門的 AI 代理，擁有各自的自訂系統提示詞、獨立的上下文視窗，以及隔離的執行環境。它們處理由主代理委派的特定任務，而不會汙染主要對話的上下文。

**主要特性：**

- **隔離的上下文視窗：** 每個子代理都維護各自獨立的上下文視窗。只有子代理回傳的最終結果會佔用主代理上下文中的空間，中間處理過程則不會。
- **自訂系統提示詞：** 每個子代理都有專屬的系統提示詞，定義其行為、個性與任務解讀方式。
- **自動任務委派：** 當偵測到適合的任務類型時，主代理會自動呼叫子代理，類似於自動工具選擇。
- **手動呼叫：** 使用者可以透過 @-mention 明確引用子代理（`@Verifier`、`@Explorer`、`@Code-reviewer`）。

**兩種類別：**
- **預設子代理：** 內建（Verifier、Explorer、Code-reviewer）—— 可立即使用，已預先設定
- **自訂子代理：** 由使用者建立，儲存於 `~/.verdent/subagents/`—— 針對專案特定需求量身打造

---

## 理解預設子代理

Verdent for VS Code 包含三個內建的預設子代理，皆已預先設定、可立即使用，且無需任何設定或配置。

<Tabs>
  <Tab title="@Verifier">
    **專長：** 快速程式碼檢查與驗證

    **能力：**
    - 驗證程式碼邏輯
    - 檢查語法正確性
    - 對照需求驗證實作

    **用法：**
    在程式設計任務中引用：
    ```
    @Verifier check this authentication logic
    ```

    **最適合：** 在不需完整程式碼審查負擔的情況下快速驗證
  </Tab>

  <Tab title="@Explorer">
    **專長：** 快速探索與瀏覽程式碼庫

    **能力：**
    - 依模式或名稱尋找檔案
    - 搜尋程式碼中的關鍵字／函式
    - 回答架構相關問題
    - 找出功能的實作位置

    **用法：**
    在程式碼庫相關問題中自動呼叫，或在明確要求時呼叫：
    ```
    @Explorer find all API endpoints
    ```

    **最適合：**
    - 理解不熟悉的程式碼庫
    - 定位特定實作
    - 架構分析

    **效能：** Token 使用效率高，可平行執行多個實例以處理複雜搜尋
  </Tab>

  <Tab title="@Code-reviewer">
    **專長：** 程式碼品質評估

    **能力：**
    - 主動掃描新增與修改的程式碼以發現安全漏洞
    - 找出可維護性問題
    - 偵測效能問題

    **用法：**
    引用以進行品質檢查：
    ```
    @Code-reviewer review this authentication flow
    ```

    **最適合：**
    - 提交前審查
    - 在整合前找出問題
    - 確保程式碼品質標準
  </Tab>
</Tabs>

---

### 自動呼叫與手動呼叫

**自動選擇觸發條件：**

主代理會根據任務模式辨識自動選擇子代理：

**Explorer 子代理：**
- 關於程式碼庫結構的問題（「架構是什麼？」、「X 在哪裡實作？」）
- 檔案搜尋請求（「找出所有……的檔案」、「顯示與……相關的元件」）
- 程式碼瀏覽查詢（「驗證機制如何運作？」、「什麼會呼叫這個函式？」）

**Code-reviewer 子代理：**
- 安全審查請求（「審查安全漏洞」、「檢查 SQL injection 風險」）
- 程式碼品質評估提示（「分析程式碼品質」、「找出可維護性問題」）
- 提交前審查情境（在呈現程式碼變更時隱含觸發）

**Verifier 子代理：**
- 驗證請求（「驗證這個邏輯」、「檢查這個實作是否正確」）
- 語法與正確性檢查（「這段程式碼能運作嗎？」、「驗證驗證流程」）

**手動指定：**

使用者可以透過 @-mention 覆寫自動路由：

```
@Explorer find all authentication-related files
@Code-reviewer review the security of login flow
@Verifier check validation logic in middleware
```

**Add Subagent 按鈕：**
點擊輸入框中的 **Add Subagent** 按鈕可以：
- 從可用的子代理中選擇（預設與自訂）
- 明確將任務委派給選定的子代理
- 覆寫自動路由決策

**手動指定的好處：**
- **精準度：** 確保由指定的子代理處理任務
- **覆寫：** 當有多個子代理皆適用時，選擇特定的子代理
- **測試：** 明確驗證自訂子代理的行為
- **一致性：** 以相同的子代理重複處理任務，以獲得一致的結果

<Info>
自訂子代理可能會根據其在子代理系統提示詞呼叫政策中定義的「使用時機」指引自動呼叫。關於觸發模式設定的詳細資訊目前仍在開發中。
</Info>

---

## 建立自訂子代理

自訂子代理讓你能夠建立專門的代理，量身打造以符合專案特定需求、領域專業知識或團隊工作流程。

### 建立方式

<Tabs>
  <Tab title="設定選單">
    **建議新手使用**

    1. 點擊 **Settings** → **Subagents**
    2. 選擇「Create new subagent」
    3. 定義子代理名稱、描述與系統提示詞
    4. 設定呼叫政策與使用指引
    5. 儲存至 `~/.verdent/subagents/` 目錄

    此方式提供引導式介面來建立子代理，並具備驗證與實用提示。
  </Tab>

  <Tab title="直接建立檔案">
    **建議進階使用者使用**

    1. 前往 `~/.verdent/subagents/`
    2. 建立 markdown 檔案（例如 `security-reviewer.md`）
    3. 加入帶有 `name` 與 `description` 的 YAML frontmatter
    4. 撰寫定義行為的系統提示詞
    5. 指定呼叫政策與「使用時機」指引

    此方式提供更多控制權，對熟悉檔案結構的使用者而言速度更快。

    <Tip>
    將自訂子代理儲存在 ~/.verdent/subagents/ 中，即可跨專案共用。它們將在所有工作區中可用。
    </Tip>
  </Tab>
</Tabs>

---

### 檔案結構

自訂子代理檔案使用 Markdown 格式並搭配 YAML frontmatter：

```markdown
---
name: subagent-name
description: Brief description of specialization
---
# System Prompt

[Behavior definition, personality, interpretation style]

Invocation policy (strict): Only run if explicitly requested.

When to use:
- Specific scenario 1
- Specific scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2
```

**YAML Frontmatter（必填）：**
- `name`：在 @-mention 中使用的子代理識別碼
- `description`：子代理用途的一行描述

**系統提示詞區段：**
定義子代理行為的 Markdown 內容：
- 個性與語氣
- 任務的解讀方式
- 輸出格式偏好
- 決策原則

**呼叫政策（必填）：**
```
Invocation policy (strict|flexible): Policy description
```
- **strict：** 僅在使用者明確要求時呼叫
- **flexible：** 允許根據任務模式自動呼叫

**使用指引：**
```
When to use the [name] agent:
- Bullet list of scenarios for invocation

When NOT to use:
- Bullet list of scenarios to avoid
```

---

### 自訂子代理範例

<Tabs>
  <Tab title="API 文件">
    ```markdown
    ---
    name: api-documenter
    description: Generates comprehensive API documentation from code
    ---
    # System Prompt

    You are an API documentation specialist.

    Documentation approach:
    - Extract endpoints, parameters, and responses from code
    - Generate OpenAPI/Swagger specifications
    - Include usage examples and error codes
    - Document authentication requirements

    Output format:
    - Markdown tables for endpoints
    - Code examples in multiple languages
    - Authentication flow diagrams

    Invocation policy (strict): Only run when explicitly requested.

    When to use:
    - User requests API documentation generation
    - Need to document REST/GraphQL endpoints
    - Creating developer guides

    When NOT to use:
    - Inline code comments
    - User-facing documentation
    ```

    **使用情境：** 透過分析路由處理器、控制器與 schema 定義，自動產生完整的 API 文件。
  </Tab>

  <Tab title="資料庫遷移">
    ```markdown
    ---
    name: migration-reviewer
    description: Reviews database migrations for safety and correctness
    ---
    # System Prompt

    You are a database migration safety specialist.

    Review checklist:
    - Check for destructive operations (DROP, DELETE without WHERE)
    - Verify reversible migrations (up/down compatibility)
    - Identify potential data loss scenarios
    - Validate index creation strategies
    - Check for blocking operations on large tables

    Risk assessment:
    - Categorize migrations: low/medium/high risk
    - Recommend staging environment testing for high-risk changes
    - Suggest rollback procedures

    Invocation policy (strict): Only run when explicitly requested.

    When to use:
    - User creates or modifies migration files
    - Pre-deployment migration review
    - Investigating migration failures

    When NOT to use:
    - Schema design from scratch
    - Query optimization
    ```

    **使用情境：** 在部署前找出有風險的資料庫操作，以防止正式環境事故。
  </Tab>

  <Tab title="無障礙">
    ```markdown
    ---
    name: a11y-auditor
    description: Audits frontend code for accessibility compliance
    ---
    # System Prompt

    You are an accessibility compliance specialist (WCAG 2.1 Level AA).

    Audit criteria:
    - Semantic HTML structure
    - ARIA labels and roles
    - Keyboard navigation support
    - Color contrast ratios
    - Screen reader compatibility
    - Focus management

    Report format:
    - Issues categorized by severity (critical/major/minor)
    - WCAG guideline references
    - Code examples showing fixes
    - Testing recommendations

    Invocation policy (flexible): May auto-invoke for UI component reviews.

    When to use:
    - User creates/modifies UI components
    - Pre-deployment accessibility checks
    - Compliance audits

    When NOT to use:
    - Backend API code
    - Build configuration files
    ```

    **使用情境：** 確保網頁應用程式在部署前符合無障礙標準。
  </Tab>
</Tabs>

---

### 自訂子代理的常見使用情境

<Tabs>
  <Tab title="領域專業知識">
    **領域特定專業知識**

    - **財務計算：** 專精於稅務合規、財務法規的子代理
    - **醫療 HIPAA 合規：** 審查程式碼是否符合病患資料處理標準
    - **密碼學：** 對照最佳實務分析安全實作

    適合具有專業知識需求與法規限制的產業。
  </Tab>

  <Tab title="團隊工作流程">
    **團隊特定工作流程**

    - **程式碼風格強制器：** 對照超出 linter 規則的團隊特定程式設計標準進行檢查
    - **文件一致性：** 確保文件遵循團隊範本與語氣
    - **相依套件稽核器：** 對照核准清單監控第三方套件的使用

    強制執行團隊慣例，並在協作專案中維持一致性。
  </Tab>

  <Tab title="技術堆疊">
    **技術堆疊專家**

    - **React 效能最佳化器：** 找出不必要的重新渲染與 memoization 機會
    - **SQL 查詢最佳化器：** 分析並改善資料庫查詢效能
    - **Docker 設定審查器：** 驗證容器化最佳實務

    對特定框架、語言或基礎架構技術的深度專業知識。
  </Tab>

  <Tab title="品質保證">
    **品質保證**

    - **測試覆蓋率分析器：** 找出未測試的程式碼路徑，並建議測試情境
    - **錯誤處理審查器：** 確保完整的例外處理
    - **日誌標準強制器：** 驗證日誌實務以利除錯與監控

    自動化品質檢查，以維持程式碼可靠性與可維護性標準。
  </Tab>

  <Tab title="合規">
    **合規與安全**

    - **GDPR 合規檢查器：** 審查資料處理是否符合隱私要求
    - **安全漏洞掃描器：** 針對框架特定問題的專門偵測
    - **授權合規稽核器：** 檢查相依套件的授權相容性

    確保在部署前遵循法律、安全與授權要求。
  </Tab>

  <Tab title="專案特定">
    **專案特定需求**

    - **舊版程式碼現代化器：** 找出過時模式，並建議現代替代方案
    - **遷移助手：** 引導框架或語言版本升級
    - **效能預算強制器：** 對照閾值監控套件大小與載入時間

    針對獨特專案挑戰與技術債管理量身打造的自訂解決方案。
  </Tab>
</Tabs>

---

## 子代理行為設定（AGENTS.md 模式）

雖然 AGENTS.md 主要作為專案規則檔案（參見 [規則系統](/docs/verdent-for-vscode/agents-rules/rule-systems)），它也可以定義專案特定的子代理行為。

### 系統提示詞設計原則

**具體且明確：**
定義確切的行為預期，而非籠統的指引。

<Tip>
在系統提示詞中要具體且明確，「最佳化前先進行 profiling」比「盡可能嘗試最佳化」更好。
</Tip>

**良好：**
```markdown
Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks
```

**避免：**
```markdown
Try to optimize code when possible
```

**建立個性與語氣：**
建立針對特定用途最佳化的鮮明「人設」：

```markdown
You are a performance optimization specialist.
```

**定義決策原則：**
引導子代理應如何權衡取捨：

```markdown
When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement
```

**指定輸出格式：**
控制結果的呈現方式：

```markdown
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams
```

---

### 呼叫政策設定

**Strict 政策：**
```markdown
Invocation policy (strict): Only run when explicitly requested.
```

使用時機：
- 子代理處理敏感操作（安全審查、資料庫遷移）
- 使用者應有意識地決定何時呼叫
- 自動呼叫可能造成干擾

**Flexible 政策：**
```markdown
Invocation policy (flexible): May auto-invoke based on task patterns.
```

使用時機：
- 子代理提供有用的上下文而不造成干擾
- 自動呼叫能提升工作流程效率
- 任務模式可清楚辨識

**使用指引最佳實務：**

**「使用時機」區段：**
- 具體說明觸發情境
- 包含應該呼叫該子代理的範例提示
- 描述符合子代理專長的任務特性

**「不該使用時機」區段：**
- 明確列出排除情況，以防止不當呼叫
- 釐清與相關子代理之間的界線
- 防止範圍蔓延

---

## 任務路由與分派

Verdent 的多子代理系統可在多個專門代理之間實現平行任務執行，並具備自動路由與協調功能。

### 架構元件

**主代理（協調者）：**
主要代理會分析使用者請求、拆解複雜任務，並將專門工作委派給適當的子代理。它維護對話上下文並協調子代理的結果。

**子代理池：**
可呼叫（自動或手動）的可用子代理集合（包含預設與自訂）。每個子代理皆以隔離的上下文獨立運作。

**自動任務路由：**
當主代理偵測到符合子代理專長的任務模式時，它會自動分派工作：
- 程式碼庫探索問題 → Explorer 子代理
- 安全審查請求 → Code-reviewer 子代理
- 驗證檢查 → Verifier 子代理

**平行執行：**
多個子代理可同時執行複雜操作。例如：Explorer 子代理搜尋程式碼庫，同時 Code-reviewer 分析安全性，更快交付結果。

<Note>
平行子代理執行可加速複雜任務，Explorer 可在 Code-reviewer 分析的同時進行搜尋。
</Note>

**結果整合：**
子代理的輸出會回傳給主代理，主代理會綜合結果並向使用者呈現統一的回應。

<Info>
關於子代理執行排程、優先順序、最大並行限制、錯誤處理與資源分配的詳細資訊目前仍在開發中。如有特定架構問題請聯絡支援團隊。
</Info>

---

## 子代理監控

透過 Chat View 追蹤子代理使用狀況與效能，Verdent 會在此顯示子代理的操作與結果。

### 監控方式

**Chat View 指示器：**
- 子代理呼叫會出現在對話歷史中
- 進度指示器會顯示子代理執行的時機
- 結果會明確標示是哪個子代理提供的輸出

**子代理輸出區段：**
專門用於顯示：
- 子代理任務執行的結果
- 平行任務的進度指示器
- 任務完成時的整合摘要

**回應歸屬：**
Verdent 會在回應中將結果歸屬於特定子代理，明確指出是哪個代理執行了哪項分析或搜尋。

### 可見性與透明度

**操作透明度：**
Verdent 會顯示：
- 呼叫了哪個子代理
- 呼叫是自動還是手動
- 任務委派原因
- 子代理執行狀態

**手動指定驗證：**
當你使用 @-mention 時，Verdent 會確認指定的子代理正在處理任務，確保你的路由偏好受到尊重。

<Info>
增強型監控功能，包括詳細的執行日誌、效能指標（執行時間、token 使用量）、歷史呼叫追蹤、活動可見性設定與使用分析儀表板，目前仍在開發中。
</Info>

---

## 另請參閱

<CardGroup cols={2}>
  <Card title="規則系統與行為指引" icon="sliders" href="/docs/verdent-for-vscode/agents-rules/rule-systems">
    透過使用者規則、專案規則與計畫規則設定 Verdent 的行為
  </Card>
  <Card title="工具參考" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference">
    可用工具與功能的完整參考
  </Card>
</CardGroup>