@zhin.js/adapter-qq 5.0.0 → 5.0.2

package/src/endpoint.ts

@@ -9,22 +9,27 @@ import {
 import path from "path";
 import { formatCompact } from "@zhin.js/logger";
 import { registerFetchRoute, type RouterContext } from "@zhin.js/host-router/router";
-import {
-  Endpoint,
-  Message,
-  SendOptions,
-  SendContent,
-  segment,} from 'zhin.js';
-import type { MessageElement } from "zhin.js";
+import { Endpoint, Message, SendOptions, SendContent, segment, type MessageElement } from 'zhin.js';
+
 import { ReceiverMode, type QQEndpointConfig, type ApplicationPlatform } from "./types.js";
 import type { QQAdapter } from "./adapter.js";
 import { normalizeQqInboundWsPayload, type QqWsPacket } from "./inbound-normalize.js";
 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 +176,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 +214,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 +288,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 +326,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 +367,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 +409,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/gateway-config.ts

@@ -1,7 +1,7 @@
-import type { Logger } from "@zhin.js/logger";
-import { formatCompact } from "@zhin.js/logger";
-import type { Bot as QQOfficialBot } from "qq-official-bot";
-import { ReceiverMode } from "qq-official-bot";
+import { formatCompact, type Logger } from '@zhin.js/logger';
+
+import { ReceiverMode, type Bot as QQOfficialBot } from 'qq-official-bot';
+
 import type { QQEndpointConfig } from "./types.js";
 
 /** qq-official-bot 默认 token 接口 */
@@ -36,7 +36,7 @@ export function applyCustomAuthEndpoints(
     if (gatewayUrl) session.authManager.config.gatewayUrl = gatewayUrl;
   }
 
-  logger.info(formatCompact({
+  logger.debug(formatCompact({
     op: "qq_gateway",
     mode,
     accessTokenUrl: accessTokenUrl ?? DEFAULT_ACCESS_TOKEN_URL,

package/src/group-at-normalize.ts

@@ -1,10 +1,7 @@
-import type { MessageElement } from "zhin.js";
+import { readMentionSegmentTarget, type MessageElement } 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,16 +2,16 @@
  * 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";
 import {
-  platformPermit,
   qqGuildPermitResolver,
   registerQqPlatformPermitChecker,
 } from "./platform-permit.js";
 import { disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
+import { setQqAgentDeps } from "./qq-agent-deps.js";
 
 declare module "zhin.js" {
   namespace Plugin {
@@ -56,203 +56,20 @@ 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,
+  setQqAgentDeps({
+    getEndpoint: (endpointId) => {
+      const endpoint = qq.endpoints.get(endpointId);
+      if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
+      return endpoint;
+    },
+    getAdapter: () => qq,
+  });
+  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(toolService.addTool({
-    name: 'qq_list_guilds',
-    description: '获取 QQ 频道列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-      },
-      required: ['endpoint_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const guilds = await endpoint.getGuilds();
-      return { guilds, count: guilds.length };
-    },
-  }, plugin.name));
-
-  // 获取子频道列表
-  disposers.push(toolService.addTool({
-    name: 'qq_list_channels',
-    description: '获取 QQ 频道下的子频道列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-      },
-      required: ['endpoint_id', 'guild_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('manage_channels')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const channels = await endpoint.getChannels(args.guild_id);
-      return { channels, count: channels.length };
-    },
-  }, plugin.name));
-
-  // 获取角色列表
-  disposers.push(toolService.addTool({
-    name: 'qq_list_roles',
-    description: '获取 QQ 频道角色列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-      },
-      required: ['endpoint_id', 'guild_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('manage_roles')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const roles = await endpoint.getGuildRoles(args.guild_id);
-      return { roles, count: roles.length };
-    },
-  }, plugin.name));
-
-  // 创建角色
-  disposers.push(toolService.addTool({
-    name: 'qq_create_role',
-    description: '创建 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        name: { type: 'string', description: '角色名称' },
-        color: { type: 'number', description: '颜色（RGB 十进制数值）' },
-      },
-      required: ['endpoint_id', 'guild_id', 'name'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('guild_owner')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const role = await endpoint.createGuildRole(args.guild_id, args.name, args.color);
-      return { success: !!role, role, message: role ? `角色 "${args.name}" 创建成功` : '创建失败' };
-    },
-  }, plugin.name));
-
-  // 添加角色
-  disposers.push(toolService.addTool({
-    name: 'qq_add_role',
-    description: '给成员添加 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['endpoint_id', 'guild_id', 'channel_id', 'user_id', 'role_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('manage_roles')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const success = await endpoint.addMemberRole(args.guild_id, args.channel_id, args.user_id, args.role_id);
-      return { success, message: success ? '已给成员添加角色' : '操作失败' };
-    },
-  }, plugin.name));
-
-  // 移除角色
-  disposers.push(toolService.addTool({
-    name: 'qq_remove_role',
-    description: '移除成员的 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['endpoint_id', 'guild_id', 'channel_id', 'user_id', 'role_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('manage_roles')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const success = await endpoint.removeMemberRole(args.guild_id, args.channel_id, args.user_id, args.role_id);
-      return { success, message: success ? '已移除成员的角色' : '操作失败' };
-    },
-  }, plugin.name));
-
-  // 子频道详情
-  disposers.push(toolService.addTool({
-    name: 'qq_channel_info',
-    description: '获取 QQ 频道中指定子频道的详细信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-      },
-      required: ['endpoint_id', 'channel_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('guild_admin')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const info = await endpoint.getChannelInfo(args.channel_id);
-      return info;
-    },
-  }, plugin.name));
-
-  // 单成员详情
-  disposers.push(toolService.addTool({
-    name: 'qq_member_detail',
-    description: '获取 QQ 频道中指定成员的详细信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-      },
-      required: ['endpoint_id', 'guild_id', 'user_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('guild_admin')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const member = await endpoint.getGuildMember(args.guild_id, args.user_id);
-      return member;
-    },
-  }, plugin.name));
+  disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
 
   return () => disposers.forEach(d => d());
 });

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 } };
+  });
+}