@zhin.js/adapter-qq 5.0.1 → 5.0.3

package/src/adapter.ts

@@ -1,101 +0,0 @@
-/**
- * QQ 官方适配器
- */
-import {
-  Adapter,
-  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", []);
-    this.#router = router;
-  }
-
-  getRouter(): Router | undefined {
-    return this.#router;
-  }
-
-  createEndpoint(config: QQEndpointConfig<ReceiverMode>): QQEndpoint<ReceiverMode> {
-    return new QQEndpoint(this, config);
-  }
-
-  override getEndpointManager(): EndpointManager {
-    if (!this.#endpointManager) {
-      this.#endpointManager = new QqEndpointManager(this);
-    }
-    return this.#endpointManager;
-  }
-
-  // ── ISceneManagement 标准群管方法 ──────────────────────────────────
-
-  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);
-  }
-
-  async muteMember(endpointId: string, sceneId: string, userId: string, duration = 600) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
-    return endpoint.muteMembers(sceneId, [userId], duration);
-  }
-
-  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);
-  }
-
-  async listMembers(endpointId: string, sceneId: string) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
-    return endpoint.getGuildMembers(sceneId);
-  }
-
-  async getSceneInfo(endpointId: string, sceneId: string) {
-    const endpoint = this.endpoints.get(endpointId);
-    if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`);
-    return endpoint.getGuildInfo(sceneId);
-  }
-
-  // ── 生命周期 ───────────────────────────────────────────────────────
-
-  async start(): Promise<void> {
-    if (!this.#router) {
-      this.#router = (this.plugin.inject as (key: string) => Router | undefined)("router");
-    }
-    (this.plugin.useContext as (key: string, fn: (router: Router) => void) => void)(
-      "router",
-      (router) => {
-        this.#router = router;
-      },
-    );
-    await super.start();
-  }
-
-}

package/src/gateway-config.ts

@@ -1,48 +0,0 @@
-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 type { QQEndpointConfig } from "./types.js";
-
-/** qq-official-bot 默认 token 接口 */
-export const DEFAULT_ACCESS_TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
-/** qq-official-bot 默认 gateway 路径（相对 API baseURL） */
-export const DEFAULT_GATEWAY_URL = "/gateway/bot";
-
-type AuthManagerSession = {
-  authManager: {
-    config: {
-      accessTokenUrl?: string;
-      gatewayUrl?: string;
-    };
-  };
-};
-
-/**
- * 将自定义 gateway / token 地址注入 SDK Auth。
- * SDK 仅在 websocket 模式自动读取配置；middleware / webhook 需在此补丁。
- */
-export function applyCustomAuthEndpoints(
-  endpoint: QQOfficialBot,
-  config: Pick<QQEndpointConfig<ReceiverMode>, "mode" | "accessTokenUrl" | "gatewayUrl">,
-  logger: Logger,
-): void {
-  const { accessTokenUrl, gatewayUrl, mode } = config;
-  if (!accessTokenUrl && !gatewayUrl) return;
-
-  if (mode !== ReceiverMode.WEBSOCKET) {
-    const session = endpoint.sessionManager as unknown as AuthManagerSession;
-    if (accessTokenUrl) session.authManager.config.accessTokenUrl = accessTokenUrl;
-    if (gatewayUrl) session.authManager.config.gatewayUrl = gatewayUrl;
-  }
-
-  logger.info(formatCompact({
-    op: "qq_gateway",
-    mode,
-    accessTokenUrl: accessTokenUrl ?? DEFAULT_ACCESS_TOKEN_URL,
-    gatewayUrl: gatewayUrl ?? DEFAULT_GATEWAY_URL,
-    note: mode === ReceiverMode.WEBSOCKET
-      ? "websocket 入站使用 gatewayUrl"
-      : "middleware/webhook 仅 accessTokenUrl 生效",
-  }));
-}

package/src/group-at-normalize.ts

@@ -1,76 +0,0 @@
-import type { MessageElement } from "zhin.js";
-import { readMentionSegmentTarget } from "zhin.js";
-
-function segmentAtId(seg: MessageElement): string {
-  return readMentionSegmentTarget(seg);
-}
-
-function textMentionsEndpoint(text: string, endpointIds: string[]): boolean {
-  for (const id of endpointIds) {
-    const re = new RegExp(`@${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
-    if (re.test(text)) return true;
-  }
-  return false;
-}
-
-function stripInlineAtEndpoint(text: string, endpointIds: string[]): string {
-  let result = text;
-  for (const id of endpointIds) {
-    if (!id) continue;
-    const re = new RegExp(`^@${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
-    result = result.replace(re, "");
-  }
-  return result.trimStart();
-}
-
-/**
- * 统一 QQ 群 @ 机器人前缀：
- * - 去掉正文前的 at 段与内联 @，使命令/文本从首段开始匹配
- * - 若曾 @ 机器人，在末尾追加规范 at 段，供 AI @ 触发器识别
- */
-export function normalizeGroupAtPrefix(
-  content: MessageElement[],
-  endpointAtIds: string[],
-  forceAt: boolean,
-): MessageElement[] {
-  const ids = [...new Set(endpointAtIds.map(String).filter(Boolean))];
-  if (!ids.length || !Array.isArray(content)) return content;
-
-  let mentioned = forceAt;
-  const body: MessageElement[] = [];
-
-  for (const seg of content) {
-    if (seg.type === "at" || seg.type === "mention") {
-      const uid = segmentAtId(seg);
-      if (uid && ids.includes(uid)) {
-        mentioned = true;
-        continue;
-      }
-      body.push(seg);
-      continue;
-    }
-    if (seg.type === "text" && seg.data && typeof seg.data === "object") {
-      const raw = String((seg.data as { text?: string }).text ?? "");
-      if (textMentionsEndpoint(raw, ids)) mentioned = true;
-      const stripped = stripInlineAtEndpoint(raw, ids);
-      if (stripped) {
-        body.push({ ...seg, data: { ...(seg.data as object), text: stripped } });
-      }
-      continue;
-    }
-    body.push(seg);
-  }
-
-  while (body.length > 0 && body[0]?.type === "text") {
-    const t = String((body[0].data as { text?: string })?.text ?? "").trim();
-    if (t) break;
-    body.shift();
-  }
-
-  if (mentioned) {
-    const canonicalId = ids[0]!;
-    body.push({ type: "at", data: { qq: canonicalId, id: canonicalId } });
-  }
-
-  return body.length ? body : content;
-}

package/src/inbound-action.ts

@@ -1,87 +0,0 @@
-/**
- * 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/inbound-normalize.ts

@@ -1,57 +0,0 @@
-/**
- * QQ 官方 API v2 入站 WebSocket payload 归一化（group_openid → group_id 等）。
- * qq-official-bot 解析层仍按旧字段名取值，未归一化时群 @ 可能解析失败并被 SDK 静默丢弃。
- */
-
-export type QqWsPacket = {
-  d?: Record<string, unknown>;
-  id?: string;
-  t?: string;
-};
-
-const GROUP_MESSAGE_EVENTS = new Set([
-  'GROUP_AT_MESSAGE_CREATE',
-  'GROUP_MESSAGE_CREATE',
-]);
-
-export function normalizeQqInboundWsPayload(event: string, packet: QqWsPacket): void {
-  const d = packet.d;
-  if (!d || typeof d !== 'object') return;
-
-  if (GROUP_MESSAGE_EVENTS.has(event)) {
-    if (!d.group_id && typeof d.group_openid === 'string') {
-      d.group_id = d.group_openid;
-    }
-
-    const author = d.author;
-    if (author && typeof author === 'object') {
-      const a = author as Record<string, unknown>;
-      if (!a.id) {
-        a.id = a.member_openid ?? a.user_openid ?? a.id;
-      }
-      if (!a.username && !a.user_name) {
-        a.username = a.member_openid ?? a.user_openid ?? 'unknown';
-      }
-    }
-
-    if (!Array.isArray(d.mentions) && typeof d.content === 'string') {
-      const mentions: Array<{ id: string }> = [];
-      const re = /<@!?(\d+)>/g;
-      let m: RegExpExecArray | null;
-      while ((m = re.exec(d.content))) {
-        mentions.push({ id: m[1]! });
-      }
-      if (mentions.length) d.mentions = mentions;
-    }
-
-    if (Array.isArray(d.attachments)) {
-      for (const att of d.attachments) {
-        if (att && typeof att === 'object' && (att as Record<string, unknown>).url == null) {
-          (att as Record<string, unknown>).url = '';
-        }
-      }
-    }
-
-    d.__zhin_group_at = event === 'GROUP_AT_MESSAGE_CREATE';
-  }
-}

package/src/mention-enrich.ts

@@ -1,71 +0,0 @@
-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

@@ -1,118 +0,0 @@
-/**
- * 将 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;
-}