前言¶

在 DeepSeek Harness (DSH) 的开发场景中，模型输出往往包含自然语言时间表述，例如“明天 9 点”或“2 小时后”。调度或提醒逻辑需要将这些模糊的时间点转换为精确的 ISO 8601 时间戳。dsh-when 插件专注于解决这一解析需求，它将中文自然语言相对时间短语解析为标准时间格式，并注册一个 when 工具供其他插件调用。

插件定位¶

dsh-when 是一个纯 ESM 模块，零依赖且无需构建。由 ZhijiangTang 维护，采用 MIT 许可证。它通过挂载一个 when 工具，为智能体提供从自然语言到机器可读时间的转换能力。

安装与启用¶

在 DSH 配置文件中添加该插件：

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

安装完成后，插件会自动挂载 when 工具层（层 id 为 when）。

工具能力¶

when 工具接收自然语言时间短语，返回包含解析结果和元数据的对象。

参数说明：

返回规范值：

• ok: 布尔值，解析成功或失败。
• iso: UTC ISO 8601 字符串（带 Z）。
• local: 目标时区本地 ISO 字符串（带 ±HH:MM 偏移）。
• relativeSeconds: 目标时刻相对 now 的秒数（目标 − now，可为负）。
• matchedPattern: 命中的模式名（day-offset / duration / weekday / clock-time / iso）。
• errors: 失败时的错误原因。

支持的短语模式¶

插件仅支持以下列出的短语形态，不进行模糊语义猜测。

工作原则与自检¶

该插件遵循 fail-fast 原则，即只解析明确支持的短语。任何无法识别的输入（例如“随便什么”或超出短语表的组合）都会返回 ok:false，并在 errors 中给出完整支持列表提示。这种机制避免了模糊语义导致的错误调度。

插件在挂载时会自动执行 4 条自检（测试短语：明天 9 点、2 小时后、下周一 9 点、不支持短语），证据行输出到日志，前缀为 [dsh-when]。

生态配合¶

该插件常与调度类插件配合使用：
- dsh-cron-parse: 用于解析结构化的周期性规则（Cron 表达式）。
- dsh-scheduler: 用于执行具体的调度任务。

两者的分工是：dsh-cron-parse 负责周期性计划，dsh-when 负责一次性自然语言时刻的解析。dsh-when 输出的 ISO 时刻可直接作为触发点。

注意事项与局限¶

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

结语¶

dsh-when 提供了在 DSH 生态中将中文自然语言转换为 ISO 时间戳的标准化方案。对于需要处理用户输入时间或模型生成时间描述的场景，该插件可以作为工具链中的一环，确保时间计算的准确性。更多细节可参考 GitHub 仓库 或 DSH 目录页。