crontap-heartbeat-for-cron

用途

Crontap Heartbeat for Cron 用于给已经拥有自身调度时钟的周期性任务添加心跳监控。任务在成功完成工作后向 Crontap 发送一次 ping；如果超过设定的周期加宽限窗口仍无 ping，则被记录为一次漏检（missed check-in），而 /fail 变体用于显式报告失败。该技能适合需要为现有 cron 或定时作业增加告警能力的场景。

主要能力

创建心跳：指定名称、预期周期（periodMinutes）和宽限窗口（graceMinutes），并可设置邮件冷却时间（emailCooldownMinutes）。
返回密钥 ping URL：创建响应中包含一个秘密 ping URL，需一次性捕获并作为密钥存储。
查看 ping 历史：可按 UTC 日期查询某个心跳的 ping 记录。
轮换令牌：在明确确认后轮换心跳令牌，旧 URL 的两个变体会立即失效。
成功与失败上报：任务成功后可发送成功 ping；在已处理的失败路径中可调用 /fail 变体并附带受限的错误摘要。

使用方式

前置条件

使用前先检查所需工具是否可用。若缺失，应停止并让用户在以下两项中明确选择其一：

连接 Crontap MCP：https://mcp.crontap.com/mcp ，MCP 访问在所有 Crontap 套餐均可用。
配置 $CRONTAP_CLIENT_ID 和 $CRONTAP_API_KEY 以使用原始 API，原始 API 访问需要 Ultra 套餐。

不要静默选择某条路径或继续，直到用户做出选择。此外还需了解任务真实的最大间隔（包括预期抖动），选择足够长的宽限窗口以覆盖普通延迟和运行时间，并决定由哪个组件安全存储返回的 ping URL。

工作流

使用预期周期和宽限创建心跳。
一次性捕获返回的 ping URL 并作为密钥存储。
仅在任务成功完成后添加成功 ping。
在任务已处理的失败路径中添加 /fail ping。
部署后以及任何事故后检查 ping 历史。
仅在凭据泄露或计划性凭据轮换时轮换令牌。

MCP 示例

创建每日心跳，宽限 30 分钟：

{ "tool": "create_heartbeat", "arguments": { "name": "Nightly import", "periodMinutes": 1440, "graceMinutes": 30, "emailCooldownMinutes": 60 } }

响应包含一个秘密 ping URL。不要将其回显到源码管理、CI 日志、支持工单或后续的代理消息中。

查看一个 UTC 日：

{ "tool": "get_heartbeat_pings", "arguments": { "heartbeatId": "<heartbeat-id>", "day": "2026-09-14" } }

在明确确认后轮换：

{ "tool": "rotate_heartbeat_token", "arguments": { "heartbeatId": "<heartbeat-id>" } }

轮换会立即使旧 URL 的两个变体失效。需在下一个截止时间前用新返回的 URL 更新任务。

任务集成

使用环境变量，例如 CRONTAP_HEARTBEAT_URL：

run_the_job && curl --fail --silent --show-error "$CRONTAP_HEARTBEAT_URL"

在已处理的失败中，调用 "$CRONTAP_HEARTBEAT_URL/fail?msg=bounded-error-summary"。消息中不得包含凭据、个人数据或大型堆栈跟踪。

REST 回退

REST 需要 Ultra API 访问，MCP 不需要。

curl --fail-with-body https://api.crontap.com/v1/heartbeat
-X POST
-H "ClientId: $CRONTAP_CLIENT_ID"
-H "ApiKey: $CRONTAP_API_KEY"
-H "Content-Type: application/json"
--data '{ "name": "Nightly import", "periodMinutes": 1440, "graceMinutes": 30 }'

验证

从已部署的任务环境发送一次测试成功 ping。
确认心跳在接受 ping 后从 pending 状态变化。
演练一条安全的失败路径，验证产生 fail 事件且不暴露 ping URL。
检查周期加宽限是否反映任务最坏情况下的正常运行时间。

适用场景

适用于已有自身调度时钟的周期性任务，需要检测任务是否静默失败或未按时运行的场景。心跳检测的是静默，不会启动或重启任务。

限制与安全

ping URL 是凭据，任何持有它的人都可以报告活动。
心跳检测静默，但不启动或重启任务。
Starter 套餐的心跳频率和数量限制与付费套餐不同，以创建响应为准。
遇到套餐限制响应时，应呈现其四选项阶梯和最小可行选项，不要编造价格。

故障排查

在第一次被接受的 ping 之前，不会开始任何截止时间。
暂停期间的 ping 会记录历史，但不会改变截止时间。
重复快速 ping 可能被限流，但仍返回 HTTP 200。
轮换后旧 URL 停止工作属于预期行为，需部署替换后的密钥。