复杂任务编排器#

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

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

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

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

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

---

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

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

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

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

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

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

任务完成后收尾：

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

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

---

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

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

text

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

阶段 2：选择执行策略#

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

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

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

做法：

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

防膨胀措施：

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

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

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

做法：

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

Sub-agent 任务 prompt 模板：

text

你的任务：[具体描述]

输出要求：
- 结果写入文件 [路径]（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+ 项）、需要中途验证、怕断点丢进度

做法：

1. 按批次分段：每段 10-20 个子任务
2. 每段完成后：
   • 结果写入检查点文件（JSON/Markdown）
   • 汇报进度给用户（ 已完成 X/Y，成功 A 个失败 B 个）
   • 验证结果（抽检 2-3 个）
3. 如果某段失败，从检查点恢复而不是重头来

检查点文件格式：

json

{
  "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：混合编排#

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

做法：

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

示例：

text

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

---

阶段 3：执行与监控#

执行铁律#

1. WAL 优先：关键中间结果先写文件再继续，不要等最后一起写
2. 进度可见：每完成 25% 给用户简短汇报
3. 失败隔离：一个子任务失败不影响其他子任务，记录失败原因继续
4. 验收分离：做完 ≠ 完成，验完才算完（参考 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，而是并发控制的基本原理——跟数据库事务冲突是同一个问题。

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

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

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

飞书文档特有问题

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

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

text

✅ 新建文档 → 写入重构内容 → 通知用户手动复制粘贴替换原文档
❌ 原地删除全部 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 调用串行等返回，或合并成一次调用

三条铁律：

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

输出归一化#

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

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

---

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

text

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

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

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

---

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

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

已知缺陷清单#

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

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

1. 不信任 announce，主动验证

text

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. 失败后的恢复流程

text

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 提供输出格式
• 多步骤工程 → 本技能选策略 + 具体领域技能提供专业知识