@zhin.js/adapter-qq 1.1.19 → 1.1.21

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/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(); },
+      };
+    },
+  };
+}