@zhin.js/adapter-onebot12 5.0.12 → 5.0.13

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @zhin.js/adapter-onebot12
 
+## 5.0.13
+
+### Patch Changes
+
+- b2ef6b1: Add canonical scoped message resolution and explicit unsupported results for protocol capabilities OneBot 12 does not standardize.
+- 5969c5b: Add SideEventGateway so adapters forward notice/request/system into HandlerIndex. HandlerContext now exposes only generation-safe capabilities and prompt ports; live Endpoint escape hatches are removed.
+- Updated dependencies [5969c5b]
+- Updated dependencies [d336a3f]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [974772e]
+- Updated dependencies [5969c5b]
+- Updated dependencies [2f786bd]
+- Updated dependencies [1312ca0]
+- Updated dependencies [985fa22]
+  - @zhin.js/im-contract@1.0.4
+  - @zhin.js/core@1.5.12
+  - @zhin.js/adapter@1.1.11
+  - @zhin.js/host-http@1.0.11
+  - @zhin.js/command@1.0.15
+  - zhin.js@6.0.12
+
 ## 5.0.12
 
 ### Patch Changes

package/adapters/onebot12.js

@@ -3,7 +3,7 @@
  * Convention entry: discover `adapters/onebot12.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { OneBot12WebhookEndpoint } from "../lib/webhook.js";
 import { OneBot12WsEndpoint } from "../lib/ws-endpoint.js";
@@ -24,6 +24,7 @@ export default defineAdapter({
     create(context) {
         const config = resolveOneBot12Config(context.config);
         const gateway = context.use(messageGatewayToken);
+        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（onebot12.endpoint list 的"运行中"数据源）
         context.use(onebot12RuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -33,6 +34,7 @@ export default defineAdapter({
             return new OneBot12WebhookEndpoint({
                 id: context.id,
                 gateway,
+                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
@@ -41,6 +43,7 @@ export default defineAdapter({
             return new OneBot12WssEndpoint({
                 id: context.id,
                 gateway,
+                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
@@ -48,6 +51,7 @@ export default defineAdapter({
         return new OneBot12WsEndpoint({
             id: context.id,
             gateway,
+            sideEvents,
             config,
         });
     },

package/adapters/onebot12.ts

@@ -2,7 +2,7 @@
  * Convention entry: discover `adapters/onebot12.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { OneBot12WebhookEndpoint } from '../src/webhook.js';
 import { OneBot12WsEndpoint } from '../src/ws-endpoint.js';
@@ -21,6 +21,12 @@ export { OneBot12WssEndpoint } from '../src/wss-endpoint.js';
 export type { OneBot12WssEndpointOptions } from '../src/wss-endpoint.js';
 export type { OneBot12WsSocket, OneBot12WsCreateOptions } from '../src/ws-types.js';
 
