---
title: "任务管理"
description: "任务追踪是 AI 自我管理的关键。理解双轨架构（V1 内存 / V2 文件系统）、依赖管理、认领竞争和验证推动的设计。"
keywords: ["任务管理", "TodoWrite", "任务队列", "依赖管理", "多任务"]
---

## 核心问题

复杂任务需要分解为多个步骤。没有任务追踪，AI 容易"迷失"——做了第三步忘了第二步，或者跳过关键验证直接宣布完成。

任务系统让 AI 能规划、追踪和汇报自己的工作进度。

## 双轨架构

Claude Code 有两个并存的任务系统，按运行模式自动切换：

| 维度 | V1: TodoWrite | V2: TaskCreate/TaskUpdate |
|------|:------------:|:------------------------:|
| **存储** | 内存（进程退出即丢失） | 文件系统（跨进程持久化） |
| **适用** | 非交互式（pipe/SDK） | 交互式 REPL（默认） |
| **数据** | 扁平三元组 | 完整实体（含依赖、认领） |
| **并发** | 无（单会话） | 文件锁 + 高水位标记 |

**设计考量**：V1 追求极简——pipe 模式是一次性执行，不需要持久化。V2 追求可靠——交互式会话和多 Agent 团队需要任务在进程崩溃后仍能恢复。

## V1：TodoWrite 的极简设计

V1 本质是一个全量替换操作——每次调用传入完整的任务列表，完全覆盖之前的状态。

### 智能清空

当所有任务都完成时，列表被自动清空。这确保 UI 上不会有"已完成"的视觉噪音。

### 验证推动（Verification Nudge）

当 AI 完成了 3+ 个任务且没有任何一个是验证步骤时，系统追加提示催促 AI 派生验证子 Agent。

**设计洞察**：这是防止 AI "自说自话地宣布完成"的防御性设计。它不是硬约束（AI 可以忽略），而是结构性推动——通过在合适的时机插入提醒，让 AI 自己决定是否验证。

为什么是 3 个任务？太少的阈值会产生过多噪音，太多则会让 AI 在完成大量工作后才被提醒验证，错过了早期发现问题的机会。

## V2：文件系统持久化

### 数据模型

每个任务是一个独立的 JSON 文件，包含：
- **subject**：祈使句标题（"Fix auth bug"）
- **activeForm**：进行时形式（"Fixing auth bug"），用于 spinner
- **status**：pending → in_progress → completed
- **owner**：认领该任务的 Agent
- **blocks / blockedBy**：任务间依赖

### ID 分配的安全保证

任务 ID 是递增整数，但在并发场景下需要防止竞争：
- 使用排他锁防止两个 Agent 同时创建相同 ID
- 高水位标记确保删除任务后 ID 不会被重用

**设计考量**：为什么不使用 UUID？整数 ID 更直观（"任务 3 阻塞任务 5"比"任务 a3f2 阻塞任务 b7c1"更易读）。但在并发环境下需要额外的工作来保证唯一性。

## 依赖管理：blocks / blockedBy

任务间的依赖通过双向字段实现：
- `taskA.blocks = ["3"]` — 任务 A 完成前，任务 3 不能开始
- `task3.blockedBy = ["A"]` — 任务 3 必须等任务 A 完成

两端同时维护，删除任务时自动清理所有引用。

**为什么是双向而非单向**？因为两个方向的查询都很常见：
- "任务 A 阻塞了谁？" → 读 `blocks`
- "任务 3 在等谁？" → 读 `blockedBy`

单向存储需要遍历所有任务来回答其中一个问题。

## 任务认领与并发控制

多个 Agent 可能同时想认领同一个任务。系统提供两种锁定粒度：

| 模式 | 锁定范围 | 适用场景 |
|------|---------|---------|
| 任务级锁 | 只锁定目标任务 | 单 Agent |
| 列表级锁 + Agent 忙碌检查 | 锁定整个任务目录 | 多 Agent 团队 |

认领失败有多种原因：任务已被认领、任务已完成、依赖未满足、Agent 已有其他未完成任务。

**设计考量**：列表级锁的 `checkAgentBusy` 防止一个 Agent 一次认领太多任务。在 swarm 模式下，每个 Agent 应该专注于一件事——认领新任务前必须完成或放弃当前任务。

## 多 Agent 团队的生命周期

```
Leader 创建任务 → 设置依赖 → Teammate 认领 → 执行 → 完成 → 解锁下游任务
                                                              ↓
                                          Teammate 异常退出 → 未完成任务被重置
```

Teammate 异常退出时，其未完成任务被自动重置为无主状态，Leader 可以重新分配。这确保了单个 Agent 的崩溃不会永远阻塞整个团队。

## 与 Plan Mode 的配合

Plan Mode 和任务系统是互补但独立的机制：

1. Plan Mode 限制工具集为只读，迫使 AI 先理解再行动
2. AI 在 Plan Mode 中创建任务列表
3. 用户审批后退出 Plan Mode
4. AI 按依赖拓扑序逐项执行

任务管理操作始终自动批准——它们不产生副作用（不修改代码、不执行命令），只是追踪"要做什么"。

## 接下来

- **Agent 系统** — 理解子 Agent 的创建和协调
- **Plan Mode** — 理解"先规划再执行"的工作流
- **Swarm 模式** — 理解多 Agent 团队的任务分配
