子代理管理
在 Verdent 中理解與管理子代理
子代理是專門的 AI 代理，擁有各自的自訂系統提示詞、獨立的上下文視窗，以及隔離的執行環境。它們處理由主代理委派的特定任務，而不會汙染主要對話的上下文。
主要特性：
- 隔離的上下文視窗： 每個子代理都維護各自獨立的上下文視窗。只有子代理回傳的最終結果會佔用主代理上下文中的空間，中間處理過程則不會。
- 自訂系統提示詞： 每個子代理都有專屬的系統提示詞，定義其行為、個性與任務解讀方式。
- 自動任務委派： 當偵測到適合的任務類型時，主代理會自動呼叫子代理，類似於自動工具選擇。
- 手動呼叫： 使用者可以透過 @-mention 明確引用子代理（
@Verifier、@Explorer、@Code-reviewer）。
兩種類別：
- 預設子代理： 內建（Verifier、Explorer、Code-reviewer）—— 可立即使用，已預先設定
- 自訂子代理： 由使用者建立，儲存於
~/.verdent/subagents/—— 針對專案特定需求量身打造
理解預設子代理
Verdent for VS Code 包含三個內建的預設子代理，皆已預先設定、可立即使用，且無需任何設定或配置。
專長： 快速程式碼檢查與驗證
能力：
- 驗證程式碼邏輯
- 檢查語法正確性
- 對照需求驗證實作
用法： 在程式設計任務中引用：
@Verifier check this authentication logic最適合： 在不需完整程式碼審查負擔的情況下快速驗證
專長： 快速探索與瀏覽程式碼庫
能力：
- 依模式或名稱尋找檔案
- 搜尋程式碼中的關鍵字／函式
- 回答架構相關問題
- 找出功能的實作位置
用法： 在程式碼庫相關問題中自動呼叫，或在明確要求時呼叫：
@Explorer find all API endpoints最適合：
- 理解不熟悉的程式碼庫
- 定位特定實作
- 架構分析
效能： Token 使用效率高，可平行執行多個實例以處理複雜搜尋
專長： 程式碼品質評估
能力：
- 主動掃描新增與修改的程式碼以發現安全漏洞
- 找出可維護性問題
- 偵測效能問題
用法： 引用以進行品質檢查：
@Code-reviewer review this authentication flow最適合：
- 提交前審查
- 在整合前找出問題
- 確保程式碼品質標準
自動呼叫與手動呼叫
自動選擇觸發條件：
主代理會根據任務模式辨識自動選擇子代理：
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 middlewareAdd Subagent 按鈕： 點擊輸入框中的 Add Subagent 按鈕可以：
- 從可用的子代理中選擇（預設與自訂）
- 明確將任務委派給選定的子代理
- 覆寫自動路由決策
手動指定的好處：
- 精準度： 確保由指定的子代理處理任務
- 覆寫： 當有多個子代理皆適用時，選擇特定的子代理
- 測試： 明確驗證自訂子代理的行為
- 一致性： 以相同的子代理重複處理任務，以獲得一致的結果
自訂子代理可能會根據其在子代理系統提示詞呼叫政策中定義的「使用時機」指引自動呼叫。關於觸發模式設定的詳細資訊目前仍在開發中。
建立自訂子代理
自訂子代理讓你能夠建立專門的代理，量身打造以符合專案特定需求、領域專業知識或團隊工作流程。
建立方式
建議新手使用
- 點擊 Settings → Subagents
- 選擇「Create new subagent」
- 定義子代理名稱、描述與系統提示詞
- 設定呼叫政策與使用指引
- 儲存至
~/.verdent/subagents/目錄
此方式提供引導式介面來建立子代理，並具備驗證與實用提示。
建議進階使用者使用
- 前往
~/.verdent/subagents/ - 建立 markdown 檔案（例如
security-reviewer.md） - 加入帶有
name與description的 YAML frontmatter - 撰寫定義行為的系統提示詞
- 指定呼叫政策與「使用時機」指引
此方式提供更多控制權，對熟悉檔案結構的使用者而言速度更快。
將自訂子代理儲存在 ~/.verdent/subagents/ 中，即可跨專案共用。它們將在所有工作區中可用。
檔案結構
自訂子代理檔案使用 Markdown 格式並搭配 YAML frontmatter：
---
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 2YAML 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自訂子代理範例
---
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 文件。
---
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使用情境： 在部署前找出有風險的資料庫操作，以防止正式環境事故。
---
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使用情境： 確保網頁應用程式在部署前符合無障礙標準。
自訂子代理的常見使用情境
領域特定專業知識
- 財務計算： 專精於稅務合規、財務法規的子代理
- 醫療 HIPAA 合規： 審查程式碼是否符合病患資料處理標準
- 密碼學： 對照最佳實務分析安全實作
適合具有專業知識需求與法規限制的產業。
團隊特定工作流程
- 程式碼風格強制器： 對照超出 linter 規則的團隊特定程式設計標準進行檢查
- 文件一致性： 確保文件遵循團隊範本與語氣
- 相依套件稽核器： 對照核准清單監控第三方套件的使用
強制執行團隊慣例，並在協作專案中維持一致性。
技術堆疊專家
- React 效能最佳化器： 找出不必要的重新渲染與 memoization 機會
- SQL 查詢最佳化器： 分析並改善資料庫查詢效能
- Docker 設定審查器： 驗證容器化最佳實務
對特定框架、語言或基礎架構技術的深度專業知識。
品質保證
- 測試覆蓋率分析器： 找出未測試的程式碼路徑，並建議測試情境
- 錯誤處理審查器： 確保完整的例外處理
- 日誌標準強制器： 驗證日誌實務以利除錯與監控
自動化品質檢查，以維持程式碼可靠性與可維護性標準。
合規與安全
- GDPR 合規檢查器： 審查資料處理是否符合隱私要求
- 安全漏洞掃描器： 針對框架特定問題的專門偵測
- 授權合規稽核器： 檢查相依套件的授權相容性
確保在部署前遵循法律、安全與授權要求。
專案特定需求
- 舊版程式碼現代化器： 找出過時模式，並建議現代替代方案
- 遷移助手： 引導框架或語言版本升級
- 效能預算強制器： 對照閾值監控套件大小與載入時間
針對獨特專案挑戰與技術債管理量身打造的自訂解決方案。
子代理行為設定（AGENTS.md 模式）
雖然 AGENTS.md 主要作為專案規則檔案（參見 規則系統），它也可以定義專案特定的子代理行為。
系統提示詞設計原則
具體且明確： 定義確切的行為預期，而非籠統的指引。
在系統提示詞中要具體且明確，「最佳化前先進行 profiling」比「盡可能嘗試最佳化」更好。
良好：
Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks避免：
Try to optimize code when possible建立個性與語氣： 建立針對特定用途最佳化的鮮明「人設」：
You are a performance optimization specialist.定義決策原則： 引導子代理應如何權衡取捨：
When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement指定輸出格式： 控制結果的呈現方式：
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams呼叫政策設定
Strict 政策：
Invocation policy (strict): Only run when explicitly requested.使用時機：
- 子代理處理敏感操作（安全審查、資料庫遷移）
- 使用者應有意識地決定何時呼叫
- 自動呼叫可能造成干擾
Flexible 政策：
Invocation policy (flexible): May auto-invoke based on task patterns.使用時機：
- 子代理提供有用的上下文而不造成干擾
- 自動呼叫能提升工作流程效率
- 任務模式可清楚辨識
使用指引最佳實務：
「使用時機」區段：
- 具體說明觸發情境
- 包含應該呼叫該子代理的範例提示
- 描述符合子代理專長的任務特性
「不該使用時機」區段：
- 明確列出排除情況，以防止不當呼叫
- 釐清與相關子代理之間的界線
- 防止範圍蔓延
任務路由與分派
Verdent 的多子代理系統可在多個專門代理之間實現平行任務執行，並具備自動路由與協調功能。
架構元件
主代理（協調者）： 主要代理會分析使用者請求、拆解複雜任務，並將專門工作委派給適當的子代理。它維護對話上下文並協調子代理的結果。
子代理池： 可呼叫（自動或手動）的可用子代理集合（包含預設與自訂）。每個子代理皆以隔離的上下文獨立運作。
自動任務路由： 當主代理偵測到符合子代理專長的任務模式時，它會自動分派工作：
- 程式碼庫探索問題 → Explorer 子代理
- 安全審查請求 → Code-reviewer 子代理
- 驗證檢查 → Verifier 子代理
平行執行： 多個子代理可同時執行複雜操作。例如：Explorer 子代理搜尋程式碼庫，同時 Code-reviewer 分析安全性，更快交付結果。
平行子代理執行可加速複雜任務，Explorer 可在 Code-reviewer 分析的同時進行搜尋。
結果整合： 子代理的輸出會回傳給主代理，主代理會綜合結果並向使用者呈現統一的回應。
關於子代理執行排程、優先順序、最大並行限制、錯誤處理與資源分配的詳細資訊目前仍在開發中。如有特定架構問題請聯絡支援團隊。
子代理監控
透過 Chat View 追蹤子代理使用狀況與效能，Verdent 會在此顯示子代理的操作與結果。
監控方式
Chat View 指示器：
- 子代理呼叫會出現在對話歷史中
- 進度指示器會顯示子代理執行的時機
- 結果會明確標示是哪個子代理提供的輸出
子代理輸出區段： 專門用於顯示：
- 子代理任務執行的結果
- 平行任務的進度指示器
- 任務完成時的整合摘要
回應歸屬： Verdent 會在回應中將結果歸屬於特定子代理，明確指出是哪個代理執行了哪項分析或搜尋。
可見性與透明度
操作透明度： Verdent 會顯示：
- 呼叫了哪個子代理
- 呼叫是自動還是手動
- 任務委派原因
- 子代理執行狀態
手動指定驗證： 當你使用 @-mention 時，Verdent 會確認指定的子代理正在處理任務，確保你的路由偏好受到尊重。
增強型監控功能，包括詳細的執行日誌、效能指標（執行時間、token 使用量）、歷史呼叫追蹤、活動可見性設定與使用分析儀表板，目前仍在開發中。