@zhin.js/adapter-icqq 1.1.14 → 1.1.16

package/lib/endpoint.js

@@ -13,6 +13,7 @@ import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guil
 import { prepareIcqqOutboundMedia, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
 import { formatInboundContent, formatOutboundMessages, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 import { ManagedIcqqClient } from './managed-client.js';
+import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
 const BOUND_EVENTS = [
     'message.private',
     'message.group',
@@ -55,6 +56,8 @@ export class IcqqEndpoint extends Endpoint {
     #contentResolver;
     content;
     management = Object.freeze({
+        inspectGroupMember: (group, user, signal) => inspectGroupMember(this.client, group, user, signal),
+        moderateGroupMember: (group, user, action, signal) => moderateGroupMember(this.client, group, user, action, signal, () => this.#open && !this.#retiring && !this.#stopped),
         listFriends: async () => Array.from(this.client.fl.values()).map((f) => ({
             user_id: f.user_id,
             nickname: f.nickname,
@@ -84,12 +87,18 @@ export class IcqqEndpoint extends Endpoint {
         deleteFriend: async (userId) => {
             await this.client.deleteFriend(Number(userId));
         },
+        sendGroupNotice: async (groupId, content) => {
+            if (await this.client.sendGroupNotice(Number(groupId), content) === false) {
+                throw new Error('QQ did not confirm the group notice');
+            }
+        },
     });
     control = Object.freeze({
         recall: async (message) => {
             if (!message.id || message.id.startsWith('outbound:'))
                 return;
-            await this.client.deleteMsg(message.id);
+            if (!await this.client.deleteMsg(message.id))
+                throw new Error('QQ did not confirm message recall');
         },
         addReaction: async (message, emoji) => {
             const target = resolveIcqqGroupReactionTarget(message);
@@ -618,6 +627,7 @@ export class IcqqEndpoint extends Endpoint {
         this.#logSystemEvent(`login.${step}`, event);
         void runIcqqLoginAssistStep({
             assist: this.#options.loginAssist,
+            locale: this.#options.locale,
             client: this.client,
             adapter: 'icqq',
             endpointKey: this.endpointName,
@@ -764,6 +774,7 @@ export class IcqqEndpoint extends Endpoint {
             metadata: {
                 nickname: normalized.nickname,
                 senderRole: normalized.senderRole,
+                platformSentAt: normalized.timestampMs,
             },
         }, admittedBeforeRetire);
     }

package/lib/group-moderation.d.ts

@@ -0,0 +1,5 @@
+import type { Client } from '@icqqjs/icqq';
+import type { GroupModerationAction, GroupModerationMember } from 'zhin.js/adapter';
+/** Native role/join facts stay in the adapter; the moderation plugin owns policy. */
+export declare function inspectGroupMember(client: Client, groupId: string, userId: string, signal: AbortSignal): Promise<GroupModerationMember>;
+export declare function moderateGroupMember(client: Client, groupId: string, userId: string, action: GroupModerationAction, signal: AbortSignal, isActive: () => boolean): Promise<void>;

package/lib/group-moderation.js

@@ -0,0 +1,46 @@
+/** Native role/join facts stay in the adapter; the moderation plugin owns policy. */
+export async function inspectGroupMember(client, groupId, userId, signal) {
+    signal.throwIfAborted();
+    const group = numericId(groupId);
+    const user = numericId(userId);
+    const [self, member] = await Promise.all([
+        client.getGroupMemberInfo(group, client.uin, true),
+        client.getGroupMemberInfo(group, user, true),
+    ]);
+    signal.throwIfAborted();
+    const joinedAt = member.join_time * 1000;
+    return {
+        canModerate: client.isOnline() && user !== client.uin
+            && self.user_id === client.uin && self.group_id === group
+            && member.user_id === user && member.group_id === group
+            && (self.role === 'owner' || self.role === 'admin') && member.role === 'member',
+        ...(Number.isSafeInteger(joinedAt) && joinedAt > 0 && joinedAt <= Date.now() ? { joinedAt } : {}),
+    };
+}
+export async function moderateGroupMember(client, groupId, userId, action, signal, isActive) {
+    const member = await inspectGroupMember(client, groupId, userId, signal);
+    signal.throwIfAborted();
+    if (!isActive() || !member.canModerate)
+        throw new Error('Group moderation permission is unavailable');
+    if (action.type === 'kick') {
+        if (!Number.isSafeInteger(action.maxMembershipAgeMs) || action.maxMembershipAgeMs <= 0
+            || member.joinedAt !== action.joinedAt || !member.joinedAt
+            || Date.now() - member.joinedAt > action.maxMembershipAgeMs) {
+            throw new Error('Group membership no longer matches the approved newcomer window');
+        }
+    }
+    else if (!Number.isSafeInteger(action.durationSeconds) || action.durationSeconds <= 0) {
+        throw new Error('Invalid group mute duration');
+    }
+    const ok = action.type === 'kick'
+        ? await client.setGroupKick(numericId(groupId), numericId(userId))
+        : await client.setGroupBan(numericId(groupId), numericId(userId), action.durationSeconds);
+    if (!ok)
+        throw new Error('Platform did not confirm the moderation action');
+}
+function numericId(value) {
+    const id = Number(value);
+    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(id))
+        throw new Error('Invalid QQ identifier');
+    return id;
+}

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.js

@@ -248,6 +248,21 @@ export function icqqElementsToSegments(elements) {
             case "face":
                 out.push({ type: "face", data: { id: Number(el.id) } });
                 break;
+            case "bface": {
+                // ICQQ 的原创表情 file 是两个 MD5 加包编号，不是本地文件路径。
+                const file = typeof el.file === "string" ? el.file : "";
+                if (/^[a-f\d]{64}\d+$/i.test(file)) {
+                    const md5 = file.slice(0, 32).toLowerCase();
+                    out.push({
+                        type: "image",
+                        data: { media: { kind: "url", value: `https://gxh.vip.qq.com/club/item/parcel/item/${md5.slice(0, 2)}/${md5}/raw300.gif`, mime_type: "image/gif" } },
+                    });
+                }
+                // 保留标签：下载或识图失败时仍能读懂表情的文字含义。
+                if (el.text)
+                    out.push({ type: "text", data: { text: String(el.text) } });
+                break;
+            }
             case "image": {
                 const value = String(el.url ?? el.file ?? "");
                 if (!value)

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;

package/lib/protocol.js

@@ -265,6 +265,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 +337,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);
@@ -380,6 +381,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 +419,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.14",
+  "version": "1.1.16",
   "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.21",
-    "@zhin.js/agent-feature": "1.1.8",
-    "@zhin.js/core": "1.1.49",
-    "@zhin.js/feature-kit": "1.1.7",
-    "@zhin.js/im-contract": "1.1.5",
+    "@zhin.js/adapter": "1.1.23",
+    "@zhin.js/agent-feature": "1.1.10",
+    "@zhin.js/core": "1.1.51",
+    "@zhin.js/feature-kit": "1.1.9",
+    "@zhin.js/im-contract": "1.1.7",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.7",
-    "@zhin.js/skill": "1.1.8",
-    "@zhin.js/tool": "1.1.8"
+    "@zhin.js/permission": "1.1.9",
+    "@zhin.js/skill": "1.1.10",
+    "@zhin.js/tool": "1.1.10"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.21",
-    "@zhin.js/command": "^1.1.9",
-    "@zhin.js/core": "^1.1.49",
-    "@zhin.js/prompt-section": "^1.1.7",
-    "zhin.js": "^1.1.14"
+    "@zhin.js/adapter": "^1.1.23",
+    "@zhin.js/command": "^1.1.11",
+    "@zhin.js/core": "^1.1.51",
+    "@zhin.js/prompt-section": "^1.1.9",
+    "zhin.js": "^1.1.16"
   },
   "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.7",
-    "zhin.js": "1.1.14"
+    "@zhin.js/prompt-section": "1.1.9",
+    "zhin.js": "1.1.16"
   },
   "files": [
     "adapters",

package/prompt-sections/platform/index.js

@@ -3,8 +3,7 @@ import { defineAgentPromptSection } from '@zhin.js/prompt-section';
 export default defineAgentPromptSection({
     title: 'ICQQ / QQ',
     content: [
-        'ICQQ capabilities are grouped into directory, interaction, group-admin, and group-state Skills.',
-        'Use discover for the user intent, then load only the matching Skill before calling its private Tool.',
+        'Use the current Skill catalog; discover the intent and load the matching Skill before its private Tool.',
         'The current IM operation selects the bot Client automatically; never guess user_id or group_id.',
     ].join('\n'),
     layer: 'tools',

package/prompt-sections/platform/index.ts

@@ -3,8 +3,7 @@ import { defineAgentPromptSection } from '@zhin.js/prompt-section';
 export default defineAgentPromptSection({
   title: 'ICQQ / QQ',
   content: [
-    'ICQQ capabilities are grouped into directory, interaction, group-admin, and group-state Skills.',
-    'Use discover for the user intent, then load only the matching Skill before calling its private Tool.',
+    'Use the current Skill catalog; discover the intent and load the matching Skill before its private Tool.',
     'The current IM operation selects the bot Client automatically; never guess user_id or group_id.',
   ].join('\n'),
   layer: 'tools',