@zhin.js/adapter-icqq 1.1.15 → 1.1.17

package/lib/group-scene.js

@@ -0,0 +1,71 @@
+/** Listing a very large roster only to find admins is not worth the packet; adminIds stay unknown. */
+export const ADMIN_SCAN_MAX_MEMBERS = 1000;
+const MAX_ADMIN_IDS = 20;
+function positiveId(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
+}
+function numericId(value) {
+    const id = Number(value);
+    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(id))
+        throw new Error('Invalid QQ identifier');
+    return id;
+}
+/**
+ * ADR 0041 scene facts: one uncached group-info read, plus (small groups only) one roster read for
+ * admins. A roster failure leaves adminIds unknown instead of failing the other facts.
+ */
+export async function inspectGroupScene(client, groupId, signal) {
+    signal.throwIfAborted();
+    const group = numericId(groupId);
+    const info = await client.getGroupInfo(group, true);
+    signal.throwIfAborted();
+    if (info.group_id !== group)
+        return {};
+    const memberCount = Number.isSafeInteger(info.member_count) && info.member_count > 0 ? info.member_count : undefined;
+    const ownerId = positiveId(info.owner_id);
+    let adminIds;
+    if (memberCount === undefined || memberCount <= ADMIN_SCAN_MAX_MEMBERS) {
+        try {
+            const roster = await client.getGroupMemberList(group);
+            signal.throwIfAborted();
+            adminIds = [...roster.values()]
+                .filter(member => member.role === 'admin' && member.group_id === group)
+                .map(member => positiveId(member.user_id))
+                .filter((id) => id !== undefined)
+                .slice(0, MAX_ADMIN_IDS);
+        }
+        catch {
+            signal.throwIfAborted();
+            adminIds = undefined;
+        }
+    }
+    const name = typeof info.group_name === 'string' && info.group_name.trim() ? info.group_name.trim() : undefined;
+    const nowSeconds = Date.now() / 1000;
+    return {
+        ...(name ? { name } : {}),
+        ...(ownerId ? { ownerId } : {}),
+        ...(adminIds ? { adminIds } : {}),
+        ...(memberCount !== undefined ? { memberCount } : {}),
+        ...(typeof info.shutup_time_whole === 'number' ? { muteAll: info.shutup_time_whole > nowSeconds } : {}),
+    };
+}
+/** ADR 0041 member facts from one uncached lookup (same rationale as the agent `freshMember` helper). */
+export async function inspectGroupMemberProfile(client, groupId, userId, signal) {
+    signal.throwIfAborted();
+    const group = numericId(groupId);
+    const user = numericId(userId);
+    const member = await client.getGroupMemberInfo(group, user, true);
+    signal.throwIfAborted();
+    if (member.user_id !== user || member.group_id !== group)
+        return {};
+    const card = typeof member.card === 'string' && member.card.trim() ? member.card.trim() : undefined;
+    const title = typeof member.title === 'string' && member.title.trim() ? member.title.trim() : undefined;
+    const shutupSeconds = member.shutup_time;
+    return {
+        ...(member.role === 'owner' || member.role === 'admin' || member.role === 'member' ? { platformRole: member.role } : {}),
+        ...(card ? { card } : {}),
+        ...(title ? { title } : {}),
+        ...(typeof shutupSeconds === 'number' && Number.isFinite(shutupSeconds)
+            ? { mutedUntil: shutupSeconds * 1000 > Date.now() ? shutupSeconds * 1000 : 0 } : {}),
+    };
+}

package/lib/i18n.d.ts

@@ -0,0 +1 @@
+export declare const messages: (locale: import("zhin.js").Locale | undefined, key: "direct" | "addUsage" | "uinRequired" | "uinInvalid" | "endpointAdded" | "endpointAddFailed" | "loginQr" | "loginSlider" | "loginSms" | "loginAuth" | "loginOther", values?: import("zhin.js").MessageValues) => string;

package/lib/i18n.js