+declare module '@zhin.js/core' {
+  interface AdapterEndpoints {
+    onebot12: import('../src/ws-endpoint.js').OneBot12WsEndpoint;
+  }
+}
+
 export default defineAdapter<OneBot12AdapterConfig>({
   capabilities: ['inbound', 'outbound'],
   // 媒体段经 upload_file 物化为 file_id（spec 正式投递）；上传失败降级扩展字段透传。
@@ -32,6 +38,7 @@ export default defineAdapter<OneBot12AdapterConfig>({
   create(context) {
     const config = resolveOneBot12Config(context.config);
     const gateway = context.use(messageGatewayToken);
+    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（onebot12.endpoint list 的"运行中"数据源）
     context.use(onebot12RuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -41,6 +48,7 @@ export default defineAdapter<OneBot12AdapterConfig>({
       return new OneBot12WebhookEndpoint({
         id: context.id,
         gateway,
+        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
@@ -49,6 +57,7 @@ export default defineAdapter<OneBot12AdapterConfig>({
       return new OneBot12WssEndpoint({
         id: context.id,
         gateway,
+        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
@@ -56,6 +65,7 @@ export default defineAdapter<OneBot12AdapterConfig>({
     return new OneBot12WsEndpoint({
       id: context.id,
       gateway,
+      sideEvents,
       config,
     });
   },

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 createOneBot12ContentPort(callApi: CallApi): EndpointContentPort;
+export {};

package/lib/content-port.js

@@ -0,0 +1,45 @@
+export function createOneBot12ContentPort(callApi) {
+    return Object.freeze({
+        async resolve(reference, context) {
+            try {
+                context.signal.throwIfAborted();
+                if (reference.kind === 'forward') {
+                    return Object.freeze({ status: 'unsupported', code: 'onebot12_forward_lookup_not_standardized' });
+                }
+                if (reference.kind === 'media') {
+                    return reference.media.kind === 'file'
+                        ? Object.freeze({ status: 'unsupported', code: 'onebot12_opaque_media' })
+                        : Object.freeze({ status: 'resolved', reference, value: reference.media });
+                }
+                const row = await callApi('get_message', { message_id: reference.message.id });
+                context.signal.throwIfAborted();
+                const message = (row.message && typeof row.message === 'object' ? row.message : row);
+                const segments = normalizeSegments(message.message ?? message.content);
+                const value = Object.freeze({
+                    ref: reference.message,
+                    ...(message.user_id != null ? { actor: Object.freeze({ id: String(message.user_id) }) } : {}),
+                    segments,
+                    timestamp: toMillis(message.time),
+                });
+                return Object.freeze({ status: 'resolved', reference, value });
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+                return Object.freeze({ status: 'failed', code: 'onebot12_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+            }
+        },
+    });
+}
+function normalizeSegments(value) {
+    if (!Array.isArray(value))
+        return Object.freeze([{ type: 'text', data: Object.freeze({ text: String(value ?? '') }) }]);
+    return Object.freeze(value.map((item) => {
+        const row = item;
+        return Object.freeze({ type: String(row.type ?? 'text'), data: Object.freeze((row.data ?? {})) });
+    }));
+}
+function toMillis(value) {
+    const time = Number(value);
+    return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
+}

package/lib/protocol.js

@@ -105,14 +105,14 @@ export function onebot12InboundConversation(endpointKey, ev) {
 }
 /** Build inbound text for MessageGateway.receive */
 export function formatInboundContent(ev) {
-    if (typeof ev.alt_message === 'string' && ev.alt_message)
-        return ev.alt_message;
     if (Array.isArray(ev.message)) {
         return ev.message
             .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
             .join('');
     }
-    return '';
+    return typeof ev.alt_message === 'string'
+        ? ev.alt_message.replace(/\[[^\]]*(?:image|audio|video|file)[^\]]*\]/gi, '').trim()
+        : '';
 }
 /**
  * Runtime Message sender 必须是用户 ID（agent bridge 以 sender 与 endpointMaster 比对）。

package/lib/side-event-dispatch.d.ts

@@ -0,0 +1,7 @@
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { type getAdapterLogger } from '@zhin.js/logger';
+import type { OneBot12Event } from './protocol.js';
+export interface OneBot12SideEventCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function receiveOneBot12SideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, caller: OneBot12SideEventCaller, raw: OneBot12Event, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -0,0 +1,36 @@
+import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+export function receiveOneBot12SideEvent(sideEvents, endpointKey, caller, raw, logger) {
+    if (!sideEvents)
+        return;
+    const record = raw;
+    const eventType = String(record.type ?? record.post_type ?? '');
+    const detailType = String(record.detail_type ?? '');
+    const isRequest = eventType === 'request' || eventType.startsWith('request.');
+    const isFriend = detailType.includes('friend') || String(record.request_type ?? '') === 'friend';
+    void receiveOneBotLikeSideEvent(sideEvents, {
+        adapter: 'onebot12',
+        endpointKey,
+        platform: 'onebot',
+        raw: record,
+        ...(isRequest ? {
+            approve: async (flag, remark) => {
+                await (isFriend
+                    ? caller.callApi('set_friend_add_request', { flag, approve: true, remark })
+                    : caller.callApi('set_group_add_request', { flag, approve: true, reason: remark }));
+            },
+            reject: async (flag, reason) => {
+                await (isFriend
+                    ? caller.callApi('set_friend_add_request', { flag, approve: false })
+                    : caller.callApi('set_group_add_request', { flag, approve: false, reason }));
+            },
+        } : {}),
+    }).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'onebot12_side_event_failed',
+            endpoint: endpointKey,
+            type: eventType || undefined,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+}

package/lib/webhook.d.ts

@@ -1,11 +1,12 @@
 import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { callOneBot12Action, type OneBot12Event, type OneBot12WebhookConfig } from './protocol.js';
 export interface OneBot12WebhookEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: OneBot12WebhookConfig;
     readonly callAction?: typeof callOneBot12Action;
@@ -13,6 +14,7 @@ export interface OneBot12WebhookEndpointOptions {
 export declare class OneBot12WebhookEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot12WebhookEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/webhook.js

@@ -1,11 +1,14 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import { buildSendMessageParams, callOneBot12Action, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
+import { createOneBot12ContentPort } from './content-port.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 const logger = getLogger('onebot12');
 export class OneBot12WebhookEndpoint {
     #options;
     management = createOneBot12EndpointManagement(this);
+    content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
     #callAction;
     #routeReleases = [];
     #open = false;
@@ -79,8 +82,12 @@ export class OneBot12WebhookEndpoint {
         return resp.data;
     }
     admit(ev) {
-        if (!this.#open || !isMessageEvent(ev))
+        if (!this.#open)
             return;
+        if (!isMessageEvent(ev)) {
+            receiveOneBot12SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, logger);
+            return;
+        }
         const conversation = onebot12InboundConversation(String(this.#options.id), ev);
         const content = formatInboundContent(ev);
         const nickname = senderNickname(ev);

package/lib/ws-endpoint.d.ts

@@ -1,17 +1,19 @@
 import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from 'zhin.js';
 import { type OneBot12Event, type OneBot12WsConfig } from './protocol.js';
 import { type OneBot12WsCreateOptions, type OneBot12WsSocket } from './ws-types.js';
 export interface OneBot12WsEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly config: OneBot12WsConfig;
     readonly createWebSocket?: (url: string, options: OneBot12WsCreateOptions) => OneBot12WsSocket;
 }
 export declare class OneBot12WsEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot12WsEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/ws-endpoint.js

@@ -7,11 +7,14 @@ import { createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import { buildSendMessageParams, buildWsConnectOptions, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
+import { createOneBot12ContentPort } from './content-port.js';
 import { WS_OPEN, } from './ws-types.js';
 export class OneBot12WsEndpoint {
     #logger;
     #options;
     management = createOneBot12EndpointManagement(this);
+    content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
     #lifecycle;
     #ws;
     #requestId = 0;
@@ -102,8 +105,12 @@ export class OneBot12WsEndpoint {
     }
     /** Test / internal: admit a parsed event when the endpoint is open. */
     admit(ev) {
-        if (!this.#open || !isMessageEvent(ev))
+        if (!this.#open)
             return;
+        if (!isMessageEvent(ev)) {
+            receiveOneBot12SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            return;
+        }
         const conversation = onebot12InboundConversation(String(this.#options.id), ev);
         const content = formatInboundContent(ev);
         const nickname = senderNickname(ev);

package/lib/wss-endpoint.d.ts

@@ -1,17 +1,19 @@
 import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type OneBot12Event, type OneBot12WssConfig } from './protocol.js';
 export interface OneBot12WssEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: OneBot12WssConfig;
 }
 export declare class OneBot12WssEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot12WssEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/wss-endpoint.js

@@ -5,12 +5,15 @@ import { clearInterval } from 'node:timers';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import { buildSendMessageParams, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
+import { createOneBot12ContentPort } from './content-port.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 import { WS_OPEN } from './ws-types.js';
 export class OneBot12WssEndpoint {
     #logger;
     #options;
     management = createOneBot12EndpointManagement(this);
+    content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
     #ws;
     #wsRelease;
     #heartbeatTimer;
@@ -99,8 +102,12 @@ export class OneBot12WssEndpoint {
         return this.#callAction(action, params);
     }
     admit(ev) {
-        if (!this.#open || !isMessageEvent(ev))
+        if (!this.#open)
             return;
+        if (!isMessageEvent(ev)) {
+            receiveOneBot12SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            return;
+        }
         const conversation = onebot12InboundConversation(String(this.#options.id), ev);
         const nickname = senderNickname(ev);
         const mentioned = isBotMentioned(ev);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot12",
-  "version": "5.0.12",
+  "version": "5.0.13",
   "description": "Zhin.js OneBot 12 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -40,10 +40,10 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/core": "1.5.12",
+    "@zhin.js/host-http": "1.0.11",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76"
   },
   "devDependencies": {
@@ -51,14 +51,14 @@
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.10",
-    "zhin.js": "6.0.11"
+    "@zhin.js/host-http": "1.0.11",
+    "zhin.js": "6.0.12"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/core": "1.5.11",
-    "zhin.js": "6.0.11"
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.12",
+    "zhin.js": "6.0.12"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {

package/src/content-port.ts

@@ -0,0 +1,49 @@
+import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import type { ConversationMessage, ConversationReference } from '@zhin.js/im-contract';
+
+type CallApi = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+
+export function createOneBot12ContentPort(callApi: CallApi): EndpointContentPort {
+  return Object.freeze({
+    async resolve(reference: ConversationReference, context: EndpointContentResolveContext) {
+      try {
+        context.signal.throwIfAborted();
+        if (reference.kind === 'forward') {
+          return Object.freeze({ status: 'unsupported' as const, code: 'onebot12_forward_lookup_not_standardized' });
+        }
+        if (reference.kind === 'media') {
+          return reference.media.kind === 'file'
+            ? Object.freeze({ status: 'unsupported' as const, code: 'onebot12_opaque_media' })
+            : Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
+        }
+        const row = await callApi('get_message', { message_id: reference.message.id }) as Record<string, unknown>;
+        context.signal.throwIfAborted();
+        const message = (row.message && typeof row.message === 'object' ? row.message : row) as Record<string, unknown>;
+        const segments = normalizeSegments(message.message ?? message.content);
+        const value: ConversationMessage = Object.freeze({
+          ref: reference.message,
+          ...(message.user_id != null ? { actor: Object.freeze({ id: String(message.user_id) }) } : {}),
+          segments,
+          timestamp: toMillis(message.time),
+        });
+        return Object.freeze({ status: 'resolved' as const, reference, value });
+      } catch (error) {
+        if (context.signal.aborted) return Object.freeze({ status: 'expired' as const, code: 'turn_aborted' });
+        return Object.freeze({ status: 'failed' as const, code: 'onebot12_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
+}
+
+function normalizeSegments(value: unknown) {
+  if (!Array.isArray(value)) return Object.freeze([{ type: 'text', data: Object.freeze({ text: String(value ?? '') }) }]);
+  return Object.freeze(value.map((item) => {
+    const row = item as Record<string, unknown>;
+    return Object.freeze({ type: String(row.type ?? 'text'), data: Object.freeze((row.data ?? {}) as Record<string, unknown>) });
+  }));
+}
+
+function toMillis(value: unknown): number {
+  const time = Number(value);
+  return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
+}

package/src/protocol.ts

@@ -228,13 +228,14 @@ export function onebot12InboundConversation(endpointKey: string, ev: OneBot12Eve
 
 /** Build inbound text for MessageGateway.receive */
 export function formatInboundContent(ev: OneBot12Event): string {
-  if (typeof ev.alt_message === 'string' && ev.alt_message) return ev.alt_message;
   if (Array.isArray(ev.message)) {
     return ev.message
       .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
       .join('');
   }
-  return '';
+  return typeof ev.alt_message === 'string'
+    ? ev.alt_message.replace(/\[[^\]]*(?:image|audio|video|file)[^\]]*\]/gi, '').trim()
+    : '';
 }
 
 /**

package/src/side-event-dispatch.ts

@@ -0,0 +1,48 @@
+import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
+import type { OneBot12Event } from './protocol.js';
+
+export interface OneBot12SideEventCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function receiveOneBot12SideEvent(
+  sideEvents: SideEventGateway | undefined,
+  endpointKey: string,
+  caller: OneBot12SideEventCaller,
+  raw: OneBot12Event,
+  logger: ReturnType<typeof getAdapterLogger>,
+): void {
+  if (!sideEvents) return;
+  const record = raw as Record<string, unknown>;
+  const eventType = String(record.type ?? record.post_type ?? '');
+  const detailType = String(record.detail_type ?? '');
+  const isRequest = eventType === 'request' || eventType.startsWith('request.');
+  const isFriend = detailType.includes('friend') || String(record.request_type ?? '') === 'friend';
+  void receiveOneBotLikeSideEvent(sideEvents, {
+    adapter: 'onebot12',
+    endpointKey,
+    platform: 'onebot',
+    raw: record,
+    ...(isRequest ? {
+      approve: async (flag, remark) => {
+        await (isFriend
+          ? caller.callApi('set_friend_add_request', { flag, approve: true, remark })
+          : caller.callApi('set_group_add_request', { flag, approve: true, reason: remark }));
+      },
+      reject: async (flag, reason) => {
+        await (isFriend
+          ? caller.callApi('set_friend_add_request', { flag, approve: false })
+          : caller.callApi('set_group_add_request', { flag, approve: false, reason }));
+      },
+    } : {}),
+  }).catch((err) => {
+    logger.warn(formatCompact({
+      op: 'onebot12_side_event_failed',
+      endpoint: endpointKey,
+      type: eventType || undefined,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+  });
+}

package/src/webhook.ts

@@ -3,7 +3,7 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -22,6 +22,8 @@ import {
   type OneBot12Event,
   type OneBot12WebhookConfig,
 } from './protocol.js';
+import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
+import { createOneBot12ContentPort } from './content-port.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 
 const logger = getLogger('onebot12');
@@ -29,6 +31,7 @@ const logger = getLogger('onebot12');
 export interface OneBot12WebhookEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: OneBot12WebhookConfig;
   readonly callAction?: typeof callOneBot12Action;
@@ -37,6 +40,7 @@ export interface OneBot12WebhookEndpointOptions {
 export class OneBot12WebhookEndpoint implements EndpointInstance {
   readonly #options: OneBot12WebhookEndpointOptions;
   readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
+  readonly content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
   readonly #callAction: typeof callOneBot12Action;
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
@@ -124,7 +128,17 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
   }
 
   admit(ev: OneBot12Event): void {
-    if (!this.#open || !isMessageEvent(ev)) return;
+    if (!this.#open) return;
+    if (!isMessageEvent(ev)) {
+      receiveOneBot12SideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        this,
+        ev,
+        logger,
+      );
+      return;
+    }
     const conversation = onebot12InboundConversation(String(this.#options.id), ev);
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);

package/src/ws-endpoint.ts

@@ -11,7 +11,7 @@ import {
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
@@ -31,6 +31,8 @@ import {
   type OneBot12Event,
   type OneBot12WsConfig,
 } from './protocol.js';
+import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
+import { createOneBot12ContentPort } from './content-port.js';
 import {
   type OneBot12WsCreateOptions,
   type OneBot12WsSocket,
@@ -40,6 +42,7 @@ import {
 export interface OneBot12WsEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly config: OneBot12WsConfig;
   readonly createWebSocket?: (
     url: string,
@@ -52,6 +55,7 @@ export class OneBot12WsEndpoint implements EndpointInstance {
 
   readonly #options: OneBot12WsEndpointOptions;
   readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
+  readonly content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
   readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot12WsSocket;
   #requestId = 0;
@@ -155,7 +159,17 @@ export class OneBot12WsEndpoint implements EndpointInstance {
 
   /** Test / internal: admit a parsed event when the endpoint is open. */
   admit(ev: OneBot12Event): void {
-    if (!this.#open || !isMessageEvent(ev)) return;
+    if (!this.#open) return;
+    if (!isMessageEvent(ev)) {
+      receiveOneBot12SideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        this,
+        ev,
+        this.#logger,
+      );
+      return;
+    }
     const conversation = onebot12InboundConversation(String(this.#options.id), ev);
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);

package/src/wss-endpoint.ts

@@ -3,7 +3,7 @@
  */
 import { clearInterval } from 'node:timers';
 import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -23,12 +23,15 @@ import {
   type OneBot12Event,
   type OneBot12WssConfig,
 } from './protocol.js';
+import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
+import { createOneBot12ContentPort } from './content-port.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 import { type OneBot12WsSocket, WS_OPEN } from './ws-types.js';
 
 export interface OneBot12WssEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: OneBot12WssConfig;
 }
@@ -38,6 +41,7 @@ export class OneBot12WssEndpoint implements EndpointInstance {
 
   readonly #options: OneBot12WssEndpointOptions;
   readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
+  readonly content = createOneBot12ContentPort((action, params) => this.callApi(action, params));
   #ws?: OneBot12WsSocket;
   #wsRelease?: () => void;
   #heartbeatTimer?: NodeJS.Timeout;
@@ -140,7 +144,17 @@ export class OneBot12WssEndpoint implements EndpointInstance {
   }
 
   admit(ev: OneBot12Event): void {
-    if (!this.#open || !isMessageEvent(ev)) return;
+    if (!this.#open) return;
+    if (!isMessageEvent(ev)) {
+      receiveOneBot12SideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        this,
+        ev,
+        this.#logger,
+      );
+      return;
+    }
     const conversation = onebot12InboundConversation(String(this.#options.id), ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);