第4课：Subagent —— 拆解大任务，上下文隔离

第1轮: bash → cat package.json          (输出: 200行JSON)
第2轮: bash → cat jest.config.js        (输出: 30行配置)
第3轮: bash → cat tsconfig.json         (输出: 50行JSON)
第4轮: bash → ls tests/                 (输出: 15行文件列表)
第5轮: bash → head -20 tests/setup.ts   (输出: 20行代码)

┌────────────────────────────────────────────────────────┐
│  父 Agent (messages[])                                 │
│                                                        │
│  User: "重构这个模块，先弄清楚测试框架"               │
│  Assistant: 我先调查测试框架 → tool_use: task          │
│                                                        │
│  ┌──────────────────────────────────────────────────┐  │
│  │  子 Agent (sub_messages[] — 独立，用完即弃)      │  │
│  │                                                  │  │
│  │  User: "这个项目用什么测试框架？"                │  │
│  │  Assistant: → bash cat package.json  (200行)     │  │
│  │  Assistant: → bash cat jest.config.js (30行)     │  │
│  │  Assistant: → bash ls tests/         (15行)      │  │
│  │  Assistant: "项目使用 Jest 测试框架，配置..."    │  │
│  │                                                  │  │
│  │  ★ 整个 sub_messages[] 在这里丢弃               │  │
│  └──────────────────────────────────────────────────┘  │
│                                                        │
│  tool_result: "项目使用 Jest 测试框架，配置在..."     │
│  Assistant: 好的，现在开始重构... (继续干净地工作)     │
│                                                        │
└────────────────────────────────────────────────────────┘

TASK_TOOL = {
    "name": "task",
    "description": (
        "Run a subtask in an isolated context. "
        "Use this for research, analysis, or any work whose "
        "intermediate output the parent does not need to see. "
        "Returns only the final text summary."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "prompt": {
                "type": "string",
                "description": "The task description for the subagent",
            }
        },
        "required": ["prompt"],
    },
}

def run_subagent(prompt: str) -> str:
    """在隔离上下文中执行子任务，仅返回最终文本。"""
    sub_messages = [{"role": "user", "content": prompt}]
    
    # 子 Agent 可用的工具：除了 task 之外的所有工具
    sub_tools = [t for t in ALL_TOOLS if t["name"] != "task"]
    
    for turn in range(MAX_SUBAGENT_TURNS):  # 硬上限，防止失控
        response = client.messages.create(
            model=MODEL,
            system=SUBAGENT_SYSTEM,
            messages=sub_messages,
            tools=sub_tools,
            max_tokens=8000,
        )
        sub_messages.append({
            "role": "assistant", 
            "content": response.content,
        })
        
        # 子 Agent 决定不再调工具 → 任务完成
        if response.stop_reason != "tool_use":
            break
        
        # 执行工具，收集结果
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        sub_messages.append({"role": "user", "content": results})
    
    # ★ 关键：只提取最终文本，sub_messages 整个丢弃
    return extract_text(response)

def extract_text(response) -> str:
    """从响应中提取纯文本，丢弃工具调用块。"""
    parts = []
    for block in response.content:
        if hasattr(block, "text"):
            parts.append(block.text)
    return "\n".join(parts) if parts else "(subagent produced no text output)"

# 工具列表：在原有工具基础上加入 task
PARENT_TOOLS = BASE_TOOLS + [TASK_TOOL]

# dispatch map：加入 task → run_subagent 映射
TOOL_HANDLERS = {
    "bash":  run_bash,
    "read":  read_file,
    "write": write_file,
    "edit":  edit_file,
    "todo":  todo_write,
    "task":  lambda prompt: run_subagent(prompt),  # 新增
}

