@zhin.js/adapter-qq 1.1.14 → 1.1.16

package/commands/qq/endpoint/definition.ts

@@ -1,3 +1,5 @@
+import { resolveLocale, type Locale } from 'zhin.js/i18n';
+import { messages as t } from '../../../src/i18n.js';
 /**
  * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
  * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
@@ -19,7 +21,7 @@ import {
   type EndpointConfigurationStore,
 } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { QQ_BOT_KIND_PROMPT, qqCommandSessionKey } from '../../../src/qq-bot-kind-prompt.js';
+import { qqBotKindPrompt, qqCommandSessionKey } from '../../../src/qq-bot-kind-prompt.js';
 import { startQqBindFlow } from '../../../src/qq-bind-flow.js';
 import { defaultQqEndpointIntentFields, type QqBotKind } from '../../../src/qq-intents.js';
 import {
@@ -50,10 +52,10 @@ export function extractQqCommandReply(input: unknown): QqCommandReply {
   return extractEndpointCommandReply(input);
 }
 
-function busyFooter(state: QqRuntimeState): string | undefined {
-  if (state.bindFlow) return '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消';
+function busyFooter(state: QqRuntimeState, locale?: Locale): string | undefined {
+  if (state.bindFlow) return t(locale, 'bindingBusy') + (state.bindFlow.cancelCommand ? `\n${t(locale, 'cancelHint', { command: state.bindFlow.cancelCommand })}` : '');
   if (state.pendingBotKind) {
-    return `⚠️ endpoint「${state.pendingBotKind.endpointId}」等待公域/私域选择，回复 public/private 或 qq endpoint cancel`;
+    return t(locale, 'kindBusy', { id: state.pendingBotKind.endpointId });
   }
   return undefined;
 }
@@ -62,11 +64,12 @@ function busyFooter(state: QqRuntimeState): string | undefined {
 export async function runQqEndpointList(
   state: QqRuntimeState,
   store: EndpointConfigurationStore,
+  locale?: Locale,
 ): Promise<string> {
   return formatEndpointList(qqEndpointListSpec, {
     running: state.endpoints.values(),
     configured: await store.list('qq'),
-    footer: busyFooter(state),
+    footer: busyFooter(state, locale), locale,
   });
 }
 
@@ -81,6 +84,7 @@ async function writeEndpointWithBotKind(
   botKind: QqBotKind,
   store: EndpointConfigurationStore,
 ): Promise<string> {
+  const locale = pending.locale;
   const appidKey = buildEndpointEnvKey('qq', pending.endpointId, 'appid');
   const secretKey = buildEndpointEnvKey('qq', pending.endpointId, 'secret');
   const intentFields = defaultQqEndpointIntentFields(botKind);
@@ -98,11 +102,7 @@ async function writeEndpointWithBotKind(
       [secretKey]: pending.appSecret,
     },
   });
-  return (
-    `✅ 已按 botKind=${intentFields.botKind} 将 endpoint「${pending.endpointId}」写入 .env 与 ${filePath}。\n` +
-    `intents: ${intentFields.intents.join(', ')}。\n` +
-    '⚠️ 需重启 zhin 后新 endpoint 才会生效。'
-  );
+  return t(locale, 'endpointSaved', { kind: intentFields.botKind, id: pending.endpointId, file: filePath, intents: intentFields.intents.join(', ') });
 }
 
 /**
@@ -129,10 +129,13 @@ export function runQqEndpointAdd(
   reply: QqCommandReply,
   store: EndpointConfigurationStore,
   input?: unknown,
+  locale: Locale = 'zh-CN',
+  cancelCommand?: string,
+  commandHeads?: readonly string[],
 ): Promise<string> {
   if (state.bindFlow || state.pendingBotKind) {
     return Promise.resolve(
-      '已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先发送 qq endpoint cancel 取消后再试',
+      t(locale, 'existingFlow'),
     );
   }
   const endpointId = id?.trim() || undefined;
@@ -155,12 +158,12 @@ export function runQqEndpointAdd(
         onQrDisplayed: (url) => {
           // QQ 出站当前仅支持纯文本（富媒体未迁移），二维码只能发链接文本
           settle(
-            `请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`,
+            t(locale, 'scanLink', { url }),
           );
         },
         onQrExpired: async () => {
           try {
-            await reply('二维码已过期，正在刷新，请扫描新链接…');
+            await reply(t(locale, 'qrExpired'));
           } catch {
             // same as settle follow-up: best-effort after command scope ends
           }
@@ -179,12 +182,12 @@ export function runQqEndpointAdd(
                     endpointId: finalName,
                     appId,
                     appSecret,
-                    sessionKey: '',
+                    sessionKey: '', locale, cancelCommand,
                   },
                   'public',
                   store,
                 ) +
-                '\n（当前会话无法交互选择公/私域；私域请手动改配置。）',
+                t(locale, 'noInteractiveKind'),
               );
               return;
             }
@@ -193,40 +196,40 @@ export function runQqEndpointAdd(
               endpointId: finalName,
               appId,
               appSecret,
-              sessionKey,
+              sessionKey, locale, cancelCommand, commandHeads,
             };
             settle(
-              `✅ 扫码成功！endpoint「${finalName}」。\n` +
-              QQ_BOT_KIND_PROMPT,
+              t(locale, 'scanned', { id: finalName, prompt: qqBotKindPrompt(locale, cancelCommand) }),
             );
           } catch (error) {
-            settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+            settle(t(locale, 'writeFailed', { error: error instanceof Error ? error.message : String(error) }));
           }
         },
         onFailure: (error) => {
           state.bindFlow = null;
-          settle(`❌ QQ 绑定失败：${error.message}`);
+          settle(t(locale, 'bindingFailed', { error: error.message }));
         },
       },
-      { source: 'zhin' },
+      { source: 'zhin', locale },
     );
-    state.bindFlow = { id: endpointId, stop };
+    state.bindFlow = { id: endpointId, stop, locale, cancelCommand, commandHeads };
   });
 }
 
 /** `qq endpoint cancel`：中止进行中的绑定或待选 botKind */
