@zhin.js/adapter-qq 1.1.10 → 1.1.12

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.10",
+  "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.19",
-    "@zhin.js/agent-feature": "1.1.6",
-    "@zhin.js/core": "1.1.45",
-    "@zhin.js/feature-kit": "1.1.5",
-    "@zhin.js/host-http": "1.1.6",
-    "@zhin.js/im-contract": "1.1.4",
+    "@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.8",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.6",
-    "@zhin.js/skill": "1.1.6",
-    "@zhin.js/tool": "1.1.6"
+    "@zhin.js/tool": "1.1.8"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.19",
-    "@zhin.js/command": "^1.1.7",
-    "@zhin.js/core": "^1.1.45",
-    "@zhin.js/middleware": "^1.1.6",
-    "zhin.js": "^1.1.10"
+    "@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.6",
-    "zhin.js": "1.1.10"
+    "@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,