@zhin.js/adapter-qq 5.0.0 → 5.0.1

package/src/endpoint.ts

@@ -14,7 +14,8 @@ import {
   Message,
   SendOptions,
   SendContent,
-  segment,} from 'zhin.js';
+  segment,
+} from 'zhin.js';
 import type { MessageElement } from "zhin.js";
 import { ReceiverMode, type QQEndpointConfig, type ApplicationPlatform } from "./types.js";
 import type { QQAdapter } from "./adapter.js";
@@ -22,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 {
@@ -171,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 ?? '?'}`,
@@ -181,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));
@@ -252,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;
     };
 
@@ -282,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,
@@ -315,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:")) {
@@ -347,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),
+  });
+}

package/src/index.ts

@@ -2,7 +2,7 @@
  * QQ 官方适配器入口：类型扩展、导出、注册
  */
 import path from "node:path";
-import { usePlugin, type Plugin, type IGroupManagement, createGroupManagementTools, type ToolFeature } from "zhin.js";
+import { usePlugin, type Plugin, type ISceneManagement, createSceneManagementTools, type ToolFeature } from "zhin.js";
 import type { Router } from "@zhin.js/host-router";
 import { QQAdapter } from "./adapter.js";
 import { PageManager } from "@zhin.js/host-api";
@@ -56,12 +56,12 @@ useContext("router", (router: Router) => {
 useContext('tool', 'qq', (toolService: ToolFeature, qq: QQAdapter) => {
   const disposers: (() => void)[] = [];
   disposers.push(registerQqPlatformPermitChecker());
-  const groupTools = createGroupManagementTools(
-    qq as unknown as IGroupManagement,
+  const sceneTools = createSceneManagementTools(
+    qq as unknown as ISceneManagement,
     'qq',
     { permitResolver: qqGuildPermitResolver, registerChecker: false },
   );
-  disposers.push(...groupTools.map(t => toolService.addTool(t, plugin.name)));
+  disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
 
   // 获取频道列表
   disposers.push(toolService.addTool({

package/src/mention-enrich.ts

@@ -0,0 +1,71 @@
+import type { Segment } from 'zhin.js';
+import type { QQAdapter } from './adapter.js';
+
+type MentionWire = {
+  id?: string;
+  member_openid?: string;
+  username?: string;
+  nickname?: string;
+};
+
+type QQEndpointLike = {
+  $id: string;
+  $platformUserId?: string;
+  $config: { name?: string; appid?: string; nickname?: string };
+};
+
+function mentionWireId(row: MentionWire): string {
+  return String(row.id ?? row.member_openid ?? '').trim();
+}
+
+function mentionWireName(row: MentionWire): string | undefined {
+  const name = row.username ?? row.nickname;
+  return typeof name === 'string' && name.trim() ? name.trim() : undefined;
+}
+
+function endpointLookupIds(endpoint: QQEndpointLike): string[] {
+  const cfg = endpoint.$config;
+  return [
+    endpoint.$platformUserId,
+    cfg.appid,
+    cfg.name,
+    endpoint.$id,
+  ].filter((id): id is string => Boolean(id)).map(String);
+}
+
+function resolveEndpointDisplayName(endpoint: QQEndpointLike): string | undefined {
+  const cfg = endpoint.$config;
+  return cfg.nickname?.trim() || cfg.name?.trim() || endpoint.$id;
+}
+
+/** 为 canonical mention 段补齐展示名（平台 payload / endpoint 配置）。 */
+export function enrichCanonicalMentionNames(
+  segments: Segment[],
+  adapter: QQAdapter,
+  wireMentions?: MentionWire[],
+): Segment[] {
+  const nameById = new Map<string, string>();
+  for (const row of wireMentions ?? []) {
+    const id = mentionWireId(row);
+    const name = mentionWireName(row);
+    if (id && name) nameById.set(id, name);
+  }
+
+  for (const endpoint of adapter.endpoints.values()) {
+    const display = resolveEndpointDisplayName(endpoint);
+    if (!display) continue;
+    for (const id of endpointLookupIds(endpoint)) {
+      if (!nameById.has(id)) nameById.set(id, display);
+    }
+  }
+
+  return segments.map((seg) => {
+    if (seg.type !== 'mention') return seg;
+    const data = seg.data as { target?: string; name?: string };
+    const target = String(data.target ?? '').trim();
+    if (!target || data.name) return seg;
+    const name = nameById.get(target);
+    if (!name) return seg;
+    return { ...seg, data: { target, name } };
+  });
+}

package/src/outbound-keyboard.ts

@@ -0,0 +1,118 @@
+/**
+ * 将 core keyboard 段转为 qq-official-bot 可识别的 button / markdown 段。
+ * @see https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/trans/msg-btn.html
+ */
+import type { ButtonData, KeyboardSegmentData } from "zhin.js";
+import type { MessageSegment, SendContent } from "zhin.js";
+import { isKeyboardSegment, KeyboardSegment } from "zhin.js";
+
+function asKeyboardData(item: unknown): KeyboardSegmentData | null {
+  if (item instanceof KeyboardSegment) return item.data;
+  if (item != null && typeof item === "object" && isKeyboardSegment(item as MessageSegment)) {
+    return (item as MessageSegment).data as KeyboardSegmentData;
+  }
+  return null;
+}
+
+type QqButton = {
+  id: string;
+  render_data: { label: string; visited_label: string; style: number };
+  action: {
+    type: number;
+    permission: { type: number };
+    data: string;
+    click_limit: number;
+    unsupport_tips: string;
+    enter?: boolean;
+    reply?: boolean;
+  };
+};
+
+function coreButtonToQq(btn: ButtonData): QqButton {
+  const isCommand = btn.mode === 'command';
+  const action: QqButton['action'] = {
+    type: isCommand ? 2 : 1,
+    permission: { type: 2 },
+    data: btn.payload,
+    click_limit: btn.disabled ? 0 : 10,
+    unsupport_tips: btn.disabled ? "该按钮不可用" : "",
+  };
+  if (isCommand) {
+    if (btn.command?.enter != null) action.enter = btn.command.enter;
+    if (btn.command?.reply != null) action.reply = btn.command.reply;
+  }
+  return {
+    id: btn.id,
+    render_data: {
+      label: btn.label,
+      visited_label: btn.label,
+      style: 0,
+    },
+    action,
+  };
+}
+
+function keyboardDataToQqSegments(data: KeyboardSegmentData): MessageSegment[] {
+  const out: MessageSegment[] = [];
+  for (const row of data.rows) {
+    out.push({
+      type: "button",
+      data: {
+        buttons: row.map(coreButtonToQq),
+      },
+    } as MessageSegment);
+  }
+  return out;
+}
+
+/** QQ 官方出站：keyboard → button 行；前置 text 合并为 markdown（按钮消息需带 markdown） */
+export function expandKeyboardSegmentsForQq(content: SendContent): SendContent {
+  const items = Array.isArray(content) ? content : [content];
+  const out: (string | MessageSegment)[] = [];
+  const textParts: string[] = [];
+
+  for (const item of items) {
+    if (typeof item === "string") {
+      textParts.push(item);
+      continue;
+    }
+    const keyboardData = asKeyboardData(item);
+    if (keyboardData) {
+      if (textParts.length > 0) {
+        out.push({
+          type: "markdown",
+          data: { content: textParts.join("\n") },
+        } as MessageSegment);
+        textParts.length = 0;
+      }
+      out.push(...keyboardDataToQqSegments(keyboardData));
+      continue;
+    }
+
+    if (item.type === "text") {
+      const t = item.data?.text ?? item.data?.content ?? "";
+      if (t) textParts.push(String(t));
+      continue;
+    }
+
+    if (textParts.length > 0) {
+      out.push({
+        type: "markdown",
+        data: { content: textParts.join("\n") },
+      } as MessageSegment);
+      textParts.length = 0;
+    }
+    out.push(item as MessageSegment);
+  }
+
+  if (textParts.length > 0) {
+    out.push({
+      type: "markdown",
+      data: { content: textParts.join("\n") },
+    } as MessageSegment);
+  }
+
+  if (out.length === 0) return { type: "text", data: { text: "" } };
+  if (out.length === 1) return out[0]!;
+  return out;
+}