心跳管理器

自动化任务监控 · 智能超时分析 · 日报/周报 · 健康度评分

---

⚠️ 安装前须知

Git / subprocess 声明

本技能在 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 单独开关，默认同样关闭

凭证声明

本技能 不内置、不存储任何邮件凭证。邮件功能（告警、日报、周报）需要你在安装后自行配置：

• - 提供一个 Gmail 账号及其应用专用密码
• 填入 config/.env（该文件永远不会被上传或共享）

若不配置邮件，技能仍可正常运行心跳检查（任务监控、健康度评分），仅邮件通知功能不可用。

副作用声明

本技能会在运行时产生以下副作用：

操作	说明	可关闭
写入本地文件	更新 workspace/ 下的 MASTER.md、state.json 等	❌ 核心功能
写入日志

追加 logs/heartbeat.log | ✅ settings.yaml | | IMAP 读取邮件 | 检查指定邮箱未读邮件 | ✅ email.enabled: false | | SMTP 发送邮件 | 发送告警、日报、周报 | ✅ email.enabled: false | | Git commit + push | 自动提交工作区变更至远程 | ✅ git.enabled: false（默认关闭） |

---

快速开始

1. 安装依赖

bash
pip install pyyaml jinja2 python-dotenv

或使用 uv（推荐）

uv venv .venv && uv pip install --python .venv/bin/python pyyaml jinja2 python-dotenv

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

bash
cp config/.env.example config/.env

编辑 config/.env：

env

Gmail 发件账号

EMAIL_SENDER=your-agent@gmail.com

Gmail 应用专用密码（非登录密码）

获取方式：Google 账号 → 安全性 → 两步验证 → 应用专用密码

EMAILAPPPASSWORD=xxxx xxxx xxxx xxxx

收件人列表（逗号分隔）

EMAIL_RECIPIENTS=you@example.com

如何获取 Gmail 应用专用密码：

1. 1. 开启 Google 账号两步验证
2. 访问 myaccount.google.com/apppasswords
3. 生成一个应用专用密码并粘贴到上方

3. 调整配置（可选）

编辑 config/settings.yaml：

yaml
email:
enabled: true # 改为 false 可完全禁用邮件功能

git:
enabled: false # 改为 true 可开启 Git 同步（默认关闭）
auto_push: false # 改为 true 可开启自动推送

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

⚠️ Git 功能会调用系统 git 命令向远程仓库推送内容，请确认你了解并信任此操作后再开启。

如需开启，编辑 config/settings.yaml：

yaml
git:
enabled: true # 第一步：开启 git 功能
auto_commit: true # 每次心跳自动 commit
auto_push: false # 推送到远程（确认 remote 已配置后再开启）

开启前请确认：

1. 1. 当前目录已初始化 git 仓库（git status）
2. 已配置远程 remote（git remote -v）
3. 你信任此技能向该 remote 推送内容

5. 验证配置

bash
python tools/heartbeat_run.py status

6. 首次心跳

bash
python tools/heartbeat_run.py beat

---

功能概览

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

1. 0. 检查 .last_heartbeat 标记文件，距上次 < 30 分钟则静默退出（v1.2.0 看门狗）
2. 检查 daily.md 例行任务完成情况
3. 检查 todo.md 待办 + @due:HH:MM 超期检测
4. 检查 ongoing.json 任务状态机
5. 智能超时分析（正常推进 vs 完全卡死）

4.5. 检查 upcoming.md 未来7天事件 — 🔴🟡🔵分级预警（v1.1.0） 4.7. 检测 Chrome relay → 在线则同步 Canvas+FSP → 📡 同步任务自动打勾（v1.1.0）

1. 5. 检查邮件（需配置凭证）
2. 清理已完成 todo
3. Git 同步（可选）
4. 计算健康度评分（0-100）
5. 更新 MASTER.md 主控表（含 ## UPCOMING 7D 段）

reset — 每日重置（00:00）

• - 发送昨日完成任务日报邮件（需配置凭证）
• 重置 daily.md 为新一天
• 清理已完成的 ongoing 任务

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

• - 汇总本周健康度趋势与任务统计（需配置凭证）

status — 查看状态

• - 无需凭证，打印当前 MASTER 快照

---

OpenClaw 集成

在 HEARTBEAT.md 中添加：

bash
cd /path/to/heartbeat-manager && python tools/heartbeat_run.py beat

OpenClaw 内置心跳触发时将自动执行本技能。

---

任务文件格式

daily.md — 每日例行任务
markdown

DAILY | 2026-02-25

• - [ ] 晨间邮件检查
• [ ] 更新记忆库
• [x] 系统状态确认 @done:14:30

todo.md — 动态待办
markdown

• - [ ] 修复登录 bug @due:18:00
• [ ] 写周报

ongoing.json — 任务状态机
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 四分区格式

markdown

未来事件

🔮 未来（待完成事件）

• - 2026-03-01 | Canvas: CS601 测验 3 | [作业] @due:23:59 @src:canvas @id:canvas-xxx
• 2026-03-02 | 飞行训练 KGAI N12345 | [飞行] @time:14:00-17:00 @src:fsp @id:fsp-yyy

📌 手动（手动添加，不受自动清理影响）

• - 2026-05-15 | 期末考试周 | [考试]

✅ 已完成（已完成，事件日期+7天后自动删除）

• - [x] 2026-02-25 | Internet Systems 项目 #1 | [作业] @done:2026-02-25

⏰ 已超期（已过期未完成）

（暂无）

标签说明：

• - @src:canvas / @src:fsp