@zhin.js/adapter-icqq 1.1.16 → 1.1.18

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.18
+
+### Patch Changes
+
+- 6345a38: feat(adapters): add per-adapter Console pages
+
+  Every platform adapter now ships a `pages/index` Console page backed by a shared
+  `createAdapterConsolePage` component and `createAdapterConsoleRpc` server helper:
+
+  - See running endpoints, test connectivity, and manage
+    `plugins.<adapter>.endpoints` (add/remove writes `.env` references) from the
+    Console instead of chat commands.
+  - Surface LoginAssist pending tasks (QR / slider / SMS / device) so ICQQ login no
+    longer requires the terminal.
+  - QQ moves its QR binding flow (`qq endpoint add`) into Console actions with
+    public/private selection.
+  - Pages are permission-gated by `<adapter>:read`; writes need `<adapter>:write`.
+
+- ff3efe7: feat(adapters): notify masters when ICQQ or QQ goes offline and support ICQQ re-login
+
+  - Add an explicit `notify` target to ICQQ and QQ endpoint config: when the
+    transport goes offline or login fails, send a short notice through another
+    adapter instance's Endpoint via `OutboundHost`.
+  - ICQQ automatically retries login after `system.offline.kickoff` when
+    `autoReconnect` is enabled, and exposes pending QR/slider/device challenges.
+  - Add `icqq login status|qr|confirm|code|retry` recovery commands. They can be
+    invoked from the QQ conversation that received the notice; `qr` returns the
+    login QR code as an image when the notifying platform supports it.
+  - `notify.id` also counts as the master identity for the related endpoint
+    management commands, so recovery can happen from the notified conversation.
+  - Document the new config and commands in the ICQQ/QQ READMEs and generated
+    configuration reference.
+
+- c58c589: Group deferred tools by their canonical plugin or MCP server instead of installation paths. Omit already represented delivered text and ledger facts only from the current model projection, preserving full history and restoring facts when their covering reply leaves the active context. Allow tools to declare a synchronous, read-only availability predicate before turn disclosure, with execution-time checks remaining authoritative.
+
+  Preserve every confirmed platform message identity across Agent replies and ICQQ split sends. Give each bubble its own stable single-message alias while retaining the reply's ordered association; preserve confirmed prefixes on partial delivery without retrying or inventing unknown message IDs.
+
+- Updated dependencies [6345a38]
+- Updated dependencies [ff3efe7]
+- Updated dependencies [c58c589]
+  - @zhin.js/adapter@1.1.25
+  - @zhin.js/client@1.1.21
+  - @zhin.js/core@1.1.53
+  - @zhin.js/im-contract@1.1.9
+  - @zhin.js/tool@1.1.12
+
+## 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/README.md

@@ -173,6 +173,47 @@ ICQQ Agent 可按需加载 `icqq-conversation` 查询当前群／频道和 Bot
 
 `icqq-group-admin` 新增撤回他人消息与退群：前者保留群管发起权限、实时平台角色检查，无需逐次审批；退群仅主人可发起、每次审批，Bot 为群主时拒绝执行。引用／转发走统一发送链路，不支持跨会话转发。当前 guild-channel 接入仅提供身份查询，不能使用这些群／私聊操作。详见 [权限与能力说明](./PERMITS.md)。
 
