@zhin.js/adapter-qq 1.1.20 → 1.1.22

package/src/outbound.ts

@@ -302,70 +302,61 @@ export interface FormatOutboundMessagesOptions {
   readonly imageSizes?: ReadonlyMap<string, QqImageSize>;
 }
 
-function isElemOf(types: Set<string>) {
-  return (part: string | QqOutboundElem): part is QqOutboundElem => typeof part !== 'string' && types.has(part.type);
+function requireKeyboardMarkdown(messages: QqOutboundMessage[]): QqOutboundMessage[] {
+  if (!messages.length) throw new EndpointDeliveryError('unsupported_operation', 'QQ payload has no sendable content', 'not_sent');
+  for (const message of messages) {
+    const parts: readonly (string | QqOutboundElem)[] = Array.isArray(message) ? message : [message as string | QqOutboundElem];
+    if (parts.some(part => typeof part !== 'string' && (part.type === 'keyboard' || part.type === 'button'))
+      && !parts.some(part => typeof part !== 'string' && part.type === 'markdown')) {
+      throw new EndpointDeliveryError('unsupported_operation', 'QQ keyboard requires Markdown in the same physical message', 'not_sent');
+    }
+  }
+  return messages;
 }
 
 /**
- * 渲染后 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 一致（单条）。
+ * Preserve the original segment order before formatOutbound merges Markdown.
+ * Public images with known dimensions become inline Markdown at their original
+ * position. Other media form physical-message barriers; reply routing is copied
+ * to every resulting message, without moving text across a media barrier.
  */
 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 items = toSegmentList(payload);
+  const rich = items.some(item => typeof item !== 'string' && MARKDOWN_MESSAGE_TYPES.has(item.type));
+  const media = items.some(item => typeof item !== 'string' && SPLIT_MEDIA_TYPES.has(item.type));
+  if (!rich || !media) return requireKeyboardMarkdown([formatOutbound(payload)]);
 
-  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);
+  const replies = items.filter(item => typeof item !== 'string' && item.type === 'reply');
+  const templates = items.some(item => typeof item !== 'string' && item.type === 'markdown' && markdownTemplateId(item.data ?? {}));
+  const messages: QqOutboundMessage[] = [];
+  let pending: Array<string | QqWireSegment> = [];
+  const append = (items: Array<string | QqWireSegment>): void => {
+    const message = formatOutbound(items);
+    const parts = Array.isArray(message) ? message : [message];
+    if (parts.some(part => typeof part === 'string' ? part.length > 0 : part.type !== 'reply')) messages.push(message);
+  };
+  const flush = (): void => {
+    if (!pending.length) return;
+    append([...replies, ...pending]);
+    pending = [];
+  };
+  for (const item of items) {
+    if (typeof item !== 'string' && item.type === 'reply') continue;
+    if (typeof item !== 'string' && SPLIT_MEDIA_TYPES.has(item.type)) {
+      const source = item.type === 'image' && isMediaRef(item.data?.media) ? item.data.media : undefined;
+      const size = !templates && source?.kind === 'url' ? options.imageSizes?.get(source.value) : undefined;
+      if (source?.kind === 'url' && size) {
+        pending.push({ type: 'markdown', data: { content: `![图片 #${size.width}px #${size.height}px](${source.value})` } });
+      } else {
+        flush();
+        append([...replies, item]);
+      }
     } else {
-      rest.push(part);
+      pending.push(item);
     }
   }
-  return [
-    ...separate.map((item): QqOutboundMessage => (replies.length ? [...replies, item] : item)),
-    rest.length === 1 ? rest[0]! : rest,
-  ];
+  flush();
+  return requireKeyboardMarkdown(messages);
 }
 
 /**

package/src/passive-reply.ts

@@ -72,6 +72,18 @@ export class QqPassiveReplyLedger {
    * newest usable source in the conversation. Undefined when only an active message is possible.
    */
   acquire(kind: QqOutboundKind, conversationId: string, preferred?: QqReplySource): PassiveReplyGrant | undefined {
+    const entry = this.#usableSource(kind, conversationId, preferred);
+    if (!entry) return undefined;
+    entry.replies += 1;
+    return { source: entry.source, msgSeq: entry.replies };
+  }
+
+  /** Local stream preflight must not reserve a reply before any content exists. */
+  hasUsableSource(kind: QqOutboundKind, conversationId: string, preferred?: QqReplySource): boolean {
+    return this.#usableSource(kind, conversationId, preferred) !== undefined;
+  }
+
+  #usableSource(kind: QqOutboundKind, conversationId: string, preferred?: QqReplySource): SourceEntry | undefined {
     const limit = QQ_PASSIVE_LIMITS[kind];
     const now = this.now();
     const entries = this.#conversations.get(`${kind}:${conversationId}`) ?? [];
