task-coordinator

任务协调器

将 Claude Code 原生 Task 系统集成到工作流编排中的模式。

使用时机

• 工作流包含 3 个或更多需要跟踪进度的顺序步骤
• 并行执行且需要跟踪依赖关系
• 需要从崩溃中恢复的长时间运行工作流
• 需要跨会话持久化状态的工作

配置检查（守卫模式）

TASK_TRACKING = config_read("task_tracking.enabled", "false")
LEDGER_ENABLED = config_read("task_tracking.ledger", "false")
LEDGER_PATH = config_read("task_tracking.ledger_path", ".agents/workflow-ledger.yml")
AUTO_CLEANUP = config_read("task_tracking.auto_cleanup", "true")

If NOT TASK_TRACKING: skip all Task operations, run workflow normally

任务生命周期

1. 创建

TASK = TaskCreate(
  subject: "Imperative verb phrase",     # "Run security review"
  description: "What and why",
  activeForm: "Present continuous form",  # "Running security review"
  metadata: {
    workflow: WORKFLOW_ID,
    step: STEP_NUMBER,
    milestone: true|false,
    phase: "phase-name",
    parallel_group: "group-id"
  }
)

2. 完整步骤模式

If TASK_TRACKING:
  STEP_TASK = TaskCreate(subject: "Step N: Name", activeForm: "Doing name", metadata: {...})
  TaskUpdate(STEP_TASK.id, status: "in_progress")

... existing step logic (unchanged) ...

If TASK_TRACKING:
  TaskUpdate(STEP_TASK.id, status: "completed")

If LEDGER_ENABLED AND step.milestone:
  Write checkpoint -> LEDGER_PATH

元数据约定

键	类型	用途	示例
workflow	string	将任务归入同一次工作流运行	"build-task-abc123"
step	integer	工作流中的步骤编号	4
milestone	boolean	步骤是否触发账本检查点	true
phase	string	多阶段工作流的命名阶段	"discovery"
parallel_group	string	将并行启动的任务归为一组	"reviewers"

工作流 ID 格式："{workflow-name}-{timestamp}"（例如："build-task-20260213T1430"）

依赖关系映射

TASK_A = TaskCreate(subject: "Foundation step", ...)
TASK_B = TaskCreate(subject: "Depends on A", ...)
TaskUpdate(TASK_B.id, addBlockedBy: [TASK_A.id])

规则：

• 先创建所有任务，再设置依赖关系
• 阻塞中的任务在阻塞项完成前无法领取

多阶段示例：

PHASES = [
  {name: "Discovery", deps: []},
  {name: "Architecture", deps: ["Discovery"]},
  {name: "Implementation", deps: ["Architecture"]},
  {name: "Review", deps: ["Implementation"]}
]

PHASE_TASKS = {}
For each P in PHASES:
  PHASE_TASKS[P.name] = TaskCreate(
    subject: "Phase: {P.name}",
    activeForm: "Running {P.name}",
    metadata: {workflow: WORKFLOW_ID, phase: P.name}
  )

For each P in PHASES:
  If P.deps is not empty:
    BLOCKER_IDS = [PHASE_TASKS[d].id for d in P.deps]
    TaskUpdate(PHASE_TASKS[P.name].id, addBlockedBy: BLOCKER_IDS)

并行执行

先创建所有任务，再在一条消息中启动 Task Agent，以实现并行执行。

GROUP_ID = "reviewers-{WORKFLOW_ID}"

REVIEWER_TASKS = []
For each REVIEWER in REVIEWER_LIST:
  T = TaskCreate(
    subject: "Run {REVIEWER}",
    activeForm: "Running {REVIEWER}",
    metadata: {workflow: WORKFLOW_ID, parallel_group: GROUP_ID, reviewer: REVIEWER}
  )
  REVIEWER_TASKS.append(T)

# Launch ALL agents in a SINGLE message (enables parallelism)
For each T in REVIEWER_TASKS:  # all in ONE message
  Task(subagent_type: T.metadata.reviewer, prompt: "...", run_in_background: true)

# Collect results
For each T in REVIEWER_TASKS:
  RESULT = wait for agent completion
  TaskUpdate(T.id, status: "completed")

关键规则： 所有 Task() 调用都必须位于同一条响应消息中。拆分到多条消息会强制按顺序执行。

结果汇总

