Auralis-Tuner/dsh-wake-scheduler

@dsh-external/dsh-wake-scheduler

DSH 插件：通用 Agent 定时唤醒调度器。Agent 只需注册一个「文件 / 进程 / 时间」条件，插件会在条件满足或超时后，用 followup() 唤醒 同一个 Agent 继续工作。

CI
License
DSH plugin

✨ 它能做什么

在 DSH 中，Agent 经常要等待外部长任务完成（下载、PDF 解析、回测、数据冻结……）。与其反复轮询，不如让插件代劳：

- 文件数量：目录下普通文件数 ≥ N 时唤醒
- 文件内容：文件包含指定字符串时唤醒
- 错误回执：目录下出现 ERROR 或无法解析的 JSON receipt 时唤醒
- 进程退出：pgrep -f 匹配不到目标进程，并持续指定宽限期后唤醒
- 纯延迟：等待 N 秒后唤醒
- 超时兜底：每个条件都可设置 timeout_seconds，到点必醒
- 同 Agent 唤醒：自动定位注册者，调用 agent.followup()

📦 安装

方式一：DSH 注入器热装配（推荐）

git clone https://github.com/Auralis-Tuner/dsh-wake-scheduler.git
在 DSH 注入器环境中
dev_build_plugin /path/to/dsh-wake-scheduler
dev_inject_plugin /path/to/dsh-wake-scheduler

方式二：profile 装配

cd /path/to/dsh-wake-scheduler
DSH_CHECKOUT= npm run build
然后将该包加入 profile 的 bundles / patch

🚀 快速开始

插件装配后，Agent 会获得 3 个工具：

schedule_wake

注册一个唤醒条件：

{
"id": "docling-complete",
"kind": "count_ge",
"path": "/Volumes/Data/out/docling_receipts",
"threshold": 12,
"message": "Docling 批次回执已到 12 个，继续收敛",
"timeout_seconds": 1800
}

list_wakeups

查看当前排队的唤醒条件。

cancel_wake

{ "id": "docling-complete" }

🧭 条件类型

| kind              | 参数 | 唤醒时机 |
| ----------------- | ---- | -------- |
| count_ge        | path, threshold（默认 1） | 目录内普通文件数 ≥ threshold |
| file_contains   | path, needle | 文件内容包含 needle |
| error_receipts  | path | 目录下 JSON receipt 状态含 ERROR 或 JSON 不可解析 |
| process_absent  | process_pattern, grace_seconds（默认 0） | pgrep -f 匹配不到进程，且已持续 grace_seconds |
| delay           | delay_seconds | 注册后经过 delay_seconds 秒 |

每个条件都可加 timeout_seconds，超时后无论条件是否满足都会唤醒。

⚙️ 配置

| 字段 | 默认值 | 说明 |
| ---- | ------ | ---- |
| intervalMs | 30000 | 轮询周期，最小 5000ms |
| logFile | ~/.dsh/super-injector/dsh-wake-scheduler.log | 运行日志 |
| stateFile | ~/.dsh/super-injector/dsh-wake-scheduler-state.json | 持久化唤醒队列（原子写入） |

🧪 开发与测试

npm install
npm test          # typecheck + 构建 lib + node --test 测试
npm run typecheck # 仅类型检查
npm run build:lib # 仅 tsc 编译 src → lib

测试覆盖：条件判定、超时、process_absent 宽限期、参数校验、工具注册/状态持久化/定时触发/Agent followup。

🏗️ 架构

Agent ── schedule_wake ──▶ state.json ──▶ setInterval loop
▲                  │
│                  ▼
list/cancel       evaluateCondition
▲                  │ 条件满足？
│                  ▼
└── 持久化 ◀── wakeAgent(agentId)
agent.followup()

- 状态持久化：所有 wakeup 先落盘再等触发，重启不丢。
- 原子写入：tmp-pid + rename 避免状态文件写坏。
- 防重入：轮询纤维有 checking 守卫，热重载不会并发读写状态文件。
- 静默容错：日志/状态读写失败不影响主流程。

📄 许可证

本项目使用 MIT License，与 DSH 核心生态（@deepseek-ai/dsh-llm、@deepseek-ai/dsh-tools、cordis 等）保持一致。