@zhin.js/adapter-satori 0.0.0

package/lib/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Satori 适配器类型（参考 https://satori.chat 协议）
+ */
+/** 配置公共字段；单一适配器 context 均为 'satori'，连接方式由 connection 区分 */
+export interface SatoriConfigBase {
+    context: 'satori';
+    name: string;
+    baseUrl: string;
+    /** 认证 token，API 用 Authorization: Bearer，WebSocket IDENTIFY 用 token 字段 */
+    token?: string;
+}
+/** WebSocket 连接（应用连 SDK /v1/events） */
+export interface SatoriWsConfig extends SatoriConfigBase {
+    connection: 'ws';
+    /** 心跳间隔（毫秒），默认 10000 */
+    heartbeat_interval?: number;
+}
+/** WebHook（SDK POST 到应用提供的 path） */
+export interface SatoriWebhookConfig extends SatoriConfigBase {
+    connection: 'webhook';
+    path: string;
+}
+export type SatoriBotConfig = SatoriWsConfig | SatoriWebhookConfig;
+/** WebSocket/API 信号：op + body */
+export interface SatoriSignal {
+    op: number;
+    body?: Record<string, unknown>;
+}
+/** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
+export declare const SatoriOpcode: {
+    readonly EVENT: 0;
+    readonly PING: 1;
+    readonly PONG: 2;
+    readonly IDENTIFY: 3;
+    readonly READY: 4;
+    readonly META: 5;
+};
+/** 事件体（EVENT 的 body）：type、sn、timestamp、login、message、channel、user 等 */
+export interface SatoriEventBody {
+    type?: string;
+    sn?: number;
+    timestamp?: number;
+    login?: SatoriLogin;
+    message?: SatoriMessage;
+    channel?: SatoriChannel;
+    user?: SatoriUser;
+    guild?: {
+        id: string;
+        name?: string;
+    };
+    member?: {
+        user?: SatoriUser;
+        nick?: string;
+        roles?: string[];
+    };
+    [key: string]: unknown;
+}
+/** Login 资源（READY 与事件中） */
+export interface SatoriLogin {
+    platform?: string;
+    user?: SatoriUser;
+    status?: number;
+    sn?: number;
+}
+/** Channel 资源：id, type (0=TEXT,1=DIRECT,2=CATEGORY,3=VOICE) */
+export interface SatoriChannel {
+    id: string;
+    type?: number;
+    name?: string;
+    parent_id?: string;
+}
+/** User 资源 */
+export interface SatoriUser {
+    id: string;
+    name?: string;
+    avatar?: string;
+}
+/** Message 资源：id, content（元素字符串）, channel, user 等 */
+export interface SatoriMessage {
+    id: string;
+    content?: string;
+    channel?: SatoriChannel;
+    user?: SatoriUser;
+    member?: {
+        user?: SatoriUser;
+        nick?: string;
+    };
+    created_at?: number;
+    updated_at?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,QAAQ,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,UAAU,EAAE,IAAI,CAAC;IACjB,wBAAwB;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,oCAAoC;AACpC,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,UAAU,EAAE,SAAS,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,mBAAmB,CAAC;AAEnE,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,kEAAkE;AAClE,eAAO,MAAM,YAAY;;;;;;;CAOf,CAAC;AAEX,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,UAAU,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,2BAA2B;AAC3B,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,cAAc;AACd,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,UAAU,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/lib/types.js

@@ -0,0 +1,13 @@
+/**
+ * Satori 适配器类型（参考 https://satori.chat 协议）
+ */
+/** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
+export const SatoriOpcode = {
+    EVENT: 0,
+    PING: 1,
+    PONG: 2,
+    IDENTIFY: 3,
+    READY: 4,
+    META: 5,
+};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgCH,kEAAkE;AAClE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,CAAC;IACX,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;CACC,CAAC"}

package/lib/utils.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Satori 事件与 zhin Message 的转换
+ */
+import type { SendContent } from 'zhin.js';
+import type { SatoriEventBody, SatoriMessage, SatoriChannel } from './types.js';
+/** Satori Channel.type: 0=TEXT, 1=DIRECT, 2=CATEGORY, 3=VOICE */
+export declare function isPrivateChannel(channel?: SatoriChannel): boolean;
+/** 将 Satori 事件体转为 zhin Message 的 MessageBase（仅 message-created/updated，供 $formatMessage 使用） */
+export declare function formatSatoriMessagePayload(body: SatoriEventBody, adapterName: 'satori', botName: string, recallFn: (msgId: string) => Promise<void>, replyFn: (channel: {
+    id: string;
+    type: 'group' | 'private';
+}, content: (string | {
+    type: string;
+    data?: Record<string, unknown>;
+})[], quote?: boolean | string) => Promise<string>): {
+    $id: string;
+    $adapter: 'satori';
+    $bot: string;
+    $channel: {
+        id: string;
+        type: 'group' | 'private';
+    };
+    $sender: {
+        id: string;
+        name: string;
+    };
+    $content: Array<{
+        type: string;
+        data: Record<string, unknown>;
+    }>;
+    $raw: string;
+    $timestamp: number;
+    $recall: () => Promise<void>;
+    $reply: (content: SendContent, quote?: boolean | string) => Promise<string>;
+};
+/** 判断是否为消息相关事件（message-created / message-updated） */
+export declare function isMessageEvent(body: SatoriEventBody): body is SatoriEventBody & {
+    message: SatoriMessage;
+};
+//# sourceMappingURL=utils.d.ts.map

package/lib/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhF,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAEjE;AAED,+FAA+F;AAC/F,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAC1C,OAAO,EAAE,CAAC,OAAO,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;CAAE,EAAE,OAAO,EAAE,CAAC,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACjL;IACD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,CAAC;IACpD,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7E,CA4BA;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,IAAI,eAAe,GAAG;IAAE,OAAO,EAAE,aAAa,CAAA;CAAE,CAE1G"}

package/lib/utils.js

@@ -0,0 +1,33 @@
+/** Satori Channel.type: 0=TEXT, 1=DIRECT, 2=CATEGORY, 3=VOICE */
+export function isPrivateChannel(channel) {
+    return channel?.type === 1;
+}
+/** 将 Satori 事件体转为 zhin Message 的 MessageBase（仅 message-created/updated，供 $formatMessage 使用） */
+export function formatSatoriMessagePayload(body, adapterName, botName, recallFn, replyFn) {
+    const msg = body.message;
+    const channel = body.channel ?? msg.channel;
+    const user = body.user ?? msg.user ?? msg.member?.user;
+    const channelId = channel?.id ?? '';
+    const isPrivate = isPrivateChannel(channel);
+    const content = msg.content ?? '';
+    const raw = typeof content === 'string' ? content : String(content);
+    const senderId = user?.id ?? '';
+    const senderName = user?.name ?? msg.member?.nick ?? senderId;
+    return {
+        $id: `${channelId}:${msg.id}`,
+        $adapter: 'satori',
+        $bot: botName,
+        $channel: { id: channelId, type: isPrivate ? 'private' : 'group' },
+        $sender: { id: senderId, name: senderName },
+        $content: [{ type: 'text', data: { text: raw } }],
+        $raw: raw,
+        $timestamp: body.timestamp ?? msg.created_at ?? Math.floor(Date.now() / 1000),
+        $recall: () => recallFn(`${channelId}:${msg.id}`),
+        $reply: (cnt, quote) => replyFn({ id: channelId, type: isPrivate ? 'private' : 'group' }, (Array.isArray(cnt) ? cnt : [cnt]), quote),
+    };
+}
+/** 判断是否为消息相关事件（message-created / message-updated） */
+export function isMessageEvent(body) {
+    return (body.type === 'message-created' || body.type === 'message-updated') && !!body.message?.id;
+}
+//# sourceMappingURL=utils.js.map

package/lib/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAOA,iEAAiE;AACjE,MAAM,UAAU,gBAAgB,CAAC,OAAuB;IACtD,OAAO,OAAO,EAAE,IAAI,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,0BAA0B,CACxC,IAAqB,EACrB,WAAqB,EACrB,OAAe,EACf,QAA0C,EAC1C,OAAkL;IAalL,MAAM,GAAG,GAAG,IAAI,CAAC,OAAQ,CAAC;IAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;IACvD,MAAM,SAAS,GAAG,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC;IACpC,MAAM,SAAS,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC;IAChC,MAAM,UAAU,GAAG,IAAI,EAAE,IAAI,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,IAAI,QAAQ,CAAC;IAE9D,OAAO;QACL,GAAG,EAAE,GAAG,SAAS,IAAI,GAAG,CAAC,EAAE,EAAE;QAC7B,QAAQ,EAAE,QAAQ;QAClB,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE;QAClE,OAAO,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE;QAC3C,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;QACjD,IAAI,EAAE,GAAG;QACT,UAAU,EAAE,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QAC7E,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,SAAS,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;QACjD,MAAM,EAAE,CAAC,GAAgB,EAAE,KAAwB,EAAE,EAAE,CACrD,OAAO,CACL,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,EACxD,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAkE,EACnG,KAAK,CACN;KACJ,CAAC;AACJ,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,cAAc,CAAC,IAAqB;IAClD,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,iBAAiB,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;AACpG,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@zhin.js/adapter-satori",
+  "version": "0.0.0",
+  "description": "Zhin.js adapter for Satori protocol",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "zhin",
+    "bot",
+    "adapter",
+    "satori",
+    "chatbot"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.3.0",
+    "zhin.js": "1.0.50"
+  },
+  "peerDependencies": {
+    "zhin.js": "1.0.50",
+    "@zhin.js/http": "1.0.44"
+  },
+  "peerDependenciesMeta": {
+    "@zhin.js/http": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc && (test -f ../../services/console/lib/bin.js && node ../../services/console/lib/bin.js build || echo 'Skipping client build: console not built yet')",
+    "clean": "rimraf lib"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,46 @@
+/**
+ * Satori 适配器：单一适配器支持 WS 正向 / Webhook，由 config.connection 区分
+ * 协议文档：https://satori.chat/zh-CN/introduction.html
+ */
+import type { Router } from '@zhin.js/http';
+import { Adapter, Plugin } from 'zhin.js';
+import { SatoriWsClient } from './bot-ws.js';
+import { SatoriWebhookBot } from './bot-webhook.js';
+import type {
+  SatoriBotConfig,
+  SatoriWsConfig,
+  SatoriWebhookConfig,
+} from './types.js';
+import type { SatoriEventBody } from './types.js';
+
+export type SatoriBot = SatoriWsClient | SatoriWebhookBot;
+
+export class SatoriAdapter extends Adapter<SatoriBot> {
+  #router?: Router;
+
+  constructor(plugin: Plugin) {
+    super(plugin, 'satori', []);
+  }
+
+  createBot(config: SatoriBotConfig): SatoriBot {
+    switch (config.connection) {
+      case 'ws':
+        return new SatoriWsClient(this, config as SatoriWsConfig);
+      case 'webhook':
+        if (!this.#router) {
+          throw new Error('Satori connection: webhook 需要 router，请安装并在配置中启用 @zhin.js/http');
+        }
+        return new SatoriWebhookBot(this, this.#router, config as SatoriWebhookConfig);
+      default:
+        throw new Error(`Unknown Satori connection: ${(config as SatoriBotConfig).connection}`);
+    }
+  }
+
+  async start(): Promise<void> {
+    this.#router = (this.plugin.inject as (key: string) => Router | undefined)('router');
+    (this.plugin.useContext as (key: string, fn: (router: Router) => void) => void)('router', (router: Router) => {
+      this.#router = router;
+    });
+    await super.start();
+  }
+}

package/src/api.ts

@@ -0,0 +1,48 @@
+/**
+ * Satori HTTP API 封装：POST /v1/{resource}.{method}，头 Satori-Platform、Satori-User-ID、Authorization
+ * 参考 https://satori.chat/en-US/protocol/api.html
+ */
+export interface SatoriApiOptions {
+  baseUrl: string;
+  platform: string;
+  userId: string;
+  token?: string;
+}
+
+/**
+ * 调用 Satori API：POST {baseUrl}/v1/{resource}.{method}，JSON body
+ */
+export async function callSatoriApi<T = unknown>(
+  options: SatoriApiOptions,
+  resource: string,
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<T> {
+  const { baseUrl, platform, userId, token } = options;
+  const url = `${baseUrl.replace(/\/$/, '')}/v1/${resource}.${method}`;
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Satori-Platform': platform,
+    'Satori-User-ID': userId,
+  };
+  if (token) headers['Authorization'] = `Bearer ${token}`;
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(params),
+  });
+
+  const text = await res.text();
+  if (res.status === 401) throw new Error(`Satori API 认证失败: ${text}`);
+  if (res.status === 403) throw new Error(`Satori API 权限不足: ${text}`);
+  if (res.status === 404) throw new Error(`Satori API 不存在: ${resource}.${method}`);
+  if (res.status >= 400) throw new Error(`Satori API 错误 ${res.status}: ${text}`);
+
+  if (!text || text.trim() === '') return undefined as T;
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`Satori API 无效 JSON: ${text.slice(0, 200)}`);
+  }
+}

