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

# 子智能体与委托

> 专家内部的子智能体分工，与跨专家委托的三个决定性配置——含工具白名单解析规则与被静默丢弃的情形

有两套完全不同的「分工」机制，配置项也在不同地方：

* **子智能体（subagents）**：**你的专家内部**的分工。你声明若干个带独立系统提示词和工具白名单的子角色，主智能体把子任务派给它们。
* **委托（delegation）**：**跨专家**协作。用户的另一个专家来找你的专家干活，或反过来。

两者互不相通——子智能体拿不到跨专家能力，这是硬约束，下面会讲到具体是怎么拦的。

<Note>
  本页内容核对日期 2026-08-11，来源见页尾「真值来源」。
</Note>

***

## 子智能体

### 规格结构

每个子智能体是一个对象，五个字段：

```json theme={null}
{
  "name": "contract_scanner",
  "description": "扫描合同全文，标出所有涉及金额、期限、违约责任的条款位置",
  "system_prompt": "你只负责定位和摘录，不做风险判断。输出格式为 JSON 数组，每项含 clause_type / original_text / location。",
  "tools": ["read", "grep", "glob"],
  "model": "claude-sonnet-4"
}
```

| 字段              | 必填 | 说明                     |
| --------------- | -- | ---------------------- |
| `name`          | 是  | 也是主智能体调用它时的参数值，须为标识符风格 |
| `description`   | 是  | 给主智能体看的「什么时候该派给它」      |
| `system_prompt` | 是  | 子智能体自己的系统提示词           |
| `tools`         | 否  | 工具白名单，支持通配符；不填等于空数组    |
| `model`         | 否  | 指定模型；不填则继承主智能体的默认模型    |

`model` 允许你做**模型异构**：让扫描类子智能体跑便宜快速的模型，判断类子智能体跑强模型。

### 工具白名单的三遍解析

你写的 `tools` 是文本名字，运行时要把它解析成真实工具对象。解析分三遍，顺序固定：

**第一遍——拒绝 L1 保留名。** 以下六个名字无论如何都不会给子智能体：

| 保留名                                        | 为什么保留                         |
| ------------------------------------------ | ----------------------------- |
| `delegate` / `Delegate`                    | 跨专家委托，只有主智能体能发起               |
| `Task` / `task`                            | 顶层派发器；子智能体不能再生子智能体            |
| `plan_write`                               | 计划是会话级权威，子智能体代写会造成「这是谁的计划」的歧义 |
| `suggest_plan_mode` / `suggest_build_mode` | 模式切换同属会话级权威                   |

这个清单是**写死在代码里的名字集合**，不是查工具注册表得出的。原因很实在：如果靠查注册表，某个 L1 工具还没实现时查不到，守卫就静默失效了。名字在清单里就是保留的，与它是否已实现无关。

**第二遍——展开通配符。** 支持 `*`（全部）和 `mcp__server__*` 这类前缀模式，对主智能体的工具集做匹配。

**第三遍——精确匹配剩余名字，解析不到的直接丢弃。** 运行时**不会凭空造工具**。你写了一个不存在的工具名，它会被静默丢掉（记录在构建报告里），不会报错。

通配符也过一遍保留名检查——你写 `"tools": ["*"]` 拿不到 `delegate`，第二道防线会把它拦下。

### 会被丢弃的规格

以下情形下你的子智能体**不会出现在运行时**，而且不报错：

| 情形                                                 | 判定        |
| -------------------------------------------------- | --------- |
| 不是对象                                               | 丢弃        |
| `name` / `description` / `system_prompt` 任一为空或非字符串 | 丢弃        |
| `name` 含空白字符或 `"` `<` `>` `&` `'`                  | 丢弃        |
| `name` 撞上 L1 保留名                                   | 丢弃        |
| `tools` 存在但不是数组                                    | 丢弃        |
| **白名单解析后一个工具都不剩**                                  | 丢弃        |
| 与前面某个子智能体重名                                        | 丢弃（先声明者胜） |

最后两条最容易踩：

* **零工具会被丢**，设计上的理由是「没有工具的子智能体就是个纯推理者，和通用子智能体重复」。所以你想要一个纯思考型子智能体，得至少给它一个能解析到的工具。
* **重名先到先得**，且平台内置子智能体排在你的前面。你的子智能体如果和内置的重名，你的那个会被丢掉。

<Warning>
  这些丢弃都是静默的——发布不会失败，只是运行时那个子智能体不存在。症状是「主智能体从来不派活给它」。排查时先确认 `tools` 里至少有一个名字能在主智能体工具集里解析到。
</Warning>

***

## 跨专家委托

委托由三个配置和一层访问控制共同决定。

### `delegatable`（布尔，默认 true）

你的专家**能不能被别的专家委托**。默认开启。

它被校验两次：一次在构建名册时（不可委托的专家不进名册），一次在真正发起委托请求时（纵深防御）。第二次拦下时返回：

```
Expert is not delegatable
```

<Note>
  注意返回的 HTTP 状态是 200，业务结果在 body 里的 `status: "failed"` + `error` 字段。委托失败被建模成「任务结果」而非「请求错误」，因为发起方是模型不是人。
</Note>

### `delegationBrief`（文本，可空）

