前言¶
在 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
