@zhin.js/adapter-qq 1.1.13 → 1.1.15

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @zhin.js/adapter-qq
 
+## 1.1.15
+
+### Patch Changes
+
+- 7d68df6: 精简 Agent 内置固定提示词与消息说明，保留工具、审批和结构化回复能力。适配器 Skill 按会话场景拆分，群／频道管理仅向对应场景披露；提示段与模型消息段支持场景声明，沿用当前回合权限和 generation 投影。
+- e684ade: Upgrade `qq-official-bot` to 1.3.3 and send the passive-reply `msg_seq` the Endpoint assigns per source, so the platform's `msg_id + msg_seq` deduplication protects a retried passive reply.
+- 34c536b: Send QQ replies as passive messages. The Endpoint never passed the user message's `msg_id`, so every reply went out as an active message (quota-limited, blocked when the user turns off active messages). It now records each conversation's recent `msg_id` and interaction `event_id` and replies passively within the platform limits (group 5 min × 5, C2C 60 min × 4, guild 5 min), preferring an explicit reply segment. An expired or exhausted source falls back to one active message; an unknown outcome or a content rejection never does. Conversations that refuse active messages are skipped for an hour, and Markdown the platform does not allow is resent as plain text. Requires `qq-official-bot` 1.3.3, which accepts the Endpoint's per-source `msg_seq` so a retried passive reply is deduplicated by the platform.
+- Updated dependencies [f98025b]
+- Updated dependencies [66ec1a5]
+- Updated dependencies [7d68df6]
+- Updated dependencies [bf0fa9f]
+- Updated dependencies [3326db3]
+- Updated dependencies [e91235e]
+- Updated dependencies [6da2bad]
+- Updated dependencies [3781f1c]
+  - @zhin.js/core@1.1.50
+  - @zhin.js/adapter@1.1.22
+  - @zhin.js/im-contract@1.1.6
+  - @zhin.js/tool@1.1.9
+  - @zhin.js/host-http@1.1.9
+  - @zhin.js/agent-feature@1.1.9
+  - @zhin.js/feature-kit@1.1.8
+  - @zhin.js/permission@1.1.8
+  - @zhin.js/skill@1.1.9
+
+## 1.1.14
+
+### Patch Changes
+
+- Updated dependencies [974fa85]
+- Updated dependencies [1e9b3d6]
+  - @zhin.js/core@1.1.49
+
 ## 1.1.13
 
 ### Patch Changes

package/README.md

@@ -174,6 +174,28 @@ Markdown + 指令按钮组。按钮值与手动输入共用同一解析入口，
 不支持原生按钮的 Adapter 会在 Core 中把同一 keyboard 语义降级为编号列表，并保存数字到
 payload 的回跳映射。图片、音频、视频和文件仍沿 canonical `MediaRef` 出站链投递。
 
+## 被动回复与主动消息
+
+QQ 开放平台按有没有带上用户消息的 `msg_id`（或事件的 `event_id`）区分被动回复和主动消息。
+主动消息有额度限制，用户还可以在客户端关闭"允许主动发送"。Endpoint 会记录每个会话最近
+收到的 `msg_id`，以及按钮回调（`INTERACTION_CREATE`）的 `event_id`，发送时自动带上：
+
+| 场景 | 被动回复有效期 | 每个来源最多回复 |
+| --- | --- | --- |
+| 群聊 | 5 分钟 | 5 次 |
+| 单聊（C2C） | 60 分钟 | 4 次 |
+| 频道 / 频道私信 | 5 分钟 | 5 次（平台未公布次数） |
+
+- **怎么选来源**：每条消息取会话里最新的可用来源。payload 里有 `reply` 段时，优先用它指向的消息。快到有效期时（提前 15 秒）就不再使用，`msg_seq` 按来源递增，经 `qq-official-bot` 的 `SendOptions.msgSeq` 传给平台。
+- **来源不可用**：平台返回来源过期、次数用完或 msg_id 错误（`40034128`、`40034005`、`304027`、`304026` 等）时，这个来源作废，这条消息改发一次主动消息。
+- **结果未知不重发**：超时、断线这类结果未知的情况，不会改发主动消息，因为第一次请求可能已经送达；会报告 `deliveryUnknown`。
+- **内容被拒不改发主动**：审核、敏感词等内容类错误照常报失败，不改发主动消息，以免消耗主动额度。
+- **主动消息被拒**：平台拒绝主动消息时（无权限 `40034105`、私信已关闭、额度用完等），这个会话 1 小时内不再尝试主动发送，直接报失败。
+- **Markdown 没有权限**：平台拒绝 Markdown 时（`304036`、`304014`、`50056`），同一条消息改成纯文本重发，按钮会被去掉。
+
+公域机器人在群里只能收到 @ 它的消息，所以群聊旁听（`ai.trigger.ambient`）只对拥有全量
+消息权限的私域机器人有意义。
+
 ## 故障排查
 
 | 现象 | 排查 |
