文档同步
本页由 plugins/adapters/satori/README.md 自动生成。请修改包内 README 后运行 pnpm sync:adapter-docs。
@zhin.js/adapter-satori
Zhin.js Satori 聊天协议适配器(Plugin Runtime)。支持 WebSocket 正向客户端(connection: ws)与 Webhook 入站(connection: webhook,经 httpHostToken POST 路由)。
Satori 是聊天协议;图片渲染统一使用
@zhin.js/html-renderer(@pixel.js/shotium),与本适配器无关。
功能特性
- 🔌 Satori 协议 兼容
- 🌐 WebSocket 正向(
connection: ws,默认):应用连 SDKws(s)://baseUrl,IDENTIFY + 心跳 - 🔐 Bearer Token 鉴权(API 与 WS IDENTIFY)
- 📨 频道 / 私聊消息收发,消息 id 格式为
channelId:messageId - 约定式
defineAdapter/definePlugin(无需usePlugin) - Webhook(
connection: webhook):SDK POSTSatori-Opcode: 0事件到path
安装
pnpm add @zhin.js/adapter-satoriPlugin Runtime
@zhin.js/adapter— 约定式adapters/satori/index.ts(defineAdapter)@zhin.js/core—endpointSpec.events入站、统一出站管道zhin.js—plugin.ts(definePlugin)@zhin.js/host-http— Webhook 模式需httpHostToken注册 POST 路由- 配置经插件
schema.json落到顶层<instanceKey>(baseUrl/token/ …)
入站:endpoint[endpointSpec].events.emit('message.receive', { conversation, message, content, sender, metadata })(conversation 为 ConversationRef:DIRECT 频道 → kind private,其余 → kind group、所属 guild 进 parent)
出站:send({ conversation, payload }) → Satori message.create(channel_id = conversation.id)。同一次入站处理结束前的被动回复会原样带回 referrer。段里的 mention 编成 <at>,媒体编成 <img> / <audio> / <video> / <file>,emoji 和规范 face 编成 <emoji>。
入站 metadata.mentioned:消息 content 中 <at id="…"/> 元素的 id 等于登录 selfId(配置的 userId)时置 true。
每个 Endpoint 直接继承 @imhelper/satori-v1 的 SatoriV1Client,由所属 SatoriAdapter 管理。业务代码直接调用 $client.call(resource, method, params) 或其公开便捷方法;协议事件变换、Satori IDENTIFY/心跳与 Webhook 鉴权由该实际 Client 处理,Zhin 投影经 endpointSpec.events 接入。
前置条件
- 准备兼容 Satori 的服务端,记录 API Base、平台标识和用户标识。
- 正向 WS 需 Zhin 可达 Satori 服务;Webhook 需服务端可达 Zhin HTTP Host。
- 若服务启用鉴权,在两端配置相同的 Bearer token。
最小配置
configVersion: 2
# zhin.config.yml(Plugin Runtime)
plugins:
satori: "@zhin.js/adapter-satori"
satori:
connection: ws
heartbeat_interval: 10000
endpoints:
- id: satori-bot
platform: qq
userId: "123456789"
baseUrl: "http://127.0.0.1:5140"
token: "${SATORI_TOKEN}"主配置 plugins 映射需引用 @zhin.js/adapter-satori(instanceKey: satori)。
Endpoint 字段
| 字段 | 说明 |
|---|---|
heartbeat_interval | WS PING 间隔(毫秒),默认 10000 |
platform | 必填,远端 login 的平台标识 |
userId | 必填,远端 login 的用户标识(字符串) |
token | Bearer;可在 YAML 中引用 ${SATORI_TOKEN} |
Webhook
configVersion: 2
plugins:
satori: "@zhin.js/adapter-satori"
satori:
connection: webhook
endpoints:
- id: satori-bot
platform: qq
userId: "123456789"
baseUrl: "http://127.0.0.1:5140"
path: "/satori/webhook"
token: "${SATORI_TOKEN}"SDK 会向 path 发送 POST,请求头 Satori-Opcode: 0 表示事件;每个 Endpoint 必须配置 platform 与 userId。仅接纳这两个字段精确匹配的 login 事件;API 请求也固定使用这组身份。READY 中其他 login 不会改变当前账号。
鉴权
- API:请求头
Authorization: Bearer {token} - WebSocket:IDENTIFY 时 body 中传
token
消息 id 与撤回
- 消息 id 格式为
channelId:messageId,便于发消息 / 撤回时解析。 - 撤回时需
channel_id+message_id,适配器已按上述格式解析。
协议文档
Console 页面
启动后打开 Console 的「Satori」页(地址 /satori),可以:
- 查看运行中的连接、点「测试连接」做连通性诊断;
- 经所属 Adapter 增删持久化账号、启停单个 Endpoint;凭据由 Host 加密仓储保存,不改启动 YAML 或
.env,不重启进程; - 如果适配器要求登录,页面会显示 LoginAssist 的扫码 / 滑块 / 设备确认待办;
读取需要 satori:read(read 级别,内置角色 viewer 及以上都有);增删改账号等写操作需要 satori:write(operate 级别,operator 及以上都有,绑定到本适配器的角色也算),首次迁移还需管理员身份;全局所有者不受限,见插件权限的级别。页面里的「添加 endpoint」等价于原来的 satori endpoint add。
故障排查
| 现象 | 排查 |
|---|---|
| WS IDENTIFY 失败 | 检查 baseUrl、平台/用户标识与 token |
| Webhook 无事件 | 确认路径、Satori-Opcode: 0 与 HTTP Host |
| 401 | 检查 API、WS IDENTIFY 与 Webhook 使用的 token 是否一致 |
| 发送目标错误 | 核对 channel_id 与 Conversation kind;DIRECT 才映射为 private |
成员身份
Satori 事件不带可靠的群主 / 管理员信息,不上报 sender.platform,能力画像也不声明 scene.platformStanding。详见 ADR 0056 §1。