dsh-when

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

安装

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

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

工具：when

参数：

返回规范值：{ 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 给出原因。

支持短语表

「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