《Cursor文檔》-子智能體

子智能體是 Cursor 智能體可委派任務的專用 AI 助手。每個子智能體都在獨立的上下文窗口中運行，負責處理特定類型的工作，並將結果返回給父智能體。使用子智能體可拆解複雜任務、並行處理工作，並保留主對話中的上下文。

您可以在編輯器、CLI 和 Cloud Agents 中使用子智能體。

上下文隔離¶

每個子智能體都有獨立的上下文窗口。耗時較長的研究或探索任務不會佔用主對話的空間。

並行執行¶

同時啓動多個子智能體，無需等待前一個任務完成，即可處理代碼庫的不同部分。

專業能力¶

可爲子智能體配置自定義提示詞、工具訪問權限和模型，以處理特定領域的任務。

可複用性¶

定義自定義子智能體，並在多個項目中複用。

子智能體的工作方式¶

當 Agent 遇到複雜任務時，可自動啓動子智能體。子智能體會收到包含所有必要上下文的提示詞，自主完成任務，並返回包含結果的最終消息。

子智能體從空白上下文開始。由於無法訪問之前的對話記錄，父智能體會在提示詞中提供相關信息。

前臺與後臺¶

子智能體可在以下兩種模式之一運行：

內置子智能體¶

Cursor 包含三個內置子智能體，可自動處理需要大量上下文的操作。這些子智能體的設計基於對上下文窗口達到限額的智能體對話的分析。

爲什麼需要這些子智能體¶

這三項操作有一些共同特點：會產生大量中間輸出、適合使用專門的提示詞和工具，而且可能佔用大量上下文。將它們作爲子智能體運行可解決多個問題：

• 上下文隔離 — 中間輸出會保留在子智能體中，父代理只會看到最終摘要。
• 模型靈活性 — Explore 子智能體默認使用速度更快的模型。這樣可以在一次主代理搜索所需的時間內，並行進行 10 次搜索。
• 專用配置 — 每個子智能體都配有針對特定任務優化的提示詞和工具訪問權限。
• 成本效率 — 更快的模型成本更低。爲子智能體選擇合適的模型，將消耗大量 token 的工作隔離開來，可降低總體成本。

無需配置這些子智能體。Agent 會在適當時自動使用它們。

何時使用子智能體¶

如果你發現自己爲“生成變更日誌”或“格式化導入”等簡單、目的單一的任務創建子智能體，請考慮改用技能。

快速開始¶

Agent 會在適當情況下自動使用子智能體。您也可以通過讓 Agent 創建自定義子智能體：

在 .cursor/agents/verifier.md 中創建一個子智能體文件，包含 YAML frontmatter（名稱、描述），後接提示詞。驗證方子智能體應驗證已完成的工作，檢查實現是否正常運行，運行測試，並報告哪些已通過、哪些尚未完成。

如需更多控制，可在項目或用戶目錄中手動創建自定義子智能體。

自定義子智能體¶

定義自定義子智能體，以沉澱專業知識、落實團隊規範或自動化重複性工作流。

文件位置¶

名稱衝突時，項目子智能體優先。如果多個位置包含同名子智能體，.cursor/ 的優先級高於 .claude/ 和 .codex/。

文件格式¶

每個子智能體都是一個包含 YAML frontmatter 的 markdown 文件：

---
name: security-auditor
description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
model: inherit
readonly: true
---

You are a security expert auditing code for vulnerabilities.

When invoked:
1. Identify security-sensitive code paths
2. Check for common vulnerabilities (injection, XSS, auth bypass)
3. Verify secrets are not hardcoded
4. Review input validation and sanitization

Report findings by severity:
- Critical (must fix before deploy)
- High (fix soon)
- Medium (address when possible)

配置字段¶

模型配置¶

model 字段用於指定子智能體使用的模型。有兩個選項：

當子智能體需要與父智能體相同的推理能力時，選擇 inherit。如果無論父智能體使用什麼模型，都需要某個特定模型的能力，請使用特定模型 ID。

模型參數¶

在模型 ID 後添加方括號，可設置速度、reasoning effort 和上下文窗口等模型專屬選項。選項採用 id=value 格式，多個選項之間用逗號分隔。

