@zhin.js/adapter-icqq 1.1.16 → 1.1.17

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.17
+
+### Patch Changes
+
+- e23cabc: ADR 0041 slice B: the turn context now carries real scene facts. `EndpointManagement` gains `inspectGroupScene` (name, owner, admins, member count, global mute) and `inspectGroupMemberProfile` (role, card, title, mute expiry; one lookup), implemented by the ICQQ adapter from uncached group/member reads. The CLI resolves them per turn (bot role always fresh; group and sender facts reuse a 60 s, 256-entry in-memory cache scoped to the generation; failures omit fields) and the inbound actor now carries `groupNickname` / `groupTitle` / `mutedUntil` plus the platform role. The Session / Bot state blocks are replaced by one projected scene line `[scene_id:…;scene_type:…;scene_name:…;owner_id:…;admins:…;member_count:…;global_mute:…;assistant_role:…;]` (values escaped and clipped to 64 chars). No new on-disk state.
+- 4d728c0: ADR 0043 §4 + §5 (H4) and the ADR 0041 actor-only amendment. Participant headers are no longer stored: user messages keep only `actor`, assistant messages keep `assistantActor` (plus the delivered `messageId`), and the header is rendered at the LLM boundary; legacy rows that still carry `name` are read as before. Headers now use session message aliases `id:m<n>` (an ordinal over the stored active path, so already-sent prefixes never change), `time:HH:mm` shown only when a minute has passed since the last shown time (the first message and the first message of a day also carry `date`), and `reply_to:m<n>` when the message replies to one inside the visible window. A reply to a message outside the window gets one `[quote id:…;user_id:…;time:…;] <first 120 chars>` line (media as placeholders, a forward expanded one level) so the model no longer needs `inspect_conversation_reference` for ordinary quotes; the quote is resolved by the ingress through the reference port (3 s timeout) and stored as structured `UserMessage.quote`. Tool arguments named `message_id` / `message_ids` / `*_message_id` / `reference` and `reply` segments accept the alias as well as the platform id; `inspect_conversation_reference` also accepts the quoted message id.
+- 51f1328: 修复 icqq 群成员相关 Agent 工具：`group_member_info` 返回空对象（模型据此误判成员不在群里）、`group_invite` 永远判定"已在群里"、`set_mute` / `set_title` / `set_anonymous` 读旧缓存误判 Bot 不是管理员。统一改为实时查询群成员。
+- d0e1fac: Keep stable prompt instructions ahead of turn-specific capabilities, project unchanged context without placeholder text, and retain scoped state snapshots with readable updates and compaction recovery. Preserve native conversation/tool chronology and separate participant identity from runtime guidance.
+
+  Resolve the ICQQ bot account and current-group role before capability discovery, and support explicitly declared current-conversation bot-role requirements without changing existing requester permissions or approvals. Keep role lookup failures unknown and preserve execution-time platform checks.
+
+- 3771f7a: 修复同一群先后两人入群时后一次入群被当重复事件丢掉：side event 去重键（core 与 icqq）加入成员与操作人。
+- 4f96ad5: Fix member-join welcome display: icqq now sends the mention's display name as the `at` element text, the joining member's nickname from the notice is threaded into `target.name`, and icqq group messages populate `conversation.name` from `group_name` so `{group}` renders the group name instead of the group number.
+- Updated dependencies [f67883e]
+- Updated dependencies [e23cabc]
+- Updated dependencies [4d728c0]
+- Updated dependencies [eb8feeb]
+- Updated dependencies [24a2b71]
+- Updated dependencies [d0e1fac]
+- Updated dependencies [3771f7a]
+- Updated dependencies [4f96ad5]
+  - @zhin.js/core@1.1.52
+  - @zhin.js/adapter@1.1.24
+  - @zhin.js/tool@1.1.11
+  - @zhin.js/im-contract@1.1.8
+
 ## 1.1.16
 
 ### Patch Changes

package/agents/icqq/members.js

