Skill: xwz119/complex-task-orchestrator (version 1.2.0)

--- 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 原则）。 任务完成后收尾： - 清理过程中产生的临时工作记忆（如 memory_store 中的中间快照） - 日志只保留：做了什么、结果、经验教训 重启后恢复：读日志 → 找到未完成任务 → 从断点继续，不问用户"我们之前在做什么"。 --- ## 阶段 1：任务画像（30 秒内完成） 回答四个问题，写成内部工作笔记（不需要给用户看）： ``` 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 模板**： ``` 你的任务：[具体描述] 输出要求： - 结果写入文件 [路径]（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. 阶段之间通过文件传递中间结果 **示例**： ``` 研究 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 全量覆盖大文档（同理） ``` 实战：铁路行业分析文档（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. **交付验证**：抽检确认结果正确 --- ## 快速参考：策略选择决策树 ``` 任务进来 ├─ 子任务之间有依赖？ → 策略 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 提供输出格式 - **多步骤工程** → 本技能选策略 + 具体领域技能提供专业知识


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)