push-notify

用途

push-notify 是一个通过 Pushover 向移动设备发送即时推送通知的技能。它适合在需要用户及时获知信息的场景下使用，例如发送紧急警报、任务完成通知、实时监控告警以及关键系统通知。

该技能明确不适用于以下场景：批量营销消息（应使用邮件或短信服务）、非紧急通知（应使用邮件）、双向通信（应使用即时通讯应用）、定时提醒（应使用日历或任务应用）。

主要能力

向移动设备发送推送通知。
支持设置通知标题、优先级、声音、补充 URL 及 URL 按钮标题、指定设备、时间戳等参数。
支持多种优先级：-2（静默）、-1（安静）、0（普通）、1（高优先级，可绕过免打扰时段）、2（紧急，每 60 秒重复一次，持续 30 分钟）。紧急优先级需要同时提供 retry（重复间隔，最小 30 秒）和 expire（停止重试时间，最大 86400 秒）。
支持多种提示音，包括 pushover、bike、bugle、cashregister、classical、cosmic、falling、gamelan、incoming、intermission、magic、mechanical、pianobar、siren、spacealarm、tugboat、alien、climb、persistent、echo、updown、none。
支持通过群组密钥向多个用户发送通知。

使用方式

准备工作

注册 Pushover 账号：https://pushover.net
在 Pushover 控制面板获取用户密钥（User Key）。
创建应用：https://pushover.net/apps/build
从应用中获取 API Token。
配置环境变量：

export PUSHOVER_TOKEN="your_app_token" export PUSHOVER_USER_KEY="your_user_key"

API 调用

基础通知：

curl -X POST "https://api.pushover.net/1/messages.json"
-d "token=YOUR_APP_TOKEN"
-d "user=YOUR_USER_KEY"
-d "message=Hello World!"

带标题和优先级：

curl -X POST "https://api.pushover.net/1/messages.json"
-d "token=YOUR_APP_TOKEN"
-d "user=YOUR_USER_KEY"
-d "message=Server is down!"
-d "title=CRITICAL ALERT"
-d "priority=2"
-d "retry=60"
-d "expire=3600"

带声音：

curl -X POST "https://api.pushover.net/1/messages.json"
-d "token=YOUR_APP_TOKEN"
-d "user=YOUR_USER_KEY"
-d "message=New email received"
-d "sound=siren"

带 URL：

curl -X POST "https://api.pushover.net/1/messages.json"
-d "token=YOUR_APP_TOKEN"
-d "user=YOUR_USER_KEY"
-d "message=Build failed"
-d "url=https://ci.example.com/build/123"
-d "url_title=View Build"

参数说明

token（必填）：应用的 API token。
user（必填）：用户密钥或群组密钥。
message（必填）：通知消息，最多 1024 个字符。
title（可选）：通知标题。
priority（可选）：-2（最低）到 2（紧急）。
sound（可选）：自定义提示音名称。
url（可选）：补充 URL。
url_title（可选）：URL 按钮的标题。
device（可选）：指定设备，省略则发送到所有设备。
timestamp（可选）：Unix 时间戳，用于回溯时间。

Node.js 实现

const https = require('https'); const querystring = require('querystring');

async function sendNotification(message, options = {}) { const data = { token: process.env.PUSHOVER_TOKEN, user: process.env.PUSHOVER_USER_KEY, message: message, ...options };

return new Promise((resolve, reject) => { const postData = querystring.stringify(data);

const req = https.request({
  hostname: 'api.pushover.net',
  port: 443,
  path: '/1/messages.json',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
}, (res) => {
  let body = '';
  res.on('data', chunk => body += chunk);
  res.on('end', () => {
    const result = JSON.parse(body);
    if (result.status === 1) {
      resolve(result);
    } else {
      reject(new Error(result.errors?.[0] || 'Notification failed'));
    }
  });
});

req.on('error', reject);
req.write(postData);
req.end();

}); }

// 使用示例 await sendNotification('Build completed successfully!');

await sendNotification('Server CPU at 95%!', { title: 'CRITICAL ALERT', priority: 2, retry: 60, expire: 3600, sound: 'siren' });

await sendNotification('New PR opened', { title: 'GitHub', url: 'https://github.com/pr/123', url_title: 'View PR', priority: 1 });

群组通知

通过群组向多个用户发送通知：

从 Pushover 控制面板获取群组 ID（以 g1 结尾）

curl -X POST "https://api.pushover.net/1/messages.json"
-d "token=YOUR_APP_TOKEN"
-d "user=GROUP_KEY"
-d "message=Team update"

错误响应

{ "status": 0, "errors": ["User key is invalid"] }

常见错误包括：用户密钥无效、应用 token 无效、消息为空、优先级无效（必须在 -2 到 2 之间）、设备名称无效。

速率限制

免费层：每用户每月 750 条消息。
免费层：每应用每月 10,000 条消息。
紧急消息按 4 条普通消息计算。

快速响应模板

任务完成：

await sendNotification(✅ Job ${jobId} completed, { title: 'Agent Complete', url: jobUrl, url_title: 'View Results' });

错误警报：

await sendNotification(❌ ${errorMessage}, { title: 'Error', priority: 1, sound: 'siren' });

定时任务：

await sendNotification(📅 ${taskName} reminder, { title: 'Reminder', priority: 0 });

凭证验证

async function validateCredentials() { try { await sendNotification('Test notification'); return { valid: true }; } catch (error) { return { valid: false, error: error.message }; } }

适用场景

发送紧急警报。
任务完成通知。
实时监控告警。
关键系统通知。

限制

消息长度限制为 1024 个字符。
紧急优先级必须提供 retry 和 expire 参数。
用户密钥与应用 token 不同。
群组需要在 Pushover 中单独设置。
消息在送达后过期，不会被存储。
免费层存在速率限制：每用户每月 750 条消息，每应用每月 10,000 条消息，紧急消息按 4 条普通消息计算。