dsh-delivery-ledger

README

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(含本机绝对路径,不随版本库分发)。