@zhin.js/adapter-qq 2.0.10 → 2.0.12

package/src/bot.ts

@@ -7,6 +7,8 @@ import {
   GroupMessageEvent,
 } from "qq-official-bot";
 import path from "path";
+import { formatCompact } from "@zhin.js/logger";
+import { registerFetchRoute, type RouterContext } from "@zhin.js/host-router/router";
 import {
   Bot as ZhinBot,
   Message,
@@ -14,8 +16,15 @@ import {
   SendContent,
   segment,
 } from "zhin.js";
-import type { QQBotConfig, ReceiverMode, ApplicationPlatform } from "./types.js";
+import type { MessageElement } from "zhin.js";
+import { ReceiverMode, type QQBotConfig, 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 { normalizeOutboundMedia } from "./outbound-media.js";
 
 
 export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = ApplicationPlatform>
@@ -37,21 +46,74 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
 
   constructor(public adapter: QQAdapter, config: QQBotConfig<T, M>) {
     if (!config.data_dir) config.data_dir = path.join(process.cwd(), "data");
+    if (config.mode === ReceiverMode.MIDDLEWARE) {
+      const mw = config as QQBotConfig<ReceiverMode.MIDDLEWARE, M> & {
+        platform?: ApplicationPlatform;
+      };
+      if (!mw.platform) {
+        mw.platform = (mw.application ?? "koa") as ApplicationPlatform;
+      }
+    }
     super(config);
     this.$config = config;
+    this.attachSdkVersionHeader();
+    applyCustomAuthEndpoints(this, config, this.pluginLogger);
+  }
+
+  /** 出站 QQ API 请求附带 SDK 版本，便于平台侧日志排查 */
+  private attachSdkVersionHeader(): void {
+    this.request.interceptors.request.use((reqConfig) => {
+      reqConfig.headers[SDK_VERSION_HEADER] = SDK_VERSION;
+      return reqConfig;
+    });
+  }
+
+  /** 归一化 QQ API v2 群聊字段后再交给 qq-official-bot 解析 */
+  dispatchEvent(event: string, wsRes: QqWsPacket): void {
+    this.pluginLogger.debug({
+      op: 'inbound_ws',
+      event,
+      group: String(wsRes.d?.group_openid ?? wsRes.d?.group_id ?? '?'),
+    });
+    if (event === 'GROUP_AT_MESSAGE_CREATE' || event === 'GROUP_MESSAGE_CREATE') {
+      this.pluginLogger.info(
+        `qq inbound ws: ${event} group=${String(wsRes.d?.group_openid ?? wsRes.d?.group_id ?? '?')}`,
+      );
+    }
+    normalizeQqInboundWsPayload(event, wsRes);
+    super.dispatchEvent(event, wsRes);
   }
 
   private handleQQMessage(msg: PrivateMessageEvent | GroupMessageEvent): void {
-    const message = this.$formatMessage(msg);
-    this.adapter.emit("message.receive", message);
-    this.pluginLogger.debug(`${this.$config.name} recv  ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`);
+    try {
+      const message = this.$formatMessage(msg);
+      this.adapter.emit("message.receive", message);
+      this.pluginLogger.debug(
+        `${this.$config.name} recv ${message.$channel.type}(${message.$channel.id}):${segment.raw(message.$content)}`,
+      );
+    } catch (err) {
+      this.pluginLogger.warn(
+        `qq format inbound failed (${msg.message_type}): ${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 ?? '?'}`,
+    );
   }
 
   async $connect(): Promise<void> {
     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.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));
+    this.on("notice.group.receive_close", (e) => this.handleGroupNotice('group.msg_receive_close', e));
     await this.start();
+    this.mountWebhookReceiver();
     this.$connected = true;
     try {
       const self = await this.getSelfInfo();
@@ -72,11 +134,81 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
     this.$connected = false;
   }
 
+  private resolveWebhookPath(): string {
+    const raw = this.$config.webhookPath ?? "/qq/webhook";
+    return raw.startsWith("/") ? raw : `/${raw}`;
+  }
+
+  /**
+   * Webhook 入站：middleware（挂 host-router）或独立 HTTP 端口（qq-official-bot 内置服务）。
+   */
+  private mountWebhookReceiver(): void {
+    const mode = this.$config.mode;
+    if (mode === ReceiverMode.MIDDLEWARE) {
+      const router = this.adapter.getRouter();
+      if (!router) {
+        throw new Error("QQ mode=middleware 需要启用 @zhin.js/host-router 插件");
+      }
+      const webhookPath = this.resolveWebhookPath();
+      const mw = this.middleware as (
+        ctx: RouterContext,
+        next: () => Promise<void>,
+      ) => Promise<unknown>;
+      router.post(webhookPath, async (ctx: RouterContext) => {
+        this.pluginLogger.debug(ctx.body);
+        await mw(ctx, async () => {});
+      });
+      this.pluginLogger.info(formatCompact({
+        op: "webhook",
+        mode: "middleware",
+        path: webhookPath,
+        url: `POST ${webhookPath}`,
+        note: "无 /api 前缀；Host API 才走 /api/*",
+      }));
+      return;
+    }
+    if (mode === ReceiverMode.WEBHOOK) {
+      const cfg = this.$config as QQBotConfig<ReceiverMode.WEBHOOK>;
+      this.pluginLogger.info(formatCompact({
+        op: "webhook",
+        mode: "standalone",
+        port: cfg.port,
+        path: cfg.path,
+        url: `http://127.0.0.1:${cfg.port}${cfg.path}`,
+      }));
+    }
+  }
+
   $formatMessage(msg: PrivateMessageEvent | GroupMessageEvent) {
+    const raw = msg as PrivateMessageEvent & GroupMessageEvent & {
+      group_openid?: string;
+      author?: { member_openid?: string; user_openid?: string; id?: string; username?: string };
+      __zhin_group_at?: boolean;
+    };
+
+    if (msg.message_type === "group") {
+      if (!raw.group_id && raw.group_openid) {
+        raw.group_id = raw.group_openid;
+      }
+      if (!msg.user_id && raw.author) {
+        const uid = raw.author.member_openid ?? raw.author.user_openid ?? raw.author.id;
+        if (uid) msg.user_id = String(uid);
+      }
+    }
+
     let target_id = msg.user_id;
     if (msg.message_type === "guild") target_id = msg.channel_id!;
-    if (msg.message_type === "group") target_id = msg.group_id!;
+    if (msg.message_type === "group") target_id = raw.group_id ?? msg.group_id ?? "";
     if (msg.sub_type === "direct") target_id = `direct:${msg.guild_id}`;
+
+    let content = msg.message;
+    if (msg.message_type === "group" && Array.isArray(content)) {
+      const botAtIds = [this.$platformUserId, this.$config.appid]
+        .filter((id): id is string => Boolean(id))
+        .map(String);
+      content = normalizeGroupAtPrefix(content, botAtIds, raw.__zhin_group_at === true);
+    }
+
     const result = Message.from(msg, {
       $id: msg.message_id?.toString(),
       $adapter: "qq" as const,
@@ -89,7 +221,7 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
         id: target_id,
         type: msg.message_type === "guild" ? "channel" : msg.message_type,
       },
-      $content: msg.message,
+      $content: content,
       $raw: msg.raw_message,
       $timestamp: Date.now(),
       $recall: async () => {
@@ -110,27 +242,31 @@ export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = Appli
   }
 
   async $sendMessage(options: SendOptions): Promise<string> {
+    const content = normalizeOutboundMarkdown(
+      normalizeOutboundMedia(options.content),
+      this.$config.outboundMarkdown,
+    );
     switch (options.type) {
       case "private": {
         if (options.id.startsWith("direct:")) {
           const id = options.id.replace("direct:", "");
-          const result = await this.sendDirectMessage(id, options.content);
-          this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(options.content)}`);
+          const result = await this.sendDirectMessage(id, content);
+          this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
           return `direct-${options.id}:${result.id.toString()}`;
         } else {
-          const result = await this.sendPrivateMessage(options.id, options.content);
-          this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(options.content)}`);
+          const result = await this.sendPrivateMessage(options.id, content);
+          this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
           return `private-${options.id}:${result.id.toString()}`;
         }
       }
       case "group": {
-        const result = await this.sendGroupMessage(options.id, options.content);
-        this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(options.content)}`);
+        const result = await this.sendGroupMessage(options.id, content);
+        this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
         return `group-${options.id}:${result.id.toString()}`;
       }
       case "channel": {
-        const result = await this.sendGuildMessage(options.id, options.content);
-        this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(options.content)}`);
+        const result = await this.sendGuildMessage(options.id, content);
+        this.pluginLogger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(content)}`);
         return `channel-${options.id}:${result.id.toString()}`;
       }
       default:

package/src/gateway-config.ts

@@ -0,0 +1,48 @@
+import type { Logger } from "@zhin.js/logger";
+import { formatCompact } from "@zhin.js/logger";
+import type { Bot } from "qq-official-bot";
+import { ReceiverMode } from "qq-official-bot";
+import type { QQBotConfig } 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(
+  bot: Bot,
+  config: Pick<QQBotConfig<ReceiverMode>, "mode" | "accessTokenUrl" | "gatewayUrl">,
+  logger: Logger,
+): void {
+  const { accessTokenUrl, gatewayUrl, mode } = config;
+  if (!accessTokenUrl && !gatewayUrl) return;
+
+  if (mode !== ReceiverMode.WEBSOCKET) {
+    const session = bot.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

@@ -0,0 +1,78 @@
+import 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);
+}
+
+function textMentionsBot(text: string, botIds: string[]): boolean {
+  for (const id of botIds) {
+    const re = new RegExp(`@${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+    if (re.test(text)) return true;
+  }
+  return false;
+}
+
+function stripInlineAtBot(text: string, botIds: string[]): string {
+  let result = text;
+  for (const id of botIds) {
+    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[],
+  botAtIds: string[],
+  forceAt: boolean,
+): MessageElement[] {
+  const ids = [...new Set(botAtIds.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 (textMentionsBot(raw, ids)) mentioned = true;
+      const stripped = stripInlineAtBot(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-normalize.ts

@@ -0,0 +1,57 @@
+/**
+ * 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/index.ts

@@ -3,6 +3,7 @@
  */
 import path from "node:path";
 import { usePlugin, type Plugin, type IGroupManagement, createGroupManagementTools, 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";
 
@@ -10,6 +11,7 @@ declare module "zhin.js" {
   namespace Plugin {
     interface Contexts {
       web: PageManager;
+      router: Router;
     }
   }
 }
@@ -27,17 +29,19 @@ export { QQAdapter } from "./adapter.js";
 const plugin = usePlugin();
 const { provide, useContext } = plugin;
 
-provide({
-  name: "qq",
-  description: "QQ Official Bot Adapter",
-  mounted: async (p: Plugin) => {
-    const adapter = new QQAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: QQAdapter) => {
-    await adapter.stop();
-  },
+useContext("router", (router: Router) => {
+  provide({
+    name: "qq",
+    description: "QQ Official Bot Adapter",
+    mounted: async (p: Plugin) => {
+      const adapter = new QQAdapter(p, router);
+      await adapter.start();
+      return adapter;
+    },
+    dispose: async (adapter: QQAdapter) => {
+      await adapter.stop();
+    },
+  });
 });
 
 useContext('tool', 'qq', (toolService: ToolFeature, qq: QQAdapter) => {

package/src/outbound-markdown.ts

@@ -0,0 +1,93 @@
+/**
+ * 将 AI 出站纯文本段合并为 QQ Markdown 消息（msg_type=2）。
+ * 官方已开放全量 Markdown，避免 **bold** 等语法以纯文本展示。
+ */
+import { segment, type MessageElement, type MessageSegment, type SendContent } from "zhin.js";
+
+function isMessageSegment(seg: MessageElement): seg is MessageSegment {
+  return typeof seg.type === "string";
+}
+
+export type OutboundMarkdownMode = boolean | "auto";
+
+/** 常见 AI Markdown 输出特征（auto 模式） */
+const MARKDOWN_HINT =
+  /(?:\*\*|__|`|\[.+\]\(.+\)|^#{1,6}\s|^>\s|^\s*[-*+]\s|^```|\|.+\|)/m;
+
+const BODY_RICH_TYPES = new Set([
+  "image",
+  "audio",
+  "video",
+  "file",
+  "markdown",
+  "ark",
+  "embed",
+  "keyboard",
+  "button",
+  "face",
+]);
+
+function textSegment(text: string): MessageSegment {
+  return { type: "text", data: { text } };
+}
+
+function asSegments(content: SendContent): MessageSegment[] {
+  if (typeof content === "string") return [textSegment(content)];
+  if (!Array.isArray(content)) {
+    return isMessageSegment(content) ? [content] : [];
+  }
+  return content.flatMap((item) =>
+    typeof item === "string" ? [textSegment(item)] : isMessageSegment(item) ? [item] : [],
+  );
+}
+
+function textFromSegment(seg: MessageSegment): string {
+  if (seg.type !== "text") return "";
+  return seg.data.text ?? seg.data.content ?? "";
+}
+
+function shouldConvert(mode: OutboundMarkdownMode | undefined, bodyText: string): boolean {
+  if (mode === false) return false;
+  if (mode === true) return bodyText.trim().length > 0;
+  return MARKDOWN_HINT.test(bodyText);
+}
+
+/**
+ * 出站归一化：保留 leading `reply`，将连续 text 合并为单条 markdown 段。
+ * 含图片/文件等富媒体时原样返回，避免破坏分条发送。
+ */
+export function normalizeOutboundMarkdown(
+  content: SendContent,
+  mode: OutboundMarkdownMode | undefined = "auto",
+): SendContent {
+  const segments = asSegments(content);
+  if (segments.length === 0) return content;
+
+  const prefix: MessageSegment[] = [];
+  let i = 0;
+  while (i < segments.length && segments[i].type === "reply") {
+    prefix.push(segments[i]);
+    i++;
+  }
+
+  const body = segments.slice(i);
+  if (body.length === 0) return content;
+
+  if (body.some((seg) => BODY_RICH_TYPES.has(seg.type))) {
+    return content;
+  }
+
+  if (body.some((seg) => seg.type !== "text" && seg.type !== "at")) {
+    return content;
+  }
+
+  const merged = body
+    .map((seg) => (seg.type === "at"
+      ? `<@${String(seg.data.user_id ?? "")}>`
+      : textFromSegment(seg)))
+    .join("");
+
+  if (!shouldConvert(mode, merged)) return content;
+
+  return [...prefix, segment("markdown", { content: merged })];
+}

package/src/outbound-media.ts

@@ -0,0 +1,57 @@
+/**
+ * QQ 官方出站媒体归一化。
+ * qq-official-bot 的 formatMediaData 对 data.url 直接当远程 URL 上传；
+ * base64:// / data:...;base64 须走 data.file 才会解析为 file_data。
+ */
+import type { MessageElement, MessageSegment, SendContent } from "zhin.js";
+
+const MEDIA_TYPES = new Set(["image", "audio", "video", "file"]);
+
+function isMessageSegment(seg: MessageElement): seg is MessageSegment {
+  return typeof seg.type === "string";
+}
+
+function isRemoteUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function isInlineBase64(value: string): boolean {
+  return value.startsWith("base64://") || /^data:[^/]+\/[^;]+;base64,/i.test(value);
+}
+
+function resolveMediaFile(data: Record<string, unknown>): string | undefined {
+  const url = typeof data.url === "string" ? data.url : undefined;
+  const file = typeof data.file === "string" ? data.file : undefined;
+  const base64 = typeof data.base64 === "string" ? data.base64 : undefined;
+
+  if (file && !isRemoteUrl(file)) return file;
+  if (url && isInlineBase64(url)) return url;
+  if (url && !isRemoteUrl(url) && (url.startsWith("file://") || url.startsWith("/"))) return url;
+  if (base64) return base64.startsWith("base64://") ? base64 : `base64://${base64}`;
+  return undefined;
+}
+
+function normalizeMediaSegment(seg: MessageSegment): MessageSegment {
+  if (!MEDIA_TYPES.has(seg.type)) return seg;
+
+  const data = { ...seg.data } as Record<string, unknown>;
+  const file = resolveMediaFile(data);
+  if (!file) return seg;
+
+  delete data.url;
+  delete data.base64;
+  data.file = file;
+  return { type: seg.type, data } as MessageSegment;
+}
+
+/** 将 Zhin 出站 image/base64 段转为 qq-official-bot 可识别的 file 字段 */
+export function normalizeOutboundMedia(content: SendContent): SendContent {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) {
+    return isMessageSegment(content) ? normalizeMediaSegment(content) : content;
+  }
+  return content.map((item) => {
+    if (typeof item === "string") return item;
+    return isMessageSegment(item) ? normalizeMediaSegment(item) : item;
+  });
+}

package/src/sdk-version.ts

@@ -0,0 +1,21 @@
+import { createRequire } from "node:module";
+import adapterPkg from "../package.json" with { type: "json" };
+
+const require = createRequire(import.meta.url);
+
+function readDepVersion(dep: string): string {
+  try {
+    return (require(`${dep}/package.json`) as { version: string }).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/** HTTP header name for outbound QQ API requests. */
+export const SDK_VERSION_HEADER = "x-sdk-version";
+
+/**
+ * Composite SDK identity: Zhin adapter + underlying qq-official-bot.
+ * Example: `zhin-adapter-qq/v2.0.11+qq-official-bot/v1.2.1`
+ */
+export const SDK_VERSION = `zhin-adapter-qq/v${adapterPkg.version}+qq-official-bot/v${readDepVersion("qq-official-bot")}`;

package/src/types.ts

@@ -14,6 +14,28 @@ export type QQBotConfig<
   context: "qq";
   name: string;
   data_dir?: string;
+  /**
+   * middleware 模式：挂在 host-router 的回调路径（默认 `/qq/webhook`，完整 URL 为 `{host}:8086/qq/webhook`，无 `/api` 前缀）。
+   * webhook 独立端口模式：使用 qq-official-bot 的 `path` 字段。
+   */
+  webhookPath?: string;
+  /**
+   * 自定义 access token 接口（完整 URL）。
+   * 默认 `https://bots.qq.com/app/getAppAccessToken`；代理或私有部署时可覆盖。
+   */
+  accessTokenUrl?: string;
+  /**
+   * 自定义 gateway 接口（完整 URL 或相对路径，如 `/gateway/bot`）。
+   * 响应中的 `url` 为 WebSocket 地址；**仅 `mode: websocket` 入站时使用**。
+   */
+  gatewayUrl?: string;
+  /**
+   * AI 出站是否转为 QQ Markdown（`msg_type=2`）。
+   * - `auto`（默认）：正文含 Markdown 语法时转换
+   * - `true`：纯文本也走 Markdown
+   * - `false`：保持纯文本
+   */
+  outboundMarkdown?: boolean | "auto";
 };
 
 export interface QQBot<