前言¶

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