跳到正文
Ankole

任务清单与澄清

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/todo-and-clarify/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

todo 与 clarify 是归属 Ankole.Sessions.Tools.Session 的控制面原生工具:会话 Driver 负责校验入参,通过 AIGateway 记录对模型可见的工具返回结果,并将状态变更应用到当前运行上下文。

任务清单

todo 工具支持读取当前清单、整体替换清单,或按条目 ID 增量合并更新;单条状态可取 pending、in_progress、completed 或 cancelled,单次声明最多容纳 256 个条目。按照工具指令约定,凡涉及三个步骤以上的复杂任务均应维护任务清单:按优先级排序,同一时刻仅保持一项处于 in_progress 状态,完成后立即勾选完结,执行受阻失败时则补充新的修订步骤。

任务清单属于 Ankole.Sessions.Run 的会话内临时工作状态,而非跨会话的企业知识。进程故障恢复时,系统会从当前运行历史中已成功落库的工具调用记录重建清单;新建的 Session 不会继承其他 Session 的清单。需要跨会话长期共享的信息应写入 Brain。

一个决策问题

仅当用户的回答会实质改变最终产出或决定下一步走向时,Agent 才会调用 clarify 提出一个上下文自洽的澄清问题。发问前,Agent 会先充分消化当前请求与既有对话记录,既不会反复追问用户已经表态过的偏好,也不会在存在安全、低风险默认做法时无故打断执行。

澄清问题既支持开放式自由作答,也支持提供 2 至 4 个方向截然不同的候选项(问题正文上限为 2,000 个字符,单个选项标签上限为 200 个字符,可选补充说明上限为 500 个字符)。凡是允许用户拒绝执行的操作,候选项中必须包含明确的“不执行”选项。

clarify 调用成功后,系统会记录规范化后的问题与候选项,并立即结束当前推理回合——此后 Agent 不再调用任何其他工具,也不会追加最终文本答复。在原生 Pod Chat 中,控制面会将题目与选项快照写入消息的 rich_content["clarify"] 字段,由前端渲染为交互式 ChoiceCard 卡片,并通过投递交互检查点维护 pending -> answered | superseded 状态流转(当同一 Agent 发出新的澄清问题时,此前尚未作答的旧卡片会自动转为 superseded)。房间成员既可直接在 ChoiceCard 上点选按钮或填写补充说明(采用“先答生效”并发锁控制,重复抢答会收到 HTTP 409),也可在 Pod Chat 或外部聊天渠道中直接发送普通文本消息作答,从而唤醒 Agent 进入续跑回合。澄清问题与最终采纳的用户答复均会持久化保存在会话记录中。

结构化表单

当回答需要同时给出多个带类型的值时,Agent 会传入 fields 而不是 choices。一个表单包含 1 至 5 个字段。每个字段都有一个 snake_case 格式的 id、不超过 80 个字符的 label、不超过 200 个字符的可选提示 help、默认为 true 的 required、可选的预填值 default,以及以下类型之一:text(单行或 multiline 多行,max_length 最大 1,000,默认 200)、number(支持 integer、min、max 和单位标签 unit)、date(YYYY-MM-DD 格式,可设 min 和 max)、select 或 multi_select(2 至 10 个选项,每个选项包含 value 和 label;multi_select 还可设 min_items 和 max_items),以及 boolean。一个表单至少要有一个必填字段。如果字段 ID 或选项值重复、最小值大于最大值、默认值无效,或没有任何必填字段,控制面会拒绝该定义,并把原因返回给 Agent,以便它修正调用。

在 Pod Chat 中,ChoiceCard 会把表单渲染成对应类型的输入控件。控制面会再次校验每一次提交:提交无效时,相应字段下方会显示错误,问题保持待答;第一次有效提交即完成作答。房间里会以一行摘要展示答案,摘要由字段标签拼成;Agent 则同时收到这段摘要和 JSON 格式的类型化取值,其中选择类字段使用选项的 value。成员如果想用自己的话回答,仍可在输入框中打开该问题作答。

飞书/Lark 和 Microsoft Teams 会直接在回复卡片中渲染表单,并附带一个在 Pod 中打开同一表单的按钮。控制面会校验每次卡片提交:无效的提交不会结束问题,并会指出需要修改的字段——飞书/Lark 以弹出提示显示,Teams 则以一条回复告知;第一次有效提交即完成作答,随后飞书/Lark 和 Teams 会把表单替换为回答摘要。其他外部聊天渠道会收到问题、字段标签和 Pod 链接(/?interaction=<id>)。打开链接只会在对话框中显示表单,并不算作答;直到有人在卡片或 Pod 中提交有效表单,或在渠道中直接回复,问题才会结束待答状态。

后台 Job 与运维

原生 Codex 后台任务(Job)走一套独立的人工输入请求路径:当任务请求用户补充信息时,任务状态会切换为 waiting_on_user 并主动释放占用的 Worker 运行槽位;待任务所有者回复后,任务才会恢复推进。这一行为属于后台任务自身的生命周期契约,详见 后台 Agent 任务。

Console 中不提供单独调节任务拆解粒度或澄清提问频率的开关;如需调整 Agent 规划步骤或发起提问的分寸,请直接修订该 Agent 的人设指令与能力配置,详见 Agents 与 Agent 循环。