dsh-when

Readme

# dsh-when

DSH 插件：把**中文自然语言相对时间短语**解析成 **ISO 时间戳**，注册一个 `when` 工具。纯 ESM、零依赖、无构建。

## 安装

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

安装后组合层挂载 `when` 工具（`when` 层 id）。

## 工具：`when`

参数：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `text` | string | 是 | 自然语言时间短语，如 `明天 9 点`、`2 小时后`、`下周一 9 点`、`18:30` 或 ISO 8601 |
| `tz` | string | 否 | IANA 时区名（如 `Asia/Shanghai`、`UTC`），默认本地时区；无效时区返回规范错误 |
| `now` | string | 否 | ISO 8601 基准时间，默认当前时间 |

返回规范值：`{ ok, text, iso, local, relativeSeconds, matchedPattern, errors }`

- `iso`：UTC ISO 8601 字符串（带 `Z`）。
- `local`：目标时区本地 ISO 字符串（带 `±HH:MM` 偏移）。
- `relativeSeconds`：目标时刻相对 `now` 的秒数（目标 − now，可为负）。
- `matchedPattern`：命中的模式名（`day-offset` / `duration` / `weekday` / `clock-time` / `iso`）。
- 失败时 `ok:false`，`iso/local/relativeSeconds/matchedPattern` 为 `null`，`errors` 给出原因。

## 支持短语表

| 模式名 | 短语 | 说明 |
|---|---|---|
| `day-offset` | 今天 / 明天 / 后天 `[HH:MM\|HH点\|上午\|下午\|中午\|晚上]` | 上午=9 点、下午=15 点、中午=12 点、晚上=20 点；缺时间默认 9 点 |
| `duration` | `N` 分钟后 / 小时后 / 天后 / 周后 | `N` = 阿拉伯数字或中文数字「一到十」 |
| `weekday` | 下周X / 周X `[HH:MM\|HH点]` | 本周已过的周 X 自动取下周；缺时间默认 9 点 |
| `clock-time` | `HH:MM` | 纯时刻 = 今天该时刻，已过则明天 |
| `iso` | ISO 8601 | `2026-08-16T09:00:00`、`2026-08-16T09:00Z`、带 `±HH:MM` 偏移、或纯日期（按 00:00 解释） |

## 「fail-fast 不猜语义」原则

本工具**只解析明确支持的短语**。任何无法识别的输入（例如 `随便什么`、`明天上午9点` 这种超出短语表的组合）都会返回 `ok:false`，并在 `errors` 中给出完整支持列表提示——**绝不根据模糊语义“猜”一个时间**，避免给下游（调度、提醒）埋下错误时间的隐患。

## 与 dsh-cron-parse 配套场景

- `dsh-cron-parse` 解析 **cron 表达式**（结构化、周期性规则）并预览未来运行时刻。
- `dsh-when` 解析**一次性自然语言相对时间**（“明天 9 点”“2 小时后”）得到具体时刻。
- 两者互补：cron 表达周期性计划，`when` 表达单次时刻；`when` 的产物（ISO 时刻）可直接作为 `dsh-scheduler` 之类调度插件的一次性触发点。

## 自检

挂载时自动执行 4 条自检（明天 9 点 / 2 小时后 / 下周一 9 点 / 不支持短语），证据行输出到日志，前缀 `[dsh-when]`。

## 局限

- 仅支持上表列出的短语形态，不支持“半小时后”“上午 9 点 30 分”等组合或口语化表述（fail-fast）。
- ISO 无时区信息时按 `tz`（默认本地）墙钟解释；带 `Z`/偏移时按绝对时刻透传。
- 夏令时切换瞬间的歧义/重复墙钟时刻按定点迭代的某一侧解释（与 dsh-cron-parse 一致）。

## License

MIT