跳到主要内容

TaskCreateTool / TaskGetTool 等：任务管理工具集解析

🟡 进阶

Claude Code 提供了一套完整的任务管理工具（Task Management Tools），让 AI 能够像项目管理系统一样创建、追踪、更新和协作完成工作项。这套工具在 Swarm 协作模式下尤为重要——多个 AI 队友通过共享任务列表来协调工作分工。

注意：这里讨论的"任务管理工具"（TaskCreate、TaskGet 等）是用于管理**工作项（to-do items）**的工具，与上文讨论的 TaskType（LocalAgentTask 等后台任务）是不同层次的概念。前者是 AI 的项目管理工具，后者是 AI 的任务调度系统。

工具集全览​

工具名称功能是否只读是否并发安全
TaskCreate创建新工作项否是
TaskGet按 ID 获取工作项详情是是
TaskList列出所有工作项是是
TaskUpdate更新工作项（状态、所有者等）否是
TaskStop停止正在运行的后台任务否是
TaskOutput读取后台任务的输出是是

所有工具都通过 isTodoV2Enabled() 检查是否启用——这些工具属于 "TodoV2" 功能系统（区别于早期的 TodoWriteTool）。

TaskCreate：创建工作项​

功能​

在当前会话的任务列表中创建一个新工作项。

参数​

{
  subject: string        // 简短的任务标题（命令式形式，如 "Fix authentication bug"）
  description: string    // 任务详细描述（做什么、为什么、怎么做）
  activeForm?: string    // 进行时形式（如 "Fixing authentication bug"）
                         // 显示在任务运行时的 spinner 中
  metadata?: Record<string, unknown>  // 任意元数据（附加信息）
}

返回值​

{
  task: {
    id: string     // 分配的任务 ID（如 "1"、"2"...）
    subject: string
  }
}

实际使用示例​

// AI 调用 TaskCreate
{
  "subject": "Run full test suite",
  "description": "Execute all unit tests and integration tests, ensure all pass before proceeding",
  "activeForm": "Running tests"
}

// 返回
"Task #3 created successfully: Run full test suite"

设计细节​

  • 所有工作项默认以 pending 状态创建
  • shouldDefer: true——这个工具调用会触发"延迟"模式（UI 上折叠显示，不展开细节）
  • 创建工作项时自动展开任务列表面板（expandedView: 'tasks'）
  • 在 Swarm 模式下，描述需要包含足够细节，让被分配的队友能够独立理解并完成

生命周期钩子​

创建工作项时，会触发 TaskCreated 钩子：

const generator = executeTaskCreatedHooks(taskId, subject, description, ...)
for await (const result of generator) {
  if (result.blockingError) {
    // 钩子返回错误时，回滚任务创建
    await deleteTask(getTaskListId(), taskId)
    throw new Error(blockingErrors.join('\n'))
  }
}

这允许外部系统（通过 sessionHooks 配置）在工作项创建时执行自定义验证。

TaskGet：获取工作项详情​

功能​

通过 ID 获取单个工作项的完整信息。

参数​

{
  taskId: string  // 要获取的工作项 ID
}

返回值​

{
  task: {
    id: string
    subject: string
    description: string   // 完整描述
    status: 'pending' | 'in_progress' | 'completed'
    blocks: string[]      // 这个任务阻塞的其他任务 ID
    blockedBy: string[]   // 阻塞这个任务的任务 ID
  } | null  // null 表示任务不存在
}

使用场景​

  • 开始处理任务前，获取完整描述（TaskList 只显示摘要）
  • 检查 blockedBy 是否为空，确认可以开始工作
  • 在 Swarm 模式下，队友被分配任务后读取详细说明

TaskList：列出所有工作项​

功能​

列出当前会话的所有工作项（支持过滤）。

参数​

无（空对象 {}）

返回值​

{
  tasks: Array<{
    id: string
    subject: string
    status: 'pending' | 'in_progress' | 'completed'
    owner?: string      // 负责该任务的 Agent 名称
    blockedBy: string[] // 阻塞依赖（已完成的依赖不包含在内）
  }>
}

格式化输出示例：

#1 [completed] 分析代码库结构
#2 [in_progress] 修复 auth 模块空指针 (researcher)
#3 [pending] 编写单元测试 [blocked by #2]
#4 [pending] 更新文档

Swarm 模式下的队友工作流​

在多 AI 协作时，队友使用 TaskList 来找到可以认领的工作：

  1. 完成当前任务后，调用 TaskList 查看可用工作
  2. 找状态为 pending、无 owner、blockedBy 为空的任务
  3. 优先选择 ID 较小的任务（早期任务通常为后续任务建立上下文）
  4. 通过 TaskUpdate 认领任务（设置 owner 为自己的名字）
  5. 如果任务被阻塞，寻找可以解除阻塞的工作，或通知 Leader

TaskUpdate：更新工作项​

这是最复杂的任务管理工具，支持多种类型的更新。

参数​

{
  taskId: string

  // 状态更新
  status?: 'pending' | 'in_progress' | 'completed' | 'deleted'
  // 注意：'deleted' 会永久删除工作项（不同于普通状态转换）

  // 基本字段更新
  subject?: string
  description?: string
  activeForm?: string

  // 所有权
  owner?: string         // 分配给哪个 Agent

  // 依赖关系
  addBlocks?: string[]   // 这个任务阻塞哪些任务（追加，不替换）
  addBlockedBy?: string[] // 哪些任务阻塞这个任务（追加，不替换）

  // 元数据
  metadata?: Record<string, unknown>  // null 值会删除对应 key
}

状态工作流​

pending → in_progress → completed
          ↕
        (任何状态) → deleted（永久删除）

