@zhin.js/adapter-icqq 1.1.21 → 1.1.23

package/agents/icqq/skills/icqq-group-admin/tools/set_mute/index.js

@@ -11,6 +11,8 @@ export default defineAgentTool({
         duration: z.number().describe('禁言时间(秒)，0=解除禁言').default(0),
     }),
     adapter: 'icqq',
+    // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+    requiresCapabilities: ['actions.mute'],
     scopes: ['group'],
     requiresApproval: 'always',
     async execute({ group_id, user_id, duration }, context) {

package/agents/icqq/skills/icqq-group-admin/tools/set_mute/index.ts

@@ -10,6 +10,8 @@ export default defineAgentTool<{ group_id: number; user_id: number; duration?: n
     duration: z.number().describe('禁言时间(秒)，0=解除禁言').default(0),
   }),
   adapter: 'icqq',
+  // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+  requiresCapabilities: ['actions.mute'],
   scopes:['group'],
   requiresApproval: 'always',
   async execute({ group_id, user_id, duration }, context) {

package/agents/icqq/skills/icqq-group-admin/tools/set_title/index.js

@@ -12,6 +12,8 @@ export default defineAgentTool({
         duration: z.number().optional().describe('持续时间(秒)，-1永久').default(-1),
     }),
     adapter: 'icqq',
+    // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+    requiresCapabilities: ['actions.setTitle'],
     scopes: ['group'],
     requiresApproval: 'always',
     async execute({ group_id, user_id, title, duration }, context) {

package/agents/icqq/skills/icqq-group-admin/tools/set_title/index.ts

@@ -11,6 +11,8 @@ export default defineAgentTool<{ group_id: number; user_id: number; title: strin
     duration: z.number().optional().describe('持续时间(秒)，-1永久').default(-1),
   }),
   adapter: 'icqq',
+  // ADR 0044: offered only while the Bot can actually do this here (e.g. it is a group admin).
+  requiresCapabilities: ['actions.setTitle'],
   scopes:['group'],
   requiresApproval: 'always',
   async execute({ group_id, user_id, title, duration }, context) {

package/lib/endpoint.js

@@ -2,7 +2,8 @@ import { parseGroupMessageId, } from '@icqqjs/icqq';
 import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createEndpointSpecification, endpointSpec, createEndpointOperation, } from 'zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments } from '@zhin.js/core';
+import { receiveOneBotLikeSideEvent } from '@zhin.js/adapter-onebot-events';
+import { buildSystem, toCanonicalSegments } from '@zhin.js/core';
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
@@ -13,6 +14,7 @@ import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guil
 import { prepareIcqqOutboundMedia, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
 import { formatInboundContent, formatOutboundMessageParts, normalizeIcqqImageMedia, icqqInboundConversation, icqqOutboundTarget, } from './protocol.js';
 import { ManagedIcqqClient } from './managed-client.js';
+import { createIcqqActionPorts } from './group-actions.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
 import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 import { createIcqqSelfProfile } from './self-profile.js';
@@ -108,6 +110,7 @@ export class IcqqEndpoint extends ManagedIcqqClient {
                 throw new Error('QQ did not confirm the group notice');
             }
         },
+        ...createIcqqActionPorts(() => this),
     });
     #control = Object.freeze({
         recall: async ({ message, signal }) => {

package/lib/group-actions.d.ts

@@ -0,0 +1,10 @@
+import type { Client } from '@icqqjs/icqq';
+import { type EndpointManagement } from 'zhin.js/adapter';
+type ActionPorts = Pick<EndpointManagement, 'pokeUser' | 'unmuteGroupMember' | 'muteAllGroupMembers' | 'setGroupCard' | 'setGroupTitle' | 'setGroupEssence' | 'inviteGroupMember'>;
+/**
+ * ADR 0044 action ports of the icqq endpoint. Where the bot's role decides the outcome the role is
+ * read fresh from the platform first, so a stale cache can neither allow nor refuse the action.
+ * Each request carries its own lifetime: reads are `prepare`, the native effect is `run`.
+ */
+export declare function createIcqqActionPorts(getClient: () => Client): ActionPorts;
+export {};

package/lib/group-actions.js

@@ -0,0 +1,94 @@
+import { createEndpointOperation } from 'zhin.js/adapter';
+function numericId(value) {
+    const id = Number(value);
+    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(id))
+        throw new Error('Invalid QQ identifier');
+    return id;
+}
+/** Uncached member lookup; `pickMember` and the cached roster would report stale roles. */
+async function freshMember(operation, client, group, user) {
+    try {
+        const member = await operation.prepare(() => client.getGroupMemberInfo(group, user, true));
+        return member.user_id === user && member.group_id === group ? member : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function requireBotRole(operation, client, group, roles, message) {
+    const self = await freshMember(operation, client, group, client.uin);
+    if (!self || !roles.includes(self.role))
+        throw new Error(message);
+}
+function confirmed(ok, what) {
+    if (ok === false)
+        throw new Error(`QQ did not confirm ${what}`);
+}
+/**
+ * ADR 0044 action ports of the icqq endpoint. Where the bot's role decides the outcome the role is
+ * read fresh from the platform first, so a stale cache can neither allow nor refuse the action.
+ * Each request carries its own lifetime: reads are `prepare`, the native effect is `run`.
+ */
+export function createIcqqActionPorts(getClient) {
+    return {
+        async pokeUser({ userId, groupId, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const user = numericId(userId);
+            confirmed(groupId === undefined
+                ? await operation.run(() => client.pickFriend(user).poke(false))
+                : await operation.run(() => client.sendGroupPoke(numericId(groupId), user)), 'poke');
+        },
+        async unmuteGroupMember({ groupId, userId, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+            confirmed(await operation.run(() => client.setGroupBan(group, numericId(userId), 0)), 'unmute');
+        },
+        async muteAllGroupMembers({ groupId, enabled, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+            confirmed(await operation.run(() => client.setGroupWholeBan(group, enabled)), 'whole-group mute');
+        },
+        async setGroupCard({ groupId, userId, card, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            const user = numericId(userId);
+            if (user !== client.uin)
+                await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+            confirmed(await operation.run(() => client.setGroupCard(group, user, card)), 'card change');
+        },
+        async setGroupTitle({ groupId, userId, title, durationSeconds, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            const user = numericId(userId);
+            await requireBotRole(operation, client, group, ['owner'], 'Only the group owner can set special titles');
+            if (!await freshMember(operation, client, group, user))
+                throw new Error('Target is not a group member');
+            confirmed(await operation.run(() => client.setGroupSpecialTitle(group, user, title, durationSeconds ?? -1)), 'title change');
+        },
+        async setGroupEssence({ groupId, messageId, enabled, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            await requireBotRole(operation, client, numericId(groupId), ['owner', 'admin'], 'Bot is not a group admin');
+            if (enabled)
+                await operation.run(() => client.setEssenceMessage(messageId));
+            else
+                await operation.run(() => client.removeEssenceMessage(messageId));
+        },
+        async inviteGroupMember({ groupId, userId, signal }) {
+            const client = getClient();
+            const operation = createEndpointOperation({ signal });
+            const group = numericId(groupId);
+            const user = numericId(userId);
+            if (await freshMember(operation, client, group, user))
+                throw new Error('Target is already a group member');
+            confirmed(await operation.run(() => client.inviteFriend(group, user)), 'invitation');
+        },
+    };
+}

package/lib/icqq-inbound.d.ts

@@ -2,6 +2,7 @@
  * icqq 入站事件归一化（post_type / message_type / message 段）
  */
 import { type MessageSegment } from "zhin.js";
+import { InboundMessageDeduper } from "zhin.js/adapter";
 import type { GroupRole } from "./types.js";
 /** 守护进程推送的通用事件壳 */
 export interface IcqqEventBase {
@@ -163,9 +164,4 @@ export declare function resolveIcqqQuoteIdFromEvent(data: IcqqMessageEvent): str
 export declare function resolveInboundContent(data: IcqqMessageEvent): MessageSegment[];
 export declare function normalizeIcqqInboundMessage(data: IcqqMessageEvent): NormalizedIcqqInbound | null;
 /** 按 message_id 去重（多路 subscribe 会收到同一消息多次） */
-export declare class InboundMessageDeduper {
-    private readonly seen;
-    shouldProcess(messageId: string): boolean;
-    clear(): void;
-}
-export {};
+export { InboundMessageDeduper };

package/lib/icqq-inbound.js

@@ -2,6 +2,7 @@
  * icqq 入站事件归一化（post_type / message_type / message 段）
  */
 import { toCanonicalSegments } from "zhin.js";
+import { InboundMessageDeduper, promoteInboundMessagePayload } from "zhin.js/adapter";
 import { parseCqMessage, icqqMediaRefFromString } from "./cq-message.js";
 import { extractForwardResidFromJsonElement } from "./forward-msg.js";
 /**
@@ -32,7 +33,6 @@ export async function resolveIcqqInboundMedia(elements, resolver) {
         }
     }));
 }
-const DEDUPE_TTL_MS = 120_000;
 const ICQQ_GROUP_ROLES = new Set(["owner", "admin", "member"]);
 /** 从 sender.role 解析群成员角色（供 Message.$sender → resolveSenderRoles） */
 export function parseIcqqSenderGroupRole(sender) {
@@ -51,14 +51,8 @@ export function isIcqqBotMentioned(input) {
     const uin = String(input.uin ?? "").trim();
     if (!uin)
         return false;
-    for (const seg of input.content ?? []) {
-        if (!seg || (seg.type !== "at" && seg.type !== "mention"))
-            continue;
-        const data = (seg.data ?? {});
-        const target = String(data.qq ?? data.user_id ?? data.id ?? data.target ?? "").trim();
-        if (target && target !== "all" && Number(target) === Number(uin)) {
-            return true;
-        }
+    if (promoteInboundMessagePayload({ segments: input.content ?? [] }, uin).mentioned === true) {
+        return true;
     }
     const raw = input.rawMessage ?? "";
     if (!raw)
@@ -648,10 +642,7 @@ function mergeReplyFromSource(content, data) {
     ];
 }
 function quoteIdFromSegments(content) {
-    const reply = content.find((item) => item.type === 'reply');
-    const data = reply?.data;
-    const value = data?.message_id ?? data?.id;
-    return value == null || !String(value).trim() ? undefined : String(value).trim();
+    return promoteInboundMessagePayload({ segments: content }, undefined).replyTo?.id;
 }
 export function resolveInboundContent(data) {
     const fromElements = icqqElementsToSegments(data.message);
@@ -701,20 +692,4 @@ export function normalizeIcqqInboundMessage(data) {
     };
 }
 /** 按 message_id 去重（多路 subscribe 会收到同一消息多次） */
-export class InboundMessageDeduper {
-    seen = new Map();
-    shouldProcess(messageId) {
-        const now = Date.now();
-        for (const [id, t] of this.seen) {
-            if (now - t > DEDUPE_TTL_MS)
-                this.seen.delete(id);
-        }
-        if (this.seen.has(messageId))
-            return false;
-        this.seen.set(messageId, now);
-        return true;
-    }
-    clear() {
-        this.seen.clear();
-    }
-}
+export { InboundMessageDeduper };

package/lib/outbound-media.js

@@ -43,21 +43,27 @@ export function prepareIcqqOutboundMedia(content, mode = "file") {
             return seg;
         const d = data;
         const media = d.media;
-        if (!isMediaRef(media) || media.kind !== "base64")
-            return seg;
-        const b64 = media.value.replace(/^base64:\/\//, "");
+        let b64 = "";
+        let mime = "";
+        if (isMediaRef(media) && media.kind === "base64") {
+            b64 = media.value.replace(/^base64:\/\//, "");
+            mime = media.mime_type ?? "";
+        }
+        else if (typeof d.file === "string" && d.file.startsWith("base64://")) {
+            b64 = d.file.slice("base64://".length);
+        }
         if (!b64)
             return seg;
         if (type !== "image" && type !== "record" && type !== "audio" && type !== "video") {
             return seg;
         }
-        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: {
                 ...d,
+                ...(typeof d.file === "string" && d.file.startsWith("base64://") ? { file: filePath } : {}),
                 media: {
                     kind: "path",
                     value: filePath,

package/lib/sensitive-commands.d.ts

@@ -0,0 +1,8 @@
+import type { SensitiveExecCommandRule } from '@zhin.js/agent';
+/**
+ * The `icqq` command-line client can kick members, move money and delete files. Under an `allowlist`
+ * exec policy its non-sensitive subcommands run freely, while these need owner approval (ADR 0044:
+ * this knowledge lives with the adapter, the exec policy only reads the registered rule).
+ */
+export declare const ICQQ_SENSITIVE_SUBCOMMAND_REGEXES: readonly RegExp[];
+export declare const icqqSensitiveExecRule: SensitiveExecCommandRule;

package/lib/sensitive-commands.js

@@ -0,0 +1,16 @@
+/**
+ * The `icqq` command-line client can kick members, move money and delete files. Under an `allowlist`
+ * exec policy its non-sensitive subcommands run freely, while these need owner approval (ADR 0044:
+ * this knowledge lives with the adapter, the exec policy only reads the registered rule).
+ */
+export const ICQQ_SENSITIVE_SUBCOMMAND_REGEXES = Object.freeze([
+    /\bicqq\s+friend\s+(?:delete|block|move)\b/i,
+    /\bicqq\s+group\s+(?:kick|mute|set|admin|announce|transfer|quit|dissolve|invite)\b/i,
+    /\bicqq\s+(?:request|wallet|pay|recall)\b/i,
+    /\bicqq\s+file\s+(?:upload|delete)\b/i,
+    /\bicqq\s+gfs\b.*\b(?:rm|delete|del)\b/i,
+]);
+export const icqqSensitiveExecRule = Object.freeze({
+    command: 'icqq',
+    sensitive: ICQQ_SENSITIVE_SUBCOMMAND_REGEXES,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.21",
+  "version": "1.1.23",
   "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,32 +33,37 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.27",
-    "@zhin.js/agent-feature": "1.1.12",
-    "@zhin.js/client": "1.1.23",
+    "@zhin.js/adapter-onebot-events": "0.0.2",
+    "@zhin.js/adapter": "1.1.29",
+    "@zhin.js/agent-feature": "1.1.14",
+    "@zhin.js/client": "1.1.25",
     "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.55",
-    "@zhin.js/feature-kit": "1.1.11",
-    "@zhin.js/im-contract": "1.1.10",
+    "@zhin.js/core": "1.1.57",
+    "@zhin.js/feature-kit": "1.1.13",
+    "@zhin.js/im-contract": "1.1.12",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.13",
-    "@zhin.js/permission": "1.1.11",
-    "@zhin.js/skill": "1.1.12",
-    "@zhin.js/tool": "1.1.14"
+    "@zhin.js/page": "1.1.15",
+    "@zhin.js/permission": "1.1.13",
+    "@zhin.js/skill": "1.1.14",
+    "@zhin.js/tool": "1.1.16"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.27",
-    "@zhin.js/command": "^1.1.13",
-    "@zhin.js/core": "^1.1.55",
-    "@zhin.js/prompt-section": "^1.1.11",
-    "zhin.js": "^1.1.20"
+    "@zhin.js/adapter": "^1.1.29",
+    "@zhin.js/agent": "^1.1.48",
+    "@zhin.js/command": "^1.1.15",
+    "@zhin.js/core": "^1.1.57",
+    "@zhin.js/prompt-section": "^1.1.13",
+    "zhin.js": "^1.1.22"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
       "optional": true
     },
+    "@zhin.js/agent": {
+      "optional": true
+    },
     "@zhin.js/command": {
       "optional": true
     },
@@ -78,8 +83,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/prompt-section": "1.1.11",
-    "zhin.js": "1.1.20"
+    "@zhin.js/agent": "1.1.48",
+    "@zhin.js/prompt-section": "1.1.13",
+    "zhin.js": "1.1.22"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -1,9 +1,12 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
 import { permissionHostToken, createSceneRolePlatformChecker } from '@zhin.js/permission';
+import { registerSensitiveExecCommand } from '@zhin.js/agent';
 import { createIcqqConsoleRpc } from "./lib/console.js";
+import { icqqSensitiveExecRule } from "./lib/sensitive-commands.js";
 export default definePlugin({
     name: 'icqq',
+    configUpdate: { featurePaths: [['nickname'], ['profile'], ['endpoints']] },
     metadata: {
         displayName: 'ICQQ Adapter',
     },
@@ -12,6 +15,10 @@ export default definePlugin({
         const disposePlatform = context.resources.has(permissionHostToken)
             ? context.resources.use(permissionHostToken).registerPlatform('icqq', createSceneRolePlatformChecker())
             : undefined;
-        return disposePlatform;
+        const disposeExecRule = registerSensitiveExecCommand(icqqSensitiveExecRule);
+        return () => {
+            disposeExecRule();
+            disposePlatform?.();
+        };
     },
 });

package/src/endpoint.ts

@@ -33,7 +33,8 @@ import {
   type EndpointGroupNoticeRequest,
 } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments, type LoginAssist, type LoginAssistEndpointIdentity, type PendingLoginTask } from '@zhin.js/core';
+import { receiveOneBotLikeSideEvent } from '@zhin.js/adapter-onebot-events';
+import { buildSystem, toCanonicalSegments, type LoginAssist, type LoginAssistEndpointIdentity, type PendingLoginTask } from '@zhin.js/core';
 import { EndpointDeliveryError, type EndpointSendPart, type EndpointSendResult, type MessageRef } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -77,6 +78,7 @@ import {
 } from './protocol.js';
 import type { SystemMessage as IcqqSystemMessage } from './types.js';
 import { ManagedIcqqClient, type IcqqBackgroundOperation } from './managed-client.js';
+import { createIcqqActionPorts } from './group-actions.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
 import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 import { createIcqqSelfProfile } from './self-profile.js';
@@ -189,6 +191,7 @@ export class IcqqEndpoint extends ManagedIcqqClient implements Endpoint {
         throw new Error('QQ did not confirm the group notice');
       }
     },
+    ...createIcqqActionPorts(() => this),
   });
 
   readonly #control: EndpointControl = Object.freeze<EndpointControl>({

package/src/group-actions.ts

@@ -0,0 +1,105 @@
+import type { Client, MemberInfo } from '@icqqjs/icqq';
+import { createEndpointOperation, type EndpointManagement, type EndpointOperation } from 'zhin.js/adapter';
+
+type ActionPorts = Pick<
+  EndpointManagement,
+  | 'pokeUser'
+  | 'unmuteGroupMember'
+  | 'muteAllGroupMembers'
+  | 'setGroupCard'
+  | 'setGroupTitle'
+  | 'setGroupEssence'
+  | 'inviteGroupMember'
+>;
+
+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;
+}
+
+/** Uncached member lookup; `pickMember` and the cached roster would report stale roles. */
+async function freshMember(operation: EndpointOperation, client: Client, group: number, user: number): Promise<MemberInfo | undefined> {
+  try {
+    const member = await operation.prepare(() => client.getGroupMemberInfo(group, user, true));
+    return member.user_id === user && member.group_id === group ? member : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function requireBotRole(operation: EndpointOperation, client: Client, group: number, roles: readonly string[], message: string): Promise<void> {
+  const self = await freshMember(operation, client, group, client.uin);
+  if (!self || !roles.includes(self.role)) throw new Error(message);
+}
+
+function confirmed(ok: unknown, what: string): void {
+  if (ok === false) throw new Error(`QQ did not confirm ${what}`);
+}
+
+/**
+ * ADR 0044 action ports of the icqq endpoint. Where the bot's role decides the outcome the role is
+ * read fresh from the platform first, so a stale cache can neither allow nor refuse the action.
+ * Each request carries its own lifetime: reads are `prepare`, the native effect is `run`.
+ */
+export function createIcqqActionPorts(getClient: () => Client): ActionPorts {
+  return {
+    async pokeUser({ userId, groupId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const user = numericId(userId);
+      confirmed(
+        groupId === undefined
+          ? await operation.run(() => client.pickFriend(user).poke(false))
+          : await operation.run(() => client.sendGroupPoke(numericId(groupId), user)),
+        'poke',
+      );
+    },
+    async unmuteGroupMember({ groupId, userId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupBan(group, numericId(userId), 0)), 'unmute');
+    },
+    async muteAllGroupMembers({ groupId, enabled, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupWholeBan(group, enabled)), 'whole-group mute');
+    },
+    async setGroupCard({ groupId, userId, card, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      if (user !== client.uin) await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupCard(group, user, card)), 'card change');
+    },
+    async setGroupTitle({ groupId, userId, title, durationSeconds, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      await requireBotRole(operation, client, group, ['owner'], 'Only the group owner can set special titles');
+      if (!await freshMember(operation, client, group, user)) throw new Error('Target is not a group member');
+      confirmed(await operation.run(() => client.setGroupSpecialTitle(group, user, title, durationSeconds ?? -1)), 'title change');
+    },
+    async setGroupEssence({ groupId, messageId, enabled, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      await requireBotRole(operation, client, numericId(groupId), ['owner', 'admin'], 'Bot is not a group admin');
+      if (enabled) await operation.run(() => client.setEssenceMessage(messageId));
+      else await operation.run(() => client.removeEssenceMessage(messageId));
+    },
+    async inviteGroupMember({ groupId, userId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      if (await freshMember(operation, client, group, user)) throw new Error('Target is already a group member');
+      confirmed(await operation.run(() => client.inviteFriend(group, user)), 'invitation');
+    },
+  };
+}

package/src/icqq-inbound.ts

@@ -2,6 +2,7 @@
  * icqq 入站事件归一化（post_type / message_type / message 段）
  */
 import { toCanonicalSegments, type MessageSegment } from "zhin.js";
+import { InboundMessageDeduper, promoteInboundMessagePayload } from "zhin.js/adapter";
 import { parseCqMessage, icqqMediaRefFromString } from "./cq-message.js";
 import { extractForwardResidFromJsonElement } from "./forward-msg.js";
 import type { GroupRole } from "./types.js";
@@ -141,8 +142,6 @@ export interface NormalizedIcqqInbound {
   raw: IcqqMessageEvent;
 }
 
-const DEDUPE_TTL_MS = 120_000;
-
 const ICQQ_GROUP_ROLES = new Set<GroupRole>(["owner", "admin", "member"]);
 
 /** 从 sender.role 解析群成员角色（供 Message.$sender → resolveSenderRoles） */
@@ -167,15 +166,13 @@ export function isIcqqBotMentioned(input: {
 }): boolean {
   const uin = String(input.uin ?? "").trim();
   if (!uin) return false;
-  for (const seg of input.content ?? []) {
-    if (!seg || (seg.type !== "at" && seg.type !== "mention")) continue;
-    const data = (seg.data ?? {}) as Record<string, unknown>;
-    const target = String(
-      data.qq ?? data.user_id ?? data.id ?? data.target ?? "",
-    ).trim();
-    if (target && target !== "all" && Number(target) === Number(uin)) {
-      return true;
-    }
+  if (
+    promoteInboundMessagePayload<{ segments: readonly MessageSegment[]; mentioned?: boolean }>(
+      { segments: input.content ?? [] },
+      uin,
+    ).mentioned === true
+  ) {
+    return true;
   }
   const raw = input.rawMessage ?? "";
   if (!raw) return false;
@@ -805,10 +802,10 @@ function mergeReplyFromSource(
 }
 
 function quoteIdFromSegments(content: readonly MessageSegment[]): string | undefined {
-  const reply = content.find((item) => item.type === 'reply');
-  const data = reply?.data as Readonly<Record<string, unknown>> | undefined;
-  const value = data?.message_id ?? data?.id;
-  return value == null || !String(value).trim() ? undefined : String(value).trim();
+  return promoteInboundMessagePayload<{ segments: readonly MessageSegment[]; replyTo?: { readonly id: string } }>(
+    { segments: content },
+    undefined,
+  ).replyTo?.id;
 }
 
 export function resolveInboundContent(
@@ -863,20 +860,4 @@ export function normalizeIcqqInboundMessage(
 }
 
 /** 按 message_id 去重（多路 subscribe 会收到同一消息多次） */
-export class InboundMessageDeduper {
-  private readonly seen = new Map<string, number>();
-
-  shouldProcess(messageId: string): boolean {
-    const now = Date.now();
-    for (const [id, t] of this.seen) {
-      if (now - t > DEDUPE_TTL_MS) this.seen.delete(id);
-    }
-    if (this.seen.has(messageId)) return false;
-    this.seen.set(messageId, now);
-    return true;
-  }
-
-  clear(): void {
-    this.seen.clear();
-  }
-}
+export { InboundMessageDeduper };