@zhin.js/adapter-icqq 6.0.3 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @zhin.js/adapter-icqq
 
+## 7.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- e5c84ed: Adapter 多账号：插件实例 config 支持 `endpoints: [{name, ...覆盖}]` 数组，`expandEndpointConfigs` 将一个实例展开为多个 endpoint record（id 为 `<slotId>~<name>`，顶层字段共享、逐项覆盖），替代多 `instanceKey` 方案；Console `/api/plugins` 收敛为一个插件卡片 + 多 endpoint。icqq / qq schema 与 README 补 `endpoints` 配置。
+
+  Plugin Runtime Console Host：补 `/esm/*` React/router ESM 代理路由（legacy `consoleApiRouter` 对齐），TypeScriptClientBuilder 裸导入改写为 `/esm/<enc>.mjs`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- f32c424: 适配器配置统一为 endpoints 数组格式：`plugins.<adapter>` 为该 adapter 所有 endpoint 的通用配置，`plugins.<adapter>.endpoints[i]` 为单个 endpoint 的特殊配置（逐项覆盖，`name` 必填）。slack / github schema 新增 `endpoints` 属性；icqq / qq / slack 顶层必填改为 `anyOf`（单 endpoint 字段或 `endpoints` 数组二选一，兼容 Ajv strictRequired）。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - zhin.js@5.0.0
+
 ## 6.0.3
 
 ### Patch Changes

package/README.md

@@ -8,6 +8,7 @@ ICQQ Plugin Runtime 适配器 — 通过 [@icqqjs/cli](https://github.com/icqqjs
 - 入站：`messageGatewayToken`（IPC 事件订阅）
 - 出站：`send({ target, payload })` → `send_group_msg` / `send_private_msg` / …
 - Agent 工具：`agent/tools/`（戳一戳、群管、好友列表等）保留
+- Console Endpoint 管理：`src/endpoint.ts` 显式实现 `EndpointManagement`（好友/群/群成员列表、请求审批、删好友、踢人、禁言、设管理），Console 使用 `endpoint.friends` / `endpoint.groups` / `endpoint.group_members` 等规范 RPC
 
 ## 安装
 
@@ -21,12 +22,28 @@ pnpm add -g @icqqjs/cli   # 或 npx icqq login
 ```yaml
 plugins:
   icqq:
-    name: "${ICQQ_ACCOUNT}"   # QQ 号，须与 icqq login 一致
+    master: "1659488338"        # 必填，顶层共享（/approve 与 master 角色）
     autoReconnect: true
-    # rpc:                    # 可选远程守护进程
-    #   host: 10.0.0.2
-    #   port: 9527
-    #   token: ${ICQQ_RPC_TOKEN}
+    endpoints:
+      - name: "${ICQQ_ACCOUNT}"   # QQ 号，须与 icqq login 一致
+      # rpc 为 endpoint 级字段：
+      # - name: "${ICQQ_ACCOUNT_2}"
+      #   rpc:
+      #     host: 10.0.0.2
+      #     port: 9527
+      #     token: ${ICQQ_RPC_TOKEN}
+```
+
+多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
+
+```yaml
+plugins:
+  icqq:
+    master: "1659488338"      # 顶层字段所有 endpoint 共享
+    endpoints:
+      - name: "${ICQQ_ACCOUNT}"
+      - name: "${ICQQ_ACCOUNT_2}"
+      - name: "${ICQQ_ACCOUNT_3}"   # 各账号须分别 icqq login
 ```
 
 先执行 `icqq login`，再启动 Zhin。
@@ -52,6 +69,7 @@ plugins:
 
 - `autoReconnect` 已恢复实现：IPC/RPC 意外断开后按指数退避自动重连（`stop()` 为主动断开，不触发重连）。
 - `outboundMedia: file | base64` 已恢复实现：`file` 模式把 segment base64 落盘为临时文件后发 `[image:path]`；`base64` 模式（配置 `rpc` 时默认）发 `[image:base64://...]` 由守护进程解码。
+- **Console 社交/群管 RPC 已接线**：endpoint 在 Adapter 内把 ICQQ 的 `get_friend_list` / `get_group_list` / `get_group_member_list`、请求审批和群管操作归一化为冻结的 `EndpointManagement` 对象。Host 只消费该语义端口，不再探测方法别名或读取 `friends` / `groups` SDK 缓存。
 - **notice / request 入站事件已移除**：Plugin Runtime 的 `MessageGateway` 仅有 message 通道，没有 `notice.receive` / `request.receive` 事件机制，旧 `icqq-side-events.ts` / `get-msg.ts` / `login-ipc-contract.ts` / `agent-prompt.ts` 随之删除。需要好友/入群请求处理能力时请等待 runtime 提供事件通道后再恢复。
 
 ## License

package/adapters/icqq.ts

@@ -1,9 +1,17 @@
 /**
  * Convention entry: discover `adapters/icqq.ts` → defineAdapter.
  */
-import { defineAdapter } from '@zhin.js/adapter';
+import { defineAdapter, type AdapterContext } from '@zhin.js/adapter';
 import { messageGatewayToken } from '@zhin.js/core/runtime';
-import { IcqqIpcEndpoint } from '../src/endpoint.js';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import {
+  databaseHostToken,
+  INBOX_TABLE_NOTICE,
+  INBOX_TABLE_REQUEST,
+  runtimeEventPublisherToken,
+  type Token,
+} from '@zhin.js/plugin-runtime';
+import { IcqqIpcEndpoint, type IcqqInboxHooks } from '../src/endpoint.js';
 import {
   resolveIcqqConfig,
   type IcqqAdapterConfig,
@@ -16,15 +24,69 @@ export type {
   IcqqIpcTransport,
 } from '../src/endpoint.js';
 
+const logger = getLogger('icqq');
+
 export default defineAdapter<IcqqAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
   create(context) {
     // Client-library / IPC daemon path — no httpHostToken.
     // Console loginAssist + host-router routes deferred.
+    const inbox = resolveInboxHooks(context);
     return new IcqqIpcEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),
       config: resolveIcqqConfig(context.config),
+      ...(inbox ? { inbox } : {}),
     });
   },
 });
