SubAgent子智能体模式
一、基本概念
spawn_subagent 用于在当前工作空间内生成一个临时的子代理（Subagent）。子代理与当前代理共享相同的 Agent 身份（相同的配置、人格设定和工具集），但在一个独立的会话（Session）中运行。
二、核心设计特点
| 特性 | 说明 |
|---|---|
| 临时性（Ephemeral） | 子代理是一次性运行的，任务完成后会话即被丢弃，无法恢复 |
| 同构性 | 与 chat_with_agent 不同，spawn_subagent 调用的是同一个 Agent，而非另一个专业 Agent |
| 工作空间隔离 | 通过 Git Worktree 实现文件级隔离，避免污染主工作区 |
| 会话继承 | 通过 fork=True 可继承父会话的完整对话上下文 |
三、参数与模式
spawn_subagent(
task: str, # 子任务描述
fork: bool = False, # 是否继承父会话状态
background: bool = False, # 是否后台执行
timeout: int = 600, # 前台等待超时（秒）
)
四、两种运行模式对比
1. fork=False（默认模式）—— 干净独立的子任务
- 子代理以全新空会话启动，不继承任何对话历史
- 适合读取/修改当前项目文件、执行自包含的子任务
- 典型场景：扫描代码库、运行测试套件、分析性能瓶颈
spawn_subagent(task="Scan the codebase for security vulnerabilities")
2. fork=True —— 上下文感知的分支任务
- 子代理继承父会话的完整对话上下文
- 如果项目目录是 Git 仓库，会自动创建独立的 Git Worktree 实现文件隔离
- 适合需要基于当前讨论内容继续工作的场景
Fork 模式的底层流程：
调用 /api/fork/agent（localhost-only 内部 API）
│
├─ 1. 读取父会话状态文件（SafeJSONSession 格式）
├─ 2. 生成 fork session ID（如 sub-ab12ef34）
├─ 3. 写入 fork 会话状态（继承父会话上下文）
└─ 4. 若项目是 git 仓库 → 创建 Git Worktree
工作树路径: <project>/.qwenpaw/worktrees/<fork_id>/
五、两种执行方式
| 执行方式 | 行为 | 返回值 |
|---|---|---|
| 前台（默认） | 阻塞等待子代理完成 |
[SESSION: sub-ab12] + 结果文本 |
| 后台 | 立即返回，子代理在后台运行 |
[TASK_ID: task-cd34] + [SESSION: sub-ef56]
|
后台模式可通过 check_agent_task(task_id="xxx") 轮询进度。
六、与 chat_with_agent 的本质区别
| 维度 | spawn_subagent |
chat_with_agent |
|---|---|---|
| Agent 身份 | 同一个 Agent（相同配置、人格、工具） | 不同的 Agent（独立配置和工具） |
| 工作空间 | 当前工作空间 | 目标 Agent 自己的工作空间 |
| 历史继承 | 可选（fork 参数） | 无（仅文本输入） |
| 典型用途 | 分解当前 Agent 的子任务 | 调用专业 Agent（如 QA、Code Review） |
七、典型应用场景
- 复杂任务分解：主 Agent 负责规划和协调，子 Agent 负责执行具体子任务
- 后台长时任务：如扫描整个代码库、生成文档等耗时操作不阻塞主对话
-
文件修改隔离：
fork=True配合 Git Worktree，子 Agent 的文件修改不会直接影响主工作区，可安全审查后再合并 -
Skill 创建流程：在
make-skill技能中，Phase A 用户审批后，Phase B 通过spawn_subagent(fork=True, background=True)后台执行具体的 Skill 创建和验证工作
八、Fork 模式的文件隔离机制
当 fork=True 且项目为 Git 仓库时，系统会：
原始工作区: /project/
│
子代理工作区: /project/.qwenpaw/worktrees/fork-ab12ef34/
│ └── 基于独立 Git 分支（如 fork/ab12ef34）
│ └── 子代理在此修改文件，完全隔离
子代理完成后，若无文件变更，Worktree 自动清理；若有变更，返回 [FORK_BRANCH: fork/ab12ef34] 提示人工审查合并。
