@zhin.js/adapter-qq 1.1.11 → 1.1.12

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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

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>>;

package/lib/outbound.js

@@ -8,13 +8,16 @@
  *   归一到 data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
  * - markdown：data.content 原文，或 custom_template_id + params 模板。
  * - keyboard：data.rows 按钮矩阵展开为 button 段（SDK processButtons 组装
- *   keyboard 载荷）；按钮消息必须带 markdown，故同行文本合并为 markdown 段。
+ *   keyboard 载荷）；按钮消息必须带 markdown，且一条消息只承载一个 markdown、
+ *   msg_type=2 时 content 不展示，故含按钮或内联 markdown 时文本与内联 markdown
+ *   段按顺序合并为同一 markdown 段（模板 markdown 原样透传）。
  *   data.id 模板键盘原样透传。
  * canonical share 当前明确 not_sent/unsupported，避免静默丢标题/描述/URL。
  * 其他未识别段保持既有 data.text fallback；正常发送另受声明的 supported 白名单约束。
  */
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
+import { probeImageSize } from './image-size.js';
 const logger = getLogger('qq');
 /**
  * 解析 image/audio/video/file 段的投递源（canonical MediaRef 唯一来源）：
@@ -57,13 +60,16 @@ function normalizeMediaSegment(seg) {
     }
     return { type: seg.type, data: { file } };
 }
-function normalizeMarkdownSegment(seg) {
-    const data = seg.data ?? {};
-    const templateId = typeof data.custom_template_id === 'string' && data.custom_template_id
+function markdownTemplateId(data) {
+    return typeof data.custom_template_id === 'string' && data.custom_template_id
         ? data.custom_template_id
         : typeof data.template_id === 'string' && data.template_id
             ? data.template_id
             : undefined;
+}
+function normalizeMarkdownSegment(seg) {
+    const data = seg.data ?? {};
+    const templateId = markdownTemplateId(data);
     if (templateId) {
         return {
             type: 'markdown',
@@ -155,16 +161,38 @@ export function formatOutbound(payload) {
                 ? JSON.stringify(payload)
                 : String(payload);
     }
-    // QQ 按钮消息必须携带 markdown（msg_type=2），keyboard 存在时文本合并为 markdown 段
+    // 一条 QQ 消息只有一个 markdown 字段（SDK handleMarkdown 后者覆盖前者），且 msg_type=2
+    // 时 content 文本不展示。按钮消息必须携带 markdown；含内联 markdown 的消息同理：
+    // 文本与内联 markdown 按顺序合并为同一 markdown 段（落在首次出现的位置），避免正文被丢弃。
+    // 模板 markdown（custom_template_id）无法拼接，保持原样。
     const hasKeyboard = segments.some((item) => typeof item !== 'string' && item.type === 'keyboard');
+    const hasInlineMarkdown = segments.some((item) => typeof item !== 'string' && item.type === 'markdown' && !markdownTemplateId(item.data ?? {}));
+    const mergeIntoMarkdown = hasKeyboard || hasInlineMarkdown;
     const parts = [];
+    let markdownSlot;
+    let lastPieceWasMarkdown = false;
+    const appendMarkdown = (piece, isMarkdown) => {
+        if (!piece)
+            return;
+        if (!markdownSlot) {
+            markdownSlot = { type: 'markdown', data: { content: '' } };
+            parts.push(markdownSlot);
+        }
+        const current = markdownSlot.data.content;
+        const needsBreak = current.trim() !== '' && (isMarkdown || lastPieceWasMarkdown);
+        markdownSlot.data.content = needsBreak
+            ? `${current.replace(/\s+$/, '')}\n\n${piece.replace(/^\s+/, '')}`
+            : current + piece;
+        lastPieceWasMarkdown = isMarkdown;
+    };
     let textBuf = '';
     const flushText = () => {
         if (!textBuf)
             return;
-        parts.push(hasKeyboard
-            ? { type: 'markdown', data: { content: textBuf } }
-            : textBuf);
+        if (mergeIntoMarkdown)
+            appendMarkdown(textBuf, false);
+        else
+            parts.push(textBuf);
         textBuf = '';
     };
     for (const item of segments) {
@@ -198,10 +226,15 @@ export function formatOutbound(payload) {
                 break;
             }
             case 'markdown': {
-                flushText();
                 const markdown = normalizeMarkdownSegment(item);
-                if (markdown)
-                    parts.push(markdown);
+                if (!markdown)
+                    break;
+                flushText();
+                if (mergeIntoMarkdown && typeof markdown.data.content === 'string') {
+                    appendMarkdown(markdown.data.content, true);
+                    break;
+                }
+                parts.push(markdown);
                 break;
             }
             case 'keyboard': {
@@ -229,9 +262,107 @@ export function formatOutbound(payload) {
         }
     }
     flushText();
+    if (markdownSlot && !markdownSlot.data.content.trim())
+        parts.splice(parts.indexOf(markdownSlot), 1);
     if (parts.length === 0)
         return '';
     if (parts.length === 1)
         return parts[0];
     return parts;
 }
+/** SDK 能作为 msg_type=7 富媒体发送的段 */
+const SPLIT_MEDIA_TYPES = new Set(['image', 'audio', 'video']);
+/** 走 msg_type=2 的 markdown/按钮段 */
+const MARKDOWN_MESSAGE_TYPES = new Set(['markdown', 'keyboard', 'button']);
+function isElemOf(types) {
+    return (part) => typeof part !== 'string' && types.has(part.type);
+}
+/**
+ * 渲染后 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 function formatOutboundMessages(payload, options = {}) {
+    const body = formatOutbound(payload);
+    if (!Array.isArray(body))
+        return [body];
+    const elems = body;
+    const isMedia = isElemOf(SPLIT_MEDIA_TYPES);
+    if (!elems.some(isMedia) || !elems.some(isElemOf(MARKDOWN_MESSAGE_TYPES)))
+        return [body];
+    const markdownIndex = elems.findIndex(isElemOf(new Set(['markdown'])));
+    const markdownElem = markdownIndex >= 0 ? elems[markdownIndex] : undefined;
+    const markdownContent = markdownElem ? markdownElem.data.content : '';
+    const embedded = new Set();
+    let merged;
+    if (typeof markdownContent === 'string') {
+        const before = [];
+        const after = [];
+        elems.forEach((part, index) => {
+            if (!isMedia(part) || part.type !== 'image' || typeof part.data.url !== 'string')
+                return;
+            const size = options.imageSizes?.get(part.data.url);
+            if (!size)
+                return;
+            (markdownIndex < 0 || index < markdownIndex ? before : after)
+                .push(`![图片 #${size.width}px #${size.height}px](${part.data.url})`);
+            embedded.add(part);
+        });
+        if (embedded.size > 0) {
+            merged = { type: 'markdown', data: { content: [...before, markdownContent, ...after].filter((piece) => piece.trim()).join('\n\n') } };
+        }
+    }
+    const replies = elems.filter(isElemOf(new Set(['reply'])));
+    const separate = [];
+    const rest = [];
+    let mergedPlaced = false;
+    for (const part of elems) {
+        if (merged && (part === markdownElem || (!markdownElem && embedded.has(part)))) {
+            if (!mergedPlaced)
+                rest.push(merged);
+            mergedPlaced = true;
+        }
+        else if (embedded.has(part)) {
+            continue;
+        }
+        else if (isMedia(part)) {
+            separate.push(part);
+        }
+        else {
+            rest.push(part);
+        }
+    }
+    return [
+        ...separate.map((item) => (replies.length ? [...replies, item] : item)),
+        rest.length === 1 ? rest[0] : rest,
+    ];
+}
+/**
+ * 预先探测需要嵌入 markdown 的公网图片尺寸：仅当 payload 同时含图片与 markdown/按钮时，
+ * 对 http(s) URL 图片并发读取文件头；失败的图片不入表，formatOutboundMessages 会降级。
+ */
+export async function collectOutboundImageSizes(payload, probe = (url) => probeImageSize(url)) {
+    const sizes = new Map();
+    const segments = toSegmentList(payload).filter((item) => typeof item !== 'string');
+    if (!segments.some((item) => MARKDOWN_MESSAGE_TYPES.has(item.type)))
+        return sizes;
+    const urls = new Set();
+    for (const item of segments) {
+        const media = item.type === 'image' ? (item.data ?? {}).media : undefined;
+        if (isMediaRef(media) && media.kind === 'url' && /^https?:\/\//i.test(media.value))
+            urls.add(media.value);
+    }
+    await Promise.all([...urls].map(async (url) => {
+        const size = await probe(url);
+        if (size)
+            sizes.set(url, size);
+    }));
+    return sizes;
+}

package/lib/platform-permit.d.ts

@@ -12,4 +12,9 @@ export declare function normalizeQqGuildSenderForPermit(input: {
     role?: string;
     permissions?: string[];
 };
+/** 入站角色投影：规范角色 owner / admin 进 roles，原始角色 id 进 permissions（`role:<id>`）。 */
+export declare function projectQqGuildSenderRoles(authorRoles: readonly string[] | undefined): {
+    role?: 'owner' | 'admin';
+    permissions: string[];
+};
 export declare function checkQqPlatformPermit(perm: string, subject: PermissionSubject): boolean;

package/lib/platform-permit.js

@@ -22,6 +22,23 @@ export function normalizeQqGuildSenderForPermit(input) {
     }
     return { role: 'member', permissions };
 }
+/**
+ * QQ 官方频道事件 `member.roles` 中的内置身份 id：4 = 频道主，2 = 超级管理员。
+ * 事件已自带，无需额外 API；其余 id（含 5 子频道管理员）不视为 admin。
+ */
+const QQ_GUILD_OWNER_ROLE_ID = '4';
+const QQ_GUILD_ADMIN_ROLE_ID = '2';
+/** 入站角色投影：规范角色 owner / admin 进 roles，原始角色 id 进 permissions（`role:<id>`）。 */
+export function projectQqGuildSenderRoles(authorRoles) {
+    const ids = authorRoles ?? [];
+    const projected = normalizeQqGuildSenderForPermit({
+        roles: ids.map((id) => `role:${id}`),
+        isOwner: ids.includes(QQ_GUILD_OWNER_ROLE_ID),
+        isAdmin: ids.includes(QQ_GUILD_ADMIN_ROLE_ID),
+    });
+    const role = projected.role === 'owner' || projected.role === 'admin' ? projected.role : undefined;
+    return { ...(role ? { role } : {}), permissions: projected.permissions ?? [] };
+}
 export function checkQqPlatformPermit(perm, subject) {
     const role = subject.sender?.role?.[0];
     const permissions = subject.sender?.permissions ?? [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "1.1.11",
+  "version": "1.1.12",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,24 +34,24 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.3.1",
-    "@zhin.js/adapter": "1.1.20",
-    "@zhin.js/agent-feature": "1.1.7",
-    "@zhin.js/core": "1.1.46",
-    "@zhin.js/feature-kit": "1.1.6",
-    "@zhin.js/host-http": "1.1.7",
-    "@zhin.js/im-contract": "1.1.4",
-    "@zhin.js/logger": "1.1.2",
+    "@zhin.js/adapter": "1.1.21",
+    "@zhin.js/agent-feature": "1.1.8",
+    "@zhin.js/core": "1.1.47",
+    "@zhin.js/feature-kit": "1.1.7",
+    "@zhin.js/host-http": "1.1.8",
+    "@zhin.js/im-contract": "1.1.5",
     "@zhin.js/permission": "1.1.7",
-    "@zhin.js/skill": "1.1.7",
-    "@zhin.js/tool": "1.1.7"
+    "@zhin.js/skill": "1.1.8",
+    "@zhin.js/logger": "1.1.2",
+    "@zhin.js/tool": "1.1.8"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.20",
-    "@zhin.js/command": "^1.1.8",
-    "@zhin.js/core": "^1.1.46",
-    "@zhin.js/middleware": "^1.1.7",
-    "zhin.js": "^1.1.11"
+    "@zhin.js/adapter": "^1.1.21",
+    "@zhin.js/command": "^1.1.9",
+    "@zhin.js/core": "^1.1.47",
+    "@zhin.js/middleware": "^1.1.8",
+    "zhin.js": "^1.1.12"
   },
   "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.7",
-    "zhin.js": "1.1.11"
+    "@zhin.js/host-http": "1.1.8",
+    "zhin.js": "1.1.12"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -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';
@@ -18,7 +19,7 @@ import {
 import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
-import { formatOutbound } from './outbound.js';
+import { collectOutboundImageSizes, formatOutboundMessages } from './outbound.js';
 import {
   formatInboundContent,
   parseCompoundMessageId,
@@ -160,25 +161,30 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    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: unknown;
     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) {
       const { failure, diagnostic } = qqDeliveryFailure(error);
@@ -217,6 +223,7 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
       + (msg.mentioned ? ' (mentioned)' : '')
       + ` | ${truncatePreview(content, 80)}`,
     );
+    const roleProjection = projectQqGuildSenderRoles(msg.authorRoles);
     void this.emit('message.receive', {
       conversation,
       message: { conversation, id: msg.id },
@@ -225,7 +232,8 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
       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 } : {}),
@@ -233,7 +241,8 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
         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({
@@ -415,25 +424,30 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    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: unknown;
     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) {
       const { failure, diagnostic } = qqDeliveryFailure(error);
@@ -471,6 +485,7 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
       + (msg.mentioned ? ' (mentioned)' : '')
       + ` | ${truncatePreview(content, 80)}`,
     );
+    const roleProjection = projectQqGuildSenderRoles(msg.authorRoles);
     void this.emit('message.receive', {
       conversation,
       message: { conversation, id: msg.id },
@@ -479,7 +494,8 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
       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 } : {}),
@@ -487,7 +503,8 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
         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/src/image-size.ts

@@ -0,0 +1,110 @@
+/**
+ * QQ markdown 图片语法 `![alt #宽px #高px](url)` 需要图片尺寸：对公网 URL 图片只读取文件头
+ * （≤64 KiB）解析 PNG / JPEG / GIF / WebP 尺寸。探测失败返回 undefined，由调用方降级。
+ */
+export interface QqImageSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+const PROBE_BYTES = 64 * 1024;
+const PROBE_TIMEOUT_MS = 3000;
+
+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 function imageSizeFromBytes(bytes: Uint8Array): QqImageSize | undefined {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const size = (width: number, height: number): QqImageSize | undefined =>
+    width > 0 && height > 0 ? { width, height } : undefined;
+  const ascii = (offset: number, length: number): string =>
+    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: Awaited<ReturnType<ImageProbeFetch>>): Promise<Uint8Array> {
+  if (!response.body) return new Uint8Array(await response.arrayBuffer()).subarray(0, PROBE_BYTES);
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  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: string,
+  fetchImpl: ImageProbeFetch = fetch as unknown as ImageProbeFetch,
+  timeoutMs = PROBE_TIMEOUT_MS,
+): Promise<QqImageSize | undefined> {
+  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/src/index.ts

@@ -25,11 +25,16 @@ export {
 
 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,

package/src/outbound.ts

@@ -8,7 +8,9 @@
  *   归一到 data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
  * - markdown：data.content 原文，或 custom_template_id + params 模板。
  * - keyboard：data.rows 按钮矩阵展开为 button 段（SDK processButtons 组装
- *   keyboard 载荷）；按钮消息必须带 markdown，故同行文本合并为 markdown 段。
+ *   keyboard 载荷）；按钮消息必须带 markdown，且一条消息只承载一个 markdown、
+ *   msg_type=2 时 content 不展示，故含按钮或内联 markdown 时文本与内联 markdown
+ *   段按顺序合并为同一 markdown 段（模板 markdown 原样透传）。
  *   data.id 模板键盘原样透传。
  * canonical share 当前明确 not_sent/unsupported，避免静默丢标题/描述/URL。
  * 其他未识别段保持既有 data.text fallback；正常发送另受声明的 supported 白名单约束。
@@ -16,6 +18,7 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import type { QqWireSegment } from './protocol.js';
+import { probeImageSize, type QqImageSize } from './image-size.js';
 
 const logger = getLogger('qq');
 
@@ -79,13 +82,17 @@ function normalizeMediaSegment(seg: QqWireSegment): QqOutboundElem | null {
   return { type: seg.type, data: { file } };
 }
 
-function normalizeMarkdownSegment(seg: QqWireSegment): QqOutboundElem | null {
-  const data = seg.data ?? {};
-  const templateId = typeof data.custom_template_id === 'string' && data.custom_template_id
+function markdownTemplateId(data: Record<string, unknown>): string | undefined {
+  return typeof data.custom_template_id === 'string' && data.custom_template_id
     ? data.custom_template_id
     : typeof data.template_id === 'string' && data.template_id
       ? data.template_id
       : undefined;
+}
+
+function normalizeMarkdownSegment(seg: QqWireSegment): QqOutboundElem | null {
+  const data = seg.data ?? {};
+  const templateId = markdownTemplateId(data);
   if (templateId) {
     return {
       type: 'markdown',
@@ -179,18 +186,39 @@ export function formatOutbound(payload: unknown): QqOutboundMessage {
         : String(payload);
   }
 
-  // QQ 按钮消息必须携带 markdown（msg_type=2），keyboard 存在时文本合并为 markdown 段
+  // 一条 QQ 消息只有一个 markdown 字段（SDK handleMarkdown 后者覆盖前者），且 msg_type=2
+  // 时 content 文本不展示。按钮消息必须携带 markdown；含内联 markdown 的消息同理：
+  // 文本与内联 markdown 按顺序合并为同一 markdown 段（落在首次出现的位置），避免正文被丢弃。
+  // 模板 markdown（custom_template_id）无法拼接，保持原样。
   const hasKeyboard = segments.some(
     (item) => typeof item !== 'string' && item.type === 'keyboard',
   );
+  const hasInlineMarkdown = segments.some(
+    (item) => typeof item !== 'string' && item.type === 'markdown' && !markdownTemplateId(item.data ?? {}),
+  );
+  const mergeIntoMarkdown = hasKeyboard || hasInlineMarkdown;
 
   const parts: Array<string | QqOutboundElem> = [];
+  let markdownSlot: { type: 'markdown'; data: { content: string } } | undefined;
+  let lastPieceWasMarkdown = false;
+  const appendMarkdown = (piece: string, isMarkdown: boolean): void => {
+    if (!piece) return;
+    if (!markdownSlot) {
+      markdownSlot = { type: 'markdown', data: { content: '' } };
+      parts.push(markdownSlot);
+    }
+    const current = markdownSlot.data.content;
+    const needsBreak = current.trim() !== '' && (isMarkdown || lastPieceWasMarkdown);
+    markdownSlot.data.content = needsBreak
+      ? `${current.replace(/\s+$/, '')}\n\n${piece.replace(/^\s+/, '')}`
+      : current + piece;
+    lastPieceWasMarkdown = isMarkdown;
+  };
   let textBuf = '';
   const flushText = (): void => {
     if (!textBuf) return;
-    parts.push(hasKeyboard
-      ? { type: 'markdown', data: { content: textBuf } }
-      : textBuf);
+    if (mergeIntoMarkdown) appendMarkdown(textBuf, false);
+    else parts.push(textBuf);
     textBuf = '';
   };
 
@@ -223,9 +251,14 @@ export function formatOutbound(payload: unknown): QqOutboundMessage {
         break;
       }
       case 'markdown': {
-        flushText();
         const markdown = normalizeMarkdownSegment(item);
-        if (markdown) parts.push(markdown);
+        if (!markdown) break;
+        flushText();
+        if (mergeIntoMarkdown && typeof markdown.data.content === 'string') {
+          appendMarkdown(markdown.data.content, true);
+          break;
+        }
+        parts.push(markdown);
         break;
       }
       case 'keyboard': {
@@ -252,8 +285,108 @@ export function formatOutbound(payload: unknown): QqOutboundMessage {
     }
   }
   flushText();
+  if (markdownSlot && !markdownSlot.data.content.trim()) parts.splice(parts.indexOf(markdownSlot), 1);
 
   if (parts.length === 0) return '';
   if (parts.length === 1) return parts[0]!;
   return parts;
 }
+
+/** SDK 能作为 msg_type=7 富媒体发送的段 */
+const SPLIT_MEDIA_TYPES = new Set(['image', 'audio', 'video']);
+/** 走 msg_type=2 的 markdown/按钮段 */
+const MARKDOWN_MESSAGE_TYPES = new Set(['markdown', 'keyboard', 'button']);
+
+export interface FormatOutboundMessagesOptions {
+  /** 公网图片 URL → 尺寸；有尺寸的图片才能嵌入 markdown（见 collectOutboundImageSizes）。 */
+  readonly imageSizes?: ReadonlyMap<string, QqImageSize>;
+}
+
+function isElemOf(types: Set<string>) {
+  return (part: string | QqOutboundElem): part is QqOutboundElem => typeof part !== 'string' && types.has(part.type);
+}
+
+/**
+ * 渲染后 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 function formatOutboundMessages(payload: unknown, options: FormatOutboundMessagesOptions = {}): QqOutboundMessage[] {
+  const body = formatOutbound(payload);
+  if (!Array.isArray(body)) return [body as QqOutboundMessage];
+  const elems = body as ReadonlyArray<string | QqOutboundElem>;
+  const isMedia = isElemOf(SPLIT_MEDIA_TYPES);
+  if (!elems.some(isMedia) || !elems.some(isElemOf(MARKDOWN_MESSAGE_TYPES))) return [body];
+
+  const markdownIndex = elems.findIndex(isElemOf(new Set(['markdown'])));
+  const markdownElem = markdownIndex >= 0 ? elems[markdownIndex] as QqOutboundElem : undefined;
+  const markdownContent = markdownElem ? markdownElem.data.content : '';
+  const embedded = new Set<QqOutboundElem>();
+  let merged: QqOutboundElem | undefined;
+  if (typeof markdownContent === 'string') {
+    const before: string[] = [];
+    const after: string[] = [];
+    elems.forEach((part, index) => {
+      if (!isMedia(part) || part.type !== 'image' || typeof part.data.url !== 'string') return;
+      const size = options.imageSizes?.get(part.data.url);
+      if (!size) return;
+      (markdownIndex < 0 || index < markdownIndex ? before : after)
+        .push(`![图片 #${size.width}px #${size.height}px](${part.data.url})`);
+      embedded.add(part);
+    });
+    if (embedded.size > 0) {
+      merged = { type: 'markdown', data: { content: [...before, markdownContent, ...after].filter((piece) => piece.trim()).join('\n\n') } };
+    }
+  }
+
+  const replies = elems.filter(isElemOf(new Set(['reply'])));
+  const separate: QqOutboundElem[] = [];
+  const rest: Array<string | QqOutboundElem> = [];
+  let mergedPlaced = false;
+  for (const part of elems) {
+    if (merged && (part === markdownElem || (!markdownElem && embedded.has(part as QqOutboundElem)))) {
+      if (!mergedPlaced) rest.push(merged);
+      mergedPlaced = true;
+    } else if (embedded.has(part as QqOutboundElem)) {
+      continue;
+    } else if (isMedia(part)) {
+      separate.push(part);
+    } else {
+      rest.push(part);
+    }
+  }
+  return [
+    ...separate.map((item): QqOutboundMessage => (replies.length ? [...replies, item] : item)),
+    rest.length === 1 ? rest[0]! : rest,
+  ];
+}
+
+/**
+ * 预先探测需要嵌入 markdown 的公网图片尺寸：仅当 payload 同时含图片与 markdown/按钮时，
+ * 对 http(s) URL 图片并发读取文件头；失败的图片不入表，formatOutboundMessages 会降级。
+ */
+export async function collectOutboundImageSizes(
+  payload: unknown,
+  probe: (url: string) => Promise<QqImageSize | undefined> = (url) => probeImageSize(url),
+): Promise<Map<string, QqImageSize>> {
+  const sizes = new Map<string, QqImageSize>();
+  const segments = toSegmentList(payload).filter((item): item is QqWireSegment => typeof item !== 'string');
+  if (!segments.some((item) => MARKDOWN_MESSAGE_TYPES.has(item.type))) return sizes;
+  const urls = new Set<string>();
+  for (const item of segments) {
+    const media = item.type === 'image' ? (item.data ?? {}).media : undefined;
+    if (isMediaRef(media) && media.kind === 'url' && /^https?:\/\//i.test(media.value)) urls.add(media.value);
+  }
+  await Promise.all([...urls].map(async (url) => {
+    const size = await probe(url);
+    if (size) sizes.set(url, size);
+  }));
+  return sizes;
+}

package/src/platform-permit.ts

@@ -36,6 +36,28 @@ export function normalizeQqGuildSenderForPermit(input: {
   return { role: 'member', permissions };
 }
 
+/**
+ * QQ 官方频道事件 `member.roles` 中的内置身份 id：4 = 频道主，2 = 超级管理员。
+ * 事件已自带，无需额外 API；其余 id（含 5 子频道管理员）不视为 admin。
+ */
+const QQ_GUILD_OWNER_ROLE_ID = '4';
+const QQ_GUILD_ADMIN_ROLE_ID = '2';
+
+/** 入站角色投影：规范角色 owner / admin 进 roles，原始角色 id 进 permissions（`role:<id>`）。 */
+export function projectQqGuildSenderRoles(authorRoles: readonly string[] | undefined): {
+  role?: 'owner' | 'admin';
+  permissions: string[];
+} {
+  const ids = authorRoles ?? [];
+  const projected = normalizeQqGuildSenderForPermit({
+    roles: ids.map((id) => `role:${id}`),
+    isOwner: ids.includes(QQ_GUILD_OWNER_ROLE_ID),
+    isAdmin: ids.includes(QQ_GUILD_ADMIN_ROLE_ID),
+  });
+  const role = projected.role === 'owner' || projected.role === 'admin' ? projected.role : undefined;
+  return { ...(role ? { role } : {}), permissions: projected.permissions ?? [] };
+}
+
 export function checkQqPlatformPermit(perm: string, subject: PermissionSubject): boolean {
   const role = subject.sender?.role?.[0];
   const permissions = subject.sender?.permissions ?? [];