@@ -0,0 +1,16 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * 实时查询群成员（跳过缓存）；不在群里或查询失败返回 undefined。
+ * 不要用 `pickMember`：它总会返回实体对象（判空永远为真），`is_admin` 等也读旧缓存——Bot 刚被设为管理员时会误判。
+ */
+export async function freshMember(client, groupId, userId) {
+    try {
+        return await client.getGroupMemberInfo(groupId, userId, true);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isGroupManager(info) {
+    return info?.role === 'owner' || info?.role === 'admin';
+}

package/agents/icqq/members.ts

@@ -0,0 +1,17 @@
+import type { Client, MemberInfo } from '@icqqjs/icqq';
+
+/**
+ * 实时查询群成员（跳过缓存）；不在群里或查询失败返回 undefined。
+ * 不要用 `pickMember`：它总会返回实体对象（判空永远为真），`is_admin` 等也读旧缓存——Bot 刚被设为管理员时会误判。
+ */
+export async function freshMember(client: Client, groupId: number, userId: number): Promise<MemberInfo | undefined> {
+  try {
+    return await client.getGroupMemberInfo(groupId, userId, true);
+  } catch {
+    return undefined;
+  }
+}
+
+export function isGroupManager(info: MemberInfo | undefined): boolean {
+  return info?.role === 'owner' || info?.role === 'admin';
+}

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

@@ -5,7 +5,7 @@ import { z } from 'zod';
 export default defineAgentTool({
     description: '设置或移除 QQ 群精华消息',
     inputSchema: z.object({
-        message_id: z.string().describe('消息 ID'),
+        message_id: z.string().describe('消息 ID，或消息头里的 m<n> 别名'),
         action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
     }),
     adapter: 'icqq',

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

@@ -4,7 +4,7 @@ import { z } from 'zod';
 export default defineAgentTool<{ message_id: string; action: 'add' | 'remove' }>({
   description: '设置或移除 QQ 群精华消息',
   inputSchema: z.object({
-    message_id: z.string().describe('消息 ID'),
+    message_id: z.string().describe('消息 ID，或消息头里的 m<n> 别名'),
     action: z.enum(['add', 'remove']).describe('add=设为精华, remove=移除精华'),
   }),
   adapter: 'icqq',

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

@@ -1,5 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { freshMember } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
@@ -16,8 +17,7 @@ export default defineAgentTool({
         const groupInfo = client.pickGroup(group_id);
         if (!groupInfo)
             return { success: false, message: t(context.locale, 'groupMissing') };
-        const memberInfo = client.pickMember(group_id, user_id);
-        if (memberInfo)
+        if (await freshMember(client, group_id, user_id))
             return { success: false, message: t(context.locale, 'memberExists') };
         await client.inviteFriend(group_id, user_id);
         return { success: true, message: t(context.locale, 'inviteAttempted', { p0: user_id, p1: group_id }) };

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

@@ -1,4 +1,5 @@
 import { messages as t } from "../../../../messages.js";
+import { freshMember } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool<{ group_id: number; user_id: number }>({
@@ -14,8 +15,7 @@ export default defineAgentTool<{ group_id: number; user_id: number }>({
     const client = context.$client;
     const groupInfo= client.pickGroup(group_id);
     if(!groupInfo) return { success: false, message: t(context.locale, 'groupMissing') };
-    const memberInfo= client.pickMember(group_id,user_id);
-    if(memberInfo) return { success: false, message: t(context.locale, 'memberExists') };
+    if (await freshMember(client, group_id, user_id)) return { success: false, message: t(context.locale, 'memberExists') };
     await client.inviteFriend(group_id, user_id);
     return { success: true, message: t(context.locale, 'inviteAttempted', { p0: user_id, p1: group_id }) };
   },

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

@@ -7,6 +7,7 @@ export default defineAgentTool({
     description: '让机器人退出当前 QQ 群；仅主人可发起且每次人工审批，机器人是群主时拒绝执行以免解散群',
     adapter: 'icqq',
     scopes: ['group'],
+    currentConversationBotRoles: ['admin', 'member'],
     permissions: ['role(master)'],
     requiresApproval: 'human',
     risk: 'dangerous',

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

@@ -7,6 +7,7 @@ export default defineAgentTool({
   description: '让机器人退出当前 QQ 群；仅主人可发起且每次人工审批，机器人是群主时拒绝执行以免解散群',
   adapter: 'icqq',
   scopes: ['group'],
+  currentConversationBotRoles: ['admin', 'member'],
   permissions: ['role(master)'],
   requiresApproval: 'human',
   risk: 'dangerous',

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

@@ -7,10 +7,11 @@ export default defineAgentTool({
     description: '撤回当前 QQ 群内他人的真实消息；需调用方具备群管发起权限及机器人具备实时平台权限，无需逐次审批',
     adapter: 'icqq',
     scopes: ['group'],
+    currentConversationBotRoles: ['owner', 'admin'],
     permissions: ['role(master,admin,trusted,owner)'],
     requiresApproval: 'never',
     inputSchema: z.object({
-        message_id: z.string().min(1).describe('当前群中要撤回的真实消息 ID'),
+        message_id: z.string().min(1).describe('当前群中要撤回的真实消息 ID，或消息头里的 m<n> 别名'),
         reason: z.string().min(1).describe('撤回的具体原因，自动处理必须依据已确认的群规'),
     }),
     async execute({ message_id }, context) {

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

@@ -7,10 +7,11 @@ export default defineAgentTool({
   description: '撤回当前 QQ 群内他人的真实消息；需调用方具备群管发起权限及机器人具备实时平台权限，无需逐次审批',
   adapter: 'icqq',
   scopes: ['group'],
+  currentConversationBotRoles: ['owner', 'admin'],
   permissions: ['role(master,admin,trusted,owner)'],
   requiresApproval: 'never',
   inputSchema: z.object({
-    message_id: z.string().min(1).describe('当前群中要撤回的真实消息 ID'),
+    message_id: z.string().min(1).describe('当前群中要撤回的真实消息 ID，或消息头里的 m<n> 别名'),
     reason: z.string().min(1).describe('撤回的具体原因，自动处理必须依据已确认的群规'),
   }),
   async execute({ message_id }, context) {

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

@@ -1,5 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { freshMember, isGroupManager } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
@@ -15,8 +16,7 @@ export default defineAgentTool({
     async execute({ group_id, enable }, context) {
         const client = context.$client;
         const on = enable ?? true;
-        const selfInfo = client.pickMember(group_id, client.uin);
-        if (!selfInfo.is_admin && !selfInfo.is_owner)
+        if (!isGroupManager(await freshMember(client, group_id, client.uin)))
             return { success: false, message: t(context.locale, 'anonymousForbidden') };
         await client.setGroupAnonymous(group_id, on);
         return { success: true, message: on ? t(context.locale, 'anonymousEnabled') : t(context.locale, 'anonymousDisabled') };

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

@@ -1,4 +1,5 @@
 import { messages as t } from "../../../../messages.js";
+import { freshMember, isGroupManager } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool<{ group_id: number; enable?: boolean }>({
@@ -14,8 +15,7 @@ export default defineAgentTool<{ group_id: number; enable?: boolean }>({
   async execute({ group_id, enable }, context) {
     const client = context.$client;
     const on = enable ?? true;
-    const selfInfo= client.pickMember(group_id,client.uin);
-    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: t(context.locale, 'anonymousForbidden') };
+    if (!isGroupManager(await freshMember(client, group_id, client.uin))) return { success: false, message: t(context.locale, 'anonymousForbidden') };
     await client.setGroupAnonymous(group_id, on);
     return { success: true, message: on ? t(context.locale, 'anonymousEnabled') : t(context.locale, 'anonymousDisabled') };
   },

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

@@ -1,5 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { freshMember, isGroupManager } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
@@ -14,11 +15,10 @@ export default defineAgentTool({
     requiresApproval: 'always',
     async execute({ group_id, user_id, duration }, context) {
         const client = context.$client;
-        const selfInfo = client.pickMember(group_id, client.uin);
-        if (!selfInfo.is_admin && !selfInfo.is_owner)
+        const [self, member] = await Promise.all([freshMember(client, group_id, client.uin), freshMember(client, group_id, user_id)]);
+        if (!isGroupManager(self))
             return { success: false, message: t(context.locale, 'muteForbidden') };
-        const memberInfo = client.pickMember(group_id, user_id);
-        if (!memberInfo)
+        if (!member)
             return { success: false, message: t(context.locale, 'memberMissing') };
         await client.setGroupBan(group_id, user_id, duration === 0 ? 0 : duration);
         return { success: true, message: duration === 0 ? t(context.locale, 'unmuted', { user: user_id }) : t(context.locale, 'muted', { user: user_id, seconds: duration ?? 0 }) };

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

@@ -1,4 +1,5 @@
 import { messages as t } from "../../../../messages.js";
+import { freshMember, isGroupManager } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool<{ group_id: number; user_id: number; duration?: number }>({
@@ -13,10 +14,9 @@ export default defineAgentTool<{ group_id: number; user_id: number; duration?: n
   requiresApproval: 'always',
   async execute({ group_id, user_id, duration }, context) {
     const client = context.$client;
-    const selfInfo= client.pickMember(group_id,client.uin);
-    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: t(context.locale, 'muteForbidden') };
-    const memberInfo= client.pickMember(group_id,user_id);
-    if(!memberInfo) return { success: false, message: t(context.locale, 'memberMissing') };
+    const [self, member] = await Promise.all([freshMember(client, group_id, client.uin), freshMember(client, group_id, user_id)]);
+    if (!isGroupManager(self)) return { success: false, message: t(context.locale, 'muteForbidden') };
+    if (!member) return { success: false, message: t(context.locale, 'memberMissing') };
     await client.setGroupBan(group_id, user_id, duration === 0 ? 0 : duration);
     return { success: true, message: duration === 0 ? t(context.locale, 'unmuted', { user: user_id }) : t(context.locale, 'muted', { user: user_id, seconds: duration ?? 0 }) };
   },

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

@@ -1,5 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { freshMember, isGroupManager } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
@@ -15,11 +16,10 @@ export default defineAgentTool({
     requiresApproval: 'always',
     async execute({ group_id, user_id, title, duration }, context) {
         const client = context.$client;
-        const selfInfo = client.pickMember(group_id, client.uin);
-        if (!selfInfo.is_admin && !selfInfo.is_owner)
+        const [self, member] = await Promise.all([freshMember(client, group_id, client.uin), freshMember(client, group_id, user_id)]);
+        if (!isGroupManager(self))
             return { success: false, message: t(context.locale, 'titleForbidden') };
-        const memberInfo = client.pickMember(group_id, user_id);
-        if (!memberInfo)
+        if (!member)
             return { success: false, message: t(context.locale, 'memberMissing') };
         await client.setGroupSpecialTitle(group_id, user_id, title, duration ?? -1);
         return { success: true, message: t(context.locale, 'titleChanged', { p0: user_id, p1: title }) };

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

@@ -1,4 +1,5 @@
 import { messages as t } from "../../../../messages.js";
+import { freshMember, isGroupManager } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool<{ group_id: number; user_id: number; title: string; duration?: number }>({
@@ -14,10 +15,9 @@ export default defineAgentTool<{ group_id: number; user_id: number; title: strin
   requiresApproval: 'always',
   async execute({ group_id, user_id, title, duration }, context) {
     const client = context.$client;
-    const selfInfo= client.pickMember(group_id,client.uin);
-    if(!selfInfo.is_admin && !selfInfo.is_owner) return { success: false, message: t(context.locale, 'titleForbidden') };
-    const memberInfo= client.pickMember(group_id,user_id);
-    if(!memberInfo) return { success: false, message: t(context.locale, 'memberMissing') };
+    const [self, member] = await Promise.all([freshMember(client, group_id, client.uin), freshMember(client, group_id, user_id)]);
+    if (!isGroupManager(self)) return { success: false, message: t(context.locale, 'titleForbidden') };
+    if (!member) return { success: false, message: t(context.locale, 'memberMissing') };
     await client.setGroupSpecialTitle(group_id, user_id, title, duration ?? -1);
     return { success: true, message: t(context.locale, 'titleChanged', { p0: user_id, p1: title }) };
   },

package/agents/icqq/skills/icqq-group-directory/tools/group_member_info/index.js

@@ -1,5 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { freshMember } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
@@ -13,15 +14,24 @@ export default defineAgentTool({
     permissions: ['role(master,admin,trusted,owner)'],
     requiresApproval: 'never',
     async execute({ group_id, user_id }, context) {
-        const group = context.$client.pickGroup(group_id);
-        if (!group)
-            return { success: false, message: t(context.locale, 'groupMissing') };
-        const memberInfo = group.pickMember(user_id);
-        if (!memberInfo)
+        // pickMember 返回的是实体对象，序列化后只剩 `{}`：模型会据此以为成员不在群里。按 group_kick 的口径实时查询。
+        const info = await freshMember(context.$client, group_id, user_id);
+        if (!info)
             return { success: false, message: t(context.locale, 'memberMissing') };
         return {
             success: true,
-            member: memberInfo,
+            member: {
+                group_id: info.group_id,
+                user_id: info.user_id,
+                nickname: info.nickname,
+                card: info.card,
+                role: info.role,
+                title: info.title,
+                level: info.level,
+                join_time: info.join_time,
+                last_sent_time: info.last_sent_time,
+                shutup_time: info.shutup_time,
+            },
         };
     },
 });

package/agents/icqq/skills/icqq-group-directory/tools/group_member_info/index.ts

@@ -1,4 +1,5 @@
 import { messages as t } from "../../../../messages.js";
+import { freshMember } from "../../../../members.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 interface GroupMemberInfoInput {
@@ -17,13 +18,23 @@ export default defineAgentTool<GroupMemberInfoInput>({
   permissions: ['role(master,admin,trusted,owner)'],
   requiresApproval: 'never',
   async execute({ group_id, user_id }, context) {
-    const group = context.$client.pickGroup(group_id);
-    if (!group) return { success: false, message: t(context.locale, 'groupMissing') };
-    const memberInfo = group.pickMember(user_id);
-    if (!memberInfo) return { success: false, message: t(context.locale, 'memberMissing') };
+    // pickMember 返回的是实体对象，序列化后只剩 `{}`：模型会据此以为成员不在群里。按 group_kick 的口径实时查询。
+    const info = await freshMember(context.$client, group_id, user_id);
+    if (!info) return { success: false, message: t(context.locale, 'memberMissing') };
     return {
       success: true,
-      member: memberInfo,
+      member: {
+        group_id: info.group_id,
+        user_id: info.user_id,
+        nickname: info.nickname,
+        card: info.card,
+        role: info.role,
+        title: info.title,
+        level: info.level,
+        join_time: info.join_time,
+        last_sent_time: info.last_sent_time,
+        shutup_time: info.shutup_time,
+      },
     };
   },
 });

package/agents/icqq/skills/icqq-messages/tools/forward_messages/index.js

@@ -8,7 +8,7 @@ export default defineAgentTool({
     adapter: 'icqq',
     scopes: ['private', 'group'],
     requiresApproval: 'never',
-    inputSchema: z.object({ message_ids: z.array(z.string().min(1)).min(1).describe('当前会话的真实消息 ID，按转发顺序排列') }),
+    inputSchema: z.object({ message_ids: z.array(z.string().min(1)).min(1).describe('当前会话的真实消息 ID（或消息头里的 m<n> 别名），按转发顺序排列') }),
     async execute({ message_ids }, context) {
         const conversation = currentConversation(context);
         if (conversation.kind === 'channel')

package/agents/icqq/skills/icqq-messages/tools/forward_messages/index.ts

@@ -8,7 +8,7 @@ export default defineAgentTool({
   adapter: 'icqq',
   scopes: ['private', 'group'],
   requiresApproval: 'never',
-  inputSchema: z.object({ message_ids: z.array(z.string().min(1)).min(1).describe('当前会话的真实消息 ID，按转发顺序排列') }),
+  inputSchema: z.object({ message_ids: z.array(z.string().min(1)).min(1).describe('当前会话的真实消息 ID（或消息头里的 m<n> 别名），按转发顺序排列') }),
   async execute({ message_ids }, context) {
     const conversation = currentConversation(context);
     if (conversation.kind === 'channel') throw new Error(t(context.locale, 'channelOperationUnsupported'));

package/agents/icqq/skills/icqq-messages/tools/quote_reply/index.js

@@ -8,7 +8,7 @@ export default defineAgentTool({
     scopes: ['private', 'group'],
     requiresApproval: 'never',
     inputSchema: z.object({
-        message_id: z.string().min(1).describe('当前会话中真实的原消息 ID'),
+        message_id: z.string().min(1).describe('当前会话中真实的原消息 ID，或消息头里的 m<n> 别名'),
         text: z.string().min(1).describe('本次回复的文字'),
     }),
     async execute({ message_id, text }, context) {

package/agents/icqq/skills/icqq-messages/tools/quote_reply/index.ts

@@ -8,7 +8,7 @@ export default defineAgentTool({
   scopes: ['private', 'group'],
   requiresApproval: 'never',
   inputSchema: z.object({
-    message_id: z.string().min(1).describe('当前会话中真实的原消息 ID'),
+    message_id: z.string().min(1).describe('当前会话中真实的原消息 ID，或消息头里的 m<n> 别名'),
     text: z.string().min(1).describe('本次回复的文字'),
   }),
   async execute({ message_id, text }, context) {

package/agents/icqq/skills/icqq-messages/tools/recall_own_message/index.js

@@ -8,7 +8,7 @@ export default defineAgentTool({
     adapter: 'icqq',
     scopes: ['private', 'group'],
     requiresApproval: 'never',
-    inputSchema: z.object({ message_id: z.string().min(1).describe('机器人在当前会话中发送的真实消息 ID') }),
+    inputSchema: z.object({ message_id: z.string().min(1).describe('机器人在当前会话中发送的真实消息 ID，或消息头里的 m<n> 别名') }),
     async execute({ message_id }, context) {
         const message = await resolveMessage(context, message_id);
         if (message.sender.user_id !== context.$client.uin)

package/agents/icqq/skills/icqq-messages/tools/recall_own_message/index.ts

@@ -8,7 +8,7 @@ export default defineAgentTool({
   adapter: 'icqq',
   scopes: ['private', 'group'],
   requiresApproval: 'never',
-  inputSchema: z.object({ message_id: z.string().min(1).describe('机器人在当前会话中发送的真实消息 ID') }),
+  inputSchema: z.object({ message_id: z.string().min(1).describe('机器人在当前会话中发送的真实消息 ID，或消息头里的 m<n> 别名') }),
   async execute({ message_id }, context) {
     const message = await resolveMessage(context, message_id);
     if (message.sender.user_id !== context.$client.uin) return { success: false, message: t(context.locale, 'ownMessageRequired') };

package/agents/icqq/system.md

@@ -1,7 +1,7 @@
 # ICQQ Platform Agent
 
-You are the icqq platform specialist. Interpret requests in the current icqq conversation and load only the narrowest private Skill needed for the task.
+You are the icqq platform specialist. Interpret requests in the current icqq conversation and load only the narrowest available Skill needed for the task.
 
-For your own group/guild role, current scene information or platform permissions, load `icqq-conversation` and query `conversation_info`. Sender roles describe the requester, not you. Do not infer your role from old session summaries or another endpoint account.
+Use the current Bot snapshot for your platform role. Load `icqq-conversation` and query `conversation_info` when the role is unknown or you need more scene or permission details. Sender roles describe the requester, not you. Do not infer your role from old session summaries or another endpoint account.
 
-For quoting, forwarding or recalling your own speech, load `icqq-messages`. Your own-message recall needs no group management role or per-call approval. For recalling another member's message or leaving a group, load `icqq-group-admin` and follow the tool-specific rules; only leaving requires fresh approval. All these message tools are restricted to the current conversation. Guild-channel limitations are explicit in `conversation_info`.
+Discover message and management operations from the current scene's Skill catalog; follow each tool's target, platform and approval rules. Recalling your own messages needs no group management role or per-call approval. Leaving a group requires fresh approval and is forbidden when you own the group. Do not load a Skill that is absent from the current catalog.

package/lib/endpoint.js

@@ -8,12 +8,13 @@ import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logge
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
 import { IcqqContentResolver } from './content-resolver.js';
 import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, messageLookupFromIcqqSource, resolveIcqqQuoteIdFromEvent, resolveIcqqInboundMedia, resolveIcqqSelfUserId, shouldSkipSelfInboundMessage, } from './icqq-inbound.js';
-import { isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
+import { icqqNoticeDedupeKey, isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
 import { IcqqGuildCatalog, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 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';
+import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
 const BOUND_EVENTS = [
     'message.private',
     'message.group',
@@ -57,6 +58,8 @@ export class IcqqEndpoint extends Endpoint {
     content;
     management = Object.freeze({
         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),
         listFriends: async () => Array.from(this.client.fl.values()).map((f) => ({
             user_id: f.user_id,
@@ -743,6 +746,7 @@ export class IcqqEndpoint extends Endpoint {
             channelType: normalized.channelType,
             channelId: normalized.channelId,
             channelParentGroupId: normalized.channelParentGroupId,
+            name: normalized.groupName,
         });
         const quoteId = resolveIcqqQuoteIdFromEvent(data);
         const quoted = messageLookupFromIcqqSource(findIcqqNestedMessageSource(data));
@@ -857,13 +861,7 @@ export class IcqqEndpoint extends Endpoint {
     #onNoticeEvent(payload) {
         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}`))
+        if (!this.#sideEventDeduper.shouldProcess(icqqNoticeDedupeKey(payload)))
             return;
         this.#dispatchIcqqSideEvent(payload);
     }

package/lib/group-moderation.js

@@ -3,17 +3,22 @@ export async function inspectGroupMember(client, groupId, userId, signal) {
     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/lib/group-scene.d.ts

@@ -0,0 +1,11 @@
+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 declare const ADMIN_SCAN_MAX_MEMBERS = 1000;
+/**
+ * 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 declare function inspectGroupScene(client: Client, groupId: string, signal: AbortSignal): Promise<GroupSceneFacts>;
+/** ADR 0041 member facts from one uncached lookup (same rationale as the agent `freshMember` helper). */
+export declare function inspectGroupMemberProfile(client: Client, groupId: string, userId: string, signal: AbortSignal): Promise<GroupMemberProfile>;

package/lib/group-scene.js

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

package/lib/icqq-inbound.d.ts

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

package/lib/icqq-inbound.js

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

package/lib/icqq-inbox.d.ts

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

package/lib/icqq-inbox.js

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

package/lib/protocol.d.ts

@@ -246,6 +246,8 @@ export declare function icqqInboundConversation(endpointKey: string, input: {
     readonly channelId: string;
     readonly channelParentGroupId?: string;
     readonly guildId?: string;
+    /** 群名（仅 group 会话使用） */
+    readonly name?: string;
 }): ConversationRef;
 /**
  * 出站：从 ConversationRef 派生 action 路由。

package/lib/protocol.js

@@ -232,7 +232,8 @@ export function icqqInboundConversation(endpointKey, input) {
             parent: { kind: 'channel', id: input.guildId },
         };
     }
-    return { endpoint, kind: input.channelType, id: input.channelId };
+    const name = input.channelType === 'group' ? input.name?.trim() : undefined;
+    return { endpoint, kind: input.channelType, id: input.channelId, ...(name ? { name } : {}) };
 }
 /**
  * 出站：从 ConversationRef 派生 action 路由。
@@ -362,7 +363,8 @@ function formatOutboundElements(payload) {
                 if (!Number.isSafeInteger(qq) || qq <= 0) {
                     throw new TypeError(`Invalid ICQQ mention target: ${String(target ?? '')}`);
                 }
-                return { type: 'at', qq };
+                const name = typeof item.data?.name === 'string' ? item.data.name.trim() : '';
+                return name ? { type: 'at', qq, text: name.startsWith('@') ? name : `@${name}` } : { type: 'at', qq };
             }
             case 'image': {
                 const arg = resolveIcqqMediaFile(normalizeIcqqImageData(item.data));

package/package.json

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

package/src/endpoint.ts

@@ -39,6 +39,7 @@ import {
   type IcqqMessageEvent,
 } from './icqq-inbound.js';
 import {
+  icqqNoticeDedupeKey,
   isIcqqNoticePayload,
   isIcqqRequestPayload,
 } from './icqq-inbox.js';
@@ -62,6 +63,7 @@ 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;
@@ -115,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,
     ),
@@ -823,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));
@@ -942,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/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；两者皆无则无法审批，丢弃。

package/src/protocol.ts

@@ -342,6 +342,8 @@ export function icqqInboundConversation(endpointKey: string, input: {
   readonly channelId: string;
   readonly channelParentGroupId?: string;
   readonly guildId?: string;
+  /** 群名（仅 group 会话使用） */
+  readonly name?: string;
 }): ConversationRef {
   const endpoint = { id: endpointKey, adapter: ICQQ_ADAPTER_NAME };
   if (input.channelType === 'private' && input.channelParentGroupId) {
@@ -360,7 +362,8 @@ export function icqqInboundConversation(endpointKey: string, input: {
       parent: { kind: 'channel', id: input.guildId },
     };
   }
-  return { endpoint, kind: input.channelType, id: input.channelId };
+  const name = input.channelType === 'group' ? input.name?.trim() : undefined;
+  return { endpoint, kind: input.channelType, id: input.channelId, ...(name ? { name } : {}) };
 }
 
 /**
@@ -487,7 +490,8 @@ function formatOutboundElements(payload: readonly unknown[]): (string | MessageE
         if (!Number.isSafeInteger(qq) || qq <= 0) {
           throw new TypeError(`Invalid ICQQ mention target: ${String(target ?? '')}`);
         }
-        return { type: 'at', qq };
+        const name = typeof item.data?.name === 'string' ? item.data.name.trim() : '';
+        return name ? { type: 'at', qq, text: name.startsWith('@') ? name : `@${name}` } : { type: 'at', qq };
       }
       case 'image': {
         const arg = resolveIcqqMediaFile(normalizeIcqqImageData(item.data));