mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 21:05:51 +00:00
cf05a3b28b
移除 TypeScript 代码和源码路径， 聚焦三种子 Agent 路径的设计权衡、Fork 缓存优化、 工具池隔离的权限独立性和异步生命周期的后台化机制。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
111 lines
4.9 KiB
Plaintext
111 lines
4.9 KiB
Plaintext
---
|
||
title: "子 Agent"
|
||
description: "主 Agent 可以启动子 Agent 来并行工作或委派专业任务。理解三种子 Agent 路径、工具池隔离、Fork 的缓存优化和异步生命周期管理。"
|
||
keywords: ["子 Agent", "AgentTool", "任务委派", "子进程隔离"]
|
||
---
|
||
|
||
## 核心问题
|
||
|
||
单个 Agent 的上下文窗口是有限的。当需要同时研究多个方向、并行执行多个操作时，一个 Agent 做不过来。
|
||
|
||
子 Agent 让主 Agent 可以启动独立的 AI 实例来并行工作——每个子 Agent 有自己的上下文窗口和工具集。
|
||
|
||
## 三种子 Agent 路径
|
||
|
||
系统根据参数和配置走三条不同的路径：
|
||
|
||
| 路径 | 触发条件 | 上下文 | 设计目的 |
|
||
|------|---------|--------|---------|
|
||
| **命名 Agent** | 指定 `subagent_type` | 仅任务描述 | 专业任务委派 |
|
||
| **Fork 子进程** | 启用 Fork + 未指定类型 | 继承父 Agent 完整对话 | Prompt Cache 优化 |
|
||
| **通用回退** | 未启用 Fork + 未指定类型 | 仅任务描述 | 通用任务处理 |
|
||
|
||
### 命名 Agent：专业委派
|
||
|
||
系统预定义了几个内置 Agent，各有明确的职责：
|
||
|
||
| Agent | 模型 | 工具 | 用途 |
|
||
|-------|------|------|------|
|
||
| **Explore** | Haiku（轻量快速） | 只读（Read/Grep/Glob） | 代码库搜索与探索 |
|
||
| **Plan** | 继承父模型 | 只读 | 为 Plan Mode 收集信息 |
|
||
| **General-purpose** | 继承父模型 | 全部工具 | 复杂通用任务 |
|
||
|
||
**设计考量**：Explore Agent 使用 Haiku 模型（更便宜、更快），因为搜索任务不需要 Opus 的推理能力。模型选择是成本和能力的权衡——不是每个子任务都需要最强的模型。
|
||
|
||
### Fork 子进程：缓存优化
|
||
|
||
Fork 路径的核心设计是 **Prompt Cache 共享**：所有 fork 子进程共享父 Agent 的完整对话历史，只有最后的指令不同。这使得 API 请求的前缀完全一致，最大化缓存命中。
|
||
|
||
**为什么不用命名 Agent**？命名 Agent 只拿到任务描述，缺乏父 Agent 的完整上下文。Fork 让子进程"看到"父 Agent 看到的一切，代价是更高的 token 消耗——但通过 Prompt Cache，这部分消耗被大幅降低。
|
||
|
||
Fork 有两道防线防止递归创建子 Agent：检查查询来源标记和扫描消息中的特殊标签。
|
||
|
||
### 模型解析优先级
|
||
|
||
子 Agent 的模型选择遵循优先级链：
|
||
|
||
```
|
||
环境变量覆盖 > 每次调用参数 > Agent 定义的模型 > 继承父对话模型
|
||
```
|
||
|
||
`inherit` 不是简单的模型传递——它经过运行时解析，确保 plan mode 下的模型映射正确生效。
|
||
|
||
## 工具池隔离
|
||
|
||
子 Agent 不继承父 Agent 的工具限制——它的工具池完全独立组装。
|
||
|
||
**设计考量**：父 Agent 可能处于受限模式（如 Plan Mode），但子 Agent 可能需要完整的工具集来执行任务。独立的工具池让子 Agent 的权限不受父 Agent 限制。
|
||
|
||
Fork 子进程例外——它直接继承父 Agent 的工具池，以保持 Prompt Cache 中工具定义的字节一致性。
|
||
|
||
### Agent 级 MCP 服务器
|
||
|
||
子 Agent 可以额外连接专属的 MCP 服务器。如果 Agent 声明了 `requiredMcpServers`，系统会等待这些服务器连接完成（最长 30 秒），确保工具可用后才启动。
|
||
|
||
## Worktree 隔离
|
||
|
||
`isolation: "worktree"` 参数让子 Agent 在独立的 git worktree 中工作：
|
||
|
||
```
|
||
创建 worktree → 子 Agent 在独立副本中工作 → 完成
|
||
→ 有变更：保留 worktree，返回路径
|
||
→ 无变更：自动删除
|
||
```
|
||
|
||
**设计目的**：子 Agent 的实验性修改不应该影响主分支。Worktree 提供了文件系统级别的隔离，同时保持对完整代码库的访问。
|
||
|
||
## 生命周期：同步 vs 异步
|
||
|
||
### 异步 Agent（后台运行）
|
||
|
||
异步 Agent 立即返回 `async_launched` 状态，主 Agent 可以继续工作。后台 Agent 完成后通过通知机制汇报结果。
|
||
|
||
异步 Agent 获得独立的 AbortController——用户取消主线程不会杀掉后台 Agent。这确保长时间运行的构建/测试任务不会被意外中断。
|
||
|
||
### 同步 Agent（前台运行）
|
||
|
||
同步 Agent 有一个"可后台化"机制：如果执行超过阈值（默认 120 秒），系统自动将其转为后台运行。这防止了一个慢子 Agent 阻塞整个工作循环。
|
||
|
||
## 适用场景
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="并行研究" icon="magnifying-glass">
|
||
多个 fork 子进程并行搜索不同方向，共享 Prompt Cache 前缀
|
||
</Card>
|
||
<Card title="专业委派" icon="code-branch">
|
||
使用命名 Agent 执行专业任务，受限工具集 + 独立权限
|
||
</Card>
|
||
<Card title="隔离实验" icon="flask">
|
||
worktree 隔离中尝试方案，不影响主分支
|
||
</Card>
|
||
<Card title="后台构建" icon="layer-group">
|
||
异步启动长时间构建/测试，主 Agent 继续工作
|
||
</Card>
|
||
</CardGroup>
|
||
|
||
## 接下来
|
||
|
||
- **协调者与蜂群** — 理解多 Agent 的高级编排模式
|
||
- **Worktree 隔离** — 深入理解文件系统隔离机制
|
||
- **任务管理** — 理解支撑多 Agent 的任务追踪
|