@zhin.js/adapter-icqq 1.1.14 → 1.1.15

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.15
+
+### Patch Changes
+
+- 7d68df6: 精简 Agent 内置固定提示词与消息说明，保留工具、审批和结构化回复能力。适配器 Skill 按会话场景拆分，群／频道管理仅向对应场景披露；提示段与模型消息段支持场景声明，沿用当前回合权限和 generation 投影。
+- e91235e: Let the bot answer with a reaction, the way a person taps 👍 instead of typing. Adapters declare reactions with `segments.reaction` (values with meanings, optional scopes); the reply schema then has a `reaction` field limited to those values, the instruction says when a reaction alone is enough, and the reply port applies it to the message being answered before any words. icqq offers 21 QQ face reactions in groups.
+- 3781f1c: 支持多模态感知备用模型和 ICQQ 原创表情识图；增强语音回复的使用指引与错误提示，让已启用的 TTS 回复无需逐次审批。ICQQ 踢人工具使用 human 策略，每次都要求独立人工审批，不能由自动审核或历史授权替代。
+
+  内容审核支持按账号和群显式开启广告、辱骂审核：提醒、警告、10 分钟禁言，通知通过 @ 对应成员说明处理结果，30 分钟无新违规重置；提醒/警告是否撤回原消息由模型结合上下文决定。入群 10 分钟内的明确广告可直接踢出，执行前刷新权限和入群时间；审核、通知或平台操作结果不确定时不盲目重试。
+
+  并发消息独立审核并按到达顺序保存上下文，仅处罚和通知使用成员预留；重复投递不覆盖正在等待的撤回决定。接受完整 JSON 代码块，记录无效审核结果。人工确认显示具体参数，并在等待确认时隔离参数，确保批准对象与执行对象一致。
+
+- Updated dependencies [f98025b]
+- Updated dependencies [66ec1a5]
+- Updated dependencies [7d68df6]
+- Updated dependencies [bf0fa9f]
+- Updated dependencies [3326db3]
+- Updated dependencies [e91235e]
+- Updated dependencies [6da2bad]
+- Updated dependencies [3781f1c]
+  - @zhin.js/core@1.1.50
+  - @zhin.js/adapter@1.1.22
+  - @zhin.js/im-contract@1.1.6
+  - @zhin.js/tool@1.1.9
+  - @zhin.js/agent-feature@1.1.9
+  - @zhin.js/feature-kit@1.1.8
+  - @zhin.js/permission@1.1.8
+  - @zhin.js/skill@1.1.9
+
 ## 1.1.14
 
 ### Patch Changes

package/adapters/icqq/index.js