@@ -79,11 +91,8 @@ export class QqPassiveReplyLedger {
       && entry.replies < limit.maxReplies
       && now - entry.receivedAt < limit.windowMs - SAFETY_MARGIN_MS;
     const preferredKey = preferred ? sourceKey(preferred) : undefined;
-    const entry = (preferredKey ? entries.find(item => sourceKey(item.source) === preferredKey && usable(item)) : undefined)
+    return (preferredKey ? entries.find(item => sourceKey(item.source) === preferredKey && usable(item)) : undefined)
       ?? [...entries].reverse().find(usable);
-    if (!entry) return undefined;
-    entry.replies += 1;
-    return { source: entry.source, msgSeq: entry.replies };
   }
 
   /** The platform said this source can no longer be replied to (expired, over the limit, invalid id). */

package/src/protocol.ts

@@ -1,3 +1,4 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 /** QQ Official Bot protocol helpers. Canonicalization is owned by Core. */
 
 import { EndpointDeliveryError, type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
@@ -8,13 +9,16 @@ import { resolveAdapterNotifyTarget, type AdapterNotifyTarget, type ResolvedAdap
 const logger = getLogger('qq');
 
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface QqEndpointConfig {
+export interface QqEndpointConfig extends EndpointProfileConfiguration {
   readonly id: string;
   readonly appid: string;
   readonly secret: string;
   /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
   readonly mode?: 'websocket' | 'webhook' | 'middleware';
   readonly sandbox?: boolean;
+  /** Publish supported C2C replies while generated; false keeps complete delivery. */
+  readonly streaming?: boolean;
+  readonly streamingIntervalMs?: number;
   /** Explicit intents; when omitted, derived from `botKind` (default public). */
   readonly intents?: readonly string[];
   /** public | private — drives default intents when `intents` omitted. */
@@ -34,6 +38,8 @@ export interface ResolvedQqWebsocketConfig {
   readonly appid: string;
   readonly secret: string;
   readonly sandbox: boolean;
+  readonly streaming?: boolean;
+  readonly streamingIntervalMs?: number;
   readonly intents?: readonly string[];
   readonly accessTokenUrl?: string;
   readonly gatewayUrl?: string;
@@ -49,6 +55,8 @@ export interface ResolvedQqHttpConfig {
   readonly secret: string;
   readonly webhookPath: string;
   readonly sandbox: boolean;
+  readonly streaming?: boolean;
+  readonly streamingIntervalMs?: number;
   readonly notify?: ResolvedAdapterNotifyTarget;
 }
 
@@ -90,6 +98,8 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
   const appid = requiredEndpointField(config.appid, 'appid');
   const secret = requiredEndpointField(config.secret, 'secret');
   const mode = config.mode ?? 'websocket';
+  const streamingIntervalMs = config.streamingIntervalMs ?? 500;
+  if (!Number.isFinite(streamingIntervalMs) || streamingIntervalMs < 0) throw new TypeError('streamingIntervalMs must be a non-negative finite number');
   const notify = resolveAdapterNotifyTarget(config.notify);
 
   if (mode === 'webhook' || mode === 'middleware') {
@@ -103,6 +113,8 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
       secret,
       webhookPath,
       sandbox: config.sandbox === true,
+      streaming: config.streaming !== false,
+      streamingIntervalMs,
       ...(notify ? { notify } : {}),
     };
   }
@@ -116,6 +128,8 @@ export function resolveQqConfig(config: QqEndpointConfig): ResolvedQqConfig {
     appid,
     secret,
     sandbox: config.sandbox === true,
+    streaming: config.streaming !== false,
+    streamingIntervalMs,
     intents: resolveQqIntents({
       intents: config.intents,
       botKind: config.botKind,

package/src/qq-console-spec.ts

@@ -14,6 +14,8 @@ export const qqConsoleSpec = {
     { key: 'secret', required: true, env: true, description: 'QQ app secret' },
     { key: 'mode', description: 'websocket, webhook or middleware' },
     { key: 'sandbox', type: 'boolean', description: 'QQ sandbox environment' },
+    { key: 'streaming', type: 'boolean', description: 'Publish supported C2C replies while generating (default true)' },
+    { key: 'streamingIntervalMs', type: 'number', description: 'Delay between reply updates in milliseconds (default 500)' },
     { key: 'botKind', description: 'public or private; existing explicit intents remain authoritative' },
     { key: 'accessTokenUrl', description: 'Configured access-token API URL' },
     { key: 'gatewayUrl', description: 'Configured Gateway discovery URL' },

package/src/self-profile.ts

@@ -0,0 +1,20 @@
+import { createEndpointOperation, type EndpointProfile } from 'zhin.js/adapter';
+import type { Bot } from 'qq-official-bot';
+
+interface QqSelfProfileOptions {
+  readonly client: Pick<Bot, 'getSelfInfo'>;
+  readonly reportAccount: (id: string) => void;
+}
+
+/** QQ official Bot.Info has an actual bot id, display username and public avatar URL. */
+export function createQqSelfProfile({ client, reportAccount }: QqSelfProfileOptions): EndpointProfile {
+  return Object.freeze<EndpointProfile>({
+    writableFields: Object.freeze([]),
+    async read({ signal }) {
+      const self = await createEndpointOperation({ signal }).prepare(() => client.getSelfInfo());
+      if (!self?.id || typeof self.username !== 'string') throw new Error('QQ returned an incomplete bot profile');
+      reportAccount(self.id);
+      return { nickname: self.username, ...(typeof self.avatar === 'string' ? { avatar: self.avatar } : {}) };
+    },
+  });
+}

package/src/side-event-dispatch.ts

@@ -1,4 +1,4 @@
-import { receiveOneBotLikeSideEvent, type OneBotLikeRawEvent } from '@zhin.js/core';
+import { receiveOneBotLikeSideEvent, type OneBotLikeRawEvent } from '@zhin.js/adapter-onebot-events';
 import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
 import type { ApproveJoinRequestOptions } from 'qq-official-bot';

package/src/stream-markdown.ts

@@ -0,0 +1,41 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+
+interface Fence { readonly marker: string; readonly info: string; }
+
+/** Only source-level fenced context is portable to a fresh native Markdown message. */
+export function qqMarkdownContinuation(precedingText: string): { readonly opening: string } {
+  if (!precedingText) return { opening: '' };
+  const fence = openFence(precedingText);
+  if (fence) {
+    if (!precedingText.includes('\n', fence.offset)) throw unsupported();
+    return { opening: `${fence.marker}${fence.info}\n` };
+  }
+  if (/(?:^|\n) {0,3}(?:`{3,}|~{3,})[ \t]*\n?$/.test(precedingText)) return { opening: '' };
+  const boundary = precedingText.lastIndexOf('\n\n');
+  const block = precedingText.slice(boundary >= 0 ? boundary + 2 : 0);
+  // No native contract permits retroactively recreating an unfinished inline
+  // construct in another message. Admit plain continuations and closed blocks.
+  if (/[`*_\[\]~]/.test(block)) throw unsupported();
+  return { opening: '' };
+}
+
+export function qqMarkdownClosing(source: string): string {
+  const fence = openFence(source);
+  return fence ? `${source.endsWith('\n') ? '' : '\n'}${fence.marker}` : '';
+}
+
+function openFence(source: string): (Fence & { readonly offset: number }) | undefined {
+  let active: (Fence & { readonly offset: number }) | undefined;
+  for (const line of source.matchAll(/^ {0,3}(`{3,}|~{3,})([^\n]*)/gm)) {
+    const marker = line[1], info = line[2];
+    if (active) {
+      if (marker[0] === active.marker[0] && marker.length >= active.marker.length && !info.trim()) active = undefined;
+    } else if (marker[0] !== '`' || !info.includes('`')) active = { marker, info, offset: line.index };
+  }
+  return active;
+}
+
+function unsupported(): EndpointDeliveryError {
+  return new EndpointDeliveryError('unsupported_operation',
+    'QQ Markdown continuation requires a plain block boundary or a complete fenced-code header', 'not_sent');
+}

package/src/streaming.ts

@@ -0,0 +1,98 @@
+import type { Bot, PrivateMessageStream } from 'qq-official-bot';
+import { createEndpointOperation, type EndpointMessageStream, type EndpointStreaming, type EndpointStreamRequest,
+  type EndpointStreamAcknowledgement } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { qqDeliveryFailure } from './delivery-error.js';
+import { QQ_PASSIVE_SOURCE_CODES, type PassiveReplyGrant, type QqPassiveReplyLedger, type QqReplySource } from './passive-reply.js';
+import { qqOutboundKind, resolveOutboundMessageId } from './protocol.js';
+import { qqMarkdownClosing, qqMarkdownContinuation } from './stream-markdown.js';
+
+function supportsQqStream(request: Pick<EndpointStreamRequest, 'conversation' | 'source'>): boolean {
+  return qqOutboundKind(request.conversation) === 'private';
+}
+
+/** C2C native streams share the ordinary passive ledger, source and sequence. */
+export function createQqStreaming(getBot: () => Bot, ledger: QqPassiveReplyLedger, minIntervalMs = 500): EndpointStreaming {
+  return {
+    mode: 'native',
+    minIntervalMs,
+    supports: supportsQqStream,
+    open(request): EndpointMessageStream | undefined {
+      if (!supportsQqStream(request)) return undefined;
+      // stream_messages has no verified canonical mention/keyboard projection.
+      // Keep these combinations on the complete-message codec instead of guessing.
+      if (request.prefix?.some(segment => segment.type !== 'reply')) return undefined;
+      const reply = request.prefix?.find(segment => segment.type === 'reply');
+      const explicitId = reply && 'message_id' in reply.data ? reply.data.message_id : undefined;
+      const preferred: QqReplySource | undefined = typeof explicitId === 'string' && explicitId
+        ? { id: explicitId }
+        : request.source?.messageId ? { id: request.source.messageId } : undefined;
+      if (!ledger.hasUsableSource('private', request.conversation.id, preferred)) return undefined;
+      const precedingText = request.continuation?.precedingText ?? '';
+      const opening = request.format === 'markdown' ? qqMarkdownContinuation(precedingText).opening : '';
+      const cancellation = new AbortController();
+      const signal = request.signal ? AbortSignal.any([request.signal, cancellation.signal]) : cancellation.signal;
+      const operation = createEndpointOperation({ signal });
+      let native: PrivateMessageStream | undefined;
+      let grant: PassiveReplyGrant | undefined;
+      let acceptedText = '';
+      let messageId: string | undefined;
+      let exhausted = false;
+      let contentUnavailable = Boolean(opening);
+      let openingSent = false;
+      let failure: unknown;
+      let completion: Promise<EndpointStreamAcknowledgement> | undefined;
+      const acknowledgement = (): EndpointStreamAcknowledgement => ({
+        status: messageId ? 'sent' : 'buffered', acceptedText, ...(messageId ? { messageId } : {}),
+        ...(exhausted ? { exhausted: true as const } : {}),
+        ...(contentUnavailable ? { contentUnavailable: true as const } : {}),
+      });
+      const send = async (text: string, final: boolean): Promise<EndpointStreamAcknowledgement> => {
+        if (failure) throw failure;
+        if (signal.aborted) throw new EndpointDeliveryError('endpoint_inactive', 'QQ stream cancelled', 'not_sent');
+        if (!text.startsWith(acceptedText)) throw new EndpointDeliveryError('invalid_payload', 'QQ stream cannot replace its accepted prefix', 'not_sent');
+        if (!final && (text === acceptedText || exhausted)) return acknowledgement();
+        if (final && exhausted && text !== acceptedText) throw new EndpointDeliveryError('stream_capacity', 'QQ exhausted stream must finish its accepted prefix', 'not_sent');
+        if (!native) {
+          if (!text) return acknowledgement();
+          grant = ledger.acquire('private', request.conversation.id, preferred);
+          if (!grant) throw new EndpointDeliveryError('unsupported_operation', 'QQ stream has no usable passive reply source', 'not_sent');
+          native = getBot().createPrivateStream(request.conversation.id, {
+            source: grant.source, msgSeq: grant.msgSeq,
+            contentType: request.format, inputMode: 'append',
+          });
+        }
+        try {
+          const closing = final && request.format === 'markdown' ? qqMarkdownClosing(precedingText + text) : '';
+          // An exhausted container permits only the terminating state frame;
+          // no extra formatting characters may exceed its confirmed capacity.
+          const suffix = exhausted ? '' : closing;
+          const delta = (openingSent ? '' : opening) + text.slice(acceptedText.length) + suffix;
+          const result = await operation.run(() => final ? native!.end(delta) : native!.write(delta));
+          const id = resolveOutboundMessageId(result);
+          messageId = `private-${request.conversation.id}:${id}`;
+          acceptedText = text;
+          openingSent = true;
+          contentUnavailable ||= Boolean(closing);
+          // Zero is exhausted regardless of the platform's otherwise unspecified unit.
+          exhausted = result.remain_msg_len === 0;
+          return acknowledgement();
+        } catch (error) {
+          const result = qqDeliveryFailure(error);
+          if (grant && result.diagnostic.platformCode !== undefined && QQ_PASSIVE_SOURCE_CODES.has(result.diagnostic.platformCode)) {
+            ledger.exhaust('private', request.conversation.id, grant.source);
+          }
+          failure = result.failure;
+          throw failure;
+        }
+      };
+      return {
+        write: text => completion
+          ? Promise.reject(new EndpointDeliveryError('stream_closed', 'QQ stream is finishing', 'not_sent'))
+          : send(text, false),
+        finish: text => completion ??= send(text, true),
+        cancel: () => { cancellation.abort(); },
+      };
+    },
+  };
+}