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

2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
@@ -1,12 +1,17 @@
 ---
-title: "任务管理系统 - TodoWrite 与 Tasks 双轨架构"
-description: "揭秘 Claude Code 任务管理系统的双轨架构：V1 内存 TodoWrite 与 V2 文件系统 Tasks，包含依赖管理、认领竞争和验证推动机制。"
-keywords: ["任务管理", "TodoWrite", "任务队列", "依赖管理", "多任务"]
+tags: [claude-code, task-management, todo, concurrency, multi-agent]
+create time: 2026-06-09 22:30
 ---

-{/* 本章目标：揭示任务系统 V1（内存 TodoWrite）和 V2（文件系统 Task*）的双轨架构，以及依赖管理、认领竞争、验证推动的工程细节 */}
+# 任务管理系统 - TodoWrite 与 Tasks 双轨架构

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

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

@@ -20,7 +25,7 @@ Claude Code 的任务管理并非单一系统，而是两个并存、按运行

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

-## V1：TodoWrite 的极简设计
+### V1：TodoWrite 的极简设计

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

@@ -35,7 +40,7 @@ async call({ todos }, context) {
 }
 ```

-### 智能清空与验证推动
+#### 智能清空与验证推动

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

@@ -50,11 +55,12 @@ if (allDone && todos.length >= 3 && !todos.some(t => /verif/i.test(t.content)))
 // "NOTE: You just closed out 3+ tasks and none was a verification step..."
 ```

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

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

-### 数据模型
+#### 数据模型

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

@@ -73,7 +79,7 @@ if (allDone && todos.length >= 3 && !todos.some(t => /verif/i.test(t.content)))
 }
 ```

-### 任务列表 ID 的解析优先级
+#### 任务列表 ID 的解析优先级

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

@@ -83,9 +89,10 @@ if (allDone && todos.length >= 3 && !todos.some(t => /verif/i.test(t.content)))
 4. Leader 通过 `setLeaderTeamName()` 设置的 teamName
 5. `getSessionId()`（独立会话的兜底）

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

-### ID 分配与高水位标记
+#### ID 分配与高水位标记

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

@@ -104,7 +111,7 @@ async function createTask(taskListId, taskData) {

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

-## 依赖管理：blocks / blockedBy
+### 依赖管理：blocks / blockedBy

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

@@ -126,11 +133,11 @@ if (!toTask.blockedBy.includes(fromTaskId)) {

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

-## 任务认领与并发控制
+### 任务认领与并发控制

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

-### 1. 任务级锁（默认）
+#### 1. 任务级锁（默认）

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

@@ -138,7 +145,7 @@ if (!toTask.blockedBy.includes(fromTaskId)) {
 getTask → 检查 owner → 检查 status → 检查 blockedBy → 写入 owner
 ```

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

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

@@ -146,7 +153,7 @@ getTask → 检查 owner → 检查 status → 检查 blockedBy → 写入 owner
 listTasks → 检查任务状态 → 检查依赖 → 检查 Agent 是否已拥有其他未完成任务 → 写入 owner
 ```

-认领失败有 4 种原因：
+认领失败有以下原因：

 | `reason` | 含义 |
 |----------|------|
@@ -156,33 +163,29 @@ listTasks → 检查任务状态 → 检查依赖 → 检查 Agent 是否已拥
 | `blocked` | blockedBy 列表中有未完成的任务 |
 | `agent_busy` | 该 Agent 已拥有其他未完成任务（仅 `checkAgentBusy` 模式） |

-## Agent 团队的任务生命周期
+### 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 收到通知并重新分配
+```mermaid
+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 集成
+#### Hooks 集成

 TaskCreate 和 TaskUpdate 都集成了 hooks 系统：

@@ -191,7 +194,7 @@ TaskCreate 和 TaskUpdate 都集成了 hooks 系统：

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

-## activeForm：终端 UX 的细节
+### activeForm：终端 UX 的细节

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

@@ -200,7 +203,7 @@ TaskCreate 和 TaskUpdate 都集成了 hooks 系统：

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

-## Plan Mode 与任务系统的配合
+### Plan Mode 与任务系统的配合

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

@@ -209,4 +212,12 @@ Plan Mode（计划模式）和任务系统是互补但独立的机制：
 3. 用户审批后退出 Plan Mode
 4. AI 按 `blockedBy` 拓扑序逐项执行，每项用 TaskUpdate 标记进度

-`shouldDefer: true` 属性确保这些工具调用不会触发权限确认弹窗——任务管理操作始终自动批准，因为它们不产生副作用。
+> [!info] 自动批准
+> `shouldDefer: true` 属性确保这些工具调用不会触发权限确认弹窗——任务管理操作始终自动批准，因为它们不产生副作用。
+
+## 关联笔记
+
+- [[what-are-tools]]
+- [[file-operations]]
+- [[shell-execution]]
+- [[search-and-navigation]]