可用選項因模型而異，格式與 SDK 的模型參數相同，均使用 id=value 對。

---
name: planner
description: Plans complex changes before implementation.
model: claude-opus-5[effort=high]
---

Break the task into a clear, ordered implementation plan.

配置的模型何時不會生效¶

除非符合以下任一情況，否則 Cursor 會使用子智能體 frontmatter 中的 model 字段：

• 團隊管理員限制 — 您所在組織的管理員已禁止使用指定模型。
• 舊版 Max Mode 設置 — 在舊版按請求計費的方案中，該模型需要啓用 Max Mode，而您尚未啓用該模式。
• 方案限制 — 您當前的方案不支持該模型。

在這些情況下，Cursor 會改用兼容的模型。如果模型行爲不符合預期，請檢查您的方案和模型設置。

---
name: code-reviewer
description: Reviews code for correctness and style.
model: inherit
---

Review the code changes for bugs, style issues, and edge cases.

---
name: search-agent
description: Searches the codebase for relevant files and symbols.
model: inherit
---

Search the codebase and return relevant file paths and code snippets.

---
name: reasoning-agent
description: Handles complex architectural decisions.
model: gpt-5.6-sol
---

Analyze the architecture and recommend changes with detailed reasoning.

使用子智能體¶

自動委派¶

智能體會根據以下因素主動委派任務：

• 任務的複雜程度和範圍
• 項目中自定義子智能體的描述
• 當前上下文和可用工具

在描述字段中加入“主動使用”或“始終用於”等措辭，鼓勵自動委派。

顯式調用¶

在提示詞中使用 /name 語法指定特定的子智能體：

> /verifier confirm the auth flow is complete
> /debugger investigate this error
> /security-auditor review the payment module

你也可以在對話中自然地提及子智能體來調用它們：

> 使用驗證方子智能體確認認證流程已完成
> 讓調試子智能體排查此錯誤
> 讓安全審計子智能體審查支付模塊

並行執行¶

併發啓動多個子智能體，以獲得最大吞吐量：

> 並行評審 API 更改並更新文檔

智能體會在一條消息中發起多個 Task 工具調用，使子智能體能夠並行運行。

隔離的項目副本¶

默認情況下，子智能體共享父智能體的 checkout。多個子智能體同時編輯文件時，可能會互相覆蓋更改。啓用隔離後，每個子智能體都會在各自的項目副本中運行：

> 啓動一組子智能體修復這五個不穩定的測試，每個都在各自獨立的環境中運行

每個子智能體都有自己的環境和分支：要麼是在同一臺機器上、擁有獨立工作目錄的隔離 Git worktree，要麼是配有專屬 VM 和代碼倉庫克隆的雲端環境。每個子智能體的更改都會保留在各自的分支上，直到父智能體合併結果。

這是同一會話內子智能體級別的隔離。若要隔離整個智能體，請在 worktree 中運行它，或將任務交給雲端子智能體。

雲端子智能體¶

在本地智能體會話中，您可以將工作交給運行在獨立 VM 和分支上的雲端子智能體。長時間運行或並行任務在雲端執行時，您的本地工作區仍可保持整潔和流暢響應。父智能體會持續在本地或雲端運行，不受影響。您可在 Cursor 桌面端應用的代理窗口中運行雲端子智能體。

使用 /in-cloud 啓動雲端子智能體¶

輸入 /in-cloud 後，你提交的下一個任務將由雲端子智能體執行。它會啓動專屬 VM 和分支來處理該任務。

這適合將長時間運行或並行的工作隔離開來，例如修復 CI、排查問題，或在繼續本地工作的同時探索代碼庫。

使用 /babysit 跟進 PR¶

使用 /babysit 或點擊快捷操作按鈕，讓雲端子智能體跟進拉取請求。雲端代理會在遠程環境中持續迭代，爲 PR 合併做好準備，而不會佔用你的本地會話。

雲端子智能體使用爲你的倉庫配置的環境，並遵循與其他雲端代理相同的模型和能力規則。由於它們運行在雲端 VM 上，其 MCP 服務器使用的是團隊在 cursor.com/agents 中的配置，而非本地會話中的配置。

恢復子智能體¶

