Preface¶

When executing tasks, agents often need to handle time information: what the current time is, converting a specific UTC time to an IANA timezone, the result of adding a duration to a date, or the duration difference between two times. If left entirely to the model’s mental calculation, timezone offsets, leap years, and month-end boundaries can easily lead to errors.

Below, we introduce the DSH plugin omdsh-dev/dsh-tool-time. It consolidates time parsing, timezone conversion, UTC calendar arithmetic, and fixed-duration differences into a single time tool, providing structured time capabilities for DSH’s profile/bundle plugin system.

What This Is¶

• Plugin name: omdsh-dev/dsh-tool-time
• Maintainer: omdsh-dev
• License: MIT
• Compatibility: DSH 0.1.2-alpha.1 (npm) profile/bundle plugin system
• Positioning: Provides strict ISO 8601 subset parsing, IANA timezone conversion, UTC calendar arithmetic, and fixed-duration differences. As stated in the README, it is zero-dependency, zero-process, and pure functions.

The core tool provided by this plugin is time, which includes four types of operations: now, convert, add, and diff.

Core Features¶

time Tool¶

The time tool provides the following operations:

1. now: Gets the current time, with an optional timezone, defaulting to UTC.
2. convert: Converts a time, requiring value and timezone.
3. add: Adds or subtracts time, requiring value, amount, and unit; timezone is only used for display.
4. diff: Calculates duration difference, requiring from and to.

The return structure includes the following fields:

• iso
• unix
• timezone
• timezoneSource
• local
• formatted

Time Semantics and Precision¶

The plugin has clear conventions on several edge-case behaviors:

• Input year range is 1000–9999; 0000–0999 is rejected.
• add is based on UTC calendar arithmetic, not local wall-clock semantics.
• diff returns fixed-duration differences, does not support natural language dates, and does not provide calendar month/year differences.
• iso and unix preserve milliseconds.
• local and formatted are display fields with second precision.
• offset has minute-level precision; second-level offset for historical timezones <1900 is truncated.
• Timezone data comes from Node’s built-in ICU; cross-platform consistency depends on identical Node/ICU data.

Input Validation¶

The plugin declares an input validation security model with no eval and no new Function. Time inputs go through strict ISO 8601 subset parsing, and timezone inputs are handled as IANA timezone names.

Installation and Activation¶

First, confirm which profile to install into. web and headless are different profiles; dsh run defaults to the headless profile, and installing to web will not automatically cover headless.

For the web profile:

dsh plugin --profile web add github:omdsh-dev/dsh-tool-time

For dsh run, it is recommended to install to the headless profile:

dsh plugin --profile headless add github:omdsh-dev/dsh-tool-time

After installation, you can verify as described in the documentation:

dsh --profile web --dump-config | grep tool-time

Then run a typical invocation:

dsh run "Use the time tool to get the current UTC time"

Typical Usage¶

Below describes parameter boundaries by operation type.

now¶

now is used to get the current time. You can omit timezone, which defaults to UTC; you can also pass an IANA timezone name for display.

convert¶

convert is used to convert a time value to a specified IANA timezone. You need to provide:

• value
• timezone

add¶

add is used to add or subtract a duration from a time value. You need to provide:

• value
• amount
• unit

timezone can be used for display, but the calculation semantics of add are UTC calendar arithmetic, not local wall-clock addition or subtraction.

diff¶

diff is used to calculate the fixed-duration difference between two points in time. You need to provide:

• from
• to

It returns a fixed-duration difference, not natural language dates, and not calendar month/year differences.

Applicable Scenarios and Notes¶

Suitable for:

• DSH workflows that need to get the current time.
• Automated tasks that require UTC calendar addition or subtraction between fixed points in time.
• Converting strict ISO time values to an IANA timezone and outputting structured results.
• Expressing time differences as fixed durations rather than natural language dates.

Notes:

• add is UTC calendar arithmetic, not local wall-clock semantics.
• Natural language dates are not supported.
• Calendar month/year differences are not supported.
• Second-level offset for historical timezones <1900 is truncated.
• Timezone consistency depends on identical Node/ICU data.
• The plugin runs with the current dsh process permissions; review the source code, dependencies, and license before installation.
• The DSH community directory is an independent site with no official affiliation to DeepSeek / High-Flyer.

Links¶

• Community Directory Page: https://www.skillhub.cn/plugins/omdsh-dev/dsh-tool-time
• GitHub: https://github.com/omdsh-dev/dsh-tool-time