复杂任务编排器

解决一个核心问题：大任务怎么拆、怎么跑、翻车了怎么救。

决策入口：该不该用这个技能？

收到任务后先过三个判断：

条件	是 →	否 →
------	------	------
步骤 ≥ 5 或有依赖链	继续	可能不需要本技能
涉及批量操作（≥10 项同类任务）	继续	可能不需要本技能
预估用时 > 3 分钟或需要大量搜索/API 调用	继续	可能不需要本技能

满足任一条 → 走编排流程。全部不满足 → 直接干。

阶段 0：预记录（开工前必做！）

在做任何事之前，先把需求和计划写到 daily notes / 工作日志里。

为什么：崩溃/重启后上下文全丢。如果没有预记录，用户必须反复重述需求。实战中出现过用户重复 7-8 次需求的情况。

记录内容（写到 memory/YYYY-MM-DD.md 或项目工作日志）：

[来源] 谁提的需求
需求要点 — 用户想要什么（关键细节不能丢）
执行计划 — 准备用什么策略、分几步
关键参数 — 文档 token、文件路径、目标结构等
当前状态 — "未开始" / "进行到步骤 X"

执行中每完成关键步骤更新进度。先写日志，再执行操作（WAL 原则）。

任务完成后收尾：

清理过程中产生的临时工作记忆（如 memory_store 中的中间快照）
日志只保留：做了什么、结果、经验教训

重启后恢复：读日志 → 找到未完成任务 → 从断点继续，不问用户"我们之前在做什么"。

阶段 1：任务画像（30 秒内完成）

回答四个问题，写成内部工作笔记（不需要给用户看）：

1. 目标：最终交付什么？（一句话）
2. 规模：多少个子任务 / 多少数据量？
3. 依赖：哪些步骤必须串行？哪些可以并行？
4. 风险：最可能在哪一步翻车？

阶段 2：选择执行策略

根据任务画像选策略（只选一个）：

策略 A：主 session 串行（默认安全策略）

适用：步骤有强依赖、需要上下文连续、搜索密集型任务

做法：

主 session 自己一步步干
每完成一个里程碑，写入文件（WAL 原则）
上下文膨胀时主动精简回复

防膨胀措施：

每处理 5 个子项后，把结果写入文件，回复中只保留摘要
工具返回的大结果（搜索、web_fetch）提取关键段落，不要全量放进上下文
感觉上下文变重时，回复刻意简短

策略 B：分片 + Sub-agent 并行

适用：子任务之间无依赖、每个子任务自包含、不需要大量搜索

做法：

拆分成 N 个独立分片，每片 ≤ 5 个子任务
每个 sub-agent 的 task prompt 必须完全自包含（不依赖主 session 上下文）
设合理超时（参考下方超时指南）
sub-agent 结果写入文件（不是回复到主 session）

Sub-agent 任务 prompt 模板：

你的任务：[具体描述]

输出要求：
- 结果写入文件 [路径]（JSON/Markdown 格式）
- 不要用 message send，把结果写文件即可
- 如果某个子项失败，记录失败原因继续处理下一个

数据：
[直接给出需要处理的数据，不要说"参考主 session"]

超时指南：

子任务类型	建议超时	说明
-----------	---------	------
纯计算/文件处理	2-3 分钟	不涉及外部调用
少量搜索（≤3 次）	5 分钟	搜索 + 处理
中等搜索（4-8 次）	8 分钟	可能遇到慢响应
重搜索（>8 次）	⚠️ 不建议用 sub-agent	改用策略 A

关键防护：

不要给 sub-agent 搜索密集任务——上下文膨胀 → 推理变慢 → 超时 → fallback 乱跑
被 kill 的 sub-agent 可能产生残余进程——发 announce 消息搞乱主 session
sub-agent 数量 ≤ 3 个并行（EC2 小实例资源有限）

策略 C：分段串行 + 检查点

适用：大批量操作（50+ 项）、需要中途验证、怕断点丢进度

做法：

按批次分段：每段 10-20 个子任务
每段完成后：

结果写入检查点文件（JSON/Markdown）
汇报进度给用户（已完成 X/Y，成功 A 个失败 B 个）
验证结果（抽检 2-3 个）

如果某段失败，从检查点恢复而不是重头来

检查点文件格式：

{
  "task": "任务描述",
  "total": 100,
  "completed": 30,
  "succeeded": 28,
  "failed": 2,
  "failed_items": [
    {"id": "xx", "error": "原因"}
  ],
  "last_checkpoint": "2026-04-03T12:00:00Z",
  "output_file": "/path/to/results.json"
}

