AI Agent 定时任务成功但未收到通知该怎么办？
定时任务日志显示成功，但群聊、收件箱或手机依然静默。遇到这种情况时，请勿反复重新运行任务。在大多数情况下，任务执行和消息投递是两个独立的流程：前者完成仅表示工作流已到达结束状态，并不能证明通知已成功生成、发送并送达目的地。
排查“AI Agent 定时任务无通知”问题最快的方法是按顺序验证流程的每个阶段：任务是否生成了输出、通知是否被触发、投递目标是否正确、平台是否接受以及接收方是否实际收到。请严格按以下顺序逐步操作。
任务成功不等于通知成功
典型的工作流至少包含几个阶段：任务执行、结果处理、通知触发、平台投递和终端接收。调度器中的“成功”状态通常仅表示任务流程正常结束，甚至可能仅仅意味着命令返回了零退出码。通知模块可能根本没有运行，或者平台在运行后拒绝了该请求。
首先，打开本次运行的完整日志，定位到最终的业务步骤和第一个通知步骤。不要只看顶部显示的状态。如果日志在结果生成后立即结束，问题很可能出在触发条件上。如果能看到发送请求，请继续检查响应码、消息 ID 或错误体。对于需要长期运行的自动化任务，还可参考AI Agent 工作流监控与错误恢复方法，并将执行状态与投递状态分开记录。
步骤 1：检查任务是否生成了可发送的内容
许多通知规则会跳过空字符串、空数组或仅包含空白字符的结果。任务可能已成功执行，但查询未返回新记录，脚本可能已将标准输出重定向到文件，或者 Agent 仅返回了结构化对象，而通知模块只读取文本字段。这些情况都可能导致“成功但未发送”。
- 检查原始输出的字节数，而非仅依赖预览。
- 确认通知模板引用的变量名与任务实际返回的字段完全匹配。
- 临时发送一条固定的短文本消息，以判断问题出在内容生成端还是投递端。
- 检查是否触发了“仅在结果可用时通知”或“忽略空结果”等条件。
如果固定文本成功送达，说明投递通道基本正常，此时应返回修正输出映射。初次构建自动化时，建议先用一个单一、可观测的小任务验证整个流程，再逐步添加条件。具体操作请参阅AI Agent 自动化助手入门指南。
步骤 2：验证投递目标，勿仅依赖显示名称
群组名称、频道名称或联系人标签可能存在重复，或在迁移后指向已废弃的对象。请验证平台实际使用的标识符，例如聊天 ID、频道 ID、电子邮件地址或 Webhook URL。同时确认定时任务运行时读取的是生产环境配置，而非本地测试配置。
若 SmaugBrain 工作流需跨平台传递结果，请逐一检查各环境变量、关联每个密钥的账户以及目标 ID，确保它们均来自同一环境。有关配置跨平台流程的指导，请参阅AI Agent 跨平台集成指南。请特别注意这一差异：手动测试使用的是当前登录的账户，而定时任务可能使用服务账户，两者的权限未必相同。
步骤 3：检查平台权限与接收方限制
机器人被移出群聊、应用令牌过期、频道禁止发帖或邮件进入垃圾箱，均不会改变上游任务的成功状态。请检查平台返回的 HTTP 状态码和响应体：401 和 403 通常表示认证或权限问题；404 通常意味着目标已删除或 ID 错误；429 表示请求发送过快。平台有时可能返回 200，但在响应体中标记发送操作失败，因此不能仅依赖 HTTP 状态码。
在接收方侧，请检查免打扰设置、折叠消息、垃圾邮件规则以及机器人是否被屏蔽。若消息发送至群聊，还需确认应用具备发送消息、上传文件和@提及成员的相关权限。仅授予“查看”权限通常是不够的。
步骤 4：分别测试文本通知与附件通知
包含图片、PDF 或日志文件的消息可能因附件过大、文件类型受限或下载链接过期而完全失败。请先发送纯文本消息，再发送一个极小的测试附件。如果文本送达但附件未送达，请检查文件大小、MIME 类型、发送时文件是否仍可读取，以及平台是否要求先上传文件再发送消息。
长文本也可能超出单条消息的长度限制。一种可靠的做法是提取摘要，将完整结果保存在可访问的位置，然后发送链接。或者，根据平台限制将文本分段，并在每段中保留相同的运行 ID，以便接收方判断消息是否完整。
步骤 5：处理超时、限流与重试
通知请求可能已发出，但客户端可能在收到响应前超时。不检查就立即重试会导致重复消息，而从不重试则会导致漏发通知。为每条通知生成唯一键，遇到 429 或临时 5xx 响应时采用递增延迟策略，并设置最大重试次数。确定性错误（如认证失败或目标不存在）不应无限重试，而应路由至告警或待处理队列。
SmaugBrain 用户还可针对每个通知步骤单独记录开始时间、结束时间、目标、响应状态和重试次数。切勿将令牌、完整 Webhook 或私密内容写入日志。这样下次遇到“任务显示正常，但消息始终未送达”时，就能精准定位故障点。
如何验证修复效果
- 手动运行一次固定的短文本测试，并记录运行 ID。
- 确认通知模块报告成功，若平台提供消息 ID 则予以保存。
- 确认消息在实际目的地可见，而非仅在 API 报告成功后就停止验证。
- 运行另一项带有真实结果的任务，确认变量和附件正常工作。
- 等待下一次定时触发，排除仅手动执行环境有效的问题。
最后一步至关重要。手动运行会继承当前终端的环境变量和权限，而定时的运行通常使用不同的工作目录、时区和账户。只有当调度器实际触发任务且消息在目的地可见时，修复才算完成。您可以在 SmaugBrain 中保留一个低风险的自动通知自检任务，以便定期验证整个通道。
常见问题
为什么手动运行时通知正常，但定时运行时失效？
这两种执行方式通常使用不同的账户、环境变量、工作目录或时区。请对比两次运行的配置来源和通知目标，首先检查调度服务是否成功加载了密钥。
任务无输出时是否仍应发送通知？
这取决于具体使用场景。监控类任务非常适合发送简短的心跳包，例如“检查完成；未发现异常”。内容采集类任务可以跳过空结果，但跳过原因应在日志中记录。
平台 API 返回 200 是否意味着用户已收到消息？
不一定。API 可能仅表示请求已被接受。后续投递仍可能因队列、权限或接收方规则而失败。请检查响应体和消息 ID，并在目的地进行实际确认。
通知失败是否应导致整个任务失败？
对于关键告警，运行状态通常应标记为部分失败或需人工关注。常规摘要可独立重试。无论采取何种策略，“业务执行状态”与“通知投递状态”都应分开可见。
如果您正在构建多步自动化，可使用 SmaugBrain 将任务结果与通知投递拆分为两个可观测节点，然后按本文所述顺序验证每个阶段。在重新连接复杂内容之前，先确保一条简单消息能可靠送达，通常比重复运行整个工作流更快。
排查完成标记：scheduled-notification-delivery-verified