wonder/cs-note

Fork 0

Files

T

wonder e92c0327d9 vault backup: 2026-06-09 23:15:17

2026-06-09 23:15:17 +08:00

9.2 KiB

Raw Blame History

tags, create time

任务管理系统 - TodoWrite 与 Tasks 双轨架构

概述

Claude Code 的任务管理并非单一系统，而是两个并存的实现：V1 内存 TodoWrite（极简全量替换）和 V2 文件系统 Tasks（支持依赖管理、认领竞争和跨进程持久化）。本文揭示双轨架构的切换逻辑、并发控制和验证推动机制。

正文

双轨架构：TodoWrite V1 与 Tasks V2

Claude Code 的任务管理并非单一系统，而是两个并存、按运行模式切换的实现：

维度	V1: TodoWrite	V2: TaskCreate / TaskUpdate / TaskList / TaskGet
启用条件	非交互式（pipe/SDK）或 `isTodoV2Enabled()` 返回 `false`	交互式 REPL（默认）或 `CLAUDE_CODE_ENABLE_TASKS=1`
存储	内存中 `AppState.todos[sessionId]`（Zustand store）	文件系统 `~/.claude/tasks/<taskListId>/<id>.json`
数据模型	`{content, status, activeForm}` — 扁平三元组	`{id, subject, description, activeForm, owner, status, blocks[], blockedBy[], metadata}` — 完整实体
持久化	进程退出即丢失	跨进程存活，支持多 Agent 并发访问
并发安全	无（单会话单写者）	文件锁 + 高水位标记 + TOCTOU 防护

切换逻辑位于 isTodoV2Enabled()（src/utils/tasks.ts:133）：交互式会话默认启用 V2，SDK/pipe 模式回落 V1。两者互斥——TodoWriteTool.isEnabled 返回 !isTodoV2Enabled()，而 TaskCreateTool.isEnabled 返回 isTodoV2Enabled()。

V1：TodoWrite 的极简设计

TodoWrite 本质是一个全量替换操作——每次调用传入完整的 todos[] 数组，完全覆盖之前的状态：

// packages/builtin-tools/src/tools/TodoWriteTool/TodoWriteTool.ts — call() 核心逻辑
async call({ todos }, context) {
  const todoKey = context.agentId ?? getSessionId()
  const oldTodos = appState.todos[todoKey] ?? []
  const allDone = todos.every(_ => _.status === 'completed')
  const newTodos = allDone ? [] : todos  // 全部完成则清空列表
  // ... 写入 AppState
}

智能清空与验证推动

一个微妙的设计：当所有任务都 completed 时，newTodos 被设为空数组（而非保留 completed 列表）。这确保 UI 上不会有"已完成"的视觉噪音。

此外，V1 包含一个验证推动（verification nudge）机制：当主线程 Agent 完成 3+ 个任务且没有任何一个是验证步骤时，系统在 tool_result 中追加提示，催促 Agent 派生验证子 Agent：

// 条件：主线程 + 全部完成 + ≥3 项 + 无验证任务
if (allDone && todos.length >= 3 && !todos.some(t => /verif/i.test(t.content))) {
  verificationNudgeNeeded = true
}
// tool_result 中追加：
// "NOTE: You just closed out 3+ tasks and none was a verification step..."

[!tip] 防御性设计这是防止 Agent "自说自话地宣布完成"的防御性设计——通过结构性推动而非硬约束。

V2：文件系统持久化的任务系统

数据模型

每个任务是一个独立 JSON 文件，路径为 ~/.claude/tasks/<taskListId>/<id>.json：

// src/utils/tasks.ts — TaskSchema
{
  id: string,           // 自增整数（1, 2, 3...）
  subject: string,      // 祈使句标题（如 "Fix auth bug"）
  description: string,  // 详细描述
  activeForm?: string,  // 进行时形式（如 "Fixing auth bug"），用于 spinner
  owner?: string,       // 认领该任务的 Agent ID/名称
  status: "pending" | "in_progress" | "completed",
  blocks: string[],     // 此任务阻塞哪些任务 ID
  blockedBy: string[],  // 哪些任务 ID 阻塞此任务
  metadata?: Record<string, unknown>  // 任意附加数据
}

任务列表 ID 的解析优先级

getTaskListId() 按 5 级优先级解析任务归属：

CLAUDE_CODE_TASK_LIST_ID 环境变量（显式覆盖）
进程内 teammate 上下文的 teamName（共享 leader 的任务列表）
CLAUDE_CODE_TEAM_NAME 环境变量（进程级 teammate）
Leader 通过 setLeaderTeamName() 设置的 teamName
getSessionId()（独立会话的兜底）

[!info] 多 Agent 共享这意味着多 Agent 团队模式下，所有 teammate 自动共享同一个任务列表，无需额外协调。

ID 分配与高水位标记

任务 ID 是简单的递增整数，但在并发场景下需要防止竞争：

