前言¶
DeepSeek Harness (DSH) 是一個以插件爲中心的框架。在開發智能體應用時，經常會遇到需要週期性執行任務或處理定時觸發器的場景。cofy-x/dsh-cron 插件解決了這個問題，它是一個爲 DSH Automation 提供的持久化日曆觸發器適配器，能夠將一次性或重複的日曆事件轉化爲冪等的會話運行。
它是什麼¶
- 名稱: cofy-x/dsh-cron
- 分類: 工作流
- 簡介: 提供 DSH Automation 的定時任務能力，支持模型調用和 Shell 命令管理，可向 Agent 會話注入後續任務。
- 許可證: MIT
安裝與前置要求¶
安裝前需要確認環境滿足以下條件：
* Node.js 24 或更高版本
* DSH 版本 0.1.5-rc.1 或更高版本（0.1.x 系列）
* dsh-automation 0.2.x
先安裝 dsh-automation，再安裝本插件。命令如下：
dsh plugin --profile web add dsh-automation@next
dsh plugin --profile web add @cofy-x/dsh-cron
核心功能¶
該插件主要提供以下能力：
- 靈活的調度格式：支持標準的五字段 Cron 表達式、RFC 3339 時間戳以及 IANA 時區，支持夏令時計算。
- 雙重管理方式：提供 Shell 命令（如
/cron add）和 Model Tools（如cron_add、cron_update、cron_list、cron_remove）供用戶管理任務。 - 持久化與冪等性：每次日曆觸發都會持久化運行記錄，即使進程在提交後崩潰重啓，也能根據作業 ID 和時間戳恢復，保證冪等的會話運行。
- 容錯策略：採用 “Latest-only catch-up” 策略，錯過 recurring 任務的舊時間點不會重播，僅執行最新的到期任務；一次性任務觸發後保留歷史。
- 瀏覽器任務中心：通過
dsh.clientmanifest 爲瀏覽器提供任務管理界面。
使用示例¶
通過 Shell 命令創建任務非常直觀。以下是一些典型用法：
# 每週一到週五的上午 9 點總結項目狀態
/cron add 0 9 * * 1-5 Summarize the project status
# 設置上海時區，每週五下午 6 點 30 分準備週報
/cron add tz=Asia/Shanghai 30 18 * * 5 Prepare the weekly report
# 設置具體的執行時間（RFC 3339 格式）
/cron add-at 2026-09-01T09:00:00+08:00 Run the release checklist
管理任務（暫停、恢復、刪除）的命令如下：
/cron pause cron-1
/cron resume cron-1
/cron remove cron-1
配置與限制¶
插件提供了以下配置項（默認值）：
| Key | Default | Meaning |
|---|---|---|
dataDir |
$DSH_HOME/cron |
持久化作業存儲和調度器鎖目錄 |
defaultTimeZone |
host zone | Cron 表達式未指定時使用的時區 |
maxJobs |
64 |
最大活躍作業數 |
minIntervalMinutes |
1 |
最小 recurring 間隔（分鐘） |
defaultCwd |
none | 瀏覽器/API 任務的絕對回退工作目錄 |
reconcilePollMs |
1000 |
Automation 事件流輪詢間隔 |
maxRunHistory |
100 |
每個作業保留的終端運行歷史 |
併發限制方面，每個作業使用 cron:<job-id> 作爲併發鍵，默認限制爲 1 個併發作業。最大活躍作業數爲 64。
總結¶
cofy-x/dsh-cron 是一個爲 DeepSeek Harness 提供可靠定時任務能力的插件。它通過持久化記錄和冪等性設計，確保了任務調度的穩定性，適合需要在 Agent 工作流中集成周期性邏輯的場景。
