dsh-cron-toolkit

DeepSeek Harness 的 cron 表达式工具箱：explain_cron 用中文解释表达式，next_runs 计算接下来的运行时间，validate_cron 校验并给出提示。支持 5/6 段、英文缩写与 @daily 等宏。纯计算、零运行时依赖。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-cron-toolkit
• npm：https://www.npmjs.com/package/dsh-cron-toolkit

功能说明

面向 cron 表达式的"读懂 → 验证 → 排期"三步，提供三个纯计算工具：

explain_cron —— 中文解释

逐字段翻译触发规则，并给出概要描述与规范化表达式：

表达式：*/15 9-18 * * 1-5
类型：5 段

字段解释：
  分钟  */15           每 15 分钟
  小时  9-18           9-18
  日    *              每天
  月    *              每月
  星期  1-5            周一、周二、周三、周四、周五

概要：在 每天 / 周一、周二、周三、周四、周五 09:00,10:00,...,18:00 执行
规范：*/15 9-18 * * 1-5

next_runs —— 下次运行时间

表达式：0 9 * * 1-5
基准：2024-01-01T00:00:00.000Z（UTC）
时区：+08:00

   1. 2024-01-01 09:00:00（周一）  UTC 2024-01-01T01:00:00.000Z
   2. 2024-01-02 09:00:00（周二）  UTC 2024-01-02T01:00:00.000Z

validate_cron —— 校验与提示

给出合法性判定、规范化表达式与常见陷阱提示（如"日包含 31，短月不会触发"）。

主要特性

• 5 段与 6 段：自动识别（分 时 日 月 周 / 秒 分 时 日 月 周）
• 丰富语法：*、?、a-b、a,b,c、*/n、a-b/n，月与星期支持 JAN/MON 等英文缩写
• 宏支持：@yearly、@annually、@monthly、@weekly、@daily、@midnight、@hourly
• 星期日兼容：0 与 7 均表示周日
• 日期语义：日与星期同时被限定时按 vixie-cron 规则取「或」
• 时区可配：next_runs 支持 tz_offset（分钟），默认 +08:00
• 零 npm 依赖：仅使用 Node 内置模块

安装

npm install dsh-cron-toolkit

使用说明

explain_cron

用户：帮我看看 0 9 * * 1-5 是什么意思

表达式：0 9 * * 1-5
类型：5 段

字段解释：
  分钟  0              第 0 分钟
  小时  9              9
  日    *              每天
  月    *              每月
  星期  1-5            周一、周二、周三、周四、周五

概要：（限 …）在 每天 / 周一、周二、周三、周四、周五 09:00 执行
规范：0 9 * * 1-5

参数：cron（表达式，5 段或 6 段，或 @daily 等宏）。

next_runs

用户：这个定时任务接下来 5 次什么时候跑

表达式：*/15 * * * *
基准：2024-01-01T00:00:00.000Z（UTC）
时区：+08:00

   1. 2024-01-01 08:15:00（周一）  UTC 2024-01-01T00:15:00.000Z
   2. 2024-01-01 08:30:00（周一）  UTC 2024-01-01T00:30:00.000Z
   ...

参数：cron、count（默认 5，上限 50）、from（基准时间，默认当前；结果为该时间之后）、tz_offset（分钟，默认 480）。

validate_cron

用户：0 0 31 * * 这个写法有问题吗

结果：✅ 合法
表达式：0 0 31 * *
段数：5
规范：0 0 31 * *
提示：
  - 日包含 31，短月不会触发

参数：cron。

典型场景

1. 读懂别人的定时任务

用户：这个 cron 表达式是什么意思

explain_cron 一次给出逐字段解释与概要。

2. 排期核对

用户：这个任务下次什么时候执行

next_runs 列出接下来的运行时间（含星期与 UTC），便于与日历比对。

3. 上线前校验

用户：帮我确认这个表达式没写错

validate_cron 检查段数与取值范围，并提示短月、无解组合等陷阱。

4. 时区换算

用户：这个任务在美国东部时间几点跑

next_runs 传对应 tz_offset，同时给出墙钟时间与 UTC 时间。

5. 无解表达式排查

用户：0 0 30 2 * 为什么一直不触发

next_runs 会明确报出"在未来 8 年内找不到匹配时间，表达式可能无解"。

安全边界

• 纯计算：三个工具均不读写文件、不访问网络、不修改系统计划任务；测试含确定性断言。
• 迭代与年限双上限：单次查找最多 20 万次迭代，且向后搜索不超过 8 年，超出即报错，避免无解表达式造成长时间占用。
• 显式报错：段数不符、取值越界、区间颠倒、未知宏等均抛出明确错误，不静默返回错误结果。
• 不做时区数据库下载：时区以分钟偏移表示，不依赖外部 tzdata。
• 只解释不执行：本插件只做表达式解析与时间推算，不会创建或修改任何定时任务。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-plugin-timer | cron-toolkit 负责"解释与推算"，plugin-timer 负责"到点执行/提醒" | | dsh-date-calc | 用 format_date 把 next_runs 的结果做本地化展示；用 workdays_between 排除非工作日 | | dsh-table-render | 把多次运行时间渲染成对齐表格 | | dsh-workspace-journal | 把排期结果记录到工作区日志 | | dsh-json-yaml-toolkit | 校验配置文件中的 cron 字段是否合法 |

版本说明

• 0.1.0（2026-09-25）：初始版本。
  • explain_cron：逐字段中文解释 + 概要 + 规范化
  • next_runs：N 次运行时间（时区可配、含星期与 UTC）
  • validate_cron：合法性校验 + 常见陷阱提示
  • 5/6 段、宏、英文缩写、7=周日、vixie-cron 日期取或语义

RoadMap

v0.2（计划）

• 支持 Quartz 风格的 L（月末）、W（最近工作日）、#（第 N 个星期几）
• next_runs 支持跳过指定日期（节假日黑名单）
• 新增 cron_from_text：把"每天上午 9 点"这类自然语言转成表达式（启发式）
• 反向能力：给出若干时间点，推断最可能的 cron 表达式

v0.3（展望）

• 支持秒级 @every 30s 风格的间隔语法
• 输出 iCal RRULE 以便与日历系统对接
• 批量校验目录下所有配置文件中的 cron 字段

FAQ

Q：支持 5 段还是 6 段？ 都支持。5 段为 分 时 日 月 周，6 段为 秒 分 时 日 月 周，工具会自动识别。

Q：星期日写 0 还是 7？ 都表示周日，两者等价。

Q：日和周同时限定时怎么算？ 按 vixie-cron 的经典规则：两者都被限定（非 *）时取「或」，只要满足其一即触发。validate_cron 会给出提示。

Q：next_runs 的 from 是包含还是排除？ 排除。返回的都是 from 之后的时间点。

Q：为什么有些表达式会报"无解"？ 例如 0 0 30 2 *（2 月 30 日）永远不存在。插件会向后搜索 8 年，仍未命中即判定无解并报错。

Q：会不会真的创建定时任务？ 不会。本插件只做解析与推算，执行请使用 dsh-plugin-timer。

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-cron-toolkit
• npm：https://www.npmjs.com/package/dsh-cron-toolkit

许可证

MIT