名称： hour-meter
描述： 通过防篡改锁定机制，从设定的起始点追踪已用时间。类似于模拟的霍布斯表，但采用数字形式。适用于跟踪运行时间、服务时长、事件发生后的时间、戒断计时、项目时长、设备运行时间等。支持创建、锁定（密封）、检查、基于外部哈希验证、列表和导出操作。

小时表

具备三种模式、里程碑通知和防篡改验证功能的生活事件追踪器。

三种模式

正向计时 — 事件发生后的时间

# 戒烟追踪器
meter.py create smoke-free --start "2025-06-15T08:00:00Z" -d "最后一支烟"
meter.py milestone smoke-free -t hours -v 720 -m "🎉 戒烟30天！"
meter.py lock smoke-free  # → 获取纸质代码以供保存

倒计时 — 距离事件发生的时间

# 宝宝预产期
meter.py create baby --start "2026-01-15" --end "2026-10-15" --mode down -d "宝宝即将到来！"
meter.py milestone baby -t percent -v 33 -m "👶 孕早期完成！"

区间计时 — 从开始到结束的旅程

# 职业生涯跨度
meter.py create career --start "1998-05-15" --end "2038-05-15" -d "40年职业生涯"
meter.py milestone career -t percent -v 50 -m "📊 职业生涯过半！"
meter.py career --meter career --rate 85 --raise-pct 2.5

防篡改持久化

锁定计时器后，您会获得一个纸质代码——一个简短、带校验和的代码，可以写在纸上：

╔══════════════════════════════════════════════════════════════╗
║  纸质代码（请抄写下来）：                                    ║
║     318B-3229-C523-2F9C-V                                    ║
╚══════════════════════════════════════════════════════════════╝

五种保存方式（非技术性）

1️⃣ 纸质记录 — 将代码写在纸/便利贴上
- 20个字符带连字符，易于抄写
- 内置校验和可在验证时发现拼写错误
- 可存放在钱包、保险箱或粘贴在设备上

2️⃣ 拍照备份 — 截屏或拍摄锁定屏幕
- 存储在相册、云相册中
- 视觉备份，无需手动输入

3️⃣ 见证文件 — 自动保存至 ~/.openclaw/meter-witness.txt
- 仅追加日志，记录所有已锁定的计时器
- 将文件夹同步到 Dropbox/iCloud/Google Drive 进行云备份
- 包含纸质代码、完整哈希值和时间戳

4️⃣ 邮件自存 — 点击 mailto: 链接或复制单行信息
- 在邮件客户端中打开预填主题和正文
- 或复制简洁消息：🔒 my-meter | 代码: XXXX-XXXX-XXXX-XXXX-C | 锁定时间: 2026-02-02
- 发送给自己，稍后可在收件箱中搜索验证

5️⃣ SENDGRID 邮件 — 锁定时自动发送验证邮件

# 设置您的 SendGrid API 密钥
export SENDGRID_API_KEY=SG.xxxxx
export SENDGRID_FROM_EMAIL=verified@yourdomain.com

# 一键锁定并发送邮件
meter.py lock my-meter --email you@example.com

• 发送格式精美的 HTML 邮件，内含纸质代码
• 需要在 SendGrid 中设置已验证的发件人（参见 SendGrid 文档）
• 适用于自动化工作流

后续验证

# 使用纸质代码（可发现拼写错误！）
meter.py verify my-meter "318B-3229-C523-2F9C-V"

# → ✅ 验证通过！纸质代码匹配。
# → ⚠️ 校验和错误！（如有拼写错误）
# → ❌ 不匹配！（如被篡改）

里程碑

meter.py milestone <名称> --type hours --value 1000 --message "1000小时！"
meter.py milestone <名称> --type percent --value 50 --message "过半！"
meter.py check-milestones  # 用于自动化的 JSON 输出

邮件里程碑通知 (v1.3.0)

将里程碑通知直接发送到您的邮箱：

# 创建带邮件通知的计时器
meter.py create my-meter \
  --notify-email you@example.com \
  --from-email verified@yourdomain.com \
  -d "我追踪的事件"

# 照常添加里程碑
meter.py milestone my-meter -t hours -v 24 -m "🎉 完成24小时！"

# 当 check-milestones 运行且触发里程碑时，邮件将自动发送
meter.py check-milestones
# → 触发里程碑并发送邮件通知

