@zhin.js/adapter-onebot11 1.0.98 → 1.1.0

package/lib/client.js

@@ -0,0 +1,30 @@
+import { OneBotV11Client, } from '@imhelper/onebot-v11';
+import { EventFactory } from 'imhelper';
+import { defineEndpointClient, forwardEndpointClientEvents, } from 'zhin.js/adapter';
+export { OneBotV11Client as Onebot11Client } from '@imhelper/onebot-v11';
+export function createOnebot11EndpointClient(config, request) {
+    return new OneBotV11Client({
+        baseUrl: config.connection === 'ws'
+            ? config.url.replace(/^ws(s?):/, 'http$1:')
+            : 'http://localhost',
+        selfId: config.id,
+        accessToken: config.access_token,
+        receiveMode: 'manual',
+        call: request,
+    });
+}
+export async function callOnebot11Client(client, action, params) {
+    const response = await client.call(action, params);
+    if (response.status !== 'ok') {
+        throw new Error(`OneBot 11 API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`);
+    }
+    return response.data;
+}
+const onebot11ClientEventNames = Object.freeze([
+    ...EventFactory.getSupportedEventTypes(),
+    'event',
+]);
+export function forwardOnebot11ClientEvents(client, receive) {
+    return forwardEndpointClientEvents(client, onebot11ClientEventNames, receive);
+}
+export const onebot11Client = defineEndpointClient('onebot11');

package/lib/content-port.d.ts

@@ -0,0 +1,4 @@
+import type { EndpointContentPort } from 'zhin.js/adapter';
+type CallApi = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+export declare function createOneBot11ContentPort(callApi: CallApi): EndpointContentPort;
+export {};

package/lib/content-port.js