策略 D：混合编排

适用：任务有多个阶段，不同阶段适合不同策略

做法：

把任务拆成阶段
每个阶段独立选择策略 A/B/C
阶段之间通过文件传递中间结果

示例：

研究 200 家公司 →
  阶段 1（策略 A）：搜索收集所有公司基本信息 → 写入 raw-data.json
  阶段 2（策略 B）：3 个 sub-agent 并行处理纯数据整理（不搜索）
  阶段 3（策略 A）：主 session 汇总 + 补充搜索验证
  阶段 4（策略 C）：分批写入飞书文档/Excel

阶段 3：执行与监控

执行铁律

WAL 优先：关键中间结果先写文件再继续，不要等最后一起写
进度可见：每完成 25% 给用户简短汇报
失败隔离：一个子任务失败不影响其他子任务，记录失败原因继续
验收分离：做完 ≠ 完成，验完才算完（参考 AGENTS.md 验收原则）

常见翻车场景与应对

翻车场景	症状	应对
---------	------	------
上下文膨胀	回复变慢、开始遗忘前面内容	中间结果写文件，回复只放摘要
Sub-agent 超时	3+ 分钟无响应	kill → 读文件看有没有部分结果 → 主 session 接手
Sub-agent 残余进程	收到 announce 消息乱入	忽略，不要回应残余消息
批量 API 限流	连续 429/失败	降速：每 2-3 个操作暂停 1 秒
中途断连/compaction	上下文被压缩	读检查点文件恢复进度，从断点继续
飞书文档写入限制	单次表格行数有限	大表用 Excel 导出，不硬塞飞书表格
并发写入冲突（⚠️ 高频）	order conflict / 数据丢失 / 后写覆盖先写	见下方「并发写入防护」
大文档原地重构（⚠️ 必崩）	ordering conflict / 文档变半成品 / 主进程崩溃	新建文档写入，不原地改。见「并发写入防护」

并发写入防护（2026-04-03/04 实战教训）

本质问题：任何"读→改→写"模式在并发场景下都会翻车。这不是某个工具的 bug，而是并发控制的基本原理——跟数据库事务冲突是同一个问题。

核心原则：同一时间，同一资源，只能有一个写入者。

问题全景（不只是飞书文档！）

资源类型	具体表现	根因
---------	---------	------
飞书文档 API	Message ordering conflict	乐观锁 revision_id 冲突
Excel (openpyxl)	后写覆盖先写，数据丢失	全量读→改→全量写，无锁
本地文件	sub-agent 内容被另一个覆盖	多进程写同一文件，无锁
飞书 write 全量覆盖	read 异常→write 空内容→丢数据	"先读后写"不是原子操作
连续快速 API 调用	前一个没返回就发下一个	版本号过期

飞书文档特有问题

连续密集写入：一次操作里调多次 feishu_doc insert/update/write，前一个请求还没返回下一个就发出去，revision 对不上就 conflict。

大文档原地重构（>100 block）：密集删除+创建数百个 block，几乎必然 conflict，失败后文档可能处于半成品状态。

✅ 新建文档 → 写入重构内容 → 通知用户手动复制粘贴替换原文档
❌ 原地删除全部 block + 重写（必崩）
❌ 用 feishu_doc write 全量覆盖大文档（同理）

实战：铁路行业分析文档（500+ block）原地重构 5 次全部失败，新建文档写入一次成功（2026-04-04）。

Excel/本地文件问题

openpyxl 等库是「读取全量→修改→全量写回」模式。两个 sub-agent 同时读同一 xlsx，各自加了数据写回，后保存的覆盖先保存的，先写的数据直接丢。

实战：248 家 ISV 研究，3 个 sub-agent 并行写同一 xlsx，1 个翻车数据全丢，手动补 60 行（2026-04-03）。

统一防护铁律

❌ 危险模式	✅ 安全替代
------------	-----------
多 sub-agent 写同一 Excel/文件	每个 sub-agent 写独立文件（result-1.json 等）→ 主 session 合并
多 sub-agent 写同一飞书文档	同上，主 session 最后一次性写入
"先 read 再 write" 全量覆盖	用 insert/append 增量写入
大文档原地重构	新建文档写入 → 人工复制替换
连续快速 API 调用	串行等返回，或合并成一次调用