邮件包含：
- 🎯 里程碑消息
- ⏱️ 当前已用时间
- 📝 计时器描述

需要设置 SENDGRID_API_KEY 环境变量。

里程碑通知：心跳任务 vs 定时任务

推荐：心跳任务（约30分钟分辨率）
- 添加到 HEARTBEAT.md：运行 meter.py check-milestones 并通知触发的里程碑
- 与其他周期性检查任务批量执行
- 成本效益高：与其他心跳任务共享令牌使用量
- 适用于大多数场景（戒烟追踪、职业里程碑等）

动作：触发器（代理自动化）

在里程碑消息前加上 ACTION: 前缀，以触发代理执行指令，而非仅发布消息：

# 仅发布消息
meter.py milestone my-meter -t hours -v 24 -m "🎉 完成24小时！"

# 触发代理执行指令
meter.py milestone my-meter -t hours -v 24 -m "ACTION: 检查天气并发布摘要"

在 HEARTBEAT.md 中配置：

- 如果消息以 "ACTION:" 开头，则将其作为指令执行
- 否则，将消息发布到配置的频道

替代方案：定时任务（精确计时）
- 当时间精确性很重要时使用（例如，事件倒计时）
- ⚠️ 成本警告： 1分钟间隔的定时任务 = 每天1440次API调用 = 昂贵！
- 如使用定时任务，请保持间隔≥15分钟以控制成本
- 最适合一次性提醒，而非持续监控

经验法则： 如果30分钟分辨率可接受，使用心跳任务。将定时任务留给需要精确计时的场景。

快速参考

meter.py create <名称> [--start T] [--end T] [--mode up|down|between] [-d DESC]
meter.py lock <名称>                # 密封 + 获取纸质代码
meter.py verify <名称> <代码>       # 验证纸质代码
meter.py check <名称>               # 状态 + 进度
meter.py milestone <名称> -t hours|percent -v N -m "..."
meter.py check-milestones           # 所有里程碑（JSON）
meter.py witness [--show] [--path]  # 见证文件
meter.py list                       # 所有计时器
meter.py career [--meter M] [--rate R] [--raise-pct P]
meter.py export [名称]              # JSON 导出

SendGrid 邮件 Webhook 服务器

当收件人打开、点击、退回或退订您的计时器验证邮件时，接收实时通知。

设置

# 启动带 Discord Webhook 的服务器（推荐）
python sendgrid_webhook.py --port 8089 --discord-webhook https://discord.com/api/webhooks/xxx/yyy

# 或手动处理事件（供代理发布）
python sendgrid_webhook.py --process-events
python sendgrid_webhook.py --process-events --json

Discord Webhook 设置（推荐）

1. 在您的 Discord 频道中，进入 设置 > 集成 > Webhook
2. 点击 新建 Webhook，复制 URL
3. 传递给 --discord-webhook 或设置 DISCORD_WEBHOOK_URL 环境变量

SendGrid 设置

1. 进入 SendGrid > 设置 > 邮件设置 > 事件 Webhook
2. 点击 "创建新 Webhook"（或编辑现有）
3. 设置 HTTP POST URL 为：https://your-domain.com/webhooks/sendgrid
4. 在 要发布的操作 下选择所有事件类型：
   - 互动数据： 已打开、已点击、已退订、垃圾邮件报告、群组退订、群组重新订阅
   - 可送达性数据： 已处理、已丢弃、已延迟、已退回、已送达
   - 账户数据： 账户状态变更
5. 点击 "测试集成" 进行验证 - 这将向您的 Webhook 发送所有事件类型
6. 重要： 点击 保存 以启用 Webhook！
7. （可选）启用 签名事件 Webhook 以增强安全性，并设置 SENDGRID_WEBHOOK_PUBLIC_KEY

事件类型

环境变量

SENDGRID_WEBHOOK_PUBLIC_KEY    # 用于签名验证（可选）
SENDGRID_WEBHOOK_MAX_AGE_SECONDS  # 时间戳最大年龄（默认：300）
WEBHOOK_PORT                   # 服务器端口（默认：8089）
DISCORD_WEBHOOK_URL            # Discord Webhook URL
WEBHOOK_LOG_FILE               # 日志文件路径

八万小时概念

将职业生涯视为有限库存：40年 × 每年2000小时 = 80,000小时。

meter.py career --hours-worked 56000 --rate 85 --raise-pct 2.5
# → 剩余12.3年，潜在收入240万美元