SpyBara
Go Premium

agent-sdk/todo-tracking.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

21 added, 7 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

待办事项列表

使用 Claude Agent SDK 跟踪和显示待办事项,实现有组织的任务管理

待办事项跟踪提供了一种结构化的方式来管理任务并向用户显示进度。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: "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(用于每个状态更改),TaskListTaskGet 可供模型读取当前列表。您的监控代码仍然检查助手流中的 tool_use 块,但维护一个由任务 ID 键入的映射,而不是在每次调用时替换整个列表。{/* min-version: 2.1.142 */}Task 工具是 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 的默认工具,因此不需要更改 options.env

使用 TodoWrite 使用 Task 工具
一个工具调用重写完整的 todos 数组 TaskCreate 添加一个项目,TaskUpdatetaskId 修补一个项目
匹配 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}`);
}
}
}