Introduction¶

In the development scenarios of DeepSeek Harness (DSH), model outputs often contain natural-language time expressions, such as “明天 9 点” or “2 小时后”. Scheduling or reminder logic needs to convert these ambiguous time points into precise ISO 8601 timestamps. The dsh-when plugin focuses on addressing this parsing need: it parses Chinese natural-language relative-time phrases into a standard time format and registers a when tool for other plugins to call.

Plugin Positioning¶

dsh-when is a pure ESM module with zero dependencies and no build step required. It is maintained by ZhijiangTang and released under the MIT License. By mounting a when tool, it provides agents with the ability to convert natural language into machine-readable time.

Installation and Enablement¶

Add the plugin to the DSH configuration file:

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

After installation, the plugin automatically mounts the when tool layer (layer ID: when).

Tool Capabilities¶

The when tool takes a natural-language time phrase and returns an object containing the parsing result and metadata.

Parameters:

Canonical return values:

• ok: Boolean, indicating whether parsing succeeded or failed.
• iso: UTC ISO 8601 string (with Z).
• local: Local ISO string in the target time zone (with a ±HH:MM offset).
• relativeSeconds: Seconds relative to now for the target time (target − now; may be negative).
• matchedPattern: Matched pattern name (day-offset / duration / weekday / clock-time / iso).
• errors: Error reasons on failure.

Supported Phrase Patterns¶

The plugin supports only the phrase forms listed below and does not make ambiguous semantic guesses.

Operating Principles and Self-Checks¶

The plugin follows a fail-fast principle: it parses only explicitly supported phrases. Any unrecognized input (for example, “随便什么” or combinations beyond the phrase table) returns ok:false and includes a full supported-list hint in errors. This mechanism prevents incorrect scheduling caused by ambiguous semantics.

When mounted, the plugin automatically performs 4 self-checks (test phrases: 明天 9 点, 2 小时后, 下周一 9 点, unsupported phrase). Evidence lines are written to the log with the prefix [dsh-when].

Ecosystem Integration¶

This plugin is commonly used together with scheduling-related plugins:
- dsh-cron-parse: Used to parse structured recurring rules (Cron expressions).
- dsh-scheduler: Used to execute specific scheduled tasks.

The division of labor is as follows: dsh-cron-parse handles recurring schedules, while dsh-when handles one-off natural-language time points. The ISO time output by dsh-when can be used directly as a trigger point.

Notes and Limitations¶

1. Syntax limitations: Only the phrase forms listed in the table above are supported; combinations or colloquial expressions such as “半小时后” or “上午 9 点 30 分” are not supported.
2. Time zone interpretation:
   • If an ISO string has no time zone information, it is interpreted as wall-clock time in tz (default: local).
   • If an ISO string includes Z or an offset, it is passed through as an absolute time.
3. Daylight saving time: Ambiguous or repeated wall-clock times around DST transitions are interpreted on one side of fixed-point iteration (consistent with dsh-cron-parse).

Conclusion¶

dsh-when provides a standardized solution for converting Chinese natural language into ISO timestamps within the DSH ecosystem. For scenarios that require handling user-provided times or model-generated time descriptions, the plugin can serve as part of the toolchain to ensure accurate time calculations. For more details, see the GitHub repository or the DSH catalog page.