leetom314/dsh-delivery-ledger

dsh-delivery-ledger

Recurring task scheduler with a delivery ledger — 定时任务执行器 + 投递台账。 移植 Hermes Agent 的 delivery_obligations 治理:每次任务执行都留台账行,失败可查可补发,同窗口去重。

What it does

• ledger_create — 注册定时任务(命令 + 间隔秒)。插件自带调度器,按窗口对齐触发,不依赖 dsh-schedule(那是会话内提醒)。
• ledger_list — 查台账,支持按状态过滤(ok/failed/abandoned)。
• ledger_retry — 补发最近的失败/放弃窗口(redeliver 语义:attempt 递增,同一 dueAt)。

设计

• 台账 append-only JSONL,存 $DSH_HOME/ledger/<task-id>.jsonl(经 dshHomePath)。
• 窗口对齐(interval 边界)+ 同窗口去重:进程抖动不会重复执行。
• Hermes redeliver 语义:retry 补的是失败的窗口而非新跑当前时刻。
• 零网络零 LLM;命令执行走 /bin/sh -c,10s 超时。
• 任务注册表在内存(跨进程不持久调度——v1 边界,GOAL.md 有声明)。

验证

单测 node --test(ledger.js 行覆盖 100%);真实 headless e2e:

• 5s 任务 sleep 13s → 4 行 ok(每窗口 1 次,去重生效)
• gate 文件场景 → 3 行 failed → touch 开闸 → retry → 同 dueAt attempt 2 ok

安装/开发

# from GitHub (requires dsh CLI)
dsh plugin --profile web add "github:leetom314/dsh-delivery-ledger#main"

# or clone and verify locally first
git clone https://github.com/leetom314/dsh-delivery-ledger.git
cd dsh-delivery-ledger && ./setup.sh && ./verify.sh   # 一键真实 e2e(隔离 DSH_HOME)

verify.sh 动态生成临时 overlay($HERE/index.js 路径),不需要仓库内 overlay 文件——overlay*.yml 已 gitignore(含本机绝对路径,不随版本库分发)。