1什么场景值得给用户推送

邮件打开率越来越低，站内信要用户回站才看得到，短信成本高还容易进垃圾箱。把「值得让用户马上知道的事」推到他已经在用的钉钉、飞书、Telegram 里，是最省事的做法。

2一封传话解决什么问题

你自己只需要维护「什么时候推、推给谁、推什么」，剩下的投递工作交给一封传话。

• 支持多种推送通道：企业微信群机器人、钉钉群机器人、飞书群机器人、企业微信应用消息、Bark（iOS）、Telegram、Discord、自定义 Webhook、浏览器通知，以及 QQ / 163 / 126 / 搜狐 / 139 / 189 / 新浪 / 阿里云邮箱和官方邮件。用户用哪个工具，就配哪条通道。
• 多通道聚合：一个组合通道背后可以挂多条子通道，一次调用同时送到值班手机、团队群和邮箱，调用方只存一个通道码。
• 不用重复开发：不用逐家申请机器人、研究各自的签名与模板、处理令牌过期。你只调一个接口，各家平台的差异由一封传话消化。
• 一个 SDK 统一集成：push-sdk.js 同时支持浏览器 <script>、CommonJS 和 ES Module，前端后台都能用。
• 用户自己管理接收端：用户想加一条通道、换绑接收工具，在页面里自己操作即可，你的网站不用改代码。
• 推送记录可查：每次推送都有记录，方便你确认某条通知到底有没有送达。

3五分钟接入

整个过程只有四步：引入 SDK、给用户开通道码、把通道码存进用户资料、事件发生时调一次推送。

1. 引入 SDK在页面底部加一行 script，官方 CDN 直接可用。
2. 创建 SDK 实例填一个属于你网站的 mcpSource，方便在后台区分来源。
3. 给用户开通道码用用户邮箱发起授权，用户在官网页输入验证码后，SDK 会把通道码交回来。
4. 推送业务事件触发时请求 /services/push/trigger/通道码 网址，消息送到用户配置的通道。

3.1 引入并初始化

<script src="https://push.phprm.com/static/js/push-sdk.js"></script>
<script>
var pushSdk = YfPush.create({
  apiBase: 'https://www.phprm.com',  // 默认就是这个地址，可以省略
  mcpSource: 'my-website'            // 你的站点标识，便于在后台区分调用来源
});
</script>

用构建工具的项目也可以直接 import YfPush from './push-sdk.js'，或在 Node 里 require('./push-sdk.js')。

4用用户邮箱换通道码

你不需要让用户在你的网站注册账号，也不需要用户先来官网注册。只要拿到用户的邮箱，就能给他开一条专属推送通道。

4.1 用户会经历什么

1. 你发起授权会话调用 pushSdk.createEmailSession(email)，得到一个 10 分钟内有效的授权链接。
2. 用户打开链接页面会显示收件邮箱，一封验证码邮件随之发出。
3. 用户填写验证码登录在官网页输入邮件里的验证码，完成登录。
4. SDK 取回通道码你轮询 pushSdk.pollSession(sessionId)，状态变成 success 时拿到该用户的通道码。

4.2 最省事的方式：直接挂一张授权卡片

SDK 自带一张完整的「一键开通」卡片，包含登录方式下拉、邮箱输入、验证码引导和轮询。你只需要给一个容器：

<div id="auth-slot"></div>

<script src="https://push.phprm.com/static/js/push-sdk.js"></script>
<script>
YfPush.create({ mcpSource: 'my-website' }).mountAuthCard('#auth-slot', {
  title: '订阅更新通知',
  desc: '用邮箱接收验证码，开通后新内容会推送到你常用的聊天工具。',
  onSuccess: function (result) {
    // result.channelCode 就是这位用户的推送通道码
    fetch('/api/save-channel', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ channelCode: result.channelCode })
    });
  }
});
</script>

卡片会自己从服务端读取当前支持的登录方式（飞书、钉钉、Gitee、GitHub、邮箱验证码），官方新增登录方式时你不用改代码。

4.3 想自己画界面：手动两步

var pushSdk = YfPush.create({ mcpSource: 'my-website' });

// 1. 用邮箱创建授权会话
pushSdk.createEmailSession('user@example.com').then(function (session) {
  // session.sessionId / session.authUrl / session.pollInterval / session.expiresIn
  window.open(session.authUrl, '_blank');   // 用户在这里输入邮件验证码

  // 2. 按 pollInterval 轮询，直到 success
  var timer = setInterval(function () {
    pushSdk.pollSession(session.sessionId).then(function (r) {
      if (r.status === 'pending') { return; }

      clearInterval(timer);
      if (r.status === 'success') {
        saveChannelCode(r.channelCode);     // 存到你自己的用户资料里
      } else {
        // expired / consumed / failed：提示用户重新发起授权
      }
    });
  }, (session.pollInterval || 5) * 1000);
});

落地建议：在用户表里加一个 push_channel_code 字段。每个用户一条自己的通道码，后续停用、重置、查推送记录互不干扰。

