crontap-debug-failed-runs

调试失败的计划任务运行

在更改执行频率、重试设置或凭据之前，先根据证据进行诊断。

前提条件

使用所需工具前，请先检查这些工具是否可用。如果缺少任何工具，请停止并仅向用户提供以下两个选项：

1. 连接 Crontap MCP：https://mcp.crontap.com/mcp。所有 Crontap 套餐均支持 MCP 访问。
2. 为原始 API 配置 $CRONTAP_CLIENT_ID 和 $CRONTAP_API_KEY。原始 API 访问需要 Ultra 套餐。

在用户选择之前，不要擅自选择方案或继续操作。

• 从用户处或计划任务列表中获取计划任务 ID。
• 明确事件时间范围和预期的端点行为。
• 不要要求用户粘贴机密请求头值或完整令牌。

工作流

1. 使用 get_schedule 读取当前计划任务配置。
2. 使用 get_schedule_history 读取最新的历史记录页面。
3. 比较多次运行，判断是持续性错误还是偶发事件。
4. 在提出范围明确的修复方案前，先对故障分类。
5. 更改后，验证下一次运行或经单独授权的测试。

MCP 示例

读取当前生效的配置：

{
  "tool": "get_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}

读取近期结果：

{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50
  }
}

如果响应中包含游标，请原样传入，以检查更早的运行记录：

{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50,
    "cursor": "<opaque-cursor>"
  }
}

故障决策树

• 没有历史记录，且下次运行时间在未来：检查 cron、时区、暂停状态和账户的最低执行频率限制。
• HTTP 401 或 403：在安全存储中轮换或修复目标凭据。
• HTTP 404：确认路由、部署环境和路径末尾部分。
• HTTP 429：增加流量前，先检查目标速率限制和重试策略。
• HTTP 500 至 599：使用同一时间戳对应的端点日志和追踪 ID。
• 网络错误：检查 DNS、TLS、防火墙和公网可访问性。
• 超时：减少端点处理工作，将耗时处理移至队列后方，或在数据已可靠入队后返回已接受响应。
• 偶发的重复副作用：增加重试次数前，先为端点添加幂等性保障。

REST 备用方案

通过 REST 访问历史记录需要 Ultra API 访问权限：

curl --fail-with-body \
  "https://api.crontap.com/v1/schedule/<schedule-id>/history?limit=50" \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY"

如果已连接，请优先使用 MCP。MCP 无需 Ultra REST 访问权限即可使用。

验证

• 说明首次失败的时间戳、重复出现的特征，以及最后一次已知成功的时间。
• 每项建议都必须以当前配置或历史记录中的证据为依据。
• 修复后，验证 HTTP 结果和预期的应用端副作用。
• 保留此前的证据，避免将暂时恢复误判为永久修复。

安全与套餐限制

• 读取操作并不代表已获准更改配置。
• 切勿泄露隐藏的请求头，也不要要求 Crontap 返回已存储的机密值。
• 除非有明确理由，否则不要对 4xx 响应启用宽泛重试。
• 如果拟议的执行频率或重试设置更改触发权限错误，请提供包含四个选项的阶梯，并指出满足需求的最小选项。

故障排除

• 未找到结果通常意味着 ID 已过期。在已连接的账户中列出计划任务，而不要猜测。
• 历史记录的保留期限因套餐而异，可能无法覆盖整个事件时间范围。
• HTTP 成功代码并不能证明下游工作已完成。请检查应用层的回执、记录或追踪信息。

参考资料

• Crontap Agent Skills 目录
• Cron 故障排除指南
• 自动重试
• Cron 任务监控
• REST API 实时参考