Back to Details

crontap-natural-language-schedules

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Preview natural-language schedules

预览自然语言调度

Use this skill to resolve timing before another skill creates or updates a schedule. A preview is read-only.
使用此 skill，在另一个 skill 创建或更新调度之前解析时间安排。预览是只读操作。

Prerequisites

前提条件

Before using the required tools, check whether they are available. If any are missing, stop and offer the user exactly two choices:
  1. Connect Crontap MCP at 
    https://mcp.crontap.com/mcp
    . MCP access works on every Crontap tier.
  2. Configure 
    $CRONTAP_CLIENT_ID
    and 
    $CRONTAP_API_KEY
    for the raw API. Raw API access requires Ultra.
Do not silently choose a path or continue until the user selects one.
  • Identify the user's intended local timezone.
  • Ask whether business-day wording means weekdays or a holiday-aware calendar.
  • Capture any boundary requirement, such as start date or final day of month.
在使用所需工具之前，检查这些工具是否可用。如果有任何工具缺失，请停止操作，并向用户提供恰好两个选项：
  1. 在 
    https://mcp.crontap.com/mcp
    连接 Crontap MCP。所有 Crontap 套餐均支持 MCP 访问。
  2. 为 raw API 配置 
    $CRONTAP_CLIENT_ID
    和 
    $CRONTAP_API_KEY
    。raw API 访问需要 Ultra 套餐。
不要擅自选择一种方式；在用户选择之前不要继续。
  • 确定用户所指的本地时区。
  • 询问“工作日”表述是指星期几，还是指包含节假日规则的日历。
  • 明确任何边界要求，例如开始日期或每月最后一天。

Phrase schedules precisely

精确表述调度

Prefer phrases with a frequency, local time, and calendar scope:
  • every weekday at 09:15
  • every 6 hours
  • at 02:30 every Sunday
  • on the first day of every month at 08:00
Avoid phrases such as 
in the morning
, 
twice a month
, 
month end
, or 
weekdays
without a timezone. Five-field cron cannot represent every holiday-aware or last-business-day rule.
优先使用包含频率、本地时间和日历范围的说法：
  • every weekday at 09:15
  • every 6 hours
  • at 02:30 every Sunday
  • on the first day of every month at 08:00
避免使用诸如 
in the morning
、
twice a month
、
month end
或未指定时区的 
weekdays
等说法。五字段 cron 无法表示所有考虑节假日或最后一个工作日的规则。

Workflow

工作流

  1. Resolve an exact IANA timezone with the user.
  2. Call 
    preview_schedule
    with the original cadence and timezone.
  3. If the response needs clarification, present its question and options.
  4. Preview again with the user's answer.
  5. Report the resolved cron, timezone, and every returned next run.
  6. Ask for confirmation before any separate create or update operation.
  1. 与用户确认确切的 IANA 时区。
  2. 使用原始调度频率和时区调用 
    preview_schedule
    。
  3. 如果响应需要澄清，则展示其中的问题和选项。
  4. 使用用户的回答再次预览。
  5. 报告解析后的 cron、时区以及返回的每一次下一次运行时间。
  6. 在任何单独的创建或更新操作之前请求确认。

MCP example

MCP 示例

json
{
  "tool": "preview_schedule",
  "arguments": {
    "text": "every weekday at 09:15",
    "timezone": "America/New_York"
  }
}
Do not save a guessed cron if the response has 
needs_clarification
or 
rejected
status. Treat returned options as choices, not as permission to pick for the user.
json
{
  "tool": "preview_schedule",
  "arguments": {
    "text": "every weekday at 09:15",
    "timezone": "America/New_York"
  }
}
如果响应的状态为 
needs_clarification
或 
rejected
，不要保存猜测的 cron。将返回的选项视为供用户选择的选项，而不是替你选择的许可。

DST and calendar checks

DST 与日历检查

  • Verify next runs on both sides of a nearby daylight-saving transition.
  • A named timezone preserves local wall-clock intent. A UTC schedule preserves a fixed UTC time.
  • Confirm whether 
    weekday
    excludes only Saturday and Sunday.
  • For last-business-day logic, schedule a safe candidate cadence and put the final calendar check inside an idempotent endpoint.
  • For one-time work, use a one-time schedule only after confirming its exact timestamp and cleanup behavior.
  • 验证临近的夏令时切换（daylight-saving transition）两侧的下一次运行时间。
  • 具名时区会保留按本地钟表时间运行的意图。UTC 调度则保持固定的 UTC 时间。
  • 确认 
    weekday
    是否仅排除星期六和星期日。
  • 对于最后一个工作日逻辑，安排一个安全的候选频率，并将最终日历检查放在 idempotent endpoint 内部。
  • 对于一次性工作，只有在确认精确时间戳和清理行为后，才能使用一次性调度。

REST fallback

REST 回退方案

The public API fallback requires Ultra API access:
bash
curl --fail-with-body https://api.crontap.com/v1/schedule/preview \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"text":"every weekday at 09:15","timezone":"America/New_York"}'
MCP remains available without Ultra. Prefer MCP when connected.
公共 API 回退方案需要 Ultra API 访问权限：
bash
curl --fail-with-body https://api.crontap.com/v1/schedule/preview \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"text":"every weekday at 09:15","timezone":"America/New_York"}'
MCP 无需 Ultra 套餐也可使用。已连接时优先使用 MCP。

Safety and plan limits

安全与套餐限制

  • Previewing does not consume resource capacity.
  • A valid preview can still produce a cadence below the account's creation floor. Creation is the authoritative entitlement check.
  • If creation later returns a plan-limit response, preserve its four-option ladder and identify the smallest viable plan.
  • Never infer user consent to create from a read-only preview.
  • 预览不会消耗资源容量。
  • 即使预览有效，所生成的调度频率仍可能低于账户的创建下限。创建操作才是套餐权限的最终校验依据。
  • 如果后续创建操作返回套餐限制响应，请保留其四选项阶梯结构，并确定最小可行套餐。
  • 绝不能根据只读预览推断用户同意创建。

Troubleshooting

故障排查

  • If the phrase is rejected, simplify it to one frequency and one local time.
  • If the cron looks right but next runs look wrong, check the timezone first.
  • If a desired calendar rule cannot be represented, move that condition into the endpoint and keep the endpoint idempotent.
  • 如果表述被拒绝，将其简化为一个频率和一个本地时间。
  • 如果 cron 看起来正确但下一次运行时间不正确，请先检查时区。
  • 如果所需的日历规则无法表示，请将该条件移至 endpoint，并保持 endpoint 为 idempotent。

References

参考资料