@@ -0,0 +1,63 @@
+import { toCanonicalSegments } from '@zhin.js/core';
+export function createOneBot11ContentPort(callApi) {
+    return Object.freeze({
+        async resolve(reference, context) {
+            try {
+                context.signal.throwIfAborted();
+                if (reference.kind === 'media') {
+                    return reference.media.kind === 'file'
+                        ? Object.freeze({ status: 'unsupported', code: 'onebot11_opaque_media' })
+                        : Object.freeze({ status: 'resolved', reference, value: reference.media });
+                }
+                if (reference.kind === 'message') {
+                    const row = await callApi('get_msg', { message_id: reference.message.id });
+                    context.signal.throwIfAborted();
+                    const segments = normalizeSegments(row.message ?? row.raw_message);
+                    const sender = row.sender;
+                    const value = Object.freeze({
+                        ref: reference.message,
+                        ...(sender?.user_id != null ? { actor: Object.freeze({
+                                id: String(sender.user_id),
+                                ...(sender.nickname ? { displayName: String(sender.nickname) } : {}),
+                            }) } : {}),
+                        segments,
+                        timestamp: toMillis(row.time),
+                    });
+                    return Object.freeze({ status: 'resolved', reference, value });
+                }
+                const raw = await callApi('get_forward_msg', { id: reference.forwardId });
+                context.signal.throwIfAborted();
+                const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
+                const value = Object.freeze(nodes.map((node) => {
+                    const row = node;
+                    const sender = row.sender;
+                    return Object.freeze({
+                        ...(sender?.user_id != null ? { actor: Object.freeze({
+                                id: String(sender.user_id),
+                                ...(sender.nickname ? { displayName: String(sender.nickname) } : {}),
+                            }) } : {}),
+                        timestamp: toMillis(row.time),
+                        segments: normalizeSegments(row.content ?? row.message),
+                    });
+                }));
+                return Object.freeze({ status: 'resolved', reference, value, truncated: nodes.length >= context.maxEntries });
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+                return Object.freeze({ status: 'failed', code: 'onebot11_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+}
+function normalizeSegments(value) {
+    if (Array.isArray(value))
+        return Object.freeze(toCanonicalSegments(value));
+    return Object.freeze([{ type: 'text', data: Object.freeze({ text: String(value ?? '') }) }]);
+}
+function toMillis(value) {
+    const time = Number(value);
+    if (!Number.isFinite(time))
+        return Date.now();
+    return time < 10_000_000_000 ? time * 1000 : time;
+}

package/lib/endpoint-management.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OneBot11 endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * 归一化取舍：
+ * - friend → {user_id:number, nickname, remark: remark ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 OneBot11 原生形状，仅保证数组
+ */
+import type { EndpointManagement } from 'zhin.js/adapter';
+/** 管理面只依赖 endpoint 的 callApi（ws/wss 两种传输各自实现）。 */
+export interface OneBot11ManagementCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createOneBot11EndpointManagement(endpoint: OneBot11ManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -0,0 +1,47 @@
+export function createOneBot11EndpointManagement(endpoint) {
+    return Object.freeze({
+        async listFriends() {
+            const data = await endpoint.callApi('get_friend_list');
+            return toArray(data).map((value) => {
+                const friend = asRecord(value);
+                return {
+                    user_id: toNumberId(friend.user_id, 'user_id'),
+                    nickname: String(friend.nickname ?? ''),
+                    remark: String(friend.remark ?? ''),
+                };
+            });
+        },
+        async listGroups() {
+            const data = await endpoint.callApi('get_group_list');
+            return toArray(data).map((value) => {
+                const group = asRecord(value);
+                return {
+                    group_id: toNumberId(group.group_id, 'group_id'),
+                    name: String(group.group_name ?? group.name ?? ''),
+                };
+            });
+        },
+        async listGroupMembers(groupId) {
+            const data = await endpoint.callApi('get_group_member_list', {
+                group_id: toNumberId(groupId, 'group_id'),
+            });
+            return toArray(data);
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value, label) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+        throw new TypeError(`onebot11 ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}

package/lib/index.d.ts

@@ -1,16 +1,10 @@
-import { OneBot11Adapter } from './adapter.js';
-export * from './types.js';
-export { OneBot11WsClient } from './bot-ws-client.js';
-export { OneBot11WsServer } from './bot-ws-server.js';
-export { OneBot11Adapter, type OneBot11Bot } from './adapter.js';
-declare module 'zhin.js' {
-    namespace Plugin {
-        interface Contexts {
-            router: import('@zhin.js/host-router').Router;
-        }
-    }
-    interface Adapters {
-        onebot11: OneBot11Adapter;
-    }
-}
-//# sourceMappingURL=index.d.ts.map
+export { buildSendAction, buildWsConnectOptions, extractQuoteId, formatInboundContent, formatInboundMetadata, formatOutboundSegments, getChannelId, isMessageEvent, isOneBot11BotMentioned, mediaRefToOneBotFile, onebot11InboundConversation, resolveOneBot11Config, senderDisplayName, senderNickname, senderUserId, type OneBot11ActionRequest, type OneBot11ActionResponse, type OneBot11AdapterConfig, type OneBot11ConfigBase, type OneBot11EndpointConfig, type OneBot11Event, type OneBot11Segment, type OneBot11Sender, type OneBot11WireSegment, type OneBot11WsConfig, type OneBot11WssConfig, type ResolvedOneBot11Config, } from './protocol.js';
+export { OneBot11WsEndpoint, type OneBot11WsEndpointOptions, } from './ws-endpoint.js';
+export { OneBot11WssEndpoint, type OneBot11WssEndpointOptions, } from './wss-endpoint.js';
+export type { OneBot11WsSocket, OneBot11WsCreateOptions } from './ws-types.js';
+export { callOneBot11WsAction, decodeWsPayload, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';
+export { verifyOneBotAccessToken } from './wss-auth.js';
+export { Onebot11Client, onebot11Client, type Onebot11ClientEventMap, } from './client.js';
+export type { OneBotV11ActionUrlResolver, OneBotV11AdapterConfig as ImHelperOneBotV11AdapterConfig, OneBotV11Call, OneBotV11ClientConfig, OneBotV11Event as ImHelperOneBotV11Event, OneBotV11Response, } from '@imhelper/onebot-v11';
+export { ProtocolError } from '@imhelper/onebot-v11';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/lib/index.js

@@ -1,53 +1,7 @@
-/**
- * OneBot11 适配器入口：单一适配器，支持正向 WS / 反向 WS（connection: ws | wss）
- */
-import { usePlugin, createGroupManagementTools } from 'zhin.js';
-import { OneBot11Adapter } from './adapter.js';
-export * from './types.js';
-export { OneBot11WsClient } from './bot-ws-client.js';
-export { OneBot11WsServer } from './bot-ws-server.js';
-export { OneBot11Adapter } from './adapter.js';
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-provide({
-    name: 'onebot11',
-    description: 'OneBot11 协议适配器（正向 WS / 反向 WS）',
-    mounted: async (p) => {
-        const adapter = new OneBot11Adapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        await adapter.stop();
-    },
-});
-useContext('tool', 'onebot11', (toolService, onebot11) => {
-    const groupTools = createGroupManagementTools(onebot11, 'onebot11');
-    const disposers = groupTools.map(t => toolService.addTool(t, plugin.name));
-    // Platform-specific tool: set title
-    disposers.push(toolService.addTool({
-        name: 'onebot11_set_title',
-        description: '设置 QQ 群成员的专属头衔。只有群主才能设置。',
-        parameters: {
-            type: 'object',
-            properties: {
-                bot: { type: 'string', description: 'Bot 名称' },
-                group_id: { type: 'number', description: '目标群号' },
-                user_id: { type: 'number', description: '目标成员 QQ号' },
-                title: { type: 'string', description: '头衔文字' },
-            },
-            required: ['bot', 'group_id', 'user_id', 'title'],
-        },
-        platforms: ['onebot11'],
-        tags: ['onebot11'],
-        execute: async (args) => {
-            const bot = onebot11.bots.get(args.bot);
-            if (!bot)
-                throw new Error(`Bot ${args.bot} 不存在`);
-            const success = await bot.setTitle(args.group_id, args.user_id, args.title);
-            return { success, message: success ? `已将 ${args.user_id} 的头衔设为 "${args.title}"` : '设置失败' };
-        },
-    }, plugin.name));
-    return () => disposers.forEach(d => d());
-});
-//# sourceMappingURL=index.js.map
+export { buildSendAction, buildWsConnectOptions, extractQuoteId, formatInboundContent, formatInboundMetadata, formatOutboundSegments, getChannelId, isMessageEvent, isOneBot11BotMentioned, mediaRefToOneBotFile, onebot11InboundConversation, resolveOneBot11Config, senderDisplayName, senderNickname, senderUserId, } from './protocol.js';
+export { OneBot11WsEndpoint, } from './ws-endpoint.js';
+export { OneBot11WssEndpoint, } from './wss-endpoint.js';
+export { callOneBot11WsAction, decodeWsPayload, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';
+export { verifyOneBotAccessToken } from './wss-auth.js';
+export { Onebot11Client, onebot11Client, } from './client.js';
+export { ProtocolError } from '@imhelper/onebot-v11';

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

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

package/lib/onebot11-endpoint-commands.js

@@ -0,0 +1,24 @@
+/**
+ * `onebot11.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { onebot11RuntimeStateToken } from './onebot11-runtime-state.js';
+export const onebot11EndpointCommands = createEndpointCommands({
+    adapterKey: 'onebot11',
+    adapterDisplayName: 'OneBot 11',
+    fields: [
+        { key: 'url', description: 'OneBot 实现 WebSocket URL（connection: ws 必填）' },
+        { key: 'path', description: 'reverse-wss 路径（connection: wss）' },
+        { key: 'access_token', env: true, description: 'OneBot access token' },
+    ],
+    running: (use) => use(onebot11RuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => {
+        if (entry.url)
+            return `url: ${String(entry.url)}`;
+        if (entry.path)
+            return `path: ${String(entry.path)}`;
+        return '';
+    },
+}, defineCommand);

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

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

package/lib/onebot11-runtime-state.js

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

package/lib/protocol.d.ts

@@ -0,0 +1,160 @@
+/**
+ * OneBot 11 protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ * Spec: https://github.com/botuniverse/onebot-11
+ */
+import { type MediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
+/** Transitional legacy endpoint row (`endpoints[]` with `context: onebot11`). */
+export interface OneBot11LegacyEndpointRow {
+    readonly context?: string;
+    readonly connection?: 'ws' | 'wss';
+    /** Legacy alias: `type: 'ws' | 'ws_reverse'` */
+    readonly type?: string;
+    readonly id?: string;
+    readonly access_token?: string;
+    readonly url?: string;
+    readonly path?: string;
+    readonly reconnect_interval?: number;
+    readonly heartbeat_interval?: number;
+}
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface OneBot11AdapterConfig {
+    readonly connection?: 'ws' | 'wss';
+    readonly id?: string;
+    readonly access_token?: string;
+    readonly url?: string;
+    readonly path?: string;
+    readonly reconnect_interval?: number;
+    readonly heartbeat_interval?: number;
+    /** Transitional: legacy root `endpoints[]` with `context: onebot11`. */
+    readonly endpoints?: ReadonlyArray<OneBot11LegacyEndpointRow>;
+}
+export interface OneBot11ConfigBase {
+    readonly context: 'onebot11';
+    readonly id: string;
+    readonly access_token?: string;
+}
+/** 正向 WebSocket：应用连 OneBot 实现的 WS 服务器 */
+export interface OneBot11WsConfig extends OneBot11ConfigBase {
+    readonly connection: 'ws';
+    readonly url: string;
+    readonly reconnect_interval: number;
+    readonly heartbeat_interval: number;
+}
+/** 反向 WebSocket（slice 1 deferred — needs httpHostToken） */
+export interface OneBot11WssConfig extends OneBot11ConfigBase {
+    readonly connection: 'wss';
+    readonly path: string;
+    readonly heartbeat_interval: number;
+}
+export type ResolvedOneBot11Config = OneBot11WsConfig | OneBot11WssConfig;
+export type OneBot11EndpointConfig = ResolvedOneBot11Config;
+export interface OneBot11Sender {
+    readonly role?: string;
+    readonly nickname?: string;
+    readonly card?: string;
+    readonly title?: string;
+}
+export interface OneBot11Segment {
+    type: string;
+    data?: Record<string, unknown>;
+}
+export interface OneBot11Event {
+    post_type: string;
+    self_id?: number | string;
+    message_type?: string;
+    sub_type?: string;
+    message_id?: number | string;
+    user_id?: number | string;
+    group_id?: number | string;
+    sender?: OneBot11Sender;
+    message?: OneBot11Segment[];
+    raw_message?: string;
+    time?: number;
+    notice_type?: string;
+    request_type?: string;
+    [key: string]: unknown;
+}
+export interface OneBot11ActionRequest {
+    action: string;
+    params: Record<string, unknown>;
+    echo?: string;
+}
+export interface OneBot11ActionResponse {
+    status: 'ok' | 'failed';
+    retcode: number;
+    data?: unknown;
+    message?: string;
+    echo?: string;
+}
+export interface OneBot11WireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export declare function resolveOneBot11Config(config?: OneBot11AdapterConfig): ResolvedOneBot11Config;
+/** 判断是否为消息事件（post_type=message） */
+export declare function isMessageEvent(ev: OneBot11Event): ev is OneBot11Event & {
+    message_id: number | string;
+};
+/** 从事件得到场景 id：私聊 user_id，群 group_id */
+export declare function getChannelId(ev: OneBot11Event): string;
+/**
+ * 入站归一化 → ConversationRef：OneBot 11 `group` 消息 → kind 'group'，
+ * 其余（private 及带 group_id 的非 private 事件按群处理）→ kind 'private'。
+ * OneBot 11 无 guild/temp 容器概念，不填 parent。
+ */
+export declare function onebot11InboundConversation(endpointKey: string, ev: OneBot11Event): ConversationRef;
+/** Build inbound text for OutboundMessageService.receive */
+export declare function formatInboundContent(ev: OneBot11Event): string;
+export declare function senderDisplayName(ev: OneBot11Event): string;
+/**
+ * Runtime Message.sender 必须是用户 ID（agent bridge 用它与 endpointMaster 比对）。
+ * user_id 缺失时兜底为空串，绝不回退到显示名。
+ */
+export declare function senderUserId(ev: OneBot11Event): string;
+/** 显示名（群名片优先）放 metadata.nickname；没有则返回 undefined，不写该字段。 */
+export declare function senderNickname(ev: OneBot11Event): string | undefined;
+/**
+ * 回复引用 id：优先取 message 数组中的 {type:'reply', data:{id}} 段；
+ * 兼容部分实现把 reply 放在事件顶层（标量或带 message_id 的对象）。
+ */
+export declare function extractQuoteId(ev: OneBot11Event): string | undefined;
+/** 扫描 message 段中的 at，qq 等于本机 uin（self_id）即视为被 @；`qq:'all'`（@全体）不算。 */
+export declare function isOneBot11BotMentioned(input: {
+    readonly selfId: string | undefined;
+    readonly message?: readonly OneBot11Segment[];
+}): boolean;
+/** Inbound fields extracted from an event for gateway.receive (ws / wss 两个 endpoint 共用). */
+export interface OneBot11InboundFields {
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly endpointId: string;
+    readonly mentioned: boolean;
+    readonly replyTo: {
+        readonly id: string;
+    } | undefined;
+}
+/** 构造 gateway.receive 的 metadata 与提升字段（ws / wss 两个 endpoint 共用）。 */
+export declare function formatInboundMetadata(ev: OneBot11Event, endpoint: string): OneBot11InboundFields;
+/**
+ * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
+ * 本地路径 → `file://`（路径在 OneBot 实现侧解析）、kind=file 不透明引用原样透传。
+ */
+export declare function mediaRefToOneBotFile(media: MediaRef): string;
+/**
+ * Wire-encode an already-rendered outbound payload into OneBot 11 message segments.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 媒体段只消费 canonical `data.media`（无 MediaRef 的媒体段 warn + 丢弃），
+ * 其余 wire 形状段（at / 平台扩展段）原样透传。
+ */
+export declare function formatOutboundSegments(payload: unknown): OneBot11Segment[];
+export declare function buildSendAction(conversation: ConversationRef, message: OneBot11Segment[]): {
+    action: string;
+    params: Record<string, unknown>;
+};
+/** Build WS connect URL + headers (access_token via Bearer + query). */
+export declare function buildWsConnectOptions(config: OneBot11WsConfig): {
+    readonly url: string;
+    readonly headers: Record<string, string>;
+    readonly safeUrl: string;
+};