前言¶
DeepSeek Harness（DSH）採用插件化架構，允許開發者根據需求擴展功能。在構建自動化智能體或工作流時，常遇到需要定時執行命令、記錄執行歷史以及處理失敗重試的場景。dsh-delivery-ledger 插件正是爲此設計，它將定時任務調度與投遞臺賬（Delivery Ledger）結合，借鑑了 Hermes Agent 的 delivery_obligations 治理邏輯。
插件定位¶
這是一個定時任務執行器與投遞臺賬。插件會爲每次任務執行生成臺賬行，支持按狀態查詢，並提供補發機制。其核心價值在於窗口對齊去重與 Hermes 風格的重發語義，確保重複任務不會因進程抖動而重複執行。
核心功能¶
ledger_create：註冊定時任務，指定執行的命令和間隔秒數。插件自帶調度器，按窗口對齊觸發。ledger_list：查詢檯賬，支持按狀態過濾（ok/failed/abandoned）。ledger_retry：補發最近失敗或放棄的窗口。重發時 attempt 遞增，dueAt 保持不變。
設計與限制¶
- 存儲方式：臺賬採用 append-only JSONL 格式，存儲在
$DSH_HOME/ledger/<task-id>.jsonl。 - 執行機制：窗口對齊（interval 邊界）+ 同窗口去重，防止進程抖動導致重複執行。命令通過
/bin/sh -c執行，超時時間爲 10s。 - 調度狀態：任務註冊表僅在內存中，跨進程不持久調度（v1 邊界）。
- 無依賴：零網絡、零 LLM 調用，純本地執行。
安裝與啓用¶
在 DSH 環境中安裝該插件：
dsh plugin --profile web add "github:leetom314/dsh-delivery-ledger#main"
典型用法¶
- 註冊任務：調用
ledger_create接口，傳入命令和間隔時間。 - 查看臺賬：調用
ledger_list接口，傳入過濾條件（如僅查看 failed 狀態）。 - 補發重試：調用
ledger_retry接口，對指定任務進行重發。
適用場景與注意¶
該插件適合需要嚴格審計和去重控制的定時任務場景。使用時需注意：
* 任務調度目前僅在內存中，進程重啓後註冊的任務會丟失（v1 版本限制）。
* 代碼執行依賴當前 DSH 進程的權限。
* 建議在安裝前檢查源碼與許可證（MIT）。
結尾¶
以上介紹了 dsh-delivery-ledger 的核心功能與使用方式。更多細節可查看插件目錄頁或 GitHub 倉庫。
