@zhin.js/adapter-qq 2.0.11 → 3.0.0

package/src/adapter.ts

@@ -5,12 +5,20 @@ import {
   Adapter,
   Plugin,
 } from "zhin.js";
+import type { Router } from "@zhin.js/host-router";
 import { QQBot } from "./bot.js";
 import type { QQBotConfig, ReceiverMode } from "./types.js";
 
 export class QQAdapter extends Adapter<QQBot<ReceiverMode>> {
-  constructor(plugin: Plugin) {
+  #router?: Router;
+
+  constructor(plugin: Plugin, router?: Router) {
     super(plugin, "qq", []);
+    this.#router = router;
+  }
+
+  getRouter(): Router | undefined {
+    return this.#router;
   }
 
   createBot(config: QQBotConfig<ReceiverMode>): QQBot<ReceiverMode> {
@@ -52,6 +60,15 @@ export class QQAdapter extends Adapter<QQBot<ReceiverMode>> {
   // ── 生命周期 ───────────────────────────────────────────────────────
 
   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/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,9 +16,38 @@ 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";
 
+/** 从 qq-official-bot SendResult / 审核回包中解析出站消息 ID */
+export function resolveOutboundMessageId(result: unknown): string {
+  if (!result || typeof result !== "object") {
+    throw new Error("QQ 发送消息失败：响应为空");
+  }
+  const row = result as Record<string, unknown>;
+  const nested = row.data && typeof row.data === "object"
+    ? row.data as Record<string, unknown>
+    : undefined;
+  const audit = (row.message_audit ?? nested?.message_audit) as Record<string, unknown> | undefined;
+  const id = row.id ?? row.message_id ?? audit?.audit_id;
+  if (id == null || id === "") {
+    const code = row.code;
+    const msg = row.message;
+    throw new Error(
+      code != null
+        ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ""}`
+        : "QQ 发送消息失败：响应缺少消息 ID",
+    );
+  }
+  return String(id);
+}
 
 export class QQBot<T extends ReceiverMode, M extends ApplicationPlatform = ApplicationPlatform>
   extends Bot
@@ -37,21 +68,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 +156,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 +243,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,28 +264,32 @@ 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)}`);
-          return `direct-${options.id}:${result.id.toString()}`;
+          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}:${resolveOutboundMessageId(result)}`;
         } 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)}`);
-          return `private-${options.id}:${result.id.toString()}`;
+          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}:${resolveOutboundMessageId(result)}`;
         }
       }
       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)}`);
-        return `group-${options.id}:${result.id.toString()}`;
+        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}:${resolveOutboundMessageId(result)}`;
       }
       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)}`);
-        return `channel-${options.id}:${result.id.toString()}`;
+        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}:${resolveOutboundMessageId(result)}`;
       }
       default:
         throw new Error(`unsupported channel type ${options.type}`);

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) => {
@@ -296,28 +300,46 @@ useContext("router", "qq", (router: any, qq: QQAdapter) => {
     }
   });
 
-  // 频道列表
+  // 频道列表（QQ 官方 API 返回 guild_id/guild_name，归一化为控制台用的 id/name）
   router.get("/api/qq/bots/:name/guilds", async (ctx: any) => {
     try {
       const bot = qq.bots.get(ctx.params.name);
       if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
       if (!bot.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Bot 未连接" }; return; }
-      const guilds = await bot.getGuilds();
-      ctx.body = { success: true, data: guilds || [] };
+      const raw = await bot.getGuilds();
+      const guilds = (raw || []).map((g: any) => ({
+        id: g.guild_id ?? g.id,
+        name: g.guild_name ?? g.name,
+        icon: g.icon,
+        description: g.description,
+        memberCount: g.member_count,
+        ownerId: g.owner_id,
+        owner: g.owner,
+        joinTime: g.join_time,
+      }));
+      ctx.body = { success: true, data: guilds };
     } catch (e: any) {
       ctx.status = 500;
       ctx.body = { success: false, error: e?.message || "获取频道失败" };
     }
   });
 
-  // 子频道列表
+  // 子频道列表（QQ 官方 API 返回 channel_id/channel_name，归一化为 id/name）
   router.get("/api/qq/bots/:name/guilds/:guildId/channels", async (ctx: any) => {
     try {
       const bot = qq.bots.get(ctx.params.name);
       if (!bot) { ctx.status = 404; ctx.body = { success: false, error: "Bot 不存在" }; return; }
       if (!bot.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Bot 未连接" }; return; }
-      const channels = await bot.getChannels(ctx.params.guildId);
-      ctx.body = { success: true, data: channels || [] };
+      const raw = await bot.getChannels(ctx.params.guildId);
+      const channels = (raw || []).map((ch: any) => ({
+        id: ch.channel_id ?? ch.id,
+        name: ch.channel_name ?? ch.name,
+        type: ch.type,
+        subType: ch.sub_type,
+        position: ch.position,
+        parentId: ch.parent_id,
+      }));
+      ctx.body = { success: true, data: channels };
     } catch (e: any) {
       ctx.status = 500;
       ctx.body = { success: false, error: e?.message || "获取子频道失败" };

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