omdsh-dev/dsh-tool-time
40最近提交 2026年8月14日
dsh-tool-time DSH 插件
dsh-tool-time 是一款 DSH 插件，为 AI Agent 提供可靠的时间处理能力。它支持严格 ISO 8601 解析、IANA 时区转换、带月份钳制的 UTC 日历运算以及固定时长差计算。插件零依赖、无子进程、无 eval 或 new Function，确保跨平台的一致性。
如何安装 dsh-tool-time DSH 插件
dsh plugin --profile web add github:omdsh-dev/dsh-tool-time复制不会执行命令。安装 dsh-tool-time DSH 插件前请核对仓库和版本。
dsh-tool-time DSH 插件数据来源
dsh-tool-time DSH 插件快照日期：2026年8月16日
discovered
dsh-tool-time DSH 插件能做什么
- 严格 ISO 8601 解析与校验（拒绝自然语言、RFC 2822 等）
- IANA 时区转换（使用 Intl API，仅影响展示，内部 UTC）
- UTC 日历运算，带月份/年份钳制（如 1 月 31 日 + 1 个月 = 2 月 28 日）
- 固定时长差计算（无月/年，带符号与绝对余数分解）
- 零外部依赖、纯函数、无子进程
dsh-tool-time DSH 插件适合哪些场景
- 获取当前 UTC 或指定时区的时间，用于 Agent 回复
- 将时间戳从一个时区转换到另一个时区（如 UTC 转北京时间）
- 对日期加减一个持续时间（秒、天、月等）
- 精确计算两个时间戳之间的毫秒差
dsh-tool-time DSH 插件适合谁
- 需要可靠跨平台时间处理的 DSH Agent 开发者
- 与需要时间感知能力的 Agent 互动的用户（如日程、日期运算）
dsh-tool-time DSH 插件的限制
- peer 依赖（如 @deepseek-ai/dsh-tools）为 npm 私有包，无法公开安装
- `add` 操作基于 UTC 日历，非当地墙钟语义（v2 计划支持）
- 不支持自然语言日期（如“下周”）
- 年份范围限制为 1000–9999；历史时区偏移（1900 年前）截断到分钟精度
dsh-tool-time DSH 插件的仓库 README 摘录
以下文字摘自 dsh-tool-time DSH 插件的上游仓库 omdsh-dev/dsh-tool-time 的 README，版权归原作者，仅作引用。
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
阅读完整 README仓库许可: MIT
dsh-tool-time DSH 插件常见问题
如何安装 dsh-tool-time？
使用 `dsh plugin` 命令。例如，在 web profile 中安装：`dsh plugin --profile web add github:omdsh-dev/dsh-tool-time`。也可以先在仓库中运行 `npm pack` 生成 tarball，然后执行 `dsh plugin --profile web add ./dsh-tool-time-<version>.tgz`。注意 web 和 headless 是不同 profile，需要分别安装。
插件支持哪些时间格式？
接受严格 ISO 8601 子集：`YYYY-MM-DD`（UTC 零点）、`YYYY-MM-DDTHH:mm:ssZ` 和 `YYYY-MM-DDTHH:mm:ss±HH:MM`（可选 `.SSS` 毫秒）。不支持自然语言日期、RFC 2822 或不带时区的日期时间。像 `2026-02-30` 这样的日历溢出会通过查表校验拒绝。
如何指定时区？
使用有效的 IANA 时区名称，例如 `Asia/Shanghai`。插件通过 `Intl.DateTimeFormat` 进行校验。如果省略时区，默认为 UTC。注意 `add` 和 `diff` 操作基于 UTC，时区仅影响 `local` 和 `formatted` 展示字段。
`add` 操作是基于 UTC 还是本地时间？
`add` 始终基于 UTC 日历时间运算，以保证跨 DST 的日历日语义一致。`timezone` 参数仅决定 `local` 和 `formatted` 的展示方式。如果需要当地墙钟语义，v2 版本计划支持。
为什么 `diff` 不支持月或年？
月和年的长度不固定，无法从毫秒差唯一推导。`diff` 返回固定时长差，包含符号和绝对余数分解（秒、分钟、小时、天、周）。如果差值超过安全整数范围，会抛出错误。