package/src/bot-webhook.ts

@@ -0,0 +1,117 @@
+/**
+ * Satori WebHook Bot：应用提供 POST path，SDK 推送 EVENT（Satori-Opcode: 0）
+ */
+import { EventEmitter } from 'events';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import type { Router, RouterContext } from '@zhin.js/http';
+import { callSatoriApi } from './api.js';
+import type { SatoriWebhookConfig, SatoriEventBody, SatoriLogin } from './types.js';
+import { SatoriOpcode } from './types.js';
+import type { SatoriAdapter } from './adapter.js';
+import { formatSatoriMessagePayload, isMessageEvent } from './utils.js';
+
+export class SatoriWebhookBot extends EventEmitter implements Bot<SatoriWebhookConfig, SatoriEventBody> {
+  $connected: boolean = true;
+  /** 从首个事件的 login 得到，用于 API 的 platform / userId */
+  private login?: SatoriLogin;
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(
+    public adapter: SatoriAdapter,
+    public router: Router,
+    public $config: SatoriWebhookConfig,
+  ) {
+    super();
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  private apiOptions(): { baseUrl: string; platform: string; userId: string; token?: string } {
+    const platform = this.login?.platform ?? '';
+    const userId = this.login?.user?.id ?? '';
+    return { baseUrl: this.$config.baseUrl, platform, userId, token: this.$config.token };
+  }
+
+  async $connect(): Promise<void> {
+    const path = this.$config.path.startsWith('/') ? this.$config.path : `/${this.$config.path}`;
+    this.router.post(path, async (ctx: RouterContext) => {
+      const opcode = parseInt(ctx.headers['satori-opcode'] as string ?? '', 10);
+      const body = ctx.request.body as SatoriEventBody | undefined;
+      if (opcode === SatoriOpcode.EVENT && body) {
+        if (body.login && !this.login) this.login = body.login;
+        this.handleEvent(body);
+      }
+      ctx.status = 200;
+      ctx.body = {};
+    });
+    this.logger.info(`Satori WebHook 注册路径: ${path}`);
+  }
+
+  async $disconnect(): Promise<void> {
+    this.$connected = false;
+  }
+
+  private handleEvent(body: SatoriEventBody): void {
+    if (isMessageEvent(body)) {
+      const message = this.$formatMessage(body);
+      this.adapter.emit('message.receive', message);
+      this.logger.debug(
+        `${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`,
+      );
+    }
+  }
+
+  $formatMessage(body: SatoriEventBody): Message<SatoriEventBody> {
+    if (!isMessageEvent(body)) {
+      return Message.from(body, {
+        $id: '',
+        $adapter: 'satori',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: body.timestamp ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatSatoriMessagePayload(
+      body,
+      'satori',
+      this.$config.name,
+      (id) => this.$recallMessage(id),
+      (channel, content, _quote) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'satori',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+    );
+    return Message.from(body, payload);
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const channelId = options.id;
+    const contentRaw = segment.raw(options.content);
+    const result = await callSatoriApi(this.apiOptions(), 'message', 'create', {
+      channel_id: channelId,
+      content: contentRaw,
+    });
+    const list = Array.isArray(result) ? result : (result as { data?: unknown[] })?.data;
+    const msg = list?.[0] as { id?: string } | undefined;
+    const msgId = msg?.id ?? '';
+    return msgId ? `${channelId}:${msgId}` : '';
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    const [channelId, messageId] = id.includes(':') ? id.split(':') : ['', id];
+    await callSatoriApi(this.apiOptions(), 'message', 'delete', { channel_id: channelId, message_id: messageId });
+  }
+}

package/src/bot-ws.ts

@@ -0,0 +1,187 @@
+/**
+ * Satori WebSocket Bot：应用连 SDK /v1/events，IDENTIFY 认证，收 EVENT 转 Message
+ */
+import WebSocket from 'ws';
+import { EventEmitter } from 'events';
+import { clearInterval } from 'node:timers';
+import { Bot, Message, SendOptions, segment } from 'zhin.js';
+import { callSatoriApi } from './api.js';
+import type { SatoriWsConfig, SatoriSignal, SatoriEventBody, SatoriLogin } from './types.js';
+import { SatoriOpcode } from './types.js';
+import type { SatoriAdapter } from './adapter.js';
+import { formatSatoriMessagePayload, isMessageEvent } from './utils.js';
+
+export class SatoriWsClient extends EventEmitter implements Bot<SatoriWsConfig, SatoriEventBody> {
+  $connected: boolean;
+  private ws?: WebSocket;
+  private reconnectTimer?: NodeJS.Timeout;
+  private heartbeatTimer?: NodeJS.Timeout;
+  /** READY 后得到的当前登录，用于 API 的 platform / userId */
+  private login?: SatoriLogin;
+  private lastSn?: number;
+
+  get logger() {
+    return this.adapter.plugin.logger;
+  }
+
+  constructor(public adapter: SatoriAdapter, public $config: SatoriWsConfig) {
+    super();
+    this.$connected = false;
+  }
+
+  get $id() {
+    return this.$config.name;
+  }
+
+  private get wsUrl(): string {
+    const base = this.$config.baseUrl.replace(/\/$/, '');
+    return base.replace(/^http/, 'ws') + '/v1/events';
+  }
+
+  private apiOptions(): { baseUrl: string; platform: string; userId: string; token?: string } {
+    const platform = this.login?.platform ?? '';
+    const userId = this.login?.user?.id ?? '';
+    return { baseUrl: this.$config.baseUrl, platform, userId, token: this.$config.token };
+  }
+
+  private sendSignal(op: number, body?: Record<string, unknown>): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    this.ws.send(JSON.stringify({ op, body: body ?? {} }));
+  }
+
+  private startHeartbeat(): void {
+    const interval = this.$config.heartbeat_interval ?? 10000;
+    this.heartbeatTimer = setInterval(() => {
+      this.sendSignal(SatoriOpcode.PING);
+    }, interval);
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) return;
+    const delay = 5000;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.$connect().catch((err) => this.logger.warn('Satori 重连失败', err));
+    }, delay);
+  }
+
+  async $connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.wsUrl);
+
+      this.ws.on('open', () => {
+        this.$connected = true;
+        this.sendSignal(SatoriOpcode.IDENTIFY, {
+          token: this.$config.token,
+          sn: this.lastSn,
+        });
+        this.startHeartbeat();
+        resolve();
+      });
+
+      this.ws.on('message', (data) => {
+        try {
+          const signal = JSON.parse(data.toString()) as SatoriSignal;
+          if (signal.op === SatoriOpcode.READY && signal.body?.logins) {
+            const logins = signal.body.logins as SatoriLogin[];
+            this.login = logins[0];
+            if (!this.login?.platform || !this.login?.user?.id) {
+              this.logger.warn('Satori READY 未包含 platform/user，API 调用可能失败');
+            }
+          } else if (signal.op === SatoriOpcode.EVENT && signal.body) {
+            if (signal.body.sn != null) this.lastSn = signal.body.sn as number;
+            this.handleEvent(signal.body as SatoriEventBody);
+          }
+        } catch (error) {
+          this.emit('error', error);
+        }
+      });
+
+      this.ws.on('close', (code, reason) => {
+        this.$connected = false;
+        reject(new Error(`Satori WS closed: ${code} ${reason.toString()}`));
+        this.scheduleReconnect();
+      });
+
+      this.ws.on('error', (error) => {
+        reject(error);
+      });
+    });
+  }
+
+  async $disconnect(): Promise<void> {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = undefined;
+    }
+    this.$connected = false;
+  }
+
+  private handleEvent(body: SatoriEventBody): void {
+    if (isMessageEvent(body)) {
+      const message = this.$formatMessage(body);
+      this.adapter.emit('message.receive', message);
+      this.logger.debug(
+        `${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`,
+      );
+    }
+  }
+
+  $formatMessage(body: SatoriEventBody): Message<SatoriEventBody> {
+    if (!isMessageEvent(body)) {
+      return Message.from(body, {
+        $id: '',
+        $adapter: 'satori',
+        $bot: this.$config.name,
+        $channel: { id: '', type: 'private' },
+        $sender: { id: '', name: '' },
+        $content: [],
+        $raw: '',
+        $timestamp: body.timestamp ?? 0,
+        $recall: async () => {},
+        $reply: async () => '',
+      });
+    }
+    const payload = formatSatoriMessagePayload(
+      body,
+      'satori',
+      this.$config.name,
+      (id) => this.$recallMessage(id),
+      (channel, content, _quote) =>
+        this.adapter.sendMessage({
+          ...channel,
+          context: 'satori',
+          bot: this.$config.name,
+          content: content as import('zhin.js').SendContent,
+        }),
+    );
+    return Message.from(body, payload);
+  }
+
+  async $sendMessage(options: SendOptions): Promise<string> {
+    const channelId = options.id;
+    const contentRaw = segment.raw(options.content);
+    const result = await callSatoriApi(this.apiOptions(), 'message', 'create', {
+      channel_id: channelId,
+      content: contentRaw,
+    });
+    const list = Array.isArray(result) ? result : (result as { data?: unknown[] })?.data;
+    const msg = list?.[0] as { id?: string } | undefined;
+    const msgId = msg?.id ?? '';
+    this.logger.debug(`${this.$config.name} send ${options.type}(${channelId}):${contentRaw}`);
+    return msgId ? `${channelId}:${msgId}` : '';
+  }
+
+  async $recallMessage(id: string): Promise<void> {
+    const [channelId, messageId] = id.includes(':') ? id.split(':') : ['', id];
+    await callSatoriApi(this.apiOptions(), 'message', 'delete', { channel_id: channelId, message_id: messageId });
+  }
+}