@zhin.js/adapter-qq 1.1.14 → 1.1.16

package/src/endpoint.ts

@@ -20,6 +20,8 @@ import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { collectOutboundImageSizes, formatOutboundMessages } from './outbound.js';
+import { QqActiveMessageGate, QqPassiveReplyLedger } from './passive-reply.js';
+import { sendQqMessages } from './qq-send.js';
 import {
   formatInboundContent,
   parseCompoundMessageId,
@@ -67,6 +69,9 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   #bot: QqBotTransport | null = null;
   #open = false;
   readonly #seenInteractions = new Map<string, number>();
+  /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
+  readonly #passiveReplies = new QqPassiveReplyLedger();
+  readonly #activeGate = new QqActiveMessageGate();
   readonly #lifecycle: EndpointLifecycle;
   #cleanup?: () => Promise<void>;
   readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
@@ -169,23 +174,12 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     const bot = this.#requireBot();
     let result: unknown;
     try {
-      for (const message of messages) {
-        switch (kind) {
-          case 'private':
-            result = await bot.sendPrivateMessage(conversation.id, message);
-            break;
-          case 'group':
-            result = await bot.sendGroupMessage(conversation.id, message);
-            break;
-          case 'channel':
-            result = await bot.sendGuildMessage(conversation.id, message);
-            break;
-          case 'direct':
-            if (!bot.sendDirectMessage) throw new Error('QQ direct message not supported by transport');
-            result = await bot.sendDirectMessage(conversation.id, message);
-            break;
-        }
-      }
+      result = await sendQqMessages({
+        bot,
+        ledger: this.#passiveReplies,
+        activeGate: this.#activeGate,
+        log: fields => this.#logger.warn(formatCompact(fields)),
+      }, conversation, messages);
     } catch (error) {
       const { failure, diagnostic } = qqDeliveryFailure(error);
       this.#logger.warn(formatCompact(diagnostic));
@@ -224,6 +218,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
       + ` | ${truncatePreview(content, 80)}`,
     );
     const roleProjection = projectQqGuildSenderRoles(msg.authorRoles);
+    if (msg.id) this.#passiveReplies.record(qqOutboundKind(conversation), conversation.id, { id: msg.id });
     void this.emit('message.receive', {
       conversation,
       message: { conversation, id: msg.id },
@@ -266,6 +261,8 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
     // ACK owns only platform loading state, never implies business acceptance.
     void action.ack().then(ok => { if (ok === false) this.#logger.warn('qq_interaction_ack_failed'); }, () => this.#logger.warn('qq_interaction_ack_failed'));
     const conversation = qqInboundConversation(String(this.#options.id), action.message);
+    // INTERACTION_CREATE's id is an event_id the reply may answer passively.
+    this.#passiveReplies.record(qqOutboundKind(conversation), conversation.id, { event_id: action.message.id });
     void this.emit('message.receive', {
       conversation, message: { conversation, id: action.message.id }, content: '',
       segments: action.message.segments, sender: { id: action.message.authorId }, endpointId: this.#options.config.id,
@@ -330,6 +327,9 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   #bot: QqHttpBotTransport | null = null;
   #open = false;
   readonly #seenInteractions = new Map<string, number>();
+  /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
+  readonly #passiveReplies = new QqPassiveReplyLedger();
+  readonly #activeGate = new QqActiveMessageGate();
   readonly #lifecycle: EndpointLifecycle;
   #cleanup?: () => Promise<void>;
   readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
@@ -432,23 +432,12 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     const bot = this.#requireBot();
     let result: unknown;
     try {
-      for (const message of messages) {
-        switch (kind) {
-          case 'private':
-            result = await bot.sendPrivateMessage(conversation.id, message);
-            break;
-          case 'group':
-            result = await bot.sendGroupMessage(conversation.id, message);
-            break;
-          case 'channel':
-            result = await bot.sendGuildMessage(conversation.id, message);
-            break;
-          case 'direct':
-            if (!bot.sendDirectMessage) throw new Error('QQ direct message not supported by transport');
-            result = await bot.sendDirectMessage(conversation.id, message);
-            break;
-        }
-      }
+      result = await sendQqMessages({
+        bot,
+        ledger: this.#passiveReplies,
+        activeGate: this.#activeGate,
+        log: fields => this.#logger.warn(formatCompact(fields)),
+      }, conversation, messages);
     } catch (error) {
       const { failure, diagnostic } = qqDeliveryFailure(error);
       this.#logger.warn(formatCompact(diagnostic));
@@ -486,6 +475,7 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
       + ` | ${truncatePreview(content, 80)}`,
     );
     const roleProjection = projectQqGuildSenderRoles(msg.authorRoles);
+    if (msg.id) this.#passiveReplies.record(qqOutboundKind(conversation), conversation.id, { id: msg.id });
     void this.emit('message.receive', {
       conversation,
       message: { conversation, id: msg.id },
@@ -528,6 +518,8 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     // ACK owns only platform loading state, never implies business acceptance.
     void action.ack().then(ok => { if (ok === false) this.#logger.warn('qq_interaction_ack_failed'); }, () => this.#logger.warn('qq_interaction_ack_failed'));
     const conversation = qqInboundConversation(String(this.#options.id), action.message);
+    // INTERACTION_CREATE's id is an event_id the reply may answer passively.
+    this.#passiveReplies.record(qqOutboundKind(conversation), conversation.id, { event_id: action.message.id });
     void this.emit('message.receive', {
       conversation, message: { conversation, id: action.message.id }, content: '',
       segments: action.message.segments, sender: { id: action.message.authorId }, endpointId: this.#options.config.id,

package/src/i18n.ts

@@ -0,0 +1,73 @@
+import { createMessages } from 'zhin.js/i18n';
+
+export const messages = createMessages({
+  bindTaskFailed: { 'zh-CN': '获取绑定任务失败: {error}', en: 'Could not create the binding task: {error}' },
+  "kindPrompt": {
+    "zh-CN": "请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。",
+    "en": "Reply public or private to save .env and configuration together."
+  },
+  "cancelHint": {
+    "zh-CN": "也可发 {command} 取消。",
+    "en": "Send {command} to cancel."
+  },
+  "bindingBusy": {
+    "zh-CN": "⚠️ 有进行中的扫码绑定，请先取消当前绑定流程",
+    "en": "⚠️ A QR binding is in progress; cancel it before starting another"
+  },
+  "kindBusy": {
+    "zh-CN": "⚠️ endpoint「{id}」等待公域/私域选择，请回复 public/private",
+    "en": "⚠️ Endpoint “{id}” is waiting for public/private selection"
+  },
+  "endpointSaved": {
+    "zh-CN": "✅ 已按 botKind={kind} 将 endpoint「{id}」写入 .env 与 {file}。\nintents: {intents}。\n⚠️ 需重启 zhin 后新 endpoint 才会生效。",
+    "en": "✅ Saved endpoint “{id}” with botKind={kind} to .env and {file}.\nintents: {intents}.\n⚠️ Restart zhin to activate the new endpoint."
+  },
+  "existingFlow": {
+    "zh-CN": "已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先取消后再试",
+    "en": "A QQ binding or public/private selection is already in progress; cancel it before trying again"
+  },
+  "scanLink": {
+    "zh-CN": "请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n{url}",
+    "en": "Open this link in mobile QQ to scan and bind the bot:\n{url}"
+  },
+  "qrExpired": {
+    "zh-CN": "二维码已过期，正在刷新，请扫描新链接…",
+    "en": "The QR code expired. Refreshing; scan the new link…"
+  },
+  "noInteractiveKind": {
+    "zh-CN": "\n（当前会话无法交互选择公/私域；私域请手动改配置。）",
+    "en": "\n(This source cannot answer public/private selection. Edit the configuration manually for a private bot.)"
+  },
+  "scanned": {
+    "zh-CN": "✅ 扫码成功！endpoint「{id}」。\n{prompt}",
+    "en": "✅ QR binding succeeded for endpoint “{id}”.\n{prompt}"
+  },
+  "writeFailed": {
+    "zh-CN": "绑定成功但写入配置失败：{error}",
+    "en": "Binding succeeded but configuration could not be saved: {error}"
+  },
+  "bindingFailed": {
+    "zh-CN": "❌ QQ 绑定失败：{error}",
+    "en": "❌ QQ binding failed: {error}"
+  },
+  "cancelled": {
+    "zh-CN": "已取消进行中的 QQ 绑定流程",
+    "en": "The active QQ binding was cancelled"
+  },
+  "pendingCancelled": {
+    "zh-CN": "已取消 endpoint「{name}」的绑定（尚未写入任何文件）",
+    "en": "Binding for endpoint “{name}” cancelled; no files were written"
+  },
+  "noFlow": {
+    "zh-CN": "当前没有进行中的 QQ 绑定流程",
+    "en": "No QQ binding is in progress"
+  },
+  "kindUnrecognized": {
+    "zh-CN": "未识别「{raw}」。{prompt}",
+    "en": "Unrecognized answer “{raw}”. {prompt}"
+  },
+  "configFailed": {
+    "zh-CN": "写入配置失败：{error}",
+    "en": "Could not save configuration: {error}"
+  }
+});

package/src/passive-reply.ts

@@ -0,0 +1,159 @@
+/**
+ * Passive replies on the QQ open platform.
+ *
+ * A message sent with the `msg_id` of a recent user message (or the `event_id` of a recent event)
+ * is a passive reply; without one it is an active message, which has quotas and can be switched
+ * off by the user. Each source may be replied to a limited number of times within a window, and
+ * `msg_seq` must differ for every reply to the same source. The ledger remembers recent sources
+ * per conversation and hands out the newest one still usable, with its next `msg_seq`.
+ *
+ * Limits from https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/overview.html
+ */
+import type { QqChannelKind as QqOutboundKind } from './protocol.js';
+
+/** Reply-to source for the SDK: a user message id or an event id. */
+export type QqReplySource = { readonly id: string } | { readonly event_id: string };
+
+export interface QqPassiveLimit {
+  readonly windowMs: number;
+  readonly maxReplies: number;
+}
+
+/** C2C: 60 min, 4 replies. Group: 5 min, 5 replies. Guild channel and DM: 5 min (count unpublished; 5 assumed). */
+export const QQ_PASSIVE_LIMITS: Readonly<Record<QqOutboundKind, QqPassiveLimit>> = Object.freeze({
+  private: { windowMs: 60 * 60_000, maxReplies: 4 },
+  group: { windowMs: 5 * 60_000, maxReplies: 5 },
+  channel: { windowMs: 5 * 60_000, maxReplies: 5 },
+  direct: { windowMs: 5 * 60_000, maxReplies: 5 },
+});
+
+/** Stop using a source this long before the platform window closes: the request itself takes time. */
+const SAFETY_MARGIN_MS = 15_000;
+/** Sources remembered per conversation; older ones are long expired in practice. */
+const MAX_SOURCES_PER_CONVERSATION = 8;
+
+interface SourceEntry {
+  readonly source: QqReplySource;
+  readonly receivedAt: number;
+  replies: number;
+  exhausted: boolean;
+}
+
+export interface PassiveReplyGrant {
+  readonly source: QqReplySource;
+  readonly msgSeq: number;
+}
+
+function sourceKey(source: QqReplySource): string {
+  return 'id' in source ? `msg:${source.id}` : `event:${source.event_id}`;
+}
+
+/** Expired conversations are dropped every this many records. */
+const PRUNE_EVERY_RECORDS = 256;
+
+export class QqPassiveReplyLedger {
+  readonly #conversations = new Map<string, SourceEntry[]>();
+  #records = 0;
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /** A user message or event in `conversation` that later replies may answer. */
+  record(kind: QqOutboundKind, conversationId: string, source: QqReplySource, receivedAt = this.now()): void {
+    const key = `${kind}:${conversationId}`;
+    const entries = (this.#conversations.get(key) ?? []).filter(entry => sourceKey(entry.source) !== sourceKey(source));
+    entries.push({ source, receivedAt, replies: 0, exhausted: false });
+    entries.sort((a, b) => a.receivedAt - b.receivedAt);
+    this.#conversations.set(key, entries.slice(-MAX_SOURCES_PER_CONVERSATION));
+    if (++this.#records % PRUNE_EVERY_RECORDS === 0) this.prune();
+  }
+
+  /**
+   * Claim one reply: `preferred` (an explicit reply segment) when it is still usable, otherwise the
+   * newest usable source in the conversation. Undefined when only an active message is possible.
+   */
+  acquire(kind: QqOutboundKind, conversationId: string, preferred?: QqReplySource): PassiveReplyGrant | undefined {
+    const limit = QQ_PASSIVE_LIMITS[kind];
+    const now = this.now();
+    const entries = this.#conversations.get(`${kind}:${conversationId}`) ?? [];
+    const usable = (entry: SourceEntry) => !entry.exhausted
+      && entry.replies < limit.maxReplies
+      && now - entry.receivedAt < limit.windowMs - SAFETY_MARGIN_MS;
+    const preferredKey = preferred ? sourceKey(preferred) : undefined;
+    const entry = (preferredKey ? entries.find(item => sourceKey(item.source) === preferredKey && usable(item)) : undefined)
+      ?? [...entries].reverse().find(usable);
+    if (!entry) return undefined;
+    entry.replies += 1;
+    return { source: entry.source, msgSeq: entry.replies };
+  }
+
+  /** The platform said this source can no longer be replied to (expired, over the limit, invalid id). */
+  exhaust(kind: QqOutboundKind, conversationId: string, source: QqReplySource): void {
+    const key = sourceKey(source);
+    const entry = this.#conversations.get(`${kind}:${conversationId}`)?.find(item => sourceKey(item.source) === key);
+    if (entry) entry.exhausted = true;
+  }
+
+  /** Drop conversations whose every source is past its window. */
+  prune(): void {
+    const now = this.now();
+    for (const [key, entries] of this.#conversations) {
+      const kind = key.slice(0, key.indexOf(':')) as QqOutboundKind;
+      const windowMs = QQ_PASSIVE_LIMITS[kind]?.windowMs ?? 0;
+      const live = entries.filter(entry => now - entry.receivedAt < windowMs);
+      if (live.length === 0) this.#conversations.delete(key);
+      else this.#conversations.set(key, live);
+    }
+  }
+}
+
+/** Platform codes meaning the reply source is unusable: switch to an active message. */
+export const QQ_PASSIVE_SOURCE_CODES: ReadonlySet<number> = new Set([
+  40034128, // 被动回复时间或次数超限
+  40034005, // 回复消息 msg_id 已过期
+  304027, // MSG_EXPIRE 回复的消息过期
+  304026, // MSG_ID 回复的消息 id 错误
+  306002, // msgid error
+  501005, 501008, 501009, // MessageID 错误 / 不存在 / 解析失败
+]);
+
+/** Platform codes meaning active messages are unavailable for this conversation for now. */
+export const QQ_ACTIVE_UNAVAILABLE_CODES: ReadonlySet<number> = new Set([
+  40034105, // 主动消息发送失败，无权限
+  304031, 304032, 304034, // 私信已关闭 / 不存在 / 不是私信成员
+  304035, 304045, 304047, 304049, 304050, // 主动消息额度、频控
+  304046, 304048, // 不允许在此（子）频道发主动消息
+]);
+
+/** Platform codes meaning Markdown is not allowed: resend as plain text. */
+export const QQ_MARKDOWN_DENIED_CODES: ReadonlySet<number> = new Set([
+  304036, // 没有 markdown 模板的权限
+  304014, // TEMPLATE_PRIVILEGE 没有模板权限
+  50056, // 不允许发送 markdown content
+]);
+
+/** How long a conversation is not offered active messages after the platform refused them. */
+export const ACTIVE_UNAVAILABLE_BACKOFF_MS = 60 * 60_000;
+
+/** Conversations where the platform recently refused active messages. */
+export class QqActiveMessageGate {
+  readonly #blockedUntil = new Map<string, number>();
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  blocked(kind: QqOutboundKind, conversationId: string): boolean {
+    const key = `${kind}:${conversationId}`;
+    const until = this.#blockedUntil.get(key);
+    if (until === undefined) return false;
+    if (this.now() < until) return true;
+    this.#blockedUntil.delete(key);
+    return false;
+  }
+
+  /** Returns true the first time a conversation is blocked, so the caller can log it once. */
+  block(kind: QqOutboundKind, conversationId: string): boolean {
+    const key = `${kind}:${conversationId}`;
+    const fresh = !this.blocked(kind, conversationId);
+    this.#blockedUntil.set(key, this.now() + ACTIVE_UNAVAILABLE_BACKOFF_MS);
+    return fresh;
+  }
+}

package/src/qq-bind-flow.ts

@@ -1,3 +1,5 @@
+import type { Locale } from 'zhin.js/i18n';
+import { messages as t } from './i18n.js';
 /**
  * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
  */
@@ -25,6 +27,7 @@ export interface QqBindCallbacks {
 }
 
 export interface QqBindFlowOptions {
+  locale?: Locale;
   signal?: AbortSignal;
   source?: string;
 }
@@ -99,7 +102,7 @@ export function startQqBindFlow(
         task = await createBindTask();
       } catch (err) {
         throw new Error(
-          `获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`,
+          t(options.locale, 'bindTaskFailed', { error: err instanceof Error ? err.message : String(err) }),
           { cause: err },
         );
       }

package/src/qq-bot-kind-prompt.ts

@@ -1,47 +1,32 @@
+import { conversationRefKey } from '@zhin.js/im-contract';
+import { createDeliveryTarget } from 'zhin.js';
+import { resolveLocale, type Locale } from 'zhin.js/i18n';
+import { messages as t } from './i18n.js';
 import { parseQqBotKind, type QqBotKind } from './qq-intents.js';
 
-/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+/** Bind replies to the complete canonical conversation and actual sender. */
 export function qqCommandSessionKey(input: unknown): string | undefined {
-  const message = input as {
-    conversation?: {
-      endpoint?: { id?: unknown; adapter?: unknown };
-      kind?: unknown;
-      id?: unknown;
-    };
-    sender?: unknown;
-  } | null | undefined;
-  const conversation = message?.conversation;
-  const adapter = conversation?.endpoint?.adapter;
-  const endpointKey = conversation?.endpoint?.id;
-  const kind = conversation?.kind;
-  const id = conversation?.id;
-  const sender = message?.sender;
-  if (
-    adapter == null
-    || endpointKey == null
-    || (kind !== 'private' && kind !== 'group' && kind !== 'channel')
-    || typeof id !== 'string'
-    || !id
-    || sender == null
-    || String(sender).trim() === ''
-  ) {
-    return undefined;
-  }
-  return `${String(adapter)}\0${String(endpointKey)}\0${kind}\0${id}\0${String(sender).trim()}`;
+  if (!input || typeof input !== 'object') return undefined;
+  const message = input as { conversation?: unknown; sender?: { id?: unknown } };
+  if (typeof message.sender?.id !== 'string' || !message.sender.id.trim()) return undefined;
+  try {
+    const conversation = createDeliveryTarget({ conversation: message.conversation as Parameters<typeof createDeliveryTarget>[0]['conversation'] });
+    return JSON.stringify([conversationRefKey(conversation), message.sender.id]);
+  } catch { return undefined; }
 }
 
-/**
- * 解析用户对公域/私域的回复。
- * 接受：public / private / 公域 / 私域（大小写不敏感，可带前后空白）。
- */
-export function parseQqBotKindAnswer(raw: unknown): QqBotKind | undefined {
+/** Public/private are stable botKind values; Chinese aliases apply only to Chinese flows. */
+export function parseQqBotKindAnswer(raw: unknown, locale?: Locale): QqBotKind | undefined {
   const text = String(raw ?? '').trim().toLowerCase();
   if (!text) return undefined;
-  if (text === '公域' || text === '公开' || text === '1') return 'public';
-  if (text === '私域' || text === '2') return 'private';
+  if (resolveLocale(locale) === 'zh-CN') {
+    if (text === '公域' || text === '公开' || text === '1') return 'public';
+    if (text === '私域' || text === '2') return 'private';
+  }
   return parseQqBotKind(text);
 }
 
-export const QQ_BOT_KIND_PROMPT =
-  '请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。\n'
-  + '也可发 qq endpoint cancel 取消。';
+export function qqBotKindPrompt(locale?: Locale, cancelCommand?: string): string {
+  return t(locale, 'kindPrompt') + (cancelCommand ? '\n' + t(locale, 'cancelHint', { command: cancelCommand }) : '');
+}
+export const QQ_BOT_KIND_PROMPT = qqBotKindPrompt();

package/src/qq-runtime-state.ts

@@ -14,6 +14,9 @@ export interface QqBindFlowHandle {
   /** 绑定期望的 endpoint id（未指定时为 undefined，成功后取 appId） */
   id?: string;
   stop: () => void;
+  readonly locale?: import('zhin.js/i18n').Locale;
+  readonly cancelCommand?: string;
+  readonly commandHeads?: readonly string[];
 }
 
 /**
@@ -26,6 +29,9 @@ export interface QqPendingBotKind {
   readonly appSecret: string;
   /** 发起 add 的会话键；仅同会话回复可完成选择 */
   readonly sessionKey: string;
+  readonly locale?: import('zhin.js/i18n').Locale;
+  readonly cancelCommand?: string;
+  readonly commandHeads?: readonly string[];
 }
 
 export interface QqRuntimeState {

package/src/qq-send.ts

@@ -0,0 +1,138 @@
+/**
+ * One QQ outbound send: passive reply when a usable source exists, active message otherwise, with
+ * the fallbacks the platform's error codes allow. Shared by the websocket and webhook Endpoints.
+ *
+ * 1. Each message claims a passive source (explicit reply segment first, else the conversation's
+ *    newest usable msg_id / event_id) with its own msg_seq.
+ * 2. Source unusable (expired, over the limit, invalid id): mark it and send that message once as
+ *    an active message. Never after a timeout: the first request may have been delivered.
+ * 3. Markdown not allowed: resend the same message as plain text.
+ * 4. Active message refused (no permission, quota, user switched it off): remember the conversation
+ *    for a while and fail fast instead of calling the platform again.
+ */
+import type { ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import type { QqOutboundElem, QqOutboundMessage } from './outbound.js';
+import {
+  QQ_ACTIVE_UNAVAILABLE_CODES,
+  QQ_MARKDOWN_DENIED_CODES,
+  QQ_PASSIVE_SOURCE_CODES,
+  type PassiveReplyGrant,
+  type QqActiveMessageGate,
+  type QqPassiveReplyLedger,
+  type QqReplySource,
+} from './passive-reply.js';
+import { qqDeliveryFailure } from './delivery-error.js';
+import { qqOutboundKind } from './protocol.js';
+import type { QqBotTransport, QqSendOptions } from './ws.js';
+
+export interface QqSendContext {
+  readonly bot: QqBotTransport;
+  readonly ledger: QqPassiveReplyLedger;
+  readonly activeGate: QqActiveMessageGate;
+  readonly log: (fields: Record<string, string | number | undefined>) => void;
+}
+
+type Kind = ReturnType<typeof qqOutboundKind>;
+
+function elements(message: QqOutboundMessage): Array<string | QqOutboundElem> {
+  return Array.isArray(message) ? [...message] : [message as string | QqOutboundElem];
+}
+
+/** The reply segment the payload already names, as a passive source. */
+export function explicitReplySource(message: QqOutboundMessage): QqReplySource | undefined {
+  for (const part of elements(message)) {
+    if (typeof part === 'string' || part.type !== 'reply') continue;
+    if (typeof part.data.event_id === 'string' && part.data.event_id) return { event_id: part.data.event_id };
+    if (typeof part.data.id === 'string' && part.data.id) return { id: part.data.id };
+  }
+  return undefined;
+}
+
+/** Plain-text version of a Markdown message (buttons dropped); undefined when it has no Markdown. */
+export function markdownAsText(message: QqOutboundMessage): QqOutboundMessage | undefined {
+  const parts = elements(message);
+  if (!parts.some(part => typeof part !== 'string' && (part.type === 'markdown' || part.type === 'keyboard' || part.type === 'button'))) return undefined;
+  const text = parts.map(part => {
+    if (typeof part === 'string') return part;
+    if (part.type === 'text') return String(part.data.text ?? '');
+    if (part.type === 'markdown') {
+      return String(part.data.content ?? '')
+        .replace(/!\[[^\]\n]{0,500}\]\(([^)\s]{1,2000})\)/g, '$1')
+        .replace(/\[([^\]\n]{1,500})\]\(([^)\s]{1,2000})\)/g, '$1 $2')
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/(\*\*|__|~~|`)/g, '');
+    }
+    return '';
+  }).join('').trim();
+  const kept = parts.filter((part): part is QqOutboundElem => typeof part !== 'string' && (part.type === 'reply' || part.type === 'at'));
+  return text ? [...kept, text] : undefined;
+}
+
+function dispatch(bot: QqBotTransport, kind: Kind, id: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown> {
+  switch (kind) {
+    case 'private': return bot.sendPrivateMessage(id, message, source, options);
+    case 'group': return bot.sendGroupMessage(id, message, source, options);
+    case 'channel': return bot.sendGuildMessage(id, message, source, options);
+    case 'direct':
+      if (!bot.sendDirectMessage) throw new Error('QQ direct message not supported by transport');
+      return bot.sendDirectMessage(id, message, source, options);
+  }
+}
+
+function platformCode(error: unknown): number | undefined {
+  return qqDeliveryFailure(error).diagnostic.platformCode;
+}
+
+/** Sends one message, passive if possible; returns the platform result. */
+async function sendOne(context: QqSendContext, kind: Kind, id: string, message: QqOutboundMessage): Promise<unknown> {
+  const passive = (body: QqOutboundMessage, grant: PassiveReplyGrant) =>
+    dispatch(context.bot, kind, id, body, grant.source, { msgSeq: grant.msgSeq });
+  const active = async (body: QqOutboundMessage): Promise<unknown> => {
+    if (context.activeGate.blocked(kind, id)) {
+      throw new EndpointDeliveryError('platform_rejected', 'QQ active messages are unavailable for this conversation', 'not_sent');
+    }
+    try {
+      return await dispatch(context.bot, kind, id, body);
+    } catch (error) {
+      const code = platformCode(error);
+      if (code !== undefined && QQ_ACTIVE_UNAVAILABLE_CODES.has(code) && context.activeGate.block(kind, id)) {
+        context.log({ op: 'qq_active_unavailable', target: `${kind}:${id}`, platformCode: code });
+      }
+      throw error;
+    }
+  };
+  /** Markdown refused: the same message once more as plain text, under a fresh msg_seq when passive. */
+  const asText = (error: unknown, previous: PassiveReplyGrant | undefined): Promise<unknown> => {
+    const code = platformCode(error);
+    const text = code !== undefined && QQ_MARKDOWN_DENIED_CODES.has(code) ? markdownAsText(message) : undefined;
+    if (!text) throw error;
+    context.log({ op: 'qq_markdown_denied_as_text', target: `${kind}:${id}`, platformCode: code });
+    const retry = previous ? context.ledger.acquire(kind, id, previous.source) : undefined;
+    return retry ? passive(text, retry) : active(text);
+  };
+  const activeOrText = (body: QqOutboundMessage) => active(body).catch((error: unknown) => asText(error, undefined));
+
+  const grant = context.ledger.acquire(kind, id, explicitReplySource(message));
+  if (!grant) return activeOrText(message);
+  try {
+    return await passive(message, grant);
+  } catch (error) {
+    const code = platformCode(error);
+    if (code !== undefined && QQ_PASSIVE_SOURCE_CODES.has(code)) {
+      context.ledger.exhaust(kind, id, grant.source);
+      context.log({ op: 'qq_passive_source_unusable', target: `${kind}:${id}`, platformCode: code });
+      return activeOrText(message);
+    }
+    // Anything else, including a timeout (outcome unknown), is not retried as an active message.
+    return asText(error, grant);
+  }
+}
+
+/** Sends every message of one delivery in order; returns the last platform result. */
+export async function sendQqMessages(context: QqSendContext, conversation: ConversationRef, messages: readonly QqOutboundMessage[]): Promise<unknown> {
+  const kind = qqOutboundKind(conversation);
+  let result: unknown;
+  for (const message of messages) result = await sendOne(context, kind, conversation.id, message);
+  return result;
+}

package/src/webhook.ts

@@ -100,10 +100,10 @@ export function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTra
     removeAllListeners: () => {
       bot.removeAllListeners(undefined as never);
     },
-    sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message as Sendable),
-    sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message as Sendable),
-    sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message as Sendable),
-    sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message as Sendable),
+    sendPrivateMessage: (userId, message, source, options) => bot.sendPrivateMessage(userId, message as Sendable, source, options),
+    sendGroupMessage: (groupId, message, source, options) => bot.sendGroupMessage(groupId, message as Sendable, source, options),
+    sendGuildMessage: (channelId, message, source, options) => bot.sendGuildMessage(channelId, message as Sendable, source, options),
+    sendDirectMessage: (guildId, message, source, options) => bot.sendDirectMessage(guildId, message as Sendable, source, options),
     recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
     recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
     recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),