可以恢復子智能體，繼續之前的對話。這對於需要跨多次調用的長時間運行任務很有用。

每次執行子智能體都會返回一個智能體 ID。傳入此 ID，即可在保留完整上下文的情況下恢復子智能體：

> 恢復智能體 abc123，並分析剩餘的測試失敗

後臺子智能體會在運行過程中寫入自身狀態。子智能體完成後，您可以恢復它，以在保留上下文的情況下繼續對話。

常見用法¶

驗證智能體¶

驗證智能體會獨立覈實聲稱已完成的工作是否真的完成。這解決了一個常見問題：AI 會將任務標記爲已完成，但實現並不完整或存在錯誤。

---
name: verifier
description: Validates completed work. Use after tasks are marked done to confirm implementations are functional.
---

You are a skeptical validator. Your job is to verify that work claimed as complete actually works.

When invoked:
1. Identify what was claimed to be completed
2. Check that the implementation exists and is functional
3. Run relevant tests or verification steps
4. Look for edge cases that may have been missed

Be thorough and skeptical. Report:
- What was verified and passed
- What was claimed but incomplete or broken
- Specific issues that need to be addressed

Do not accept claims at face value. Test everything.

在 .cursor/agents/verifier.md 創建一個子智能體文件，並添加包含名稱和描述的 YAML frontmatter。描述應爲“驗證已完成的工作。在任務標記爲完成後使用，以確認實現是否正常運行。”提示詞正文應指示它保持審慎，通過運行測試驗證實現是否確實可用，並查找邊界情況。

此模式適用於：

• 在將工單標記爲完成前，驗證功能是否端到端正常運行
• 發現功能僅部分實現的情況
• 確保測試確實通過 (而不只是存在測試文件)

編排器模式¶

對於複雜工作流，父智能體可以依次協調多個專業子智能體：

1. 規劃者分析需求並制定技術方案
2. 實現者根據方案實現功能
3. 驗證者確認實現是否符合需求

每次交接都會提供結構化輸出，確保下一個智能體獲得清晰的上下文。

子智能體示例¶

調試器¶

---
name: debugger
description: Debugging specialist for errors and test failures. Use when encountering issues.
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach

Focus on fixing the underlying issue, not symptoms.

在 .cursor/agents/debugger.md 中創建一個子智能體文件，並添加包含名稱和描述的 YAML frontmatter。調試器子智能體應專注於根因分析：捕獲堆棧跟蹤、確定復現步驟、隔離故障、實施最小化修復並驗證解決方案。

測試運行器¶

---
name: test-runner
description: Test automation expert. Use proactively to run tests and fix failures.
---

You are a test automation expert.

When you see code changes, proactively run appropriate tests.

If tests fail:
1. Analyze the failure output
2. Identify the root cause
3. Fix the issue while preserving test intent
4. Re-run to verify

Report test results with:
- Number of tests passed/failed
- Summary of any failures
- Changes made to fix issues

在 .cursor/agents/test-runner.md 創建一個子智能體文件，並添加包含名稱和描述（提及“主動使用”）的 YAML frontmatter。test-runner 子智能體應在發現代碼更改時主動運行測試，分析失敗原因，在保留測試意圖的前提下修復問題，並報告結果。

最佳實踐¶

• 編寫職責明確的子智能體 — 每個子智能體都應有單一、明確的職責。避免使用泛泛的“助手”智能體。
• 重視描述 — description 字段決定 Agent 何時將任務委派給你的子智能體。花時間打磨它。通過編寫提示詞並檢查是否觸發了正確的子智能體來測試。
• 保持提示詞簡潔 — 冗長、鬆散的提示詞會分散重點。要具體、直接。
• 將子智能體納入版本控制 — 將 .cursor/agents/ 提交到代碼倉庫，讓團隊成員都能受益。
• 從 Agent 生成的智能體開始 — 先讓 Agent 幫你起草初始配置，再進行自定義。
• 使用鉤子處理文件輸出 — 如果需要子智能體生成結構化輸出文件，可考慮使用鉤子，以一致的方式處理和保存結果。

應避免的反模式¶

不要創建幾十個通用子智能體。 創建 50 多個帶有“協助編程”等模糊說明的子智能體並不高效。智能體不知道該在何時使用它們，你也會浪費時間維護它們。

