本文是「从零理解 Claude Code20 个 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 会把它们放到后台执行。
