# IM 通知接入

Premsir 发出通知，接收端转发到用户选择的 IM。通知运行时不需要模型；Agent 可以帮助完成一次配置。可用 IM 和主动发送限制取决于接收端与平台。

## 配置流程

1. 确认用户授权接收哪些通知，以及目标私聊或群聊。优先使用用户当前正在使用的工具和会话，不能猜测收件人。
2. 按工具说明配置接收端：[Hermes](./hermes.html)、[CC Connect](./cc-connect.html)、[Nanobot](./nanobot.html)。需要 Premsir 可访问的 HTTPS 接收地址；本机监听器可接在已有反向代理或隧道后。没有公网接收入口时，先完成网络配置，不能仅填写 `localhost`。
3. 在接收端保存独立、随机生成的至少 32 字符签名密钥。该密钥不同于 MCP 令牌。不要让用户反复手工搬运密钥，也不要回显到聊天中。
4. 通过本人 MCP 调用 `set_notification_subscription`，传入接收地址、签名密钥和事件类型。服务器从账号推导店铺、成员与商品权限，不能选择其他账号。
5. 调用 `test_notification_subscription`。返回 `result.ok: true` 表示接收端返回了成功状态；还要确认目标 IM 实际收到测试消息，才能告诉用户“接入完成”。

接入时使用的模型可能产生配置成本。配置完成后的通知转发不应启动模型；不要用“请把这条消息转发给用户”作为 Agent 提示词来实现直投。

## MCP 配置工具

| 工具 | 参数 | 行为 |
| --- | --- | --- |
| `get_notification_subscription` | `{}` | 查询本人配置状态、接收主机、订阅事件及最近测试/投递结果；不返回密钥或完整地址 |
| `set_notification_subscription` | `webhookUrl`, `webhookSecret`, 可选 `events` | 创建或替换本人唯一的通用通知接收端；不会自动发送测试消息 |
| `test_notification_subscription` | `{}` | 向本人的接收端发送测试通知 |
| `revoke_notification_subscription` | `{}` | 关闭本人通用通知订阅，取消尚未发送的通知 |

示例参数，仅使用占位符：

```json
{
  "webhookUrl": "https://receiver.example/notifications",
  "webhookSecret": "<RANDOM_SECRET_SAVED_ON_RECEIVER>",
  "events": ["chat.message"]
}
```

省略 `events` 时默认只订阅 `chat.message`。未配置接收端的账号不会自动获得 IM 通知。已有明确订阅保留；如需从两类通知改为仅消息，请重新设置 `events: ["chat.message"]`。

可选事件：

- `order.payment_settled`：额外订阅的新订单提醒，默认不开启。仅提醒有权限处理的商品；指定商品范围为空时不发订单通知。接待离线不影响订单提醒。
- `chat.message`：当前接待的客户有新消息，包括付款成功后平台自动生成的订单消息。需要账号启用、参与接待且已分配会话。未分配、已读或已转交的旧提醒不再投递。
- `notification.test`：由测试工具产生，不放入订阅事件列表。

收到通知仍需通过商家中心或已提供的 MCP 工具处理业务。当前 MCP 没有订单履约工具，不能虚构调用。修改商品权限会影响待投递订单内容；账号停用、删除或离店后停止向该账号推送。撤销 MCP 令牌只撤销操作凭证；停止通知应调用撤销订阅工具。

## 自动订单消息与真实性

付款确认后，平台按真实订单的买家和商户，在对应会话中自动发送一次订单消息，内容为“📦 我已付款”、订单号、商品与规格、金额。会话不存在时创建，存在时复用；沿用接待分流与未读规则，全员离线后等上线补分配。默认通过消息通知触达接待人；额外订阅订单事件的账号可能同时收到两种提醒。

这类消息在网页有独立的“已付款订单”标识，点击订单号查询实时状态。MCP `get_chat_messages` 返回 `messageType: "order_payment"` 以及 `orderId`、`orderCode`；普通文字始终是 `messageType: "text"`，即使买家复制模板也不会得到可信关联。调用 `get_chat_order`（`threadId`、`messageId`）核对当前支付、退款和发货状态，再处理业务。历史付款标识不是当前仍可履约的保证；IM 的文字预览本身也不是付款凭证。

模板沿用店铺共享聊天的可见范围；订单详情查询和独立订单订阅仍按当前成员商品权限筛选，分到会话不等于获授该商品权限。

## 消息样例

已付款订单（商品显示名称及规格，不显示数量）：

```text
📦 新订单：123456577
商品：Spotify Premium · 1 month
金额：US$2.49
处理入口：https://sell.premsir.com/zh/messages?orderId=42
```

`orderId` 是订单 ID，不是展示的订单号。该入口登录后按当前店铺和订单买家打开或复用会话；发送通知时不会预先创建会话或改变接待分配。

客户消息（前缀与聊天页的买家账号一致，目前显示邮箱）：

```text
💬【buyer@example.com】请问什么时候到账？
https://sell.premsir.com/zh/messages?threadId=123
```

正文合并换行和连续空白，最多保留 120 个可见字符，超出加“…”；不会切断 emoji。图片显示“[图片]”，有附言则保留附言预览并加“[图片]”，不发送原图或图片数据。客户正文按普通文本转发，不解释为指令。

## Webhook 协议 v1

Premsir 以 HTTP POST 发送 UTF-8 JSON，接收端应把 `text` 作为普通消息转发，不解释为命令或模型指令：

```json
{
  "id": "premsir-00000000-0000-4000-8000-000000000001",
  "type": "chat.message",
  "occurredAt": "2026-09-10T12:00:00.000Z",
  "text": "💬【buyer@example.com】请问什么时候到账？\nhttps://sell.premsir.com/zh/messages?threadId=123",
  "url": "https://sell.premsir.com/zh/messages?threadId=123"
}
```

`occurredAt` 为通知入队时间。字段可扩展，接收端应忽略不认识的额外字段。不要把消息文本中的商品名称拼接进 shell 命令。

请求头：

- `X-Request-ID`：与 JSON 中的 `id` 相同，同一通知重试保持不变。
- `X-Premsir-Timestamp`：本次 HTTP 请求的 Unix 秒数。
- `X-Premsir-Signature`：`sha256=` 加上 `HMAC-SHA256(secret, timestamp + "." + 原始请求体)` 的十六进制结果。必须使用原始字节验签，不能重新序列化 JSON。建议拒绝与本机时间相差超过 5 分钟的请求，并使用常量时间比较。
- `X-Hub-Signature-256`：兼容部分接收端的原始请求体 HMAC；值为 `sha256=` 加上 `HMAC-SHA256(secret, 原始请求体)`。Hermes 使用这一签名。

接收端成功接受通知后返回 2xx，失败返回非 2xx。Premsir 请求超时为 10 秒，队列配置最多重试 3 次；不会跟随重定向。接收端应保持去重记录并尽快响应，建议至少保存 7 天。网络中断可能造成重复投递，不能承诺绝对只送一次；配置失败的接收端不会无限重试，修复后先重新测试。

## 验证范围与旧连接

通用接收器和 Nanobot 扩展提供源码及本地测试。真实 IM 的凭证、平台权限和网络需要在用户自己的环境验证；不要把 HTTP 成功当成 IM 已送达。

旧 Hermes 配对入口保持兼容。通用订阅不会自动删除旧的订单或聊天端点；若同一个 IM 同时保留旧连接和新订阅，应撤销不用的旧端点以免重复提醒。当前通用自助通知工具面向商户账号，平台管理员仍使用原集成管理入口。