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

# 子代理

> 為特定任務建立專屬代理

子代理是專門處理專案範圍內任務的 AI 代理。主代理可以將工作委派給子代理，每個子代理擁有自己的工具與指令。

## 內建子代理

CTOR 包含兩個內建子代理：

| 名稱        | 說明                      | 工具                        |
| --------- | ----------------------- | ------------------------- |
| `general` | 通用代理，用於研究、多步驟編輯、指令執行與分析 | 所有內建工具（`spawn_agent` 除外）  |
| `explore` | 唯讀的程式碼庫搜尋與探索            | `read_file`、`glob`、`grep` |

內建子代理無法編輯或刪除。

## 管理子代理

點擊側邊欄工具列中的**子代理**按鈕，開啟管理面板。

### 範圍

子代理分為兩個範圍：

* **全域** —適用於所有開啟的專案。儲存於 `~/.bricks-project-desktop/agents/`。
* **專案** —僅適用於特定專案。儲存於專案的 `.bricks/agents/` 目錄中。

同名的專案範圍代理會覆蓋全域代理。同名的自訂全域代理會覆蓋內建代理。

### 建立子代理

1. 開啟**子代理**面板
2. 選擇**全域**範圍
3. 點擊**新增代理**
4. 在編輯器中編輯代理的 frontmatter 與指令
5. 點擊**儲存**

### 代理檔案格式

子代理為帶有 YAML frontmatter 的 markdown 檔案：

```markdown theme={null}
---
name: my-agent
description: Describe when to use this agent
thinking_level: low
tools:
  - read_file
  - glob
  - grep
---

You are a specialized agent. Describe your purpose and instructions here.
```

**Frontmatter 欄位：**

| 欄位               | 必填 | 說明                                                                                            |
| ---------------- | -- | --------------------------------------------------------------------------------------------- |
| `name`           | 是  | 代理的唯一識別碼                                                                                      |
| `description`    | 否  | 何時使用此代理（顯示於代理卡片中）                                                                             |
| `model`          | 否  | AI 模型覆蓋設定（例如 `anthropic/claude-haiku-4-5-20251001`）。請參閱[模型解析](#model-resolution)              |
| `thinking_level` | 否  | 思考層級覆蓋（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`）。請參閱[思考層級解析](#thinking-level-resolution) |
| `tools`          | 否  | 代理可使用的工具清單                                                                                    |

未指定 `tools` 清單（或設為 `null`）時，代理會獲得所有內建工具（`spawn_agent` 除外）。若要限制工具，只列出需要的項目：

**常用工具：** `read_file`、`glob`、`grep`

### 編輯子代理

點擊代理卡片上的**編輯**按鈕開啟編輯器。修改 frontmatter 或指令後，點擊**儲存**。

### 刪除子代理

點擊代理卡片上的**移除**按鈕，再次點擊確認。代理檔案將被永久刪除。

<Info>
  磁碟上代理檔案的變更會自動偵測。若您使用外部編輯器編輯代理檔案，面板會即時更新。
</Info>

## 指令檔案

Skill 可以透過自己附帶的指令檔案來驅動子代理（通常是 `general`）。產生代理時，主代理可傳入選用的 `instructions_file` 路徑—一個 Markdown 檔案，其內容會附加到子代理的系統提示中，置於 **Task-Specific Instructions** 標題之下。

### 運作方式

1. Skill 在 `SKILL.md` 旁附帶一個指令檔案（例如 `agents/grader.md`）
2. 主代理產生子代理時，將 `instructions_file` 指向該檔案
3. CTOR 會移除檔案的 frontmatter，並將內文原樣附加—不做樣板替換或變數替代
4. 指令中參照的任何輸入值（例如檔案路徑、設定）由呼叫者在任務提示中傳入

### 路徑解析

* **相對路徑**以專案根目錄為基準解析
* **絕對路徑**必須位於以下允許的目錄之一：
  * 專案目錄
  * 專案或全域 skill 目錄
  * 專案或全域代理目錄
  * 內建 skill 目錄

超出這些目錄的路徑會基於安全性被拒絕。

### 範例

一個包含 `agents/grader.md` 指令檔案的 skill：

```
my-skill/
├── SKILL.md
├── agents/
│   └── grader.md       # 給 general 子代理的指令
└── rules/
    └── conventions.md
```

`grader.md` 使用標準的代理檔案格式：

```markdown theme={null}
---
name: grader
---

Grade the outputs found in the directory specified in the task.
Compare each output against the expectations provided.
Write a summary report to the outputs directory.
```

主代理會使用此檔案產生 `general` 子代理，並在任務中傳入具體的值。

## 模型解析

子代理執行時，其模型按以下順序解析：

1. **代理檔案的 `model` 欄位** —若代理檔案指定了模型，則使用該模型
2. **設定預設值** —在設定中設定的預設子代理模型
3. **服務商特定預設值** —目前服務商的低成本模型：Anthropic 使用 `claude-haiku-4-5-20251001`，OpenAI Codex 和 GitHub Copilot 使用 `gpt-5.4-mini`，Google 使用 `gemini-3.5-flash`，OpenCode Zen 使用 `minimax-m2.5`，OpenCode Go 使用 `minimax-m2.7`
4. **工作階段模型** —目前工作階段所選的模型

這意味著子代理會自動為目前服務商使用低成本模型，無需逐一設定。

## 思考層級解析

子代理執行時，其思考層級按以下順序解析：

1. **代理檔案的 `thinking_level` 欄位** —若代理檔案指定了思考層級，則使用該層級
2. **設定預設值** —在設定中設定的預設子代理思考層級
3. **模型特定後備** —對於 OpenAI Responses API 上的推理模型，預設為 `low`