父 Agent:
  思考: 这个任务有两步——先调研技术栈，再写文档。
        调研部分会产生大量中间输出，用 task 隔离。

  tool_use: task(prompt="分析这个项目的技术栈，
            包括语言、框架、测试工具、构建工具")

    ┌─ 子 Agent (独立上下文) ─────────────────────┐
    │ bash → cat package.json         (200行)     │
    │ bash → cat tsconfig.json        (50行)      │
    │ bash → ls src/                  (20行)      │
    │ bash → cat vite.config.ts       (30行)      │
    │ bash → cat jest.config.js       (25行)      │
    │ bash → cat Dockerfile           (15行)      │
    │                                              │
    │ 最终回复: "技术栈分析：                      │
    │   - 语言: TypeScript 5.3                     │
    │   - 前端: React 18 + Vite 5                  │
    │   - 测试: Jest + Testing Library             │
    │   - 构建: Docker + GitHub Actions            │
    │   - 包管理: pnpm"                            │
    │                                              │
    │ ★ 340行中间输出在此丢弃                      │
    └──────────────────────────────────────────────┘

  tool_result: "技术栈分析：语言 TypeScript 5.3..."
                (只有5行摘要进入父上下文)

  思考: 拿到技术栈信息了，现在编辑 README。
  tool_use: read(path="README.md")
  tool_use: edit(path="README.md", ...)

  最终回复: "已在 README.md 中补充了技术栈说明。"

✅ 正确: 父 → [子A, 子B, 子C]      (宽度扩展)
❌ 错误: 父 → 子 → 孙 → 曾孙        (深度递归)

SUBAGENT_SYSTEM = """You are a focused research and analysis agent.

Your job is to complete the specific task given to you, then provide
a clear, concise summary of your findings.

Guidelines:
- Stay focused on the given task
- Be thorough but efficient
- End with a clear summary of findings
- Do not ask for clarification — work with what you have
"""

MAX_SUBAGENT_TURNS = 30

# 进入项目目录
cd learn-claude-code

# 启动第四课
python agents/s04_subagent.py

s04 >> Use a subtask to find what testing framework this project uses
> task (Find the testing framework used in this project):
  (子 Agent 独立执行：读取 package.json、requirements.txt、
   tests/ 目录、多个测试文件……全部在隔离上下文中完成)

  子 Agent 返回摘要 ↓

## Results
The project uses **two Python testing frameworks**:

| Framework | Version | Role |
|-----------|---------|------|
| **pytest** | 9.0.2 | Primary — used across tests/ and mypackage/tests/ |
| **unittest** | stdlib | Secondary — used in one file with TestCase style |

Notably, the web/ subdirectory has **no JavaScript testing
framework** configured.

s04 >> Delegate: read all .py files and summarize what each one does
> bash: (列出所有 25 个 .py 文件)

> task (Summarize top-level .py files): ...
> task (Summarize mypackage .py files): ...
> task (Summarize agents s01-s06 .py files): ...
> task (Summarize agents s07-s12 and s_full .py files): ...
> task (Summarize tests and skills .py files): ...

Here's a complete summary of all 25 `.py` files:

## 📁 Top-Level
| File | Summary |
|------|---------|
| hello.py | greet(name) function returning "Hello, {name}!" |
| greet.py | Minimal module with a single greet(name) function |

## 📁 agents/ — Progressive Agent Harness (s01–s12)
| File | Summary |
|------|---------|
| s01_agent_loop.py | The Agent Loop — minimal core |
| s02_tool_use.py | Tool Dispatch — dispatch map |
| s03_todo_write.py | TodoWrite — planning system |
| s04_subagent.py | Subagents — context isolation |
| ... | (后续 8 个 agent 文件的完整摘要) |

s04 >> Use a task to create a new module, then verify it from here
> task (Create a new JavaScript utility module):
  (子 Agent 独立创建 src/utils/stringUtils.js，
   包含 capitalize、reverseString、isPalindrome、truncate 四个函数)

  子 Agent 返回摘要 ↓

> bash: cat src/utils/stringUtils.js
  (父 Agent 自己读取文件验证内容)
> bash: node -e "..." (逐个测试每个函数)

✅ Module created and verified successfully!

| Function | Test Input | Expected | Actual | Status |
|---|---|---|---|---|
| capitalize | 'hello' | 'Hello' | 'Hello' | ✅ |
| reverseString | 'hello' | 'olleh' | 'olleh' | ✅ |
| isPalindrome | 'racecar' | true | true | ✅ |
| truncate | 'Hello, World!', 5 | 'Hello...' | 'Hello...' | ✅ |

# 预告：s05 的技能加载
def load_skill(skill_name: str) -> str:
    skill_path = f"skills/{skill_name}.md"
    return read_file(skill_path)

# 技能内容注入系统提示词
system = BASE_SYSTEM + "\n\n" + load_skill("python-testing")