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