# Nanobot 接入 IM 通知

先阅读[通用通知接入](./notifications.html)。Nanobot 的普通消息输入与 trigger 会进入 Agent 处理，不能直接拿它们实现零模型通知。这里使用接收扩展，把已签名通知放到现有网关的 **outbound** 发送队列。

## 安装接收扩展

核对日期：2026-09-10。本地适配验证基于 Nanobot `d7de5d5344bb64cd64b5cf8eec7951499757cceb`，覆盖扩展发现、签名请求进入 outbound 队列和去重，没有使用真实 IM 凭证。当前主线使用 `nanobot/channels/<name>/` 通道包；旧版本的插件机制可能不同。先检查安装版本是否支持下列结构，不要覆盖已有文件或假定任意版本兼容。

在 Nanobot 使用的 Python 环境中找到 `nanobot/channels` 目录，新建 `premsir_notify`，放入以下四个文件：

- [`__init__.py`](./adapters/nanobot/__init__.py)
- [`manifest.py`](./adapters/nanobot/manifest.py)
- [`runtime.py`](./adapters/nanobot/runtime.py)
- [`receiver.py`](./adapters/receiver.py)，与前三个文件放在同一目录。

这是安装到 Nanobot 环境中的扩展；升级或重装 Nanobot 后需要检查它是否仍存在。`nanobot plugins list` 应能找到 `premsir_notify`。

## 配置

保持原 IM 通道配置，在 `channels` 下增加：

```json
{
  "premsir_notify": {
    "enabled": true,
    "port": 8787,
    "targetChannel": "<EXISTING_CHANNEL_NAME>",
    "targetChatId": "<CONFIRMED_CHAT_ID>",
    "secretEnv": "PREMSIR_NOTIFICATION_SECRET",
    "state": "~/.nanobot/premsir-notifications.sqlite3"
  }
}
```

将签名密钥设置在 gateway 服务的环境变量中，然后按用户环境的服务管理方式重启 gateway。接收器监听 `127.0.0.1:8787/notifications`，通过已有 HTTPS 入口暴露；使用该地址调用 `set_notification_subscription`，再测试 IM 收件。

`targetChannel` 和 `targetChatId` 来自用户已经配置且确认的目标。支持命名实例的版本要填写实际运行通道名。接收端拒绝由通知内容指定收件人。

## 投递语义

扩展只调用 `bus.publish_outbound(OutboundMessage(...))`，不调用 `_handle_message`、`publish_inbound` 或 Agent。它不新建第二个 IM 登录实例，直接使用已有网关。

返回成功表示通知已进入 Nanobot 的发送队列，**不是 IM 已收到的回执**。后续发送由 Nanobot 负责；若网关在接受后、发送前退出，内存队列可能丢失通知。因此必须用测试通知验证实际收件，并保持 gateway 运行。需要端到端持久化投递的环境应使用带可靠队列的发送适配，而不能声称本扩展保证不丢消息。

## 依据

- [官方通道包说明](https://github.com/HKUDS/nanobot/blob/main/docs/channel-package-guide.md)
- [消息总线](https://github.com/HKUDS/nanobot/blob/main/nanobot/bus/queue.py)
- [IM 通道管理](https://github.com/HKUDS/nanobot/blob/main/nanobot/channels/manager.py)