• 描述模糊 — “用於一般任務”無法讓智能體判斷何時該委派任務。應明確說明：“用於通過 OAuth 提供商實現身份驗證流程時。”
• 提示詞過長 — 2,000 字的提示詞不會讓子智能體更聰明，只會讓它變慢，也更難維護。
• 重複設置斜槓命令 — 如果任務用途單一且不需要上下文隔離，請改用技能或命令。
• 子智能體過多 — 先從 2-3 個專注於特定任務的子智能體開始。只有在存在明確且不同的使用場景時，再添加更多。

管理子智能體¶

創建子智能體¶

創建子智能體最簡單的方式是讓 Agent 爲您創建：

在 .cursor/agents/security-reviewer.md 創建一個子智能體文件，並添加包含名稱和描述的 YAML frontmatter。security-reviewer 子智能體應檢查代碼中常見的漏洞，例如注入、XSS 和硬編碼的機密信息。

您也可以將 markdown 文件添加到 .cursor/agents/ (項目) 或 ~/.cursor/agents/ (用戶) 目錄，手動創建子智能體。

查看子智能體¶

Agent 可使用所有自定義子智能體。你可以查看項目中的 .cursor/agents/ 目錄，瞭解已配置哪些子智能體。

性能與成本¶

子智能體各有利弊。瞭解這些取捨有助於您判斷何時使用它們。

Token 和成本注意事項¶

• 子智能體會獨立消耗 token — 每個子智能體都有各自的上下文窗口和 token 用量。並行運行五個子智能體，消耗的 token 約爲單個智能體的五倍。
• 權衡額外開銷 — 對於快速簡單的任務，主智能體通常更快。子智能體更適合複雜、長時間運行或可並行處理的工作。
• 子智能體可能更慢 — 其優勢在於上下文隔離，而非速度。由於需要從零開始處理，子智能體執行簡單任務時可能比主智能體更慢。

常見問題¶

有哪些內置子智能體？¶

Cursor 提供三個內置子智能體：用於代碼庫搜索的 explore、用於運行 shell 命令的 bash，以及通過 MCP 實現瀏覽器自動化的 browser。它們會自動處理需要大量上下文的操作，無需配置。

子智能體可以啓動其他子智能體嗎？¶

可以，但受嵌套層級限制。自 Cursor 2.5 起，子智能體可以啓動子級子智能體，形成協同工作的樹狀結構。主智能體及其直屬子智能體可以啓動子智能體，但由子智能體啓動的子智能體無法再啓動更多子智能體。
嵌套啓動還要求當前模式有權訪問 Task 工具，鉤子或工具策略也可能阻止創建子智能體。

如何查看子智能體在做什麼？¶

後臺子智能體會將輸出寫入 ~/.cursor/subagents/。父智能體可以讀取這些文件以查看進度。

子智能體失敗時會怎樣？¶

子智能體會向父智能體返回錯誤狀態。父智能體可以重試、補充上下文後繼續執行，或以其他方式處理失敗。

可以在子智能體中使用 MCP 工具嗎？¶

可以。子智能體會繼承父智能體的所有工具，包括來自已配置服務器的 MCP 工具。雲端子智能體 是例外：它們在雲端 VM 上運行，使用的是在 cursor.com/agents 爲你的團隊配置的 MCP 服務器，而非本地會話中的服務器。

如何調試行爲異常的子智能體？¶

檢查子智能體的描述和提示詞，確保指令具體且明確。你也可以使用簡單任務顯式調用子智能體進行測試。

爲什麼我的子智能體使用了不同的模型？¶

當團隊管理員禁用了該模型、你的套餐不包含該模型，或舊版按請求計費套餐要求使用 Max Mode 而你尚未啓用時，Cursor 會覆蓋已配置的模型。在未啓用 Max Mode 的舊版按請求計費套餐中，無論 model 如何配置，子智能體都會使用 Composer 運行。如果團隊管理員禁用了 Composer，則子智能體僅能在啓用 Max Mode 時運行。在按用量計費套餐以及啓用了 Max Mode 的舊版按請求計費套餐中，子智能體默認使用父智能體的模型。詳見模型配置。