5通道管理 API 与页面功能对照

后面这套接口，和你在 一封传话分享页 上看到的按钮一一对应。就算你不写代码，也可以先在那页面上点一遍，理解每条通道在管什么。

6发送推送消息

拿到通道码后，发一条推送只需要请求一个网址：把 head、body、url、avatar 带上即可。

6.1 最简单的方式：一个网址就是一次推送

https://www.phprm.com/services/push/trigger/你的通道码?head=你订阅的栏目更新了&body=《如何选择推送通道》已发布&url=https://your-site.com/post/123&avatar=https://your-site.com/logo.png

直接在浏览器打开这个网址，或用 fetch / $.getJSON 请求它，消息就会推送到通道对应的接收端。参数值里带中文、空格或 & 时，记得先做 URL 编码。

6.2 服务端定时任务 / 后台事件：用 POST

「关注的商品到货」「公告更新」这类不是你点一下才发生的事件，放在服务端请求更方便；正文较长时也用 POST。

curl -X POST "https://www.phprm.com/services/push/trigger/你的通道码" \
  -H "Content-Type: application/json" \
  -d '{"head":"补货提醒","body":"你关注的商品已经到货，库存有限。","url":"https://your-site.com/item/123","avatar":"https://your-site.com/logo.png"}'

POST 只接受 application/json。已经在用 SDK 的项目，也可以继续调用 pushSdk.sendPushMessage(通道码, { head, body, url, avatar })，参数含义与上面一致。

6.3 安全提醒

• 通道码等同于推送凭证，不要展示给无关的人，也不要写进公开的仓库。
• 组合通道码能触达所有子通道，只放在服务端；前端只使用当前用户自己的子通道码。
• 怀疑泄露时调用 resetChannel 换码，旧码立即失效。
• 给每个用户单独开子通道，停用、重置、查记录都互不影响。

8相关开源项目：AI 弹幕组件

同一作者开源的 teakong/danmu，把实时弹幕接进任意网站。它复用的就是本页介绍的推送通道：一条弹幕就是一条推送消息，页面通过 WebSocket 实时收到并渲染。

• 一行代码接入：一个 script 标签自动加载依赖、连接通道、渲染弹幕，纯前端即可运行。
• 实时 WebSocket 推送：基于 Socket.IO，订阅同一通道的所有页面同时看到弹幕。
• AI 自动弹幕：按设定间隔识别当前页面内容，调用大模型生成弹幕并推送。
• 交互与插件：弹幕支持点赞、关闭；plugins=control 打开左下角设置面板，plugins=input 打开底部发送框。
• 后端可过滤：danMuFilter 回调里异步校验内容、查询点赞数，适合需要审核的场景。
• 兼容性好：严格 ES5，兼容 IE 与 GBK 页面；localStorage 不可用时自动回退 cookie。

一句话集成

<script src="https://ws.phprm.com/static/customer/js/danmu.js?appName=我的网站&channelCode=你的通道码&danMu=1&plugins=control,input"></script>

发出一条弹幕同样是一句话，所有订阅该通道的页面都会实时看到：

$.getJSON('https://www.phprm.com/services/push/trigger/你的通道码?head=这是第一条弹幕');

更多参数、插件与后端过滤示例见仓库说明：github.com/teakong/danmu（国内可用 Gitee 镜像）。

9SKILL 集成：让 AI 助手会推送

官方开源的 Agent Skill teakong/push-server，把「任务完成后推一条通知」变成 AI 助手的默认动作。纯 MCP 调用，不需要脚本或任何运行时依赖，Trae、Claude、Cursor、WorkBuddy 等客户端都适用。

• 一条命令安装：npx skills add teakong/push-server，装到全局加 -g。
• 纯 MCP，无依赖：推送走 push-server 远程 MCP 服务器，不生成脚本、不装运行时。
• 推送规范内置：标题结论先行、正文 Markdown 排版、单条与多条（批量采集）的判定、发送前链接清洗，都写在 Skill 里。
• 结果可回查：内置令牌换取与消息分页 / 详情接口，AI 能替你查已经推过的消息、管理通道。
• 结构化入库：body 直接传 JSON，经 Webhook 通道原样转发到你的业务服务端。

安装与配置

安装 skill 不等于配好通道，还需要在 AI 客户端里添加远程 MCP 服务器（Streamable HTTP），并把通道码填进 Header：

# 安装到当前项目（全局加 -g）
npx skills add teakong/push-server
npx skills add teakong/push-server -g

{
  "mcpServers": {
    "push-server": {
      "url": "https://www.phprm.com/services/push/mcp",
      "headers": {
        "X-Push-Channel-Code": "你的32位通道码",
        "X-Mcp-Source": "trae"
      }
    }
  }
}

传输类型选 Streamable HTTP（不是 SSE）；部分客户端需要 "type": "streamable-http"，不认该字段就删掉这一行。通道码只填在 Header 里，不要提交进仓库。更多说明见 github.com/teakong/push-server 与 MCP 配置页。