omdsh-dev/dsh-tool-time
40Last commit Aug 14, 2026
dsh-tool-time DSH plugin
dsh-tool-time is a DSH plugin that provides reliable time handling for AI agents. It offers strict ISO 8601 parsing, IANA timezone conversion, UTC calendar arithmetic with month clamping, and fixed duration difference calculation. The plugin is zero-dependency, uses no subprocesses, and has no eval or new Function, ensuring safety and consistency across platforms.
How to install the dsh-tool-time DSH plugin
dsh plugin --profile web add github:omdsh-dev/dsh-tool-timeCopying does not run this command. Review the repository and version before installing the dsh-tool-time DSH plugin.
dsh-tool-time DSH plugin data source
dsh-tool-time DSH plugin snapshot date: Aug 16, 2026
discovered
What the dsh-tool-time DSH plugin can do
- Strict ISO 8601 parsing and validation (rejects natural language, RFC 2822, etc.)
- IANA timezone conversion using Intl API (display only; UTC internally)
- UTC calendar arithmetic with month/year clamping (e.g., Jan 31 + 1 month = Feb 28)
- Fixed duration difference calculation (no months/years; sign + absolute decomposition)
- Zero external dependencies, pure functions, no subprocesses
Where the dsh-tool-time DSH plugin fits
- Get current UTC or timezone-specific time for agent responses
- Convert a timestamp from one timezone to another (e.g., UTC to Asia/Shanghai)
- Add or subtract a duration (seconds, days, months, etc.) to a date
- Compute the exact difference between two timestamps in milliseconds
Who the dsh-tool-time DSH plugin is for
- DSH agent developers who need reliable, cross-platform time handling
- Users who interact with agents requiring time-aware operations (e.g., scheduling, date math)
dsh-tool-time DSH plugin limitations
- Peer dependencies (e.g., @deepseek-ai/dsh-tools) are private npm packages; not publicly installable
- `add` operates on UTC calendar, not local wall-clock time (v2 planned)
- Natural language dates (e.g., 'next week') are not supported
- Year range limited to 1000–9999; historical timezone offsets (pre-1900) truncated to minute precision
dsh-tool-time DSH plugin: from the repository README
Quoted from the omdsh-dev/dsh-tool-time README, the upstream source of the dsh-tool-time DSH plugin. Copyright remains with the original authors.
DSH 时间工具插件 —— 严格 ISO 解析、IANA 时区转换、UTC 日历运算、固定时长差。零依赖、零进程、纯函数。 [](LICENSE) ## 动机 Agent 处理时间信息是最高频需求之一——"现在几点"、"3 天后是几号"、"把 UTC 转成北京时间"。当前做法 `bash date` 的问题：每次起进程、跨平台语法不一致（macOS 与 GNU `date -d` 完全不同）、时区转换靠 `TZ=...` 手动拼。模型心算时区偏移和闰年/DST 边界是错误高发区。 ## 安全模型 无 `eval`、无 `new Function`。输入只经过严格校验： - **严格 ISO 8601 子集**：仅接受 `YYYY-MM-DD`（UTC 零点）、`YYYY-MM-DDTHH:mm:ssZ`、`YYYY-MM-DDTHH:mm:ss±HH:MM`（±14:00 内，可选 `.SSS` 毫秒）；不带时区的日期时间、RFC 2822、自然语言日期一律拒绝；`2026-02-30` 等日历溢出由查表校验拒绝（不依赖 Date 的静默归一化） - **时区名**：IANA 名交给 `Intl.DateTimeFormat` 校验，非法即抛 `time: unknown timezone` - **数值**：`amount` 必须是安全整数；`unit` 枚举白名单；所有字符串 ≤200 字符 - **Intl 环境固定**：`'en-CA'` + `hourCycle: 'h23'`（避免午夜 `24:00` 与本地化数字） ## 架构 ``` DSH Agent │ ctx.tools.register() ▼ src/index.ts（Cordis 插件入口 + action 分发 + 独立校验） │ ▼ src/time.ts ├── parseStrictISO() — 严格 ISO 解析（正则 + 查表校验） ├── formatInTimezone() — Intl formatToParts 组装（时钟可注入） ├── addMonthsClamped() — 先置 1 日 → 目标年月 → 天数钳制 └── diffBetween() — 固定时长（sign + absolute 分解） ``` ## 工具声明 ```ts ctx.tools.register(defineTool({ name: 'time', parameters: { action: { type: 'string', required: true
Read the full READMERepository license: MIT
dsh-tool-time DSH plugin questions
How do I install dsh-tool-time?
Use the `dsh plugin` command. For example, to install it in the web profile: `dsh plugin --profile web add github:omdsh-dev/dsh-tool-time`. You can also install from a local tarball by running `npm pack` in the repo and then `dsh plugin --profile web add ./dsh-tool-time-<version>.tgz`. Remember that web and headless are separate profiles.
What time formats does this plugin accept?
It accepts a strict subset of ISO 8601: `YYYY-MM-DD` (UTC midnight), `YYYY-MM-DDTHH:mm:ssZ`, and `YYYY-MM-DDTHH:mm:ss±HH:MM` (with optional `.SSS` milliseconds). It does not accept natural language dates, RFC 2822, or date-time without a timezone. Calendar overflow like `2026-02-30` is rejected by lookup validation.
How do I specify a timezone?
Use a valid IANA timezone name, e.g., `Asia/Shanghai`. The plugin validates it via `Intl.DateTimeFormat`. If the timezone is omitted, UTC is used as default. Note that `add` and `diff` operations are UTC-based; the timezone only affects the `local` and `formatted` display fields.
Does the `add` operation use UTC or local time?
`add` always operates on UTC calendar time. This means calendar day semantics are preserved across DST boundaries. The `timezone` parameter only determines how the result is displayed in `local` and `formatted` fields. If you need local wall-clock arithmetic, that is planned for v2.
Why doesn't `diff` support months or years?
Months and years have variable lengths, so they cannot be uniquely derived from a millisecond duration. The `diff` action returns a fixed duration with sign and absolute decomposition (seconds, minutes, hours, days, weeks). If the duration exceeds the safe integer range, it throws an error.