用持久化任务兑现语音助手的回拨承诺

AI 助手答应「周四上午 10 点给你回电话」，难点在于挂断之后，系统还能不能兑现承诺。服务重启、用户改期、预约取消，都可能让一句听起来可靠的回答变成空话。

Telnyx 的开源 TypeScript 示例 Concierge Diary，把模型的判断交给一个持久化实体执行：模型提出回访意图，系统负责记住、调度和追踪。它值得看的地方是如何处理承诺的生命周期，以及明确承认哪些故障还没兜住。

模型负责决定，谁来负责兑现？

原文以影像诊所为例。通话结束后，AI Assistant 的 post-conversation processing 会给模型额外一轮处理机会，让它判断是否需要回访，再通过 HTTP 工具提交结构化意图。

这份意图包含 conversationId、patientName、reason、callbackAt、opener、endUserTarget 和 agentTarget。示例时间为 2026-11-12T10:00:00-08:00，患者名为 Maya；两个号码占位符 <PATIENT_E164> 和 <ASSISTANT_E164> 需要替换成测试环境的 E.164 号码。

请求进入 POST /diary/entries 后，路由通过 env.DIARY.idFromName(conversationId) 得到标识，再用 env.DIARY.get(id) 获取对应的 Telnyx Edge Stateful Actor。可以把 Actor 理解成一个拥有持久化状态、专门管理这次回访的对象。

它保存回访时间、个性化开场白、调度事件 ID、当前状态，以及表示创建工作尚未完成的标记。SQL 则记录回访生命周期，方便检查。

模型可以决定要做什么，但兑现承诺需要独立的状态和执行机制。

这个边界很实用：对话负责收集需求，业务对象负责后续操作。下一轮模型是否还记得前文，不应成为预约能否执行的条件。

为什么必须先记账，再创建电话任务？

Actor 不会收到请求就直接创建电话任务。它先持久化预约，把 eventId 设为 null、status 设为 "booked"、createPending 设为 true，并将原始意图存入 pendingBody。

随后，它写入 SQL，调用 schedule(await this.sweepSeconds(), "onSweep", ...) 安排恢复检查，最后执行 createPendingEvent("booked")。

这样，即使进程在创建事件前停止，系统仍有记录可查，恢复检查也能唤醒 Actor，继续处理待办工作。持久化的对象不仅是「有一条预约」，还包括「这条预约还有一步没做完」。

实际发送给 Scheduled Events 的关键参数如下，它解决的是何时拨打、使用什么个性化内容，以及失败后如何重试：

{
  telnyx_conversation_channel: "phone_call",
  scheduled_at_fixed_datetime: intent.callbackAt,
  dynamic_variables: {
    patient_name: intent.patientName,
    topic: intent.reason,
    opener: intent.opener
  },
  max_retries_client_errors: 2,
  retry_interval_secs: 300
}

这里要看清 max_retries_client_errors: 2 和 retry_interval_secs: 300：原文配置的是客户端错误最多重试 2 次、重试间隔 300 秒，不能据此推断所有失败都会自动恢复。

事件被接受后，Actor 才保存返回的事件 ID，清除待创建标记，更新 SQL，再通过 Programmable Messaging 发送确认短信。

改期同样围绕状态展开：先删除旧事件，再按新时间创建替代事件。删除返回 404 也视为成功，因为旧事件可能已经触发或被移除。取消则删除待执行事件、清理待处理状态，同时保留取消记录。

状态回调还必须匹配当前保存的事件 ID，避免旧预约的迟到通知误改新预约。

能恢复重启，不等于不会重复拨打

原文对幂等性给出了明确边界。相同预约重复提交时，如果 Actor 已有同一时间的 "booked" 事件，就返回现有状态，避免再次创建。

但还有一个危险窗口：上游已经成功创建事件，本地却在保存返回 ID 前停止。恢复后，本地仍认为创建未完成，再试一次就可能产生第二个事件。

待处理标记能保住工作意图，却不能单独保证外部操作只执行一次。

要补上这个缺口，需要上游支持幂等键，或者应用重试前先核对已有事件。作者还建议给长期停留在 pending 状态的记录加告警，并制定数据保留规则。原文没有展示完整的核对实现，也没有给出故障注入测试或重复率数据，不能把它当作已经证明的生产保证。

试跑入口倒是比较克制。项目默认 DEMO_MODE=true，Actor 状态和 SQL 流转真实执行，但事件创建、删除和短信发送只写日志。下面是原文的安装、冒烟检查与部署命令：

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/concierge-diary
cp .env.example .env
npm install
npm run smoke

telnyx-edge auth api-key set "$TELNYX_API_KEY"
telnyx-edge secrets add TELNYX_API_KEY "$TELNYX_API_KEY"
telnyx-edge types
telnyx-edge ship

要留意 npm run smoke 所在的测试阶段：保留 DEMO_MODE=true 可以检查流程，但不能验证真实电话和短信是否送达。

真实预约路由要求共享密钥 DIARY_WEBHOOK_SECRET，助手的 webhook 工具可发送 Authorization: Bearer <DIARY_WEBHOOK_SECRET> 或 X-Diary-Token: <DIARY_WEBHOOK_SECRET>。切换到真实模式前，还要配置 assistant ID、账户自有发送号码、诊所名称和该密钥。

我的判断

这套设计最有价值的地方，是把 AI 编程中容易被忽略的部分摆到了台前：工具调用成功之后，业务还要经历重试、取消、改期和迟到通知。

按 conversationId 聚合状态，也让一次回访的责任归属比较清楚。不过，示例没有说清同一通话需要多个独立回访时怎么建模，这个前提不能直接照搬。

如果团队已有数据库、任务队列和定时调度服务，也可以组合出类似流程。Actor 提供了集中管理单个预约的方式，但原文没有对照成本、吞吐或维护复杂度的数据，无法据此断言它更适合所有 Node 团队。

医疗场景也只是业务示例。文章展示的是调度与状态管理，没有说明患者数据的访问控制和保留策略如何落地。拿去处理真实业务前，这些仍是待完成的工作。

能拿来做什么

• 给 AI 助手增加后续执行能力时，先定义结构化意图和业务状态，让模型提交需求，由服务端持久化对象负责执行与追踪。
• 在 Node 服务审查外部调用时，专门检查「上游成功、本地未落库」这个窗口，确认重试前是否有幂等键或事件核对机制。
• 做预约管理前端时，把改期、取消和状态查询作为完整流程设计，并让后端按当前事件 ID 校验回调，避免页面被旧任务通知带偏。
• 试跑 Concierge Diary 时先保持 DEMO_MODE=true，检查 SQL 记录和状态流转，再补齐真实调用配置，并验证重复提交与中断恢复的行为。