Skip to content

文档同步

本页由 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,默认):应用连 SDK ws(s)://baseUrl,IDENTIFY + 心跳
  • 🔐 Bearer Token 鉴权(API 与 WS IDENTIFY)
  • 📨 频道 / 私聊消息收发,消息 id 格式为 channelId:messageId
  • 约定式 defineAdapter / definePlugin(无需 usePlugin)
  • Webhook(connection: webhook):SDK POST Satori-Opcode: 0 事件到 path

安装 ​

bash
pnpm add @zhin.js/adapter-satori

Plugin 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 接入。

前置条件 ​

  1. 准备兼容 Satori 的服务端,记录 API Base、平台标识和用户标识。
  2. 正向 WS 需 Zhin 可达 Satori 服务;Webhook 需服务端可达 Zhin HTTP Host。
  3. 若服务启用鉴权,在两端配置相同的 Bearer token。

最小配置 ​

yaml
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_intervalWS PING 间隔(毫秒),默认 10000
platform必填,远端 login 的平台标识
userId必填,远端 login 的用户标识(字符串)
tokenBearer;可在 YAML 中引用 ${SATORI_TOKEN}

Webhook ​

yaml
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。