+
+/** 资源可选（轻量 Root 无 DatabaseHost / console hub）：缺失时降级为不写收件箱。 */
+function tryUse<T>(context: AdapterContext<IcqqAdapterConfig>, token: Token<T>): T | undefined {
+  try {
+    return context.use(token);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 收件箱钩子：写 unified_inbox_request/notice（按 platform_*_id 去重，
+ * 推送事件与 GET_SYSTEM_MSG 首拉可能重复同一请求），并经 console hub 广播。
+ */
+function resolveInboxHooks(context: AdapterContext<IcqqAdapterConfig>): IcqqInboxHooks | undefined {
+  const host = tryUse(context, databaseHostToken);
+  const publisher = tryUse(context, runtimeEventPublisherToken);
+  if (!host && !publisher) return undefined;
+  const insertDeduped = async (
+    table: string,
+    idField: 'platform_request_id' | 'platform_notice_id',
+    row: Record<string, unknown>,
+  ): Promise<void> => {
+    const model = host?.models.get(table);
+    if (!model) return;
+    try {
+      const existing = await model.select().where({
+        adapter: row.adapter,
+        endpoint_id: row.endpoint_id,
+        [idField]: row[idField],
+      });
+      if (Array.isArray(existing) && existing.length > 0) return;
+      await model.insert(row);
+    } catch (error) {
+      logger.warn(formatCompact({
+        op: 'inbox_insert',
+        table,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    }
+  };
+  const publish = publisher;
+  return {
+    recordRequest: (row) => insertDeduped(INBOX_TABLE_REQUEST, 'platform_request_id', row),
+    recordNotice: (row) => insertDeduped(INBOX_TABLE_NOTICE, 'platform_notice_id', row),
+    ...(publish
+      ? { publish: (type: string, data: unknown): void => publish.publish(type, data) }
+      : {}),
+  };
+}

package/lib/endpoint.d.ts

@@ -1,11 +1,11 @@
 /**
  * IcqqIpcEndpoint — lifecycle, outbound, IPC subscribe/admit for ICQQ daemon.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type IcqqInboundMessage, type IpcEvent, type IpcResponse, type ResolvedIcqqConfig } from './protocol.js';
-import type { IpcFriendInfo, IpcGroupInfo } from './types.js';
+import type { IpcFriendInfo, IpcGroupInfo, IpcMemberInfo } from './types.js';
 /** Minimal IPC surface used by the endpoint (real IpcClient or test mock). */
 export interface IcqqIpcTransport {
     request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
@@ -16,11 +16,22 @@ export interface IcqqIpcTransport {
     close(): void;
 }
 export type CreateIcqqIpc = (config: ResolvedIcqqConfig) => Promise<IcqqIpcTransport>;
+/**
+ * 收件箱写/推钩子（由装配层注入，见 adapters/icqq.ts）。
+ * record* 写 unified_inbox_request/notice；publish 向 console hub 推送实时事件。
+ */
+export interface IcqqInboxHooks {
+    recordRequest(row: Record<string, unknown>): void | Promise<void>;
+    recordNotice(row: Record<string, unknown>): void | Promise<void>;
+    publish?(type: string, data: unknown): void;
+}
 export interface IcqqEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
     readonly config: ResolvedIcqqConfig;
     readonly createIpc?: CreateIcqqIpc;
+    /** 未注入时 request/notice 事件仅按非消息载荷忽略（不报错）。 */
+    readonly inbox?: IcqqInboxHooks;
 }
 export declare class IcqqIpcEndpoint implements EndpointInstance {
     #private;
@@ -29,6 +40,7 @@ export declare class IcqqIpcEndpoint implements EndpointInstance {
     ipc: IcqqIpcTransport;
     readonly friends: Map<number, IpcFriendInfo>;
     readonly groups: Map<number, IpcGroupInfo>;
+    readonly management: EndpointManagement;
     constructor(options: IcqqEndpointOptions);
     request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
     start(): Promise<void>;
@@ -46,6 +58,44 @@ export declare class IcqqIpcEndpoint implements EndpointInstance {
     removeReaction(messageId: string, reactionId: string): Promise<void>;
     /** Activity-feedback autoRemove / Console recall. */
     recallMessage(messageId: string): Promise<void>;
+    /** EndpointManagement.listFriends —— 好友列表（LIST_FRIENDS，归一为 {user_id, nickname, remark}）。 */
+    getFriendList(): Promise<Array<{
+        user_id: number;
+        nickname: string;
+        remark: string;
+    }>>;
+    /** EndpointManagement.listGroups —— 群列表（LIST_GROUPS，归一为 {group_id, name}）。 */
+    getGroupList(): Promise<Array<{
+        group_id: number;
+        name: string;
+    }>>;
+    /** EndpointManagement.listGroupMembers —— 群成员列表（字段对齐 daemon 返回）。 */
+    getGroupMemberList(groupId: number | string): Promise<IpcMemberInfo[]>;
+    /** getGroupMemberList 别名（console 探测 listMembers / getMemberList）。 */
+    listMembers(groupId: number | string): Promise<IpcMemberInfo[]>;
+    getMemberList(groupId: number | string): Promise<IpcMemberInfo[]>;
+    /**
+     * EndpointManagement.resolveRequest —— id 为 inbox 行的 platform_request_id。
+     * 先 GET_SYSTEM_MSG 按 flag（回退 seq）定位请求，再按类型路由 handle_friend/group_request。
+     */
+    approveRequest(id: string, remark?: string): Promise<void>;
+    rejectRequest(id: string, reason?: string): Promise<void>;
+    /** EndpointManagement.deleteFriend —— FRIEND_DELETE。 */
+    deleteFriend(userId: number | string): Promise<void>;
+    /** deleteFriend 别名（console 探测 delete_friend）。 */
+    delete_friend(userId: number | string): Promise<void>;
+    /** EndpointManagement.kickGroupMember —— GROUP_KICK。 */
+    removeMember(groupId: number | string, userId: number | string): Promise<void>;
+    kickMember(groupId: number | string, userId: number | string): Promise<void>;
+    setGroupKick(groupId: number | string, userId: number | string): Promise<void>;
+    /** EndpointManagement.muteGroupMember —— GROUP_MUTE（duration 秒，默认 600）。 */
+    muteMember(groupId: number | string, userId: number | string, duration?: number): Promise<void>;
+    banMember(groupId: number | string, userId: number | string, duration?: number): Promise<void>;
+    setGroupMute(groupId: number | string, userId: number | string, duration?: number): Promise<void>;
+    /** EndpointManagement.setGroupAdmin —— SET_GROUP_ADMIN（enable 默认 true）。 */
+    setModerator(groupId: number | string, userId: number | string, enable?: boolean): Promise<void>;
+    setAdmin(groupId: number | string, userId: number | string, enable?: boolean): Promise<void>;
+    setGroupAdmin(groupId: number | string, userId: number | string, enable?: boolean): Promise<void>;
     /** Test / internal: admit when open. */
     admit(msg: IcqqInboundMessage): void;
 }

package/lib/endpoint.js

@@ -1,7 +1,8 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { registerIcqqAgentEndpoint } from './icqq-agent-deps.js';
 import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, quotedPayloadFromIcqqSource, resolveIcqqQuoteIdFromEvent, shouldSkipSelfInboundMessage, unwrapIcqqIpcEventPayload, } from './icqq-inbound.js';
-import { isIcqqGuildIpcEvent, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
+import { buildIcqqInboxNoticeRow, buildIcqqInboxRequestRow, buildIcqqSystemRequestRow, isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
+import { IcqqGuildCatalog, isIcqqGuildIpcEvent, normalizeIcqqGuildInboundMessage, } from './icqq-guild.js';
 import { IpcClient } from './ipc-client.js';
 import { materializeOutboundBase64, resolveIcqqOutboundMediaMode, } from './outbound-media.js';
 import { Actions, formatInboundContent, formatInboundTarget, formatOutboundBody, parseSendTarget, } from './protocol.js';
@@ -14,10 +15,28 @@ export class IcqqIpcEndpoint {
     ipc;
     friends = new Map();
     groups = new Map();
+    #guildCatalog = new IcqqGuildCatalog();
+    management = Object.freeze({
+        listFriends: () => this.getFriendList(),
+        listGroups: () => this.getGroupList(),
+        listChannels: async () => {
+            await this.#guildCatalog.syncAll(this.ipc);
+            return this.#guildCatalog.getGuildChannelList();
+        },
+        listGroupMembers: (groupId) => this.getGroupMemberList(groupId),
+        approveRequest: (requestId, remark) => this.approveRequest(requestId, remark),
+        rejectRequest: (requestId, reason) => this.rejectRequest(requestId, reason),
+        kickGroupMember: (groupId, userId) => this.removeMember(groupId, userId),
+        muteGroupMember: (groupId, userId, duration) => this.muteMember(groupId, userId, duration),
+        setGroupAdmin: (groupId, userId, enabled) => this.setModerator(groupId, userId, enabled),
+        deleteFriend: (userId) => this.deleteFriend(userId),
+    });
     #open = false;
     #started = false;
     #subscriptions = [];
     #inboundDeduper = new InboundMessageDeduper();
+    /** request/notice 去重（推送事件与 GET_SYSTEM_MSG 首拉可能重复同一 flag）。 */
+    #inboxDeduper = new InboundMessageDeduper();
     #unregisterAgent;
     /** 用户主动 stop 时为 true，阻止自动重连 */
     #intentionalDisconnect = false;
@@ -71,6 +90,9 @@ export class IcqqIpcEndpoint {
             this.#handleEvent(event);
         });
         this.#subscriptions.push(sub);
+        // daemon 推送 client.em 全部事件，request/notice 实时到达；
+        // 启动时补一次 GET_SYSTEM_MSG，捞离线期间积存的待处理请求。
+        void this.#pullPendingSystemMessages();
     }
     /** IPC/RPC 意外断开时调度重连（指数退避） */
     #scheduleReconnect() {
@@ -145,8 +167,10 @@ export class IcqqIpcEndpoint {
         this.#unregisterAgent?.();
         this.#unregisterAgent = undefined;
         this.#inboundDeduper.clear();
+        this.#inboxDeduper.clear();
         this.friends.clear();
         this.groups.clear();
+        this.#guildCatalog.clear();
         try {
             this.ipc?.close();
         }
@@ -342,6 +366,132 @@ export class IcqqIpcEndpoint {
             }));
         }
     }
+    // ── 社交/群管（Console endpoint RPC 探测面）────────────────────────
+    // console-rpc-extended.ts 按方法名探测这些接口；全部薄封装走 IPC daemon。
+    /** EndpointManagement.listFriends —— 好友列表（LIST_FRIENDS，归一为 {user_id, nickname, remark}）。 */
+    async getFriendList() {
+        const resp = await this.#mustRequest(Actions.LIST_FRIENDS, undefined, '获取好友列表');
+        const list = Array.isArray(resp.data) ? resp.data : [];
+        return list.map((f) => ({
+            user_id: f.user_id,
+            nickname: f.nickname,
+            remark: f.remark ?? '',
+        }));
+    }
+    /** EndpointManagement.listGroups —— 群列表（LIST_GROUPS，归一为 {group_id, name}）。 */
+    async getGroupList() {
+        const resp = await this.#mustRequest(Actions.LIST_GROUPS, undefined, '获取群列表');
+        const list = Array.isArray(resp.data) ? resp.data : [];
+        return list.map((g) => ({
+            group_id: g.group_id,
+            name: g.group_name,
+        }));
+    }
+    /** EndpointManagement.listGroupMembers —— 群成员列表（字段对齐 daemon 返回）。 */
+    async getGroupMemberList(groupId) {
+        const resp = await this.#mustRequest(Actions.LIST_GROUP_MEMBERS, { group_id: toNumericId(groupId, 'group_id') }, '获取群成员列表');
+        return Array.isArray(resp.data) ? resp.data : [];
+    }
+    /** getGroupMemberList 别名（console 探测 listMembers / getMemberList）。 */
+    listMembers(groupId) {
+        return this.getGroupMemberList(groupId);
+    }
+    getMemberList(groupId) {
+        return this.getGroupMemberList(groupId);
+    }
+    /**
+     * EndpointManagement.resolveRequest —— id 为 inbox 行的 platform_request_id。
+     * 先 GET_SYSTEM_MSG 按 flag（回退 seq）定位请求，再按类型路由 handle_friend/group_request。
+     */
+    async approveRequest(id, remark) {
+        await this.#handleSystemRequest(id, true, { remark });
+    }
+    async rejectRequest(id, reason) {
+        await this.#handleSystemRequest(id, false, { reason });
+    }
+    /** EndpointManagement.deleteFriend —— FRIEND_DELETE。 */
+    async deleteFriend(userId) {
+        await this.#mustRequest(Actions.FRIEND_DELETE, { user_id: toNumericId(userId, 'user_id') }, '删除好友');
+    }
+    /** deleteFriend 别名（console 探测 delete_friend）。 */
+    delete_friend(userId) {
+        return this.deleteFriend(userId);
+    }
+    /** EndpointManagement.kickGroupMember —— GROUP_KICK。 */
+    async removeMember(groupId, userId) {
+        await this.#mustRequest(Actions.GROUP_KICK, { group_id: toNumericId(groupId, 'group_id'), user_id: toNumericId(userId, 'user_id') }, '踢出群成员');
+    }
+    kickMember(groupId, userId) {
+        return this.removeMember(groupId, userId);
+    }
+    setGroupKick(groupId, userId) {
+        return this.removeMember(groupId, userId);
+    }
+    /** EndpointManagement.muteGroupMember —— GROUP_MUTE（duration 秒，默认 600）。 */
+    async muteMember(groupId, userId, duration = 600) {
+        await this.#mustRequest(Actions.GROUP_MUTE, {
+            group_id: toNumericId(groupId, 'group_id'),
+            user_id: toNumericId(userId, 'user_id'),
+            duration,
+        }, '禁言群成员');
+    }
+    banMember(groupId, userId, duration = 600) {
+        return this.muteMember(groupId, userId, duration);
+    }
+    setGroupMute(groupId, userId, duration = 600) {
+        return this.muteMember(groupId, userId, duration);
+    }
+    /** EndpointManagement.setGroupAdmin —— SET_GROUP_ADMIN（enable 默认 true）。 */
+    async setModerator(groupId, userId, enable = true) {
+        await this.#mustRequest(Actions.SET_GROUP_ADMIN, {
+            group_id: toNumericId(groupId, 'group_id'),
+            user_id: toNumericId(userId, 'user_id'),
+            enable,
+        }, '设置群管理员');
+    }
+    setAdmin(groupId, userId, enable = true) {
+        return this.setModerator(groupId, userId, enable);
+    }
+    setGroupAdmin(groupId, userId, enable = true) {
+        return this.setModerator(groupId, userId, enable);
+    }
+    /** IPC 请求并统一错误上下文：daemon 返回 ok=false 时抛出带操作名的错误。 */
+    async #mustRequest(action, params, label) {
+        const resp = await this.request(action, params);
+        if (!resp.ok) {
+            throw new Error(`icqq ${label}失败: ${resp.error ?? 'daemon 未返回错误详情'}`);
+        }
+        return resp;
+    }
+    /** 按 flag/seq 在 GET_SYSTEM_MSG 中定位请求，路由到好友/群请求处理 action。 */
+    async #handleSystemRequest(id, approve, extra) {
+        const resp = await this.#mustRequest(Actions.GET_SYSTEM_MSG, undefined, '获取待处理请求');
+        const data = resp.data;
+        const friendRequests = Array.isArray(data?.friendRequests)
+            ? data.friendRequests
+            : [];
+        const groupRequests = Array.isArray(data?.groupRequests)
+            ? data.groupRequests
+            : [];
+        const matches = (m) => m.flag === id || (m.seq != null && String(m.seq) === id);
+        const friend = friendRequests.find(matches);
+        const group = friend ? undefined : groupRequests.find(matches);
+        const target = friend ?? group;
+        if (!target?.flag) {
+            throw new Error(`icqq 未找到待处理请求: ${id}（GET_SYSTEM_MSG 中无匹配 flag/seq）`);
+        }
+        const params = { flag: target.flag, approve };
+        if (friend) {
+            if (extra.remark)
+                params.remark = extra.remark;
+            await this.#mustRequest(Actions.HANDLE_FRIEND_REQUEST, params, '处理好友请求');
+        }
+        else {
+            if (extra.reason)
+                params.reason = extra.reason;
+            await this.#mustRequest(Actions.HANDLE_GROUP_REQUEST, params, '处理群请求');
+        }
+    }
     /** Test / internal: admit when open. */
     admit(msg) {
         if (!this.#open)
@@ -394,6 +544,14 @@ export class IcqqIpcEndpoint {
         const payload = unwrapIcqqIpcEventPayload(event);
         if (!payload || typeof payload !== 'object')
             return;
+        if (isIcqqRequestPayload(payload)) {
+            this.#recordInboxRequest(payload);
+            return;
+        }
+        if (isIcqqNoticePayload(payload)) {
+            this.#recordInboxNotice(payload);
+            return;
+        }
         if (!isIcqqMessagePostType(payload))
             return;
         const data = payload;
@@ -427,6 +585,7 @@ export class IcqqIpcEndpoint {
         const normalized = normalizeIcqqGuildInboundMessage(payload);
         if (!normalized)
             return;
+        this.#guildCatalog.upsertFromInbound(normalized.raw);
         if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`))
             return;
         this.admit({
@@ -445,6 +604,71 @@ export class IcqqIpcEndpoint {
             },
         });
     }
+    /** 收件箱行公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
+    #inboxBase() {
+        const id = String(this.#options.id);
+        return { adapter: id.split('\0').pop() ?? id, endpointId: this.name };
+    }
+    #recordInboxRequest(payload) {
+        const hooks = this.#options.inbox;
+        if (!hooks)
+            return;
+        const row = buildIcqqInboxRequestRow(payload, this.#inboxBase());
+        if (!row)
+            return;
+        if (!this.#inboxDeduper.shouldProcess(`request:${String(row.platform_request_id)}`))
+            return;
+        void hooks.recordRequest(row);
+        hooks.publish?.('endpoint:request', row);
+    }
+    #recordInboxNotice(payload) {
+        const hooks = this.#options.inbox;
+        if (!hooks)
+            return;
+        const row = buildIcqqInboxNoticeRow(payload, this.#inboxBase());
+        if (!row)
+            return;
+        if (!this.#inboxDeduper.shouldProcess(`notice:${String(row.platform_notice_id)}`))
+            return;
+        void hooks.recordNotice(row);
+        hooks.publish?.('endpoint:notice', row);
+    }
+    /** 启动/重连后首拉 GET_SYSTEM_MSG：补录离线期间的好友/群待处理请求。 */
+    async #pullPendingSystemMessages() {
+        const hooks = this.#options.inbox;
+        if (!hooks || !this.ipc)
+            return;
+        try {
+            const resp = await this.ipc.request(Actions.GET_SYSTEM_MSG);
+            if (!resp.ok)
+                return;
+            const data = resp.data;
+            const base = this.#inboxBase();
+            const rows = [
+                ...(Array.isArray(data?.friendRequests)
+                    ? data.friendRequests.map((m) => buildIcqqSystemRequestRow(m, 'friend', base))
+                    : []),
+                ...(Array.isArray(data?.groupRequests)
+                    ? data.groupRequests.map((m) => buildIcqqSystemRequestRow(m, 'group', base))
+                    : []),
+            ];
+            for (const row of rows) {
+                if (!row)
+                    continue;
+                if (!this.#inboxDeduper.shouldProcess(`request:${String(row.platform_request_id)}`))
+                    continue;
+                void hooks.recordRequest(row);
+                hooks.publish?.('endpoint:request', row);
+            }
+        }
+        catch (error) {
+            logger.debug(formatCompact({
+                op: 'inbox_pull_system_msg',
+                endpoint: this.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
 }
 /**
  * 组装入站 metadata：在基础字段上补充 quote 链路信息。
@@ -474,6 +698,14 @@ function buildIcqqQuoteMetadata(data, base) {
         metadata.quote_content = quoteText;
     return metadata;
 }
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumericId(value, label) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || String(value).trim() === '') {
+        throw new TypeError(`icqq ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}
 async function defaultCreateIpc(config) {
     const uin = Number(config.name);
     if (config.rpc) {

package/lib/icqq-guild.d.ts

@@ -3,7 +3,13 @@
  */
 import { type MessageSegment } from "zhin.js";
 import { type IpcGuildMessageEventData } from "./protocol.js";
-import type { IpcClient } from "./ipc-client.js";
+/** Narrow request port shared by the real IPC client and endpoint test transports. */
+export interface IcqqGuildRpc {
+    request(action: string, params?: Record<string, unknown>): Promise<{
+        ok: boolean;
+        data?: unknown;
+    }>;
+}
 export interface IcqqGuildChannelEntry {
     channel_id: string;
     channel_name: string;
@@ -27,7 +33,7 @@ export declare class IcqqGuildCatalog {
     private readonly channels;
     private readonly guilds;
     clear(): void;
-    syncAll(ipc: IpcClient): Promise<void>;
+    syncAll(ipc: IcqqGuildRpc): Promise<void>;
     upsertFromInbound(data: IpcGuildMessageEventData): void;
     getGuildChannelList(): Array<{
         id: string;

package/lib/icqq-inbox.d.ts

@@ -0,0 +1,33 @@
+/**
+ * icqq IPC request/notice 事件 → 统一收件箱行（unified_inbox_request / unified_inbox_notice）。
+ *
+ * daemon 经 IpcEvent 推送 icqq client.em 分发的全部事件（见 protocol.ts），
+ * 好友/群请求（request.friend.add、request.group.add、request.group.invite）
+ * 与通知（notice.friend.*、notice.group.*）随事件流实时到达，无需轮询；
+ * endpoint 启动时补一次 GET_SYSTEM_MSG 拉取离线期间积存的待处理请求。
+ */
+import type { IpcSystemMessage } from './types.js';
+/** 行级公共前缀：adapter 槽 localName + endpoint live 名（uin）。 */
+export interface IcqqInboxBase {
+    readonly adapter: string;
+    readonly endpointId: string;
+}
+/** post_type=request / request.* 判定（OneBot 事件壳）。 */
+export declare function isIcqqRequestPayload(payload: unknown): boolean;
+/** post_type=notice / notice.* 判定。 */
+export declare function isIcqqNoticePayload(payload: unknown): boolean;
+/**
+ * request 事件载荷 → unified_inbox_request 行。
+ * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。
+ */
+export declare function buildIcqqInboxRequestRow(payload: Record<string, unknown>, base: IcqqInboxBase): Record<string, unknown> | null;
+/**
+ * notice 事件载荷 → unified_inbox_notice 行。
+ * 事件本身无稳定 id，platform_notice_id 由 time + actor + type 合成（配合去重）。
+ */
+export declare function buildIcqqInboxNoticeRow(payload: Record<string, unknown>, base: IcqqInboxBase): Record<string, unknown> | null;
+/**
+ * GET_SYSTEM_MSG 返回项 → unified_inbox_request 行（启动时首次拉取）。
+ * friend 列表项 type 语义即好友请求；group 列表项 type 为 add/invite（记 sub_type）。
+ */
+export declare function buildIcqqSystemRequestRow(message: IpcSystemMessage, kind: 'friend' | 'group', base: IcqqInboxBase): Record<string, unknown> | null;