+## Console 页面
+
+启动后打开 Console 的「ICQQ」页（地址 `/icqq`），可以：
+
+- 查看运行中的连接、点「测试连接」做连通性诊断；
+- 增删 `plugins.icqq.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；
+- 处理登录待办（扫码 / 滑块 / 设备确认等，来自 LoginAssist）；
+
+ICQQ 首次登录的二维码、滑块、设备确认会出现在「登录待办」里，不需要再回到终端确认。
+
+读取需要 `icqq:read`，写操作需要 `icqq:write`；管理员 full token 不受限。页面里的「添加 endpoint」等价于原来的 `icqq endpoint add`。
+
+## 掉线通知与重新登录
+
+配置 `notify` 后，ICQQ 被踢下线、登录失败或启动失败时，会通过另一个适配器实例给 master 发通知。例如用 QQ 官方机器人实例通知：
+
+```yaml
+qq:
+  # ... 已配置好的 QQ 官方机器人
+icqq:
+  master: 123456
+  autoReconnect: true   # 默认 true：被踢下线后自动重新登录
+  notify:
+    adapter: qq
+    endpoint: bot-1
+    kind: private
+    id: "${QQ_MASTER_OPENID}"   # master 在 QQ 官方机器人里的 openid
+```
+
+`autoReconnect: true` 时，被踢下线会自动重试登录；二维码/滑块/设备确认就绪后，通知会提示下一步。收到通知后可以直接在 QQ 里完成：
+
+| 命令 | 作用 |
+|------|------|
+| `icqq login qr` | 把 ICQQ 登录二维码发到当前会话（QQ 支持图片时） |
+| `icqq login confirm` | 扫码后确认继续登录 |
+| `icqq login code <内容>` | 提交滑块 ticket、短信验证码或设备确认内容 |
+| `icqq login status` | 查看在线状态与登录待办 |
+| `icqq login retry` | 强制重新触发登录 |
+
+命令只接受 master（顶层或 `endpoints[i].master`）或 `notify.id` 对应账号；两者都没配置时请用 Console 的 ICQQ 页面。没有配置 `notify` 时，掉线只写日志并在 Console 显示登录待办。
+
 ## 故障排查
 
 | 现象 | 排查 |
@@ -190,14 +231,14 @@ MIT
 
 发送成功回执只接受平台真实消息 ID。网络超时、断线、缺少消息 ID 的响应会报告 `deliveryUnknown`，框架不会自动重发；手动重发可能重复发送。
 
-ICQQ 原生分享和文件 API 可能已经成功，但只返回空值或文件 ID；这类结果不能当作可引用、可撤回的消息 ID。群聊和私聊的分享卡片发出后，适配器会读一次会话记录，找到机器人自己刚发出的卡片消息，用它的真实消息 ID 作为回执（记录有延迟时半秒后再读一次）。找不到时（以及临时会话、频道和文件）仍报告投递结果未知，不编造 ID。平台操作仍只执行一次。文件撤回应使用平台专用文件 API。
+ICQQ 原生分享和文件 API 可能已经成功，但只返回空值或文件 ID；这类结果不能当作可引用、可撤回的消息 ID。适配器不会根据时间和卡片类型从历史猜测本次分享的 ID；同一时刻的其他卡片也可能匹配。没有直接消息 ID 的部分保留为未知，平台操作仍只执行一次。文件撤回应使用平台专用文件 API。
 
 ### 独立元素按顺序拆分发送
 
 ICQQ 要求分享、文件、语音、视频、JSON 卡片和合并转发单独成条。一条消息里同时有文字和这些元素时（例如 Agent 回复“找到了：”加一张音乐分享卡片），适配器按原顺序拆成多条依次发送，引用只附在第一条普通消息上。
 
-- 回执的消息 ID 取第一条拿到 ID 的部分；所有部分都没有 ID（如单独一张分享）时，仍报告投递结果未知。
-- 第一条就失败时原样报告失败；后面的部分失败时报告 `partial_delivery`（结果未知），因为前面的部分已经送达，重发会重复。
+- 回执按发送顺序保留每部分的真实 ID 和原始段位置；没有 ID 的卡片或文件保留未知槽位，不把完整回复正文复制给每个 ID。所有部分都没有 ID（如单独一张分享）时，仍报告投递结果未知。
+- 第一条就失败时原样报告失败；后面的部分失败时报告 `partial_delivery`（结果未知），保留已完成部分的回执。前面的调用可能已被平台接收，重发可能重复。
 
 ## 语言
 

package/adapters/icqq/index.js

@@ -3,10 +3,12 @@ import { projectLocaleToken } from 'zhin.js/i18n';
 /**
  * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
-import { defineAdapter } from 'zhin.js/adapter';
+import { createAdapterOutageNotifier, defineAdapter } from 'zhin.js/adapter';
 import { loginAssistToken } from '@zhin.js/core/runtime';
+import { outboundHostToken } from 'zhin.js';
 import { IcqqEndpoint } from "../../lib/endpoint.js";
 import { icqqRuntimeStateToken } from "../../lib/icqq-runtime-state.js";
+import { icqqLoginControlToken } from "../../lib/icqq-login-control.js";
 import { resolveIcqqConfig, } from "../../lib/protocol.js";
 export { IcqqEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
@@ -44,11 +46,17 @@ export default defineAdapter({
             id: config.id,
             mode: 'direct',
         });
-        return new IcqqEndpoint({
+        const outbound = context.has?.(outboundHostToken) ? context.use(outboundHostToken) : undefined;
+        const endpoint = new IcqqEndpoint({
             id: context.id,
             loginAssist: context.use(loginAssistToken),
             locale: context.use(projectLocaleToken),
             config,
+            notifier: createAdapterOutageNotifier(outbound, config.notify),
         });
+        if (context.has?.(icqqLoginControlToken)) {
+            context.use(icqqLoginControlToken).set(config.id, endpoint.loginControl);
+        }
+        return endpoint;
     },
 });

package/adapters/icqq/index.ts

@@ -2,10 +2,12 @@ import { projectLocaleToken } from 'zhin.js/i18n';
 /**
  * Convention entry: discover `adapters/icqq/index.ts` → defineAdapter.
  */
-import { defineAdapter } from 'zhin.js/adapter';
+import { createAdapterOutageNotifier, defineAdapter } from 'zhin.js/adapter';
 import { loginAssistToken } from '@zhin.js/core/runtime';
+import { outboundHostToken } from 'zhin.js';
 import { IcqqEndpoint } from '../../src/endpoint.js';
 import { icqqRuntimeStateToken } from '../../src/icqq-runtime-state.js';
+import { icqqLoginControlToken } from '../../src/icqq-login-control.js';
 import {
   resolveIcqqConfig,
   type IcqqEndpointConfig,
@@ -55,11 +57,17 @@ export default defineAdapter<IcqqEndpointConfig>({
       id: config.id,
       mode: 'direct',
     });
-    return new IcqqEndpoint({
+    const outbound = context.has?.(outboundHostToken) ? context.use(outboundHostToken) : undefined;
+    const endpoint = new IcqqEndpoint({
       id: context.id,
       loginAssist: context.use(loginAssistToken),
       locale: context.use(projectLocaleToken),
       config,
+      notifier: createAdapterOutageNotifier(outbound, config.notify),
     });
+    if (context.has?.(icqqLoginControlToken)) {
+      context.use(icqqLoginControlToken).set(config.id, endpoint.loginControl);
+    }
+    return endpoint;
   },
 });

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') };