Swarm 模式下的自动认领​

当队友将任务状态改为 in_progress 时，如果没有指定 owner，系统会自动将当前 Agent 名称设为 owner：

// TaskUpdateTool.ts
if (
  isAgentSwarmsEnabled() &&
  status === 'in_progress' &&
  owner === undefined &&
  !existingTask.owner
) {
  const agentName = getAgentName()
  if (agentName) {
    updates.owner = agentName  // 自动认领
  }
}

邮箱通知​

当任务被分配给新 owner 时，系统自动向新 owner 发送邮箱消息（Swarm 模式）：

const assignmentMessage = JSON.stringify({
  type: 'task_assignment',
  taskId,
  subject: existingTask.subject,
  description: existingTask.description,
  assignedBy: senderName,
  timestamp: new Date().toISOString(),
})
await writeToMailbox(updates.owner, { from: senderName, text: assignmentMessage, ... })

完成验证钩子​

将任务标记为 completed 时，触发 TaskCompleted 钩子：

const generator = executeTaskCompletedHooks(taskId, subject, description, ...)
// 如果钩子返回错误，任务不会被标记为完成

验证提醒（Verification Nudge）​

当主代理完成一个包含 3+ 任务的会话，且没有任何任务涉及验证时，工具会在结果中附上提醒：

NOTE: You just closed out 3+ tasks and none of them was a verification step.
Before writing your final summary, spawn the verification agent (subagent_type="verification").
You cannot self-assign PARTIAL by listing caveats — only the verifier issues a verdict.

这是一个设计精妙的"强制验证"机制——通过工具输出的提示文字，引导 AI 在没有做验证的情况下不要直接宣告任务完成。

TaskStop：停止后台任务​

功能​

停止一个正在运行的后台任务（local_bash、local_agent、remote_agent 等）。

参数​

{
  task_id?: string   // 要停止的任务 ID（如 "b3f8k2m9"）
  shell_id?: string  // 已废弃，向后兼容 KillShell 工具
}

验证逻辑​

// 调用前先验证
if (!task) {
  return { result: false, message: `No task found with ID: ${id}` }
}
if (task.status !== 'running') {
  return { result: false, message: `Task ${id} is not running (status: ${task.status})` }
}

只有状态为 running 的任务才能被停止。

向后兼容​

TaskStop 有一个别名 KillShell，保持与旧版 API 的兼容性：

aliases: ['KillShell'],

TaskOutput：读取任务输出​

功能​

读取后台任务（shell 命令、子代理）的输出内容。

参数​

{
  task_id: string           // 任务 ID
  block: boolean = true     // 是否等待任务完成
  timeout: number = 30000   // 最长等待时间（毫秒，最大 600000 = 10 分钟）
}

工作模式​

  • block: true（默认）：等待任务完成，返回完整输出。如果超时，返回 retrieval_status: 'timeout' 和当前已有输出
  • block: false：立即返回当前已有的部分输出（retrieval_status: 'not_ready' 或 'success'）

AI 如何管理异步任务的完整示例​

以下是 AI 通过任务管理工具执行并行工作的完整示例：

[1] AI 创建多个工作项

TaskCreate({ subject: "分析认证模块", description: "..." })
→ 返回: task #1

TaskCreate({ subject: "调查相关测试", description: "..." })
→ 返回: task #2

TaskCreate({ subject: "修复空指针", description: "...", addBlockedBy: ["1", "2"] })
→ 返回: task #3 [blocked by #1, #2]

[2] AI 启动并行子代理

Agent({ prompt: "分析认证模块，完成后更新 task #1 状态", task_id: "1" })
→ 返回: 子代理 a3f8k2m9

Agent({ prompt: "调查测试覆盖，完成后更新 task #2 状态", task_id: "2" })
→ 返回: 子代理 a9x2p7q1

[3] 收到子代理通知后更新任务

[<task-notification> from a3f8k2m9: completed]
TaskUpdate({ taskId: "1", status: "completed" })

[<task-notification> from a9x2p7q1: completed]
TaskUpdate({ taskId: "2", status: "completed" })

[4] 任务 #3 依赖已解除，开始执行

TaskList()
→ #3 [pending] 修复空指针（依赖已清空）

TaskUpdate({ taskId: "3", status: "in_progress" })
Agent({ prompt: "修复 src/auth/validate.ts:42 的空指针..." })

任务 ID 与状态查询​

任务 ID 是会话内的递增整数（"1"、"2"、"3"...），与后台任务的 UUID 格式（"b3f8k2m9"）完全不同。这两套 ID 系统服务于不同目的：

  • 工作项 ID（"1"、"2"）：短且易读，适合 AI 和用户在对话中引用
  • 后台任务 ID（"b3f8k2m9"）：带类型前缀的随机 ID，适合系统内部追踪

小结​

Claude Code 的任务管理工具集构成了一个完整的项目管理层：TaskCreate 定义工作、TaskList 追踪进度、TaskGet 获取详情、TaskUpdate 更新状态和分配所有权、TaskStop 中止后台操作、TaskOutput 读取执行结果。在 Swarm 多 AI 协作模式下，这套工具让多个 AI 实例能够像真正的工程团队一样分工合作、自动协调。

📄source/src/tools/TaskCreateTool/TaskCreateTool.tsL1-139查看源码 →
📄source/src/tools/TaskGetTool/TaskGetTool.tsL1-129查看源码 →
📄source/src/tools/TaskUpdateTool/TaskUpdateTool.tsL1-406查看源码 →
📄source/src/tools/TaskListTool/TaskListTool.tsL1-116查看源码 →
📄source/src/tools/TaskStopTool/TaskStopTool.tsL1-131查看源码 →