前言¶

在 DeepSeek Harness (DSH) 的開發場景中，模型輸出往往包含自然語言時間表述，例如“明天 9 點”或“2 小時後”。調度或提醒邏輯需要將這些模糊的時間點轉換爲精確的 ISO 8601 時間戳。dsh-when 插件專注於解決這一解析需求，它將中文自然語言相對時間短語解析爲標準時間格式，並註冊一個 when 工具供其他插件調用。

插件定位¶

dsh-when 是一個純 ESM 模塊，零依賴且無需構建。由 ZhijiangTang 維護，採用 MIT 許可證。它通過掛載一個 when 工具，爲智能體提供從自然語言到機器可讀時間的轉換能力。

安裝與啓用¶

在 DSH 配置文件中添加該插件：

dsh plugin --profile <name> add file:./plugins/dsh-when
# 或在 npm 發佈後直接安裝：
# dsh plugin --profile <name> add dsh-when

安裝完成後，插件會自動掛載 when 工具層（層 id 爲 when）。

工具能力¶

when 工具接收自然語言時間短語，返回包含解析結果和元數據的對象。

參數說明：

返回規範值：

• ok: 布爾值，解析成功或失敗。
• iso: UTC ISO 8601 字符串（帶 Z）。
• local: 目標時區本地 ISO 字符串（帶 ±HH:MM 偏移）。
• relativeSeconds: 目標時刻相對 now 的秒數（目標 − now，可爲負）。
• matchedPattern: 命中的模式名（day-offset / duration / weekday / clock-time / iso）。
• errors: 失敗時的錯誤原因。

支持的短語模式¶

插件僅支持以下列出的短語形態，不進行模糊語義猜測。

工作原則與自檢¶

該插件遵循 fail-fast 原則，即只解析明確支持的短語。任何無法識別的輸入（例如“隨便什麼”或超出短語表的組合）都會返回 ok:false，並在 errors 中給出完整支持列表提示。這種機制避免了模糊語義導致的錯誤調度。

插件在掛載時會自動執行 4 條自檢（測試短語：明天 9 點、2 小時後、下週一 9 點、不支持短語），證據行輸出到日誌，前綴爲 [dsh-when]。

生態配合¶

該插件常與調度類插件配合使用：
- dsh-cron-parse: 用於解析結構化的週期性規則（Cron 表達式）。
- dsh-scheduler: 用於執行具體的調度任務。

兩者的分工是：dsh-cron-parse 負責週期性計劃，dsh-when 負責一次性自然語言時刻的解析。dsh-when 輸出的 ISO 時刻可直接作爲觸發點。

注意事項與侷限¶

1. 語法限制: 僅支持上表列出的短語形態，不支持“半小時後”、“上午 9 點 30 分”等組合或口語化表述。
2. 時區解釋:
   • ISO 字符串無時區信息時，按 tz（默認本地）牆鍾解釋。
   • ISO 字符串帶 Z 或偏移時，按絕對時刻透傳。
3. 夏令時: 夏令時切換瞬間的歧義/重複牆鍾時刻，按定點迭代的某一側解釋（與 dsh-cron-parse 保持一致）。

結語¶

dsh-when 提供了在 DSH 生態中將中文自然語言轉換爲 ISO 時間戳的標準化方案。對於需要處理用戶輸入時間或模型生成時間描述的場景，該插件可以作爲工具鏈中的一環，確保時間計算的準確性。更多細節可參考 GitHub 倉庫 或 DSH 目錄頁。