long-task-coordinator

长任务协调器

让长时间运行的工作可恢复、有状态且如实透明。

何时使用此技能

在以下情况下使用此技能：

• 工作跨越多个回合或多个会话
• 涉及向工作者、子 Agent 或后台任务移交工作
• 需要明确的等待状态，而不是“仍在查找”之类的更新
• 必须通过持久状态文件承受中断并恢复

小型、单回合任务无需使用此技能。简单规划足够且恢复逻辑并非主要关注点时，请使用 planning-with-files。

相关技能

• planning-with-files 用文件整理多步骤工作。
• workflow-orchestrator 在里程碑之后串联后续技能。
• long-task-coordinator 让长时间运行的工作可恢复、可审计且便于安全移交。

核心规则

1. 创建唯一事实来源

对于任何真正的长任务，都应维护一个持久状态文件。聊天记录不是可靠的状态存储。

状态文件至少应记录：

• 目标
• 成功标准
• 当前状态
• 当前步骤
• 已完成的工作
• 下一步行动
• 下一个检查点
• 阻碍因素
• 当前负责者或工作者

2. 仅在需要时拆分角色

使用适合任务的最精简角色模型：

• 发起方：负责目标和验收标准
• 协调者：负责状态、排序和恢复
• 工作者：执行范围明确的子任务
• 看门狗：仅检查运行状态和恢复情况

简单任务可以由一个 Agent 承担所有角色。对于长任务或委派任务，应明确划分角色。

3. 按以下顺序运行每个周期

对于每轮协调：

READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END

在更新状态文件之前，不要报告结论。

4. 将 awaiting-result 视为有效状态

如果工作者或后台任务已成功派发，仅仅因为结果尚未返回，并不意味着任务失败。

有效的状态转换包括：

• running -> awaiting-result
• awaiting-result -> running
• running -> paused
• running -> complete

5. 非终止轮次必须取得实际进展

协调轮次只有在至少完成以下一项时才有效：

• 派发范围明确的工作
• 处理新结果
• 更新当前阶段或决策
• 保存新的后续步骤或检查点
• 执行明确的恢复操作

如果没有任何变化，就不要假装任务取得了进展。

6. 将恢复与领域工作分开

恢复要回答：

• 执行是否偏离了已保存的状态？
• 预期的工作者结果是否仍在等待中？
• 是否需要等待、重试或重新派发？

领域工作要回答：

• 接下来应该构建、分析或交付什么？

先恢复，再继续领域工作。

操作工作流

步骤 1：判断任务是否需要协调

符合以下任一条件时，使用此技能：

• 任务会延续到当前回合之后
• 任务会将工作移交给另一个执行单元
• 任务需要检查点、轮询或定时跟进
• 任务足够复杂，丢失状态会造成较大代价

步骤 2：创建或加载状态文件

优先选择易于重新找到的路径，例如：

• docs/<topic>-execution-plan.md
• docs/<topic>-state.md
• worklog/<topic>-state.md

如果尚无持久状态，请根据 references/workflow.md 创建一个。

步骤 3：先恢复，再采取行动

每轮开始时：

1. 读取状态文件
2. 检查记录的下一步是否仍然合理
3. 确认是否有委派的工作已返回结果
4. 在采取新行动之前，修正过时的假设

步骤 4：先保存，再报告

决定下一步行动后：

1. 更新状态文件
2. 记录新的状态、负责人、阻碍因素和检查点
3. 之后再向用户或调用方报告进展

步骤 5：如实结束本轮

每轮结束时，应处于以下某个状态：

• running
• awaiting-result
• paused
• blocked
• complete

报告的状态应与已保存的状态完全一致。

输出预期

使用此技能时，更新内容应以已保存的状态为依据：

• 任务当前处于什么状态
• 本轮有哪些变更
• 下一步预期是什么
• 哪些事项可以解除阻塞或完成任务

验收标准

只有以下所有相关条件均满足时，才将协调工作视为已完成：

• 在可预测的路径中存在持久化状态文件
• 保存的状态与任务的实际状态一致
• 明确记录已完成的工作、下一步操作和阻塞事项
• 任何委派的工作都有明确的负责人和返回条件
• 最终报告依据持久化状态生成，而非临时推理

如果任务尚未真正完成，请以 running、awaiting-result、paused 或 blocked 结束，而不要假装任务已完成

反模式

避免：

• 不查看状态文件，而凭记忆还原进度
• 保存之前就报告结论
• 将等待标记为失败
• 一轮结束时既没有采取新行动，也没有更新状态
• 在一个模糊步骤中混合恢复检查与领域决策

参考资料

• references/workflow.md - 详细工作流、状态模板和恢复检查清单