subagent-orchestrator-whhh（子 Agent 协调器 whhh）

Subagent Orchestrator Skill

版本

• v1.3.0 (2026-04-26): 新增：结构化 Return 协议（tag/证明格式）+ Anti-Drop Guard + 交付验证规则 + 按需 Memory 固化（第2轮达尔文优化）
• v1.2.0 (2026-04-26): 新增：Subagent token 节流规范、连续失败 5 次暂停机制；辅助用户创建每日 session 清理定时任务
• v1.0.0 (2026-04-26): 从 tourism-guide-harvester 提炼，泛化为通用大型任务分工框架

技能描述

将复杂大型任务拆解为多个子任务，通过 Subagent 并行/串行执行，三文件持久化防丢失，Main Agent 统筹整合。适用于任何需要多步骤、多信息源、长时间运行的任务，也适用于即将超出上下文窗口时的任务分流——在 context 被压缩前，将未完成工作迁移到 Subagent，避免记忆丢失。

触发词

• 大型任务拆分
• 任务分工
• 子任务编排
• 多agent协作
• 复杂任务执行
• 上下文溢出
• context快满了
• 任务分流

自动触发场景（🆕 重点）

不只是用户主动要求时才用，以下情况应自动启用本 skill：

场景1：预估任务将超出上下文窗口

信号：

• 任务需要读取/处理大量文件或网页（>10个源）
• 预计对话轮次 > 20 轮
• 需要多轮浏览器操作 + 大量文本提取
• 单次输出预计 > 2000 字且还要继续

动作： 立即将任务拆分为 Subagent 子任务，把重IO/重token的部分分流出去，Main Session 只保留轻量统筹。

场景2：Context 即将被 compact

信号：

• 对话已经很长，感觉到近期回复变慢或开始遗忘早期内容
• 系统发出 context window 接近上限的信号
• 已执行大量工具调用，对话历史膨胀

动作： 在 compact 发生前，紧急执行「上下文抢救」：

1. 将当前未完成的任务要点写入 _任务.md
2. 将已完成的中间成果写入 _数据.md
3. 将当前进度和断点写入 _状态.md
4. spawn Subagent 接续执行，task 参数中包含完整上下文
5. Main Session 只保留极简状态等待结果

关键：compact 会丢信息，文件不会。compact 前落盘 = 零损失。

场景3：单任务天然适合拆分

信号：

• 任务涉及多个独立信息源/平台/API
• 任务有天然的分阶段结构（收集→分析→输出）
• 不同部分可以由不同 agent 并行完成

动作： 按本 skill 正常流程执行 Phase 1-5。

场景4：任务执行中途发现上下文不够用

信号：

• 执行过程中发现数据量远超预期
• 单个 Subagent 自己也快撑爆上下文

动作： Subagent 自身也应用三文件分离——把中间结果写入文件，避免在对话历史中累积。

⚠️ 嵌套 spawn 需谨慎： Subagent 再 spawn 子 Subagent（嵌套分工）会增加编排复杂度和资源消耗，必须在嵌套前告知用户并获得确认，不得自行决定嵌套。优先尝试通过三文件分离 + 断点续传解决问题，嵌套是最后手段。

场景5：Subagent 执行失败超过 5 次（🆕）

信号：

• 同一子任务连续失败 5 次（网络/权限/验证码/信息不足等）
• 状态文件中出现连续失败标记

动作：

1. 停止重试，避免空转浪费 token
2. 在 _状态.md 中记录：❌ 暂停：连续失败 5 次
3. 向 Main Agent 报告：「任务 X 失败 5 次，需要人工介入」
4. Main Agent 接到报告后：汇总已完成的成果，分析失败原因，向用户询问下一步（调整参数/换方案/放弃）

为什么停： 反复失败不解决会无限消耗 token，及时暂停并上报是最优策略。

上下文抢救清单（Compact 前必做）

☐ 当前任务目标 → 写入 _任务.md
☐ 已完成成果 → 写入 _数据.md
☐ 进度断点 → 写入 _状态.md
☐ 关键决策/用户偏好 → 写入 _任务.md 备注
☐ spawn Subagent → task 参数包含完整恢复信息
☐ Main Session 释放上下文 → 只保留等待结果的轻量状态

核心原则

1. 分工原则

串行 vs 并行判断：

• 共享资源（如浏览器、数据库连接）→ 串行
• 独立资源（如 web_fetch、不同API）→ 可并行
• 不确定时 → 默认串行，安全优先

2. Subagent 记忆固化原则（防止任务丢失）

核心：三重保险——session + task参数 + 文件。缺一不可。

SessionKey 命名规范： [项目]-[子任务简称]-[YYYYMMDD]

最小 spawn 模板：

