subagent

Files (2)

• SKILL.md
• tools.ts

SKILL.md (first lines)

# Subagent Skill（v2）

`spawn_subagent` 派一个独立 agent 干活。子 agent 是一个普通 MaxClaw session：完整 agent loop、全部工具、独立上下文，跑完把最终回复交回来。

这是旧 subagent 子系统（2026-07 裁撤）的极简重建：没有 taskId、没有 OKR/Exit Protocol 模板、没有通知轮询。一次调用一个决定：任务写清楚，别的交给框架。

## 两种模式

**同步（默认）**——像调用一个会自己干活的函数：

```ts
spawn_subagent({
  task: '扫描 ~/proj 的 npm 依赖已知漏洞。产出：漏洞列表（包名/版本/CVE/severity），按 severity 排序。',
  label: '扫依赖漏洞',
})
// → 阻塞至完成，{ response: <子 agent 最终回复> }
```

**后台（`run_in_background: true`）**——长任务派出去就走，完成时框架以 framework 消息唤醒当前 channel，**不要轮询**：

```ts
spawn_subagent({ task: '...', label: '回测网格', run_in_background: true, timeout_ms: 3600000 })
// → 立即返回 { session_id, status: 'running' }
```

## 并行 fan-out

同一回合发多个 spawn_subagent 调用，框架并行执行：

```ts
// 一个回合内三个独立探索并行跑
spawn_subagent({ task: '调查 A...', label: '查A' })
spawn_subagent({ task: '调查 B...', label: '查B' })
spawn_subagent({ task: '调查 C...', label: '查C' })
```

## 参数速查

| 参数 | 必填 | 说明 |
|---|---|---|
| `task` | ✓ | 自包含任务描述。子 agent 看不到你的对话上下文——路径、数据源、期望产出都写进去 |
| `label` | ✓ | 3-8 字短标签 |
| `model` | | `palette:light`（快/便宜）/ `palette:mid` / `palette:frontier`，或精确 provider id。优先级：`model` > `role.model` > 继承父会话 |
| `role` | | 专职 role 名（`roles/<name>.md`）：追加专职 system prompt + 模型倾向。用于审计/领域核查等需独立视角的任务。文件不存在 fail-loud |
| `context` | | 显式有限上下文（string/object）：只传子 agent 所需最小背景。用于"保留主控+按需委托"（如多模态看图只传图路径+评判背景） |
| `run_in_background` | | 默认 false（同步） |
| `timeout_ms` | | 默认同步 15min / 后台 2h，上限 6h |

## 什么时候派 / 不派

**派**：可独立描述的探索、批量处理、数据拉取、计算回测；需要隔离上下文的繁重工作（避免污染主对话上下文）；多个互不依赖的任务（fan-out）。

**不派**：3 步内自己能做完；任务依赖当前对话的隐含上下文（序列化成本 > 执行成本）；需要逐步与用户确认的工作。

## role + context：专职委托与信息预算

`role` 和 `context` 解决两个 native runtime subagent 覆盖不到的场景：

**role（专职 prompt）**--子 agent 获得独立视角。审计场景典型：让审计员 subagent 看不到生成者的设计权衡，只以文件为证据对抗"放行倾向"。role 的 systemPrompt 追加到子 agent baseSystemPrompt（cache 友好的 system 层注入，不混进 user message）。

```ts
spawn_subagent({
  role: 'excel-auditor',
  task: '审计 /path/to/export.xlsx 的格式一致性。逐列检查类型/空值/枚举违例。',
  label: '审计导出表',
})
```

**context（显式有限上下文）**--精确控制子 agent 该看到多少。看图委托场景典型：主 agent（纯文本模型）看不了图，派多模态子 agent 看图，只传图路径 + 评判背景，不把全量对话塞给它。

```ts
spawn_subagent({
  model: 'palette:mid',  // 或任一多模态 provider id
  context: '训练目标：X。当前阶段：Y。期望 loss 单调下降。',
  task: '用 view_image 加载 /path/loss.png，描述现象并评判训练是否正常。',
  label: '看训练曲线',
})
```

role 只提供专职 prompt + 模型倾向，**不绑定工具/backend/编排**--那些是 native runtime 的领地。刻意不重建 2026-07 砍掉的 archetype 体系（worker/advisor/explorer 那种通用角色与 native runtime 重复）。

## 与 native runtime subagent 的分工

claude-agent-sdk / codex runtime 各自带 subagent 能力（SDK 的 Agent/Workflow、codex 的 collab），与 spawn_subagent 并存。按附加能力需求选：

| 需求 | 用 |
|---|---|
| 要 role 独立视角 / context 信息预算 / 结果进 MaxClaw session | `spawn_subagent` |
| 要多 agent 编排 / pipeline / cache-resume / ultracode | SDK `Workflow` |
| 简单一次性委托、不在乎治理 | SDK `Agent` |

不强制屏蔽 native subagent--都提供，按上述分工选。只有实测反复误用（如该用 context 的场景用了 native Agent 导致信息预算失控）才考虑屏蔽。

## 机制要点

- 子 session 记在 sessions 表（`parent_id` = 父 session），token 正常记账。`depth` 是剩余层级预算：channel session 3 → 子 2 → 孙 1 → 0 不能再派，禁止无限套娃。
- 子 agent 继承父 channel 的 worker 亲和性：channel 绑定了 worker，子 agent 的文件操作就在那台机器上。
- 私密会话（stealth）语义向下继承。
- 后台任务登记在进程内，MaxClaw 重启不恢复；`check_subagents` 可核对状态（不是轮询工具）。
- 父 turn 被用户 stop 时：同步子 agent 一并停止；后台子 agent 不受影响。

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss