@zhin.js/adapter-qq 1.1.10 → 1.1.12

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @zhin.js/adapter-qq
 
+## 1.1.12
+
+### Patch Changes
+
+- e40899f: Adapters now project group owners and admins onto the canonical `sender.roles` names `owner` / `admin` (Telegram creator/administrator, KOOK guild owner and admin-permission roles, Lark chat owner/managers, QQ official guild owner/admin identities). KOOK numeric role ids moved from `roles` to `permissions` (`role:<id>`). `@zhin.js/command` exports `canManageConversation` ("private chat or owner/admin/master"), now shared by the Bilibili and earthquake subscription commands; Roulette lets owners and admins toggle the mute penalty and cancel a game.
+- 5fc9e20: 修复 QQ 官方机器人分页「菜单」只显示标题和翻页按钮、指令列表丢失的问题：一条 QQ 消息只能携带一个 markdown，按钮消息或含内联 markdown 的消息中，文本与内联 markdown 现按顺序合并为同一 markdown 段（模板 markdown 与纯文本消息不变）。图片与 markdown/按钮同时出现时（如菜单渲染成图片），公网 URL 图片按 `![图片 #宽px #高px](url)` 嵌入 markdown（尺寸读取图片文件头获得）；base64/本地图片（QQ 上传接口只返回 file_info，拿不到 URL）或尺寸未知时，降级为先发独立图片消息、再发 markdown 与按钮，避免 msg_type 冲突导致图片丢失。新增导出 `formatOutboundMessages`、`collectOutboundImageSizes`、`probeImageSize`、`imageSizeFromBytes`。
+- Updated dependencies [1a11207]
+- Updated dependencies [9943df6]
+- Updated dependencies [5be09ae]
+- Updated dependencies [a3ab153]
+- Updated dependencies [e8f7309]
+- Updated dependencies [5afc18f]
+- Updated dependencies [d3563d9]
+- Updated dependencies [c618eb7]
+- Updated dependencies [fbfefb7]
+  - @zhin.js/tool@1.1.8
+  - @zhin.js/core@1.1.47
+  - @zhin.js/adapter@1.1.21
+  - @zhin.js/feature-kit@1.1.7
+  - @zhin.js/im-contract@1.1.5
+  - @zhin.js/agent-feature@1.1.8
+  - @zhin.js/skill@1.1.8
+  - @zhin.js/host-http@1.1.8
+
+## 1.1.11
+
+### Patch Changes
+
+- 9816c18: 将应用插件装配改为 configVersion: 2：主配置 plugins 映射实例名到包，disable_plugins 控制启停，业务配置使用顶层同名块。package.json 继续保留 features、entry、engine 等包契约，并支持静态 displayName/icon。
+
+  这是配置格式的破坏性更新：旧配置不能继续运行，请先停止 Bot，运行 `zhin migrate instances` 预览，再使用 `--apply` 转换；提供备份与中断继续/回滚，无法无损转换的嵌套、optional 和别名碰撞需人工迁移。Runtime、Console、CLI 与创建向导统一使用新声明。
+
+  保留框架顶层 `menuKeyword` / `menuStyle`，通过当前 generation 的 Root 配置视图供 Command Feature 消费；严格校验和配置修改不会丢失菜单设置，子实例配置保持隔离。
+
+- Updated dependencies [c407bd2]
+- Updated dependencies [064b06d]
+- Updated dependencies [2b4d6dc]
+- Updated dependencies [a50fc8a]
+- Updated dependencies [b58548a]
+- Updated dependencies [e914a93]
+- Updated dependencies [e914a93]
+- Updated dependencies [064b06d]
+  - @zhin.js/core@1.1.46
+  - @zhin.js/feature-kit@1.1.6
+  - @zhin.js/host-http@1.1.7
+  - @zhin.js/permission@1.1.7
+  - @zhin.js/adapter@1.1.20
+  - @zhin.js/agent-feature@1.1.7
+  - @zhin.js/skill@1.1.7
+  - @zhin.js/tool@1.1.7
+
 ## 1.1.10
 
 ### Patch Changes

