@zhin.js/adapter-icqq 8.0.12 → 8.0.14

package/lib/icqq-login-assist.js

@@ -0,0 +1,109 @@
+import { formatCompact } from '@zhin.js/logger';
+/**
+ * Drive ICQQ login challenges through LoginAssist (refresh-safe pending tasks).
+ * Mirrors the classic stdin flow: qrcode/auth → login(); slider → submitSlider;
+ * device → sendSmsCode then submitSmsCode.
+ */
+export async function runIcqqLoginAssistStep(input) {
+    const { assist, client, adapter, endpointKey, owner, logger, step, event } = input;
+    assist.cancelOwned(owner, `replaced_by_${step}`);
+    const payload = buildPayload(step, event);
+    logger.info(formatCompact({
+        op: 'login_assist_pending',
+        endpoint: endpointKey,
+        type: step,
+        message: payload.message,
+        ...(typeof payload.url === 'string' ? { url: payload.url } : {}),
+    }));
+    try {
+        if (step === 'device') {
+            try {
+                await client.sendSmsCode();
+            }
+            catch (error) {
+                logger.warn(formatCompact({
+                    op: 'login_assist_send_sms_failed',
+                    endpoint: endpointKey,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+        }
+        const value = await assist.waitForInput(adapter, endpointKey, step, payload, { owner });
+        const text = normalizeSubmitValue(value);
+        switch (step) {
+            case 'qrcode':
+            case 'auth':
+                await client.login();
+                break;
+            case 'slider':
+                await client.submitSlider(text);
+                break;
+            case 'device':
+            case 'sms':
+                await client.submitSmsCode(text);
+                break;
+            default:
+                await client.login();
+                break;
+        }
+    }
+    catch (error) {
+        logger.warn(formatCompact({
+            op: 'login_assist_failed',
+            endpoint: endpointKey,
+            type: step,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
+}
+function buildPayload(step, event) {
+    const raw = event && typeof event === 'object' ? event : {};
+    switch (step) {
+        case 'qrcode':
+            return {
+                message: '扫码登录：请在手机 QQ 扫描二维码，完成后在 Console / 终端确认继续',
+                image: bufferToDataUrl(raw.image),
+            };
+        case 'slider':
+            return {
+                message: '滑动验证：打开链接完成滑块，将返回的 ticket（可含 randstr）提交继续',
+                url: typeof raw.url === 'string' ? raw.url : undefined,
+            };
+        case 'device':
+            return {
+                message: '设备锁：已请求短信验证码，请提交短信验证码继续',
+                url: typeof raw.url === 'string' ? raw.url : undefined,
+                phone: raw.phone,
+            };
+        case 'auth':
+            return {
+                message: '身份验证：完成后在 Console / 终端确认继续',
+                url: typeof raw.url === 'string' ? raw.url : undefined,
+                device: raw.device,
+            };
+        default:
+            return { message: `登录辅助（${step}）` };
+    }
+}
+function normalizeSubmitValue(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (typeof value.ticket === 'string')
+        return value.ticket.trim();
+    if (typeof value.code === 'string')
+        return value.code.trim();
+    if (typeof value.value === 'string')
+        return value.value.trim();
+    return JSON.stringify(value);
+}
+function bufferToDataUrl(image) {
+    if (Buffer.isBuffer(image)) {
+        return `data:image/png;base64,${image.toString('base64')}`;
+    }
+    if (image instanceof Uint8Array) {
+        return `data:image/png;base64,${Buffer.from(image).toString('base64')}`;
+    }
+    if (typeof image === 'string' && image.trim())
+        return image.trim();
+    return undefined;
+}

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { Actions, formatInboundContent, formatOutboundBody, icqqInboundConversation, icqqOutboundTarget, type ActionResult, type IcqqAdapterConfig, type IcqqInboundMessage, type IcqqWireSegment, type ParsedIcqqSendTarget, type ResolvedIcqqConfig, } from './protocol.js';
-export { IcqqEndpoint, type IcqqEndpointOptions, type IcqqInboxHooks, } from './endpoint.js';
+export { IcqqEndpoint, type IcqqEndpointOptions, } from './endpoint.js';
 export * from './types.js';
 export { getIcqqAgentDeps, registerIcqqAgentEndpoint, setIcqqAgentDeps, type IcqqAgentDeps, type IcqqAgentEndpoint, } from './icqq-agent-deps.js';
 export { resolveIcqqInboundMessageId, } from './icqq-inbound.js';

package/lib/outbound-media.d.ts

@@ -5,6 +5,10 @@ export declare function resolveIcqqOutboundMediaMode(config: Pick<IcqqEndpointCo
 /**
  * file 模式：将 canonical MediaRef（`data.media`，kind=base64）物化为本机路径，
  * 并把 media 改写为 path 引用（icqq 客户端直接读盘）。
- * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://）。
+ * base64 模式：不改动（由 native Sendable projection 生成 base64:// file）。
  */
-export declare function materializeOutboundBase64(content: SendContent, mode?: IcqqOutboundMediaMode): SendContent;
+export interface PreparedIcqqOutboundMedia {
+    readonly content: SendContent;
+    dispose(): void;
+}
+export declare function prepareIcqqOutboundMedia(content: SendContent, mode?: IcqqOutboundMediaMode): PreparedIcqqOutboundMedia;

package/lib/outbound-media.js

@@ -29,19 +29,18 @@ export function resolveIcqqOutboundMediaMode(config) {
     }
     return "file";
 }
-/**
- * file 模式：将 canonical MediaRef（`data.media`，kind=base64）物化为本机路径，
- * 并把 media 改写为 path 引用（icqq 客户端直接读盘）。
- * base64 模式：不改动（由 toCqString/formatOutboundBody 生成 base64://）。
- */
-export function materializeOutboundBase64(content, mode = "file") {
+export function prepareIcqqOutboundMedia(content, mode = "file") {
     if (mode === "base64")
-        return content;
+        return { content, dispose() { } };
+    const createdFiles = [];
+    const inputWasArray = Array.isArray(content);
     const segments = Array.isArray(content) ? content : [content];
-    return segments.map((seg) => {
+    const materialized = segments.map((seg) => {
         if (typeof seg === "string")
             return seg;
         const { type, data } = seg;
+        if (!data || typeof data !== "object")
+            return seg;
         const d = data;
         const media = d.media;
         if (!isMediaRef(media) || media.kind !== "base64")
@@ -54,6 +53,7 @@ export function materializeOutboundBase64(content, mode = "file") {
         }
         const mime = media.mime_type ?? "";
         const filePath = spoolBase64ToFile(b64, mime || (type === "image" ? "image/jpeg" : type === "video" ? "video/mp4" : "audio/mpeg"), type === "record" || type === "audio" ? "audio" : type);
+        createdFiles.push(filePath);
         return {
             type,
             data: {
@@ -66,4 +66,11 @@ export function materializeOutboundBase64(content, mode = "file") {
             },
         };
     });
+    return {
+        content: inputWasArray ? materialized : materialized[0],
+        dispose() {
+            for (const filePath of createdFiles)
+                fs.rmSync(filePath, { force: true });
+        },
+    };
 }

package/lib/protocol.d.ts

@@ -1,3 +1,4 @@
+import type { Sendable } from '@icqqjs/icqq';
 import type { ConversationRef } from '@zhin.js/im-contract';
 import type { MessageSegment } from "zhin.js";
 export type ActionResult = {
@@ -231,6 +232,9 @@ export interface IcqqInboundMessage {
     };
     readonly channelType: 'private' | 'group' | 'channel';
     readonly metadata?: Record<string, unknown>;
+    readonly replyTo?: {
+        readonly id: string;
+    };
 }
 export type ParsedIcqqSendTarget = {
     readonly kind: 'private';
@@ -263,5 +267,10 @@ export declare function icqqInboundConversation(endpointKey: string, input: {
  * 群容器（parent kind 'group'）内的 private 会话即 ICQQ 群临时会话（temp）。
  */
 export declare function icqqOutboundTarget(conversation: ConversationRef): ParsedIcqqSendTarget;
-export declare function formatOutboundBody(payload: unknown): string;
+/**
+ * Project canonical Zhin segments directly into the native ICQQ Sendable
+ * algebra. ICQQ's direct client does not parse Zhin's historical `[image:x]`
+ * notation; passing that notation would send it as literal text.
+ */
+export declare function formatOutboundBody(payload: unknown): Sendable;
 export declare function formatInboundContent(rawMessage: string): string;

package/lib/protocol.js

@@ -1,5 +1,5 @@
 import { pickCredential } from 'zhin.js/adapter';
-import { resolveCqMediaArg } from "./cq-message.js";
+import { resolveIcqqMediaFile } from "./cq-message.js";
 export { resolveIcqqInboundMessageId } from "./icqq-inbound.js";
 /**
  * 所有操作常量（@icqqjs/icqq）
@@ -257,6 +257,18 @@ export function icqqOutboundTarget(conversation) {
     }
     return { kind: 'channel', guildId, channelId: conversation.id };
 }
+const ICQQ_STANDALONE_ELEMENTS = new Set([
+    'record',
+    'video',
+    'file',
+    'json',
+    'long_msg',
+]);
+/**
+ * Project canonical Zhin segments directly into the native ICQQ Sendable
+ * algebra. ICQQ's direct client does not parse Zhin's historical `[image:x]`
+ * notation; passing that notation would send it as literal text.
+ */
 export function formatOutboundBody(payload) {
     if (typeof payload === 'string') {
         const text = payload.trim();
@@ -276,7 +288,7 @@ export function formatOutboundBody(payload) {
         const text = String(payload).trim();
         return text || '\u200b';
     }
-    const joined = payload.map((seg) => {
+    const elements = payload.flatMap((seg) => {
         if (typeof seg === 'string')
             return seg;
         const item = seg;
@@ -284,32 +296,82 @@ export function formatOutboundBody(payload) {
             case 'text':
                 return String(item.data?.text ?? '');
             case 'at':
-            case 'mention':
-                return `[at:${item.data?.qq ?? item.data?.id ?? item.data?.target ?? ''}]`;
+            case 'mention': {
+                const target = item.data?.qq ?? item.data?.id ?? item.data?.target;
+                if (target === 'all')
+                    return { type: 'at', qq: 'all' };
+                const qq = Number(target);
+                if (!Number.isSafeInteger(qq) || qq <= 0) {
+                    throw new TypeError(`Invalid ICQQ mention target: ${String(target ?? '')}`);
+                }
+                return { type: 'at', qq };
+            }
             case 'image': {
-                const arg = resolveCqMediaArg('image', item.data);
-                return arg ? `[image:${arg}]` : '';
+                const arg = resolveIcqqMediaFile(item.data);
+                if (!arg)
+                    throw new TypeError('ICQQ image segment requires canonical data.media');
+                return { type: 'image', file: arg };
+            }
+            case 'face': {
+                const id = Number(item.data?.id);
+                if (!Number.isSafeInteger(id) || id < 0) {
+                    throw new TypeError(`Invalid ICQQ face id: ${String(item.data?.id ?? '')}`);
+                }
+                return { type: 'face', id };
+            }
+            case 'reply': {
+                const id = String(item.data?.message_id ?? item.data?.id ?? '').trim();
+                if (!id)
+                    throw new TypeError('ICQQ reply segment requires message_id');
+                return { type: 'reply', id };
             }
-            case 'face':
-                return `[face:${item.data?.id ?? ''}]`;
-            case 'reply':
-                return `[reply:${item.data?.message_id ?? item.data?.id ?? ''}]`;
             case 'record':
             case 'audio': {
-                const arg = resolveCqMediaArg('record', item.data);
-                return arg ? `[record:${arg}]` : '';
+                const arg = resolveIcqqMediaFile(item.data);
+                if (!arg)
+                    throw new TypeError('ICQQ audio segment requires canonical data.media');
+                return { type: 'record', file: arg };
             }
             case 'video': {
-                const arg = resolveCqMediaArg('video', item.data);
-                return arg ? `[video:${arg}]` : '';
+                const arg = resolveIcqqMediaFile(item.data);
+                if (!arg)
+                    throw new TypeError('ICQQ video segment requires canonical data.media');
+                return { type: 'video', file: arg };
+            }
+            case 'file': {
+                const arg = resolveIcqqMediaFile(item.data);
+                if (!arg)
+                    throw new TypeError('ICQQ file segment requires canonical data.media');
+                const name = String(item.data?.name ?? '').trim();
+                return { type: 'file', file: arg, ...(name ? { name } : {}) };
+            }
+            case 'dice':
+                return { type: 'dice' };
+            case 'rps':
+                return { type: 'rps' };
+            case 'forward': {
+                const resid = String(item.data?.forward_id ?? item.data?.resid ?? item.data?.id ?? '').trim();
+                if (!resid)
+                    throw new TypeError('ICQQ forward segment requires forward_id');
+                return { type: 'long_msg', resid };
             }
             case 'share':
                 return formatMusicShareJson(item.data);
-            default:
-                return String(item.data?.text ?? '');
+            default: {
+                const text = item.data?.text;
+                if (typeof text === 'string' && text)
+                    return text;
+                throw new TypeError(`Unsupported ICQQ outbound segment: ${item.type}`);
+            }
         }
-    }).join('').trim();
-    return joined || '\u200b';
+    }).filter((element) => typeof element !== 'string' || element.length > 0);
+    if (elements.length === 0)
+        return '\u200b';
+    const standalone = elements.find((element) => typeof element !== 'string' && ICQQ_STANDALONE_ELEMENTS.has(element.type));
+    if (standalone && elements.length !== 1) {
+        throw new TypeError(`ICQQ ${standalone.type} element must be sent as a standalone message`);
+    }
+    return elements.length === 1 ? elements[0] : elements;
 }
 export function formatInboundContent(rawMessage) {
     return rawMessage;
@@ -322,7 +384,7 @@ function isWireSegment(value) {
 }
 function formatMusicShareJson(data) {
     if (!data)
-        return '';
+        throw new TypeError('ICQQ share segment requires data');
     const config = data.config;
     const title = String(data.title ?? '');
     const desc = String(data.artist ?? '');
@@ -359,5 +421,5 @@ function formatMusicShareJson(data) {
             },
         },
     };
-    return `[json:${JSON.stringify(json)}]`;
+    return { type: 'json', data: json };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "8.0.12",
+  "version": "8.0.14",
   "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,21 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/core": "1.5.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/core": "1.5.12",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76",
-    "@zhin.js/permission": "1.0.2",
-    "@zhin.js/tool": "1.0.11"
+    "@zhin.js/permission": "1.0.3",
+    "@zhin.js/tool": "1.0.12"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent": "1.1.12",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/core": "1.5.10",
-    "zhin.js": "6.0.10"
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/agent": "1.1.14",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.12",
+    "zhin.js": "6.0.12"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
@@ -73,8 +73,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.12",
-    "zhin.js": "6.0.10"
+    "@zhin.js/agent": "1.1.14",
+    "zhin.js": "6.0.12"
   },
   "files": [
     "adapters",

package/src/cq-message.ts

@@ -1,13 +1,6 @@
-/**
- * CQ 码与 MessageSegment 互转。
- * 出站：@icqqjs/cli 要求 message 为非空字符串；引用段编码为 [reply:id]（需 cli parse-message 支持 reply，见 scripts/patch-icqq-cli-reply.mjs）。
- * 媒体段双向均为 canonical MediaRef（`data.media`），无 legacy url/file/base64 字段。
- */
+/** ICQQ 历史文本视图 → canonical MessageSegment。出站只使用原生 Sendable。 */
 import { isMediaRef, type MediaRef } from "@zhin.js/core";
-import { formatCompact, getLogger } from "@zhin.js/logger";
-import { MessageSegment, segment, SendContent } from "zhin.js";
-
-const logger = getLogger("icqq");
+import type { MessageSegment } from "zhin.js";
 
 const MAX_CQ_PARSE_LEN = 256_000;
 
@@ -29,23 +22,14 @@ export function icqqMediaRefFromString(value: string): MediaRef {
 }
 
 /**
- * canonical MediaRef（`data.media`，唯一媒体来源）→ CQ 媒体参数：
- * base64 → `base64://` 前缀（守护进程解码）；url/path/file 原样直出。
- * 无 canonical 媒体引用时 warn 并返回 undefined（调用方丢弃该段）。
+ * canonical MediaRef（`data.media`，唯一媒体来源）→ ICQQ native
+ * element 的 file 参数。base64 使用 ICQQ 原生支持的 `base64://` 前缀。
  */
-export function resolveCqMediaArg(
-  type: string,
+export function resolveIcqqMediaFile(
   data: Record<string, unknown> | undefined,
 ): string | undefined {
   const media = data?.media;
-  if (!isMediaRef(media)) {
-    logger.warn(formatCompact({
-      op: "icqq_outbound_media_dropped",
-      type,
-      reason: "missing_media_ref",
-    }));
-    return undefined;
-  }
+  if (!isMediaRef(media)) return undefined;
   if (media.kind === "base64") {
     return media.value.startsWith("base64://") ? media.value : `base64://${media.value}`;
   }
@@ -75,7 +59,7 @@ function pushCqSegment(segments: MessageSegment[], type: string, arg: string): v
       break;
     case "record":
     case "audio":
-      segments.push({ type: "record", data: { media: icqqMediaRefFromString(arg) } });
+      segments.push({ type: "audio", data: { media: icqqMediaRefFromString(arg) } });
       break;
     case "video":
       segments.push({ type: "video", data: { media: icqqMediaRefFromString(arg) } });
@@ -127,54 +111,3 @@ export function parseCqMessage(raw: string): MessageSegment[] {
 
   return segments.length ? segments : [{ type: "text", data: { text: raw } }];
 }
-
-/** 构建 icqq send_*_msg 的 message 字符串（非空） */
-export function buildIcqqMessage(content: SendContent): string {
-  let message = toCqString(content).trim();
-  if (!message) message = "\u200b";
-  return message;
-}
-
-export function toCqString(content: SendContent): string {
-  if (!Array.isArray(content)) content = [content];
-  return content
-    .map((seg) => {
-      if (typeof seg === "string") return seg;
-      const { type, data } = seg as MessageSegment;
-      switch (type) {
-        case "text":
-          return data.text ?? "";
-        case "face":
-          return `[face:${data.id}]`;
-        case "image": {
-          const arg = resolveCqMediaArg("image", data);
-          return arg ? `[image:${arg}]` : "";
-        }
-        case "at":
-        case "mention": {
-          const target = data.target ?? data.qq ?? data.id ?? data.user_id;
-          return `[at:${target}]`;
-        }
-        case "dice":
-          return "[dice]";
-        case "rps":
-          return "[rps]";
-        case "record":
-        case "audio": {
-          const arg = resolveCqMediaArg("record", data);
-          return arg ? `[record:${arg}]` : "";
-        }
-        case "video": {
-          const arg = resolveCqMediaArg("video", data);
-          return arg ? `[video:${arg}]` : "";
-        }
-        case "reply":
-          return `[reply:${data.message_id ?? data.id}]`;
-        case "json":
-          return `[json:${data.text ?? ''}]`;
-        default:
-          return segment.toString(seg);
-      }
-    })
-    .join("");
-}