analysis_claude_code/docs/v3-子代理机制.md

# v3: 子代理机制

**~450 行代码，+1 个工具，分而治之。**

v2 添加了规划。但对于大型任务如"探索代码库然后重构认证"，单一 Agent 会撞上上下文限制。探索过程把 20 个文件倒进历史记录，重构时失去焦点。

v3 添加了 **Task 工具**：生成带有隔离上下文的子代理。

## 问题

单 Agent 的上下文污染：

```
主 Agent 历史：
  [探索中...] cat file1.py -> 500 行
  [探索中...] cat file2.py -> 300 行
  ... 15 个文件 ...
  [现在重构...] "等等，file1 里有什么来着？"
```

解决方案：**把探索委托给子代理**：

```
主 Agent 历史：
  [Task: 探索代码库]
    -> 子代理探索 20 个文件
    -> 返回: "认证在 src/auth/，数据库在 src/models/"
  [现在用干净的上下文重构]
```

## 代理类型注册表

每种代理类型定义其能力：

```python
AGENT_TYPES = {
    "explore": {
        "description": "只读，用于搜索和分析",
        "tools": ["bash", "read_file"],  # 不能写
        "prompt": "搜索和分析。不要修改。返回简洁摘要。"
    },
    "code": {
        "description": "完整代理，用于实现",
        "tools": "*",  # 所有工具
        "prompt": "高效实现更改。"
    },
    "plan": {
        "description": "规划和分析",
        "tools": ["bash", "read_file"],  # 只读
        "prompt": "分析并输出编号计划。不要改文件。"
    }
}
```

## Task 工具

```python
{
    "name": "Task",
    "description": "为聚焦的子任务生成子代理",
    "input_schema": {
        "description": "短任务名（3-5 词）",
        "prompt": "详细指令",
        "agent_type": "explore | code | plan"
    }
}
```

主代理调用 Task → 子代理运行 → 返回摘要。

## 子代理执行

Task 工具的核心：

```python
def run_task(description, prompt, agent_type):
    config = AGENT_TYPES[agent_type]

    # 1. 代理特定的系统提示词
    sub_system = f"You are a {agent_type} subagent.\n{config['prompt']}"

    # 2. 过滤后的工具
    sub_tools = get_tools_for_agent(agent_type)

    # 3. 隔离的历史（关键：没有父上下文）
    sub_messages = [{"role": "user", "content": prompt}]

    # 4. 同样的查询循环
    while True:
        response = client.messages.create(
            model=MODEL, system=sub_system,
            messages=sub_messages, tools=sub_tools
        )
        if response.stop_reason != "tool_use":
            break
        # 执行工具，追加结果...

    # 5. 只返回最终文本
    return extract_final_text(response)
```

**关键概念：**

| 概念 | 实现 |
|------|------|
| 上下文隔离 | 全新的 `sub_messages = []` |
| 工具过滤 | `get_tools_for_agent()` |
| 专门化行为 | 代理特定的系统提示词 |
| 结果抽象 | 只返回最终文本 |

## 工具过滤

```python
def get_tools_for_agent(agent_type):
    allowed = AGENT_TYPES[agent_type]["tools"]
    if allowed == "*":
        return BASE_TOOLS  # 不给 Task（演示中不递归）
    return [t for t in BASE_TOOLS if t["name"] in allowed]
```

- `explore`：只有 bash + read_file
- `code`：所有工具
- `plan`：只有 bash + read_file

子代理不获得 Task 工具（防止无限递归）。

## 进度显示

子代理输出不污染主聊天：

```
你: 探索代码库
> Task: 探索代码库
  [explore] 探索代码库 ... 5 个工具, 3.2s
  [explore] 探索代码库 - 完成 (8 个工具, 5.1s)

这是我发现的: ...
```

实时进度，干净的最终输出。

## 典型流程

```
用户: "把认证重构为 JWT"

主 Agent:
  1. Task(explore): "找到所有认证相关文件"
     -> 子代理读取 10 个文件
     -> 返回: "认证在 src/auth/login.py，session 在..."

  2. Task(plan): "设计 JWT 迁移方案"
     -> 子代理分析结构
     -> 返回: "1. 添加 jwt 库 2. 创建 token 工具..."

  3. Task(code): "实现 JWT tokens"
     -> 子代理写代码
     -> 返回: "创建了 jwt_utils.py，更新了 login.py"

  4. 总结更改
```

每个子代理有干净的上下文。主代理保持聚焦。

## 对比

| 方面 | v2 | v3 |
|------|----|----|
| 上下文 | 单一，增长中 | 每任务隔离 |
| 探索 | 污染历史 | 包含在子代理中 |
| 并行 | 否 | 可能（演示中没有） |
| 新增代码 | ~300 行 | ~450 行 |

## 模式

```
复杂任务
  └─ 主 Agent（协调者）
       ├─ 子代理 A (explore) -> 摘要
       ├─ 子代理 B (plan) -> 计划
       └─ 子代理 C (code) -> 结果
```

同样的 Agent 循环，不同的上下文。这就是全部技巧。

---

**分而治之。上下文隔离。**

[← v2](./v2-结构化规划.md) | [返回 README](../README_zh.md) | [v0 →](./v0-Bash就是一切.md)