@@ -181,7 +203,9 @@ payload 的回跳映射。图片、音频、视频和文件仍沿 canonical `Med
 | Gateway Identify 后断线 | 检查 `botKind` 与 intents；公域机器人不要订阅受限 intent |
 | 二维码绑定后仍离线 | 在 Console 登录待办确认结果，并检查 App ID、Secret 与 Token |
 | Webhook 无事件 | 检查 HTTP Host、公网路径、平台回调与签名参数 |
-| Markdown/按钮发送失败 | 检查平台模板与权限，并按 Endpoint 能力降级 |
+| Markdown/按钮发送失败 | 检查平台模板与权限；无权限时 Endpoint 会自动改发纯文本 |
+| 日志出现 `qq_active_unavailable` | 该会话拒绝主动消息：让用户打开"允许主动发送"，或等用户再发消息后以被动回复送达 |
+| 定时任务、超时通知发不出 | 触发时会话里没有有效期内的 `msg_id`，只能发主动消息；检查主动消息权限与额度 |
 
 ## 许可证
 

package/agents/qq/skills/qq/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: qq
-platforms: [qq]
-description: QQ 官方机器人频道、角色和成员详情能力。
-keywords: [qq, guild, channel, role, member]
-tags: [adapter, community]
+platforms:
+  - qq
+description: QQ 官方机器人频道、角色和成员详情管理。
+keywords:
+  - qq
+  - guild
+  - channel
+  - role
+  - member
+tags:
+  - adapter
+  - community
 tools:
-  - list_guilds
   - list_channels
   - list_roles
   - create_role
@@ -13,10 +20,9 @@ tools:
   - remove_role
   - channel_info
   - member_detail
+scopes:
+  - channel
 ---
+# QQ 频道
 
-# QQ 官方机器人
-
-先用 `list_guilds` 和 `list_channels` 确认频道上下文。角色操作前用 `list_roles` 获取角色 ID；成员操作前用 `member_detail` 确认目标。创建、授予和移除角色属于写操作，应遵守对应 Tool 的审批策略。
-
-当前 Agent Tool 不提供群踢人、禁言或成员列表能力。
+确认频道和成员 ID 后查询详情或维护角色；权限与审批由各 Tool 执行。可访问频道列表使用 qq-directory。

package/agents/qq/skills/qq/tools/add_role/index.js

@@ -11,6 +11,7 @@ export default defineAgentTool({
         role_id: z.string().describe('角色 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id, channel_id, user_id, role_id }, context) {

package/agents/qq/skills/qq/tools/add_role/index.ts

@@ -11,6 +11,7 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
     role_id: z.string().describe('角色 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'manage_roles')],
   async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {

package/agents/qq/skills/qq/tools/channel_info/index.js

@@ -8,6 +8,7 @@ export default defineAgentTool({
         channel_id: z.string().describe('子频道 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'guild_admin')],
     async execute({ channel_id }, context) {

package/agents/qq/skills/qq/tools/channel_info/index.ts

@@ -8,6 +8,7 @@ export default defineAgentTool<{ channel_id: string }>({
     channel_id: z.string().describe('子频道 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'guild_admin')],
   async execute({ channel_id  }: { channel_id: string }, context) {

package/agents/qq/skills/qq/tools/create_role/index.js

@@ -10,6 +10,7 @@ export default defineAgentTool({
         color: z.number().optional().describe('颜色（RGB 十进制数值）'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'guild_owner')],
     async execute({ guild_id, name, color }, context) {

package/agents/qq/skills/qq/tools/create_role/index.ts

@@ -10,6 +10,7 @@ export default defineAgentTool<{ guild_id: string; name: string; color?: number
     color: z.number().optional().describe('颜色（RGB 十进制数值）'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'guild_owner')],
   async execute({ guild_id, name, color  }: { guild_id: string; name: string; color?: number }, context) {

package/agents/qq/skills/qq/tools/list_channels/index.js

@@ -8,6 +8,7 @@ export default defineAgentTool({
         guild_id: z.string().describe('频道 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'manage_channels')],
     async execute({ guild_id }, context) {

package/agents/qq/skills/qq/tools/list_channels/index.ts

@@ -8,6 +8,7 @@ export default defineAgentTool<{ guild_id: string }>({
     guild_id: z.string().describe('频道 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'manage_channels')],
   async execute({ guild_id  }: { guild_id: string }, context) {

package/agents/qq/skills/qq/tools/list_roles/index.js

@@ -8,6 +8,7 @@ export default defineAgentTool({
         guild_id: z.string().describe('频道 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id }, context) {

package/agents/qq/skills/qq/tools/list_roles/index.ts

@@ -8,6 +8,7 @@ export default defineAgentTool<{ guild_id: string }>({
     guild_id: z.string().describe('频道 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'manage_roles')],
   async execute({ guild_id  }: { guild_id: string }, context) {

package/agents/qq/skills/qq/tools/member_detail/index.js

@@ -9,6 +9,7 @@ export default defineAgentTool({
         user_id: z.string().describe('用户 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'guild_admin')],
     async execute({ guild_id, user_id }, context) {

package/agents/qq/skills/qq/tools/member_detail/index.ts

@@ -9,6 +9,7 @@ export default defineAgentTool<{ guild_id: string; user_id: string }>({
     user_id: z.string().describe('用户 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'guild_admin')],
   async execute({ guild_id, user_id  }: { guild_id: string; user_id: string }, context) {

package/agents/qq/skills/qq/tools/remove_role/index.js

@@ -11,6 +11,7 @@ export default defineAgentTool({
         role_id: z.string().describe('角色 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id, channel_id, user_id, role_id }, context) {

package/agents/qq/skills/qq/tools/remove_role/index.ts

@@ -11,6 +11,7 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
     role_id: z.string().describe('角色 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'manage_roles')],
   async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {

package/agents/qq/skills/qq-directory/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: qq-directory
+platforms:
+  - qq
+description: QQ 官方机器人可访问的频道列表查询。
+keywords:
+  - qq
+  - list_guilds
+tools:
+  - list_guilds
+---
+# qq-directory
+
+先查询可访问的频道列表，使用工具返回的真实 ID。

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/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-send.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { QqOutboundMessage } from './outbound.js';
+import { type QqActiveMessageGate, type QqPassiveReplyLedger, type QqReplySource } from './passive-reply.js';
+import type { QqBotTransport } from './ws.js';
+export interface QqSendContext {
+    readonly bot: QqBotTransport;
+    readonly ledger: QqPassiveReplyLedger;
+    readonly activeGate: QqActiveMessageGate;
+    readonly log: (fields: Record<string, string | number | undefined>) => void;
+}
+/** The reply segment the payload already names, as a passive source. */
+export declare function explicitReplySource(message: QqOutboundMessage): QqReplySource | undefined;
+/** Plain-text version of a Markdown message (buttons dropped); undefined when it has no Markdown. */
+export declare function markdownAsText(message: QqOutboundMessage): QqOutboundMessage | undefined;
+/** Sends every message of one delivery in order; returns the last platform result. */
+export declare function sendQqMessages(context: QqSendContext, conversation: ConversationRef, messages: readonly QqOutboundMessage[]): Promise<unknown>;