Daftar Todo
Lacak dan tampilkan todos menggunakan Claude Agent SDK untuk manajemen tugas yang terorganisir
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.
Siklus Hidup Todo
Todos mengikuti siklus hidup yang dapat diprediksi:
- Dibuat sebagai
pendingketika tugas diidentifikasi - Diaktifkan menjadi
in_progressketika pekerjaan dimulai - Diselesaikan ketika tugas selesai dengan sukses
- 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}`);
});
}
}
}
}
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
async for message in 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=ClaudeAgentOptions(max_turns=15, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),
):
# Todo updates are reflected in the message stream
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
todos = block.input["todos"]
print("Todo Status Update:")
for i, todo in enumerate(todos):
status = (
"✅"
if todo["status"] == "completed"
else "🔧"
if todo["status"] == "in_progress"
else "❌"
)
print(f"{i + 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");
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
from typing import List, Dict
class TodoTracker:
def __init__(self):
self.todos: List[Dict] = []
def display_progress(self):
if not self.todos:
return
completed = len([t for t in self.todos if t["status"] == "completed"])
in_progress = len([t for t in self.todos if t["status"] == "in_progress"])
total = len(self.todos)
print(f"\nProgress: {completed}/{total} completed")
print(f"Currently working on: {in_progress} task(s)\n")
for i, todo in enumerate(self.todos):
icon = (
"✅"
if todo["status"] == "completed"
else "🔧"
if todo["status"] == "in_progress"
else "❌"
)
text = (
todo["activeForm"]
if todo["status"] == "in_progress"
else todo["content"]
)
print(f"{i + 1}. {icon} {text}")
async def track_query(self, prompt: str):
async for message in query(
prompt=prompt,
# Re-enable TodoWrite, which this tracker watches for.
options=ClaudeAgentOptions(max_turns=20, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
self.todos = block.input["todos"]
self.display_progress()
# Usage
tracker = TodoTracker()
await tracker.track_query("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. {/* min-version: 2.1.142 */}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 TodoWrite |
Dengan alat Task |
|---|---|
Satu panggilan alat menulis ulang array todos lengkap |
TaskCreate 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 langsung |
Akumulasi 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}`);
}
}
}
from claude_agent_sdk import query, AssistantMessage, ToolUseBlock
async for message in query(
prompt="Optimize my React app performance",
):
if not isinstance(message, AssistantMessage):
continue
for block in message.content:
if not isinstance(block, ToolUseBlock):
continue
if block.name == "TaskCreate":
print(f"+ {block.input['subject']}")
elif block.name == "TaskUpdate" and block.input.get("status"):
print(f" {block.input['taskId']} -> {block.input['status']}")