@zhin.js/adapter-onebot11 6.0.13 → 6.0.14

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @zhin.js/adapter-onebot11
 
+## 6.0.14
+
+### Patch Changes
+
+- ffe7463: Add generation-bound message and merged-forward resolution through the canonical endpoint content port.
+- 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 [0c82a7e]
+- Updated dependencies [b9217e4]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [974772e]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [2f786bd]
+- Updated dependencies [63d89f9]
+- Updated dependencies [71c7cdd]
+- Updated dependencies [3cca0ea]
+- Updated dependencies [1312ca0]
+- Updated dependencies [985fa22]
+- Updated dependencies [04b861d]
+- Updated dependencies [a23d544]
+- Updated dependencies [8cddabf]
+- Updated dependencies [dbe5081]
+  - @zhin.js/im-contract@1.0.4
+  - @zhin.js/core@1.5.12
+  - @zhin.js/adapter@1.1.11
+  - @zhin.js/agent@1.1.14
+  - @zhin.js/host-http@1.0.11
+  - @zhin.js/command@1.0.15
+  - zhin.js@6.0.12
+  - @zhin.js/permission@1.0.3
+
 ## 6.0.13
 
 ### Patch Changes

package/README.md

@@ -70,7 +70,7 @@ plugins:
 
 ## 迁移说明（Plugin Runtime）
 
-- **notice / request 侧事件已移除**：旧 Adapter 对 `post_type: notice|request` 构建 `notice.receive` / `request.receive` 事件；新 Plugin Runtime（`messageGatewayToken`）暂无侧事件总线，入站仅处理 `post_type: message`，notice / request 事件静默丢弃。
+- **notice / request / meta 侧事件**：经 `sideEventGatewayToken` 归一后分发到 `handlers`；消息仍走 `messageGatewayToken`。
 - **群管工具暂未迁移**：旧 Adapter 经 `createSceneManagementTools` 注册踢人 / 禁言 / 群名片等成套 agent 工具；迁移后仅保留 `onebot11_set_title`，其余群管能力可通过 `callApi`（如 `set_group_kick`、`set_group_ban`）作为逃生舱调用。
 - **平台权限门禁**：`plugin.ts` setup 已注册 `registerDefaultScenePlatformPermitChecker('onebot11')`，`scene_admin` / `scene_owner` 依据入站 metadata 中的 sender `role`（owner / admin）判定。
 

package/adapters/onebot11.js

@@ -3,7 +3,7 @@
  * Convention entry: discover `adapters/onebot11.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 { OneBot11WsEndpoint } from "../lib/ws-endpoint.js";
 import { OneBot11WssEndpoint } from "../lib/wss-endpoint.js";
@@ -21,6 +21,7 @@ export default defineAdapter({
     create(context) {
         const config = resolveOneBot11Config(context.config);
         const gateway = context.use(messageGatewayToken);
+        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（onebot11.endpoint list 的"运行中"数据源）
         context.use(onebot11RuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -30,6 +31,7 @@ export default defineAdapter({
             return new OneBot11WssEndpoint({
                 id: context.id,
                 gateway,
+                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
@@ -37,6 +39,7 @@ export default defineAdapter({
         return new OneBot11WsEndpoint({
             id: context.id,
             gateway,
+            sideEvents,
             config,
         });
     },

package/adapters/onebot11.ts

@@ -2,7 +2,7 @@
  * Convention entry: discover `adapters/onebot11.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 { OneBot11WsEndpoint } from '../src/ws-endpoint.js';
 import { OneBot11WssEndpoint } from '../src/wss-endpoint.js';
@@ -18,6 +18,12 @@ export { OneBot11WssEndpoint } from '../src/wss-endpoint.js';
 export type { OneBot11WssEndpointOptions } from '../src/wss-endpoint.js';
 export type { OneBot11WsSocket, OneBot11WsCreateOptions } from '../src/ws-types.js';
 