@@ -16,6 +16,19 @@ export default defineAdapter({
         supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps', 'share'],
         outboundMedia: ['base64', 'url', 'path'],
         interactive: 'text',
+        // QQ group reactions take system face ids; private chats have no reactions.
+        reaction: {
+            scopes: ['group'],
+            values: [
+                { value: '76', label: '赞' }, { value: '66', label: '爱心' }, { value: '124', label: 'OK' },
+                { value: '99', label: '鼓掌' }, { value: '144', label: '喝彩' }, { value: '320', label: '庆祝' },
+                { value: '319', label: '比心' }, { value: '299', label: '牛啊' }, { value: '297', label: '拜谢' },
+                { value: '182', label: '笑哭' }, { value: '179', label: 'doge' }, { value: '264', label: '捂脸' },
+                { value: '271', label: '吃瓜' }, { value: '269', label: '暗中观察' }, { value: '268', label: '问号脸' },
+                { value: '270', label: 'emm' }, { value: '106', label: '委屈' }, { value: '285', label: '摸鱼' },
+                { value: '104', label: '哈欠' }, { value: '267', label: '头秃' }, { value: '326', label: '生气' },
+            ],
+        },
         model: {
             share: {
                 fields: ['description', 'image', 'audio', 'platform'],

package/adapters/icqq/index.ts

@@ -27,6 +27,19 @@ export default defineAdapter<IcqqEndpointConfig>({
     supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps', 'share'],
     outboundMedia: ['base64', 'url', 'path'],
     interactive: 'text',
+    // QQ group reactions take system face ids; private chats have no reactions.
+    reaction: {
+      scopes: ['group'],
+      values: [
+        { value: '76', label: '赞' }, { value: '66', label: '爱心' }, { value: '124', label: 'OK' },
+        { value: '99', label: '鼓掌' }, { value: '144', label: '喝彩' }, { value: '320', label: '庆祝' },
+        { value: '319', label: '比心' }, { value: '299', label: '牛啊' }, { value: '297', label: '拜谢' },
+        { value: '182', label: '笑哭' }, { value: '179', label: 'doge' }, { value: '264', label: '捂脸' },
+        { value: '271', label: '吃瓜' }, { value: '269', label: '暗中观察' }, { value: '268', label: '问号脸' },
+        { value: '270', label: 'emm' }, { value: '106', label: '委屈' }, { value: '285', label: '摸鱼' },
+        { value: '104', label: '哈欠' }, { value: '267', label: '头秃' }, { value: '326', label: '生气' },
+      ],
+    },
     model: {
       share: {
         fields: ['description', 'image', 'audio', 'platform'],

package/agents/icqq/skills/icqq-directory/SKILL.md

@@ -2,19 +2,17 @@
 name: icqq-directory
 platforms:
   - icqq
-description: ICQQ 好友、群和成员目录查询能力。
+description: ICQQ 好友列表、群列表和用户资料查询。
 keywords:
-  - "icqq"
-  - "好友列表"
-  - "群列表"
-  - "成员信息"
+  - icqq
+  - 好友列表
+  - 群列表
+  - 用户资料
 tools:
-  - "friend_list"
-  - "group_list"
-  - "user_info"
-  - "group_member_info"
+  - friend_list
+  - group_list
+  - user_info
 ---
-
 # icqq-directory
 
-查询用户或群成员前先获取稳定 QQ 号或群号。目录信息只向群主、管理员、master 或 trusted 披露；不要根据昵称猜测身份。
+先查询稳定 QQ 号或群号，不猜测昵称对应的 ID。目录信息只向群主、管理员、master 或 trusted 披露。

package/agents/icqq/skills/icqq-group-admin/SKILL.md

@@ -4,22 +4,29 @@ platforms:
   - icqq
 description: ICQQ 邀请、踢人、禁言、头衔、匿名、公告和精华管理能力。
 keywords:
-  - "icqq"
-  - "群管理"
-  - "禁言"
-  - "踢人"
-  - "公告"
-  - "精华"
+  - icqq
+  - 群管理
+  - 禁言
+  - 踢人
+  - 公告
+  - 精华
 tools:
-  - "group_invite"
-  - "group_kick"
-  - "set_mute"
-  - "set_title"
-  - "set_anonymous"
-  - "announce"
-  - "essence"
+  - group_invite
+  - group_kick
+  - set_mute
+  - set_title
+  - set_anonymous
+  - announce
+  - essence
+scopes:
+  - group
 ---
-
 # icqq-group-admin
 
 仅在目标群和目标成员明确时加载。所有写操作遵守 Tool 审批与角色权限；不可逆或影响成员关系的操作先复核参数。
+
+自动管群必须先确认具体规则和目标群，不能仅凭权限许可自行制定触发条件。
+
+本技能的踢人工具每次都需人工审批，必须展示本次目标群、目标成员和理由；上一笔操作的批准不能授权下一笔踢人。
+
+已配置的自动审核流程可对入群 10 分钟内的明确广告直接踢出；该例外由审核流程核验，不授权本技能或普通对话绕过人工审批。

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

@@ -8,6 +8,7 @@ export default defineAgentTool({
         user_id: z.number().describe('要邀请的 QQ号'),
     }),
     adapter: 'icqq',
+    scopes: ["group"],
     requiresApproval: 'always',
     async execute({ group_id, user_id }, context) {
         const client = context.$client;

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

@@ -7,6 +7,7 @@ export default defineAgentTool<{ group_id: number; user_id: number }>({
     user_id: z.number().describe('要邀请的 QQ号'),
   }),
   adapter: 'icqq',
+  scopes: ["group"],
   requiresApproval: 'always',
   async execute({ group_id, user_id }, context) {
     const client = context.$client;

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

@@ -6,22 +6,24 @@ export default defineAgentTool({
     inputSchema: z.object({
         group_id: z.number().describe('目标群号'),
         user_id: z.number().describe('要踢出的成员 QQ号'),
+        reason: z.string().min(1).describe('本次踢人的具体原因，随目标群和成员一起供人工确认'),
     }),
     adapter: 'icqq',
     scopes: ['group'],
     permissions: ['role(master,admin,trusted,owner)'],
-    requiresApproval: 'once',
+    requiresApproval: 'human',
     async execute({ group_id, user_id }, context) {
         const client = context.$client;
-        const selfInfo = client.pickMember(group_id, client.uin);
-        if (!selfInfo.is_admin && !selfInfo.is_owner)
-            return { success: false, message: '机器人不是群主或管理员，无法踢出成员' };
-        if (selfInfo.user_id === user_id)
-            return { success: false, message: '机器人不能踢出自己' };
-        const memberInfo = client.pickMember(group_id, user_id);
-        if (!memberInfo)
-            return { success: false, message: '目标成员不存在' };
-        await client.setGroupKick(group_id, user_id);
+        const [self, member] = await Promise.all([
+            client.getGroupMemberInfo(group_id, client.uin, true),
+            client.getGroupMemberInfo(group_id, user_id, true),
+        ]);
+        if (user_id === client.uin || (self.role !== 'owner' && self.role !== 'admin')
+            || member.role !== 'member')
+            return { success: false, message: '当前权限或成员状态不允许踢出' };
+        context.signal.throwIfAborted();
+        if (!await client.setGroupKick(group_id, user_id))
+            return { success: false, message: '平台未确认踢出成功，请勿自动重试' };
         return { success: true, message: `已踢出 ${user_id} 成员` };
     },
 });

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

@@ -1,23 +1,26 @@
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-export default defineAgentTool<{ group_id: number; user_id: number }>({
+export default defineAgentTool<{ group_id: number; user_id: number; reason: string }>({
   description: '踢出 QQ 群中的某个成员',
   inputSchema: z.object({
     group_id: z.number().describe('目标群号'),
     user_id: z.number().describe('要踢出的成员 QQ号'),
+    reason: z.string().min(1).describe('本次踢人的具体原因，随目标群和成员一起供人工确认'),
   }),
   adapter: 'icqq',
   scopes:['group'],
   permissions: ['role(master,admin,trusted,owner)'],
-  requiresApproval: 'once',
+  requiresApproval: 'human',
   async execute({ group_id, user_id }, context) {
     const client = context.$client;
-    const selfInfo= client.pickMember(group_id,client.uin);
-    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: '机器人不是群主或管理员，无法踢出成员' };
-    if(selfInfo.user_id === user_id) return { success: false, message: '机器人不能踢出自己' };
-    const memberInfo= client.pickMember(group_id,user_id);
-    if(!memberInfo) return { success: false, message: '目标成员不存在' };
-    await client.setGroupKick(group_id, user_id);
+    const [self, member] = await Promise.all([
+      client.getGroupMemberInfo(group_id, client.uin, true),
+      client.getGroupMemberInfo(group_id, user_id, true),
+    ]);
+    if (user_id === client.uin || (self.role !== 'owner' && self.role !== 'admin')
+      || member.role !== 'member') return { success: false, message: '当前权限或成员状态不允许踢出' };
+    context.signal.throwIfAborted();
+    if (!await client.setGroupKick(group_id, user_id)) return { success: false, message: '平台未确认踢出成功，请勿自动重试' };
     return { success: true, message: `已踢出 ${user_id} 成员` };
   },
 });

package/agents/icqq/skills/icqq-group-directory/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: icqq-group-directory
+platforms:
+  - icqq
+scopes:
+  - group
+description: ICQQ 群成员信息查询。
+keywords:
+  - icqq
+  - 成员信息
+tools:
+  - group_member_info
+---
+# icqq-group-directory
+
+目标群和成员必须明确；只把工具返回的信息当作已验证事实。

package/agents/icqq/skills/icqq-group-interaction/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: icqq-group-interaction
+platforms:
+  - icqq
+scopes:
+  - group
+description: ICQQ 群成员戳一戳与群签到。
+keywords:
+  - icqq
+  - 戳一戳
+  - 签到
+tools:
+  - poke
+  - group_sign
+---
+# icqq-group-interaction
+
+确认当前群和目标成员后调用；点赞使用 icqq-interaction。遵守各 Tool 审批策略。

package/agents/icqq/skills/icqq-group-state/SKILL.md

@@ -4,14 +4,15 @@ platforms:
   - icqq
 description: ICQQ 群文件与禁言状态查询能力。
 keywords:
-  - "icqq"
-  - "群文件"
-  - "禁言列表"
+  - icqq
+  - 群文件
+  - 禁言列表
 tools:
-  - "group_files"
-  - "list_muted"
+  - group_files
+  - list_muted
+scopes:
+  - group
 ---
-
 # icqq-group-state
 
 用于读取群文件和禁言状态。确认群号后调用，不把列表之外的信息当作已验证事实。

package/agents/icqq/skills/icqq-interaction/SKILL.md

@@ -2,18 +2,13 @@
 name: icqq-interaction
 platforms:
   - icqq
-description: ICQQ 点赞、戳一戳和群签到互动能力。
+description: ICQQ 用户点赞。
 keywords:
-  - "icqq"
-  - "点赞"
-  - "戳一戳"
-  - "签到"
+  - icqq
+  - 点赞
 tools:
-  - "poke"
-  - "send_user_like"
-  - "group_sign"
+  - send_user_like
 ---
-
 # icqq-interaction
 
-用于低风险社交互动。确认目标用户或群后再调用，并遵守各 Tool 的审批策略。
+用于给用户点赞；先确认真实 QQ 号，遵守 Tool 审批策略。

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,
@@ -89,7 +92,8 @@ export class IcqqEndpoint extends Endpoint {
         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);
@@ -764,6 +768,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "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.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/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.8",
+    "@zhin.js/skill": "1.1.9",
+    "@zhin.js/tool": "1.1.9"
   },
   "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.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"
   },
   "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.8",
+    "zhin.js": "1.1.15"
   },
   "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',

package/src/endpoint.ts

@@ -61,6 +61,7 @@ import {
 } from './protocol.js';
 import type { SystemMessage as IcqqSystemMessage } from './types.js';
 import { ManagedIcqqClient, type IcqqBackgroundOperation } from './managed-client.js';
+import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
 
 export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
@@ -112,6 +113,10 @@ export class IcqqEndpoint extends Endpoint<Client> {
   readonly content: EndpointContentPort;
 
   readonly management: EndpointManagement = Object.freeze<EndpointManagement>({
+    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,
@@ -149,7 +154,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   readonly control: EndpointControl = Object.freeze({
     recall: async (message: MessageRef) => {
       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: MessageRef, emoji: string) => {
       const target = resolveIcqqGroupReactionTarget(message);
@@ -844,6 +849,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
       metadata: {
         nickname: normalized.nickname,
         senderRole: normalized.senderRole,
+        platformSentAt: normalized.timestampMs,
       },
     }, admittedBeforeRetire);
   }

package/src/group-moderation.ts

@@ -0,0 +1,52 @@
+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 async function inspectGroupMember(
+  client: Client, groupId: string, userId: string, signal: AbortSignal,
+): Promise<GroupModerationMember> {
+  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: Client, groupId: string, userId: string, action: GroupModerationAction,
+  signal: AbortSignal, isActive: () => boolean,
+): Promise<void> {
+  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: string): number {
+  const id = Number(value);
+  if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(id)) throw new Error('Invalid QQ identifier');
+  return id;
+}

package/src/icqq-inbound.ts

@@ -394,6 +394,20 @@ export function icqqElementsToSegments(
       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) break;