@zhin.js/adapter-icqq 1.1.15 → 1.1.17

package/schema.json

@@ -4,75 +4,169 @@
   "additionalProperties": false,
   "properties": {
     "master": {
-      "type": ["string", "number"],
-      "description": "框架 master QQ uin（/approve、AI/工具权限）；endpoints[i].master 可逐项覆盖"
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master QQ uin（/approve、AI/工具权限）；endpoints[i].master 可逐项覆盖",
+      "x-i18n": {
+        "en": {
+          "description": "Framework master QQ uin list for approval and AI/tool permissions. endpoints[i].master can override this value."
+        }
+      }
     },
     "trusted": {
       "type": "array",
-      "items": { "type": ["string", "number"] },
-      "description": "框架 trusted QQ uin 列表（弱于 master）"
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ]
+      },
+      "description": "框架 trusted QQ uin 列表（弱于 master）",
+      "x-i18n": {
+        "en": {
+          "description": "Framework trusted QQ uin list, below master authority."
+        }
+      }
     },
     "password": {
       "type": "string",
-      "description": "QQ 密码（可选，不填则扫码登录）"
+      "description": "QQ 密码（可选，不填则扫码登录）",
+      "x-i18n": {
+        "en": {
+          "description": "QQ password (optional); scan a QR code to log in when omitted."
+        }
+      }
     },
     "platform": {
       "type": "number",
-      "enum": [1, 2, 3, 4, 5, 6, 7],
+      "enum": [
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7
+      ],
       "default": 1,
-      "description": "登录设备平台：1=Android, 2=aPad, 3=Watch, 4=iMac, 5=iPad, 6=Tim, 7=Custom"
+      "description": "登录设备平台：1=Android, 2=aPad, 3=Watch, 4=iMac, 5=iPad, 6=Tim, 7=Custom",
+      "x-i18n": {
+        "en": {
+          "description": "Login device platform: 1=Android, 2=aPad, 3=Watch, 4=iMac, 5=iPad, 6=Tim, 7=Custom."
+        }
+      }
     },
     "ver": {
       "type": "string",
-      "description": "协议版本号，仅在对应 platform 有多个版本时有效，不填则使用最新版本"
+      "description": "协议版本号，仅在对应 platform 有多个版本时有效，不填则使用最新版本",
+      "x-i18n": {
+        "en": {
+          "description": "Protocol version, only applicable when the selected platform has multiple versions. Uses the latest when omitted."
+        }
+      }
     },
     "signApiAddr": {
       "type": "string",
-      "description": "签名服务器地址；未配置时若安装了 @icqqjs/qqsign 则自动使用本地签名"
+      "description": "签名服务器地址；未配置时若安装了 @icqqjs/qqsign 则自动使用本地签名",
+      "x-i18n": {
+        "en": {
+          "description": "Signing server URL. When omitted, uses local signing automatically if @icqqjs/qqsign is installed."
+        }
+      }
     },
     "dataDir": {
       "type": "string",
-      "description": "数据存储文件夹路径，默认为主模块下的 data 文件夹"
+      "description": "数据存储文件夹路径，默认为主模块下的 data 文件夹",
+      "x-i18n": {
+        "en": {
+          "description": "Data directory path; defaults to the data directory under the main module."
+        }
+      }
     },
     "autoReconnect": {
       "type": "boolean",
       "default": true,
-      "description": "断线后是否自动重连（默认 true）"
+      "description": "断线后是否自动重连（默认 true）",
+      "x-i18n": {
+        "en": {
+          "description": "Reconnect automatically after disconnecting (default true)."
+        }
+      }
     },
     "outboundMedia": {
       "type": "string",
-      "enum": ["file", "base64"],
+      "enum": [
+        "file",
+        "base64"
+      ],
       "default": "file",
-      "description": "出站媒体模式：file=落盘本地路径（默认）; base64=CQ base64:// 内联"
+      "description": "出站媒体模式：file=落盘本地路径（默认）; base64=CQ base64:// 内联",
+      "x-i18n": {
+        "en": {
+          "description": "Outbound media mode: file uses local file paths (default); base64 uses inline CQ base64:// data."
+        }
+      }
     },
     "ignoreSelf": {
       "type": "boolean",
       "default": true,
-      "description": "群聊和频道中是否过滤自己的消息（默认 true）"
+      "description": "群聊和频道中是否过滤自己的消息（默认 true）",
+      "x-i18n": {
+        "en": {
+          "description": "Filter the bot's own messages in groups and channels (default true)."
+        }
+      }
     },
     "resend": {
       "type": "boolean",
       "default": false,
-      "description": "被风控时是否尝试用分片发送（默认 false）"
+      "description": "被风控时是否尝试用分片发送（默认 false）",
+      "x-i18n": {
+        "en": {
+          "description": "Attempt fragmented sending when rate-limited by the platform (default false)."
+        }
+      }
     },
     "cacheGroupMember": {
       "type": "boolean",
       "default": true,
-      "description": "是否缓存群员列表（默认 true）；群多时（500+）会多占约 100MB+ 内存"
+      "description": "是否缓存群员列表（默认 true）；群多时（500+）会多占约 100MB+ 内存",
+      "x-i18n": {
+        "en": {
+          "description": "Cache group member lists (default true). Large numbers of groups (500+) may use approximately 100 MB or more of extra memory."
+        }
+      }
     },
     "autoServer": {
       "type": "boolean",
       "default": true,
-      "description": "是否自动选择最优服务器（默认 true）"
+      "description": "是否自动选择最优服务器（默认 true）",
+      "x-i18n": {
+        "en": {
+          "description": "Automatically select the optimal server (default true)."
+        }
+      }
     },
     "qqnt": {
       "type": "boolean",
       "default": true,
-      "description": "是否使用 QQNT 协议（默认 true）"
+      "description": "是否使用 QQNT 协议（默认 true）",
+      "x-i18n": {
+        "en": {
+          "description": "Use the QQNT protocol (default true)."
+        }
+      }
     },
     "ntLogin": {
       "type": "boolean",
-      "description": "是否使用 NT 登录方式"
+      "description": "是否使用 NT 登录方式",
+      "x-i18n": {
+        "en": {
+          "description": "Use the NT login method."
+        }
+      }
     },
     "endpoints": {
       "type": "array",
@@ -88,81 +182,195 @@
             "description": "QQ uin"
           },
           "master": {
-            "type": ["string", "number"],
-            "description": "本 endpoint 的 master QQ uin；覆盖顶层 master"
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的 master QQ uin；覆盖顶层 master",
+            "x-i18n": {
+              "en": {
+                "description": "Master QQ uin list for this endpoint, overriding the top-level master list."
+              }
+            }
           },
           "trusted": {
             "type": "array",
-            "items": { "type": ["string", "number"] },
-            "description": "本 endpoint 的 trusted 列表"
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ]
+            },
+            "description": "本 endpoint 的 trusted 列表",
+            "x-i18n": {
+              "en": {
+                "description": "Trusted users for this endpoint."
+              }
+            }
           },
           "password": {
             "type": "string",
-            "description": "本 endpoint 的 QQ 密码"
+            "description": "本 endpoint 的 QQ 密码",
+            "x-i18n": {
+              "en": {
+                "description": "QQ password for this endpoint."
+              }
+            }
           },
           "platform": {
             "type": "number",
-            "enum": [1, 2, 3, 4, 5, 6, 7],
-            "description": "登录设备平台：1=Android, 2=aPad, 3=Watch, 4=iMac, 5=iPad, 6=Tim, 7=Custom"
+            "enum": [
+              1,
+              2,
+              3,
+              4,
+              5,
+              6,
+              7
+            ],
+            "description": "登录设备平台：1=Android, 2=aPad, 3=Watch, 4=iMac, 5=iPad, 6=Tim, 7=Custom",
+            "x-i18n": {
+              "en": {
+                "description": "Login device platform: 1=Android, 2=aPad, 3=Watch, 4=iMac, 5=iPad, 6=Tim, 7=Custom."
+              }
+            }
           },
           "ver": {
             "type": "string",
-            "description": "协议版本号"
+            "description": "协议版本号",
+            "x-i18n": {
+              "en": {
+                "description": "Protocol version."
+              }
+            }
           },
           "signApiAddr": {
             "type": "string",
-            "description": "签名服务器地址"
+            "description": "签名服务器地址",
+            "x-i18n": {
+              "en": {
+                "description": "Signing server URL."
+              }
+            }
           },
           "dataDir": {
             "type": "string",
-            "description": "数据存储文件夹路径"
+            "description": "数据存储文件夹路径",
+            "x-i18n": {
+              "en": {
+                "description": "Data directory path."
+              }
+            }
           },
           "autoReconnect": {
             "type": "boolean",
-            "description": "断线后是否自动重连"
+            "description": "断线后是否自动重连",
+            "x-i18n": {
+              "en": {
+                "description": "Reconnect automatically after disconnecting."
+              }
+            }
           },
           "outboundMedia": {
             "type": "string",
-            "enum": ["file", "base64"],
-            "description": "出站媒体模式"
+            "enum": [
+              "file",
+              "base64"
+            ],
+            "description": "出站媒体模式",
+            "x-i18n": {
+              "en": {
+                "description": "Outbound media mode."
+              }
+            }
           },
           "ignoreSelf": {
             "type": "boolean",
-            "description": "是否过滤自己的消息"
+            "description": "是否过滤自己的消息",
+            "x-i18n": {
+              "en": {
+                "description": "Filter the bot's own messages."
+              }
+            }
           },
           "resend": {
             "type": "boolean",
-            "description": "被风控时是否分片发送"
+            "description": "被风控时是否分片发送",
+            "x-i18n": {
+              "en": {
+                "description": "Use fragmented sending when rate-limited by the platform."
+              }
+            }
           },
           "cacheGroupMember": {
             "type": "boolean",
-            "description": "是否缓存群员列表"
+            "description": "是否缓存群员列表",
+            "x-i18n": {
+              "en": {
+                "description": "Cache group member lists."
+              }
+            }
           },
           "autoServer": {
             "type": "boolean",
-            "description": "是否自动选择最优服务器"
+            "description": "是否自动选择最优服务器",
+            "x-i18n": {
+              "en": {
+                "description": "Automatically select the optimal server."
+              }
+            }
           },
           "qqnt": {
             "type": "boolean",
-            "description": "是否使用 QQNT 协议"
+            "description": "是否使用 QQNT 协议",
+            "x-i18n": {
+              "en": {
+                "description": "Use the QQNT protocol."
+              }
+            }
           },
           "ntLogin": {
             "type": "boolean",
-            "description": "是否使用 NT 登录方式"
+            "description": "是否使用 NT 登录方式",
+            "x-i18n": {
+              "en": {
+                "description": "Use the NT login method."
+              }
+            }
           },
           "commandPrefix": {
             "type": "string",
-            "description": "本 endpoint 的命令前缀"
+            "description": "本 endpoint 的命令前缀",
+            "x-i18n": {
+              "en": {
+                "description": "Command prefix for this endpoint."
+              }
+            }
           }
         },
