@zhin.js/adapter-satori 1.0.0 → 1.1.0

package/lib/protocol.js

@@ -0,0 +1,242 @@
+/**
+ * Satori protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ * Spec: https://satori.chat/zh-CN/protocol/overview.html
+ */
+import { pickCredential } from 'zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('satori');
+/** 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,
+};
+export function resolveSatoriConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'satori');
+    const connection = config.connection ?? entry?.connection ?? 'ws';
+    const baseUrl = pickCredential(config.baseUrl, entry?.baseUrl, process.env.SATORI_BASE_URL);
+    if (!baseUrl) {
+        throw new TypeError('Satori adapter requires baseUrl (plugins.<key>.baseUrl or endpoints with context: satori)');
+    }
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
+        || process.env.SATORI_BOT_NAME
+        || 'satori-bot';
+    const token = (typeof config.token === 'string' && config.token)
+        || (typeof entry?.token === 'string' && entry.token)
+        || process.env.SATORI_TOKEN
+        || undefined;
+    if (connection === 'webhook') {
+        const path = config.path ?? entry?.path;
+        if (!path) {
+            throw new TypeError('Satori connection:webhook requires path');
+        }
+        return {
+            context: 'satori',
+            connection: 'webhook',
+            id,
+            baseUrl,
+            token,
+            path,
+        };
+    }
+    const heartbeat = config.heartbeat_interval
+        ?? entry?.heartbeat_interval
+        ?? 10_000;
+    return {
+        context: 'satori',
+        connection: 'ws',
+        id,
+        baseUrl,
+        token,
+        heartbeat_interval: heartbeat,
+    };
+}
+/** Channel.type 1 = DIRECT (private). */
+export function isPrivateChannel(channel) {
+    return channel?.type === 1;
+}
+export function isMessageEvent(body) {
+    return (body.type === 'message-created' || body.type === 'message-updated')
+        && !!body.message?.id;
+}
+export function buildWsUrl(baseUrl, token) {
+    const url = new URL(baseUrl.replace(/\/$/, ''));
+    if (token)
+        url.searchParams.set('access_token', token);
+    return url.toString();
+}
+/**
+ * Call Satori HTTP API: POST {baseUrl}/v1/{resource}.{method}
+ * @see https://satori.chat/en-US/protocol/api.html
+ */
+export async function callSatoriApi(options, resource, method, params = {}) {
+    const { baseUrl, platform, userId, token } = options;
+    const url = `${baseUrl.replace(/\/$/, '')}/v1/${resource}.${method}`;
+    const headers = {
+        '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;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Satori API 无效 JSON: ${text.slice(0, 200)}`);
+    }
+}
+/** Build inbound text for OutboundMessageService.receive. */
+export function formatInboundContent(body) {
+    const content = body.message.content ?? '';
+    return typeof content === 'string' ? content : String(content);
+}
+/**
+ * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
+ * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
+ */
+export function satoriInboundConversation(endpointKey, body) {
+    const channel = body.channel ?? body.message.channel;
+    const kind = isPrivateChannel(channel) ? 'private' : 'group';
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind,
+        id: channel?.id ?? '',
+        ...(kind === 'group' && body.guild?.id
+            ? { parent: { kind: 'channel', id: body.guild.id } }
+            : {}),
+    };
+}
+export function resolveInboundSender(body) {
+    const user = body.user ?? body.message.user ?? body.message.member?.user;
+    const name = user?.name ?? body.message.member?.nick;
+    const id = user?.id ?? name ?? '';
+    return name && name !== id ? { id, name } : { id };
+}
+/**
+ * Detect `<at id="…"/>` elements in message content targeting the bot selfId.
+ * selfId 来源：READY/事件携带的 `login.user.id`。
+ */
+export function isSelfMentioned(body, selfId) {
+    if (!selfId)
+        return false;
+    const content = body.message.content;
+    if (typeof content !== 'string' || !content.includes('<at'))
+        return false;
+    const tags = content.match(/<at\b[^>]*>/gi) ?? [];
+    return tags.some((tag) => /\bid\s*=\s*["']([^"']+)["']/i.exec(tag)?.[1] === selfId);
+}
+export function formatMessageId(channelId, messageId) {
+    return `${channelId}:${messageId}`;
+}
+export function parseMessageRef(id) {
+    if (id.includes(':')) {
+        const [channelId, messageId] = id.split(':');
+        return { channelId: channelId ?? '', messageId: messageId ?? '' };
+    }
+    return { channelId: '', messageId: id };
+}
+/**
+ * 解析媒体段（image/audio/video/file）的投递源，canonical MediaRef 为唯一来源：
+ * - kind=url → 直发 URL；
+ * - kind=base64 → 规范为 `base64://` 前缀内联（Satori img/file 元素消费内联数据）。
+ * 无 canonical 媒体引用或来源不可投递（path / file 本端点不物化）时 warn + 丢弃。
+ */
+function resolveMediaSrc(type, data) {
+    const media = data.media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: 'satori_outbound_media_dropped',
+            type,
+            reason: 'missing_media_ref',
+        }));
+        return undefined;
+    }
+    if (media.kind === 'url')
+        return media.value;
+    if (media.kind === 'base64') {
+        return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+    }
+    logger.warn(formatCompact({
+        op: 'satori_outbound_media_dropped',
+        type,
+        reason: `unsupported_media_kind:${media.kind}`,
+    }));
+    return undefined;
+}
+/**
+ * Wire-encode an already-rendered outbound payload into Satori message content.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatSatoriOutbound(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    if (payload == null)
+        return '';
+    const segments = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (segments.length === 0) {
+        return typeof payload === 'object' ? JSON.stringify(payload) : String(payload);
+    }
+    const parts = [];
+    for (const item of segments) {
+        if (typeof item === 'string') {
+            parts.push(item);
+            continue;
+        }
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                parts.push(String(data.text ?? data.content ?? ''));
+                break;
+            case 'at':
+            case 'mention':
+                parts.push(`@${String(data.name ?? data.id ?? data.target ?? '')}`);
+                break;
+            case 'image':
+            case 'audio':
+            case 'video':
+            case 'file': {
+                const src = resolveMediaSrc(item.type, data);
+                if (src)
+                    parts.push(`[${item.type}:${src}]`);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return parts.join('');
+}
+export function extractCreatedMessageId(result) {
+    const list = Array.isArray(result)
+        ? result
+        : result?.data;
+    const msg = list?.[0];
+    return msg?.id ?? '';
+}

package/lib/satori-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const satoriEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/satori-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `satori.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { satoriRuntimeStateToken } from './satori-runtime-state.js';
+export const satoriEndpointCommands = createEndpointCommands({
+    adapterKey: 'satori',
+    adapterDisplayName: 'Satori',
+    fields: [
+        { key: 'baseUrl', required: true, description: 'Satori 服务 base URL' },
+        { key: 'path', description: 'webhook 路径（connection: webhook）' },
+        { key: 'token', env: true, description: 'Satori access token' },
+    ],
+    running: (use) => use(satoriRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
+}, defineCommand);

package/lib/satori-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const satoriRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/satori-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * Satori 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `satori.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const satoriRuntimeStateToken = defineEndpointRuntimeStateToken('satori');

package/lib/webhook.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type ResolvedSatoriWebhookConfig } from './protocol.js';
+export interface SatoriWebhookHandler {
+    readonly config: ResolvedSatoriWebhookConfig;
+    readonly isOpen: boolean;
+    acceptHttp(request: IncomingMessage, response: ServerResponse): Promise<void>;
+}
+export declare function registerSatoriWebhookRoutes(http: HttpHost, handler: SatoriWebhookHandler): HttpRouteRegistration[];
+export declare function handleSatoriWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: SatoriWebhookHandler): Promise<void>;
+export declare function resolveSatoriOpcode(request: IncomingMessage): number | undefined;
+export declare function verifySatoriToken(token: string | undefined, request: IncomingMessage): boolean;

package/lib/webhook.js

@@ -0,0 +1,60 @@
+/**
+ * Satori webhook HTTP: token → opcode → parse → admit.
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { getLogger } from '@zhin.js/logger';
+import { SatoriOpcode, } from './protocol.js';
+const logger = getLogger('satori');
+export function registerSatoriWebhookRoutes(http, handler) {
+    const path = handler.config.path;
+    return [
+        http.route('POST', path, async (request, response) => {
+            await handleSatoriWebhookRequest(request, response, handler);
+        }, { summary: 'Satori webhook callback', tags: ['satori'] }),
+    ];
+}
+export async function handleSatoriWebhookRequest(request, response, handler) {
+    try {
+        if (!verifySatoriToken(handler.config.token, request)) {
+            response.writeHead(403, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ message: 'Unauthorized' }));
+            return;
+        }
+        const opcode = resolveSatoriOpcode(request);
+        if (opcode !== SatoriOpcode.EVENT && opcode !== SatoriOpcode.META) {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ message: 'OK' }));
+            return;
+        }
+        if (handler.isOpen) {
+            await handler.acceptHttp(request, response);
+        }
+        else {
+            response.writeHead(200, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ status: 'ok' }));
+        }
+    }
+    catch (error) {
+        logger.error('Satori webhook error:', error);
+        if (!response.headersSent) {
+            response.writeHead(500, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ message: 'Internal Server Error' }));
+        }
+    }
+}
+export function resolveSatoriOpcode(request) {
+    const raw = request.headers['satori-opcode'] ?? request.headers['Satori-Opcode'];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (value == null || value === '')
+        return undefined;
+    const parsed = Number.parseInt(String(value), 10);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+export function verifySatoriToken(token, request) {
+    if (!token)
+        return true;
+    const auth = request.headers.authorization ?? '';
+    const expected = Buffer.from(`Bearer ${token}`, 'utf8');
+    const actual = Buffer.from(auth, 'utf8');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}

package/lib/ws.d.ts

@@ -0,0 +1,13 @@
+export declare const WS_OPEN = 1;
+export interface SatoriWsSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+}
+export type CreateSatoriWebSocket = (url: string, options?: {
+    readonly headers?: Record<string, string>;
+}) => SatoriWsSocket;
+export declare function defaultCreateWebSocket(url: string, options?: {
+    readonly headers?: Record<string, string>;
+}): SatoriWsSocket;

package/lib/ws.js

@@ -0,0 +1,5 @@
+import WebSocket from 'ws';
+export const WS_OPEN = 1;
+export function defaultCreateWebSocket(url, options) {
+    return new WebSocket(url, { headers: options?.headers });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-satori",
-  "version": "1.0.0",
-  "description": "Zhin.js adapter for Satori protocol",
+  "version": "1.1.0",
+  "description": "Zhin.js Satori adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,12 +13,15 @@
     }
   },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "README.md"
+    "agent",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "zhin",
@@ -31,31 +34,75 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/zhinjs/zhin",
+    "url": "https://github.com/zhinjs/zhin.git",
     "directory": "plugins/adapters/satori"
   },
   "dependencies": {
-    "ws": "^8.21.0"
+    "@imhelper/satori-v1": "1.0.7",
+    "imhelper": "1.0.7",
+    "ws": "^8.21.1",
+    "@zhin.js/adapter": "1.1.12",
+    "@zhin.js/core": "1.1.35",
+    "@zhin.js/feature-kit": "1.1.0",
+    "@zhin.js/host-http": "1.1.0",
+    "@zhin.js/im-contract": "1.1.0",
+    "@zhin.js/logger": "1.1.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
-    "zhin.js": "2.0.0",
-    "@zhin.js/cli": "1.0.88",
-    "@zhin.js/client": "2.0.2"
+    "vitest": "^4.1.10",
+    "@zhin.js/host-http": "1.1.0",
+    "zhin.js": "1.1.0"
   },
   "peerDependencies": {
-    "zhin.js": "2.0.0",
-    "@zhin.js/host-router": "1.0.0"
+    "@zhin.js/adapter": "^1.1.12",
+    "@zhin.js/command": "^1.1.0",
+    "@zhin.js/core": "^1.1.35",
+    "zhin.js": "^1.1.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "zhin.js": {
       "optional": true
     }
   },
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/satori/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,14 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { satoriRuntimeStateToken } from "./lib/satori-runtime-state.js";
+export default definePlugin({
+    name: 'satori',
+    metadata: {
+        displayName: 'Satori Adapter',
+    },
+    setup(context) {
+        // 运行中 endpoint 注册表（satori.endpoint list 的"运行中"数据源）
+        context.resources.provide(satoriRuntimeStateToken, createEndpointRuntimeState());
+    },
+});

package/schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "connection": {
+      "type": "string",
+      "enum": [
+        "ws",
+        "webhook"
+      ],
+      "default": "ws",
+      "description": "ws (default) or webhook (httpHostToken POST route)"
+    },
+    "heartbeat_interval": {
+      "type": "number",
+      "default": 10000,
+      "description": "WS PING interval in milliseconds"
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（platform user id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted platform user id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（platform user id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted platform user id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "Satori SDK HTTP/WS base URL (e.g. http://127.0.0.1:5140)"
+          },
+          "token": {
+            "type": "string",
+            "description": "Bearer token for API and WS IDENTIFY"
+          },
+          "path": {
+            "type": "string",
+            "description": "Webhook POST path (connection: webhook)"
+          },
+          "id": {
+            "type": "string",
+            "description": "Satori bot name"
+          }
+        },
+        "required": [
+          "id",
+          "baseUrl"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,57 @@
+import {
+  SatoriV1Client,
+  type SatoriV1Event,
+} from '@imhelper/satori-v1';
+import { EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
+import {
+  defineEndpointClient,
+  forwardEndpointClientEvents,
+  type ClientEventPayloads,
+} from 'zhin.js/adapter';
+import type {
+  ResolvedSatoriConfig,
+  SatoriApiOptions,
+  callSatoriApi,
+} from './protocol.js';
+
+export { SatoriV1Client as SatoriClient } from '@imhelper/satori-v1';
+
+type SatoriClientEvents = ImHelperEventMap<string, SatoriV1Event, EventMap<string>>;
+export type SatoriClientEventMap = ClientEventPayloads<SatoriClientEvents>;
+
+export function createSatoriEndpointClient(
+  config: ResolvedSatoriConfig,
+  request: typeof callSatoriApi,
+  apiOptions: () => SatoriApiOptions,
+): SatoriV1Client {
+  return new SatoriV1Client({
+    baseUrl: config.baseUrl,
+    selfId: config.id,
+    accessToken: config.token,
+    receiveMode: 'manual',
+    call: (resource, method, params) => request(apiOptions(), resource, method, params ?? {}),
+  });
+}
+
+const satoriClientEventNames = Object.freeze([
+  ...EventFactory.getSupportedEventTypes<string>(),
+  'event',
+]);
+
+export function forwardSatoriClientEvents(
+  client: SatoriV1Client,
+  receive: (name: string, payload: unknown) => void,
+): () => void {
+  return forwardEndpointClientEvents(client, satoriClientEventNames, receive);
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly satori: {
+      readonly client: SatoriV1Client;
+      readonly events: SatoriClientEventMap;
+    };
+  }
+}
+
+export const satoriClient = defineEndpointClient<SatoriV1Client, SatoriClientEventMap>('satori');