待辦事項追蹤提供了一種結構化的方式來管理任務並向用戶顯示進度。Claude Agent SDK 包含內建的待辦事項功能，有助於組織複雜的工作流程並讓用戶了解任務進展。

​
待辦事項生命週期

待辦事項遵循可預測的生命週期：
  1. 建立為 pending 狀態，當任務被識別時
  2. 啟動為 in_progress 狀態，當工作開始時
  3. 完成當任務成功完成時
  4. 移除當群組中的所有任務都完成時

​
何時使用待辦事項

SDK 會自動為以下情況建立待辦事項：
  • 複雜的多步驟任務需要 3 個或更多不同的操作
  • 用戶提供的任務清單當提到多個項目時
  • 非平凡的操作受益於進度追蹤
  • 明確請求當用戶要求待辦事項組織時

​
範例

​
監控待辦事項變更

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

for await (const message of query({
  prompt: "優化我的 React 應用程式效能並使用待辦事項追蹤進度",
  options: { maxTurns: 15 }
})) {
  // 待辦事項更新會反映在訊息串流中
  if (message.type === "tool_use" && message.name === "TodoWrite") {
    const todos = message.input.todos;
    
    console.log("待辦事項狀態更新：");
    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(`\n進度：${completed}/${total} 已完成`);
    console.log(`目前正在處理：${inProgress} 個任務\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,
      options: { maxTurns: 20 }
    })) {
      if (message.type === "tool_use" && message.name === "TodoWrite") {
        this.todos = message.input.todos;
        this.displayProgress();
      }
    }
  }
}

// 使用方式
const tracker = new TodoTracker();
await tracker.trackQuery("建立完整的身份驗證系統並使用待辦事項");

​
相關文件