-        "required": ["id"]
+        "required": [
+          "id"
+        ]
+      },
+      "x-i18n": {
+        "en": {
+          "description": "Multiple accounts: mount multiple endpoints in one plugin instance. Each entry uses the top-level fields; id is required and other fields override defaults."
+        }
       }
     },
     "commandPrefix": {
       "type": "string",
       "default": "",
-      "description": "命令前缀（默认 '' 无前缀）。endpoints[i] 可逐项覆盖"
+      "description": "命令前缀（默认 '' 无前缀）。endpoints[i] 可逐项覆盖",
+      "x-i18n": {
+        "en": {
+          "description": "Command prefix, empty by default. Each endpoints[i] can override it."
+        }
+      }
     }
   },
-  "required": ["master", "endpoints"]
+  "required": [
+    "master",
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -39,6 +39,7 @@ import {
   type IcqqMessageEvent,
 } from './icqq-inbound.js';
 import {
+  icqqNoticeDedupeKey,
   isIcqqNoticePayload,
   isIcqqRequestPayload,
 } from './icqq-inbox.js';
@@ -62,11 +63,13 @@ import {
 import type { SystemMessage as IcqqSystemMessage } from './types.js';
 import { ManagedIcqqClient, type IcqqBackgroundOperation } from './managed-client.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
+import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 
 export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
   readonly config: ResolvedIcqqConfig;
   readonly loginAssist: LoginAssist;
+  readonly locale?: import('zhin.js/i18n').Locale;
 }
 
 const BOUND_EVENTS = [
@@ -114,6 +117,8 @@ export class IcqqEndpoint extends Endpoint<Client> {
 
   readonly management: EndpointManagement = Object.freeze<EndpointManagement>({
     inspectGroupMember: (group, user, signal) => inspectGroupMember(this.client, group, user, signal),
+    inspectGroupScene: (group, signal) => inspectGroupScene(this.client, group, signal),
+    inspectGroupMemberProfile: (group, user, signal) => inspectGroupMemberProfile(this.client, group, user, signal),
     moderateGroupMember: (group, user, action, signal) => moderateGroupMember(
       this.client, group, user, action, signal, () => this.#open && !this.#retiring && !this.#stopped,
     ),
@@ -149,6 +154,11 @@ export class IcqqEndpoint extends Endpoint<Client> {
     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');
+      }
+    },
   });
 
   readonly control: EndpointControl = Object.freeze({
@@ -699,6 +709,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
     this.#logSystemEvent(`login.${step}`, event);
     void runIcqqLoginAssistStep({
       assist: this.#options.loginAssist,
+      locale: this.#options.locale,
       client: this.client,
       adapter: 'icqq',
       endpointKey: this.endpointName,
@@ -816,6 +827,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
       channelType: normalized.channelType,
       channelId: normalized.channelId,
       channelParentGroupId: normalized.channelParentGroupId,
+      name: normalized.groupName,
     });
     const quoteId = resolveIcqqQuoteIdFromEvent(data);
     const quoted = messageLookupFromIcqqSource(findIcqqNestedMessageSource(data));
@@ -935,13 +947,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
 
   #onNoticeEvent(payload: Record<string, unknown> | null): void {
     if (!payload || !isIcqqNoticePayload(payload)) return;
-    const key = [
-      payload.time,
-      payload.operator_id ?? payload.user_id,
-      payload.notice_type ?? payload.type,
-      payload.sub_type,
-    ].join('_');
-    if (!this.#sideEventDeduper.shouldProcess(`notice:${key}`)) return;
+    if (!this.#sideEventDeduper.shouldProcess(icqqNoticeDedupeKey(payload))) return;
     this.#dispatchIcqqSideEvent(payload);
   }
 

package/src/group-moderation.ts

@@ -8,17 +8,22 @@ export async function inspectGroupMember(
   signal.throwIfAborted();
   const group = numericId(groupId);
   const user = numericId(userId);
+  const selfLookup = client.getGroupMemberInfo(group, client.uin, true);
   const [self, member] = await Promise.all([
-    client.getGroupMemberInfo(group, client.uin, true),
-    client.getGroupMemberInfo(group, user, true),
+    selfLookup,
+    user === client.uin ? selfLookup : client.getGroupMemberInfo(group, user, true),
   ]);
   signal.throwIfAborted();
   const joinedAt = member.join_time * 1000;
+  const platformRole = member.user_id === user && member.group_id === group
+    && (member.role === 'owner' || member.role === 'admin' || member.role === 'member')
+    ? member.role : undefined;
   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',
+    ...(platformRole ? { platformRole } : {}),
     ...(Number.isSafeInteger(joinedAt) && joinedAt > 0 && joinedAt <= Date.now() ? { joinedAt } : {}),
   };
 }

package/src/group-scene.ts

@@ -0,0 +1,76 @@
+import type { Client } from '@icqqjs/icqq';
+import type { GroupMemberProfile, GroupSceneFacts } from 'zhin.js/adapter';
+
+/** 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: unknown): string | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
+}
+
+function numericId(value: string): number {
+  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: Client, groupId: string, signal: AbortSignal): Promise<GroupSceneFacts> {
+  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: string[] | undefined;
+  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 is string => 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: Client, groupId: string, userId: string, signal: AbortSignal,
+): Promise<GroupMemberProfile> {
+  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/src/i18n.ts

@@ -0,0 +1,48 @@
+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/src/icqq-inbound.ts

@@ -129,6 +129,8 @@ export interface NormalizedIcqqInbound {
   channelId: string;
   /** 群临时会话：来源群号 */
   channelParentGroupId?: string;
+  /** 群聊时来自 group_name */
+  groupName?: string;
   userId: string;
   nickname: string;
   /** 群聊时来自 sender.role（私聊无） */
@@ -847,6 +849,9 @@ export function normalizeIcqqInboundMessage(
     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/src/icqq-inbox.ts

@@ -20,6 +20,21 @@ export function isIcqqNoticePayload(payload: unknown): boolean {
     && (postType === 'notice' || postType.startsWith('notice.'));
 }
 
+/**
+ * notice 去重键。成员与操作人分开记：同一管理员先后拉两个人进群时，`operator_id ?? user_id`
+ * 会撞键（icqq 群通知又常不带 time），后一次入群被当重复吞掉。
+ */
+export function icqqNoticeDedupeKey(payload: Record<string, unknown>): string {
+  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；两者皆无则无法审批，丢弃。