dual-channel-watchexec-notifications

Watchexec 双通道通知

当 watchexec 检测到文件变更或进程崩溃时，同时向 Telegram 和 Pushover 发送可靠通知。

何时使用此技能

在以下情况下使用此技能：

• 设置文件变更监控和通知
• 通过 Telegram 和 Pushover 实现进程崩溃告警
• 创建支持双通道通知的 watchexec 包装脚本
• 分别为 HTML（Telegram）和纯文本（Pushover）格式化消息
• 排查通知发送或格式问题

核心模式

watchexec 包装脚本 → 检测事件 → notify-script → Telegram + Pushover

# wrapper.sh - Monitors process and detects restart reasons
watchexec --restart -- python bot.py

# On event, call:
notify-script.sh <reason> <exit_code> <watchexec_info_file> <crash_context>

---

关键规则：格式差异

Telegram：仅使用 HTML 模式

MESSAGE="<b>Alert</b>: <code>file.py</code>"
# Escape 3 chars: & → &amp;, < → &lt;, > → &gt;

Pushover：仅使用纯文本

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
# Strip HTML tags before sending
MESSAGE_PLAIN=$(echo "$MESSAGE_HTML" | sed 's/<[^>]*>//g')
SKILL_SCRIPT_EOF

Telegram 使用 HTML 的原因：

• Markdown 需要转义 40 多个字符（.、-、_ 等）
• HTML 只需转义 3 个字符（&、<、>）
• 符合行业最佳实践

---

快速参考

同时发送到两个通道

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
# 1. Build HTML message for Telegram
MESSAGE_HTML="<b>File</b>: <code>handler_classes.py</code>"

# 2. Strip HTML for Pushover
MESSAGE_PLAIN=$(echo "$MESSAGE_HTML" | sed 's/<[^>]*>//g')

# 3. Send to Telegram with HTML
curl -s -d "chat_id=$CHAT_ID" \
  -d "text=$MESSAGE_HTML" \
  -d "parse_mode=HTML" \
  https://api.telegram.org/bot$BOT_TOKEN/sendMessage

# 4. Send to Pushover with plain text
curl -s --form-string "message=$MESSAGE_PLAIN" \
  https://api.pushover.net/1/messages.json
SKILL_SCRIPT_EOF_2

执行模式

# Fire-and-forget background notifications (don't block restarts)
"$NOTIFY_SCRIPT" "crash" "$EXIT_CODE" "$INFO_FILE" "$CONTEXT_FILE" &

---

验证清单

部署前：

• Telegram 使用 HTML 解析模式（而非 Markdown）
• 为 Pushover 去除 HTML 标签（仅使用纯文本）
• 对所有动态内容应用 HTML 转义（&、<、>）
• 从环境变量/Doppler 加载凭据（不硬编码）
• 启用消息归档以便调试
• 使用 stat 检测文件（而非 find -newermt）
• Heredoc 使用未加引号的分隔符，以便展开变量
• 在后台运行通知（发送后不等待）
• 使用包含特殊字符（_、.、-）的文件进行测试
• Telegram 和 Pushover 均能成功接收通知

---

总结

要点：

1. Telegram 始终使用 HTML 模式（转义更简单）
2. Pushover 始终去除 HTML 标签（仅使用纯文本）
3. HTML 中只需转义 3 个字符：& → &、< → <、> → >
4. 发送前归档消息以便调试
5. 在 macOS 上使用 stat 检测文件（而非 find -newermt）
6. 从环境变量/Doppler 加载凭据（绝不硬编码）
7. 在后台发送通知，不等待发送完成（避免阻塞重启）

---

参考文档

详细信息请参阅：

• Telegram HTML - HTML 模式格式和消息模板
• Pushover Integration - API 调用和优先级
• Credential Management - Doppler、环境变量和钥匙串模式
• Watchexec Patterns - 文件检测和重启原因检测
• Common Pitfalls - Pushover 中的 HTML 标签、转义问题、macOS 兼容性

随附示例：

• examples/notify-restart.sh - 完整的双通道通知脚本
• examples/bot-wrapper.sh - 带重启检测的 watchexec 包装脚本
• examples/setup-example.sh - 设置指南和安装步骤

故障排查

问题	原因	解决方案
Telegram 转义错误	使用了 Markdown 而非 HTML	使用 parse_mode=HTML 切换到 HTML 模式
Pushover 显示 HTML 标签	未剥除 HTML	发送到 Pushover 前使用 sed 剥除标签
未收到通知	缺少凭据	检查 BOT_TOKEN、CHAT_ID 和 Pushover 密钥
特殊字符显示异常	缺少 HTML 转义	对动态内容中的 &、<、> 进行转义
find -newermt 在 macOS 上失败	与 macOS 不兼容	改用 stat 检测文件
通知阻塞	未在后台运行	添加 &，让通知脚本以即发即弃方式运行
通知重复	重启循环	添加防抖逻辑或冷却时间
缺少崩溃上下文	未写入上下文文件	检查 watchexec 信息文件路径是否存在