复杂任务编排器
解决一个核心问题：大任务怎么拆、怎么跑、翻车了怎么救。
决策入口：该不该用这个技能？
收到任务后先过三个判断：
| 条件 | 是 → | 否 → |
|---|
| 步骤 ≥ 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 提供输出格式
- 多步骤工程 → 本技能选策略 + 具体领域技能提供专业知识
