From 79baf14a8f32e726a33ab8758a20a925cfd6c716 Mon Sep 17 00:00:00 2001 From: claude-code-best Date: Mon, 20 Apr 2026 10:51:23 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=E4=BB=BB=E5=8A=A1?= =?UTF-8?q?=E7=AE=A1=E7=90=86=EF=BC=8C=E4=BB=8E=E6=BA=90=E7=A0=81=E8=A7=A3?= =?UTF-8?q?=E5=89=96=E6=94=B9=E4=B8=BA=E5=8F=8C=E8=BD=A8=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E5=88=86=E6=9E=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 移除 TypeScript 代码和源码路径， 聚焦 V1/V2 双轨的设计权衡、验证推动的阈值考量、 双向依赖的查询优化和多 Agent 认领的并发控制。 Co-Authored-By: Claude Opus 4.6 --- docs/tools/task-management.mdx | 237 ++++++++++----------------------- 1 file changed, 69 insertions(+), 168 deletions(-) diff --git a/docs/tools/task-management.mdx b/docs/tools/task-management.mdx index 372eeb19b..8d0444c26 100644 --- a/docs/tools/task-management.mdx +++ b/docs/tools/task-management.mdx @@ -1,212 +1,113 @@ --- -title: "任务管理系统 - TodoWrite 与 Tasks 双轨架构" -description: "揭秘 Claude Code 任务管理系统的双轨架构：V1 内存 TodoWrite 与 V2 文件系统 Tasks，包含依赖管理、认领竞争和验证推动机制。" +title: "任务管理" +description: "任务追踪是 AI 自我管理的关键。理解双轨架构（V1 内存 / V2 文件系统）、依赖管理、认领竞争和验证推动的设计。" keywords: ["任务管理", "TodoWrite", "任务队列", "依赖管理", "多任务"] --- -{/* 本章目标：揭示任务系统 V1（内存 TodoWrite）和 V2（文件系统 Task*）的双轨架构，以及依赖管理、认领竞争、验证推动的工程细节 */} +## 核心问题 -## 双轨架构：TodoWrite V1 与 Tasks V2 +复杂任务需要分解为多个步骤。没有任务追踪，AI 容易"迷失"——做了第三步忘了第二步，或者跳过关键验证直接宣布完成。 -Claude Code 的任务管理并非单一系统，而是两个并存、按运行模式切换的实现： +任务系统让 AI 能规划、追踪和汇报自己的工作进度。 -| 维度 | V1: TodoWrite | V2: TaskCreate / TaskUpdate / TaskList / TaskGet | -|------|--------------|--------------------------------------------------| -| **启用条件** | 非交互式（pipe/SDK）或 `isTodoV2Enabled()` 返回 `false` | 交互式 REPL（默认）或 `CLAUDE_CODE_ENABLE_TASKS=1` | -| **存储** | 内存中 `AppState.todos[sessionId]`（Zustand store） | 文件系统 `~/.claude/tasks//.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()`。 +Claude Code 有两个并存的任务系统，按运行模式自动切换： + +| 维度 | V1: TodoWrite | V2: TaskCreate/TaskUpdate | +|------|:------------:|:------------------------:| +| **存储** | 内存（进程退出即丢失） | 文件系统（跨进程持久化） | +| **适用** | 非交互式（pipe/SDK） | 交互式 REPL（默认） | +| **数据** | 扁平三元组 | 完整实体（含依赖、认领） | +| **并发** | 无（单会话） | 文件锁 + 高水位标记 | + +**设计考量**：V1 追求极简——pipe 模式是一次性执行，不需要持久化。V2 追求可靠——交互式会话和多 Agent 团队需要任务在进程崩溃后仍能恢复。 ## V1：TodoWrite 的极简设计 -TodoWrite 本质是一个**全量替换**操作——每次调用传入完整的 `todos[]` 数组，完全覆盖之前的状态： +V1 本质是一个全量替换操作——每次调用传入完整的任务列表，完全覆盖之前的状态。 -```typescript -// 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 -} -``` +### 智能清空 -### 智能清空与验证推动 +当所有任务都完成时，列表被自动清空。这确保 UI 上不会有"已完成"的视觉噪音。 -一个微妙的设计：当所有任务都 `completed` 时，`newTodos` 被设为空数组（而非保留 `completed` 列表）。这确保 UI 上不会有"已完成"的视觉噪音。 +### 验证推动（Verification Nudge） -此外，V1 包含一个**验证推动**（verification nudge）机制：当主线程 Agent 完成 3+ 个任务且没有任何一个是验证步骤时，系统在 tool_result 中追加提示，催促 Agent 派生验证子 Agent： +当 AI 完成了 3+ 个任务且没有任何一个是验证步骤时，系统追加提示催促 AI 派生验证子 Agent。 -```typescript -// 条件：主线程 + 全部完成 + ≥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..." -``` +**设计洞察**：这是防止 AI "自说自话地宣布完成"的防御性设计。它不是硬约束（AI 可以忽略），而是结构性推动——通过在合适的时机插入提醒，让 AI 自己决定是否验证。 -这是防止 Agent "自说自话地宣布完成"的防御性设计——通过结构性推动而非硬约束。 +为什么是 3 个任务？太少的阈值会产生过多噪音，太多则会让 AI 在完成大量工作后才被提醒验证，错过了早期发现问题的机会。 -## V2：文件系统持久化的任务系统 +## V2：文件系统持久化 ### 数据模型 -每个任务是一个独立 JSON 文件，路径为 `~/.claude/tasks//.json`： +每个任务是一个独立的 JSON 文件，包含： +- **subject**：祈使句标题（"Fix auth bug"） +- **activeForm**：进行时形式（"Fixing auth bug"），用于 spinner +- **status**：pending → in_progress → completed +- **owner**：认领该任务的 Agent +- **blocks / blockedBy**：任务间依赖 -```typescript -// 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 // 任意附加数据 -} -``` +### ID 分配的安全保证 -### 任务列表 ID 的解析优先级 +任务 ID 是递增整数，但在并发场景下需要防止竞争： +- 使用排他锁防止两个 Agent 同时创建相同 ID +- 高水位标记确保删除任务后 ID 不会被重用 -`getTaskListId()` 按 5 级优先级解析任务归属： - -1. `CLAUDE_CODE_TASK_LIST_ID` 环境变量（显式覆盖） -2. 进程内 teammate 上下文的 teamName（共享 leader 的任务列表） -3. `CLAUDE_CODE_TEAM_NAME` 环境变量（进程级 teammate） -4. Leader 通过 `setLeaderTeamName()` 设置的 teamName -5. `getSessionId()`（独立会话的兜底） - -这意味着多 Agent 团队模式下，所有 teammate 自动共享同一个任务列表，无需额外协调。 - -### ID 分配与高水位标记 - -任务 ID 是简单的递增整数，但在并发场景下需要防止竞争： - -```typescript -// 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。 +**设计考量**：为什么不使用 UUID？整数 ID 更直观（"任务 3 阻塞任务 5"比"任务 a3f2 阻塞任务 b7c1"更易读）。但在并发环境下需要额外的工作来保证唯一性。 ## 依赖管理：blocks / blockedBy -任务间的依赖通过双向链表式的 `blocks` / `blockedBy` 字段实现： +任务间的依赖通过双向字段实现： +- `taskA.blocks = ["3"]` — 任务 A 完成前，任务 3 不能开始 +- `task3.blockedBy = ["A"]` — 任务 3 必须等任务 A 完成 -- `taskA.blocks = ["3"]` 表示 "任务 A 完成前，任务 3 不能开始" -- `task3.blockedBy = ["A"]` 表示 "任务 3 必须等任务 A 完成" +两端同时维护，删除任务时自动清理所有引用。 -`blockTask()` 函数同时维护两端： +**为什么是双向而非单向**？因为两个方向的查询都很常见： +- "任务 A 阻塞了谁？" → 读 `blocks` +- "任务 3 在等谁？" → 读 `blockedBy` -```typescript -// 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 的核心并发原语，支持两种锁定粒度： +多个 Agent 可能同时想认领同一个任务。系统提供两种锁定粒度： -### 1. 任务级锁（默认） +| 模式 | 锁定范围 | 适用场景 | +|------|---------|---------| +| 任务级锁 | 只锁定目标任务 | 单 Agent | +| 列表级锁 + Agent 忙碌检查 | 锁定整个任务目录 | 多 Agent 团队 | -仅锁定目标任务文件，适合单 Agent 场景： +认领失败有多种原因：任务已被认领、任务已完成、依赖未满足、Agent 已有其他未完成任务。 + +**设计考量**：列表级锁的 `checkAgentBusy` 防止一个 Agent 一次认领太多任务。在 swarm 模式下，每个 Agent 应该专注于一件事——认领新任务前必须完成或放弃当前任务。 + +## 多 Agent 团队的生命周期 ``` -getTask → 检查 owner → 检查 status → 检查 blockedBy → 写入 owner +Leader 创建任务 → 设置依赖 → Teammate 认领 → 执行 → 完成 → 解锁下游任务 + ↓ + Teammate 异常退出 → 未完成任务被重置 ``` -### 2. 列表级锁 + Agent 忙碌检查 +Teammate 异常退出时，其未完成任务被自动重置为无主状态，Leader 可以重新分配。这确保了单个 Agent 的崩溃不会永远阻塞整个团队。 -当 `checkAgentBusy: true` 时，锁定整个任务列表目录（`.lock` 文件），原子化地完成： +## 与 Plan Mode 的配合 -``` -listTasks → 检查任务状态 → 检查依赖 → 检查 Agent 是否已拥有其他未完成任务 → 写入 owner -``` +Plan Mode 和任务系统是互补但独立的机制： -认领失败有 4 种原因： - -| `reason` | 含义 | -|----------|------| -| `task_not_found` | 任务 ID 不存在 | -| `already_claimed` | 已被其他 Agent 认领 | -| `already_resolved` | 任务已标记 completed | -| `blocked` | blockedBy 列表中有未完成的任务 | -| `agent_busy` | 该 Agent 已拥有其他未完成任务（仅 `checkAgentBusy` 模式） | - -## Agent 团队的任务生命周期 - -在 swarms 模式下，任务系统的生命周期是这样的： - -``` -Leader 创建团队 - ↓ -Leader 用 TaskCreate 创建任务（status=pending, owner=undefined） - ↓ -Leader 用 TaskUpdate 设置依赖关系（addBlocks/addBlockedBy） - ↓ -Teammate 调用 TaskList → 发现可认领的任务 - ↓ -Teammate 调用 TaskUpdate(taskId, {status: "in_progress"}) - → 自动设置 owner 为 teammate 名称 - → Leader 通过 mailbox 收到 task_assignment 通知 - ↓ -Teammate 完成工作 → TaskUpdate(taskId, {status: "completed"}) - → tool_result 提示 "Call TaskList to find your next available task" - → 依赖此任务的其他任务自动解锁 - ↓ -Teammate 异常退出 → unassignTeammateTasks() - → 未完成任务被重置为 pending + owner=undefined - → 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（计划模式）和任务系统是互补但独立的机制： - -1. Plan Mode 限制工具集为只读（搜索、阅读），迫使 AI 先理解再行动 -2. AI 在 Plan Mode 中用 TaskCreate 建立任务列表 +1. Plan Mode 限制工具集为只读，迫使 AI 先理解再行动 +2. AI 在 Plan Mode 中创建任务列表 3. 用户审批后退出 Plan Mode -4. AI 按 `blockedBy` 拓扑序逐项执行，每项用 TaskUpdate 标记进度 +4. AI 按依赖拓扑序逐项执行 -`shouldDefer: true` 属性确保这些工具调用不会触发权限确认弹窗——任务管理操作始终自动批准，因为它们不产生副作用。 +任务管理操作始终自动批准——它们不产生副作用（不修改代码、不执行命令），只是追踪"要做什么"。 + +## 接下来 + +- **Agent 系统** — 理解子 Agent 的创建和协调 +- **Plan Mode** — 理解"先规划再执行"的工作流 +- **Swarm 模式** — 理解多 Agent 团队的任务分配