dsh-cron-parse

Readme

# dsh-cron-parse

DSH 插件：解析 **5 段标准 cron 表达式**，提供校验、中文人性化描述、各字段展开值，以及**未来若干次运行时间预览**。纯 ESM、零依赖、无构建。

## 安装

```sh
dsh plugin --profile <name> add file:./plugins/dsh-cron-parse
# 或 npm 发布后：dsh plugin --profile <name> add dsh-cron-parse
```

安装后组合层会挂载 `cron_parse` 工具（`cron-parse` 层 id）。

## 工具：`cron_parse`

参数：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `expression` | string | 是 | 5 段标准 cron：`minute hour dayOfMonth month dayOfWeek` |
| `count` | number | 否 | 未来运行次数（1–10），默认 5 |
| `tz` | string | 否 | IANA 时区名（如 `Asia/Shanghai`、`UTC`），默认本地时区 |
| `now` | string | 否 | ISO 8601 基准时间，默认当前时间 |

返回规范值：`{ ok, valid, description, fields: { minute, hour, dom, month, dow }, nextRuns, timezone, errors }`。

## 支持语法表

| 语法 | 示例 | 含义 |
|---|---|---|
| `*` | `*` | 全部取值 |
| `*/n` | `*/15`（分钟） | 每 n（自最小值起） |
| `a-b` | `1-5`（星期） | 闭区间 |
| `a-b/n` | `0-30/10` | 区间内步进 |
| 列表 | `1,15,30` | 多值并集 |
| 名称 | `jan-dec`、`sun-sat` | 月名/星期名，大小写不敏感 |
| 周日 | `0` 或 `7` | `0/7` 都表示周日，展开后归一为 `0` |

各字段取值范围：分钟 `0-59`，小时 `0-23`，日 `1-31`，月 `1-12`，星期 `0-7`。

## 语义说明

- **dow / dom 并集（经典 Vixie 语义）**：当「日（dayOfMonth）」与「星期（dayOfWeek）」**都受限**（字段不是纯 `*`）时，某天只要**满足其一**即触发（OR）；仅一个受限时用它；都不受限时每天触发。例如 `0 0 1,15 * 1` 表示每月 1 日、15 日**以及**每个周一触发。
- **受限判定**：字段只有为纯 `*` 时才视为“不受限”；`*/n`、`a-b`、列表均视为受限。
- **下次运行计算**：从 `now` 的下一分钟边界起，逐日扫描（日内按 hour×minute 枚举匹配时刻），最多迭代 100000 天（仅兜底，可满足表达式 + `count≤10` 永不触顶）。可满足性预判会提前拦截“日/月无可行组合”的永不触发表达式（如 `0 0 30 2 *`，2 月没有 30 日）并返回 `ok:false`。
- 所有结果按 `tz`（默认本地）时区解释；`nextRuns` 为带时区偏移的 ISO 8601 字符串。

## 人性化描述示例

| 表达式 | 描述 |
|---|---|
| `0 9 * * *` | 每天 09:00 |
| `30 8 * * 1-5` | 每周一至五 08:30 |
| `15 * * * *` | 每小时的第 15 分钟 |
| `*/15 * * * *` | 每 15 分钟 |
| `0 0 1 jan *` | 每年1月1日 00:00 |

复杂表达式（如 dow/dom 并集、多字段组合）退化为「字段原文 + 各字段展开值」。

## 局限

- 仅支持 **5 段标准 cron**，不支持秒段，也不支持 `L`、`W`、`#`、`?` 等特殊字符。
- 「永不触发」通过“日/月可行组合”预判 + 100000 天迭代上限双重判定；闰年 `2 月 29 日` 会被正确识别为可触发（约每 4 年一次）。
- 计算按目标时区墙钟逐日推进，夏令时切换瞬间的歧义/重复墙钟时刻按定点迭代的某一侧解释。

## 自检

挂载时自动执行 5 条自检（工作日 9 点 / 每 15 分钟 / 每年 1 月 1 日 / 非法值 / 2 月 30 日永不触发），证据行输出到日志，前缀 `[dsh-cron-parse]`。

## License

MIT