前言¶

DeepSeek Harness (dsh) 是一個基於插件的工作流框架。在開發智能體或管理自動化任務時，經常需要系統在後臺、獨立於當前會話地執行特定指令。dsh-cron 是一個針對 DeepSeek Harness 的無人值守定時作業插件，支持在 cron 表達式、固定間隔或一次性即時時刻觸發任務。

與依賴會話的持久化提醒不同，dsh-cron 屬於主機端調度：任務屬於不與交互會話綁定的後臺進程，只要 dsh 進程運行，任務就會自動觸發。

核心功能¶

該插件提供了以下核心能力：

1. 三種觸發方式

   • cron：支持 5 字段標準表達式及顯式 IANA 時區。
   • everySeconds：基於錨點對齊的固定間隔，最小間隔爲 60 秒。
   • at：支持 RFC3339 格式的單次觸發時間。

2. 三種任務類型

   • agent：創建無頭代理，通過完整 dsh 工具鏈執行提示詞。
   • command：直接在主機上 spawn 子進程，記錄退出碼和輸出尾部。
   • callback：調用已註冊的插件回調函數。

3. 三種聲明方式

   • 通過 Profile Config 進行聲明性配置。
   • 通過 Runtime Overlay（側邊欄 + 或會話命令）聲明。
   • 通過其他插件調用 cron 服務進行註冊。

4. 可靠性保障

   • 狀態持久化存儲在 ctx.storage.domain（domain 名爲 cron）。
   • 語義爲 at-most-once，即在執行前持久化 lastFiredMs。
   • 支持時鐘紀律：長等待會被分塊處理，防止時鐘跳躍導致觸發異常。

5. 策略配置

   • overlap：當上一任務未結束時，選擇 skip（跳過）、queue（排隊）或 replace（替換）。
   • misfire：當進程掛起期間錯過的觸發，選擇 skip（忽略）或 runOnce（僅執行一次）。

安裝與啓用¶

通過以下兩種方式之一安裝插件：

1. 使用命令行安裝¶

dsh plugin --profile web add https://github.com/squirrel20/dsh-cron/releases/latest/download/dsh-cron.tgz

2. 使用插件市場¶

安裝 dsh-market 後，進入 Settings → Plugin Market，搜索 dsh-cron 並安裝。

安裝後，需將 "dsh-cron" 添加到 dsh.profile.bundles 配置中才能生效。

任務聲明方式¶

插件支持在配置文件中聲明持久化任務，或在運行時動態創建。

通過 Profile Config 聲明¶

在 Profile 的 cordis.patch.yml 中聲明，適合聲明性、版本化的常駐任務：

- id: dsh-cron
  config:
    historyLimit: 50
    jobs:
      - name: daily-log-review
        schedule: { cron: "0 7 * * *", timeZone: "Asia/Shanghai" }
        task:
          kind: agent
          prompt: Read yesterday's logs under logs/, summarize anomalies.
          cwd: /path/to/project
          timeoutSeconds: 1800
        policy: { overlap: skip, misfire: skip }
        delivery:
          argv: ["/usr/local/bin/notify", "--stdin"]
          onlyOnFailure: true
      - name: heartbeat
        schedule: { everySeconds: 3600 }
        task: { kind: command, argv: ["./scripts/heartbeat.sh"], cwd: /path/to/project }
    sessionGc:
      enabled: true
      graceMinutes: 30

注意：配置錯誤（如重複名稱、無效表達式）會在掛載時立即報錯，不會靜默失敗。

通過插件服務聲明¶

在其他插件中，可以通過 ctx.cron.registerJob 動態註冊任務。

安全與權限¶

重要：Cron 任務屬於主機管理，不屬於沙盒擴展。執行任務的工具需要 danger-full-access 權限策略和 never 審批策略。預設名稱不能單獨授權，未解析的權限策略會導致執行失敗。

Web 寫入控制¶

若需要通過 Web UI 操作，必須設置 webControlToken，且長度至少爲 32 個字符。該 Token 用於 Authorization: Bearer <webControlToken> 頭部驗證。

生成 Token 示例：

openssl rand -hex 32

注意事項：
* Web 寫入需要 HTTPS 連接。
* 配置聲明和插件註冊被視爲受信任的主機聲明，命令和交付命令在主機上執行。
* 現有手動作業如果沒有匹配授權記錄會被隔離（requiresApproval: true），需編輯並保存以授權。

適用場景與注意事項¶

• 適用場景：需要定期執行的日誌分析、健康檢查、定時通知推送、定時數據同步等後臺任務。
• 依賴項：插件依賴 zod 及多個 DeepSeek Harness 相關庫，安裝時需注意版本兼容區間。
• 生態背景：該插件由社區維護，目錄頁位於 skillhub.cn。