---
title: "任务清单与澄清"
description: "Ankole agent 如何为复杂任务做计划、如何在任务中途解决真正的歧义——todo 工具（按会话、同时最多一项进行中）和 clarify 工具（一个问题，持久记录，结束本回合）。agent 各拿它们做什么，运维不该期待它们做什么。"
url: "https://ankole.agentbull.com/zh-Hans-CN/docs/todo-and-clarify/"
lang: "zh-Hans-CN"
---

> 面向 AI Agent 的文档索引：https://ankole.agentbull.com/zh-Hans-CN/llms.txt

# 任务清单与澄清

`todo` 和 `clarify` 是 agent 的结构化计划工具。一个把计划留在会话内，另一个在答案真的会改变结果时只问你一个问题。两者都随 worker 出厂，源在 `app/agent_computer/src/tools/`。它们不是记忆，也不是聊天界面——它们让 agent 自己站稳脚跟，也让它发起一次决策提问。

先说明最关键的一点：todo 清单是易失的、按会话隔离的；一次 `clarify` 调用会结束本回合。清单不会跨会话保留，agent 一旦提问，就等你的下一条消息。两者都不是持久真相——那个角色归 Memory。

## 每个工具是什么

- **`todo`**（`tools/todo/todo-tool.ts`，第 182 行）——管理当前会话的任务清单。用于三步以上的复杂任务，也用于用户一次给出多个任务的情况。清单顺序就是优先级。同时最多一项 `in_progress`。一完成立即标完成；失败则取消并加一条修订项。
- **`clarify`**（`tools/clarify/clarify-tool.ts`，第 39 行）——在歧义真的会改变结果时，向用户提一个决策问题。用于真正的取舍、缺失的需求、以及事后反馈。若有安全的低风险默认值，就别问。成功时它返回归一化后的问题和选项，持久记录它们，并结束当前回合。

todo 清单存在一个按会话隔离的 `TodoStore` 里。它是工作状态，不是记录。允许四种状态：`pending`、`in_progress`、`completed`、`cancelled`。

## agent 何时用 todo

当步骤多到光靠上下文兜不住时，agent 才用 `todo`。三步以上，或一次交接多个任务，是触发点。清单一旦建立，agent 遵守三条规则：

1. **顺序即优先级。** 第一项就是 agent 接下来要做的。
2. **同时最多一项进行中。** agent 不会在第一项完成或取消前就开第二项。
3. **完成即标记。** 做完的步骤以 `completed` 离开清单，而不是停在当前项。失败的步骤标 `cancelled`，并加一条修订项。

todo 清单不是什么：它不是持久计划，也不是把活交给下一会话的手段。新会话从空清单开始。如果一份计划必须熬过会话，它进 Memory，不进 `todo`。

## agent 何时用 clarify

`clarify` 留给那一个答案真的会把结果分叉的问题。契约刻意收窄。agent 提一个问题，带可选选项（每个不超过 500 字符），然后停手。一次成功调用会发生三件事：

- 归一化后的问题和选项被持久记录，事后可追溯这次决策；
- 当前回合结束——agent 不再产出回答，也不再调工具；
- 你的回复作为下一条用户消息到达，agent 从那里把活接回来。

这意味着 `clarify` 调用是一次干净交还，不是长回合里的一次暂停。你按自己的节奏回答，继续的回合是一个以你的回答开头的新回合。

agent 不该问的时候：存在安全的低风险默认值。如果 agent 能选一条合理路径并告诉你它选了什么，它就该选，而不是打断你。把 `clarify` 留给真正的取舍、缺失的需求、事后反馈——猜错就得返工的场合。

## clarify 与后台任务如何衔接

在 [后台任务](https://ankole.agentbull.com/zh-Hans-CN/docs/background-jobs/index.md) 里，一次 `clarify` 调用会把任务推入 `waiting_on_user` 状态。在你回复前任务不再推进，你的回复把它推回 `running`。从你这边看，这像任务停下来只问一个问题。从 agent 这边看，是同一套契约——提问、结束回合、等下一条消息——落进任务生命周期里。状态模型和你如何发现一个在等你的任务，见 [后台 Agent 任务](https://ankole.agentbull.com/zh-Hans-CN/docs/background-jobs/index.md)。

## 运维不该碰的东西

todo store、clarify 的持久记录、结束回合的行为，都是 worker 内部，不是 Console 可调的设置。如果 agent 该问却不问，或问得太勤，修在 agent 的人设和能力集里——见 [Agents](https://ankole.agentbull.com/zh-Hans-CN/docs/agents/index.md)——而不在某个 worker 开关上。被记录的决策可经写它的同一套 worker 界面审计；运维不手动改它们。

## 下一步

- 塑造 agent 何时做计划、何时提问的人设与能力，读 [Agents](https://ankole.agentbull.com/zh-Hans-CN/docs/agents/index.md)。
- 真正熬过会话的持久知识，归 Memory。
- `waiting_on_user` 任务状态，以及任务内一次 clarify 如何暂停它，读 [后台 Agent 任务](https://ankole.agentbull.com/zh-Hans-CN/docs/background-jobs/index.md)。
- 回合内跑这些工具的 worker，读 [Agent Computer Worker](https://ankole.agentbull.com/zh-Hans-CN/docs/agent-computer-worker/index.md) 开发者页。