给**其他专家的模型**看的能力简介。它决定别的专家在什么情况下会想到来找你。

回落规则写在 SQL 里：

```sql theme={null}
coalesce(delegation_brief, description, '')
```

不填就用 `description` 顶上。但两者受众不同：

* `description` 写给**人**看——出现在市场卡片上，要有吸引力
* `delegationBrief` 写给**模型**看——要说清「什么输入交给我、我产出什么」

一个对比：

```
description（给人看）
  三十年老会计，帮你把乱账理清楚，报税不再头疼。

delegationBrief（给模型看）
  处理中国大陆小微企业的记账与税务问题。
  接受：银行流水、发票扫描件、往期账套、具体税务政策问题。
  产出：分类账目表、税务风险点清单、申报表填写建议。
  不接受：审计意见、跨境税务、上市公司合规。
```

后者显著提高被正确委托的概率，也减少了被错误委托后浪费的调用。

### 名册注入策略

主专家能看到哪些专家，由用户侧的委托策略决定：

| 策略      | 注入的名册                |
| ------- | -------------------- |
| `none`  | 空                    |
| `all`   | 用户有权访问的全部可委托专家       |
| 白名单（非空） | 白名单内全部注入，上限 **10** 个 |

不管哪种策略，用户在消息里 `@` 提到的专家都会**额外合并进名册**，走同一套安全条件。

### 安全条件（四条，全部必须满足）

任何专家要进入名册，必须同时满足：

```ts theme={null}
eq(expertAccess.userId, userId),      // 用户对它有访问权（买过或自己创建）
eq(expert.delegatable, true),         // 创作者允许被委托
eq(expert.status, EXPERT_STATUS.PUBLISHED),  // 已上架
isNull(expert.deletedAt),             // 未删除
```

外加一条：**排除当前专家自己**，不允许自我委托。

第一条是关键——委托不会给用户带来越权。用户没买过的专家，别的专家也委托不到。

***

## 两者的边界

子智能体拿不到 `delegate` 工具，这条边界在两个地方各拦一次：规格里显式写 `delegate` 被第一遍拒绝，写 `*` 通配则被第二遍拦下。

设计意图是**权限不能通过嵌套逃逸**。如果子智能体能委托，那么「用户授权专家 A 使用」就会传递成「A 的子智能体也能调用 B」，授权边界变得不可推理。

***

## 边界与失败态

<AccordionGroup>
  <Accordion title="配了子智能体但主智能体从不用">
    按顺序查三点：① 规格是否被丢弃（最常见是 `tools` 全部解析不到，导致零工具丢弃）；② `description` 是否说清了适用场景——主智能体靠它决定派不派活，写得含糊就不会被选中；③ 是否与内置子智能体重名被先到先得挤掉。
  </Accordion>

  <Accordion title="子智能体报「工具不可用」">
    白名单里的工具必须存在于**主智能体的工具集**里。你不能给子智能体主智能体自己都没有的工具——解析是对父工具集做交集。先确认对应插件在这个专家上是启用的。
  </Accordion>

  <Accordion title="别的专家委托我时返回 Expert is not delegatable">
    你的 `delegatable` 被关掉了。到 Studio 打开即可。注意 HTTP 状态是 200，错误在响应体里，不要按 4xx 去排查。
  </Accordion>

  <Accordion title="委托请求返回 Expert not found or access denied">
    发起委托的**用户**对目标专家没有访问权。委托不提权——用户得先购买目标专家。
  </Accordion>

  <Accordion title="白名单配了 15 个但只生效 10 个">
    上限就是 10（`DELEGATION_WHITELIST_MAX`）。超出部分被丢弃并记日志。
  </Accordion>
</AccordionGroup>

***

## 验证

**验子智能体**：给一个明确应该由某个子智能体处理的任务，在对话的执行轨迹里看是否出现了对应的子任务调用。没出现就是被丢弃了或 `description` 不够明确。

**验委托**：用一个**同时拥有两个专家**的账号，在专家 A 里提出一个明显属于专家 B 领域的问题，看 A 是否发起委托。若要精确测试，直接在消息里 `@` 提及专家 B——`@` 提及会绕过策略强制合并进名册，可以把「策略问题」和「简介写得不好」这两个原因区分开。

***

## 真值来源

<Note>
  核对日期 2026-08-11。来源：

  * 三遍解析、L1 保留名清单、丢弃规则：`services/agent-runtime/src/harness/subagent/builder.py`
  * 名册安全条件、`coalesce` 回落、白名单上限 10：`services/core/src/db/service/delegation.ts`、`packages/db/src/schema/config.ts`
  * 委托请求校验与错误响应形态：`services/core/src/routes/agent-proxy/delegate.ts`
  * 字段类型定义：`packages/db/src/schema/marketplace.ts`
</Note>

***

## 下一步

<CardGroup cols={2}>
  <Card title="Prompt 四层结构" icon="layer-group" href="/zh/creators/expert-config/prompt-layers">
    四个输入框各自的注入位置
  </Card>

  <Card title="案例演示与工作区" icon="folder-open" href="/zh/creators/expert-config/workspace-and-demos">
    案例演示配置与工作区种子现状
  </Card>
</CardGroup>