Subagents任务分配与协调（Task系统）

一、Task系统概述

Task系统是Subagents框架中用于分配、跟踪和协调工作的核心机制。它将复杂的工作负载拆分为独立的任务单元，由多个子代理并行或串行执行，从而实现高效的多代理协作。

核心概念：Task（任务）是分配给子代理（Subagent）执行的最小工作单元。每个Task包含描述、状态、负责人和依赖关系等信息，通过TaskList集中管理。

基本术语

Task（任务）：可分配给子代理执行的工作单元，包含明确的描述、预期输出和状态信息
TaskList（任务列表）：每个Team对应一个独立的TaskList，用于管理该Team的所有任务
Owner（负责人）：当前负责执行该任务的子代理名称
Status（状态）：标识任务当前所处的阶段（pending / in_progress / completed / blocked）
Dependency（依赖关系）：任务之间的前置条件，只有依赖的任务完成后才能开始当前任务

任务状态流转

每个Task在其生命周期中会经历多个状态。子代理通过TaskUpdate工具推动任务状态的流转，主代理和调度器监控全局状态变化。

任务状态流转图:

  pending ──→ in_progress ──→ completed
     ↑              │
     └──────────── blocked

状态	含义	说明
pending	待处理	任务已创建，等待子代理认领
in_progress	进行中	子代理已认领并正在执行
completed	已完成	任务执行完毕，输出结果已提交
blocked	已阻塞	因依赖任务未完成或其他原因暂停

二、TaskCreate创建任务

TaskCreate是用于创建新任务并将其添加到TaskList的工具。主代理或已授权的子代理可以使用它来定义工作单元，设置任务的各项属性。

创建任务的基本流程

调用TaskCreate工具，指定任务名称和详细描述
系统自动为新任务分配唯一的任务ID
新创建的任务默认状态为pending，等待子代理认领
任务被添加到当前Team的TaskList中

任务描述的编写原则

明确性：描述应当清晰说明需要完成什么工作，避免歧义
可衡量性：说明任务完成的验收标准或预期输出
可行性：确保任务范围合理，子代理有能力独立完成
上下文：提供必要的背景信息，帮助子代理理解任务

最佳实践：创建任务时，描述中应包含足够的上下文信息，但不要过度约束实现方式。给予子代理一定的自主权，往往能获得更好的执行效果。

设置任务依赖关系

通过设置依赖关系（dependencies），可以定义任务之间的执行顺序。任务B依赖任务A，意味着只有当任务A的状态变为completed后，任务B才能被执行。这种机制天然支持多阶段的流水线式工作流。

示例：具有依赖关系的任务列表

Task-1: 数据收集 (pending)
Task-2: 数据清洗 (pending) [依赖: Task-1]
Task-3: 数据分析 (pending) [依赖: Task-2]
Task-4: 生成报告 (pending) [依赖: Task-3]

设置任务优先级

优先级机制帮助调度系统决定任务的处理顺序。在资源有限或任务并发的情况下，高优先级的任务会先被分配给空闲的子代理。

高优先级：紧急任务或关键路径上的任务，需要优先处理
普通优先级：常规任务，按创建顺序处理
低优先级：非紧急任务，可在空闲时处理

定义任务预期输出

明确预期输出有助于子代理理解任务的目标，并为后续的验证提供依据。预期输出可以是具体的文件路径、数据结构、或是完成标准描述。

注意：预期输出是任务验收的重要参考。创建任务时清晰地定义预期输出，可以大大减少后续的沟通成本和返工风险。

三、TaskList查看任务

TaskList提供对所有任务的全局视图，是团队协作的"指挥中心"。子代理通过TaskList了解当前的工作状态，发现可以认领的任务。

查看所有任务

通过TaskList视图，可以查看当前Team中所有任务的完整列表，包括每个任务的ID、名称、状态、负责人、依赖关系和创建时间等信息。

示例：TaskList输出

ID          | 名称           | 状态       | 负责人      | 依赖
------------|----------------|------------|-------------|------
TASK-001    | 数据收集       | completed  | agent-alpha | -
TASK-002    | 数据清洗       | in_progress | agent-beta  | TASK-001
TASK-003    | 数据分析       | pending    | -           | TASK-002
TASK-004    | 生成报告       | blocked    | agent-gamma | TASK-003

按状态过滤

可以通过状态过滤快速定位待处理或阻塞的任务。这对于子代理查找可认领的任务非常有用——只需关注status=pending的任务即可。

pending：等待认领的任务，子代理可以主动领取
in_progress：正在执行的任务，了解当前工作负载
completed：已完成的任务，查看历史记录
blocked：被阻塞的任务，需要主代理介入处理

按优先级和负责人过滤

TaskList还支持按优先级和负责人过滤，帮助不同角色快速获取所需信息：

