dual-channel-watchexec

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 集成 - API 调用和优先级
• 凭据管理 - Doppler、环境变量和钥匙串模式
• Watchexec 模式 - 文件检测和重启原因检测
• 常见陷阱 - 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 信息文件路径存在

执行后复盘

此技能执行完毕后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口有所变动，请更新用法示例和参数表，使之与实际情况一致。
3. 是否需要变通处理？ — 如果你不得不临时变通（使用不同的标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时还需要同样的变通处理。

仅在问题真实且可复现时才进行更新，不要基于猜测更新。