前言¶
在 DeepSeek Harness（DSH）裏跑智能體或自動化工作流時，進程往往一直活着，但任務可能已經停在某一步：等 API、等用戶、或邏輯死循環。只看進程是否存活，無法區分「還在跑」和「已經卡住」。社區插件 dsh-task-heartbeat 把關注點放在任務進度：註冊長任務、在有意義的一步完成後打點（beat），當最後一次 beat 超過閾值時，把它列入 stalled 列表，而不是做簡單的存活探測。
這是什麼¶
dsh-task-heartbeat 是 DSH 生態中的工作流類插件，由 jerentpan-lab 維護（npm 作者名 jetpan）。倉庫與 npm 包同名，許可證 MIT，當前 package 版本 0.2.0。簡介原文：Task heartbeat for DeepSeek Harness: progress beats and stall detection, not mere liveness.
插件通過 Cordis patch（cordis.patch.yml）向 DSH 暴露一組工具，狀態持久化到本地 JSON 文件，適合配合定時任務做巡檢。
核心功能¶
README 中的設計動機寫得很直接：智能體可以 alive 但仍 stuck；若任務 15 分鐘沒有產生 beat，即使進程仍在運行，也應視爲 stalled。
插件提供的工具（名稱與參數以 README 爲準）：
task_register：{ taskId, owner, expect?, ttlS? }— 註冊進行中的長任務；未傳ttlS時使用配置裏的默認閾值。task_beat：{ taskId, note? }— 每完成一個有意義的步驟後打點，可選附 note。task_check— 列出已超過 TTL 仍未 beat 的 stalled 任務。task_list— 列出當前登記的任務。task_done：{ taskId }— 標記任務結束。
taskId 僅允許 [A-Za-z0-9_-]{1,64}；註冊時必須提供 owner。若同一 taskId 已在運行，需 force:true 才能重啓登記。
配置（0.2.0）¶
默認配置示例：
{ "stateFile": "~/.dsh/task-heartbeat.json", "defaultTtlS": 900 }
stateFile：心跳狀態文件路徑，默認~/.dsh/task-heartbeat.json；環境變量DSH_TASK_HEARTBEAT_FILE可覆蓋。defaultTtlS：task_register未指定ttlS時的默認 stall 閾值（秒），示例爲 900（15 分鐘）。
未知配置鍵或非法值會拋出可讀的 ConfigError；可參考倉庫中的 config.example.json。README 建議本地開發時運行 npm run verify 做測試與打包檢查。
性能方面，README 的 Bench 說明：每次 beat 是一次帶 fsync 的持久化寫入（作者在示例主機上約 97ms/beat），因此 beat 頻率應貼合任務自然步進，不宜無意義高頻調用。
安裝與啓用¶
從 npm 安裝（README 給出的命令）：
dsh plugin --profile web add dsh-task-heartbeat
若要從 GitHub 源安裝，README 另給出：
dsh plugin --profile web add github:jerentpan-lab/dsh-task-heartbeat
安裝後，可在宿主機上每 5 分鐘跑一次檢查（README 以 Python heredoc 示意，實際需通過你的 DSH session / CLI 調用 task_check）：
python3 - <<'PY'
# call task_check via your DSH session / CLI
PY
本地可運行演示：
node examples/demo.mjs
典型用法流程¶
下面介紹一種與 README 一致的用法順序，便於在長任務 Agent 流程裏落地。
- 任務開始時調用
task_register，傳入taskId、owner，按需設置expect（預期說明）和ttlS（秒）。 - 每完成一個可對外說明的里程碑，調用
task_beat，必要時用note記錄當前階段。 - 由 cron 或調度器週期性調用
task_check，處理返回的 stalled 列表（告警、重試或人工介入）。 - 任務正常結束時調用
task_done。
狀態文件若損壞，插件會 quarantine（*.corrupt-*）並告警，工具仍可繼續工作；若系統時鐘回撥，會通過 monotonic clamp 避免年齡爲負。
常見問題（節選）¶
README 故障表中的典型項：
| 現象 | 原因 | 處理 |
|---|---|---|
ConfigError ... unknown key |
配置鍵拼寫或不支持 | 對照 config.example.json |
ConfigError ... defaultTtlS |
非有限正數 | 使用秒數，如 900 |
taskId must match ... |
ID 含非法字符 | 僅用 [A-Za-z0-9_-]{1,64} |
register: owner is required |
未傳 owner | 註冊時帶上 owner |
could not acquire lock ... |
其他進程持鎖超過 30s | 重試；檢查陳舊鎖文件 |
適用場景與注意¶
適合：多步驟、耗時的 DSH 工作流；需要區分「進程還在」與「進度還在推進」的 Agent 任務；希望用固定間隔的 task_check 做 stall 巡檢的場景。
注意：
- 插件在當前 DSH 進程權限下讀寫狀態文件與加鎖，安裝前請閱讀 GitHub 源碼 與 MIT 許可證，確認符合你的安全與合規要求。
- DSH 採用「一切皆插件」的擴展方式；社區目錄 SkillHub 插件頁 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係，不要將其等同於官方應用商店。
結尾¶
dsh-task-heartbeat 把長任務的觀測從「進程是否存活」推進到「進度是否在 beat」：註冊、打點、按 TTL 列出 stalled，配置簡單，工具面清晰。需要細節、演示與 Bench 說明時，以倉庫 README 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/jerentpan-lab/dsh-task-heartbeat
- GitHub：https://github.com/jerentpan-lab/dsh-task-heartbeat
