> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt
> Use this file to discover all available pages before exploring further.

子智能体（Subagent）是一种通过 Markdown 文件定义的专用智能体。SOLO Agent 会在识别到合适任务时自动调用对应的 Subagent。

Subagent 拥有独立的上下文窗口。它的中间推理和执行过程不会污染 SOLO Agent 的对话历史，因此适合处理需要大量检索、分析或推理，但最终只需要返回结果的任务。

## 了解 Subagent {#hTa0IRZUS}

### 调用机制 {#hffEtN3G1}

SOLO Agent 调用 Subagent 的流程如下：

1. **用户发送消息**：用户发送消息后，SOLO Agent 判断当前任务类型。
2. **匹配** **`description`**：SOLO Agent 将用户意图与所有可用 Subagent 的 `description` 字段进行匹配。
3. **决定是否调用**：如果某个 Subagent 的 `description` 与任务高度相关，SOLO Agent 会自动将任务委派给它。
4. **执行任务**：Subagent 在自己的上下文窗口和工具权限范围内完成任务。
5. **返回结果**：Subagent 将结果返回给 SOLO Agent，由 SOLO Agent 汇总并呈现给用户。

### Subagent 类型 {#hW2VqEg4U}

<!-- @cols-width: 131,285,446 -->
|**类型** |**作用范围** |**配置文件路径** |
|---|---|---|
|用户级 Subagent |用户级 Subagent 对当前设备上的所有项目生效。 |* macOS & Linux：`~/.trae-cn/agents/{my_agent}.md` |\
| | |* Windows：`%userprofile%/.trae-cn/agents/{my_agent}.md` |
|项目级 Subagent |项目级 Subagent 跟随当前项目的代码仓库，因此仅对当前项目生效。 |`{project_folder}/.trae/agents/{my_agent}.md` |

### Subagent 覆盖规则 {#hLeuiqvz3}

如果多个 `{my_agent}.md` 文件中定义了同名的 Subagent，将遵循以下覆盖规则：

* 项目级 Subagent 会覆盖同名的用户级 Subagent。
* 对于同一类型（用户级或项目级）的多个同名 Subagent，只有最先被加载的会生效，其后的将被忽略。

### 适用场景 {#hsZfDWKOh}

你可以将高频、重复、边界清晰的工作流封装为可复用的 Subagent，例如：

* **重复性流程**：如固定格式的代码审查、测试生成、文档检查。
* **专业任务**：如安全审计、性能分析、依赖风险检查。
* **上下文隔离**：任务需要读取大量文件或进行多轮分析，但不希望占用主对话上下文。
* **固化团队规范**：将团队约定、检查清单和输出格式固化为项目级 Subagent。

### 使用限制 {#hQkZgnfrs}

仅 SOLO 模式中的 SOLO Agent 可调用 Subagent。

## 创建 Subagent {#ha9qdePcs}

### 启用 Subagent 功能 {#hzQP6VTmM}

Subagent 功能通常已默认开启。若未开启，可通过以下步骤开启：

1. 前往 **设置** > **Beta**。
2. 在 **Subagents** 处，打开 **启用 Subagents 目录** 开关。
   ![Image=650x111](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/4fd8b37deacb4ca0a5be3014d5469b1c)   


### 编写 Subagent 文件 {#hxE9PFpWv}

Subagent 配置文件使用 Markdown 格式，由两部分组成：

* **YAML frontmatter**：定义 Subagent 的基础元信息，例如名称、描述、可用的工具和 MCP Server。
* **系统提示词**：定义 Subagent 的角色、工作流程、行为边界和输出格式等。

基础结构如下：

```Markdown
---
name: {my-agent}
description: {Describe when SOLO Agent should invoke this Subagent}
model: {modelName}
tools: {toolName}, {toolName}, {toolName}
disallowedTools: {toolName}, {toolName}, {toolName}
mcpServers:
    - {mcpServerName}
    - {mcpServerName}
---

{systemPrompt}
```

frontmatter 字段说明如下：

<!-- @cols-width: 139,100,100,525 -->
|**字段** |**类型** |**是否必填** |**描述** |
|---|---|---|---|
|name |string |是 |Subagent 的唯一标识。 |\
| | | | |\
| | | |必须以字母开头，中间可包含字母、数字和连字符 `-`，以字母或数字结尾，长度不超过 50 个字符。建议使用清晰、唯一的名称，例如 `code-reviewer`、`unit-test-writer`。  |
|description |string |是 |描述 SOLO Agent 应在什么场景下调用该 Subagent。 |\
| | | | |\
| | | |描述越具体，调度越准确；过于模糊可能导致应调用时未调用，或不该调用时误触发。 |
|model |string |否 |指定该 Subagent 使用的模型。 |\
| | | | |\
| | | |仅支持指定 TRAE IDE 提供的内置模型，不支持自定义模型。详情参考下文 “可用模型” 列表。 |\
| | | | |\
| | | |若不配置该字段，则默认使用你在 IDE 的 AI 对话输入框中为 SOLO Agent 所选择的模型。 |
|tools |string |否 |允许该 Subagent 使用的工具，多个工具用英文逗号分隔。详情参考下文 “可用工具” 列表。 |\
| | | | |\
| | | |若不配置，默认加载全部可用工具；若不希望调用任何工具，可设置为 `""`。 |
|disallowedTools |string |否 |禁止该 Subagent 使用的工具，多个工具用英文逗号分隔。 |\
| | | | |\
| | | |若某个工具同时出现在 `tools` 和 `disallowedTools` 中，`disallowedTools` 优先级更高。  |
|mcpServers |list |否 |允许该 Subagent 调用的 MCP Server 的名称。填写前需确认对应 MCP Server 已在 IDE 中配置并启用。 |

