@zhin.js/adapter-qq 7.0.13 → 7.0.14

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @zhin.js/adapter-qq
 
+## 7.0.14
+
+### Patch Changes
+
+- 974772e: Replace the user-facing `Prompt` vocabulary with the `UserInteraction` authoring surface for input, confirmation, and selection. Commands and handlers now expose `interaction`; IM Runtime exposes `createInteraction`; schema-driven endpoint collection is named `SchemaInteraction`. The old prompt-named interaction types and properties are removed rather than aliased. User interactions render through one canonical Markdown and keyboard/list presentation module shared by commands and Agent `ask_user` turns.
+
+  Extract the transport-neutral interaction contract into `@zhin.js/interaction`. A discriminated `ask()` API supports text, number, confirmation, single-select, multi-select, and typed lists with structured `title`, `description`, and `tip` content. Typed `sequence()` interactions return one result object keyed by step id, render progress, and retry invalid replies without leaking invalid values to callers.
+
+  Preserve AI Markdown and card command actions through outbound publishing. QQ delivers Markdown with native command buttons; KOOK, Discord, Telegram, DingTalk, and Lark/Feishu now declare and encode their native Markdown dialects while retaining each adapter's interaction policy. Correct QQ callback button action encoding and button style mapping.
+
+- 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/middleware@1.0.12
+  - @zhin.js/permission@1.0.3
+
 ## 7.0.13
 
 ### Patch Changes

package/README.md

@@ -135,9 +135,14 @@ master 可执行；未配置则放行（首个扫码绑定者会写入该 endpoi
 
 platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；`@zhin.js/tool` descriptor 保留 `platforms` / `scopes` / `permissions`，CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 执行门禁。
 
-## 迁移后出站能力变化
+## Markdown 与交互输出
 
-迁移到 Plugin Runtime 后，出站统一经 `messageGatewayToken` 渲染为文本后发送（`sendPrivateMessage` / `sendGroupMessage` / `sendGuildMessage`）。旧 Adapter 的富媒体出站能力（图片 / 语音 / 视频、keyboard 按钮、markdown 模板等）暂未迁移，当前出站等价于纯文本。如需富媒体，可通过 endpoint 的 QQ API 封装或直接调用 QQ HTTP API 作为逃生舱。
+QQ Endpoint 声明原生 `markdown` / `keyboard` 能力。普通 AI Markdown 会保留为 QQ Markdown
+消息；命令或 Agent 通过 `UserInteraction.ask()` 发起 `confirm` / `select` 时，会生成
+Markdown + 指令按钮组。按钮值与手动输入共用同一解析入口，不维护 QQ 专用交互状态。
+
+不支持原生按钮的 Adapter 会在 Core 中把同一 keyboard 语义降级为编号列表，并保存数字到
+payload 的回跳映射。图片、音频、视频和文件仍沿 canonical `MediaRef` 出站链投递。
 
 ## 许可证
 

package/adapters/qq.js

