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

## 安装/开发

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