### 可用模型 {#hEr4d7s7P}

Subagent 可调用的模型如下：

<!-- @cols-width: 322,330 -->
|**模型名称** |**应在** **`model` 字段中填入的值** |
|---|---|
|Doubao-Seed-2.1-Pro |`Doubao-Seed-2.1-Pro` |
|Doubao-Seed-2.1-Turbo |`Doubao-Seed-2.1-Turbo` |
|Doubao-Seed-Code |`Doubao_1_6` |
|MiniMax-M3 |`minimax-m3` |
|MiniMax-M2.7 |`minimax-m2.7` |
|GLM-5.2 |`glm-5.2` |
|GLM-5.1 |`glm-5.1` |
|GLM-5V-Turbo |`glm-5v-turbo` |
|GLM-5 |`glm-5` |
|DeepSeek-V4-Pro |`DeepSeek-V4-Pro` |
|DeepSeek-V4-Flash |`DeepSeek-V4-Flash` |
|Kimi-K2.7-Code |`kimi-k2.7-code` |
|Kimi-K2.6 |`kimi-k2.6` |
|Qwen3.7-Plus |`qwen-3.7-plus` |
|Qwen3.6-Plus |`qwen-3.6-plus` |

### 可用工具 {#hDtRX9lmQ}

Subagent 可调用的工具如下：

<!-- @cols-width: 283,579 -->
|**工具名称** |**功能** |
|---|---|
|Bash |运行终端命令。 |
|Edit |编辑或删除文件。 |
|Glob |按文件名模式搜索文件。 |
|Grep |按内容正则搜索。 |
|Read |读取文件或目录。 |
|Skill |调用 Skill。 |
|TodoWrite |管理任务清单。 |
|WebFetch |抓取网页内容。 |
|WebSearch |在网络上搜索。 |
|Write |创建或覆写文件。 |
|LSP |通过 Language Server 检查语法问题。 |
|mcp__<server_name>__<tool_name> |限定调用某个 MCP Server 下的指定工具，需配合 `mcpServers` 字段一起使用，例如 `mcp__github__get_issue`（限定调用 `GitHub` MCP 中的 `get_issue` 工具）。 |

## 最佳实践 {#hYVjxTsod}

### `description` 编写范例 {#hC1sNS5Ng}

<!-- @cols-width: 607,254 -->
|✅ **推荐写法** |❌ **不推荐写法** |
|---|---|
|"Reviews code for quality and best practices when user asks for code review" |"Code reviewer" |
|"Generates unit tests for TypeScript files using Jest framework" |"Write tests" |
|"Analyzes and explains complex Go code when user asks 'what does this do'" |"Helper" |

### Prompt 编写建议 {#hwsitcb6V}

* **明确角色定位**：开头说明 Subagent 的身份和专业领域。
* **定义工作流程**：使用编号列表描述执行步骤。
* **约束输出格式**：如果期望输出特定格式（如 JSON、表格）的内容，应明确说明。
* **设定行为边界**：说明哪些事情不应做，例如 “只读，不修改文件”。
* **保持简洁**：Prompt 越短，调用成本越低，执行也更稳定。

## 调试与排查 {#hrl3sNKe1}

### Subagent 没有被调用？ {#hw47HQ3Sx}

<!-- @cols-width: 207,634 -->
|**检查项** |**排查方法** |
|---|---|
|功能开关 |前往 **设置** > **Beta** > **Subagents**，确认 **启用 Subagents 目录** 开关已打开。 |
|文件路径 |确认用户级和项目级 Subagent 的配置文件都位于正确的目录。 |
|`name` 的合法性 |确认 `name` 以字母开头，只包含字母、数字和连字符，并以字母或数字结尾，长度不超过 50。 |
|`description` 是否存在 |缺少 `description` 的文件不会被正常解析。 |
|frontmatter 格式 |确认 frontmatter 部分为标准 YAML：以 `---` 开头和结束，且没有 BOM。 |
|`description` 的匹配度 |尝试在指令中使用 `description` 里的关键词，验证该 Subagent 是否能被调用。 |

### **Subagent 被调用但行为不符合预期？** {#hOeylyKTt}

