tradmangh-job-execution-monitor

基于心跳监控定时任务（cron），在任务失败或错过计划时发出告警。

## 概述（中文）

基于心跳监控定时任务（cron），在任务失败或错过计划时发出告警。

## 技能正文

# 任务执行监控器（Job Execution Monitor）

监控定时任务（cron），并在任务失败或错过计划执行时间时发出告警。

## 安装 / 更新（ClawHub）

安装：
```bash
clawhub install job-execution-monitor
```

更新：
```bash
clawhub update job-execution-monitor
```

---

## 何时使用
当用户提出以下请求时使用：
- “监控 cron 任务”
- “任务失败时告警”
- “检查任务是否运行过”
- “任务健康检查”
- “任务监视”
- “为什么我的定时任务没有运行？”

## 它能做什么

**基于心跳的监控：**
- 代理在周期性的心跳轮询中检查任务（约每 60 分钟一次）
- 使用最便宜的 LLM（Gemini Flash 或 Haiku）以最小化成本
- 仅在检测到问题时才发送告警
- 跟踪告警状态以避免重复刷屏

**成本：** 约 100k tokens/天（约 48 次检查 × 2k tokens）

## 工作原理

1. **配置：** 要监控的任务列在 `job-execution-monitor.json` 中
2. **心跳检查：** 代理每 15-30 分钟唤醒一次，约每第 4 次唤醒检查一次任务
3. **检测：** 将上次运行时间与预期计划时间 + 容差进行比较
4. **告警：** 携带上下文（预期计划时间 vs 上次运行）发送唤醒事件 → 由你决定下一步操作
5. **恢复：** 当任务再次成功运行时清除告警

## 禁用 / 卸载

### 如果通过 systemd *用户* 定时器安装
```bash
systemctl --user stop openclaw-job-execution-monitor.timer
systemctl --user disable openclaw-job-execution-monitor.timer
systemctl --user daemon-reload

# 可选：删除单元文件
rm -f ~/.config/systemd/user/openclaw-job-execution-monitor.service \
      ~/.config/systemd/user/openclaw-job-execution-monitor.timer
```

### 如果通过 cron 安装
```bash
crontab -l | sed '/job-execution-monitor\/scripts\/healthcheck\.sh/d' | crontab -
```

### 可选清理（配置/状态/日志）
```bash
rm -f ~/.openclaw/workspace/job-execution-monitor.json
rm -f ~/.openclaw/workspace/.job-execution-monitor-state.json
rm -f ~/.openclaw/workspace/job-execution-monitor.log
```

---

## 配置

**文件：** `~/.openclaw/workspace/job-execution-monitor.json`

```json
{
  "checkIntervalMin": 60,
  "jobs": {
    "Daily 21:00 journaling (projects + accomplishments + next day plan)": {
      "schedule": "0 22 * * *",
      "tolerance": 600,
      "critical": true,
      "expectedMinLength": 200,
      "errorPatterns": ["error", "failed", "Pong", "token overflow"]
    }
  }
}
```

**字段：**
- `schedule`：预期运行时间的 cron 表达式
- `tolerance`：宽限期，单位为秒（默认 600 = 10 分钟）
- `critical`：若为 true，则立即告警（未来：可能升级处理）
- `expectedMinLength`：最小响应长度（第 2 阶段）
- `errorPatterns`：表示失败的文本模式（第 2 阶段）

## 状态跟踪

**文件：** `~/.openclaw/workspace/.job-execution-monitor-state.json`

```json
{
  "lastCheck": 1771025000,
  "alerts": {
    "daily-wrap-up_missed": 1771024500
  }
}
```

- `lastCheck`：上次检查的 unix 时间戳
- `alerts`：alert_key → 时间戳的映射（防止重复刷屏）

## 说明（面向代理）

在 `HEARTBEAT.md` 中：

```markdown
## Job Execution Monitor (every ~60min, rotate)

Check cron jobs for missed schedules. Only alert if problem found.

**Instructions:**
1. Load `job-execution-monitor.json` config
2. Call `cron list` 
3. For each job in config:
   - Extract `state.lastRunAtMs` and `state.lastStatus`
   - Parse schedule (e.g., "0 22 * * *" = 22:00 daily)
   - If last run > (expected time + tolerance): **ALERT**
   - If last run recent: **SILENT**
4. On alert: send wake event with job name, expected time, last run time
5. On recovery (was alerting before, now OK): send recovery wake event

**State tracking:** `~/.openclaw/workspace/.job-execution-monitor-state.json`
- Track which jobs already alerted (don't spam)
- Clear alert flag when job recovers

**Rotate check:** Only run every ~4th heartbeat (once/hour if heartbeat is 15min)
```

## 示例

**场景 1：任务错过执行**
```
🔴 Job Execution Monitor: "daily-wrap-up" missed schedule
Expected: 22:00 ±10min
Last run: 5h 32m ago
Checking logs...
```

**场景 2：任务恢复**
```
✅ Job Execution Monitor: "daily-wrap-up" recovered
Last run: 22:02 (2min ago)
```

**场景 3：一切正常**
```
(silent - no wake event, no alert)
```

## 成本分析

**每次检查（约 2k tokens）：**
- 加载配置：约 200 tokens
- 调用 cron list：约 500 tokens
- 解析 + 比较：约 500 tokens
- 决策 + 响应：约 800 tokens

**每天（约 48 次检查）：**
- 48 × 2k = **约 100k tokens/天**
- 使用 Gemini Flash：**约 $0.01/天** ✅

**与其他方案的对比：**
- 每 10 分钟运行的 Bash 脚本：0 tokens，但复杂且脆弱
- 每 10 分钟运行的 cron 任务：144 × 2k = 约 300k tokens/天
- 每 60 分钟运行的心跳：**约 100k tokens/天** ← 选定方案 ✅

## 文件

- `SKILL.md` - 本文档
- `README.md` - 快速上手
- `config/job-execution-monitor.example.json` - 配置模板
- `scripts/patterns.json` - 错误模式（第 2 阶段）
- `~/workspace/job-execution-monitor.json` - 用户配置
- `~/workspace/.job-execution-monitor-state.json` - 告警状态

## 设计理念

**智能监控，成本极低。**

- 检查频率：约每小时 1 次（对于每日任务已足够）
- 使用最便宜的 LLM：Gemini Flash 或 Haiku
- 仅在出现真正问题时才唤醒主会话
- 状态跟踪可防止告警刷屏
- 基于代理 = 复用现有工具，无需处理认证/API 麻烦

---

**第 1 阶段已完成。** ✅  
**第 2 阶段（模式匹配）：** 即将推出。  
**第 3 阶段（结构化校验）：** 未来计划。