Heartbeat Manager

v1.2.0

Agent 心跳管理系统：自动检查任务状态、智能超时分析、日报/周报、健康度评分。与 OpenClaw 心跳同步运行。

⭐ 2· 491·5 current·5 all-time

byRongze Gao@zeron-g

Security Scan

VirusTotal

Benign

View report →

OpenClaw

Suspicious

high confidence

Purpose & Capability

Name/description match core capabilities (heartbeat, reports, Canvas/FSP sync), but shipped defaults and included code diverge: SKILL.md and meta claim Git push disabled by default, yet config/settings.yaml in the package sets git.enabled: true and auto_push: true. The package also contains Discord notification logic (not documented in SKILL.md) that reads other agent config; that access is out-of-scope for a pure heartbeat manager.

Instruction Scope

Runtime instructions and code operate on workspace files (expected) and call external services (Canvas, FSP, IMAP/SMTP) only if tokens are set (expected). However the code also attempts to read ~/.openclaw/openclaw.json to obtain a Discord Bot token and will POST to discord.com via curl if discord notifications are enabled (the SKILL.md does not mention this). The skill thus accesses other agent config and an external chat endpoint beyond the documented integrations.

✓

Install Mechanism

No install spec — code is included as files (lower install risk). Dependencies are standard Python libraries. No remote download or arbitrary extraction observed in the manifest.

Credentials

Registry metadata declares no required env vars, but the code expects optional secrets in config/.env (EMAIL_APP_PASSWORD, CANVAS_API_TOKEN, FSP_API_TOKEN). That's acceptable if optional, but the code also reads ~/.openclaw/openclaw.json (other agent credentials) to obtain a Discord token which is not declared or documented. The package's settings.yaml enabling git.auto_push by default further escalates required trust since pushing can leak workspace contents to a remote.

Persistence & Privilege

The skill writes/updates workspace files and logs (declared). However it also reads a user-level OpenClaw config file (~/.openclaw/openclaw.json) and can perform network posts to Discord using a token recovered from that file. Combined with the unexpected git auto_push default this creates a higher privilege/persistence surface than the SKILL.md conveys.

What to consider before installing

This skill appears to implement a reasonable heartbeat/monitoring tool, but there are concrete inconsistencies and surprising behaviors you should address before installing or enabling features: - Review config/settings.yaml in the package: it currently sets git.enabled: true and git.auto_push: true. If you do not want any remote pushes, change git.enabled: false and auto_push: false before running. - By default the code will try to send emails/IMAP checks if email.enabled is true — keep email.enabled=false until you intentionally create config/.env with only the credentials you trust. - The code contains an undocumented Discord notifier that will attempt to read ~/.openclaw/openclaw.json to obtain a bot token and post heartbeat messages to Discord. If you do not want this, search for "discord_notify" or the _notify_discord_heartbeat function and disable/remove it or ensure no sensitive tokens exist in ~/.openclaw. - Treat config/.env and any API tokens (Gmail App Password, CANVAS_API_TOKEN, FSP_API_TOKEN) as sensitive — only populate them after auditing the code. The skill claims it won't upload those files, but it can use them locally to contact external services. - Run the skill in a sandboxed environment first (or inspect/grep the code for network calls like requests.get/post and subprocess.run) to confirm behavior. Specifically inspect heartbeat_run.py for where Discord/curl is invoked and review git_ops.py to understand what will be added/committed/pushed. If you want a lower-risk start: set email.enabled=false, monitoring.canvas.enabled=false, monitoring.fsp.enabled=false, git.enabled=false in config/settings.yaml and run python tools/heartbeat_run.py status to observe local, read-only behavior before enabling external integrations.

Like a lobster shell, security has layers — review code before you run it.

latestvk972bk8kk3cc9njekky9b0m78n81wbhj

491downloads

2stars

6versions

Updated 1mo ago

v1.2.0

MIT-0

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

Comments

Loading comments...

Heartbeat Manager

Heartbeat Manager

⚠️ 安装前须知

Git / subprocess 声明

凭证声明

副作用声明

Quick Start

1. 安装依赖

2. 配置邮件（可选，但强烈推荐）

3. 调整配置（可选）

4. 配置 Git 同步（可选，默认关闭）

5. 验证配置

6. 首次心跳

功能概览

beat — 心跳检查（每30分钟）

reset — 每日重置（00:00）

weekly — 周报（每周日 23:59）

status — 查看状态

OpenClaw 集成

任务文件格式

健康度评分

未来事件监控 (v1.1.0)

upcoming.md 四分区格式

Canvas LMS 配置

Flight Schedule Pro (FSP) 配置

Chrome 浏览器自动同步

看门狗机制 (v1.2.0)

许可

Comments

`beat` — 心跳检查（每30分钟）

`reset` — 每日重置（00:00）

`weekly` — 周报（每周日 23:59）

`status` — 查看状态