* 检查 `tools` 字段中添加的工具是否过多或不足，必要时遵循最小权限原则。
* 检查 Prompt 是否存在歧义，尤其是任务边界、输出格式和禁止事项。
* 检查是否存在同名 Subagent，导致当前 Subagent 被覆盖。
* 检查是否需要补充项目背景、技术栈、代码风格或示例输出。
* 如果涉及 MCP 调用，确认 `mcpServers` 字段中添加的 MCP Server 名称与 IDE 中配置的名称一致。

## 示例 {#hkUuSlvgQ}

### 代码审查专家 {#hEiuHKXt3}

该示例适用于代码审查场景，可用于检查代码质量、识别潜在风险，并评估实现是否符合最佳实践。该示例中，`code-reviewer` 仅可以调用读取和检索类工具。因此，它可以在不修改仓库内容的前提下分析目标文件，并按固定格式输出审查结论，适合作为合并前检查或日常 CR 辅助工具。

```Markdown
---
name: code-reviewer
description: Reviews code for quality, security, and best practices when user asks for code review or CR
tools: Read, Glob, Grep
---

You are a senior code reviewer with expertise in TypeScript and React.

When invoked, follow this workflow:
1. Identify the files to review (from user context or recent changes)
2. Read each file carefully
3. Analyze for: logic errors, security vulnerabilities, performance issues, code style

Output format:
- Use a table with columns: File | Line | Severity | Issue | Suggestion
- Severity levels: 🔴 Critical, 🟡 Warning, 🔵 Info
- End with a summary: total issues found, overall assessment
```

### 单测生成器 {#hwug3eSfO}

该示例适用于为指定函数、模块或文件补充单元测试。`unit-test-writer` 会先读取目标源码，并参考项目中已有的测试风格，再生成覆盖正常路径、边界条件和异常分支的测试用例，适合用于提升测试覆盖率，或为新功能快速补齐基础验证。

```Markdown
---
name: unit-test-writer
description: Generates unit tests for specified functions or files when user asks to write or generate tests
tools: Read, Glob, Grep, Write
---

You are a test engineer specializing in unit test generation.

When invoked:
1. Read the target file to understand the functions and their signatures
2. Identify edge cases, boundary conditions, and error paths
3. Generate comprehensive test cases using the project's testing framework

Rules:
- Match the project's existing test style (check existing test files first)
- Cover: happy path, edge cases, error handling
- Use descriptive test names that explain the scenario
- Do NOT modify the source code, only create/edit test files
```

### 项目引导员 {#hZUvlZxPY}

该示例适用于项目成员快速了解代码仓库结构、研发规范和关键流程。`project-guide` 会以只读方式检索仓库文档和源码信息，帮助新成员定位模块边界、构建流程和约定说明，从而减少重复沟通成本。

```Markdown
---
name: project-guide
description: Answers questions about project architecture, conventions, and onboarding when new members ask about the project
model: minimax-m3
tools: Read, Glob, Grep
---

You are a project guide for this repository. Your job is to help team members
understand the codebase structure, conventions, and architecture decisions.

When answering questions:
1. First search for relevant files and documentation
2. Provide concise, accurate answers with file path references
3. If unsure, say so and suggest where to look

Key areas you should know:
- Project structure and module boundaries
- Naming conventions and code style
- Build and deployment process
- Key dependencies and their roles
```

### MCP 集成：GitHub Issue 分类 {#hbi43Bjwa}

该示例适用于将 Subagent 接入外部平台能力，完成自动化协作任务。通过配置指定的 MCP Server 和工具白名单，`github-issue-triager` 可以读取 GitHub Issue 内容，并按照预设规则完成分类、打标和回复草稿生成，适合用于规范和统一 Issue 处理流程。

```Markdown
---
name: github-issue-triager
description: Automatically triages, labels, and responds to GitHub issues when user asks to handle or triage issues
tools: Read, mcp__github__get_issue, mcp__github__update_issue, mcp__github__add_issue_comment
mcpServers:
    - GitHub
---

You are a GitHub issue triage specialist.

When invoked with an issue number or URL:
1. Fetch the issue details
2. Analyze the content to determine: type (bug/feature/question), priority, affected area
3. Apply appropriate labels
4. If it's a question with an obvious answer, draft a helpful response

Label mapping:
- Bug reports → "bug" + severity label
- Feature requests → "enhancement"
- Questions → "question"
```

### 安全审计（只读） {#hXoKqftpQ}

该示例适用于对代码仓库进行安全风险排查。`security-auditor` 仅具备读取和检索权限，可用于识别硬编码密钥、注入风险、XSS 攻击面等问题，并输出包含风险等级、文件位置和修复建议的安全报告。

```Markdown
---
name: security-auditor
description: Performs security audit on code looking for vulnerabilities, secrets, and unsafe patterns
model: glm-5.2
tools: Read, Glob, Grep
---

You are a security auditor. Scan code for:
- Hardcoded secrets (API keys, passwords, tokens)
- SQL injection vulnerabilities
- XSS attack vectors
- Unsafe deserialization
- Insecure dependencies

Output a security report with:
- Risk level (Critical/High/Medium/Low)
- File and line reference
- Description of the vulnerability
- Recommended fix

IMPORTANT: You are read-only. Do NOT modify any files.
```