package/README.md

@@ -24,7 +24,7 @@ pnpm add @zhin.js/adapter-qq
 - `@zhin.js/adapter` — 约定式 `adapters/qq/index.ts`（`defineAdapter`）
 - `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
-- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- 配置经插件 `schema.json` 落到顶层 `<instanceKey>`
 - **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（WebSocket 路径）
 
 入站：`gateway.receive({ conversation, message, content, sender, metadata })`（ConversationRef 结构化寻址）  
@@ -43,15 +43,17 @@ pnpm add @zhin.js/adapter-qq
 ## 最小配置
 
 ```yaml
+configVersion: 2
 # zhin.config.yml（Plugin Runtime）
 plugins:
-  qq:
-    # mode: websocket   # 默认
-    endpoints:
-      - id: my-qq-bot
-        appid: ${QQ_APPID}
-        secret: ${QQ_SECRET}
-        # botKind / intents 可由向导写入；`qq endpoint add` 扫码后会追问公域/私域再写入
+  qq: "@zhin.js/adapter-qq"
+qq:
+  # mode: websocket   # 默认
+  endpoints:
+    - id: my-qq-bot
+      appid: ${QQ_APPID}
+      secret: ${QQ_SECRET}
+      # botKind / intents 可由向导写入；`qq endpoint add` 扫码后会追问公域/私域再写入
 ```
 
 ### botKind 与 intents
@@ -70,35 +72,37 @@ WebSocket Identify 的 `intents` **必须与开放平台已开通的权限一致
 多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`id` 必填）：
 
 ```yaml
+configVersion: 2
 plugins:
-  qq:
-    mode: websocket
-    endpoints:
-      - id: main-bot
-        appid: ${QQ_APPID}
-        secret: ${QQ_SECRET}
-        botKind: public
-        intents:
-          - GROUP_AND_C2C_EVENT
-          - GROUP_MEMBER
-          - GUILDS
-          - GUILD_MEMBERS
-          - DIRECT_MESSAGE
-          - PUBLIC_GUILD_MESSAGES
-      - id: private-bot
-        appid: ${QQ_APPID_2}
-        secret: ${QQ_SECRET_2}
-        botKind: private
-        intents:
-          - GROUP_AND_C2C_EVENT
-          - GROUP_MEMBER
-          - GUILDS
-          - GUILD_MEMBERS
-          - DIRECT_MESSAGE
-          - GUILD_MESSAGES
+  qq: "@zhin.js/adapter-qq"
+qq:
+  mode: websocket
+  endpoints:
+    - id: main-bot
+      appid: ${QQ_APPID}
+      secret: ${QQ_SECRET}
+      botKind: public
+      intents:
+        - GROUP_AND_C2C_EVENT
+        - GROUP_MEMBER
+        - GUILDS
+        - GUILD_MEMBERS
+        - DIRECT_MESSAGE
+        - PUBLIC_GUILD_MESSAGES
+    - id: private-bot
+      appid: ${QQ_APPID_2}
+      secret: ${QQ_SECRET_2}
+      botKind: private
+      intents:
+        - GROUP_AND_C2C_EVENT
+        - GROUP_MEMBER
+        - GUILDS
+        - GUILD_MEMBERS
+        - DIRECT_MESSAGE
+        - GUILD_MESSAGES
 ```
 
-根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-qq`（`instanceKey: qq`）。
+主配置 `plugins` 映射需引用 `@zhin.js/adapter-qq`（`instanceKey: qq`）。
 
 ## Endpoint 管理命令
 
@@ -106,7 +110,7 @@ plugins:
 
 | 命令 | 说明 |
 |------|------|
