@zhin.js/adapter-qq 4.0.2 → 5.0.1

package/lib/qq-endpoint-manager.js

@@ -0,0 +1,159 @@
+import { ReceiverMode as QQReceiverMode } from './types.js';
+import { startQqBindFlow } from './qq-bind-flow.js';
+import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
+const DEFAULT_INTENTS = [
+    'GUILDS',
+    'GUILD_MEMBERS',
+    'GUILD_MESSAGE_REACTIONS',
+    'DIRECT_MESSAGE',
+    'GROUP_AND_C2C_EVENT',
+    'INTERACTION',
+    'MESSAGE_AUDIT',
+    'AUDIO_ACTION',
+    'PUBLIC_GUILD_MESSAGES',
+];
+function clonePlainConfig(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function resolveQqEndpointTemplate(root) {
+    const configService = root.inject('config');
+    const raw = configService?.primaryFile && configService.getRaw
+        ? configService.getRaw(configService.primaryFile)
+        : undefined;
+    const existing = raw?.endpoints?.find((e) => e.context === 'qq');
+    if (!existing) {
+        return {
+            mode: QQReceiverMode.WEBSOCKET,
+            sandbox: false,
+            timeout: 10_000,
+            data_dir: './data',
+            intents: [...DEFAULT_INTENTS],
+        };
+    }
+    const { name: _n, appid: _a, secret: _s, context: _c, ...rest } = existing;
+    return clonePlainConfig(rest);
+}
+function resolveBindOperatorId(userOpenId, ctx) {
+    const fromApi = userOpenId?.trim();
+    if (fromApi)
+        return fromApi;
+    return ctx.message.$sender?.id?.trim() ?? '';
+}
+function applyBindOwnership(template, operatorId) {
+    const { master: _m, aiAccess, ...rest } = template;
+    if (!operatorId) {
+        return rest;
+    }
+    const prior = aiAccess;
+    return {
+        ...rest,
+        master: operatorId,
+        aiAccess: {
+            mode: prior?.mode ?? 'whitelist',
+            users: [operatorId],
+            groups: Array.isArray(prior?.groups) ? [...prior.groups] : [],
+            denyMessage: typeof prior?.denyMessage === 'string'
+                ? prior.denyMessage
+                : '当前用户尚未开放 AI 功能，请联系开启。',
+        },
+    };
+}
+function readQqConfigs(root) {
+    const configService = root.inject('config');
+    if (!configService?.primaryFile || !configService.getRaw)
+        return [];
+    const raw = configService.getRaw(configService.primaryFile);
+    return (raw?.endpoints ?? []).filter((e) => e.context === 'qq');
+}
+/** 全局单例：同一时间只允许一个 QQ 扫码绑定 */
+let activeStopFlow = null;
+export class QqEndpointManager {
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    supportsProvision() {
+        return true;
+    }
+    listEndpoints() {
+        return readQqConfigs(this.adapter.plugin.root);
+    }
+    cancelProvision() {
+        if (!activeStopFlow)
+            return false;
+        activeStopFlow();
+        activeStopFlow = null;
+        return true;
+    }
+    async addEndpoint(ctx) {
+        if (activeStopFlow) {
+            throw new Error('已有进行中的 QQ 机器人绑定，请先 /endpoint cancel');
+        }
+        let endpointName;
+        const nameMatch = ctx.message.$raw?.match(/\/endpoint\s+add\s+qq\s+(\S+)/);
+        if (nameMatch?.[1]) {
+            endpointName = nameMatch[1];
+        }
+        return new Promise((resolve, reject) => {
+            const stopFlow = startQqBindFlow({
+                onQrDisplayed: async (url) => {
+                    await ctx.onStatusUpdate('请用手机 QQ 扫描二维码完成机器人绑定。', {
+                        qrcode: url,
+                    });
+                },
+                onQrExpired: async () => {
+                    await ctx.onStatusUpdate('二维码已过期，正在刷新，请扫描新二维码…');
+                },
+                onSuccess: async (credentials) => {
+                    activeStopFlow = null;
+                    const [{ appId, appSecret, userOpenId }] = credentials;
+                    const name = endpointName?.trim() || appId;
+                    await ctx.onStatusUpdate('凭据绑定成功，正在写入配置…');
+                    const envKeys = persistQqCredentialsToEnv(name, appId, appSecret);
+                    const template = resolveQqEndpointTemplate(ctx.root);
+                    const operatorId = resolveBindOperatorId(userOpenId, ctx);
+                    const owned = applyBindOwnership(template, operatorId);
+                    resolve({
+                        context: 'qq',
+                        name,
+                        appid: envKeys.appidRef,
+                        secret: envKeys.secretRef,
+                        ...owned,
+                    });
+                },
+                onFailure: async (error) => {
+                    activeStopFlow = null;
+                    reject(error);
+                },
+            }, { source: 'zhin' });
+            activeStopFlow = stopFlow;
+        });
+    }
+    async editEndpoint(name, ctx) {
+        const existing = this.listEndpoints().find((e) => e.name === name);
+        if (!existing) {
+            throw new Error(`配置中不存在 qq/${name}`);
+        }
+        await ctx.onStatusUpdate(`QQ 官方机器人暂不支持在线改凭据，请 /endpoint remove qq ${name} 后重新 /endpoint add qq。`);
+        return existing;
+    }
+    async removeEndpoint(name) {
+        return this.listEndpoints().some((e) => e.name === name);
+    }
+    async startEndpoint(name, ctx) {
+        if (!this.listEndpoints().some((e) => e.name === name)) {
+            throw new Error(`配置中不存在 qq/${name}`);
+        }
+        await ctx.onStatusUpdate(`正在连接 qq/${name}…`);
+    }
+    async stopEndpoint(name) {
+        return this.adapter.endpoints.has(name);
+    }
+}
+export function disposeQqEndpointProvision() {
+    if (activeStopFlow) {
+        activeStopFlow();
+        activeStopFlow = null;
+    }
+}
+//# sourceMappingURL=qq-endpoint-manager.js.map

package/lib/qq-endpoint-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qq-endpoint-manager.js","sourceRoot":"","sources":["../src/qq-endpoint-manager.ts"],"names":[],"mappings":"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"}

package/lib/segment-mapper.d.ts

@@ -0,0 +1,2 @@
+export { toCanonicalSegments, fromCanonicalSegments } from 'zhin.js';
+//# sourceMappingURL=segment-mapper.d.ts.map

package/lib/segment-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-mapper.d.ts","sourceRoot":"","sources":["../src/segment-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC"}

package/lib/segment-mapper.js

@@ -0,0 +1,2 @@
+export { toCanonicalSegments, fromCanonicalSegments } from 'zhin.js';
+//# sourceMappingURL=segment-mapper.js.map

package/lib/segment-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-mapper.js","sourceRoot":"","sources":["../src/segment-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC"}

package/lib/types.d.ts

@@ -31,6 +31,13 @@ export type QQEndpointConfig<T extends ReceiverMode, M extends ApplicationPlatfo
      * - `false`：保持纯文本
      */
     outboundMarkdown?: boolean | "auto";
+    /** 本 Endpoint AI 访问控制（见 docs/advanced/content-moderation.md） */
+    aiAccess?: {
+        mode?: 'open' | 'closed' | 'whitelist';
+        users?: string[];
+        groups?: string[];
+        denyMessage?: string;
+    };
 };
 export interface QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform = ApplicationPlatform> {
     $config: QQEndpointConfig<T, M>;

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,GAAG,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEnE,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,mBAAmB,GAAG,mBAAmB,IACjD,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAC/B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACrC,CAAC;AAEF,MAAM,WAAW,UAAU,CACzB,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IAEnD,OAAO,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,GAAG,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEnE,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,mBAAmB,GAAG,mBAAmB,IACjD,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAC/B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;QACvC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,UAAU,CACzB,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IAEnD,OAAO,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "4.0.2",
+  "version": "5.0.1",
   "description": "Zhin.js adapter for QQ Official Bot",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,28 +34,28 @@
     "directory": "plugins/adapters/qq"
   },
   "dependencies": {
-    "qq-official-bot": "^1.2.2"
+    "qq-official-bot": "^1.2.3"
   },
   "devDependencies": {
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "lucide-react": "^1.17.0",
+    "lucide-react": "^1.22.0",
     "typescript": "^6.0.3",
-    "@zhin.js/client": "2.0.3",
-    "@zhin.js/contract": "1.0.1",
-    "@zhin.js/host-api": "2.0.2",
-    "@zhin.js/cli": "1.0.90",
-    "@zhin.js/host-router": "2.0.0",
-    "zhin.js": "4.0.1",
-    "@zhin.js/logger": "0.1.71"
+    "@zhin.js/cli": "1.0.92",
+    "@zhin.js/client": "2.0.4",
+    "@zhin.js/contract": "1.0.2",
+    "@zhin.js/host-api": "2.0.4",
+    "@zhin.js/host-router": "2.0.2",
+    "@zhin.js/logger": "1.0.73",
+    "zhin.js": "4.1.1"
   },
   "peerDependencies": {
-    "@zhin.js/client": "2.0.3",
-    "@zhin.js/host-api": "2.0.2",
-    "@zhin.js/host-router": "2.0.0",
-    "@zhin.js/logger": "0.1.71",
-    "@zhin.js/contract": "1.0.1",
-    "zhin.js": "4.0.1"
+    "@zhin.js/client": "2.0.4",
+    "@zhin.js/host-api": "2.0.4",
+    "@zhin.js/contract": "1.0.2",
+    "@zhin.js/host-router": "2.0.2",
+    "@zhin.js/logger": "1.0.73",
+    "zhin.js": "4.1.1"
   },
   "peerDependenciesMeta": {
     "@zhin.js/client": {

package/skills/qq/PERMITS.md

@@ -22,4 +22,4 @@
 
 ## 工厂映射
 
-`group_admin` → `guild_admin` · `group_owner` → `guild_owner`
+`scene_admin` → `guild_admin` · `scene_owner` → `guild_owner`

package/src/adapter.ts

@@ -6,13 +6,30 @@ import {
   Plugin,
 } from "zhin.js";
 import type { Router } from "@zhin.js/host-router";
+import type { EndpointManager } from "zhin.js";
 import { QQEndpoint } from "./endpoint.js";
+import { QqEndpointManager } from "./qq-endpoint-manager.js";
 import type { QQEndpointConfig, ReceiverMode } from "./types.js";
+import type { OutboundRichSegmentPolicy } from "zhin.js";
+import { QQ_AI_OUTBOUND_EXTENSIONS } from "zhin.js";
 
 export class QQAdapter extends Adapter<QQEndpoint<ReceiverMode>> {
   static override readonly capabilities = ['inbound', 'outbound'] as const;
+  static override outboundRichSegmentPolicy: OutboundRichSegmentPolicy = {
+    qrcode: 'image',
+    html: 'image',
+    markdown: 'origin',
+  };
+  static override interactivePolicy = 'native' as const;
+  static override aiOutboundCapabilities = {
+    mentions: true,
+    richSegments: ['qrcode', 'html', 'markdown', 'tts'],
+    interactive: 'native' as const,
+  };
+  static override aiOutboundExtensions = QQ_AI_OUTBOUND_EXTENSIONS;
 
   #router?: Router;
+  #endpointManager?: QqEndpointManager;
 
   constructor(plugin: Plugin, router?: Router) {
     super(plugin, "qq", []);
@@ -27,9 +44,16 @@ export class QQAdapter extends Adapter<QQEndpoint<ReceiverMode>> {
     return new QQEndpoint(this, config);
   }
 
-  // ── IGroupManagement 标准群管方法 ──────────────────────────────────
+  override getEndpointManager(): EndpointManager {
+    if (!this.#endpointManager) {
+      this.#endpointManager = new QqEndpointManager(this);
+    }
+    return this.#endpointManager;
+  }
+
+  // ── ISceneManagement 标准群管方法 ──────────────────────────────────
 
-  async kickMember(endpointId: string, sceneId: string, userId: string) {
+  async removeMember(endpointId: string, sceneId: string, userId: string) {
     const endpoint = this.endpoints.get(endpointId);
     if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
     return endpoint.removeGuildMember(sceneId, userId, false);
@@ -41,7 +65,7 @@ export class QQAdapter extends Adapter<QQEndpoint<ReceiverMode>> {
     return endpoint.muteMembers(sceneId, [userId], duration);
   }
 
-  async muteAll(endpointId: string, sceneId: string, enable = true) {
+  async setSceneMuted(endpointId: string, sceneId: string, enable = true) {
     const endpoint = this.endpoints.get(endpointId);
     if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
     return endpoint.muteAll(sceneId, enable ? 600 : 0);
@@ -53,7 +77,7 @@ export class QQAdapter extends Adapter<QQEndpoint<ReceiverMode>> {
     return endpoint.getGuildMembers(sceneId);
   }
 
-  async getGroupInfo(endpointId: string, sceneId: string) {
+  async getSceneInfo(endpointId: string, sceneId: string) {
     const endpoint = this.endpoints.get(endpointId);
     if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
     return endpoint.getGuildInfo(sceneId);

package/src/endpoint.ts

@@ -15,7 +15,7 @@ import {
   SendOptions,
   SendContent,
   segment,
-} from "zhin.js";
+} from 'zhin.js';
 import type { MessageElement } from "zhin.js";
 import { ReceiverMode, type QQEndpointConfig, type ApplicationPlatform } from "./types.js";
 import type { QQAdapter } from "./adapter.js";
@@ -23,9 +23,19 @@ import { normalizeQqInboundWsPayload, type QqWsPacket } from "./inbound-normaliz
 import { normalizeGroupAtPrefix } from "./group-at-normalize.js";
 import { SDK_VERSION, SDK_VERSION_HEADER } from "./sdk-version.js";
 import { applyCustomAuthEndpoints } from "./gateway-config.js";
-import { normalizeOutboundMarkdown } from "./outbound-markdown.js";
+import { normalizeOutboundMarkdown, asOutboundSegments, splitReplyPrefix } from "./outbound-markdown.js";
 import { normalizeOutboundMedia } from "./outbound-media.js";
+import { fromCanonicalSegments, toCanonicalSegments } from "./segment-mapper.js";
+import { enrichCanonicalMentionNames } from "./mention-enrich.js";
+import {
+  buildMixedMediaMessagePayload,
+  buildQqImageUploadPayload,
+  firstImageSegment,
+  shouldSendTextImageMixedMedia,
+} from "./outbound-mixed-media.js";
 import { normalizeQqGuildSenderForPermit } from "./platform-permit.js";
+import { expandKeyboardSegmentsForQq } from "./outbound-keyboard.js";
+import { formatQqActionMessage, type QqActionNoticeEvent } from "./inbound-action.js";
 
 /** 从 qq-official-bot SendResult / 审核回包中解析出站消息 ID */
 export function resolveOutboundMessageId(result: unknown): string {
@@ -172,6 +182,34 @@ export class QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform =
     }
   }
 
+  private async handleQQAction(event: QqActionNoticeEvent): Promise<void> {
+    try {
+      await event.reply(0);
+      const channel = event.notice_type === 'group'
+        ? { id: String(event.group_id), type: 'group' as const }
+        : event.notice_type === 'guild'
+          ? { id: String(event.channel_id), type: 'channel' as const }
+          : { id: String(event.operator_id), type: 'private' as const };
+      const message = formatQqActionMessage(event, {
+        endpointName: this.$config.name,
+        send: async (content) => this.adapter.sendMessage({
+          ...channel,
+          context: 'qq',
+          endpoint: this.$config.name,
+          content,
+        }),
+      });
+      await this.adapter.receiveMessageAwait(message);
+      this.pluginLogger.debug(
+        `qq action ${message.$channel.type}(${message.$channel.id}): ${message.$raw}`,
+      );
+    } catch (err) {
+      this.pluginLogger.warn(
+        `qq format action failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
   private handleGroupNotice(event: string, payload: { group_id?: string; operator_id?: string }): void {
     this.pluginLogger.info(
       `qq notice ${event}: group=${payload.group_id ?? '?'} operator=${payload.operator_id ?? '?'}`,
@@ -182,6 +220,9 @@ export class QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform =
     this.on("message.group", this.handleQQMessage.bind(this));
     this.on("message.guild", this.handleQQMessage.bind(this));
     this.on("message.private", this.handleQQMessage.bind(this));
+    this.on("notice.friend.action", this.handleQQAction.bind(this));
+    this.on("notice.group.action", this.handleQQAction.bind(this));
+    this.on("notice.guild.action", this.handleQQAction.bind(this));
     this.on("notice.group.increase", (e) => this.handleGroupNotice('group.add_robot', e));
     this.on("notice.group.decrease", (e) => this.handleGroupNotice('group.del_robot', e));
     this.on("notice.group.receive_open", (e) => this.handleGroupNotice('group.msg_receive_open', e));
@@ -253,10 +294,18 @@ export class QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform =
     }
   }
 
+  private toWireSendContent(content: SendContent): MessageElement[] {
+    const items = (Array.isArray(content) ? content : [content]).map((item) =>
+      typeof item === "string" ? { type: "text", data: { text: item } } : item as MessageElement,
+    );
+    return fromCanonicalSegments(toCanonicalSegments(items as never));
+  }
+
   $formatMessage(msg: PrivateMessageEvent | GroupMessageEvent) {
     const raw = msg as PrivateMessageEvent & GroupMessageEvent & {
       group_openid?: string;
       author?: { member_openid?: string; user_openid?: string; id?: string; username?: string };
+      mentions?: Array<{ id?: string; member_openid?: string; username?: string; nickname?: string }>;
       __zhin_group_at?: boolean;
     };
 
@@ -283,6 +332,14 @@ export class QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform =
       content = normalizeGroupAtPrefix(content, endpointAtIds, raw.__zhin_group_at === true);
     }
 
+    if (Array.isArray(content)) {
+      content = enrichCanonicalMentionNames(
+        toCanonicalSegments(content),
+        this.adapter,
+        raw.mentions,
+      );
+    }
+
     const result = Message.from(msg, {
       $id: msg.message_id?.toString(),
       $adapter: "qq" as const,
@@ -316,10 +373,20 @@ export class QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform =
   }
 
   async $sendMessage(options: SendOptions): Promise<string> {
-    const content = normalizeOutboundMarkdown(
-      normalizeOutboundMedia(options.content),
-      this.$config.outboundMarkdown,
-    );
+    const expanded = expandKeyboardSegmentsForQq(options.content);
+    const canonicalized = this.toWireSendContent(expanded);
+    const mediaNorm = normalizeOutboundMedia(canonicalized);
+    const markdownMode = this.$config.outboundMarkdown;
+
+    if (
+      (options.type === "group" || options.type === "private")
+      && !options.id.startsWith("direct:")
+      && shouldSendTextImageMixedMedia(mediaNorm, markdownMode)
+    ) {
+      return await this.$sendTextImageMixedMedia(options, mediaNorm);
+    }
+
+    const content = normalizeOutboundMarkdown(mediaNorm, markdownMode);
     switch (options.type) {
       case "private": {
         if (options.id.startsWith("direct:")) {
@@ -348,6 +415,51 @@ export class QQEndpoint<T extends ReceiverMode, M extends ApplicationPlatform =
     }
   }
 
+  /** 内联图 + 文本：上传 file_info 后以 msg_type=7 图文混排发送（二维码等场景） */
+  private async $sendTextImageMixedMedia(
+    options: SendOptions,
+    content: SendContent,
+  ): Promise<string> {
+    const endpointPath = this.resolveV2EndpointPath(options);
+    const { body } = splitReplyPrefix(asOutboundSegments(content));
+    const image = firstImageSegment(body);
+    if (!image) {
+      throw new Error("QQ 图文混排：未找到图片段");
+    }
+
+    const uploadPayload = buildQqImageUploadPayload(image);
+    const { data: uploadResult } = await this.request.post(
+      `${endpointPath}/files`,
+      { ...uploadPayload, srv_send_msg: false },
+    ) as { data: { file_info?: string } };
+
+    if (!uploadResult?.file_info) {
+      throw new Error("QQ 图文混排：图片上传未返回 file_info");
+    }
+
+    const messagePayload = buildMixedMediaMessagePayload(content, uploadResult.file_info);
+    const { data: result } = await this.request.post(
+      `${endpointPath}/messages`,
+      messagePayload,
+    );
+    this.pluginLogger.debug(
+      `${this.$config.name} send mixed-media ${options.type}(${options.id}):${segment.raw(content)}`,
+    );
+    const idPrefix = options.type === "group" ? "group" : "private";
+    return `${idPrefix}-${options.id}:${resolveOutboundMessageId(result)}`;
+  }
+
+  private resolveV2EndpointPath(options: SendOptions): string {
+    switch (options.type) {
+      case "group":
+        return `/v2/groups/${options.id}`;
+      case "private":
+        return `/v2/users/${options.id}`;
+      default:
+        throw new Error(`QQ 图文混排不支持 ${options.type}`);
+    }
+  }
+
   async $recallMessage(id: string): Promise<void> {
     if (!/^(private|group|channel|direct)-([^\:]+):(.+)$/.test(id)) throw new Error(`invalid message id ${id}`);
     const match = id.match(/^(private|group|channel|direct)-([^\:]+):(.+)$/);

package/src/group-at-normalize.ts

@@ -1,10 +1,8 @@
 import type { MessageElement } from "zhin.js";
+import { readMentionSegmentTarget } from "zhin.js";
 
 function segmentAtId(seg: MessageElement): string {
-  if (seg.type !== "at" && seg.type !== "mention") return "";
-  const data = seg.data as Record<string, unknown> | undefined;
-  const raw = data?.user_id ?? data?.qq ?? data?.id;
-  return raw == null ? "" : String(raw);
+  return readMentionSegmentTarget(seg);
 }
 
 function textMentionsEndpoint(text: string, endpointIds: string[]): boolean {

package/src/inbound-action.ts

@@ -0,0 +1,87 @@
+/**
+ * QQ 官方互动事件 → 标准 action 段
+ * @see https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/trans/msg-btn.html
+ */
+import type {
+  FriendActionNoticeEvent,
+  GroupActionNoticeEvent,
+  GuildActionNoticeEvent,
+} from 'qq-official-bot';
+import { Message, type MessageSegment, type SendContent } from 'zhin.js';
+
+export type QqActionNoticeEvent =
+  | FriendActionNoticeEvent
+  | GroupActionNoticeEvent
+  | GuildActionNoticeEvent;
+
+export interface FormatQqActionMessageOptions {
+  endpointName: string;
+  send: (content: SendContent) => Promise<string>;
+}
+
+/** `group-{openid}:{msgId}` → 平台 msg_id */
+export function stripQqOutboundMessageId(storedId: string): string {
+  const match = /^(?:private|group|channel|direct)-[^:]+:(.+)$/.exec(storedId);
+  return match ? match[1]! : storedId;
+}
+
+function prependReply(content: SendContent, msgId: string): MessageSegment[] {
+  const items = Array.isArray(content) ? [...content] : [content];
+  items.unshift({ type: 'reply', data: { id: msgId } });
+  return items as MessageSegment[];
+}
+
+function createQqActionReplyHandler(
+  send: (content: SendContent) => Promise<string>,
+) {
+  return async (content: SendContent, quote: boolean | string = false): Promise<string> => {
+    const outbound = typeof quote === 'string'
+      ? prependReply(content, stripQqOutboundMessageId(quote))
+      : content;
+    return await send(outbound);
+  };
+}
+
+export function formatQqActionMessage(
+  event: QqActionNoticeEvent,
+  options: FormatQqActionMessageOptions,
+): ReturnType<typeof Message.from<QqActionNoticeEvent>> {
+  const resolved = event.data?.resolved;
+  const buttonId = String(resolved?.button_id ?? '');
+  const buttonData = resolved?.button_data != null ? String(resolved.button_data) : '';
+  const payload = buttonData || buttonId;
+  const sourceMessageId = resolved?.message_id != null ? String(resolved.message_id) : undefined;
+
+  let channelType: 'private' | 'group' | 'channel' = 'private';
+  let channelId = String(event.operator_id ?? '');
+
+  if (event.notice_type === 'group') {
+    channelType = 'group';
+    channelId = String(event.group_id);
+  } else if (event.notice_type === 'guild') {
+    channelType = 'channel';
+    channelId = String(event.channel_id);
+  }
+
+  const senderId = String(event.operator_id ?? '');
+
+  return Message.from(event, {
+    $id: event.notice_id ?? event.event_id ?? `action:${Date.now()}`,
+    $adapter: 'qq',
+    $endpoint: options.endpointName,
+    $sender: { id: senderId, name: senderId },
+    $channel: { id: channelId, type: channelType },
+    $content: [{
+      type: 'action',
+      data: {
+        id: buttonId,
+        payload,
+        sourceMessageId,
+      },
+    }],
+    $raw: payload,
+    $timestamp: Date.now(),
+    $recall: async () => {},
+    $reply: createQqActionReplyHandler(options.send),
+  });
+}