ALL_TASKS = TaskList()
GROUP_TASKS = [T for T in ALL_TASKS where T.metadata.parallel_group == GROUP_ID]
COMPLETED = [T for T in GROUP_TASKS where T.status == "completed"]
FAILED = [T for T in GROUP_TASKS where T.status != "completed"]

If FAILED is not empty: Handle failures per error table
Else: Aggregate results from COMPLETED tasks

账本检查点模式

基于 YAML 的回执，用于在里程碑步骤中从崩溃中恢复。

架构

version: 1
workflow_id: "build-task-20260213T1430"
workflow_type: "build-task"
started_at: "2026-02-13T14:30:00Z"
last_checkpoint: "2026-02-13T14:35:00Z"
current_step: 4
status: "in_progress"  # in_progress | completed | failed
checkpoints:
  - step: 1
    name: "Workspace setup"
    status: "completed"
    completed_at: "2026-02-13T14:31:00Z"
    data: {}

写入检查点

If LEDGER_ENABLED AND step.milestone:
  CHECKPOINT = {step: STEP_NUMBER, name: STEP_NAME, status: "completed", completed_at: NOW(), data: {...}}
  Read existing ledger from LEDGER_PATH (or create new)
  Append CHECKPOINT to checkpoints array
  Update last_checkpoint, current_step
  Write ledger to LEDGER_PATH

各工作流的里程碑步骤

工作流	里程碑步骤
build-task	工作区设置（1）、构建（4）、验证（5）、质量（7）、交付（9）
blueprint	探索（1）、架构设计（4）、计划编写完成（6）、执行（9）
run-blueprint	创建任务（2）、每项任务完成时
quality-gate	每位审查者完成时、最终结论

从崩溃中恢复

If LEDGER_ENABLED:
  LEDGER = Read LEDGER_PATH
  If LEDGER exists AND LEDGER.status == "in_progress":
    LAST_STEP = LEDGER.current_step
    COMPLETED_STEPS = [C.step for C in LEDGER.checkpoints where C.status == "completed"]
    For each STEP in WORKFLOW_STEPS:
      If STEP.number in COMPLETED_STEPS: skip
      Else: Execute STEP

恢复决策表：

账本状态	操作
无账本文件	全新开始
status: completed	全新开始（上一次运行已完成）
status: in_progress	从上一个检查点恢复
status: failed	从失败步骤恢复
账本解析错误	记录警告，全新开始

跨会话持久化

# At workflow start: export task list ID
TASK_LIST_ID = current task list identifier
Set env: CLAUDE_CODE_TASK_LIST_ID = TASK_LIST_ID

# In new session: restore task list
If env CLAUDE_CODE_TASK_LIST_ID is set:
  Restore task list from CLAUDE_CODE_TASK_LIST_ID
  ALL_TASKS = TaskList()
  Resume from incomplete tasks

注意： 跨会话持久化要求将任务列表 ID 存储在外部（环境变量、文件或账本中）。

清理

If TASK_TRACKING AND workflow completed successfully:
  If AUTO_CLEANUP:
    ALL_TASKS = TaskList()
    WORKFLOW_TASKS = [T for T in ALL_TASKS where T.metadata.workflow == WORKFLOW_ID]
    For each T in WORKFLOW_TASKS:
      TaskUpdate(T.id, status: "completed")

  If LEDGER_ENABLED:
    Update ledger: status = "completed", last_checkpoint = NOW()

错误处理

错误	操作
TaskCreate 失败	记录警告，不跟踪任务并继续
TaskUpdate 失败	重试一次，然后记录并继续
TaskList 超时	如果有账本，则回退到使用账本
TaskGet 返回过时数据	重新获取后再更新
账本写入失败	记录警告，不写入检查点并继续
账本解析错误	记录警告，将其视为全新开始
检测到依赖环	记录错误，移除依赖环并继续

原则： 任务跟踪失败绝不能阻塞工作流执行。始终以平稳降级的方式处理。

状态关系

+---------------------------+     +---------------------------+
|     Native Tasks          |     |     YAML Ledger           |
|  (TaskCreate/Update/List) |     |  (.agents/workflow-ledger) |
+---------------------------+     +---------------------------+
|  Source of truth for:     |     |  Supplementary for:       |
|  - Current step status    |     |  - Crash recovery         |
|  - Dependency tracking    |     |  - Cross-session resume   |
|  - Progress visibility    |     |  - Milestone receipts     |
|  - Parallel coordination  |     |  - Audit trail            |
+---------------------------+     +---------------------------+
         PRIMARY                         SECONDARY

If conflict: Tasks win. Ledger is advisory only.