dsh-cron-scheduler

Readme

# dsh-cron-scheduler

Linux crontab 风格的定时任务调度插件，让 LLM 可以：
- **按 cron 表达式定时调用现有的工作流**（workflow 任务）
- **按 cron 表达式定时投递一段提示词**（prompt 任务）

任务与会话（session）绑定，通过会话事件日志持久化——宿主重启后调度自动恢复。

## 功能

- ✅ 标准 5 段 cron 表达式 `分 时 日 月 周`，以及带秒的 6 段形式 `秒 分 时 日 月 周`
- ✅ 步进 `*/15`、范围 `9-18`、范围步进 `9-18/2`、列表 `1,5,10`、月份/星期名称（`JAN-DEC`、`MON-FRI`、`SUNDAY`）
- ✅ 与 Linux crontab 一致的语义：日与星期同时指定按 **OR** 处理；5 段表达式在整分 `:00` 触发；错过的触发不补发
- ✅ LLM 工具：创建 / 列出 / 删除 / 暂停 / 恢复 / 预览 / 手动触发
- ✅ 主动任务：LLM 从聊天记录中推理出周期/提醒类意图 → 形成待确认建议 → 主人确认后自动加入排程（`cron_suggest` / `cron_accept` / `cron_reject`）
- ✅ 到点后投递提示词（prompt 任务），或指示 agent 调用 `run_workflow`（workflow 任务，可带参数）
- ✅ 会话级持久化 + 宿主重启后恢复调度
- ✅ 通过 agent 自身的消息循环投递，保持审批与可见性语义

## 安装

### 方式一：插件中心 / npm（推荐）

DSH 插件中心搜索 `dsh-cron-scheduler` 安装；或在 web profile（`C:\Users\admin\.dsh\profiles\web`）中手动添加：

```jsonc
// package.json 的 dependencies 中新增
"dsh-cron-scheduler": "^0.1.0"
```

然后在 profile 目录执行 `pnpm install`，重启 DSH Host。

### 方式二：本地开发（file: 链接）

1. 把插件加入依赖：

```jsonc
// package.json 的 dependencies 中新增
"dsh-cron-scheduler": "file:E:/dsh/dsh-cron"
```

2. 在 `dsh.profile.bundles` 数组中追加 `"dsh-cron-scheduler"`：

```jsonc
"dsh": {
  "profile": {
    "bundles": [ "...", "dsh-cron-scheduler" ]
  }
}
```

3. 在 profile 目录执行 `pnpm install`，然后重启 DSH Host。

插件自身的 `cordis.patch.yml` 声明 `id: cron`，加载后自动挂到每个 root agent。

## 用法（LLM 侧工具）

| 工具 | 说明 |
| --- | --- |
| `cron_create` | 创建定时任务。`cron` 必填；`kind` 为 `prompt` 或 `workflow` |
| `cron_list` | 列出本会话所有任务（按下次触发时间排序）+ 待主人确认的主动任务建议 |
| `cron_next` | 只读预览：计算表达式未来 N 次触发时间 |
| `cron_delete` | 按 id 删除任务 |
| `cron_pause` / `cron_resume` | 暂停 / 恢复任务 |
| `cron_run` | 立即手动触发一次（不改变原计划） |
| `cron_suggest` | **主动任务**：根据聊天记录推理出周期/提醒意图，形成待确认建议（未排程） |
| `cron_accept` | 主人确认建议 → 把建议转为真实定时任务（自动加入排程） |
| `cron_reject` | 主人拒绝建议 → 丢弃建议 |

### 创建 prompt 任务

```text
请创建定时任务：每天 09:00 投递提示词「早上好，请总结昨日进展并列出今日计划」，
cron 表达式为 0 9 * * *，kind 为 prompt。
```

### 创建 workflow 任务

```text
请创建定时任务：每周一至周五 18:00 调用工作流 daily_report，
cron 表达式为 0 18 * * 1-5，kind 为 workflow，参数 { scope: "today" }。
```

### 预览触发时间

```text
请用 cron_next 预览 0 18 * * 1-5 未来 5 次的触发时间。
```

## 主动任务（建议确认流）

当对话中出现周期 / 提醒 / 定时类意图（如「每天提醒我喝水」「每周一发周报」）时，LLM 会：
1. **推理**：从聊天记录里推断 cron 表达式、任务内容，并附上推理理由（`reason`）；
2. **建议**：调用 `cron_suggest` 形成**待确认建议**（不直接排程），并把建议展示给主人；
3. **判定**：主人回复同意 → LLM 调用 `cron_accept` 把建议转为真实任务自动加入排程；主人拒绝 → 调用 `cron_reject` 丢弃建议。

- 建议与任务一样通过 `cron/change` 事件持久化（操作 `suggest` / `accept` / `reject`），宿主重启后不丢失。
- 建议 id 使用独立命名空间（`cron_s_...`），与任务 id（`cron_...`）不冲突。
- `cron_list` 会同时返回 `jobs` 与 `suggestions`（`status: "pending_confirmation"`），即使建议 id 丢失也能找回。
- 建议未确认前**不会**触发任何定时投递；`cron_accept` 在确认时才计算首次触发时间。

## Cron 表达式语法

```
分  时  日  月  周
0   9   *   *   1-5     # 工作日 09:00
*/15 *   *   *   *      # 每 15 分钟
0   0   1   *   *       # 每月 1 日 00:00
0   12  *   *   MON-FRI # 工作日 12:00（支持名称）
0   0   13  *   5       # 每月 13 日或每周五（日/周 OR 语义）
```

字段范围：
- 分 `0-59`，时 `0-23`，日 `1-31`，月 `1-12`（或 `JAN-DEC`），周 `0-7`（0 和 7 都是周日，或 `SUN-SAT`）
- 带秒：`秒 分 时 日 月 周`，秒范围 `0-59`，例如 `*/10 * * * * *` 每 10 秒一次

## 实现说明

- `lib/cron-parser.js` — 纯函数 cron 表达式解析与下次触发时间计算（无副作用，可独立测试）
- `lib/cron.js` — 任务记录模型、主动任务建议模型、事件日志变更（`cron/change`）、折叠（jobs + suggestions）、消息渲染
- `lib/runtime.js` — 每个 root agent 一个 `CronRuntime`：折叠事件 → 武装定时器 → 到点投递
- `lib/tools.js` — 注册 `cron_*` 工具（含主动任务三件套 `cron_suggest` / `cron_accept` / `cron_reject`）
- `lib/index.js` — 插件入口，生命周期接线 + 注册 `cron/change` 会话事件类型

任务与建议均通过 `cron/change` 事件持久化到会话日志（与 `loop/change`、`schedule/change` 同机制）。
`foldCronState` 一次折叠出活动的 `jobs` 与待确认的 `suggestions`；`foldCronEvents` 保持向后兼容（只返回 jobs）。
workflow 任务到点时向 agent 投递一条 `<cron_fire>` 心跳，指示 agent 调用自身的
`run_workflow` 工具——审批、可见性与权限语义与手动调用完全一致。

## 测试

```bash
# 用真实 node（PATH 上的 node 可能是 DSH 包装器，会卡住）
"C:\Program Files\nodejs\node.exe" --test test/
```

## License

MIT