@zhin.js/adapter-qq 1.1.10 → 1.1.12

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 ?? [];