BrainBank
AI 课堂/知识Claude Code Deep Dive

TaskUpdateTool：更新任务

2026/8/2 15:46:42 · 来源

#claude-code#knowledge#tooling#state-machine#task-system#dependency-management

TaskUpdateTool 是 Claude Code 任务系统的主写入口，负责修改任务对象的全部可变字段、推进状态流转并维护依赖关系，是整个任务流的核心状态机引擎。

第 1 段，共 9 段

它是任务系统的主写入口

TaskUpdateTool 负责修改任务对象本身。
如果说 TaskCreateTool 是创建节点，那 TaskUpdateTool 就是任务流真正推进的主干工具。

关键源码

它支持更新的字段非常多：

const inputSchema = z.strictObject({
  taskId: z.string(),
  subject: z.string().optional(),
  description: z.string().optional(),
  activeForm: z.string().optional(),
  status: TaskUpdateStatusSchema.optional(),
  addBlocks: z.array(z.string()).optional(),
  addBlockedBy: z.array(z.string()).optional(),
  owner: z.string().optional(),
  metadata: z.record(z.string(), z.unknown()).optional(),
})

这说明它不只是“改状态”，而是整个任务对象的维护入口。

调用链

模型推进任务或调整依赖 > TaskUpdateTool > 更新 status / owner / metadata / dependency > 必要时触发 hooks 与验证提醒

小结

TaskUpdateTool 是 Claude Code 正式任务系统里最像“状态机推进器”的工具。

学习地图

🗺️ TaskUpdateTool 学习路线

🟢 阶段一：理解上下文

  1. 回顾 Claude Code 的任务系统整体架构
  2. 了解 TaskCreateTool（创建节点）与 TaskUpdateTool（推进主链）的职责分工
  3. 明确「任务即有向无环图」的基本思想

🔵 阶段二：掌握字段能力

  1. 逐一理解 inputSchema 中每个字段的含义与作用
    • subject / description — 描述更新
    • activeForm — 激活形式的切换
    • status — 状态机推进（核心）
    • addBlocks / addBlockedBy — 依赖增减
    • owner / metadata — 归属与扩展信息
  2. 区分 TaskUpdateTool 与 TaskCreateTool 的能力边界

🟡 阶段三：跟踪调用链

  1. 理解触发流程：模型推理 → 调整依赖/状态 → TaskUpdateTool → hooks & 验证提醒
  2. 学习任务状态的合法流转路径（哪些状态可互转）
  3. 了解 metadata 自定义扩展的最佳实践

🟠 阶段四：实战与排查

  1. 实际调用 TaskUpdateTool 更新任务状态
  2. 添加/移除任务间的阻塞依赖，验证 DCR 是否正确执行
  3. 在 metadata 中记录任务决策日志

动手实践——分步指南

Step 1：查看当前任务列表

先运行 Claude Code（或你使用的工具环境），列出已有任务清单，确认要更新的 taskId。

Step 2：调用 TaskUpdateTool — 修改状态

使用 TaskUpdateTool，传入目标 taskId 和 status 字段：

  • taskId: "<你的任务ID>"
  • status: "In Progress"（或其他合法状态） 观察状态变更是否成功。

Step 3：调用 TaskUpdateTool — 增删依赖

通过 addBlockedBy 字段添加依赖项（数组），将当前任务标记为被上游阻塞，或向下游传递：

  • taskId: "<你的任务ID>"
  • addBlockedBy: ["上游任务1", "上游任务2"]

Step 4：调用 TaskUpdateTool — 更新描述与归属

一次性修改多项内容。例如同时更新描述、负责人和元数据：

  • taskId: "<你的任务ID>"
  • description: "更新后的任务描述"
  • owner: "<新负责人ID>"
  • metadata: {"updatedBy": "手动", "reason": "需求变更"}

Step 5：验证调用链触发结果

  1. 确认 hooks 是否被正确触发（查看日志或通知）
  2. 检查依赖提醒是否按预期执行
  3. 用列表命令确认最终状态、依赖关系和 owner 均与预期一致

三大推荐资源

  1. 1
    Claude Code Tasks 官方文档

    Claude Code 任务系统的官方参考，包含 TaskUpdateTool 在内的所有任务管理工具的使用说明。

    https://docs.anthropic.com/en/docs/claude-code/tasks

  2. 2
    Anthropic Claude Code GitHub

    Claude Code 开源仓库，可查看所有工具的源码实现与 TaskUpdateTool 的输入 Schema。

    https://github.com/anthropics/claude-code

  3. 3
    Task-Oriented AI Workflow Patterns

    Anthropic 官方提示库与教程，涵盖任务流编排、状态管理与多工具协作的最佳实践。

    https://docs.anthropic.com/en/docs/claude-code/prompt-library

链接由 AI 推荐——使用前建议快速核实。