-| `qq endpoint add [name]` | 手机 QQ 扫码绑定 → **追问公域/私域** → 一次性写入 `.env` + `plugins.qq.endpoints`（重启生效） |
+| `qq endpoint add [name]` | 手机 QQ 扫码绑定 → **追问公域/私域** → 一次性写入 `.env` + `qq.endpoints`（重启生效） |
 | `qq endpoint cancel` | 取消进行中的扫码绑定或待确认的公域/私域选择 |
 | `qq endpoint list` | 列出运行中与配置中的 endpoints |
 | `qq endpoint remove <name>` | 从配置移除 endpoint（`.env` 键保留，可手动清理） |

package/lib/endpoint.js

@@ -1,4 +1,5 @@
 import { installQqUploadDiagnostics } from './upload-diagnostics.js';
+import { projectQqGuildSenderRoles } from './platform-permit.js';
 import { qqDeliveryFailure } from './delivery-error.js';
 import { normalizeQqInteraction } from './interaction.js';
 import { awaitQqStartup } from './start-deadline.js';
@@ -8,7 +9,7 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
  */
 import { Endpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
-import { formatOutbound } from './outbound.js';
+import { collectOutboundImageSizes, formatOutboundMessages } from './outbound.js';
 import { formatInboundContent, parseCompoundMessageId, qqInboundConversation, qqOutboundKind, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
 import { defaultCreateHttpBot, registerQqWebhookRoutes, } from './webhook.js';
 import { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';
@@ -115,26 +116,31 @@ export class QqWebsocketEndpoint extends Endpoint {
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        const body = formatOutbound(payload);
+        // 媒体与 markdown/按钮不能同条发送（msg_type 7 与 2 互斥）：公网图片嵌入 markdown，
+        // 拿不到 URL/尺寸的媒体降级为独立消息先发
+        const messages = formatOutboundMessages(payload, { imageSizes: await collectOutboundImageSizes(payload) });
+        const body = messages[messages.length - 1];
         const kind = qqOutboundKind(conversation);
         const bot = this.#requireBot();
         let result;
         try {
-            switch (kind) {
-                case 'private':
-                    result = await bot.sendPrivateMessage(conversation.id, body);
-                    break;
-                case 'group':
-                    result = await bot.sendGroupMessage(conversation.id, body);
-                    break;
-                case 'channel':
-                    result = await bot.sendGuildMessage(conversation.id, body);
-                    break;
-                case 'direct':
-                    if (!bot.sendDirectMessage)
-                        throw new Error('QQ direct message not supported by transport');
-                    result = await bot.sendDirectMessage(conversation.id, body);
-                    break;
+            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;
+                }
             }
         }
         catch (error) {
@@ -169,6 +175,7 @@ export class QqWebsocketEndpoint extends Endpoint {
             + (msg.authorId ? ` from ${msg.authorId}` : '')
             + (msg.mentioned ? ' (mentioned)' : '')
             + ` | ${truncatePreview(content, 80)}`);
+        const roleProjection = projectQqGuildSenderRoles(msg.authorRoles);
         void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
@@ -177,7 +184,8 @@ export class QqWebsocketEndpoint extends Endpoint {
             sender: {
                 id: msg.authorId,
                 name: senderDisplayName(msg) || undefined,
-                ...(msg.authorRoles?.length ? { roles: msg.authorRoles } : {}),
+                ...(roleProjection.role ? { roles: [roleProjection.role] } : {}),
+                ...(roleProjection.permissions.length ? { permissions: roleProjection.permissions } : {}),
             },
             endpointId: this.#options.config.id,
             ...(msg.mentioned ? { mentioned: true } : {}),
@@ -185,7 +193,8 @@ export class QqWebsocketEndpoint extends Endpoint {
                 channelKind: msg.channelKind,
                 userId: msg.authorId,
                 guildId: msg.guildId,
-                roles: msg.authorRoles,
+                authorRoleIds: msg.authorRoles,
+                ...(roleProjection.role ? { senderRole: roleProjection.role } : {}),
             }),
         }).catch((err) => {
             this.#logger.warn(formatCompact({
@@ -362,26 +371,31 @@ export class QqHttpEndpoint extends Endpoint {
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        const body = formatOutbound(payload);
+        // 媒体与 markdown/按钮不能同条发送（msg_type 7 与 2 互斥）：公网图片嵌入 markdown，
+        // 拿不到 URL/尺寸的媒体降级为独立消息先发
+        const messages = formatOutboundMessages(payload, { imageSizes: await collectOutboundImageSizes(payload) });
+        const body = messages[messages.length - 1];
         const kind = qqOutboundKind(conversation);
         const bot = this.#requireBot();
         let result;
         try {
-            switch (kind) {
-                case 'private':
-                    result = await bot.sendPrivateMessage(conversation.id, body);
-                    break;
-                case 'group':
-                    result = await bot.sendGroupMessage(conversation.id, body);
-                    break;
-                case 'channel':
-                    result = await bot.sendGuildMessage(conversation.id, body);
-                    break;
-                case 'direct':
-                    if (!bot.sendDirectMessage)
-                        throw new Error('QQ direct message not supported by transport');
-                    result = await bot.sendDirectMessage(conversation.id, body);
-                    break;
+            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;
+                }
             }
         }
         catch (error) {
@@ -415,6 +429,7 @@ export class QqHttpEndpoint extends Endpoint {
             + (msg.authorId ? ` from ${msg.authorId}` : '')
             + (msg.mentioned ? ' (mentioned)' : '')
             + ` | ${truncatePreview(content, 80)}`);
+        const roleProjection = projectQqGuildSenderRoles(msg.authorRoles);
         void this.emit('message.receive', {
             conversation,
             message: { conversation, id: msg.id },
@@ -423,7 +438,8 @@ export class QqHttpEndpoint extends Endpoint {
             sender: {
                 id: msg.authorId,
                 name: senderDisplayName(msg) || undefined,
-                ...(msg.authorRoles?.length ? { roles: msg.authorRoles } : {}),
+                ...(roleProjection.role ? { roles: [roleProjection.role] } : {}),
+                ...(roleProjection.permissions.length ? { permissions: roleProjection.permissions } : {}),
             },
             endpointId: this.#options.config.id,
             ...(msg.mentioned ? { mentioned: true } : {}),
@@ -431,7 +447,8 @@ export class QqHttpEndpoint extends Endpoint {
                 channelKind: msg.channelKind,
                 userId: msg.authorId,
                 guildId: msg.guildId,
-                roles: msg.authorRoles,
+                authorRoleIds: msg.authorRoles,
+                ...(roleProjection.role ? { senderRole: roleProjection.role } : {}),
             }),
         }).catch((err) => {
             this.#logger.warn(formatCompact({

package/lib/image-size.d.ts

@@ -0,0 +1,20 @@
+/**
+ * QQ markdown 图片语法 `![alt #宽px #高px](url)` 需要图片尺寸：对公网 URL 图片只读取文件头
+ * （≤64 KiB）解析 PNG / JPEG / GIF / WebP 尺寸。探测失败返回 undefined，由调用方降级。
+ */
+export interface QqImageSize {
+    readonly width: number;
+    readonly height: number;
+}
+export type ImageProbeFetch = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly body?: ReadableStream<Uint8Array> | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+/** 从图片文件头解析尺寸（PNG / GIF / JPEG / WebP）。 */
+export declare function imageSizeFromBytes(bytes: Uint8Array): QqImageSize | undefined;
+/** 读取公网图片文件头得到尺寸；网络错误、超时或格式不识别时返回 undefined。 */
+export declare function probeImageSize(url: string, fetchImpl?: ImageProbeFetch, timeoutMs?: number): Promise<QqImageSize | undefined>;

package/lib/image-size.js

@@ -0,0 +1,99 @@
+const PROBE_BYTES = 64 * 1024;
+const PROBE_TIMEOUT_MS = 3000;
+/** 从图片文件头解析尺寸（PNG / GIF / JPEG / WebP）。 */
+export function imageSizeFromBytes(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const size = (width, height) => width > 0 && height > 0 ? { width, height } : undefined;
+    const ascii = (offset, length) => offset + length <= bytes.length ? String.fromCharCode(...bytes.subarray(offset, offset + length)) : '';
+    // PNG: 8 字节签名 + IHDR
+    if (bytes.length >= 24 && bytes[0] === 0x89 && ascii(1, 3) === 'PNG' && ascii(12, 4) === 'IHDR') {
+        return size(view.getUint32(16), view.getUint32(20));
+    }
+    // GIF87a / GIF89a
+    if (bytes.length >= 10 && (ascii(0, 6) === 'GIF87a' || ascii(0, 6) === 'GIF89a')) {
+        return size(view.getUint16(6, true), view.getUint16(8, true));
+    }
+    // WebP: RIFF....WEBP + VP8 / VP8L / VP8X
+    if (bytes.length >= 30 && ascii(0, 4) === 'RIFF' && ascii(8, 4) === 'WEBP') {
+        const chunk = ascii(12, 4);
+        if (chunk === 'VP8X') {
+            const w = 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16));
+            const h = 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16));
+            return size(w, h);
+        }
+        if (chunk === 'VP8L' && bytes[20] === 0x2f) {
+            const b = view.getUint32(21, true);
+            return size((b & 0x3fff) + 1, ((b >>> 14) & 0x3fff) + 1);
+        }
+        if (chunk === 'VP8 ')
+            return size(view.getUint16(26, true) & 0x3fff, view.getUint16(28, true) & 0x3fff);
+        return undefined;
+    }
+    // JPEG: 扫描 SOFn 段
+    if (bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+        let offset = 2;
+        while (offset + 9 <= bytes.length) {
+            if (bytes[offset] !== 0xff)
+                return undefined;
+            const marker = bytes[offset + 1];
+            if (marker === 0xff) {
+                offset += 1;
+                continue;
+            }
+            if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+                offset += 2;
+                continue;
+            }
+            const length = view.getUint16(offset + 2);
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return size(view.getUint16(offset + 7), view.getUint16(offset + 5));
+            }
+            offset += 2 + length;
+        }
+    }
+    return undefined;
+}
+async function readHead(response) {
+    if (!response.body)
+        return new Uint8Array(await response.arrayBuffer()).subarray(0, PROBE_BYTES);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (total < PROBE_BYTES) {
+            const { done, value } = await reader.read();
+            if (done || !value)
+                break;
+            chunks.push(value);
+            total += value.length;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    const out = new Uint8Array(Math.min(total, PROBE_BYTES));
+    let offset = 0;
+    for (const chunk of chunks) {
+        const take = Math.min(chunk.length, out.length - offset);
+        out.set(chunk.subarray(0, take), offset);
+        offset += take;
+        if (offset >= out.length)
+            break;
+    }
+    return out;
+}
+/** 读取公网图片文件头得到尺寸；网络错误、超时或格式不识别时返回 undefined。 */
+export async function probeImageSize(url, fetchImpl = fetch, timeoutMs = PROBE_TIMEOUT_MS) {
+    try {
+        const response = await fetchImpl(url, {
+            headers: { Range: `bytes=0-${PROBE_BYTES - 1}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return undefined;
+        return imageSizeFromBytes(await readHead(response));
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 export { formatInboundContent, formatOutboundText, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, type QqEndpointConfig, type QqChannelKind, type QqInboundMessage, type QqWireSegment, type ResolvedQqConfig, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig, } from './protocol.js';
 export { DEFAULT_QQ_BOT_KIND, QQ_INTENTS_BY_KIND, defaultQqEndpointIntentFields, parseQqBotKind, resolveQqIntents, type QqBotKind, type QqIntent, } from './qq-intents.js';
-export { formatOutbound, resolveMediaFile, type QqOutboundElem, type QqOutboundMessage, } from './outbound.js';
+export { formatOutbound, formatOutboundMessages, collectOutboundImageSizes, type FormatOutboundMessagesOptions, resolveMediaFile, type QqOutboundElem, type QqOutboundMessage, } from './outbound.js';
+export { imageSizeFromBytes, probeImageSize, type QqImageSize } from './image-size.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, type CreateQqBot, type CreateQqHttpBot, type QqBotTransport, type QqOfficialApi, type QqEndpointOptions, type QqHttpBotTransport, type QqHttpEndpointOptions, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, type QqWebhookHandler, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';

package/lib/index.js

@@ -1,6 +1,7 @@
 export { formatInboundContent, formatOutboundText, resolveOutboundMessageId, resolveQqConfig, senderDisplayName, } from './protocol.js';
 export { DEFAULT_QQ_BOT_KIND, QQ_INTENTS_BY_KIND, defaultQqEndpointIntentFields, parseQqBotKind, resolveQqIntents, } from './qq-intents.js';
-export { formatOutbound, resolveMediaFile, } from './outbound.js';
+export { formatOutbound, formatOutboundMessages, collectOutboundImageSizes, resolveMediaFile, } from './outbound.js';
+export { imageSizeFromBytes, probeImageSize } from './image-size.js';
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from './endpoint.js';
 export { registerQqWebhookRoutes, handleQqWebhookRequest, readRequestBodyText, defaultCreateHttpBot, } from './webhook.js';
 export { bindQqBotInboundEvents, defaultCreateBot, normalizeQqMessage, } from './ws.js';

package/lib/outbound.d.ts

@@ -1,3 +1,4 @@
+import { type QqImageSize } from './image-size.js';
 /** qq-official-bot Sendable 的最小结构子集（字符串模板或消息段）。 */
 export interface QqOutboundElem {
     readonly type: string;
@@ -15,3 +16,25 @@ export declare function resolveMediaFile(data: Record<string, unknown>): string
  * 纯文本输入原样返回（与既有行为一致）；含富媒体段时返回段数组。
  */
 export declare function formatOutbound(payload: unknown): QqOutboundMessage;
+export interface FormatOutboundMessagesOptions {
+    /** 公网图片 URL → 尺寸；有尺寸的图片才能嵌入 markdown（见 collectOutboundImageSizes）。 */
+    readonly imageSizes?: ReadonlyMap<string, QqImageSize>;
+}
+/**
+ * 渲染后 payload → 按序发送的 QQ Sendable 列表。
+ *
+ * QQ 单条消息的 msg_type 只能是一种：富媒体（7，media.file_info）与 markdown/按钮（2）
+ * 互斥，SDK 后处理的段会覆盖 msg_type，导致图片被静默丢弃。处理顺序：
+ * 1. 公网 URL 图片且已知尺寸：按 QQ markdown 语法 `![图片 #宽px #高px](url)` 嵌入同一
+ *    markdown 段（开放平台会下载转存），仍为一条消息；
+ * 2. 其余媒体（base64 / 本地渲染图：v2 /files 上传只返回 file_info，拿不到 URL；或尺寸
+ *    未知、模板 markdown 无法拼接）降级为独立富媒体消息先发，markdown + 按钮作为最后一条
+ *    （返回其消息 ID）。reply 段随每条消息携带，保持被动回复。
+ * 不含媒体与 markdown/按钮冲突时与 formatOutbound 一致（单条）。
+ */
+export declare function formatOutboundMessages(payload: unknown, options?: FormatOutboundMessagesOptions): QqOutboundMessage[];
+/**
+ * 预先探测需要嵌入 markdown 的公网图片尺寸：仅当 payload 同时含图片与 markdown/按钮时，
+ * 对 http(s) URL 图片并发读取文件头；失败的图片不入表，formatOutboundMessages 会降级。
+ */
+export declare function collectOutboundImageSizes(payload: unknown, probe?: (url: string) => Promise<QqImageSize | undefined>): Promise<Map<string, QqImageSize>>;