In DeepSeek Harness (DSH) development, agents often need to handle scheduled tasks. Whether setting daily reminders or implementing complex scheduling logic, parsing Cron expressions, validating their correctness, and predicting future trigger times are common requirements. Writing parsing logic manually is both tedious and error-prone. The following introduces the dsh-cron-parse plugin, which provides a complete solution.

Plugin Positioning

This is a DSH plugin maintained by ZhijiangTang. Its core function is to parse 5-field standard Cron expressions (minute, hour, day of month, month, day of week), and provide validation, human-readable Chinese descriptions, expanded values for each field, and previews of future run times. It is designed as a pure ESM module with zero dependencies and no build step required.

Core Capabilities

  1. Syntax support
    Supports multiple syntax forms:

    • *: all values
    • */n: every n units (starting from the minimum value)
    • a-b: inclusive range
    • a-b/n: step within a range
    • Lists: union of multiple values (e.g. 1,15,30)
    • Names: month names or day-of-week names (e.g. jan-dec, sun-sat), case-insensitive

    Field ranges: minute 0-59, hour 0-23, day 1-31, month 1-12, day of week 0-7 (both 0 and 7 mean Sunday).

  2. Semantic logic
    Uses classic Vixie semantics:

    • Union triggering: When both day of month and day of week are restricted, a day triggers if it matches either one (OR logic); it also works when only one is restricted; when neither is restricted, it triggers every day.
    • Never-trigger detection: A dual determination based on a “day/month feasible combination” precheck and a 100,000-day iteration limit. For example, 0 0 30 2 * (February 30) is detected as never triggering.
    • Time calculation: Advances day by day according to wall-clock time in the target time zone. Daylight saving time switches are interpreted with fixed-point iteration.

  3. Self-check mechanism
    When the plugin is mounted, it automatically runs 5 self-checks, writes evidence lines to the log, with prefix [dsh-cron-parse].

Installation and Enablement

In a DSH environment, run the following command to install the plugin:

dsh plugin --profile <name> add file:./plugins/dsh-cron-parse

After installation, the composition layer mounts the cron_parse tool.

Typical Usage

When invoking the cron_parse layer, parameters must be provided. The parameters are as follows:

  • expression (required): a 5-field standard cron string.
  • count (optional): number of future runs, range 1–10, default 5.
  • tz (optional): IANA time zone name (e.g. Asia/Shanghai, UTC), default local time zone.
  • now (optional): ISO 8601 base time, default current time.

The tool returns a canonical value containing the following fields: ok, valid, description (Chinese description), fields (expanded values for each field), nextRuns (list of future run times), timezone, errors.

Use Cases and Notes

  • Use cases: scenarios in DSH agent development that require handling scheduled task dispatch, Chinese output of cron meaning, and validation of expression legality.
  • Limitations: supports only 5-field standard cron; does not support seconds, and does not support special characters such as L, W, #, and ?.
  • Notes: the plugin runs with the permissions of the current DSH process; it is recommended to check the source code and license (MIT) before installation.

With its zero-dependency and pure ESM design, the plugin provides end-to-end capabilities from parsing to preview.