+declare module '@zhin.js/core' {
+  interface AdapterEndpoints {
+    onebot11: import('../src/ws-endpoint.js').OneBot11WsEndpoint;
+  }
+}
+
 export default defineAdapter<OneBot11AdapterConfig>({
   capabilities: ['inbound', 'outbound'],
   // OneBot file 参数原生消费 url / base64:// 媒体；无卡片交互面，交互段降级纯文本。
@@ -28,6 +34,7 @@ export default defineAdapter<OneBot11AdapterConfig>({
   create(context) {
     const config = resolveOneBot11Config(context.config);
     const gateway = context.use(messageGatewayToken);
+    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（onebot11.endpoint list 的"运行中"数据源）
     context.use(onebot11RuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -37,6 +44,7 @@ export default defineAdapter<OneBot11AdapterConfig>({
       return new OneBot11WssEndpoint({
         id: context.id,
         gateway,
+        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
@@ -44,6 +52,7 @@ export default defineAdapter<OneBot11AdapterConfig>({
     return new OneBot11WsEndpoint({
       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 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/protocol.js

@@ -85,14 +85,14 @@ export function onebot11InboundConversation(endpointKey, ev) {
 }
 /** Build inbound text for MessageGateway.receive */
 export function formatInboundContent(ev) {
-    if (typeof ev.raw_message === 'string' && ev.raw_message)
-        return ev.raw_message;
     if (Array.isArray(ev.message)) {
         return ev.message
             .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
             .join('');
     }
-    return '';
+    return typeof ev.raw_message === 'string'
+        ? ev.raw_message.replace(/\[CQ:[^\]]+\]/g, '').trim()
+        : '';
 }
 export function senderDisplayName(ev) {
     const name = ev.sender?.card || ev.sender?.nickname;

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 { OneBot11Event } from './protocol.js';
+export interface OneBot11SideEventCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function receiveOneBot11SideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, caller: OneBot11SideEventCaller, raw: OneBot11Event, 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 receiveOneBot11SideEvent(sideEvents, endpointKey, caller, raw, logger) {
+    if (!sideEvents)
+        return;
+    const record = raw;
+    const postType = String(record.post_type ?? '');
+    const requestType = String(record.request_type ?? '');
+    const isRequest = postType === 'request' || postType.startsWith('request.');
+    const isFriend = requestType === 'friend' || postType.includes('friend');
+    void receiveOneBotLikeSideEvent(sideEvents, {
+        adapter: 'onebot11',
+        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: 'onebot11_side_event_failed',
+            endpoint: endpointKey,
+            post_type: postType || undefined,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+}

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 OneBot11Event, type OneBot11WsConfig } from './protocol.js';
 import { type OneBot11WsCreateOptions, type OneBot11WsSocket } from './ws-types.js';
 export interface OneBot11WsEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly config: OneBot11WsConfig;
     readonly createWebSocket?: (url: string, options: OneBot11WsCreateOptions) => OneBot11WsSocket;
 }
 export declare class OneBot11WsEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot11WsEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/ws-endpoint.js

@@ -7,11 +7,14 @@ import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot11EndpointManagement } from './endpoint-management.js';
 import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatInboundMetadata, formatOutboundSegments, isMessageEvent, onebot11InboundConversation, senderDisplayName, senderUserId, } from './protocol.js';
+import { receiveOneBot11SideEvent } from './side-event-dispatch.js';
+import { createOneBot11ContentPort } from './content-port.js';
 import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, } from './ws-transport.js';
 export class OneBot11WsEndpoint {
     #logger;
     #options;
     management = createOneBot11EndpointManagement(this);
+    content = createOneBot11ContentPort((action, params) => this.callApi(action, params));
     #lifecycle;
     #ws;
     #requestId = { value: 0 };
@@ -106,8 +109,12 @@ export class OneBot11WsEndpoint {
     }
     /** 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)) {
+            receiveOneBot11SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            return;
+        }
         const conversation = onebot11InboundConversation(String(this.#options.id), ev);
         const content = formatInboundContent(ev);
         const inbound = formatInboundMetadata(ev, this.#options.config.id);

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 OneBot11Event, type OneBot11WssConfig } from './protocol.js';
 export interface OneBot11WssEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: OneBot11WssConfig;
 }
 export declare class OneBot11WssEndpoint implements EndpointInstance {
     #private;
     readonly management: EndpointManagement;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot11WssEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/wss-endpoint.js

@@ -6,12 +6,15 @@ import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot11EndpointManagement } from './endpoint-management.js';
 import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import { buildSendAction, formatInboundContent, formatInboundMetadata, formatOutboundSegments, isMessageEvent, onebot11InboundConversation, senderDisplayName, senderUserId, } from './protocol.js';
+import { receiveOneBot11SideEvent } from './side-event-dispatch.js';
+import { createOneBot11ContentPort } from './content-port.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';
 export class OneBot11WssEndpoint {
     #logger;
     #options;
     management = createOneBot11EndpointManagement(this);
+    content = createOneBot11ContentPort((action, params) => this.callApi(action, params));
     #ws;
     #wsRelease;
     #heartbeatTimer;
@@ -101,8 +104,12 @@ export class OneBot11WssEndpoint {
         return true;
     }
     admit(ev) {
-        if (!this.#open || !isMessageEvent(ev))
+        if (!this.#open)
             return;
+        if (!isMessageEvent(ev)) {
+            receiveOneBot11SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            return;
+        }
         const conversation = onebot11InboundConversation(String(this.#options.id), ev);
         const inbound = formatInboundMetadata(ev, this.#options.config.id);
         void this.#options.gateway.receive({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "6.0.13",
+  "version": "6.0.14",
   "description": "Zhin.js OneBot 11 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -41,12 +41,12 @@
   },
   "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",
-    "@zhin.js/permission": "1.0.2"
+    "@zhin.js/permission": "1.0.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -54,17 +54,17 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.13",
-    "@zhin.js/host-http": "1.0.10",
-    "zhin.js": "6.0.11"
+    "@zhin.js/agent": "1.1.14",
+    "@zhin.js/host-http": "1.0.11",
+    "zhin.js": "6.0.12"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent": "1.1.13",
-    "@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/agent": "1.1.14",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.12",
+    "zhin.js": "6.0.12"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {

package/src/content-port.ts

@@ -0,0 +1,66 @@
+import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import { toCanonicalSegments } from '@zhin.js/core';
+import type { ConversationMessage, ConversationReference, ForwardEntry } from '@zhin.js/im-contract';
+
+type CallApi = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+
+export function createOneBot11ContentPort(callApi: CallApi): EndpointContentPort {
+  return Object.freeze({
+    async resolve(reference: ConversationReference, context: EndpointContentResolveContext) {
+      try {
+        context.signal.throwIfAborted();
+        if (reference.kind === 'media') {
+          return reference.media.kind === 'file'
+            ? Object.freeze({ status: 'unsupported' as const, code: 'onebot11_opaque_media' })
+            : Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
+        }
+        if (reference.kind === 'message') {
+          const row = await callApi('get_msg', { message_id: reference.message.id }) as Record<string, unknown>;
+          context.signal.throwIfAborted();
+          const segments = normalizeSegments(row.message ?? row.raw_message);
+          const sender = row.sender as Record<string, unknown> | undefined;
+          const value: ConversationMessage = 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' as const, reference, value });
+        }
+        const raw = await callApi('get_forward_msg', { id: reference.forwardId }) as Record<string, unknown>;
+        context.signal.throwIfAborted();
+        const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
+        const value: readonly ForwardEntry[] = Object.freeze(nodes.map((node) => {
+          const row = node as Record<string, unknown>;
+          const sender = row.sender as Record<string, unknown> | undefined;
+          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' as const, reference, value, truncated: nodes.length >= context.maxEntries });
+      } catch (error) {
+        if (context.signal.aborted) return Object.freeze({ status: 'expired' as const, code: 'turn_aborted' });
+        return Object.freeze({ status: 'failed' as const, code: 'onebot11_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
+}
+
+function normalizeSegments(value: unknown) {
+  if (Array.isArray(value)) return Object.freeze(toCanonicalSegments(value as never));
+  return Object.freeze([{ type: 'text', data: Object.freeze({ text: String(value ?? '') }) }]);
+}
+
+function toMillis(value: unknown): number {
+  const time = Number(value);
+  if (!Number.isFinite(time)) return Date.now();
+  return time < 10_000_000_000 ? time * 1000 : time;
+}

package/src/protocol.ts

@@ -198,13 +198,14 @@ export function onebot11InboundConversation(endpointKey: string, ev: OneBot11Eve
 
 /** Build inbound text for MessageGateway.receive */
 export function formatInboundContent(ev: OneBot11Event): string {
-  if (typeof ev.raw_message === 'string' && ev.raw_message) return ev.raw_message;
   if (Array.isArray(ev.message)) {
     return ev.message
       .map((seg) => (seg.type === 'text' ? String(seg.data?.text ?? '') : ''))
       .join('');
   }
-  return '';
+  return typeof ev.raw_message === 'string'
+    ? ev.raw_message.replace(/\[CQ:[^\]]+\]/g, '').trim()
+    : '';
 }
 
 export function senderDisplayName(ev: OneBot11Event): string {

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 { OneBot11Event } from './protocol.js';
+
+export interface OneBot11SideEventCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function receiveOneBot11SideEvent(
+  sideEvents: SideEventGateway | undefined,
+  endpointKey: string,
+  caller: OneBot11SideEventCaller,
+  raw: OneBot11Event,
+  logger: ReturnType<typeof getAdapterLogger>,
+): void {
+  if (!sideEvents) return;
+  const record = raw as Record<string, unknown>;
+  const postType = String(record.post_type ?? '');
+  const requestType = String(record.request_type ?? '');
+  const isRequest = postType === 'request' || postType.startsWith('request.');
+  const isFriend = requestType === 'friend' || postType.includes('friend');
+  void receiveOneBotLikeSideEvent(sideEvents, {
+    adapter: 'onebot11',
+    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: 'onebot11_side_event_failed',
+      endpoint: endpointKey,
+      post_type: postType || undefined,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+  });
+}

package/src/ws-endpoint.ts

@@ -10,7 +10,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 { createOneBot11EndpointManagement } from './endpoint-management.js';
@@ -28,6 +28,8 @@ import {
   type OneBot11Event,
   type OneBot11WsConfig,
 } from './protocol.js';
+import { receiveOneBot11SideEvent } from './side-event-dispatch.js';
+import { createOneBot11ContentPort } from './content-port.js';
 import {
   callOneBot11WsAction,
   handleOneBot11WsMessage,
@@ -42,6 +44,7 @@ import {
 export interface OneBot11WsEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly config: OneBot11WsConfig;
   readonly createWebSocket?: (
     url: string,
@@ -54,6 +57,7 @@ export class OneBot11WsEndpoint implements EndpointInstance {
 
   readonly #options: OneBot11WsEndpointOptions;
   readonly management: EndpointManagement = createOneBot11EndpointManagement(this);
+  readonly content = createOneBot11ContentPort((action, params) => this.callApi(action, params));
   readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot11WsSocket;
   #requestId = { value: 0 };
@@ -159,7 +163,17 @@ export class OneBot11WsEndpoint implements EndpointInstance {
 
   /** Test / internal: admit a parsed event when the endpoint is open. */
   admit(ev: OneBot11Event): void {
-    if (!this.#open || !isMessageEvent(ev)) return;
+    if (!this.#open) return;
+    if (!isMessageEvent(ev)) {
+      receiveOneBot11SideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        this,
+        ev,
+        this.#logger,
+      );
+      return;
+    }
     const conversation = onebot11InboundConversation(String(this.#options.id), ev);
     const content = formatInboundContent(ev);
     const inbound = formatInboundMetadata(ev, this.#options.config.id);

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';
@@ -21,6 +21,8 @@ import {
   type OneBot11Event,
   type OneBot11WssConfig,
 } from './protocol.js';
+import { receiveOneBot11SideEvent } from './side-event-dispatch.js';
+import { createOneBot11ContentPort } from './content-port.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 import {
   callOneBot11WsAction,
@@ -37,6 +39,7 @@ import {
 export interface OneBot11WssEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: OneBot11WssConfig;
 }
@@ -46,6 +49,7 @@ export class OneBot11WssEndpoint implements EndpointInstance {
 
   readonly #options: OneBot11WssEndpointOptions;
   readonly management: EndpointManagement = createOneBot11EndpointManagement(this);
+  readonly content = createOneBot11ContentPort((action, params) => this.callApi(action, params));
   #ws?: OneBot11WsSocket;
   #wsRelease?: () => void;
   #heartbeatTimer?: NodeJS.Timeout;
@@ -145,7 +149,17 @@ export class OneBot11WssEndpoint implements EndpointInstance {
   }
 
   admit(ev: OneBot11Event): void {
-    if (!this.#open || !isMessageEvent(ev)) return;
+    if (!this.#open) return;
+    if (!isMessageEvent(ev)) {
+      receiveOneBot11SideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        this,
+        ev,
+        this.#logger,
+      );
+      return;
+    }
     const conversation = onebot11InboundConversation(String(this.#options.id), ev);
     const inbound = formatInboundMetadata(ev, this.#options.config.id);
     void this.#options.gateway.receive({