Перейти к основному содержанию
Отслеживание задач предоставляет структурированный способ управления задачами и отображения прогресса пользователям. Claude Agent SDK включает встроенную функциональность задач, которая помогает организовать сложные рабочие процессы и держать пользователей в курсе хода выполнения задач.
Начиная с TypeScript Agent SDK 0.3.142 и Claude Code v2.1.142, сеансы используют структурированные инструменты Task TaskCreate, TaskUpdate, TaskGet и TaskList вместо TodoWrite. Смотрите Миграция на инструменты Task для информации о том, как отслеживать изменения кода. Примеры на этой странице устанавливают CLAUDE_CODE_ENABLE_TASKS=0 для продолжения отображения TodoWrite для сеансов, которые еще не перешли на новую версию.

​
Жизненный цикл задач

Задачи следуют предсказуемому жизненному циклу:
  1. Созданы как pending при выявлении задач
  2. Активированы в in_progress при начале работы
  3. Завершены при успешном завершении задачи
  4. Удалены при завершении всех задач в группе

​
Когда используются задачи

SDK автоматически создает задачи для:
  • Сложных многошаговых задач, требующих 3 или более отдельных действий
  • Списков задач, предоставленных пользователем, когда упоминаются несколько элементов
  • Нетривиальных операций, которые выигрывают от отслеживания прогресса
  • Явных запросов, когда пользователи просят организовать задачи

​
Примеры

​
Мониторинг изменений задач

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Optimize my React app performance and track progress with todos",
  // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses
  // Task tools instead and these tool_use blocks never appear.
  options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
})) {
  // Todo updates are reflected in the message stream
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "tool_use" && block.name === "TodoWrite") {
        const todos = block.input.todos;

        console.log("Todo Status Update:");
        todos.forEach((todo, index) => {
          const status =
            todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";
          console.log(`${index + 1}. ${status} ${todo.content}`);
        });
      }
    }
  }
}

​
Отображение прогресса в реальном времени

import { query } from "@anthropic-ai/claude-agent-sdk";

class TodoTracker {
  private todos: any[] = [];

  displayProgress() {
    if (this.todos.length === 0) return;

    const completed = this.todos.filter((t) => t.status === "completed").length;
    const inProgress = this.todos.filter((t) => t.status === "in_progress").length;
    const total = this.todos.length;

    console.log(`\nProgress: ${completed}/${total} completed`);
    console.log(`Currently working on: ${inProgress} task(s)\n`);

    this.todos.forEach((todo, index) => {
      const icon =
        todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";
      const text = todo.status === "in_progress" ? todo.activeForm : todo.content;
      console.log(`${index + 1}. ${icon} ${text}`);
    });
  }

  async trackQuery(prompt: string) {
    for await (const message of query({
      prompt,
      // Re-enable TodoWrite, which this tracker watches for.
      options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
    })) {
      if (message.type === "assistant") {
        for (const block of message.message.content) {
          if (block.type === "tool_use" && block.name === "TodoWrite") {
            this.todos = block.input.todos;
            this.displayProgress();
          }
        }
      }
    }
  }
}

// Usage
const tracker = new TodoTracker();
await tracker.trackQuery("Build a complete authentication system with todos");

​
Миграция на инструменты Task

Инструменты Task разделяют единый вызов TodoWrite на TaskCreate для каждого нового элемента и TaskUpdate для каждого изменения статуса, с TaskList и TaskGet, доступными для модели для чтения текущего списка. Ваш код мониторинга по-прежнему проверяет блоки tool_use в потоке помощника, но поддерживает карту, индексированную по ID задачи, вместо замены всего списка при каждом вызове. Инструменты Task являются стандартными начиная с TypeScript Agent SDK 0.3.142 и Claude Code v2.1.142, поэтому изменение options.env не требуется.
С TodoWriteС инструментами Task
Один вызов инструмента переписывает весь массив todosTaskCreate добавляет один элемент, TaskUpdate исправляет один элемент по taskId
Совпадение block.name === "TodoWrite"Совпадение block.name === "TaskCreate" или "TaskUpdate"
Форма элемента: { content, status, activeForm }Ввод TaskCreate: { subject, description, activeForm?, metadata? }. Ввод TaskUpdate: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status это "pending", "in_progress" или "completed"; установите status: "deleted" для удаления
Отобразить block.input.todos напрямуюНакопить элементы между вызовами или прочитать снимок из результата инструмента TaskList
Назначенный ID задачи отсутствует во вводе TaskCreate. Он возвращается в соответствующем tool_result как { task: { id, subject } }, поэтому захватите его из блока результата, чтобы индексировать вашу карту. Следующий пример показывает минимальное изменение цикла Мониторинг изменений задач. Для отображения полного списка смотрите результат инструмента TaskList в потоке или накопите результаты TaskCreate и вводы TaskUpdate в карту: 
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Optimize my React app performance",
})) {
  if (message.type !== "assistant") continue;
  for (const block of message.message.content) {
    if (block.type !== "tool_use") continue;
    if (block.name === "TaskCreate") {
      const input = block.input as { subject: string };
      console.log(`+ ${input.subject}`);
    } else if (block.name === "TaskUpdate") {
      const input = block.input as { taskId: string; status?: string };
      if (input.status) console.log(`  ${input.taskId} -> ${input.status}`);
    }
  }
}

​
Связанная документация