Complex Task Orchestrator
by @xwz119
复杂任务编排与分治。当任务涉及批量操作（研究20+公司、处理大量数据）、多步骤工程（5+步骤有依赖关系）、sub-agent可能翻车的场景时激活。提供预记录防崩溃丢失、分治策略、超时管控、上下文膨胀防护、失败恢复方案。也适用于"任务太大不知道怎么拆"、"sub-agent老超时"、"批量操作到一半挂了"、"崩溃后...
clawhub install complex-task-orchestrator📖 About This Skill
name: complex-task-orchestrator description: 复杂任务编排与分治。当任务涉及批量操作（研究20+公司、处理大量数据）、多步骤工程（5+步骤有依赖关系）、sub-agent可能翻车的场景时激活。提供预记录防崩溃丢失、分治策略、超时管控、上下文膨胀防护、失败恢复方案。也适用于"任务太大不知道怎么拆"、"sub-agent老超时"、"批量操作到一半挂了"、"崩溃后用户反复重述需求"等排查场景。不用于简单的单步骤任务或纯对话场景。
复杂任务编排器
解决一个核心问题：大任务怎么拆、怎么跑、翻车了怎么救。
决策入口：该不该用这个技能？
收到任务后先过三个判断：
| 条件 | 是 → | 否 → | |------|------|------| | 步骤 ≥ 5 或有依赖链 | 继续 | 可能不需要本技能 | | 涉及批量操作（≥10 项同类任务） | 继续 | 可能不需要本技能 | | 预估用时 > 3 分钟 或需要大量搜索/API 调用 | 继续 | 可能不需要本技能 |
满足任一条 → 走编排流程。全部不满足 → 直接干。
阶段 0：预记录（开工前必做！）
在做任何事之前，先把需求和计划写到 daily notes / 工作日志里。
为什么：崩溃/重启后上下文全丢。如果没有预记录，用户必须反复重述需求。实战中出现过用户重复 7-8 次需求的情况。
记录内容（写到 memory/YYYY-MM-DD.md 或项目工作日志）：
1. [来源] 谁提的需求
2. 需求要点 — 用户想要什么（关键细节不能丢）
3. 执行计划 — 准备用什么策略、分几步
4. 关键参数 — 文档 token、文件路径、目标结构等
5. 当前状态 — "未开始" / "进行到步骤 X"
执行中每完成关键步骤更新进度。先写日志，再执行操作（WAL 原则）。
任务完成后收尾：
重启后恢复：读日志 → 找到未完成任务 → 从断点继续，不问用户"我们之前在做什么"。
阶段 1：任务画像（30 秒内完成）
回答四个问题，写成内部工作笔记（不需要给用户看）：
1. 目标：最终交付什么？（一句话）
2. 规模：多少个子任务 / 多少数据量？
3. 依赖：哪些步骤必须串行？哪些可以并行？
4. 风险：最可能在哪一步翻车？
阶段 2：选择执行策略
根据任务画像选策略（只选一个）：
策略 A：主 session 串行（默认安全策略）
适用：步骤有强依赖、需要上下文连续、搜索密集型任务
做法：
防膨胀措施：
策略 B：分片 + Sub-agent 并行
适用：子任务之间无依赖、每个子任务自包含、不需要大量搜索
做法： 1. 拆分成 N 个独立分片，每片 ≤ 5 个子任务 2. 每个 sub-agent 的 task prompt 必须完全自包含（不依赖主 session 上下文） 3. 设合理超时（参考下方超时指南） 4. sub-agent 结果写入文件（不是回复到主 session）
Sub-agent 任务 prompt 模板：
你的任务：[具体描述]输出要求：
结果写入文件 [路径]（JSON/Markdown 格式）
不要用 message send，把结果写文件即可
如果某个子项失败，记录失败原因继续处理下一个 数据：
[直接给出需要处理的数据，不要说"参考主 session"]
超时指南：
| 子任务类型 | 建议超时 | 说明 | |-----------|---------|------| | 纯计算/文件处理 | 2-3 分钟 | 不涉及外部调用 | | 少量搜索（≤3 次） | 5 分钟 | 搜索 + 处理 | | 中等搜索（4-8 次） | 8 分钟 | 可能遇到慢响应 | | 重搜索（>8 次） | ⚠️ 不建议用 sub-agent | 改用策略 A |
关键防护：
策略 C：分段串行 + 检查点
适用：大批量操作（50+ 项）、需要中途验证、怕断点丢进度
做法：
1. 按批次分段：每段 10-20 个子任务
2. 每段完成后：
- 结果写入检查点文件（JSON/Markdown）
- 汇报进度给用户（已完成 X/Y，成功 A 个失败 B 个）
- 验证结果（抽检 2-3 个）
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：混合编排
适用：任务有多个阶段，不同阶段适合不同策略
做法： 1. 把任务拆成阶段 2. 每个阶段独立选择策略 A/B/C 3. 阶段之间通过文件传递中间结果
示例：
研究 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，而是并发控制的基本原理——跟数据库事务冲突是同一个问题。
核心原则：同一时间，同一资源，只能有一个写入者。
#### 问题全景（不只是飞书文档！）
| 资源类型 | 具体表现 | 根因 | |---------|---------|------| | 飞书文档 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 全量覆盖大文档（同理）
#### 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. 交付验证：抽检确认结果正确
快速参考：策略选择决策树
任务进来
├─ 子任务之间有依赖？ → 策略 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. 控制并发度
agents.defaults.subagents.maxConcurrent 硬限制3. 设计容错的 task prompt
4. 搜索密集任务避开 sub-agent
5. 失败后的恢复流程
Sub-agent 疑似失败：
1. sessions_history 查看它到底做了什么
2. 检查它应该输出的文件是否存在
3. 如果有部分结果 → 从检查点继续
4. 如果完全没结果 → 主 session 接手（别再 spawn 新的去重试同一个任务）
5. 更新检查点文件标记哪些需要补救
未来关注
与其他技能的协作
本技能是编排层，不替代领域技能：