三条铁律：

写入权收归一处 — sub-agent 只读/搜/算，写入全部由主 session 做
增量优于全量 — insert > write，append > 覆盖
并行读、串行写 — 搜索可以并行，写入必须串行

输出归一化

不管用哪个策略，最终都要：

结果文件：JSON/Excel/Markdown（根据用户需要）
进度汇报：完成 X/Y，成功 A / 失败 B
失败清单：哪些失败了、为什么、要不要重试
交付验证：抽检确认结果正确

快速参考：策略选择决策树

任务进来
  ├─ 子任务之间有依赖？ → 策略 A（串行）
  ├─ 子任务独立 + 不需要搜索？ → 策略 B（sub-agent 并行）
  ├─ 50+ 项批量操作？ → 策略 C（分段检查点）
  ├─ 多阶段混合？ → 策略 D（混合编排）
  └─ 不确定？ → 先用策略 A，后面发现可以并行再切

不确定时选策略 A——串行虽然慢但最稳。并行看着快，翻车了反而更慢。

搜索密集型任务 → 策略 A 或 C，不要用策略 B。Sub-agent 做搜索密集任务不稳定（上下文膨胀→推理变慢→超时/返回空）。

Sub-agent 已知缺陷与缓解（2026-04-03 社区调研）

以下问题是 OpenClaw sub-agent 机制的平台级局限，不是使用方式的问题。了解它们才能设计出靠谱的编排策略。

已知缺陷清单

缺陷	严重度	说明	GitHub Issue
------	--------	------	-------------
Announce 静默丢失	🔴 高	sub-agent 完成任务后回传结果超时（硬编码 60s），无重试，结果直接丢失，用户无感知	#17000, #7666, #44925
并发 session lock 冲突	🔴 高	多 agent 并行时 session 文件锁超时，即使用隔离 workspace 也会撞锁	#43367
完成声明不可信	🟡 中	sub-agent 声称"文件已创建"但文件实际不存在，无内置验证机制	#44925 Pattern 3
超时无自动重启	🟡 中	sub-agent 超时后系统不做任何事——不重试、不通知、不自动重启	#44925 Pattern 2
Gateway 争用	🟡 中	多 sub-agent 同时运行增加 gateway 负载，小实例（EC2 t3.micro）尤其明显	#43367

缓解策略（目前最佳实践）

1. 不信任 announce，主动验证

Sub-agent 完成后：
  ├─ 用 sessions_history 查看 sub-agent 实际输出
  ├─ 用 read 验证声称创建的文件确实存在且内容正确
  └─ 不要只看 announce 消息就认为成功

2. 控制并发度

EC2 小实例：≤ 2 个 sub-agent 并行
中等实例：≤ 3 个
设置 agents.defaults.subagents.maxConcurrent 硬限制
宁可串行慢一点，也不要并行翻车

3. 设计容错的 task prompt

要求 sub-agent 把结果写文件（不依赖 announce）
每处理 N 个子项就写一次中间结果（增量保存）
明确失败处理逻辑："如果 X 失败，记录原因继续下一个"

4. 搜索密集任务避开 sub-agent

原因：搜索返回大量文本 → 上下文膨胀 → 推理变慢 → 更多超时 → 可能 fallback 到弱模型
社区验证（#47862）：路由模式用 gpt-4o-mini 做分类，重活交给强模型
我们验证（2026-04-03 ISV 研究）：3 个 sub-agent 中 1 个返回空结果，正是因为搜索密集

5. 失败后的恢复流程

Sub-agent 疑似失败：
  1. sessions_history 查看它到底做了什么
  2. 检查它应该输出的文件是否存在
  3. 如果有部分结果 → 从检查点继续
  4. 如果完全没结果 → 主 session 接手（别再 spawn 新的去重试同一个任务）
  5. 更新检查点文件标记哪些需要补救

未来关注

Task Flow（v2026.4.2 新增）：持久化任务流编排，可能比 sub-agent 更适合复杂编排
noOutputTimeoutMs（#28617）：针对 stuck streaming 连接的超时配置
持续关注 OpenClaw release notes 中 sub-agent 相关修复

与其他技能的协作

本技能是编排层，不替代领域技能：

批量研究 → 本技能选策略 + company-research 提供研究方法
批量数据处理 → 本技能选策略 + excel-xlsx 提供输出格式
多步骤工程 → 本技能选策略 + 具体领域技能提供专业知识

Complex Task Orchestrator

概述