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 发生前，紧急执行「上下文抢救」：
- 将当前未完成的任务要点写入
_任务.md
- 将已完成的中间成果写入
_数据.md
- 将当前进度和断点写入
_状态.md
- spawn Subagent 接续执行，task 参数中包含完整上下文
- Main Session 只保留极简状态等待结果
关键：compact 会丢信息，文件不会。compact 前落盘 = 零损失。
场景3：单任务天然适合拆分
信号：
- 任务涉及多个独立信息源/平台/API
- 任务有天然的分阶段结构（收集→分析→输出）
- 不同部分可以由不同 agent 并行完成
动作： 按本 skill 正常流程执行 Phase 1-5。
场景4：任务执行中途发现上下文不够用
信号：
- 执行过程中发现数据量远超预期
- 单个 Subagent 自己也快撑爆上下文
动作： Subagent 自身也应用三文件分离——把中间结果写入文件，避免在对话历史中累积。
⚠️ 嵌套 spawn 需谨慎： Subagent 再 spawn 子 Subagent（嵌套分工）会增加编排复杂度和资源消耗，必须在嵌套前告知用户并获得确认，不得自行决定嵌套。优先尝试通过三文件分离 + 断点续传解决问题，嵌套是最后手段。
场景5：Subagent 执行失败超过 5 次（🆕）
信号：
- 同一子任务连续失败 5 次（网络/权限/验证码/信息不足等）
- 状态文件中出现连续失败标记
动作：
- 停止重试，避免空转浪费 token
- 在
_状态.md 中记录：❌ 暂停：连续失败 5 次
- 向 Main Agent 报告：「任务 X 失败 5 次，需要人工介入」
- Main Agent 接到报告后：汇总已完成的成果，分析失败原因，向用户询问下一步（调整参数/换方案/放弃）
为什么停： 反复失败不解决会无限消耗 token，及时暂停并上报是最优策略。
上下文抢救清单（Compact 前必做）
☐ 当前任务目标 → 写入 _任务.md
☐ 已完成成果 → 写入 _数据.md
☐ 进度断点 → 写入 _状态.md
☐ 关键决策/用户偏好 → 写入 _任务.md 备注
☐ spawn Subagent → task 参数包含完整恢复信息
☐ Main Session 释放上下文 → 只保留等待结果的轻量状态
核心原则
1. 分工原则
| 角色 | 职责 | 不做什么 |
|---|
| Main Agent | 任务拆解、文件准备、启动 Subagent、监控进度、失败汇总+询问用户、最终整合 | 不亲自执行信息收集/重IO操作 |
| Subagent | 执行具体子任务、写数据文件、更新状态、失败5次即停+报告 | 不做最终决策、不回写任务文件 |
串行 vs 并行判断：
- 共享资源（如浏览器、数据库连接）→ 串行
- 独立资源（如 web_fetch、不同API）→ 可并行
- 不确定时 → 默认串行，安全优先
2. Subagent 记忆固化原则（防止任务丢失）
核心：三重保险——session + task参数 + 文件。缺一不可。
| 机制 | 用法 | 为什么 |
|---|
| 持久化 Session | mode: "session" + 固定 sessionKey | 任务累积不丢失，跨 compact 恢复 |
| 完整 task 参数 | 所有关键要求写进 sessions_spawn(task=...) | 每次回复都能看到完整指令 |
| 文件持久化 | 三文件（任务/状态/数据）落盘 | session 彻底丢失时也能恢复 |
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 次立即停止，不空转
| 文件 | 谁写 | 谁读 | 作用 | 大小趋势 |
|---|
_任务.md | Main Agent 写一次 | Subagent 启动时读一次 | 任务要求/验收标准 | 固定不变 |
_状态.md | Subagent 增量写 | Main Agent 快速读 | 进度/断点/问题 | 小，可控 |
_数据.md | Subagent 增量写 | Main Agent 汇总只读它 | 纯成果数据 | 随任务增长 |
路径规范： ~/.openclaw/workspace/tasks/[子任务]_[日期]_{任务|状态|数据}.md
四条铁律：
_任务.md：Main Agent 写一次，Subagent 只读，永不回写_状态.md：Subagent 增量写，Main Agent 只扫进度_数据.md：Subagent 增量写，Main Agent 仅读此文件汇总- 汇总时只读数据文件 + 极小状态文件，不读任务文件，不重复读状态
token 节省原理：
旧方案（任务+进度+数据混在一起）：
任务说明(500) + 进度日志(800) × N项 = 大量重复 token
三文件分离 + 节流规范：
任务文件（只读一次） + 状态文件（极小） + 数据文件（增量纯成果）
≈ 减少 60-75% token
Subagent 自身也这样做：
避免 Subagent 自身撑爆上下文，延长可执行步数
4. 资源整合度原则（🆕）
引用的路径和资源必须在使用前验证可达性：
| 资源类型 | 验证方法 |
|---|
| tasks 目录 | ls ~/.openclaw/workspace/tasks/，不存在则 mkdir -p |
| 依赖 skill | ls skills/[name]/SKILL.md，不存在则提示用户未安装 |
| 依赖脚本 | ls scripts/[name].sh，不存在则报告路径错误 |
| 最终 wiki 输出 | ls ~/llm-wiki/raw/articles/，不存在则跳过或创建 |
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 次即暂停，不空转：
| 类型 | 可自行重试 | 超过5次 → 暂停 |
|---|
| 网络临时故障 | 等10秒再试 | 连续5次 → 暂停 |
| 验证码/风控 | 写状态→暂停 | — |
| 信息不足/参数错误 | 修复后重试 | 连续5次 → 暂停 |
| 权限/认证失败 | — | 立即暂停，报告用户 |
状态文件标记： ❌ 暂停：连续失败 N 次
Main Agent 处理： 汇总已完成部分 + 失败原因 → 向用户报告并询问下一步
8. 交付验证原则（🆕）
适用于有外部交付的任务： 推送到 Discord/微信/群/板等外部渠道的任务，不能只凭"已发送"就认为完成。
最低交付证明要求：
📤 交付验证（必须全部提供，否则视为未交付）
- 目标渠道：[channel/thread id 或具体位置描述]
- 消息ID：[message_id 或 object_id]
- 人类可查位置：[可验证的链接或描述]
处理规则：
- 缺少任一证明项 → 任务视为未完成，不得标记
done
- 不接受"已发送/已上屏/已交付"等口头确认
- 如果外部渠道无 ID 机制 → 改用截图描述（描述中含时间戳+内容特征）
9. Memory 固化原则（🆕，按需写入，不爆炸）
Phase 5 清理前，按以下规则决定是否写入 memory：
| 条件 | 是否写 memory | 写什么 | 写多少 |
|---|
| 子任务数 ≥ 3 且正常完成 | 写一行摘要 | 任务目标 + 关键成果 + 文件路径 | ~100字 |
| 有失败/异常/阻塞 | 写 | 失败原因 + 解决建议 | ~50字 |
| 正常完成（子任务数 < 3） | 不写 | — | 0 |
| 发现更好方案/工具 | 写 | 替代方案 + 使用条件 | ~50字 |
| 用户做了特殊决策 | 写 | 用户偏好（下次自动用） | ~30字 |
理由： 每个 subagent 完成都写 memory 会导致 memory 爆炸（每天5个大任务≈5000字/天）。三文件已持久化成果，memory 只保留"规律和异常"，是最优平衡。
写法：
## [日期] 任务记忆（按需）
- [任务类型]: [一句话成果摘要] → [文件路径]
- 新失败类型: [错误] → [解决方式]
执行流程
Phase 1: 任务拆解与准备（Main Agent）
- 明确目标： 最终交付物是什么？验收标准？
- 识别子任务： 按信息源/执行步骤/资源依赖拆分
- 判断串行/并行： 共享资源串行，独立资源并行
- 为每个子任务创建三文件：
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 步法）
- 读
task 参数，必要时核对 _任务.md
- 按步骤执行；遇异常立即写状态文件并暂停
- 每完成一个单位 → append 到
_数据.md
- 每次进度变化 → 更新
_状态.md
- 完成写
✅ 完成；中断写 ⚠️ 部分完成 / ❌ 失败
原则：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天未动 / 用户主动要求
流程：
- Memory 固化（按需，见 9. Memory 固化原则）
- 判断：子任务数 ≥ 3 或有异常/失败/新发现？
- 是 → 从
_数据.md 提取一行摘要，写入 memory/YYYY-MM-DD.md
- 否 → 跳过（避免 memory 爆炸）
- 列出
tasks/ 下候选文件
- 向用户展示分类（本次任务 / 历史文件 / 保留文件）
- 未获明确批准前，不执行任何清理
- 获批后使用
trash，不用 rm
规则：
- 只清理中间文件，不删最终产出
- 默认保留 72h 内文件
- "可以清理/全删了/只清这次"算批准；"先看看"不算
进度汇报模板
## 📊 进度汇报
| 子任务 | 状态 | 结果 | 问题 |
|--------|------|------|------|
| [子任务A] | 🔄/✅/⚠️/❌ | [成果摘要] | — |
| [子任务B] | 🔄/✅/⚠️/❌ | [成果摘要] | — |
下一步：xxx
常见问题速查
| 问题 | 解决方案 |
|---|
| 🆕 对话太长快撑爆上下文 | 立即执行上下文抢救：落盘三文件 + spawn Subagent 接续 |
| 🆕 Context compact 后忘了在做什么 | 读 _状态.md 恢复断点，读 _任务.md 恢复目标，不需要会话记忆 |
| 🆕 Subagent 自己也快溢出 | 优先三文件分离+断点续传；嵌套 spawn 需先告知用户获确认，不得自行嵌套 |
| Subagent 忘了任务 | 检查 task 参数是否完整；恢复优先级：task > 文件 > 记忆 |
| 多个 Subagent 资源冲突 | 串行执行，一个用完再下一个 |
| Gateway 重启导致失败 | Main Agent 重新 spawn，状态文件中有断点 |
| 进度卡住 | subagents list 检查，kill 后从断点重启 |
| Token 消耗过大 | 确认只读数据文件汇总，不读任务文件和完整状态日志 |
| 数据来源不纯 | 每个来源设验证指标，发现混入立即停止报告 |
| 临时文件堆积 | Phase 5 清理，必须用户批准 |
| 🆕 Subagent 连续失败 5 次 | 停止重试，写状态文件❌，向 Main Agent 报告，等待人工介入 |
| 🆕 Subagent 返回 autopilot 但任务线停了 | 检查 anti-drop guard 三件事：任务线存在？未完成？下一跳已派发？ |
| 🆕 外部交付任务口头确认"已发送" | 要求提供 delivery-proof（message_id/channel/location），缺一不可标记未完成 |
🆕 辅助功能：每日 Session 清理定时任务
作用： 自动清理过期/孤儿 session 文件，释放磁盘空间，避免会话列表杂乱。
使用流程：
- 用户确认需要创建定时任务（由 Main Agent 询问）
- Main Agent 使用
cron add 创建每日定时任务（详见下方配置）
- 任务运行在
isolated session，以 announce 方式汇报结果
- 用户可随时用
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 只保留等待状态 | 文件系统读写 |
| 🆕 Context compact 前抢救 | 紧急落盘三文件 + spawn 接续 Subagent | 无，纯文件操作 |
| 🆕 单任务数据量超预期 | Subagent 自身也用三文件分离，必要时嵌套 spawn | 视情况 |
| 多平台攻略抓取 | 按平台拆：小红书/马蜂窝/携程/公众号 | 浏览器串行，web_fetch并行 |
| 多文件格式转换 | 按格式拆：PDF/Word/Excel/HTML | 无，可全部并行 |
| 多数据源调研 | 按来源拆：论文/新闻/内部文档/社交媒体 | API限流可能需串行 |
| 代码项目重构 | 按模块拆：前端/后端/数据库/测试 | 文件系统，需协调避免冲突 |
| 多语言翻译 | 按语言拆：EN/JP/KR/FR | 无，可全部并行 |
设计理念
找的范围应该确定性，想的综合应该概率性。
—— 找的部分用工具/子任务精确筛选，想的部分交给 Main Agent 推理整合。
三文件分离的本质是关注点分离： 任务是契约，状态是心跳，数据是成果。混在一起，token 浪费在重复读取不变的任务说明；分开了，每次只读需要的部分。
