---
title: 工作项与任务
summary: 持久化目标与受控执行句柄，包括规划、等待、权属与完成判定。
order: 60
---

# 工作项与任务

工作项（WorkItem）记录一个持久化的业务目标。任务（Task）则追踪某次具体的执行过程，例如后台测试命令或委派给其他 Agent 的调用。一个工作项可以包含多次任务执行，简短的任务也可以独立于工作项运行。

例如，“修复构建错误并验证补丁”是一个目标，而运行构建命令是一项任务。构建成功为实现该目标提供了事实证据，但并不等同于补丁已经满足了全部验收要求。

## 何时需要跟踪目标

当一项工作需要跨轮次执行、等待 CI 或人工决策、或者需要保留进度和验收标准供后续审查时，应使用工作项。如果操作者明确要求在多轮对话中跟踪一系列决策清单，工作项同样非常适用。

简短的解答、边界收敛的检查，或者在当前轮次内即可完成并验证的改动，通常无需建立工作项。单凭步骤的多寡并不能作为创建依据。

跟踪一项方案并不代表获得了实现授权。工作项可以在等待操作者定夺期间，妥善保留备选项与待确认问题。

## 工作记录保存的内容

目标（Objective）清晰描述预期的交付成果；计划（Plan）记录工作范围、验收标准与选定方案；清单（Checklist）追踪有实质意义的推进阶段；证据引用（Evidence reference）则指向 Agent 可以重新查验的执行结果。

这些记录的核心目的，是在上下文重置后回答“还剩什么没做”。它们不应退化成每次工具调用的流水账。当推进方案发生变化时更新计划；当测试执行结束时，记录结果及其对最终验收的影响。

## 焦点、就绪与等待

“当前焦点”（Current）标明 Agent 正在关注哪一项工作，但这本身并不意味着该工作项正在运行或随时可运行。处于开启状态的工作项可能正在等待操作者输入、被外部事件阻塞，或者在其他项执行期间主动让出了执行权。

已登记的等待记录（Wait）明确了恢复后续执行所需满足的触发条件。仅在计划中写下“等待 CI”或结束当前回复，并不会在系统中注册等待。就绪与等待属于运行时状态，需要通过工作项和等待相关接口统一管理。

切换工作焦点并不会将已存在的任务迁移给另一个工作项。任务始终归属于创建时绑定的所属者。这一点至关重要：即使 Agent 已开始构思另一个目标，耗时较长的后台测试完成后，其结果依然属于原先的工作项。

关于任务结果与外部通知如何唤醒工作，详见[事件、等待与唤醒](./events-and-waits.md)。

## 任务句柄能提供的信息

借助任务句柄，Agent 可以检查任务状态与输出，并在支持的环境中发送交互输入或中止执行。部分句柄对应系统命令，另一些则代表委派工作或等待其他 Agent 的回复。应根据句柄类型来理解其完成含义。

例如，协作 Agent 回复一条消息可以解除回复等待句柄，但消息内容可能说明所请求的审查仍在处理中；命令虽然成功退出，也可能并未生成预期的文件产物。在接受结论前，务必查阅实际执行结果。

## 完成目标

只有在核对完请求的交付成果、并且验证结论已经明确时，才应将工作项标记为完成。完成报告应当阐明交付结果、具体产物，以及影响使用的限制条件。

单纯结束单次执行是不够的。如果实现工作已获授权且尚未完工，应保持工作项处于开启状态并记录可恢复的下一步；如果工作无法继续推进，应登记具体的等待条件，而不是推称它会自动继续。

## 下一步

- [跟踪与完成长期工作](../guides/run-long-lived-task.md)
- [查看执行进度与成果](../guides/observe-agent-work.md)
- [工作项参考](../reference/work-items.md)
- [任务规格](../spec/tasks.md)