Cloudflare 更新 AI 等待工具,等用户回复时可休眠
2026 年 11 月 20 日,Cloudflare 发布 Agents SDK 0.34.0 的更新说明,将 PiHarness 升级到 Pi 1.6,工具可以停下来等待信号,再恢复执行。对开发需要人工补充信息或确认的 AI 助手的团队,这提供了一条等待期间不必持续占住调用的实现路径。本文用文档归档助手说明任务怎样暂停、如何接回回复,以及重复请求、授权和版本升级要保留哪些边界。

原创 AI 概念插画,用书签、纸带与铃铛解释等待和恢复,不是产品截图。
[配图建议:纸带任务在书签处暂停,回复便笺牵动铃铛后继续展开 + 暖色水彩编辑插画]
新变化:等待也成为工具的一种状态
这次更新的重点是工具可以返回“停放”状态,而不必立刻给出结果。它可以等一个信号、一个截止时间,或另一段任务的结果;等待的调用不持有 invocation,因此承载它的 Durable Object 可以休眠。这里说的是执行框架的等待方式,不是让模型在休眠时继续推理。Cloudflare 更新公告
设想一个文档归档助手。用户提交材料后,助手已经提取了主题,却不知道该放进哪个项目。它需要向用户提出问题,然后等待。用户可能马上回答,也可能稍后从另一个页面回来;如果应用只依赖当前请求中的一个长时间等待,接回后续回复就需要额外处理。
新机制允许把“正在等什么”放进任务状态,让人类回复成为后续推进任务的信号。对读者的价值是将提问、等待与继续执行连成一条明确的流程,而不是每次收到回复都新建一个毫无关联的任务。
PiHarness 为 Pi 提供 Durable Object 中的 SQLite 存储与唤醒安排,保存会话、收件箱和任务等内容。应用仍需自己决定通过 HTTP、WebSocket 或 RPC 怎样与用户界面通信;使用框架不等于已经拥有完整产品。PiHarness 的存储与生命周期
[配图建议:同一条任务纸带依次经过提问、停放、回复和继续四个位置 + 细线水彩流程插画]
回复抵达后,工具会重新进入执行逻辑
官方示例的思路很直接:工具先读取对应信号;如果已经有答案,就将它作为工具结果返回;没有答案时显示问题,再返回等待信号的状态。应用收到用户回复后,通过 harness.signal() 把值交给对应任务,Pi 随后再次运行工具代码。等待工具示例
这点会改变代码的写法。暂停更像在任务记录中留下一个书签,而不是承诺原来那一行 JavaScript 一直挂在内存中。重新进入工具时,程序需要检查已有的信号和状态,再决定下一步。界面也应能从任务记录恢复“等待项目选择”,而不是只记住一个临时加载动画。
回到归档场景,应用应将问题、目标任务和允许选择的项目联系起来。用户返回后,先能看见自己在回答哪一个问题;服务端再将这次回复送到对应等待任务。项目选择一旦被接收,就让界面显示“已收到,正在归档”,减少用户因为页面迟迟没变而重复点击。
Pi 1.6 的变更记录还说明,信号值可以在任务真正进入等待之前到达并被保存;休眠后收到信号便可唤醒。这解决的是异步顺序问题的一部分。信号投递有接收、重复、无效、已关闭和未找到等不同结果,应用应据此决定继续、提示重试,还是告诉用户该问题已经结束。Pi Durable 1.6 信号机制
界面上的“已回复”,应对应任务确实接收到了这份答案。 如果用户回答了已取消任务,简单地把输入框清空会让人误以为处理成功。保留明确的任务状态,比把所有返回都包装成成功提示更有用。
[配图建议:回复便笺携带任务标识抵达书签,重复和过期便笺进入单独收件格 + 温和的编辑插画]
休眠、授权和重复执行要分别设计
休眠解决等待期间的执行占用,授权回答的是谁能让任务继续。归档助手中,即使某人知道任务标识,也不代表他有权替别人选择项目。应用仍要核对当前用户与会话的关系、项目访问权限,以及任务是否还在等待这个问题。这些是把机制用于业务时需要补齐的应用逻辑。
官方文档明确,PiHarness 没有内置的工具审批步骤;若需要人工批准,可以在 beforeTool 钩子中停放调用,再用信号送入答案。文档同时提醒,钩子重新打开时会再次运行,应保持幂等。审批与恢复限制 因此不能仅凭工具醒来,就把任意字符串当作“批准”,更不能把超过截止时间理解为默认同意。
重复执行也要另看。扩展文档中,replay: "safe" 表示调用被中断、对象重启后可以重跑;默认的 unsafe 则不会自动重跑,而是把中断结果交给模型。官方举例将读取与搜索列为可考虑安全重放的操作,将发送邮件这类有外部副作用的操作留在不安全一侧。工具的重放设置
这并不自动等于业务上的“只归档一次”。如果工具已经写入记录,却在保存完成结果前中断,应用仍需能查到已有记录,避免继续执行时再创建一份。可将业务操作编号与目标文档关联,在恢复时先查结果;这是应用层的去重设计,不能用一个重放标签代替。
版本也有实际代价。文档将 Pi Durable 标为实验性,API 可能在次版本中变化。依赖与版本说明 更新公告还提示,会话一旦运行在 Pi 1.6 上,Pi 1.5 就不能继续其工具调用和模型请求;出现部署问题时应向前修复,而不是直接回退旧版本。试用前应固定 SDK 与配套依赖,并将旧会话的恢复行为列入升级方案。升级边界
[配图建议:等待铃铛、权限钥匙和单次归档印章分别摆放,旁边有版本书签 + 暖色手绘说明图]
从一个没有真实写入的小任务开始
最短试验可以只做“提问后返回用户选中的项目名”,先不写数据库,也不连接真实归档工具。让一次任务走过提问、等待、回复、恢复和结束,确认界面能分清“等待回复”与“已经完成”。下面是依据文档机制设计的验证路径,不是本站已经运行的结果。
先看正常路径:新建任务、显示项目问题、送入一次合法回复,检查任务是否返回正确项目。再看页面重开:关闭界面后重新进入,确认仍能展示待答问题,并将回复接回同一个任务。这里需要观察的是持久任务记录与界面恢复,而不只是网络连接是否还在。
接着试重复回复、取消后回复,以及截止时间先到的情况。界面要说明哪一次回复被接受、任务是否结束;没有答案时要走明确的未完成分支。用户在等待期间修改了要求,也应有清楚的更新规则,避免旧问题的答案作用到新任务。
最后再接一个可检查结果的测试归档操作,记录业务编号、唤醒结果和实际写入记录。先证明任务能正确停下和接回,再讨论资源收益。 观察运行占用时还要区分模型调用、存储与其他仍在执行的工作,不能从“可以休眠”推导整套应用没有成本。
[配图建议:试验笔记依次记录正常回复、重新打开、重复回复和取消四种结果 + 轻盈的水彩实验手账]
今天先标出一个真正需要等待的地方
这项更新适合正在构建 Cloudflare 持久任务、并需要人类补充信息的团队。已有普通表单就能解决的短流程,不必只为新接口重构。今天可以先找出助手中一次真实的等待:它在等谁、答案送到哪个任务、没有答案又会怎样结束?把这三个问题写清楚,才知道停放和唤醒机制应接在哪里。
[配图建议:一张便笺写着等待对象、任务与结束条件,书签停在对应纸带位置 + 水彩技术编辑插画]
资料核查于 2026 年 11 月 22 日。本文依据 Cloudflare 与 Pi 项目一手文档整理;归档助手和验证路径为说明性设计,未部署运行或测量费用。封面为 AI 生成概念图。