sessions_spawn({
  label: "[子任务描述]",
  mode: "session",
  sessionKey: "[project]-[subtask]-[yyyymmdd]",
  task: `
目标：[明确、可验收的目标]
只读：_任务.md
只写：_状态.md + _数据.md
共享资源：[浏览器/端口/API等，如无需则删]
异常处理：立即写入状态文件并提示人工介入
验收标准：[至少N条/包含XX/格式为XX]
`
})

恢复优先级： task 参数 > 任务文件 > 会话记忆

原则：task 参数是运行真迹，文件是恢复真迹，session 只是执行容器。

3. 三文件分离原则（降低 token 消耗）

Subagent Token 节流规范（🆕）：

• 只读一次任务文件：任务文件 _任务.md 只在启动时读一次，后续按状态文件断点续做，不重复读
• 增量落盘：每完成一个子步骤，立即写数据文件，不要攒到全部完成再写（Subagent 崩溃时保底）
• 状态文件极小化：只记关键断点（完成到哪、下一步），不写流水日志，保持在 500 字以内
• Main Agent 汇总只读数据：汇总阶段只看 _数据.md，不看 _任务.md 和大段状态日志
• 失败写状态即停：遇到错误先写状态文件再试；同一错误连续失败 5 次立即停止，不空转

路径规范： ~/.openclaw/workspace/tasks/[子任务]_[日期]_{任务|状态|数据}.md

四条铁律：

1. _任务.md：Main Agent 写一次，Subagent 只读，永不回写
2. _状态.md：Subagent 增量写，Main Agent 只扫进度
3. _数据.md：Subagent 增量写，Main Agent 仅读此文件汇总
4. 汇总时只读数据文件 + 极小状态文件，不读任务文件，不重复读状态

token 节省原理：

旧方案（任务+进度+数据混在一起）：
  任务说明(500) + 进度日志(800) × N项 = 大量重复 token

三文件分离 + 节流规范：
  任务文件（只读一次） + 状态文件（极小） + 数据文件（增量纯成果）
  ≈ 减少 60-75% token

Subagent 自身也这样做：
  避免 Subagent 自身撑爆上下文，延长可执行步数

4. 资源整合度原则（🆕）

引用的路径和资源必须在使用前验证可达性：

Phase 1 开头增加路径验证步骤（检查点）：

Phase 1 第0步：验证路径
- 验证 tasks/ 目录存在
- 验证依赖 skill 的 SKILL.md 可达
- 验证依赖脚本可执行
- 如有不可达 → 报告给用户，说明缺少什么
- 全部通过后再进入任务拆解

references/paths.md 包含所有引用的路径，可随时查阅。

5. 资源独占原则

• 共享资源不可并发： 浏览器(CDP)、数据库连接、文件写锁等，同时间只有一个 Subagent 使用
• 独立资源可并发： web_fetch、只读API、不同端口的服务等
• 执行顺序由 Main Agent 在 spawn 时明确指定： "第N个执行，等前面的完成"

6. 数据纯正性原则

• 不擅自切换信息来源： 用户指定了什么来源就用什么
• 每个来源有验证方法： 提取该来源特有的指标/字段，用于验证数据确实来自该来源
• 切换来源需用户同意： 不可用时要报告问题，征求确认

7. 失败阈值原则（🆕）

连续失败 5 次即暂停，不空转：

状态文件标记： ❌ 暂停：连续失败 N 次 Main Agent 处理： 汇总已完成部分 + 失败原因 → 向用户报告并询问下一步

8. 交付验证原则（🆕）

适用于有外部交付的任务： 推送到 Discord/微信/群/板等外部渠道的任务，不能只凭"已发送"就认为完成。

最低交付证明要求：

📤 交付验证（必须全部提供，否则视为未交付）
- 目标渠道：[channel/thread id 或具体位置描述]
- 消息ID：[message_id 或 object_id]
- 人类可查位置：[可验证的链接或描述]

处理规则：

• 缺少任一证明项 → 任务视为未完成，不得标记 done
• 不接受"已发送/已上屏/已交付"等口头确认
• 如果外部渠道无 ID 机制 → 改用截图描述（描述中含时间戳+内容特征）

9. Memory 固化原则（🆕，按需写入，不爆炸）

Phase 5 清理前，按以下规则决定是否写入 memory：

理由： 每个 subagent 完成都写 memory 会导致 memory 爆炸（每天5个大任务≈5000字/天）。三文件已持久化成果，memory 只保留"规律和异常"，是最优平衡。

写法：

## [日期] 任务记忆（按需）
- [任务类型]: [一句话成果摘要] → [文件路径]
- 新失败类型: [错误] → [解决方式]

执行流程

Phase 1: 任务拆解与准备（Main Agent）