@@ -0,0 +1,47 @@
+import { createMessages } from 'zhin.js/i18n';
+export const messages = createMessages({
+    "direct": {
+        "zh-CN": "direct（直连 @icqqjs/icqq）",
+        "en": "direct (@icqqjs/icqq)"
+    },
+    "addUsage": {
+        "zh-CN": "用法：{command} <uin>（uin 为纯数字 QQ 号）",
+        "en": "Usage: {command} <uin> (a numeric QQ account ID)"
+    },
+    "uinRequired": {
+        "zh-CN": "请提供纯数字 QQ 号（uin）",
+        "en": "Provide a numeric QQ account ID (uin)"
+    },
+    "uinInvalid": {
+        "zh-CN": "icqq endpoint 名必须是纯数字 QQ 号（uin）",
+        "en": "The ICQQ endpoint name must be a numeric QQ account ID (uin)"
+    },
+    "endpointAdded": {
+        "zh-CN": "✅ endpoint「{id}」已追加到 {file} 的 plugins.icqq.endpoints。\n重启 zhin 后生效。",
+        "en": "✅ Endpoint “{id}” added to plugins.icqq.endpoints in {file}.\nRestart zhin to apply."
+    },
+    "endpointAddFailed": {
+        "zh-CN": "添加失败：{error}",
+        "en": "Could not add the endpoint: {error}"
+    },
+    "loginQr": {
+        "zh-CN": "扫码登录：请在手机 QQ 扫描二维码，完成后在 Console / 终端确认继续",
+        "en": "Scan the QR code in mobile QQ, then confirm in Console or your terminal."
+    },
+    "loginSlider": {
+        "zh-CN": "滑动验证：打开链接完成滑块，将返回的 ticket（可含 randstr）提交继续",
+        "en": "Open the link, complete the slider challenge, and submit the returned ticket (with randstr if provided)."
+    },
+    "loginSms": {
+        "zh-CN": "设备锁：已请求短信验证码，请提交短信验证码继续",
+        "en": "Device verification: an SMS code was requested. Submit the code to continue."
+    },
+    "loginAuth": {
+        "zh-CN": "身份验证：完成后在 Console / 终端确认继续",
+        "en": "Complete identity verification, then confirm in Console or your terminal."
+    },
+    "loginOther": {
+        "zh-CN": "登录辅助（{step}）",
+        "en": "Login assistance ({step})"
+    }
+});

package/lib/icqq-inbound.d.ts

