pi-pushplus-notify

pi 任务结束时，通过 PushPlus 推送一条微信通知。

English | 简体中文

本插件面向中国用户。 PushPlus 是国内的推送服务，消息最终送达微信，所以你需要有一个微信账号和一个 PushPlus 账号。如果你不使用微信，这个插件对你没有帮助。除此之外的服务商（Bark、ntfy、Telegram、Slack 等）本插件都不支持。

为什么需要它

让 pi 跑一个长任务——跑的构建、跑测试、批量改代码——启动之后你其实就没事干了，但又不敢走开：不知道它什么时候结束，也不知道成功还是失败。

这个插件在每一轮任务结束时推一条微信给你，带上项目名、工作目录、耗时和最终回复的摘要。于是你可以锁屏、去干别的，等微信响。

刻意做得很小：

• 零运行时依赖。不需要 Python，不需要 curl，只用 Node 内置的 fetch。
• token 只存在本地，文件权限 0600，除了 PushPlus 官方接口，不会发给任何第三方。
• 限流保护内置。PushPlus 超限的惩罚很重（见下方），所以插件自己会做滑动窗口限流、被限流后自动停机。
• 不阻塞界面。推送在后台发送，PushPlus 卡住时你的终端不会跟着卡住。

安装

pi install npm:pi-pushplus-notify

安装后重启 pi，或在交互式会话里执行 /reload。

快速开始：三步

PushPlus 没有 OAuth，也没有第三方授权登录。任何声称"扫码登录"的插件都是错的——官方唯一的扫码功能是给你已经登录的账号绑定推送渠道，并不能让第三方替你拿到 token。所以你只能自己取一个 token 再粘进来。

1. 取 token：在微信公众号「pushplus 推送加」里直接回复文字 token，它会立刻把 token 值回给你。不用打开网页。（其他取法见下一节。）

2. 粘贴：在 pi 里执行 /pushplus，在弹出的菜单里选「配置 token」，把 token 粘进去。

3. 看微信确认：配置时会立即发一条测试消息验证 token 真的有效。收到就说明成功，通知也自动开启了。

之后每次任务结束，微信就会收到通知。token 长期有效、不会自动过期，粘一次就够了。

前提：PushPlus 账号必须完成实名认证。未实名的账号接口会返回错误码 905，测试消息发不出来。

命令

只有一个命令 /pushplus。

裸 /pushplus 的菜单会根据当前状态变化：

• 还没配置 token 时，只有一项「配置 token」——因为这时没有别的事可做。
• 已经配置 时，提供四项：发送测试消息、开启或关闭通知（文字随当前状态变化）、更换 token、清除 token。
• 在非交互环境（如 -p 模式）下不会弹菜单，只打印一行状态。

参数支持 Tab 补全；用中文输入法打出的全角字母（如 ＯＮ）会被自动归一化。

获取 token 的三种方式

任选一种，得到的都是同一个东西：一个字母数字组成的 token。

1. 最简单：在微信公众号「pushplus 推送加」里回复文字 token，公众号直接把 token 值返回给你。不用打开网页。

2. 网页登录：微信扫码登录 pushplus.plus，进入「一对一消息」页面，页面上有一键复制按钮。

3. 更安全（推荐长期使用）：在 pushplus.plus 的个人中心 →「开发设置」里创建额外的「消息 token」。这种 token 可以设置到期时间，也可以单独删除，比账号主 token 多一层保险——万一泄露，删掉重建即可，不影响主账号。

限流与防护

先说 PushPlus 官方的限制，因为超限的惩罚很重：

• 每分钟 5 次请求
• 微信渠道每天 200 条
• 关键坑：计的是请求次数，包括失败的请求——报错也会消耗额度
• 相同内容 1 小时最多 3 条
• 超限后果：当日停推，严重时停 7 天

插件为此内置了防护：

