前言¶

Agent 在执行任务时经常需要处理时间信息：当前时间是什么、某个 UTC 时间换算到某个 IANA 时区、从某个日期加一段时间后的结果、两个时间之间的时长差。如果完全交给模型心算，时区偏移、闰年、月末边界很容易出错。

下面介绍 DSH 插件 omdsh-dev/dsh-tool-time。它把时间解析、时区转换、UTC 日历运算和固定时长差收敛到 time 工具中，面向 DSH 的 profile/bundle 插件系统提供结构化时间能力。

这是什么¶

• 插件名：omdsh-dev/dsh-tool-time
• 维护方：omdsh-dev
• 许可证：MIT
• 适配：DSH 0.1.2-alpha.1（npm）profile/bundle 插件系统
• 定位：提供严格 ISO 8601 子集解析、IANA 时区转换、UTC 日历运算、固定时长差。按 README 表述，是零依赖、零进程、纯函数。

这个插件提供的核心工具名是 time，包含 now、convert、add、diff 四类操作。

核心功能¶

time 工具¶

time 工具提供以下操作：

1. now：获取当前时间，可选 timezone，默认 UTC。
2. convert：转换时间，需要 value 和 timezone。
3. add：加减时间，需要 value、amount、unit；timezone 仅用于展示。
4. diff：计算时长差，需要 from 和 to。

返回结构包含以下字段：

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

时间语义与精度¶

插件在几个边界行为上有明确约定：

• 输入年份范围为 1000–9999，0000–0999 会被拒绝。
• add 基于 UTC 日历运算，不是当地墙钟语义。
• diff 返回固定时长差，不支持自然语言日期，也不提供日历月/年差。
• iso 和 unix 保留毫秒。
• local 和 formatted 是秒精度展示字段。
• offset 精度到分钟；历史时区 <1900 的秒级 offset 会被截断。
• 时区数据来自 Node 内置 ICU，跨平台一致性依赖相同的 Node/ICU 数据。

输入校验¶

插件声明了无 eval、无 new Function 的输入校验安全模型，时间输入走严格 ISO 8601 子集解析，时区输入按 IANA 时区名处理。

安装与启用¶

先确认安装到哪个 profile。web 与 headless 是不同 profile，dsh run 默认使用 headless profile，web 安装不会自动覆盖 headless。

如果用于 web profile：

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

如果用于 dsh run，建议安装到 headless profile：

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

安装后可以按文档给出的方式验证：

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

再运行一次典型调用：

dsh run "使用 time 工具获取当前 UTC 时间"

典型用法¶

下面按操作类型说明参数边界。

now¶

now 用于获取当前时间。可以省略 timezone，默认按 UTC 处理；也可以传入 IANA 时区名用于展示。

convert¶

convert 用于把某个时间值转换到指定 IANA 时区。需要提供：

• value
• timezone

add¶

add 用于在某个时间值上增加或减少一段时间。需要提供：

• value
• amount
• unit

timezone 可以用于展示，但 add 的计算语义是 UTC 日历运算，不是当地墙钟加减。

diff¶

diff 用于计算两个时间点之间的固定时长差。需要提供：

• from
• to

它返回固定时长差，不返回自然语言日期，也不返回日历月/年差。

适用场景与注意¶

适合：

• 需要获取当前时间的 DSH 工作流。
• 需要在固定时间点之间做 UTC 日历加减的自动化任务。
• 需要把严格 ISO 时间值转换到 IANA 时区并输出结构化结果。
• 需要把时间差表达为固定时长差，而不是自然语言日期。

注意：

• add 是 UTC 日历运算，不是当地墙钟语义。
• 不支持自然语言日期。
• 不支持日历月/年差。
• 历史时区 <1900 的秒级 offset 会被截断。
• 时区一致性依赖相同 Node/ICU 数据。
• 插件以当前 dsh 进程权限运行，安装前应检查源码、依赖和许可证。
• DSH 社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。

链接¶

• 社区目录页：https://www.skillhub.cn/plugins/omdsh-dev/dsh-tool-time
• GitHub：https://github.com/omdsh-dev/dsh-tool-time