@@ -103,6 +103,8 @@ export interface NormalizedIcqqInbound {
     channelId: string;
     /** 群临时会话：来源群号 */
     channelParentGroupId?: string;
+    /** 群聊时来自 group_name */
+    groupName?: string;
     userId: string;
     nickname: string;
     /** 群聊时来自 sender.role（私聊无） */

package/lib/icqq-inbound.js

@@ -688,6 +688,9 @@ export function normalizeIcqqInboundMessage(data) {
         channelType,
         channelId,
         channelParentGroupId,
+        ...(channelType === "group" && typeof ext.group_name === "string" && ext.group_name.trim()
+            ? { groupName: ext.group_name.trim() }
+            : {}),
         userId: String(userIdNum),
         nickname,
         senderRole,

package/lib/icqq-inbox.d.ts

@@ -8,6 +8,11 @@ export interface IcqqInboxBase {
 export declare function isIcqqRequestPayload(payload: unknown): boolean;
 /** post_type=notice / notice.* 判定。 */
 export declare function isIcqqNoticePayload(payload: unknown): boolean;
+/**
+ * notice 去重键。成员与操作人分开记：同一管理员先后拉两个人进群时，`operator_id ?? user_id`
+ * 会撞键（icqq 群通知又常不带 time），后一次入群被当重复吞掉。
+ */
+export declare function icqqNoticeDedupeKey(payload: Record<string, unknown>): string;
 /**
  * request 事件载荷 → unified_inbox_request 行。
  * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。

package/lib/icqq-inbox.js

@@ -10,6 +10,20 @@ export function isIcqqNoticePayload(payload) {
     return typeof postType === 'string'
         && (postType === 'notice' || postType.startsWith('notice.'));
 }
+/**
+ * notice 去重键。成员与操作人分开记：同一管理员先后拉两个人进群时，`operator_id ?? user_id`
+ * 会撞键（icqq 群通知又常不带 time），后一次入群被当重复吞掉。
+ */
+export function icqqNoticeDedupeKey(payload) {
+    return `notice:${[
+        payload.time,
+        payload.group_id,
+        payload.user_id,
+        payload.operator_id,
+        payload.notice_type ?? payload.type,
+        payload.sub_type,
+    ].join('_')}`;
+}
 /**
  * request 事件载荷 → unified_inbox_request 行。
  * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。

package/lib/icqq-login-assist.d.ts

@@ -1,3 +1,4 @@
+import type { Locale } from 'zhin.js/i18n';
 import type { LoginAssist, LoginAssistType } from '@zhin.js/core';
 type IcqqLoginClient = {
     login(password?: string): Promise<unknown>;
@@ -23,5 +24,6 @@ export declare function runIcqqLoginAssistStep(input: {
     logger: Logger;
     step: LoginAssistType;
     event: unknown;
+    locale?: Locale;
 }): Promise<void>;
 export {};

package/lib/icqq-login-assist.js

@@ -1,3 +1,4 @@
+import { messages as t } from './i18n.js';
 import { formatCompact } from '@zhin.js/logger';
 /**
  * Drive ICQQ login challenges through LoginAssist (refresh-safe pending tasks).
@@ -7,7 +8,7 @@ import { formatCompact } from '@zhin.js/logger';
 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);
+    const payload = buildPayload(step, event, input.locale);
     logger.info(formatCompact({
         op: 'login_assist_pending',
         endpoint: endpointKey,
@@ -56,33 +57,33 @@ export async function runIcqqLoginAssistStep(input) {
         }));
     }
 }
-function buildPayload(step, event) {
+function buildPayload(step, event, locale) {
     const raw = event && typeof event === 'object' ? event : {};
     switch (step) {
         case 'qrcode':
             return {
-                message: '扫码登录：请在手机 QQ 扫描二维码，完成后在 Console / 终端确认继续',
+                message: t(locale, 'loginQr'),
                 image: bufferToDataUrl(raw.image),
             };
         case 'slider':
             return {
-                message: '滑动验证：打开链接完成滑块，将返回的 ticket（可含 randstr）提交继续',
+                message: t(locale, 'loginSlider'),
                 url: typeof raw.url === 'string' ? raw.url : undefined,
             };
         case 'device':
             return {
-                message: '设备锁：已请求短信验证码，请提交短信验证码继续',
+                message: t(locale, 'loginSms'),
                 url: typeof raw.url === 'string' ? raw.url : undefined,
                 phone: raw.phone,
             };
         case 'auth':
             return {
-                message: '身份验证：完成后在 Console / 终端确认继续',
+                message: t(locale, 'loginAuth'),
                 url: typeof raw.url === 'string' ? raw.url : undefined,
                 device: raw.device,
             };
         default:
-            return { message: `登录辅助（${step}）` };
+            return { message: t(locale, 'loginOther', { step }) };
     }
 }
 function normalizeSubmitValue(value) {

package/lib/protocol.d.ts

@@ -198,6 +198,7 @@ export interface ResolvedIcqqConfig {
 export interface IcqqWireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
+    readonly platform?: Readonly<Record<string, unknown>>;
 }
 export interface IcqqInboundMessage {
     readonly id: string;
@@ -245,6 +246,8 @@ export declare function icqqInboundConversation(endpointKey: string, input: {
     readonly channelId: string;
     readonly channelParentGroupId?: string;
     readonly guildId?: string;
+    /** 群名（仅 group 会话使用） */
+    readonly name?: string;
 }): ConversationRef;
 /**
  * 出站：从 ConversationRef 派生 action 路由。

package/lib/protocol.js

@@ -232,7 +232,8 @@ export function icqqInboundConversation(endpointKey, input) {
             parent: { kind: 'channel', id: input.guildId },
         };
     }
-    return { endpoint, kind: input.channelType, id: input.channelId };
+    const name = input.channelType === 'group' ? input.name?.trim() : undefined;
+    return { endpoint, kind: input.channelType, id: input.channelId, ...(name ? { name } : {}) };
 }
 /**
  * 出站：从 ConversationRef 派生 action 路由。
@@ -265,6 +266,7 @@ const ICQQ_STANDALONE_ELEMENTS = new Set([
     'json',
     'share',
     'long_msg',
+    'multimsg',
 ]);
 /** Normalize inline image bytes before either temporary-file or native-base64 delivery. */
 export function normalizeIcqqImageMedia(content) {
@@ -336,7 +338,7 @@ export function formatOutboundMessages(payload) {
     }
     const messages = groups.filter(group => group.some(element => typeof element === 'string'
         ? element.trim() !== ''
-        : element.type !== 'reply'));
+        : element.type !== 'reply' && element.type !== 'quote'));
     if (messages.length === 0)
         return ['\u200b'];
     return messages.map(group => group.length === 1 ? group[0] : group);