-export function runQqEndpointCancel(state: QqRuntimeState): string {
+export function runQqEndpointCancel(state: QqRuntimeState, preference?: Locale): string {
+  const locale = resolveLocale(state.pendingBotKind?.locale ?? state.bindFlow?.locale ?? preference);
   if (state.bindFlow) {
     state.bindFlow.stop();
     state.bindFlow = null;
-    return '已取消进行中的 QQ 绑定流程';
+    return t(locale, 'cancelled');
   }
   if (state.pendingBotKind) {
     const name = state.pendingBotKind.endpointId;
     state.pendingBotKind = null;
-    return `已取消 endpoint「${name}」的绑定（尚未写入任何文件）`;
+    return t(locale, 'pendingCancelled', { name });
   }
-  return '当前没有进行中的 QQ 绑定流程';
+  return t(locale, 'noFlow');
 }
 
 /** `qq endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
@@ -245,19 +248,21 @@ export async function runQqEndpointRemove(
 export const qqEndpointCommands = createEndpointCommands({
   ...qqEndpointListSpec,
   fields: [
-    { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid' },
-    { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret' },
+    { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid', descriptionI18n: { en: "QQ bot app ID" } },
+    { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret', descriptionI18n: { en: "QQ bot secret" } },
   ],
   running: (use) => use(qqRuntimeStateToken).endpoints.values(),
-  listFooter: (use) => busyFooter(use(qqRuntimeStateToken)),
+  listFooter: (use, locale) => busyFooter(use(qqRuntimeStateToken), locale),
+  addDescriptionI18n: { en: 'Bind a bot through mobile QQ, choose public/private, then save configuration; restart to apply' },
   addDescription:
     '手机 QQ 扫码绑定机器人：确认公域/私域后一次性写入 .env 与 zhin.config.yml（重启生效）',
-  bindFlow: ({ id, reply, input, use }) =>
+  bindFlow: ({ id, reply, input, use, locale, formatCommand }) =>
     runQqEndpointAdd(
       use(qqRuntimeStateToken),
       id,
       reply,
       use(endpointConfigurationStoreToken),
-      input,
+      input, locale, formatCommand?.('qq endpoint cancel'),
+      ['qq endpoint list', 'qq endpoint add', 'qq endpoint remove', 'qq endpoint cancel'].flatMap(path => { const head = formatCommand?.(path); return head ? [head] : []; }),
     ),
 }, defineCommand);

package/lib/endpoint.js

@@ -10,6 +10,8 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { Endpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { collectOutboundImageSizes, formatOutboundMessages } from './outbound.js';
+import { QqActiveMessageGate, QqPassiveReplyLedger } from './passive-reply.js';
+import { sendQqMessages } from './qq-send.js';
 import { formatInboundContent, parseCompoundMessageId, qqInboundConversation, qqOutboundKind, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
 import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
 import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
@@ -21,6 +23,9 @@ export class QqWebsocketEndpoint extends Endpoint {
     #bot = null;
     #open = false;
     #seenInteractions = new Map();
+    /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
+    #passiveReplies = new QqPassiveReplyLedger();
+    #activeGate = new QqActiveMessageGate();
     #lifecycle;
     #cleanup;
     management = createQqEndpointManagement(() => this.#requireBot());
@@ -124,24 +129,12 @@ export class QqWebsocketEndpoint extends Endpoint {
         const bot = this.#requireBot();
         let result;
         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);
@@ -176,6 +169,8 @@ export class QqWebsocketEndpoint extends Endpoint {
             + (msg.mentioned ? ' (mentioned)' : '')
             + ` | ${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 },
@@ -224,6 +219,8 @@ export class QqWebsocketEndpoint extends Endpoint {
         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,
@@ -274,6 +271,9 @@ export class QqHttpEndpoint extends Endpoint {
     #bot = null;
     #open = false;
     #seenInteractions = new Map();
+    /** Recent msg_id / event_id per conversation, so replies go out as passive messages. */
+    #passiveReplies = new QqPassiveReplyLedger();
+    #activeGate = new QqActiveMessageGate();
     #lifecycle;
     #cleanup;
     management = createQqEndpointManagement(() => this.#requireBot());
@@ -379,24 +379,12 @@ export class QqHttpEndpoint extends Endpoint {
         const bot = this.#requireBot();
         let result;
         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);
@@ -430,6 +418,8 @@ export class QqHttpEndpoint extends Endpoint {
             + (msg.mentioned ? ' (mentioned)' : '')
             + ` | ${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 },
@@ -478,6 +468,8 @@ export class QqHttpEndpoint extends Endpoint {
         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/lib/i18n.d.ts

@@ -0,0 +1 @@
+export declare const messages: (locale: import("zhin.js").Locale | undefined, key: "bindTaskFailed" | "kindPrompt" | "cancelHint" | "bindingBusy" | "kindBusy" | "endpointSaved" | "existingFlow" | "scanLink" | "qrExpired" | "noInteractiveKind" | "scanned" | "writeFailed" | "bindingFailed" | "cancelled" | "pendingCancelled" | "noFlow" | "kindUnrecognized" | "configFailed", values?: import("zhin.js").MessageValues) => string;

package/lib/i18n.js

@@ -0,0 +1,72 @@
+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/lib/passive-reply.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 declare const QQ_PASSIVE_LIMITS: Readonly<Record<QqOutboundKind, QqPassiveLimit>>;
+export interface PassiveReplyGrant {
+    readonly source: QqReplySource;
+    readonly msgSeq: number;
+}
+export declare class QqPassiveReplyLedger {
+    #private;
+    private readonly now;
+    constructor(now?: () => number);
+    /** A user message or event in `conversation` that later replies may answer. */
+    record(kind: QqOutboundKind, conversationId: string, source: QqReplySource, receivedAt?: number): void;
+    /**
+     * 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;
+    /** 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;
+    /** Drop conversations whose every source is past its window. */
+    prune(): void;
+}
+/** Platform codes meaning the reply source is unusable: switch to an active message. */
+export declare const QQ_PASSIVE_SOURCE_CODES: ReadonlySet<number>;
+/** Platform codes meaning active messages are unavailable for this conversation for now. */
+export declare const QQ_ACTIVE_UNAVAILABLE_CODES: ReadonlySet<number>;
+/** Platform codes meaning Markdown is not allowed: resend as plain text. */
+export declare const QQ_MARKDOWN_DENIED_CODES: ReadonlySet<number>;
+/** How long a conversation is not offered active messages after the platform refused them. */
+export declare const ACTIVE_UNAVAILABLE_BACKOFF_MS: number;
+/** Conversations where the platform recently refused active messages. */
+export declare class QqActiveMessageGate {
+    #private;
+    private readonly now;
+    constructor(now?: () => number);
+    blocked(kind: QqOutboundKind, conversationId: string): boolean;
+    /** Returns true the first time a conversation is blocked, so the caller can log it once. */
+    block(kind: QqOutboundKind, conversationId: string): boolean;
+}

package/lib/passive-reply.js

@@ -0,0 +1,122 @@
+/** 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 = 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;
+function sourceKey(source) {
+    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 {
+    now;
+    #conversations = new Map();
+    #records = 0;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** A user message or event in `conversation` that later replies may answer. */
+    record(kind, conversationId, source, receivedAt = this.now()) {
+        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, conversationId, preferred) {
+        const limit = QQ_PASSIVE_LIMITS[kind];
+        const now = this.now();
+        const entries = this.#conversations.get(`${kind}:${conversationId}`) ?? [];
+        const usable = (entry) => !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, conversationId, source) {
+        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() {
+        const now = this.now();
+        for (const [key, entries] of this.#conversations) {
+            const kind = key.slice(0, key.indexOf(':'));
+            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 = 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 = 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 = 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 {
+    now;
+    #blockedUntil = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    blocked(kind, conversationId) {
+        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, conversationId) {
+        const key = `${kind}:${conversationId}`;
+        const fresh = !this.blocked(kind, conversationId);
+        this.#blockedUntil.set(key, this.now() + ACTIVE_UNAVAILABLE_BACKOFF_MS);
+        return fresh;
+    }
+}

package/lib/qq-bind-flow.d.ts

@@ -1,3 +1,4 @@
+import type { Locale } from 'zhin.js/i18n';
 export interface QqBindCredentials {
     appId: string;
     appSecret: string;
@@ -10,6 +11,7 @@ export interface QqBindCallbacks {
     onQrExpired?: () => void | Promise<void>;
 }
 export interface QqBindFlowOptions {
+    locale?: Locale;
     signal?: AbortSignal;
     source?: string;
 }

package/lib/qq-bind-flow.js

@@ -1,3 +1,4 @@
+import { messages as t } from './i18n.js';
 /**
  * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
  */
@@ -60,7 +61,7 @@ export function startQqBindFlow(callbacks, options = {}) {
                 task = await createBindTask();
             }
             catch (err) {
-                throw new Error(`获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+                throw new Error(t(options.locale, 'bindTaskFailed', { error: err instanceof Error ? err.message : String(err) }), { cause: err });
             }
             const connectUrl = buildConnectUrl(task.taskId, options.source ?? 'zhin');
             await callbacks.onQrDisplayed?.(connectUrl);

package/lib/qq-bot-kind-prompt.d.ts

@@ -1,9 +1,8 @@
+import { type Locale } from 'zhin.js/i18n';
 import { type QqBotKind } from './qq-intents.js';
-/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+/** Bind replies to the complete canonical conversation and actual sender. */
 export declare function qqCommandSessionKey(input: unknown): string | undefined;
-/**
- * 解析用户对公域/私域的回复。
- * 接受：public / private / 公域 / 私域（大小写不敏感，可带前后空白）。
- */
-export declare function parseQqBotKindAnswer(raw: unknown): QqBotKind | undefined;
+/** Public/private are stable botKind values; Chinese aliases apply only to Chinese flows. */
+export declare function parseQqBotKindAnswer(raw: unknown, locale?: Locale): QqBotKind | undefined;
+export declare function qqBotKindPrompt(locale?: Locale, cancelCommand?: string): string;
 export declare const QQ_BOT_KIND_PROMPT: string;