1. 明确目标： 最终交付物是什么？验收标准？
2. 识别子任务： 按信息源/执行步骤/资源依赖拆分
3. 判断串行/并行： 共享资源串行，独立资源并行
4. 为每个子任务创建三文件：

write ~/.openclaw/workspace/tasks/[子任务]_[日期]_任务.md   # 任务要求
write ~/.openclaw/workspace/tasks/[子任务]_[日期]_状态.md   # 初始状态
write ~/.openclaw/workspace/tasks/[子任务]_[日期]_数据.md   # 空数据文件

任务文件模板：

# [子任务名称]（[日期]）

## 任务要求
- 目标：[明确、可量化的目标]
- 信息来源：[指定来源及验证方法]
- 输出文件：~/.openclaw/workspace/tasks/[子任务]_[日期]_数据.md

## 共享资源
- [资源名称]：[端口/路径等]
- 执行顺序：第N个

## 验收标准
- [标准1]
- [标准2]

## 数据文件格式（Subagent 按此格式写入数据文件）
[定义输出格式模板]

状态文件初始内容：

# [子任务名称]状态（[日期]）

## 执行进度
- [时间] ⏳ 等待启动

## 断点记录
- 上次完成：0/N
- 下一步：[第一步操作]

## 任务状态
- 状态：⏳ 等待启动
- 完成进度：0/N

## 待解决问题
- 无

Phase 2: 启动 Subagent（Main Agent）

⚠️ 前提条件：已获用户明确确认（见上方 Spawn 前确认节点）

串行执行：

子任务A → 完成后 → 子任务B → 完成后 → 子任务C

可并行的：

子任务A（用浏览器）  ──→ 完成后 ──→ 子任务B（用浏览器）
子任务C（不用浏览器）──→ 立即启动，与A并行

每次 spawn 四必填：

• ✅ mode: "session"
• ✅ sessionKey: "[project]-[subtask]-[yyyymmdd]"
• ✅ 完整 task 参数（塞满所有细节）
• ✅ 三文件路径告知
• ✅ 交付证明要求（如有外部交付：delivery-proof 字段说明需要的证明类型）

⚠️ Spawn 前必须确认（检查点）：

每个 Phase 2 启动 Subagent 之前，必须向用户展示：子任务列表 + 并行/串行策略 + 预计执行顺序，获得用户明确回复（如「好/开始/执行」）后再 spawn。未获确认不得自行启动。嵌套 spawn 已在原则中强制要求确认，此处强调是为了覆盖普通 spawn 也需要确认。

确认话术模板：

准备好启动子任务了：
- 子任务 A（并行，独立资源）
- 子任务 B（串行，等待 A 完成）
- 预计执行顺序：A → B
开始执行？

Phase 3: Subagent 执行（5 步法）

1. 读 task 参数，必要时核对 _任务.md
2. 按步骤执行；遇异常立即写状态文件并暂停
3. 每完成一个单位 → append 到 _数据.md
4. 每次进度变化 → 更新 _状态.md
5. 完成写 ✅ 完成；中断写 ⚠️ 部分完成 / ❌ 失败

原则：task 参数优先；任务文件只读；状态/数据文件读写

结构化 Return 协议（🆕）：

每次向 Main Agent 汇报前，按以下格式写入状态文件：

## Subagent Return
tag: [autopilot | done | partial | blocked | need_user]
task_id: [子任务名]
completed: N/N
files_written: [文件路径列表]
next: [下一步做什么]
proof: [外部交付证明：message_id/channel/路径等，若无外部交付则填 null]

tag 含义：

• autopilot：本轮完成但任务线未结束 → Main Agent 必须派下一跳
• done：本子任务完全完成 → 进入 Phase 4 整合
• partial：部分完成，状态文件已有断点 → 等待接手或用户决定
• blocked：被阻塞（验证码/权限/网络持续失败）→ 等待人工介入
• need_user：需要用户决策（如来源不可用/参数不明确）→ 报告给用户

⚠️ 注意： tag=autopilot 不等于任务线结束。Main Agent 收到此 tag 后，必须立即派下一跳或显式关闭任务线，不得停等用户。

Phase 4: Main Agent 整合（6 步法）

第1步：扫状态文件（极小，token≈0）