主代理可以查看所有任务的全局状态，识别瓶颈和风险
子代理可以查看分配给自己的任务，管理个人工作队列
按优先级排序，确保重要任务优先得到处理

查看任务详情和依赖

在TaskList中展开单个任务可以查看其详细描述、依赖关系和备注信息。这对于理解任务的上下文和前置条件至关重要。

发现可认领的任务：空闲子代理应定期检查TaskList中状态为pending且依赖已满足的任务。这是子代理主动参与工作的主要方式。

四、TaskUpdate更新任务

TaskUpdate是子代理用于更新任务状态的工具。通过TaskUpdate，子代理可以认领任务、更新进度、标记完成或报告阻塞。

认领任务：设置Owner

当子代理选择一个待处理任务开始执行时，通过TaskUpdate将任务的owner设置为自己的名称。这告诉系统和其他代理："这个任务我来负责"。认领后，任务状态应更新为in_progress。

认领任务示例:
TaskUpdate(
  task_id="TASK-003",
  status="in_progress",
  owner="agent-beta"
)

完成任务：标记completed

子代理完成任务的执行后，通过TaskUpdate将任务状态更新为completed。这表示任务已成功完成，输出结果已就绪。系统会自动检查该任务是否有下游依赖任务，并相应地解除其阻塞状态。

完成任务示例:
TaskUpdate(
  task_id="TASK-003",
  status="completed",
  notes="数据分析完成，结果已保存到 output/analysis.json"
)

更新任务状态

TaskUpdate支持将任务状态更新为以下四种之一：

操作	目标状态	使用场景
认领任务	in_progress	子代理开始执行任务
完成任务	completed	任务执行完毕并提交结果
报告阻塞	blocked	遇到无法解决的问题，需要主代理介入
释放任务	pending	子代理无法继续执行，将任务放回待处理池

添加任务备注和进度说明

在更新任务时，可以通过notes参数添加备注信息。这对于任务交接、进度追踪和问题记录非常有价值。良好的备注习惯可以显著提升团队的协作效率。

建议：每次更新任务状态时都附上简短的备注，说明更新原因、当前进展或遇到的问题。这将帮助主代理和其他子代理了解任务的最新状况。

五、任务调度策略

Subagents框架提供了多种任务调度策略，以适应不同的工作场景和需求。合理的调度策略可以最大化资源利用率，加速整体任务的完成。

按ID顺序优先处理

这是默认的调度策略。系统按照任务创建的顺序（ID递增）来分配任务。较早创建的任务优先被分配给空闲的子代理。这种策略简单直观，适用于大多数线性工作流场景。

适用场景：阶段式工作流、有明确先后顺序的任务集合、初次创建的项目。

依赖任务自动阻塞

当任务之间存在依赖关系时，系统会自动管理阻塞状态。如果任务B依赖任务A，且任务A尚未完成，则任务B会自动被标记为blocked。一旦任务A完成，任务B的状态会自动恢复为pending，等待子代理认领。

依赖阻塞示例:

同时创建3个任务：
  Task-1: 安装开发环境 (pending)
  Task-2: 编写单元测试 (blocked) [依赖: Task-1]
  Task-3: 运行测试并报告 (blocked) [依赖: Task-2]

当 Task-1 完成 → Task-2 自动变为 pending
当 Task-2 完成 → Task-3 自动变为 pending

空闲子代理自动领取未分配任务

当子代理完成当前任务后变为空闲状态，系统会自动为其分配一个pending状态且依赖已满足的任务。这实现了"按需分配"的负载均衡机制，确保所有子代理始终处于工作状态。

空闲子代理自动获取下一个可执行的任务
多个空闲子代理可以并行处理不同任务
系统根据子代理的专长和能力进行智能匹配

主代理强制分配任务

在某些情况下，主代理可能需要直接干预任务的分配过程。主代理可以跳过默认调度策略，直接将特定任务分配给指定的子代理。这在以下场景中特别有用：

任务需要特定领域的专业知识，需分配给最合适的子代理
需要打破默认调度顺序，紧急处理某项任务
需要人工调整工作负载，防止某个子代理过载

注意：主代理的强制分配会覆盖默认调度策略。过度使用可能破坏自动调度机制，建议仅在特殊情况下使用。

调度策略对比

策略	优先级	自动化程度	适用场景
按ID顺序	默认	全自动	线性工作流、项目初始化
依赖阻塞	最高	全自动	有前后置条件的多阶段任务
空闲自动领取	中	全自动	多子代理并行执行
主代理强制分配	可配置	手动	专家任务、紧急插队、负载调整

核心要点总结：Task系统是Subagents框架中实现多代理协作的关键基础设施。通过TaskCreate创建任务、TaskList查看全局状态、TaskUpdate更新进度，结合灵活的任务调度策略，可以高效地组织和管理复杂的多代理工作流程。理解并善用Task系统，是掌握Subagents框架的基石。