8.4 子代理的进阶配置

面向经管学生、研究者与从业者的 AI 智能体设计教材

作者

李学恒、林建浩、严翊歆

发布于

2026-05-11

基础的 name、description、tools、model 四个字段已经能覆盖大部分场景。当子代理需要调用特定 Skill、连接外部数据源、积累跨会话知识，或者在后台并行运行时，就需要用到进阶配置字段。

以下是六个进阶字段的功能概览：

字段	用途	典型场景
`skills`	预加载 Skill 到子代理上下文	子代理需遵循特定模板或流程
`mcpServers`	配置专属 MCP 服务器	子代理需访问特定数据源
`memory`	跨会话持久记忆	子代理需积累领域知识
`hooks`	子代理内部自动化约束	子代理执行前需验证操作
`isolation`	Git Worktree 隔离	多子代理并行修改同一仓库
`background`	后台运行	不阻塞主对话

Skills 预加载

子代理不继承主对话中已匹配的 Skills。如果子代理需要遵循某个 Skill 的指令，必须在 frontmatter 的 skills 字段中显式列出。列出后，Skill 的完整内容会在子代理启动时注入其上下文。

▶ Agent

---
name: report-writer
description: 撰写行业研报初稿，遵循团队研报模板和文献引用规范
model: opus
tools: Read, Write, Edit, Grep, Glob, Bash
skills:
  - report-template
  - paper-lookup
---

你是研报撰写子代理。按照预加载的研报模板组织内容结构，
使用 /paper-lookup 检索和引用学术文献。
将初稿保存到 output/ 目录，只返回状态摘要。

Skills 预加载 vs Skill 的 context: fork

两者底层机制相同，区别在于控制权。skills 字段由子代理的 agent.md 控制，子代理定义自己需要哪些 Skill；context: fork 由 Skill 的 SKILL.md 控制，Skill 定义自己应该运行在哪个子代理中。根据管理偏好选择其中一种，避免两边重复配置。

MCP 服务器作用域

mcpServers 字段为子代理配置专属的 MCP 服务器。支持内联定义和按名称引用两种方式。

▶ Agent

---
name: data-analyst
description: 查询金融数据库并生成分析报告
model: sonnet
tools: Read, Write, Bash
mcpServers:
  - financial-db:
      type: stdio
      command: npx
      args: ["-y", "@example/financial-db-mcp"]
  - tavily
---

查询金融数据库获取所需数据，使用 tavily 搜索补充公开信息。
将分析结果保存到指定文件。

内联定义的服务器在子代理启动时连接、结束时断开，主对话感知不到它的存在。把工具描述排除在主对话上下文之外是 MCP 作用域最重要的用途——一个 MCP 服务器可能注册十几个工具，每个工具的描述都会占用上下文窗口。

持久记忆

默认情况下，子代理的知识随会话结束而消失。memory 字段让子代理拥有跨会话的持久目录。三种作用域：

作用域	存储位置	适用场景
`user`	`~/.claude/agent-memory/<name>/`	跨项目通用的知识
`project`	`.claude/agent-memory/<name>/`	项目内共享，可纳入版本控制
`local`	`.claude/agent-memory-local/<name>/`	项目内私有，不应提交到仓库

启用后，子代理的行为会发生三个变化：系统提示中自动注入记忆目录下 MEMORY.md 的前 200 行；Read、Write、Edit 工具自动启用；当 MEMORY.md 超过 200 行时，子代理会收到整理提示。

随着使用次数增加，子代理会逐步积累对特定领域的认知。这些知识在无状态子代理中每次都需要从头建立。

记忆管理

官方推荐以 project 为默认作用域。记忆目录不会自动清理，建议在子代理的系统提示中加入整理指令。project 作用域的记忆会被提交到版本控制，注意不要在其中写入敏感信息。

Hooks 集成

子代理可以在两个层面集成 Hooks。

agent.md 内部定义：这些 Hooks 只在该子代理运行期间生效，支持 PreToolUse、PostToolUse 和 Stop 三种事件。

▶ Agent

---
name: db-reader
description: 执行只读数据库查询
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

执行 SQL 查询获取数据。所有查询会在执行前经过只读验证。

settings.json 中定义 SubagentStart 和 SubagentStop 事件：在主会话层面运行，用于在子代理启动或结束时执行准备和清理工作。两种方式可以组合使用。

Worktree 隔离与后台运行

当多个子代理需要同时修改同一个仓库的文件时，isolation: worktree 让子代理在临时的 git worktree 中运行，获得仓库的隔离副本。子代理结束后，如果有文件修改则保留 worktree 供主代理决定如何合并，无修改则自动清理。

子代理默认在前台运行，阻塞主对话直到完成。设置 background: true 后，子代理在后台运行，主对话可以继续处理其他事务。

后台运行的权限机制

后台子代理无法中断你的工作来提问权限，所以 Claude Code 会在启动前一次性询问所有可能需要的权限。启动后，已批准的自动通过，未批准的自动拒绝。运行中的前台子代理也可以按 Ctrl+B 随时切换到后台。

