mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 13:55:50 +00:00
79baf14a8f
移除 TypeScript 代码和源码路径， 聚焦 V1/V2 双轨的设计权衡、验证推动的阈值考量、 双向依赖的查询优化和多 Agent 认领的并发控制。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
114 lines
5.0 KiB
Plaintext
114 lines
5.0 KiB
Plaintext
---
|
||
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 团队的任务分配
|