modbender Heartbeat Manager
自动化任务监控 · 智能超时分析 · 日报/周报 · 健康度评分
⚠️ 安装前须知
Git / subprocess 声明
本 Skill 在 tools/git_ops.py 中使用 subprocess.run 调用系统 git 命令（git add、git commit、git push）。
默认行为：Git 功能完全关闭（git.enabled: false），不会执行任何 git 操作，除非你在 config/settings.yaml 中显式开启。
安全措施：
- 所有
subprocess.run使用参数列表，禁止shell=True（杜绝 shell 注入） - commit message 经过净化，移除控制字符
auto_push单独开关，默认同样关闭
凭证声明
本 Skill 不内置、不存储任何邮件凭证。邮件功能（告警、日报、周报）需要你在安装后自行配置：
- 提供一个 Gmail 账号及其 App Password
- 填入
config/.env（该文件永远不会被上传或共享）
若不配置邮件，Skill 仍可正常运行心跳检查（任务监控、健康度评分），仅邮件通知功能不可用。
副作用声明
本 Skill 会在运行时产生以下副作用：
| 操作 | 说明 | 可关闭 |
|---|---|---|
| 写入本地文件 | 更新 workspace/ 下的 MASTER.md、state.json 等 |
❌ 核心功能 |
| 写入日志 | 追加 logs/heartbeat.log |
✅ settings.yaml |
| IMAP 读取邮件 | 检查指定邮箱未读邮件 | ✅ email.enabled: false |
| SMTP 发送邮件 | 发送告警、日报、周报 | ✅ email.enabled: false |
| Git commit + push | 自动提交工作区变更至远程 | ✅ git.enabled: false（默认关闭） |
Quick Start
1. 安装依赖
pip install pyyaml jinja2 python-dotenv
# 或使用 uv（推荐）
uv venv .venv && uv pip install --python .venv/bin/python pyyaml jinja2 python-dotenv
2. 配置邮件（可选，但强烈推荐）
cp config/.env.example config/.env
编辑 config/.env：
# Gmail 发件账号
EMAIL_SENDER=your-agent@gmail.com
# Gmail 应用专用密码（非登录密码）
# 获取方式：Google 账号 → 安全性 → 两步验证 → 应用专用密码
EMAIL_APP_PASSWORD=xxxx xxxx xxxx xxxx
# 收件人列表（逗号分隔）
EMAIL_RECIPIENTS=you@example.com
如何获取 Gmail App Password：
- 开启 Google 账号两步验证
- 访问 myaccount.google.com/apppasswords
- 生成一个应用专用密码并粘贴到上方
3. 调整配置（可选）
编辑 config/settings.yaml：
email:
enabled: true # 改为 false 可完全禁用邮件功能
git:
enabled: false # 改为 true 可开启 Git 同步（默认关闭）
auto_push: false # 改为 true 可开启自动推送
4. 配置 Git 同步（可选，默认关闭）
⚠️ Git 功能会调用系统
git命令向远程仓库推送内容，请确认你了解并信任此操作后再开启。
如需开启，编辑 config/settings.yaml：
git:
enabled: true # 第一步：开启 git 功能
auto_commit: true # 每次心跳自动 commit
auto_push: false # 推送到远程（确认 remote 已配置后再开启）
开启前请确认：
- 当前目录已初始化 git 仓库（
git status） - 已配置远程 remote（
git remote -v） - 你信任此 Skill 向该 remote 推送内容
5. 验证配置
python tools/heartbeat_run.py status
6. 首次心跳
python tools/heartbeat_run.py beat
功能概览
beat — 心跳检查（每30分钟）
- 检查
.last_heartbeat标记文件，距上次 < 30 分钟则静默退出（v1.2.0 watchdog） - 检查
daily.md例行任务完成情况 - 检查
todo.md待办 +@due:HH:MM超期检测 - 检查
ongoing.json任务状态机 - 智能超时分析（正常推进 vs 完全卡死）
4.5. 检查
upcoming.md未来7天事件 — 🔴🟡🔵分级预警（v1.1.0） 4.7. 检测 Chrome relay → 在线则同步 Canvas+FSP →📡 同步任务自动打勾（v1.1.0） - 检查邮件（需配置凭证）
- 清理已完成 todo
- Git 同步（可选）
- 计算健康度评分（0-100）
- 更新
MASTER.md主控表（含## UPCOMING 7D段）
reset — 每日重置（00:00）
- 发送昨日完成任务日报邮件（需配置凭证）
- 重置
daily.md为新一天 - 清理已完成的 ongoing 任务
weekly — 周报（每周日 23:59）
- 汇总本周健康度趋势与任务统计（需配置凭证）
status — 查看状态
- 无需凭证，打印当前 MASTER 快照
OpenClaw 集成
在 HEARTBEAT.md 中添加：
cd /path/to/heartbeat-manager && python tools/heartbeat_run.py beat
OpenClaw 内置心跳触发时将自动执行本 Skill。
任务文件格式
daily.md — 每日例行任务
# DAILY | 2026-02-25
- [ ] 晨间邮件检查
- [ ] 更新记忆库
- [x] 系统状态确认 @done:14:30
todo.md — 动态待办
- [ ] 修复登录 bug @due:18:00
- [ ] 写周报
ongoing.json — 任务状态机
{
"tasks": [{
"id": "01", "title": "毕业论文",
"status": "WIP", "priority": "P0",
"eta": "2026-03-01", "progress": 65,
"context": "第三章进行中"
}]
}
状态流转：IDLE → WIP → DONE，WIP → WAIT → WIP，WIP → BLOCK（智能检测卡死）
健康度评分
| 维度 | 权重 | 说明 |
|---|---|---|
| Daily 完成率 | 25% | 例行任务完成比例 |
| Todo 完成率 | 20% | 超期扣分 |
| Ongoing 状态 | 25% | BLOCK/超期扣分 |
| 邮件处理 | 15% | 未读过多扣分 |
| Git 同步 | 15% | push 成功满分；Git 禁用时不扣分 |
连续 3 次低于 60 分 → 邮件告警
未来事件监控 (v1.1.0)
每次心跳自动检测 Chrome 扩展 relay，在线时同步 Canvas + FSP 数据到 workspace/upcoming.md；离线时保留现有数据不做任何删除。
upcoming.md 四分区格式
# Upcoming Events
## 🔮 FUTURE （待完成事件）
- 2026-03-01 | Canvas: CS601 Quiz 3 | [作业] @due:23:59 @src:canvas @id:canvas-xxx
- 2026-03-02 | 飞行训练 KGAI N12345 | [飞行] @time:14:00-17:00 @src:fsp @id:fsp-yyy
## 📌 MANUAL （手动添加，不受自动清理影响）
- 2026-05-15 | 期末考试周 | [考试]
## ✅ DONE （已完成，事件日期+7天后自动删除）
- [x] 2026-02-25 | Internet Systems Project #1 | [作业] @done:2026-02-25
## ⏰ OVERDUE （已过期未完成）
（暂无）
标签说明：
@src:canvas/@src:fsp— 自动同步来源，未标记 src 的为手动事件@id:xxx— 来源系统唯一ID，用于去重更新@due:HH:MM— 截止时间；@time:HH:MM-HH:MM— 事件时段@done:YYYY-MM-DD— 完成日期，超过7天后自动清理
7天预警颜色（MASTER.md 中显示）：
- 🔴 ≤1天（紧急）→ ALERTS 区也会出现
- 🟡 ≤3天（注意）
- 🔵 ≤7天（提醒）
Canvas LMS 配置
# 获取方式：Canvas → Account → Settings → Approved Integrations → New Access Token
# 注意：部分机构学生账户可能无权生成 token（可手动维护 upcoming.md）
在 config/.env 中填入：
CANVAS_API_TOKEN=your_token_here
在 config/settings.yaml 中配置：
monitoring:
canvas:
enabled: true
base_url: "https://your-canvas-url.instructure.com"
lookahead_days: 30
Flight Schedule Pro (FSP) 配置
FSP API 为机构级权限，普通学员账户通常无法获取。如有权限：
FSP_API_TOKEN=your_token_here
FSP_OPERATOR_ID=your_operator_id
Chrome 浏览器自动同步
每次 beat 自动检测本地 Chrome 扩展 relay（127.0.0.1:18792）是否在线：
- 在线 → 调用
tools/site_monitor.py同步 Canvas + FSP → 自动在 daily.md 的📡 同步任务打勾 - 离线 → 静默跳过，保留现有 upcoming.md 数据不变
配置 Chrome 扩展 relay：
openclaw browser extension install
openclaw browser extension path
# → 在 Chrome 中加载该路径的扩展，填入 Gateway token，attach 目标标签页
💡 若无 API token，可每天打开 Canvas/FSP 网页并 attach Chrome 扩展，让 Eva 通过浏览器直接抓取数据，无需 API 凭证。
安全保证： site_monitor.py 使用 active_sources 机制，仅删除已激活来源中不再存在的事件；未配置 token 的来源完全跳过，现有数据100%保留。
看门狗机制 (v1.2.0)
配合 */15 * * * * cron 运行，实现可靠的30分钟心跳间隔：
- 原理：beat 完成后
touch workspace/.last_heartbeat；cron 每 15 分钟触发，先检查 mtime，距上次不到 30 分钟则静默退出 - 最大延迟：15 分钟（cron 最差情况下一个间隔）
- 无外部依赖：只依赖文件系统，不调用 openclaw CLI
- 自愈：cron 是幂等的，leaky 或 missed 触发自动修正
# openclaw cron 建议配置：
schedule: "*/15 * * * *"
许可
MIT License