--- title: "8.4 子代理的进阶配置" --- ![8.4 配图](images/img_04_advanced_config.png) 基础的 `name`、`description`、`tools`、`model` 四个字段已经能覆盖大部分场景。当子代理需要调用特定 Skill、连接外部数据源、积累跨会话知识，或者在后台并行运行时，就需要用到进阶配置字段。以下是六个进阶字段的功能概览： | 字段 | 用途 | 典型场景 | |:---|:---|:---| | `skills` | 预加载 Skill 到子代理上下文 | 子代理需遵循特定模板或流程 | | `mcpServers` | 配置专属 MCP 服务器 | 子代理需访问特定数据源 | | `memory` | 跨会话持久记忆 | 子代理需积累领域知识 | | `hooks` | 子代理内部自动化约束 | 子代理执行前需验证操作 | | `isolation` | Git Worktree 隔离 | 多子代理并行修改同一仓库 | | `background` | 后台运行 | 不阻塞主对话 | ### Skills 预加载子代理不继承主对话中已匹配的 Skills。如果子代理需要遵循某个 Skill 的指令，必须在 frontmatter 的 `skills` 字段中显式列出。列出后，Skill 的完整内容会在子代理启动时注入其上下文。 ```agent --- name: report-writer description: 撰写行业研报初稿，遵循团队研报模板和文献引用规范 model: opus tools: Read, Write, Edit, Grep, Glob, Bash skills: - report-template - paper-lookup --- 你是研报撰写子代理。按照预加载的研报模板组织内容结构，使用 /paper-lookup 检索和引用学术文献。将初稿保存到 output/ 目录，只返回状态摘要。 ``` ::: {.callout-tip} ## Skills 预加载 vs Skill 的 context: fork 两者底层机制相同，区别在于控制权。`skills` 字段由子代理的 agent.md 控制，子代理定义自己需要哪些 Skill；`context: fork` 由 Skill 的 SKILL.md 控制，Skill 定义自己应该运行在哪个子代理中。根据管理偏好选择其中一种，避免两边重复配置。 ::: ### MCP 服务器作用域 `mcpServers` 字段为子代理配置专属的 MCP 服务器。支持内联定义和按名称引用两种方式。 ```agent --- name: data-analyst description: 查询金融数据库并生成分析报告 model: sonnet tools: Read, Write, Bash mcpServers: - financial-db: type: stdio command: npx args: ["-y", "@example/financial-db-mcp"] - tavily --- 查询金融数据库获取所需数据，使用 tavily 搜索补充公开信息。将分析结果保存到指定文件。 ``` 内联定义的服务器在子代理启动时连接、结束时断开，主对话感知不到它的存在。**把工具描述排除在主对话上下文之外**是 MCP 作用域最重要的用途——一个 MCP 服务器可能注册十几个工具，每个工具的描述都会占用上下文窗口。 ### 持久记忆默认情况下，子代理的知识随会话结束而消失。`memory` 字段让子代理拥有跨会话的持久目录。三种作用域： | 作用域 | 存储位置 | 适用场景 | |:---|:---|:---| | `user` | `~/.claude/agent-memory/<name>/` | 跨项目通用的知识 | | `project` | `.claude/agent-memory/<name>/` | 项目内共享，可纳入版本控制 | | `local` | `.claude/agent-memory-local/<name>/` | 项目内私有，不应提交到仓库 | 启用后，子代理的行为会发生三个变化：系统提示中自动注入记忆目录下 `MEMORY.md` 的前 200 行；Read、Write、Edit 工具自动启用；当 `MEMORY.md` 超过 200 行时，子代理会收到整理提示。随着使用次数增加，子代理会逐步积累对特定领域的认知。这些知识在无状态子代理中每次都需要从头建立。 ::: {.callout-warning} ## 记忆管理官方推荐以 `project` 为默认作用域。记忆目录不会自动清理，建议在子代理的系统提示中加入整理指令。`project` 作用域的记忆会被提交到版本控制，注意不要在其中写入敏感信息。 ::: ### Hooks 集成子代理可以在两个层面集成 Hooks。 **agent.md 内部定义**：这些 Hooks 只在该子代理运行期间生效，支持 `PreToolUse`、`PostToolUse` 和 `Stop` 三种事件。 ```agent --- name: db-reader description: 执行只读数据库查询 tools: Bash hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-readonly-query.sh" --- 执行 SQL 查询获取数据。所有查询会在执行前经过只读验证。 ``` **settings.json 中定义 `SubagentStart` 和 `SubagentStop` 事件**：在主会话层面运行，用于在子代理启动或结束时执行准备和清理工作。两种方式可以组合使用。 ### Worktree 隔离与后台运行当多个子代理需要同时修改同一个仓库的文件时，`isolation: worktree` 让子代理在临时的 git worktree 中运行，获得仓库的隔离副本。子代理结束后，如果有文件修改则保留 worktree 供主代理决定如何合并，无修改则自动清理。子代理默认在前台运行，阻塞主对话直到完成。设置 `background: true` 后，子代理在后台运行，主对话可以继续处理其他事务。 ::: {.callout-note} ## 后台运行的权限机制后台子代理无法中断你的工作来提问权限，所以 Claude Code 会在启动前一次性询问所有可能需要的权限。启动后，已批准的自动通过，未批准的自动拒绝。运行中的前台子代理也可以按 **Ctrl+B** 随时切换到后台。 :::