push-server

# 一封传话推送 > **优先级总则（最高）**：本文件里的所有规范——emoji 用法、单条还是多条、Markdown 与 JSON 的选择、body 结构、乃至全部示例——都只是**用户没表态时的缺省基线**。用户一旦明确说出自己的推送偏好（如「不要 emoji」「分开推送」「就要表格」「标题不用 emoji，正文必须有」「用 Node 风格一点」），**一律以用户偏好为准**，本文件中与之冲突的规则自动让位；用户没提的部分仍按缺省执行。同一条消息里多条偏好冲突时，向用户确认一句，不要自作主张合并。 通过 `push-server` MCP 向用户汇报任务成果、向通知通道（IM 客户端、浏览器、webhook API）发送重要通知，把抓取内容以 JSON 推到用户自己的业务服务器，或用短期令牌经 HTTP 接口回查历史消息。 三个 MCP 工具按用途分工，**不要串用**： | 工具 | 用途 | |---|---| | `send_push_message` | 推送一条消息，绝大多数场景用它 | | `send_multi_message` | **仅批量采集类**一次调用发完多条（1~32 条），每条可指定自己的通道码。表格 / 报告场景不要用 | | `get_access_token` | 用同一个通道码换短期 `access_token`，仅供后面的 HTTP 业务接口使用 | 推送工具与 `get_access_token` 都只认 `X-Push-Channel-Code`（长期通道码）；HTTP 业务接口只认 `Authorization: Bearer <access_token>`。**通道码不能当 Bearer 用，令牌也不能拿去推送。** ## 何时调用 - 当用户明确要求发送通知或汇报执行结果时。 - 用户**明确要求分开推**时（「分别推送」「分开推送」「每个 X 单独推一条」「一条一条发」「这个单独发我」）→ `send_multi_message`，照做。**不要替用户合并成一条。** - **批量采集**时（一批并列结果每条各推一条，如「批量采集这 20 个页面」），或需要把结果同时推送到不同通道（不同通道码）时 → `send_multi_message`。 - 用户要求「整理成表格」「做成报告」「汇总给我」时 → **单条 `send_push_message`，body 写 Markdown 表格**。表格是用来横向对比的，拆成多条就废了。 - 需要把采集到的结构化内容以 JSON 推送到用户自己的服务器（webhook 通道）时。 - 需要列出或打开已推送过消息（分页、详情）时 → 先取令牌，再用 HTTP 接口。 - 需要管理通道本身时（看下有哪些通道、改成员昵称、新增/修改/删除/重置通道）→ 先取令牌，再用 HTTP 接口，规则详见 [references/api.md](references/api.md)。 ## 随附参考文件（按需读取） 本文件只保留「推送 + 判定 + 红线 + 一个最小示例」。其余内容分裂成两份参考，**只在要做这些事时才读，不要预加载**： | 要什么 | 读哪个 | |---|---| | 要把采集到的**结构化数据落到你自己的业务系统**（商品库 / 线索库 / 工单 / 时序指标，`body` = JSON，零 emoji） | [references/example.md](references/example.md) **第 1 节** | | 组装推送内容时找场景参考（签到、采集、监控告警、CI、订单、行情、安全事件、日报周报等 11 类） | [references/example.md](references/example.md) 第 **2~12** 节（第 13 节是反例对照） | | 通道管理、消息回查、字段 / 枚举 / 错误码的完整说明 | [references/api.md](references/api.md) | **组装内容前先看 example.md 里最接近的场景照着改**，比从零写快，也不容易漏掉「head 结论先行」和「📌 下一步」。 ## 配置说明（用户必读） **安装 skill ≠ 配置通道**，必须先完成两步，否则无法推送： 1. 在 [一封传话](https://push.phprm.com/mcp.html) 注册账号并创建推送通道，获取 32 位通道码。 2. 在 AI 助手中手动添加远程 MCP 服务器（以 Trae CN 为例：AI 侧边对话框右上角「设置 → MCP → + 添加 → 手动添加」，选择 **Streamable HTTP** 类型），填入以下 JSON 并替换通道码： ```json { "mcpServers": { "push-server": { "url": "https://www.phprm.com/services/push/mcp", "headers": { "X-Push-Channel-Code": "${PHPRM_CHANNEL_CODE}", "X-Mcp-Source": "trae" } } } } ``` - **名称**：`push-server`（固定，必须与本技能调用的服务器名一致） - **URL**：`https://www.phprm.com/services/push/mcp` - **Headers**： - `X-Push-Channel-Code`：32 位通道码（必须配置，否则无法接收推送） - `X-Mcp-Source`：客户端标识（可选，仅用于服务端日志区分来源，可填 `trae`、`workbuddy`、`coze` 等任意值，按自己的客户端改） - **传输类型**：Streamable HTTP（不是 SSE）。部分客户端要求 JSON 里显式声明 `type`，两种写法按客户端二选一、不要同时写：`"type": "streamable-http"`（Trae / Cursor / Cline 等多数客户端）或 `"type": "streamableHttp"`（WorkBuddy 等驼峰写法）；不认该字段的客户端整行删掉即可。 Claude Code、Cursor 等其他客户端同理，在各自的 MCP 配置中添加同名 HTTP 服务器即可。配置保存在用户本地客户端，不会进入任何代码仓库。 > **配好了 ≠ 能推送，连上了也不等于凭证生效。** MCP 端点是**匿名可连接**的：即使完全没配 `X-Push-Channel-Code`（或占位符没被客户端解析），客户端照样能连上并列出三个工具。**工具列表出现不能作为凭证有效的证据**，只有真正推送成功才算。这正是「MCP 显示已连接、工具也出来了，一推就报通道码缺失 / 无效」的来源——排查时直接核对 Header 名与通道码是否被真正替换，不要去反复重连服务器。 ## 凭证模型 | 场景 | 入口 | 凭证 | |---|---|---| | 推送单条 | MCP `send_push_message` | Header `X-Push-Channel-Code` | | 推送多条 | MCP `send_multi_message` | Header `X-Push-Channel-Code` | | 换取令牌 | MCP `get_access_token` | Header `X-Push-Channel-Code` | | 查询消息等业务 API | HTTP `https://www.phprm.com/oauth2/push/*` | `Authorization: Bearer ${CHANNEL_ACCESS_TOKEN}` | | 健康自检 | HTTP `https://www.phprm.com/services/public/ping` | 无需凭证 | - **通道码**：32 位长期凭证，只出现在 MCP 的两个推送工具与 `get_access_token` 的 Header / 入参中；仅在用户在控制台重置后才需要替换。 - **`access_token`**：短期动态凭证，由 `get_access_token` 签发，有效期 `expires_in` 秒（服务端默认 **7200 秒 = 2 小时**）。下文 curl 用 `${CHANNEL_ACCESS_TOKEN}` 代指。它的本体是一段 **RS256 签名的 JWT**（`eyJ` 开头的三段式）；直接当不透明字符串用即可，别去校验前缀、长度或自己验签。 **令牌应该在一次任务里复用，不要每条接口都重取**：同一个 `access_token` 可以连续调用任意多个 `/oauth2/push/*` 接口（9 个接口都认同一份 Bearer），重复调用 `get_access_token` 也不会让之前那张失效。所以一轮「取令牌 → 查分页 → 查详情 → 改通道」的任务里，只在开头取一次。 - **按 `expires_in` 而不是凭感觉缓存**：用它可以直用到过期前；稳妥做法是留 60~120 秒余量，快到期了再重取。 - **别把它持久化**：跨会话复用旧令牌会撞上说不清的 401（人和控制台随时可能轮换凭证）。会话内记住即可，不要写进配置文件、长期记忆或推送内容。 - **401 / 403 才是失效信号**：业务错误（`code` 非 0）跟令牌无关，别看到报错就去重取令牌。 - **有一种 401 假象**：`access_token不正确请重新获取` 这条文案也会在「当前令牌主体不是浏览器子通道」时出现，重取一次仍然一样，属于通道结构问题而非过期，别循环重试。 > `/services/public/ping` 除了「活着」还会带回一小段示例通道，见下一节。 ## ping 里的示例通道（可借用，但要打招呼） 健康自检 `/services/public/ping` 是**匿名**端点，除了存活结论还会返回一段 `rows`——服务端维护的**公开示例通道**（字段含义同 `channel/list` 的 `rows[]`，同样带 `pushUrl` / `qrCodeUrl` / `channelMemberRelId`；响应样例见 [references/api.md](references/api.md) 第 3 节）。列表可能为空。 其中两个地址字段可直接用：`pushUrl` 用浏览器打开就是**该通道的分享/管理页面**（share.html）；`qrCodeUrl` 是**推送记录页面**的二维码，扫码即可在手机上查看推送记录。想给用户一个"在哪看消息"的入口时优先用这两个字段，不要自己拼 URL。 如需测试推送，**不要**把返回的 `channelCode` 写进 MCP 配置，只允许通过 `send_push_message` / `send_multi_message` 的 `channelCode` 参数传它。 用它的规矩： - **它是别人的、公开的示范通道**——任何拿到这串码的人都能往里推，所以 `ping` 里出现的码**绝不能当成用户自己的默认通道**，更不要拿去填 `${PHPRM_CHANNEL_CODE}`。 - 唯一允许的用途：**用户明确同意后**用它做一次链路自测（例如用户还没给自己的通道码、但想确认 MCP 是否可用）。自测前说明「这是服务端示例通道，任何人都能往里推」，成功即结束，**不要把正式通知发到这里**。 - 常规推送依然要用**用户本人**的通道码；本节不改动「只能使用用户本人提供的通道码」这条红线。 > 逐个接口对接 / 排错前先看 [references/api.md](references/api.md) 第 0 节（9 个接口的总览与调用约定，尤其是「只认 form / query，JSON body 会被忽略」）和 6.1（按接口预期的失败响应文案）。 ## 业务 API（HTTP） 除健康自检外，全部是 `/oauth2/push/*`，流程两步：**先用 MCP `get_access_token` 换短期令牌 → 再带 `Authorization: Bearer ${CHANNEL_ACCESS_TOKEN}` 调用**。注意**换令牌这一步一轮任务只做一次**（原因与复用规则见上一节），后续接口共用同一张令牌。 调用约定（照错这几条会白试很多次）： - **参数只认 query 或 `application/x-www-form-urlencoded`**。`application/json` 的 body 会被完全忽略，表现为「XXX 参数缺失或非法」。 - **错误一律 HTTP 200 + 非 0 业务码**，靠 `code` 判定，不看 HTTP 状态码。只有 `401/403` 属于令牌失效，重取一次再试。 - **归属由令牌自身决定**，没有接口额外接受归属 / 租户类入参；目标通道一律用 32 位 `channelCode`。 - **别跟 `/services/push/*` 混用**：那是控制台登录态的另一套接口，参数名与返回值都不同。 - 写操作成功返回 `{"code":0,...,"data":true}`；**两个例外**：`resetChannel` 的 `data` 是新的 32 位通道码字符串，`channel/add` 的 `data` 是新建的通道对象（含它的 `channelCode`，可直接当 MCP 凭证，不必再拉一次列表）。 | 用途 | Method | Path | 参数 | 成功时 `data` | |---|---|---|------------------------------------------------------|---| | 健康自检（匿名） | GET | `/services/public/ping` | 无 | `{status,service,rows}`（`rows` 为示例通道，见「ping 里的示例通道」） | | 消息分页 | GET | `/oauth2/push/message/page` | `page`、`limit`（缺省 1 / 10） | `current`/`total`/`totalPage`/`rows` | | 消息详情 | GET | `/oauth2/push/message/detail` | `messageId`（取自分页） | 单条消息 + `viewCount` | | 通道列表 | GET | `/oauth2/push/channel/list` | 可选筛选：`channelName`（模糊）、`pushTypeName`（推送方式） | 顶层父通道信息 + `rows`（浏览器子通道另带 `pushUrl` / `qrCodeUrl`） | | 新增通道 | POST | `/oauth2/push/channel/add` | `channelName` + `pushType` 必填，`webhookUrl` / `signSecret` 按类型可选 | **新建的通道对象**（字段同通道列表 `rows[]`，仅浏览器类型带 `channelMemberRelId` / `nickname`） | | 修改通道 | POST | `/oauth2/push/channel/edit` | `channelCode` + 要改的字段，含可选 **`status`（`1` 启用 / `0` 停用）** | `true` | | 删除通道 | POST | `/oauth2/push/channel/deleteChannel` | `channelCode` | `true` | | 重置通道 | POST | `/oauth2/push/channel/resetChannel` | `channelCode` | **新的通道码字符串** | | 改成员昵称 | POST | `/oauth2/push/channel/member/edit` | `channelMemberRelId` + `nickname`（≤16 字符，空白算缺失） | `true` | 下面这张表只是**路由索引**——字段、枚举、边界一律不在这里展开，通道管理细则只维护在 [references/api.md](references/api.md)，**做通道操作前先读它**： | 要什么 | 去 api.md | |---|---| | 通道列表的字段含义、「当前通道怎么找」 | 5.1 | | 新建通道的入参与「别重复建同一类型的通道」 | 5.2 | | 改通道（含停用 `status=0` / 启用 `status=1`） | 5.3 | | 删除的边界（当前通道不能删） | 5.4 | | 重置的边界 + 重置后如何把新码写回 MCP | 5.5 | | 改成员昵称（成员侧唯一接口） | 5.6 | | `pushType` 取值表 / `status` 取值（只有 `0` / `1`） | 5.7 / 5.8 | | 「推送到 xx 通道」用哪个通道码 | 5.9 | | 各接口的失败文案与处理建议 | 6.1 / 6.2 | ## 执行步骤 1. 确认通道码：`${PHPRM_CHANNEL_CODE}` 占位符未解析（Header 未生效）且用户没给时，先向用户索取其本人的 32 位通道码，**不猜测、不用别人的通道码**。拿到后**默认显式传进 `channelCode`**——远端 schema 把 `channelCode` 列进了 `required`，无条件传可以避免客户端的严格校验卡住这一步（详见「工具参数」）。 2. 选工具：**默认单条 `send_push_message`**。升级为 `send_multi_message` 只有三种情况：**用户明确要求分开推**（「分别推送」「每个 X 单独一条」）、**批量采集**（并列结果每条各推一条）、**要发到不同通道**（每条可带自己的 `channelCode`）。反过来，**用户要表格 / 报告时不要拆成多条**，直接在单条 body 里写 Markdown 表格。**用户的显式措辞优先于这些缺省判断。**非常简单的结果可以只给 `head`。 3. 组装每条消息的 `head`（必填，≤200，纯文本）、`body`（可选，Markdown 或 JSON，≤50000）、`url`（可选，≤500）。**先分岔**：数据要落到用户的业务服务器（webhook）→ `body` 写合法 JSON 且整条零 emoji，字段名对齐对方表结构、带上批次号与采集时间；其余给人看的 → head 前置一个结论 emoji、body 按状态灯与结果符排版，规范见「内容排版：emoji 可读化」。 4. **发送前清洗（强制）**：接收端 H5 用 showdown 渲染 `body`，URL 外层一旦包了反引号，转换后会污染 `href`/`src`，导致链接点不动、图片裂图。对每条消息的 `body` 和 `url` 依次执行： ``` body = body.replace(/\]\(`(https?:\/\/[^`]+)`\)/g, ']($1)') // ① 链接语法内: ](`URL`) → ](URL) body = body.replace(/`(https?:\/\/[^`\s)]+)`/g, '$1') // ② 裸 URL 外层反引号: `URL` → URL url = url.replace(/`(https?:\/\/[^`\s]+)`/g, '$1') // ③ url 字段同样清洗 ``` 反例：点[「详情」](`https://push.phprm.com/message/x`)。正例：点[「详情」](https://push.phprm.com/message/x)。反引号只用于文件名、命令、代码标识等非 URL 内容。 5. 调用对应工具，**必须调用已注册的 `push-server` MCP 服务器提供的工具**（本 skill 不是 MCP 服务器，不能把 skill 名当 server 调用）。 6. 判定成功：`{"code":0, ...}` 且 `data.messageIdList` 非空即推送成功；`send_multi_message` 返回的是所有消息 ID 的并集，任一条失败即整次调用返回失败。 7. 需要回看已推送内容时：先 `get_access_token`，再按 [references/api.md](references/api.md) 调用消息分页/详情接口。 ## 工具参数 三个工具的 `channelCode` 都被远端 schema 列进了 `required`，但服务端描述为「Header 已预置时可省」——**两种语义并存**，严格按 schema 校验的客户端可能在 Header 已生效时仍报缺参。**稳妥做法：始终显式传 `channelCode`**（值与 Header 同源），一次写死就不用再拿模式去猜： - Header 未生效（没配 `${PHPRM_CHANNEL_CODE}`）：**必须显式传 `channelCode`**。 - Header 已生效但客户端报缺 `channelCode`：把同一串通道码显式填进 `channelCode`（值与 Header 一致），不要为此改配置或换工具。 > **`body` 支持 Markdown / 纯文本 / JSON，已是远端 schema 的正式口径**：两个推送工具（单条的 `body`、多条的 `messages[].body`）的 schema 描述都已写明「Accepts Markdown, plain text, or a JSON document」，并注明内容**按字符串原文转发、不在服务端解析或渲染**——webhook 入库时把 JSON 文本塞进 `body` 会被原样投递到接收端，这是结构化数据入库链路的基础。个别尚未同步的实例返回的仍是更早的描述（只写了 Markdown），那只是文案滞后，**JSON 一样能推，别被旧描述拦住**。同理「不支持 HTML」是渲染侧（接收端 showdown）的约束，不是传输侧限制。 ### send_push_message | 字段 | 必填 | 说明 | |---|---|---| | `head` | 是 | 标题，纯文本，支持 Unicode，≤200 字符 | | `body` | 否 | 正文，Markdown/JSON（不支持 HTML，勿用 `<br>`、`<table>`）；JSON 用于 webhook 推送到业务服务器，接收方按原文解析、不渲染。≤50000 字符 | | `url` | 否 | 跳转链接（如 PR 地址、构建日志），≤500 字符 | | `channelCode` | 条件必填 | 覆盖 Header 中的通道码；不传则用 `X-Push-Channel-Code`。Header 预置时服务端可省，但 schema 标了必填（见本节开头） | ### send_multi_message | 字段 | 必填 | 说明 | |---|---|---| | `messages` | 是 | 数组，1~32 项，每项 `{ head 必填, body, url, channelCode }` | | `messages[].head` | 是 | 同上，逐项必填 | | `messages[].channelCode` | 否 | 该项单独指定通道；不传则用工具级 `channelCode` / Header 通道码 | | `channelCode` | 条件必填 | 工具级通道码，作为所有未单独指定项的默认通道；不传则用 Header（同样 schema 必填、Header 预置时可省） | 多条并发推送，**任一条失败整次即失败**并返回第一条失败原因；超过 32 条需拆成多次调用。 **用之前先确认是否真的需要多条**——默认应该是单条： | 用户的要求 | 用哪个 | |---|---| | 「分别推送」「分开推送」「一条一条发」「这个单独发我」 | `send_multi_message` ——**用户点了名，照做** | | 「批量采集这 N 个 X」「每个 X 各推一条」 | `send_multi_message` | | 同一份内容要发到多个不同通道 | `send_multi_message` | | 「整理成表格」「做成报告」「汇总给我」「做个对比」 | **单条** `send_push_message`，body 写 Markdown 表格 + 分区标题 | | 「跑完了，告诉我结果」「帮我推一下」 | **单条** | 用户说「分开 / 分别」时不要替他合并——哪怕你觉得合成一条表格更好看。想优化可以推完之后问一句要不要合并。 **表格 / 报告类是最常见的误用点**：这类内容的价值在于行列之间的横向对比，拆成多条推送后，用户拿到的是 N 条孤立数据，要自己按顺序回忆才能比。除非用户明确说「每个 X 单独推一条」，否则一律走单条 + Markdown 表格。 ### get_access_token | 字段 | 必填 | 说明 | |---|---|--------------------------------------------------------| | `channelCode` | 条件必填 | 要换令牌的通道码；不传则取 Header `X-Push-Channel-Code`（schema 同样标了必填，见本节开头） | | `scope` | 否 | 必须是该通道客户端已登记的 scope 的子集；不传则使用服务端默认值 `basic` |