// src/utils/tasks.ts — createTask() 简化
async function createTask(taskListId, taskData) {
  release = await lockfile.lock(lockPath, LOCK_OPTIONS)  // 获取排他锁
  const highestId = await findHighestTaskId(taskListId)   // 读取当前最大 ID
  const id = String(highestId + 1)                        // 递增
  await writeFile(path, JSON.stringify({ id, ...taskData }))
  return id
}

锁配置使用指数退避重试 30 次（总计约 2.6 秒），适配 10+ 并发 Agent 的 swarm 场景。

高水位标记文件 .highwatermark 确保删除任务后 ID 不会被重用——即使任务 #5 被删除，下一个新建任务仍然是 #6。

依赖管理：blocks / blockedBy

任务间的依赖通过双向链表式的 blocks / blockedBy 字段实现：

taskA.blocks = ["3"] 表示 "任务 A 完成前，任务 3 不能开始"
task3.blockedBy = ["A"] 表示 "任务 3 必须等任务 A 完成"

blockTask() 函数同时维护两端：

// src/utils/tasks.ts — blockTask()
// A blocks B → 更新 A.blocks 加入 B，同时更新 B.blockedBy 加入 A
if (!fromTask.blocks.includes(toTaskId)) {
  await updateTask(taskListId, fromTaskId, { blocks: [...fromTask.blocks, toTaskId] })
}
if (!toTask.blockedBy.includes(fromTaskId)) {
  await updateTask(taskListId, toTaskId, { blockedBy: [...toTask.blockedBy, fromTaskId] })
}

删除任务时，系统自动清理所有指向它的依赖引用（deleteTask() 遍历全部任务移除 blocks 和 blockedBy 中的引用）。

任务认领与并发控制

claimTask() 是 V2 的核心并发原语，支持两种锁定粒度：

1. 任务级锁（默认）

仅锁定目标任务文件，适合单 Agent 场景：

getTask → 检查 owner → 检查 status → 检查 blockedBy → 写入 owner

2. 列表级锁 + Agent 忙碌检查

当 checkAgentBusy: true 时，锁定整个任务列表目录（.lock 文件），原子化地完成：

listTasks → 检查任务状态 → 检查依赖 → 检查 Agent 是否已拥有其他未完成任务 → 写入 owner

认领失败有以下原因：

`reason`	含义
`task_not_found`	任务 ID 不存在
`already_claimed`	已被其他 Agent 认领
`already_resolved`	任务已标记 completed
`blocked`	blockedBy 列表中有未完成的任务
`agent_busy`	该 Agent 已拥有其他未完成任务（仅 `checkAgentBusy` 模式）

Agent 团队的任务生命周期

在 swarms 模式下，任务系统的生命周期是这样的：

flowchart TD
    A["Leader 创建团队"] --> B["Leader 用 TaskCreate 创建任务"]
    B --> C["Leader 用 TaskUpdate 设置依赖关系"]
    C --> D["Teammate 调用 TaskList 发现可认领的任务"]
    D --> E["Teammate 调用 TaskUpdate 设置 in_progress"]
    E --> E1["自动设置 owner 为 teammate 名称"]
    E1 --> E2["Leader 通过 mailbox 收到 task_assignment 通知"]
    E2 --> F["Teammate 完成工作"]
    F --> F1["TaskUpdate 设置 completed"]
    F1 --> F2["tool_result 提示调用 TaskList 找下一个任务"]
    F2 --> F3["依赖此任务的其他任务自动解锁"]
    D --> G{"Teammate 异常退出?"}
    G -->|是| H["unassignTeammateTasks()"]
    H --> H1["未完成任务重置为 pending + owner=undefined"]
    H1 --> H2["Leader 收到通知并重新分配"]

Hooks 集成

TaskCreate 和 TaskUpdate 都集成了 hooks 系统：

创建时：executeTaskCreatedHooks — 外部钩子可以阻断任务创建（blockingError 导致任务被立即删除）
完成时：executeTaskCompletedHooks — 外部钩子可以阻断任务标记为完成

这允许外部系统（CI、审批流）参与任务状态机。

activeForm：终端 UX 的细节

每个任务有两个文案字段：

subject：祈使句，用于任务列表展示（"Fix auth bug"）
activeForm：进行时形式，用于 spinner 动画（"Fixing auth bug..."）

当 activeForm 缺省时，spinner 回退显示 subject。这个看似微小的设计确保了用户在等待时看到的是"正在做什么"而非"要做什么"。

Plan Mode 与任务系统的配合

Plan Mode（计划模式）和任务系统是互补但独立的机制：

Plan Mode 限制工具集为只读（搜索、阅读），迫使 AI 先理解再行动
AI 在 Plan Mode 中用 TaskCreate 建立任务列表
用户审批后退出 Plan Mode
AI 按 blockedBy 拓扑序逐项执行，每项用 TaskUpdate 标记进度

[!info] 自动批准 shouldDefer: true 属性确保这些工具调用不会触发权限确认弹窗——任务管理操作始终自动批准，因为它们不产生副作用。

9.2 KiB Raw Blame History Unescape Escape