本文是「从零理解 Claude Code：20 个 Agent Harness 机制」系列的第 12 篇。
对应源码：s12_task_system
源码仓库：shareAI-lab/learn-claude-code
设想 Agent 接到一个小型后端改造任务：先建立数据库表，再写接口，最后跑一下测试和写文档。
它在当前会话中列出待办后，开始处理接口，发现表结构还没有确定。等前置工作补完，会话又因为某个原因结束。下次重新启动时，Agent 还得重新确认哪些工作已经做完，接口任务是否可以继续，测试任务又要等到什么时候。
s05 的待办列表可以记录当前任务的步骤，却不保存这些步骤之间的依赖关系，也不负责跨会话恢复。s12 新增的任务系统，把每项工作写入文件，并根据任务依赖决定哪些工作可以开始。
一、待办列表为什么无法承担跨会话任务
待办列表适合处理当前会话里的执行顺序，例如先读文件、再修改代码、最后运行测试。它保存的是 Agent 当前的计划状态。
项目任务需要保存的信息更多。以建表、写接口、补测试为例，系统至少要知道：
| 工作项 | 是否可以立即开始 | 原因 |
|---|---|---|
| 建数据库表 | 可以 | 没有前置任务 |
| 写接口 | 暂时不可以 | 需要先确定表结构 |
| 补接口测试 | 暂时不可以 | 需要先完成接口 |
| 写接口文档 | 暂时不可以 | 需要先了解表结构和接口设计 |
这类关系不会自动建立依赖，这就会造成一个问题，如果临时中断的会话运行了还没有完成前置任务的工作项，那待办列表就失去了其原本的作用。
s12 将任务从会话内的计划，变成可以保存、查询和恢复的记录。任务文件留在工作目录中，会话结束后仍然存在，后续 Agent 可以继续读取它们。
二、任务状态怎样写入工作目录
本章在工作目录下创建.tasks文件夹，每个任务对应一个 JSON 文件。
任务的数据结构包含任务标题、描述、状态、负责人和依赖任务：
@dataclass class Task: id: str subject: str description: str status: str owner: str | None blockedBy: list[str]创建任务时，程序会生成任务 ID，并立刻调用保存函数写入文件。后续认领、完成任务时，也会重新写入同一个文件。
任务状态只有三种：
| 状态 | 含义 | 下一步可能动作 |
|---|---|---|
pending | 待开始 | 认领任务 |
in_progress | 正在处理 | 完成任务 |
completed | 已完成 | 解锁依赖它的下游任务 |
例如，建表任务完成前，接口任务仍然保持待开始状态，接口任务通过依赖检查并被认领后，状态才会改为进行中。
把任务状态写到文件中，带来的直接收益是进度可恢复。Agent 重启后不需要从整段消息历史里猜测当前进度，只需读取任务目录即可。
教学代码中的任务 ID 由秒级时间和四位随机数拼接而成。这个方案实现简单，但没有检查重复 ID。如果同一秒内恰好生成了相同随机数，后写入的任务会覆盖前一个文件。生产环境通常需要更可靠的编号分配方式。
三、依赖检查怎样决定任务能否开始
任务系统通过blockedBy保存前置任务 ID。
写接口任务可以依赖建表任务，补测试任务可以依赖接口任务。Agent 想认领任务时，程序会先检查所有前置任务：
def can_start(task_id: str) -> bool: task = load_task(task_id) for dep_id in task.blockedBy: if not _task_path(dep_id).exists(): return False if load_task(dep_id).status != "completed": return False return True依赖任务只要有一个不存在，或者状态还不是已完成，当前任务就不能开始。
例如，接口任务依赖建表任务。建表任务仍在进行中时，接口任务无法认领。建表任务完成后，接口任务重新通过检查，才具备开始条件。
这个判断也处理了写错依赖 ID 的情况。程序不会因为找不到依赖文件直接崩溃，而是将当前任务继续视为被阻塞。Agent 需要修正依赖关系后，才能继续推进任务。
任务依赖和状态变化放在一起看，会比一张待办清单更清楚。
四、认领和完成任务怎样推进后续工作
依赖检查通过后，Agent 可以认领任务。
认领时，代码确认任务仍处于待开始状态，然后写入负责人，并将状态更新为进行中。
任务完成时，程序先确认它当前处于进行中状态，再将状态改为已完成。随后扫描任务目录，找出依赖条件已经满足的待开始任务。
以建表任务为例，完成后可能出现两项可继续处理的工作：
| 已完成任务 | 可能可开始的下游任务 |
|---|---|
| 建数据库表 | 写接口、写接口文档 |
| 写接口 | 补接口测试 |
这里有一个需要区分的细节。complete_task()返回的列表叫作已解锁任务，代码实际列出的是所有当前可以开始、且带有依赖关系的待开始任务。
其中可能包含上一次已经满足条件、只是暂时没人认领的任务。它更像一份当前可执行任务提示，而不是严格记录本次完成动作新解锁了哪些任务。
五、教学实现还缺少哪些恢复与并发保护
任务保存到文件后，跨会话恢复的问题解决了一部分，多 Agent 场景还会遇到新的边界。
第一个问题是并发认领。
当前claim_task()会先读取任务状态，再修改负责人和状态，最后写回文件。两个 Agent 几乎同时认领同一个待开始任务时，都可能在读取阶段看到它仍然可认领，随后分别开始工作。后写入文件的结果会覆盖前一个负责人，实际工作却已经重复了。
第二个问题是任务中断后的恢复。
教学代码支持从待开始进入进行中，也支持从进行中进入已完成。Agent 认领任务后意外退出时，任务会一直停留在进行中状态，其他 Agent 无法继续认领。真实 Claude Code 会在 Agent 停止时解除未完成任务的负责人，并把任务重新放回待开始状态，本章代码没有实现这条回退路径，真实的回退逻辑可以参考前段时间cc的源码仓库 https://github.com/anthropics/claude-code。
第三个问题是依赖环。
如果任务 A 依赖任务 B，任务 B 又依赖任务 A，两项任务都会一直被阻塞。当前代码只检查前置任务是否完成，没有检测依赖图是否形成环。
另外，s12 为了聚焦任务系统，使用了简化的 Agent Loop。s11 中的输出截断恢复、上下文超限压缩、接口退避重试没有完整保留。任务持久化和错误恢复属于不同层，真实系统通常需要同时具备两者。
六、小结
待办列表适合帮助 Agent 安排当前几步工作，任务系统负责把项目里的工作留在磁盘上。每项任务保存自己的状态和依赖关系，会话结束后，后续 Agent 仍然能知道哪些工作完成了，哪些工作还要等前置任务。
s12 的代码通过任务文件、依赖检查、认领和完成状态，把任务按顺序推进起来。建表完成后，接口任务才能开始；接口完成后，测试任务才具备执行条件。
这套教学实现还没有处理多人同时认领、依赖成环、认领者中断后释放任务等情况。后续设计任务系统时，除了关心任务能否创建，也要确认任务被谁认领、异常退出后谁能接手，以及依赖关系会不会把任务永久卡住。
下一章会继续处理长时间运行的工作。测试、部署这类操作不适合让 Agent 一直停在原地等待，s13 会把它们放到后台执行。
