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

小时计（ClawHub 上的 TARDIS）

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

ClawHub 说明： 由于原始 hour-meter 列表因仓库同步问题丢失，此技能在 ClawHub 上以 TARDIS 名称发布。

三种模式

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

# 戒烟追踪器
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 环境变量。

里程碑通知：心跳检测与定时任务对比

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

里程碑消息

里程碑触发时，其消息文本会发布到配置的通知渠道：

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

在 HEARTBEAT.md 中配置：

- 运行 meter.py check-milestones 并将触发的里程碑消息发布到配置的频道

高级功能： 以 ACTION: 为前缀的里程碑消息，可根据您的心跳配置选择性地视为代理指令。此为可选功能——安全注意事项请参阅 README.md。

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

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

快速参考

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

SendGrid 邮件 Webhook 服务器

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

设置

# 使用 Discord webhook 启动 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://您的域名.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 年 × 每年 2,000 小时 = 80,000 小时。

meter.py career --hours-worked 56000 --rate 85 --raise-pct 2.5
# → 剩余 12.3 年，潜在收入 $2.4M