@@ -361,7 +363,8 @@ function formatOutboundElements(payload) {
                 if (!Number.isSafeInteger(qq) || qq <= 0) {
                     throw new TypeError(`Invalid ICQQ mention target: ${String(target ?? '')}`);
                 }
-                return { type: 'at', qq };
+                const name = typeof item.data?.name === 'string' ? item.data.name.trim() : '';
+                return name ? { type: 'at', qq, text: name.startsWith('@') ? name : `@${name}` } : { type: 'at', qq };
             }
             case 'image': {
                 const arg = resolveIcqqMediaFile(normalizeIcqqImageData(item.data));
@@ -380,6 +383,14 @@ function formatOutboundElements(payload) {
                 const id = String(item.data?.message_id ?? item.data?.id ?? '').trim();
                 if (!id)
                     throw new TypeError('ICQQ reply segment requires message_id');
+                const quote = item.platform?.icqqQuote;
+                if (quote) {
+                    const { user_id, seq, rand, time, message } = quote;
+                    if (typeof user_id !== 'number' || typeof seq !== 'number' || typeof rand !== 'number'
+                        || typeof time !== 'number' || typeof message !== 'string')
+                        throw new TypeError('Invalid ICQQ quote source');
+                    return { type: 'quote', user_id, seq, rand, time, message };
+                }
                 return { type: 'reply', id };
             }
             case 'record':
@@ -410,6 +421,10 @@ function formatOutboundElements(payload) {
                 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');
+                // Prepared merged forwards need their filename; a long_msg would expand inline.
+                const filename = item.platform?.icqqForwardFilename;
+                if (typeof filename === 'string' && filename)
+                    return { type: 'multimsg', resid, filename };
                 return { type: 'long_msg', resid };
             }
             case 'share':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,24 +33,24 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.22",
-    "@zhin.js/agent-feature": "1.1.9",
-    "@zhin.js/core": "1.1.50",
-    "@zhin.js/feature-kit": "1.1.8",
-    "@zhin.js/im-contract": "1.1.6",
+    "@zhin.js/adapter": "1.1.24",
+    "@zhin.js/agent-feature": "1.1.10",
+    "@zhin.js/core": "1.1.52",
+    "@zhin.js/feature-kit": "1.1.9",
+    "@zhin.js/im-contract": "1.1.8",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.8",
-    "@zhin.js/skill": "1.1.9",
-    "@zhin.js/tool": "1.1.9"
+    "@zhin.js/permission": "1.1.9",
+    "@zhin.js/skill": "1.1.10",
+    "@zhin.js/tool": "1.1.11"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.22",
-    "@zhin.js/command": "^1.1.10",
-    "@zhin.js/core": "^1.1.50",
-    "@zhin.js/prompt-section": "^1.1.8",
-    "zhin.js": "^1.1.15"
+    "@zhin.js/adapter": "^1.1.24",
+    "@zhin.js/command": "^1.1.11",
+    "@zhin.js/core": "^1.1.52",
+    "@zhin.js/prompt-section": "^1.1.9",
+    "zhin.js": "^1.1.17"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
@@ -75,8 +75,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/prompt-section": "1.1.8",
-    "zhin.js": "1.1.15"
+    "@zhin.js/prompt-section": "1.1.9",
+    "zhin.js": "1.1.17"
   },
   "files": [
     "adapters",