read ~/.openclaw/workspace/tasks/*_状态.md

判断：全✅→继续 | 有⚠️/❌→汇总已有+标注 | 有⏳→汇总已完成部分

第2步：仅读数据文件（纯成果内容，无冗余）

read ~/.openclaw/workspace/tasks/*_数据.md

按优先级顺序读，只读数据文件，不读任务文件。

第3步：跨数据源交叉统计

• 同类项归一（忽略空格/标点差异）
• 提及/出现次数 +1
• 每项附加所有来源
• 按出现次数降序

第4步：排序与优先级计算

• 定义权重维度（来源权重、时间衰减、相关性等）
• 计算综合优先级分
• 按分降序排列

第5步：生成最终输出文件

write [最终输出路径]

输出前逐项检查验收标准。

第6步：输出完成报告

【任务完成】
📊 数据来源：[各子任务及数量]
📋 成果统计：[关键指标]
📁 输出文件：[路径]

Anti-Drop Guard（🆕）：

每次 subagent 返回 tag=autopilot 后，Main Agent 必须确认三件事，否则本轮未完成：

✅ 确认1：任务线还在任务板上（未手动关闭）
✅ 确认2：任务线未完成（有下一节点）
✅ 确认3：下一跳已派发 OR 任务线已显式关闭（idle/blocked/need_user/done）

三件事任一缺失 → 本轮 Turn 不完整：

• 不能仅因 subagent 说"这轮完成了"就停等用户
• 不能仅因 Phase 4 第6步报告了就结束 Turn
• Turn 只有在节点已推进 + 下一跳已派发（或任务线已关闭）后才算真正完成

正确做法：

Subagent 返回 tag=autopilot
→ Main Agent 读取状态文件解析 tag
→ 确认三件事
→ 如有下一跳，立即 spawn 下一 Subagent（或派给自己）
→ 向用户简短汇报进度（不等待）

Phase 5: 清理（需用户批准）

触发： 任务完成 / 失败 / 超7天未动 / 用户主动要求

流程：

1. Memory 固化（按需，见 9. Memory 固化原则）

- 判断：子任务数 ≥ 3 或有异常/失败/新发现？ - 是 → 从 _数据.md 提取一行摘要，写入 memory/YYYY-MM-DD.md - 否 → 跳过（避免 memory 爆炸）

1. 列出 tasks/ 下候选文件
2. 向用户展示分类（本次任务 / 历史文件 / 保留文件）
3. 未获明确批准前，不执行任何清理
4. 获批后使用 trash，不用 rm

规则：

• 只清理中间文件，不删最终产出
• 默认保留 72h 内文件
• "可以清理/全删了/只清这次"算批准；"先看看"不算

进度汇报模板

## 📊 进度汇报

| 子任务 | 状态 | 结果 | 问题 |
|--------|------|------|------|
| [子任务A] | 🔄/✅/⚠️/❌ | [成果摘要] | — |
| [子任务B] | 🔄/✅/⚠️/❌ | [成果摘要] | — |

下一步：xxx

常见问题速查

🆕 辅助功能：每日 Session 清理定时任务

作用： 自动清理过期/孤儿 session 文件，释放磁盘空间，避免会话列表杂乱。

使用流程：

1. 用户确认需要创建定时任务（由 Main Agent 询问）
2. Main Agent 使用 cron add 创建每日定时任务（详见下方配置）
3. 任务运行在 isolated session，以 announce 方式汇报结果
4. 用户可随时用 cron list 查看或 cron remove 取消

Cron 任务配置：

cron.add({
  name: "每日 Session 清理",
  schedule: { kind: "cron", expr: "30 3 * * *", tz: "Asia/Shanghai" }, // 每天凌晨 03:30
  payload: {
    kind: "agentTurn",
    message: `
执行以下步骤完成 session 清理：

1. 运行扫描：~/.openclaw/workspace/skills/session-cleanup/scripts/scan_sessions.sh scan
2. 解析 JSON 输出，汇总：孤儿文件数、过期会话数、预计可释放空间
3. 默认保护 72 小时内的会话，不删除 agent:main:main
4. 删除所有孤儿 jsonl 文件（磁盘存在但 sessions.json 未登记的）
5. 删除所有过期会话（72小时以上且非受保护的）
6. 更新 sessions.json 去除对应的条目

报告格式：
🧹 每日 Session 清理完成
- 扫描时间：[时间]
- 清理孤儿文件：N 个（约 X MB）
- 清理过期会话：N 个（约 X MB）
- 本次共释放：约 X MB
- 当前注册会话：N`,
    timeoutSeconds: 300,
  },
  delivery: { mode: "announce", bestEffort: false },
  sessionTarget: "isolated",
  enabled: true,
})

⚠️ 注意事项：

• 必须先确认用户要创建，再执行 cron add
• 定时任务在 isolated session 运行，不需要 Main Agent 常驻
• 如需取消：cron remove [jobId]

适用场景示例

设计理念

找的范围应该确定性，想的综合应该概率性。 —— 找的部分用工具/子任务精确筛选，想的部分交给 Main Agent 推理整合。

三文件分离的本质是关注点分离： 任务是契约，状态是心跳，数据是成果。混在一起，token 浪费在重复读取不变的任务说明；分开了，每次只读需要的部分。