@@ -3,7 +3,7 @@
  * Convention entry: discover `adapters/qq.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 { QqHttpEndpoint, QqWebsocketEndpoint } from "../lib/endpoint.js";
 import { resolveQqConfig, } from "../lib/protocol.js";
@@ -14,12 +14,15 @@ export default defineAdapter({
     // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
     // markdown/keyboard 原生按钮承载交互段。
     segments: {
+        supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'markdown', 'keyboard'],
+        markdown: 'native',
         outboundMedia: ['url', 'upload'],
         interactive: 'native',
     },
     create(context) {
         const config = resolveQqConfig(context.config);
         const gateway = context.use(messageGatewayToken);
+        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
         const state = context.use(qqRuntimeStateToken);
         state.endpoints.set(config.id, {
@@ -32,11 +35,13 @@ export default defineAdapter({
             ? new QqWebsocketEndpoint({
                 id: context.id,
                 gateway,
+                sideEvents,
                 config,
             })
             : new QqHttpEndpoint({
                 id: context.id,
                 gateway,
+                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });

package/adapters/qq.ts

@@ -2,7 +2,7 @@
  * Convention entry: discover `adapters/qq.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 { QqHttpEndpoint, QqWebsocketEndpoint } from '../src/endpoint.js';
 import {
@@ -24,17 +24,26 @@ export type {
   QqHttpEndpointOptions,
 } from '../src/endpoint.js';
 
+declare module '@zhin.js/core' {
+  interface AdapterEndpoints {
+    qq: import('../src/endpoint.js').QqWebsocketEndpoint;
+  }
+}
+
 export default defineAdapter<QqAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
   // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
   // markdown/keyboard 原生按钮承载交互段。
   segments: {
+    supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'markdown', 'keyboard'],
+    markdown: 'native',
     outboundMedia: ['url', 'upload'],
     interactive: 'native',
   },
   create(context) {
     const config = resolveQqConfig(context.config);
     const gateway = context.use(messageGatewayToken);
+    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
     const state = context.use(qqRuntimeStateToken);
     state.endpoints.set(config.id, {
@@ -47,11 +56,13 @@ export default defineAdapter<QqAdapterConfig>({
       ? new QqWebsocketEndpoint({
         id: context.id,
         gateway,
+        sideEvents,
         config,
       })
       : new QqHttpEndpoint({
         id: context.id,
         gateway,
+        sideEvents,
         http: context.use(httpHostToken),
         config,
       });

package/lib/endpoint.d.ts

@@ -2,7 +2,7 @@
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
 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 QqInboundMessage, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig } from './protocol.js';
@@ -13,6 +13,7 @@ export type { CreateQqHttpBot, QqHttpBotTransport } from './webhook.js';
 export interface QqEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedQqWebsocketConfig;
     readonly createBot?: CreateQqBot;
 }
@@ -42,6 +43,7 @@ export declare class QqWebsocketEndpoint implements EndpointInstance {
 export interface QqHttpEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedQqHttpConfig;
     readonly createBot?: CreateQqHttpBot;

package/lib/endpoint.js

@@ -4,6 +4,7 @@ import { registerQqAgentEndpoint } from './qq-agent-deps.js';
 import { formatInboundContent, parseCompoundMessageId, qqInboundConversation, qqOutboundKind, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
 import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
 import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
+import { bindQqBotSideEvents, receiveQqSideEvent, } from './side-event-dispatch.js';
 export class QqWebsocketEndpoint {
     #logger;
     #options;
@@ -180,6 +181,9 @@ export class QqWebsocketEndpoint {
             if (msg)
                 this.admit(msg);
         });
+        bindQqBotSideEvents(bot, (eventName, raw) => {
+            receiveQqSideEvent(this.#options.sideEvents, this.#options.config.id, bot, eventName, raw, this.#logger);
+        });
     }
     #requireBot() {
         if (!this.#bot)
@@ -372,6 +376,9 @@ export class QqHttpEndpoint {
             if (msg)
                 this.admit(msg);
         });
+        bindQqBotSideEvents(bot, (eventName, raw) => {
+            receiveQqSideEvent(this.#options.sideEvents, this.#options.config.id, bot, eventName, raw, this.#logger);
+        });
     }
     #requireBot() {
         if (!this.#bot)

package/lib/outbound.js

@@ -82,7 +82,7 @@ function normalizeMarkdownSegment(seg) {
 function coreButtonToQq(btn) {
     const isCommand = btn.mode === 'command';
     const action = {
-        type: isCommand ? 2 : 1,
+        type: isCommand ? 2 : 0,
         permission: { type: 2 },
         data: btn.payload ?? '',
         click_limit: btn.disabled ? 0 : 10,
@@ -99,7 +99,7 @@ function coreButtonToQq(btn) {
         render_data: {
             label: btn.label ?? '',
             visited_label: btn.label ?? '',
-            style: 0,
+            style: btn.style === 'primary' ? 1 : btn.style === 'danger' ? 2 : 0,
         },
         action,
     };

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

@@ -0,0 +1,13 @@
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { type getAdapterLogger } from '@zhin.js/logger';
+export interface QqSideEventCaller {
+    approveGroupJoinRequest?(groupId: string, userId: string, options: {
+        op: 'approve' | 'reject';
+        join_request_id: string;
+        reason?: string;
+    }): Promise<unknown>;
+}
+export declare function bindQqBotSideEvents(bot: {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+}, dispatch: (eventName: string, raw: unknown) => void): void;
+export declare function receiveQqSideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, caller: QqSideEventCaller, eventName: string, raw: unknown, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -0,0 +1,93 @@
+import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
+import { formatCompact } from '@zhin.js/logger';
+const QQ_SIDE_EVENT_NAMES = [
+    'notice.group.join_request',
+    'notice.group.member',
+    'notice.group.member.increase',
+    'notice.group.member.decrease',
+    'notice.group.increase',
+    'notice.group.decrease',
+    'notice.guild.member',
+    'notice.guild.member.increase',
+    'notice.guild.member.decrease',
+];
+export function bindQqBotSideEvents(bot, dispatch) {
+    for (const name of QQ_SIDE_EVENT_NAMES) {
+        bot.on(name, (raw) => dispatch(name, raw));
+    }
+}
+function toOneBotLikeRaw(eventName, raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const record = raw;
+    const asId = (value) => {
+        if (typeof value === 'string' || typeof value === 'number')
+            return value;
+        return undefined;
+    };
+    const asTime = (value) => {
+        const n = typeof value === 'number' ? value : Number(value);
+        return Number.isFinite(n) && n > 0 ? n : Date.now();
+    };
+    if (eventName === 'notice.group.join_request') {
+        return {
+            ...record,
+            post_type: 'request',
+            request_type: 'group',
+            flag: record.join_request_id != null ? String(record.join_request_id) : undefined,
+            user_id: asId(record.user_id),
+            group_id: asId(record.group_id),
+            comment: record.verify_info != null ? String(record.verify_info) : undefined,
+            time: asTime(record.timestamp),
+        };
+    }
+    if (eventName.startsWith('notice.')) {
+        return {
+            ...record,
+            post_type: eventName,
+            notice_type: eventName.replace(/^notice\./, ''),
+            time: asTime(record.timestamp),
+        };
+    }
+    return null;
+}
+export function receiveQqSideEvent(sideEvents, endpointKey, caller, eventName, raw, logger) {
+    if (!sideEvents)
+        return;
+    const mapped = toOneBotLikeRaw(eventName, raw);
+    if (!mapped)
+        return;
+    const isJoinRequest = eventName === 'notice.group.join_request';
+    const joinRaw = isJoinRequest && raw && typeof raw === 'object'
+        ? raw
+        : undefined;
+    void receiveOneBotLikeSideEvent(sideEvents, {
+        adapter: 'qq',
+        endpointKey,
+        platform: 'qq',
+        raw: mapped,
+        ...(isJoinRequest && caller.approveGroupJoinRequest && joinRaw ? {
+            approve: async (flag, remark) => {
+                await caller.approveGroupJoinRequest(String(joinRaw.group_id ?? ''), String(joinRaw.user_id ?? ''), {
+                    op: 'approve',
+                    join_request_id: String(joinRaw.join_request_id ?? flag),
+                    ...(remark ? { reason: remark } : {}),
+                });
+            },
+            reject: async (flag, reason) => {
+                await caller.approveGroupJoinRequest(String(joinRaw.group_id ?? ''), String(joinRaw.user_id ?? ''), {
+                    op: 'reject',
+                    join_request_id: String(joinRaw.join_request_id ?? flag),
+                    ...(reason ? { reason } : {}),
+                });
+            },
+        } : {}),
+    }).catch((err) => {
+        logger.warn(formatCompact({
+            op: 'qq_side_event_failed',
+            endpoint: endpointKey,
+            event: eventName,
+            error: err instanceof Error ? err.message : String(err),
+        }));
+    });
+}

package/lib/webhook.js

@@ -94,6 +94,9 @@ export function defaultCreateHttpBot(config) {
             await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
             return true;
         },
+        approveGroupJoinRequest: (groupId, userId, options) => bot
+            .approveGroupJoinRequest?.(groupId, userId, options)
+            ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
         middleware: (ctx, next) => bot.middleware(ctx, next),
     };
 }

package/lib/ws.d.ts

@@ -22,6 +22,11 @@ export interface QqBotTransport {
     createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
     addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
     removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+    approveGroupJoinRequest?(groupId: string, userId: string, options: {
+        op: 'approve' | 'reject';
+        join_request_id: string;
+        reason?: string;
+    }): Promise<unknown>;
 }
 export type CreateQqBot = (config: ResolvedQqWebsocketConfig) => QqBotTransport;
 interface QqOfficialBotLifecycle {

package/lib/ws.js

@@ -226,5 +226,8 @@ export function defaultCreateBot(config) {
             await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
             return true;
         },
+        approveGroupJoinRequest: (groupId, userId, options) => bot
+            .approveGroupJoinRequest?.(groupId, userId, options)
+            ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "7.0.13",
+  "version": "7.0.14",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,21 +35,21 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@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"
   },
   "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/middleware": "1.0.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/middleware": "1.0.12",
+    "zhin.js": "6.0.12"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -73,9 +73,9 @@
     "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"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -7,7 +7,7 @@ import type {
   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 { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -37,6 +37,11 @@ import {
   type CreateQqBot,
   type QqBotTransport,
 } from './ws.js';
+import {
+  bindQqBotSideEvents,
+  receiveQqSideEvent,
+  type QqSideEventCaller,
+} from './side-event-dispatch.js';
 
 export type { CreateQqBot, QqBotTransport } from './ws.js';
 export type { CreateQqHttpBot, QqHttpBotTransport } from './webhook.js';
@@ -44,6 +49,7 @@ export type { CreateQqHttpBot, QqHttpBotTransport } from './webhook.js';
 export interface QqEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly config: ResolvedQqWebsocketConfig;
   readonly createBot?: CreateQqBot;
 }
@@ -246,6 +252,16 @@ export class QqWebsocketEndpoint implements EndpointInstance {
       const msg = normalizeQqMessage(raw);
       if (msg) this.admit(msg);
     });
+    bindQqBotSideEvents(bot, (eventName, raw) => {
+      receiveQqSideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        bot as QqSideEventCaller,
+        eventName,
+        raw,
+        this.#logger,
+      );
+    });
   }
 
   #requireBot(): QqBotTransport {
@@ -257,6 +273,7 @@ export class QqWebsocketEndpoint implements EndpointInstance {
 export interface QqHttpEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: ResolvedQqHttpConfig;
   readonly createBot?: CreateQqHttpBot;
@@ -469,6 +486,16 @@ export class QqHttpEndpoint implements EndpointInstance {
       const msg = normalizeQqMessage(raw);
       if (msg) this.admit(msg);
     });
+    bindQqBotSideEvents(bot, (eventName, raw) => {
+      receiveQqSideEvent(
+        this.#options.sideEvents,
+        this.#options.config.id,
+        bot as QqSideEventCaller,
+        eventName,
+        raw,
+        this.#logger,
+      );
+    });
   }
 
   #requireBot(): QqBotTransport {

package/src/outbound.ts

@@ -31,6 +31,7 @@ interface QqOutboundButtonSpec {
   readonly label?: string;
   readonly payload?: string;
   readonly disabled?: boolean;
+  readonly style?: 'primary' | 'danger' | 'secondary';
   readonly mode?: string;
   readonly command?: { readonly enter?: boolean; readonly reply?: boolean };
 }
@@ -103,7 +104,7 @@ function normalizeMarkdownSegment(seg: QqWireSegment): QqOutboundElem | null {
 function coreButtonToQq(btn: QqOutboundButtonSpec): Record<string, unknown> {
   const isCommand = btn.mode === 'command';
   const action: Record<string, unknown> = {
-    type: isCommand ? 2 : 1,
+    type: isCommand ? 2 : 0,
     permission: { type: 2 },
     data: btn.payload ?? '',
     click_limit: btn.disabled ? 0 : 10,
@@ -118,7 +119,7 @@ function coreButtonToQq(btn: QqOutboundButtonSpec): Record<string, unknown> {
     render_data: {
       label: btn.label ?? '',
       visited_label: btn.label ?? '',
-      style: 0,
+      style: btn.style === 'primary' ? 1 : btn.style === 'danger' ? 2 : 0,
     },
     action,
   };

package/src/side-event-dispatch.ts

@@ -0,0 +1,120 @@
+import { receiveOneBotLikeSideEvent, type OneBotLikeRawEvent } from '@zhin.js/core';
+import type { SideEventGateway } from '@zhin.js/core/runtime';
+import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
+
+export interface QqSideEventCaller {
+  approveGroupJoinRequest?(
+    groupId: string,
+    userId: string,
+    options: { op: 'approve' | 'reject'; join_request_id: string; reason?: string },
+  ): Promise<unknown>;
+}
+
+const QQ_SIDE_EVENT_NAMES = [
+  'notice.group.join_request',
+  'notice.group.member',
+  'notice.group.member.increase',
+  'notice.group.member.decrease',
+  'notice.group.increase',
+  'notice.group.decrease',
+  'notice.guild.member',
+  'notice.guild.member.increase',
+  'notice.guild.member.decrease',
+] as const;
+
+export function bindQqBotSideEvents(
+  bot: { on(event: string, listener: (...args: unknown[]) => void): void },
+  dispatch: (eventName: string, raw: unknown) => void,
+): void {
+  for (const name of QQ_SIDE_EVENT_NAMES) {
+    bot.on(name, (raw) => dispatch(name, raw));
+  }
+}
+
+function toOneBotLikeRaw(eventName: string, raw: unknown): OneBotLikeRawEvent | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const record = raw as Record<string, unknown>;
+  const asId = (value: unknown): string | number | undefined => {
+    if (typeof value === 'string' || typeof value === 'number') return value;
+    return undefined;
+  };
+  const asTime = (value: unknown): number => {
+    const n = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(n) && n > 0 ? n : Date.now();
+  };
+  if (eventName === 'notice.group.join_request') {
+    return {
+      ...record,
+      post_type: 'request',
+      request_type: 'group',
+      flag: record.join_request_id != null ? String(record.join_request_id) : undefined,
+      user_id: asId(record.user_id),
+      group_id: asId(record.group_id),
+      comment: record.verify_info != null ? String(record.verify_info) : undefined,
+      time: asTime(record.timestamp),
+    };
+  }
+  if (eventName.startsWith('notice.')) {
+    return {
+      ...record,
+      post_type: eventName,
+      notice_type: eventName.replace(/^notice\./, ''),
+      time: asTime(record.timestamp),
+    };
+  }
+  return null;
+}
+
+export function receiveQqSideEvent(
+  sideEvents: SideEventGateway | undefined,
+  endpointKey: string,
+  caller: QqSideEventCaller,
+  eventName: string,
+  raw: unknown,
+  logger: ReturnType<typeof getAdapterLogger>,
+): void {
+  if (!sideEvents) return;
+  const mapped = toOneBotLikeRaw(eventName, raw);
+  if (!mapped) return;
+  const isJoinRequest = eventName === 'notice.group.join_request';
+  const joinRaw = isJoinRequest && raw && typeof raw === 'object'
+    ? raw as { group_id?: string | number; user_id?: string | number; join_request_id?: string | number }
+    : undefined;
+  void receiveOneBotLikeSideEvent(sideEvents, {
+    adapter: 'qq',
+    endpointKey,
+    platform: 'qq',
+    raw: mapped,
+    ...(isJoinRequest && caller.approveGroupJoinRequest && joinRaw ? {
+      approve: async (flag, remark) => {
+        await caller.approveGroupJoinRequest!(
+          String(joinRaw.group_id ?? ''),
+          String(joinRaw.user_id ?? ''),
+          {
+            op: 'approve',
+            join_request_id: String(joinRaw.join_request_id ?? flag),
+            ...(remark ? { reason: remark } : {}),
+          },
+        );
+      },
+      reject: async (flag, reason) => {
+        await caller.approveGroupJoinRequest!(
+          String(joinRaw.group_id ?? ''),
+          String(joinRaw.user_id ?? ''),
+          {
+            op: 'reject',
+            join_request_id: String(joinRaw.join_request_id ?? flag),
+            ...(reason ? { reason } : {}),
+          },
+        );
+      },
+    } : {}),
+  }).catch((err) => {
+    logger.warn(formatCompact({
+      op: 'qq_side_event_failed',
+      endpoint: endpointKey,
+      event: eventName,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+  });
+}

package/src/webhook.ts

@@ -122,6 +122,10 @@ export function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTra
       await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
       return true;
     },
+    approveGroupJoinRequest: (groupId, userId, options) =>
+      (bot as { approveGroupJoinRequest?: QqBotTransport['approveGroupJoinRequest'] })
+        .approveGroupJoinRequest?.(groupId, userId, options)
+      ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
     middleware: (ctx, next) => bot.middleware(ctx as never, next as never),
   };
 }

package/src/ws.ts

@@ -39,6 +39,11 @@ export interface QqBotTransport {
     userId: string,
     roleId: string,
   ): Promise<boolean>;
+  approveGroupJoinRequest?(
+    groupId: string,
+    userId: string,
+    options: { op: 'approve' | 'reject'; join_request_id: string; reason?: string },
+  ): Promise<unknown>;
 }
 
 export type CreateQqBot = (config: ResolvedQqWebsocketConfig) => QqBotTransport;
@@ -288,5 +293,9 @@ export function defaultCreateBot(config: ResolvedQqWebsocketConfig): QqBotTransp
       await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
       return true;
     },
+    approveGroupJoinRequest: (groupId, userId, options) =>
+      (bot as { approveGroupJoinRequest?: QqBotTransport['approveGroupJoinRequest'] })
+        .approveGroupJoinRequest?.(groupId, userId, options)
+      ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
   };
 }