• 滑动窗口限流。插件记录最近 60 秒内实际发出的请求时间，达到 5 次就跳过本次推送，并明确告诉你「已达 PushPlus 每分钟 5 次上限，本次通知已跳过」。被跳过的请求没有发出去，所以不消耗配额。
• 相同内容检测。1 小时内相同正文累计 3 次就跳过，并提示「PushPlus 相同内容 1 小时最多 3 条，本次通知已跳过」。
• 收到错误码 900（账号受限）时，自动暂停 24 小时，不再继续尝试——否则只会加重服务端的惩罚。暂停期内 /pushplus test 也会被拦截。
• 错误码 903（token 无效）、905（账号未实名）、888（积分不足）都会给出对应的处理提示。
• 错误码 999 会显示 PushPlus 返回的具体原因（通常是"推送频率过快"），不会只给你一句看不懂的"服务端验证错误"。

有两点和"什么时候发"有关：

• 推送是后台发送的，不会阻塞 pi。网络慢或 PushPlus 无响应时，你的终端不会被卡住——15 秒超时只发生在后台。
• setup 和 test 是你手动触发的，它们同样占用配额。其中 setup 不受滑动窗口限制（你刚配置完总得能验证一次，否则等于什么都没发生），test 则会遵守窗口上限和限流暂停状态——窗口已满或正在暂停时它会直接告诉你，不会真的发出去。

setup 和 test 的消息里都带了时间戳，这是为了避开「相同内容」规则：如果内容完全一样，连点三次测试就会触发限流。

推送内容会经过处理

微信里收到的是摘要，不是完整内容；完整输出始终留在终端。处理规则：

• 剔除 Markdown 围栏代码块，替换为 [代码块已省略]（避免一整个 diff 变成微信消息正文）
• 清理 ANSI 转义序列
• 超过 1200 字符时保留开头和结尾，中间插入省略标记
• 标题截断到 100 字符
• 本轮没有任何文本输出时，正文显示「本轮执行结束，终端正在等待下一步输入。」

配置与存储

• 配置文件：~/.pi/agent/pushplus-notify.json（通过 pi 的 getAgentDir() 定位）。写入时权限 0600。
• 环境变量：PUSHPLUS_TOKEN。只在配置文件里没有 token 时作为初始来源生效，适合 CI —— 不需要把 token 写到磁盘上。
• 优先级：手动 /pushplus setup 保存的 token 永远优先于环境变量。所以先设了环境变量、之后再用 setup，新 token 依然会生效。
• 默认行为：配置了 token 之后，通知默认就是开启的。
• 你只需要配置一个 token；其余（开关、限流暂停截止时间、发送记录）由插件自己维护。
• 写入采用「临时文件 + 重命名」的原子方式，因此多个 pi 进程同时读写不会读到半截文件。
• reset 只清除 token、开关和发送记录，你在文件里手动添加的其它字段会被保留。

常见问题

/pushplus setup 提示「配置失败：token 无效」

token 复制错了。回公众号重新取一个（回复 token 最简单）。注意不要带上多余的空格或换行。

提示「账号未实名」（错误码 905）

PushPlus 拒绝未实名账号发送消息。去 pushplus.plus 完成实名认证后再试。

配置成功了，任务结束却收不到

按顺序排查：

1. /pushplus status 看通知是不是被关了（on 打开）；
2. 看是否显示「已被 PushPlus 限流，暂停中」（若是，等暂停期结束）；
3. 确认微信里关注的是「pushplus 推送加」公众号，且没有屏蔽它；
4. 确认账号没有因为超限被停推。

被限流了 / 收到「账号已被限流」

说明 5 次/分钟或 200 条/天的额度用满了——通常是因为短时间内跑了多个任务，或者手动测试点太多次。插件收到 900 后会自动暂停 24 小时，等它过去即可。

想立刻恢复可以执行 /pushplus reset 再重新 setup，但这不会解除 PushPlus 服务端的惩罚，只是让插件重新尝试。

收到「PushPlus 判定请求过于频繁」

这是错误码 999，原因会跟在后面（常见的是「推送频率过快」或「请勿频繁推送相同内容」）。等一分钟再试，或者检查是不是刚发过内容完全一样的两条消息。

提示「PushPlus 积分不足」（错误码 888）

账号积分用尽。去 pushplus.plus 充值或检查套餐。

setup 发的测试消息要占用配额吗？

占用。setup 和 test 都是真实请求，PushPlus 全都计数——包括失败的那些。所以别反复点测试。

只支持 PushPlus 吗？

是的。本插件只对接 PushPlus，不支持其他推送服务商。

许可证

MIT