@zhin.js/adapter-qq 1.1.14 → 1.1.15

package/lib/qq-send.js

@@ -0,0 +1,109 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { QQ_ACTIVE_UNAVAILABLE_CODES, QQ_MARKDOWN_DENIED_CODES, QQ_PASSIVE_SOURCE_CODES, } from './passive-reply.js';
+import { qqDeliveryFailure } from './delivery-error.js';
+import { qqOutboundKind } from './protocol.js';
+function elements(message) {
+    return Array.isArray(message) ? [...message] : [message];
+}
+/** The reply segment the payload already names, as a passive source. */
+export function explicitReplySource(message) {
+    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) {
+    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) => typeof part !== 'string' && (part.type === 'reply' || part.type === 'at'));
+    return text ? [...kept, text] : undefined;
+}
+function dispatch(bot, kind, id, message, source, options) {
+    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) {
+    return qqDeliveryFailure(error).diagnostic.platformCode;
+}
+/** Sends one message, passive if possible; returns the platform result. */
+async function sendOne(context, kind, id, message) {
+    const passive = (body, grant) => dispatch(context.bot, kind, id, body, grant.source, { msgSeq: grant.msgSeq });
+    const active = async (body) => {
+        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, previous) => {
+        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) => active(body).catch((error) => 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, conversation, messages) {
+    const kind = qqOutboundKind(conversation);
+    let result;
+    for (const message of messages)
+        result = await sendOne(context, kind, conversation.id, message);
+    return result;
+}

package/lib/webhook.js

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

package/lib/ws.d.ts

@@ -1,6 +1,11 @@
 import { Bot, type ApproveJoinRequestOptions } from 'qq-official-bot';
 import type { EndpointTransportState } from 'zhin.js/adapter';
 import type { QqOutboundMessage } from './outbound.js';
+import type { QqReplySource } from './passive-reply.js';
+/** Per-send options. `msgSeq` numbers replies to one passive source (qq-official-bot ≥ 1.3.3). */
+export interface QqSendOptions {
+    readonly msgSeq?: number;
+}
 import type { QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
 /** SDK business surface exposed to plugins without bypassing Endpoint lifecycle ownership. */
 export type QqOfficialApi = Pick<Bot, 'messageService' | 'fileProcessor' | 'guildService' | 'channelService' | 'memberService' | 'permissionService' | 'reactionService' | 'scheduleService' | 'threadService' | 'audioService' | 'botService' | 'groupService' | 'menuPanelService' | 'group' | 'user' | 'channel' | 'direct' | 'guild'>;
@@ -13,10 +18,11 @@ export interface QqBotTransport {
     stop(): Promise<void>;
     on(event: string, listener: (...args: unknown[]) => void): void;
     removeAllListeners(): void;
-    sendPrivateMessage(userId: string, message: QqOutboundMessage): Promise<unknown>;
-    sendGroupMessage(groupId: string, message: QqOutboundMessage): Promise<unknown>;
-    sendGuildMessage(channelId: string, message: QqOutboundMessage): Promise<unknown>;
-    sendDirectMessage?(guildId: string, message: QqOutboundMessage): Promise<unknown>;
+    /** `source` makes it a passive reply; without it the platform treats the message as active. */
+    sendPrivateMessage(userId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
+    sendGroupMessage(groupId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
+    sendGuildMessage(channelId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
+    sendDirectMessage?(guildId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
     recallPrivateMessage?(userId: string, messageId: string): Promise<unknown>;
     recallGroupMessage?(groupId: string, messageId: string): Promise<unknown>;
     recallGuildMessage?(channelId: string, messageId: string): Promise<unknown>;

package/lib/ws.js

@@ -240,10 +240,10 @@ export function defaultCreateBot(config) {
                 receiver.removeListener(entry.event, entry.listener);
             bot.removeAllListeners(undefined);
         },
-        sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message),
-        sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message),
-        sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message),
-        sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message),
+        sendPrivateMessage: (userId, message, source, options) => bot.sendPrivateMessage(userId, message, source, options),
+        sendGroupMessage: (groupId, message, source, options) => bot.sendGroupMessage(groupId, message, source, options),
+        sendGuildMessage: (channelId, message, source, options) => bot.sendGuildMessage(channelId, message, source, options),
+        sendDirectMessage: (guildId, message, source, options) => bot.sendDirectMessage(guildId, message, source, options),
         recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
         recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
         recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,25 +33,25 @@
     "directory": "plugins/adapters/qq"
   },
   "dependencies": {
-    "qq-official-bot": "^1.3.1",
-    "@zhin.js/adapter": "1.1.21",
-    "@zhin.js/agent-feature": "1.1.8",
-    "@zhin.js/core": "1.1.49",
-    "@zhin.js/feature-kit": "1.1.7",
-    "@zhin.js/host-http": "1.1.8",
-    "@zhin.js/im-contract": "1.1.5",
+    "qq-official-bot": "^1.3.3",
+    "@zhin.js/adapter": "1.1.22",
+    "@zhin.js/agent-feature": "1.1.9",
+    "@zhin.js/core": "1.1.50",
+    "@zhin.js/feature-kit": "1.1.8",
+    "@zhin.js/host-http": "1.1.9",
+    "@zhin.js/im-contract": "1.1.6",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.7",
-    "@zhin.js/skill": "1.1.8",
-    "@zhin.js/tool": "1.1.8"
+    "@zhin.js/permission": "1.1.8",
+    "@zhin.js/skill": "1.1.9",
+    "@zhin.js/tool": "1.1.9"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.21",
-    "@zhin.js/command": "^1.1.9",
-    "@zhin.js/core": "^1.1.49",
-    "@zhin.js/middleware": "^1.1.8",
-    "zhin.js": "^1.1.14"
+    "@zhin.js/adapter": "^1.1.22",
+    "@zhin.js/command": "^1.1.10",
+    "@zhin.js/core": "^1.1.50",
+    "@zhin.js/middleware": "^1.1.9",
+    "zhin.js": "^1.1.15"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -72,8 +72,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.8",
-    "zhin.js": "1.1.14"
+    "@zhin.js/host-http": "1.1.9",
+    "zhin.js": "1.1.15"
   },
   "files": [
     "adapters",

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