Langsung ke konten utama
Pelacakan todo menyediakan cara terstruktur untuk mengelola tugas dan menampilkan kemajuan kepada pengguna. Claude Agent SDK mencakup fungsionalitas todo bawaan yang membantu mengorganisir alur kerja yang kompleks dan membuat pengguna tetap terinformasi tentang perkembangan tugas.
Mulai dari TypeScript Agent SDK 0.3.142 dan Claude Code v2.1.142, sesi menggunakan alat Task terstruktur TaskCreate, TaskUpdate, TaskGet, dan TaskList sebagai pengganti TodoWrite. Lihat Migrasi ke alat Task untuk cara memantau perubahan kode. Contoh di halaman ini menetapkan CLAUDE_CODE_ENABLE_TASKS=0 untuk terus menampilkan TodoWrite untuk sesi yang belum bermigrasi.

​
Siklus Hidup Todo

Todos mengikuti siklus hidup yang dapat diprediksi:
  1. Dibuat sebagai pending ketika tugas diidentifikasi
  2. Diaktifkan menjadi in_progress ketika pekerjaan dimulai
  3. Diselesaikan ketika tugas selesai dengan sukses
  4. Dihapus ketika semua tugas dalam grup selesai

​
Kapan Todos Digunakan

SDK secara otomatis membuat todos untuk:
  • Tugas multi-langkah yang kompleks memerlukan 3 atau lebih tindakan yang berbeda
  • Daftar tugas yang disediakan pengguna ketika beberapa item disebutkan
  • Operasi non-trivial yang mendapat manfaat dari pelacakan kemajuan
  • Permintaan eksplisit ketika pengguna meminta organisasi todo

​
Contoh

​
Memantau Perubahan Todo

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}`);
        });
      }
    }
  }
}

​
Tampilan Kemajuan Real-time

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");

​
Migrasi ke alat Task

Alat Task membagi panggilan TodoWrite tunggal menjadi TaskCreate untuk setiap item baru dan TaskUpdate untuk setiap perubahan status, dengan TaskList dan TaskGet tersedia untuk model membaca kembali daftar saat ini. Kode pemantauan Anda masih memeriksa blok tool_use dalam aliran asisten, tetapi mempertahankan peta yang dikunci berdasarkan ID tugas alih-alih mengganti seluruh daftar pada setiap panggilan. Alat Task adalah default mulai dari TypeScript Agent SDK 0.3.142 dan Claude Code v2.1.142, jadi tidak ada perubahan options.env yang diperlukan.
Dengan TodoWriteDengan alat Task
Satu panggilan alat menulis ulang array todos lengkapTaskCreate menambahkan satu item, TaskUpdate menambal satu item berdasarkan taskId
Cocokkan block.name === "TodoWrite"Cocokkan block.name === "TaskCreate" atau "TaskUpdate"
Bentuk item: { content, status, activeForm }Input TaskCreate: { subject, description, activeForm?, metadata? }. Input TaskUpdate: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status adalah "pending", "in_progress", atau "completed"; atur status: "deleted" untuk menghapus
Render block.input.todos secara langsungAkumulasi item di seluruh panggilan, atau baca snapshot dari hasil alat TaskList
ID tugas yang ditugaskan tidak ada dalam input TaskCreate. Ini kembali dalam tool_result yang cocok sebagai { task: { id, subject } }, jadi tangkap dari blok hasil untuk mengunci peta Anda. Contoh berikut menunjukkan perubahan minimal ke loop Memantau Perubahan Todo. Untuk merender daftar lengkap, pantau hasil alat TaskList dalam aliran atau akumulasi hasil TaskCreate dan input TaskUpdate ke dalam peta: 
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}`);
    }
  }
}

​
Dokumentasi Terkait