@zhin.js/adapter-icqq 6.0.3 → 7.0.1

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,16 +366,166 @@ 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)
+        if (!this.#open) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'endpoint_closed',
+                endpoint: this.name,
+                id: msg.id,
+                target: msg.target,
+            }));
             return;
-        // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）只能经 metadata 传递
-        const mentioned = isIcqqBotMentioned({ uin: this.name, rawMessage: msg.content });
+        }
+        // 新 Runtime Message.content 为纯文本：@ 本机（uin = name）经结构化段 / metadata 传递
+        const mentioned = isIcqqBotMentioned({
+            uin: this.name,
+            content: msg.segments,
+            rawMessage: msg.content,
+        });
+        logger.debug(formatCompact({
+            op: 'icqq_inbound_admit',
+            endpoint: this.name,
+            id: msg.id,
+            target: msg.target,
+            sender: msg.sender,
+            channelType: msg.channelType,
+            mentioned: mentioned || undefined,
+            preview: msg.content.slice(0, 80),
+            segments: summarizeSegmentTypes(msg.segments),
+        }));
         void this.#options.gateway.receive({
             adapter: this.#options.id,
             target: msg.target,
             content: msg.content,
+            ...(msg.segments ? { segments: msg.segments } : {}),
             sender: msg.sender,
             id: msg.id,
             metadata: Object.freeze({
@@ -394,16 +568,47 @@ 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;
-        if (shouldSkipSelfInboundMessage(data))
+        if (shouldSkipSelfInboundMessage(data)) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'self',
+                endpoint: this.name,
+                user_id: data.user_id,
+                self_id: data.self_id,
+            }));
             return;
+        }
         const normalized = normalizeIcqqInboundMessage(data);
-        if (!normalized)
+        if (!normalized) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'normalize_failed',
+                endpoint: this.name,
+                message_id: data.message_id,
+                message_type: data.message_type ?? data.type,
+            }));
             return;
-        if (!this.#inboundDeduper.shouldProcess(normalized.messageId))
+        }
+        if (!this.#inboundDeduper.shouldProcess(normalized.messageId)) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'dedupe',
+                endpoint: this.name,
+                id: normalized.messageId,
+            }));
             return;
+        }
         this.admit({
             id: normalized.messageId,
             target: formatInboundTarget({
@@ -412,6 +617,7 @@ export class IcqqIpcEndpoint {
                 channelParentGroupId: normalized.channelParentGroupId,
             }),
             content: formatInboundContent(normalized.rawMessage),
+            segments: normalized.content,
             sender: normalized.userId,
             channelType: normalized.channelType,
             metadata: buildIcqqQuoteMetadata(data, {
@@ -425,10 +631,24 @@ export class IcqqIpcEndpoint {
         if (!payload || typeof payload !== 'object')
             return;
         const normalized = normalizeIcqqGuildInboundMessage(payload);
-        if (!normalized)
+        if (!normalized) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'guild_normalize_failed',
+                endpoint: this.name,
+            }));
             return;
-        if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`))
+        }
+        this.#guildCatalog.upsertFromInbound(normalized.raw);
+        if (!this.#inboundDeduper.shouldProcess(`guild:${normalized.messageId}`)) {
+            logger.debug(formatCompact({
+                op: 'icqq_inbound_skip',
+                reason: 'dedupe',
+                endpoint: this.name,
+                id: `guild:${normalized.messageId}`,
+            }));
             return;
+        }
         this.admit({
             id: normalized.messageId,
             target: formatInboundTarget({
@@ -437,6 +657,7 @@ export class IcqqIpcEndpoint {
                 guildId: normalized.guildId,
             }),
             content: formatInboundContent(normalized.rawMessage),
+            segments: normalized.content,
             sender: normalized.userId,
             channelType: 'channel',
             metadata: {
@@ -445,6 +666,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 +760,28 @@ 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;
+}
+function summarizeSegmentTypes(segments) {
+    if (!segments?.length)
+        return undefined;
+    return segments
+        .map((segment) => {
+        if (typeof segment.type === 'string')
+            return segment.type;
+        if (segment.type && typeof segment.type === 'object' && 'name' in segment.type) {
+            return String(segment.type.name);
+        }
+        return '?';
+    })
+        .join(',');
+}
 async function defaultCreateIpc(config) {
     const uin = Number(config.name);
     if (config.rpc) {

package/lib/icqq-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const icqqEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/icqq-endpoint-commands.js

@@ -0,0 +1,35 @@
+/**
+ * `icqq endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ *
+ * ICQQ 的凭据由外部守护进程（@icqqjs/cli）按账号持有（~/.icqq/<uin>/），
+ * 其 IPC/RPC 协议是「按 uin 连接 + auth + 账号级 action」，没有 add-account /
+ * 触发 login 的 action——扫码登录只能经 `icqq login <uin>` CLI 完成。
+ * 因此 add 不走 kv 凭据录入，而是 bindFlow：校验 uin、把 { name: '<uin>' }
+ * 追加到 plugins.icqq.endpoints，并引导用户先完成守护进程登录。
+ */
+import { addEndpointToConfig, createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { icqqRuntimeStateToken } from './icqq-runtime-state.js';
+export const icqqEndpointCommands = createEndpointCommands({
+    adapterKey: 'icqq',
+    adapterDisplayName: 'ICQQ',
+    running: (use) => use(icqqRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => (entry.rpc ? 'rpc（远程守护进程）' : 'ipc（本地守护进程）'),
+    addDescription: '登记 ICQQ endpoint（uin 需先经 icqq login 完成扫码登录；重启 zhin 生效）',
+    bindFlow: ({ name }) => {
+        if (!name) {
+            return '用法：icqq endpoint add <uin>（uin 为纯数字 QQ 号，且需先执行 icqq login <uin> 完成扫码登录）';
+        }
+        if (!/^\d+$/.test(name)) {
+            return 'icqq endpoint 名必须是纯数字 QQ 号（uin）';
+        }
+        try {
+            const filePath = addEndpointToConfig('icqq', { name });
+            return (`✅ endpoint「${name}」已追加到 ${filePath} 的 plugins.icqq.endpoints。\n` +
+                `⚠️ 请确保已执行 icqq login ${name} 启动守护进程并完成扫码登录；重启 zhin 后生效。`);
+        }
+        catch (error) {
+            return `添加失败：${error instanceof Error ? error.message : String(error)}`;
+        }
+    },
+}, defineCommand);

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;

package/lib/icqq-inbox.js

@@ -0,0 +1,129 @@
+/** post_type=request / request.* 判定（OneBot 事件壳）。 */
+export function isIcqqRequestPayload(payload) {
+    const postType = payload?.post_type;
+    return typeof postType === 'string'
+        && (postType === 'request' || postType.startsWith('request.'));
+}
+/** post_type=notice / notice.* 判定。 */
+export function isIcqqNoticePayload(payload) {
+    const postType = payload?.post_type;
+    return typeof postType === 'string'
+        && (postType === 'notice' || postType.startsWith('notice.'));
+}
+/**
+ * request 事件载荷 → unified_inbox_request 行。
+ * platform_request_id 取 flag（审批回执句柄），缺省回退 seq；两者皆无则无法审批，丢弃。
+ */
+export function buildIcqqInboxRequestRow(payload, base) {
+    const userId = payload.user_id ?? payload.actor_id;
+    if (userId == null)
+        return null;
+    const flag = asNonEmptyString(payload.flag);
+    const platformRequestId = flag ?? (payload.seq != null ? String(payload.seq) : '');
+    if (!platformRequestId)
+        return null;
+    const requestType = asNonEmptyString(payload.request_type) ?? asNonEmptyString(payload.type);
+    const groupId = payload.group_id;
+    const isGroup = requestType === 'group' || groupId != null;
+    return {
+        adapter: base.adapter,
+        endpoint_id: base.endpointId,
+        platform_request_id: platformRequestId,
+        type: isGroup ? 'group' : (requestType ?? 'friend'),
+        scene_type: isGroup ? 'group' : null,
+        scene_id: String(groupId ?? userId),
+        sub_type: asNonEmptyString(payload.sub_type),
+        actor_id: String(userId),
+        actor_name: asNonEmptyString(payload.nickname),
+        comment: asNonEmptyString(payload.comment),
+        created_at: toMillis(payload.time),
+        resolved: 0,
+        resolved_at: null,
+        consumed: 0,
+        consumed_at: null,
+    };
+}
+/**
+ * notice 事件载荷 → unified_inbox_notice 行。
+ * 事件本身无稳定 id，platform_notice_id 由 time + actor + type 合成（配合去重）。
+ */
+export function buildIcqqInboxNoticeRow(payload, base) {
+    const noticeType = asNonEmptyString(payload.notice_type) ?? asNonEmptyString(payload.type);
+    if (!noticeType)
+        return null;
+    const subType = asNonEmptyString(payload.sub_type);
+    const userId = payload.user_id;
+    const operatorId = payload.operator_id;
+    const groupId = payload.group_id;
+    const createdAt = toMillis(payload.time);
+    const actorId = operatorId ?? userId;
+    const platformNoticeId = asNonEmptyString(payload.notice_id)
+        ?? (payload.seq != null ? String(payload.seq) : undefined)
+        ?? `${createdAt}_${String(actorId ?? '')}_${noticeType}${subType ? `.${subType}` : ''}`;
+    const targetId = userId != null && String(userId) !== String(actorId ?? '') ? userId : undefined;
+    return {
+        adapter: base.adapter,
+        endpoint_id: base.endpointId,
+        platform_notice_id: platformNoticeId,
+        type: noticeType,
+        scene_type: groupId != null ? 'group' : null,
+        scene_id: String(groupId ?? userId ?? operatorId ?? ''),
+        sub_type: subType,
+        actor_id: actorId != null ? String(actorId) : null,
+        actor_name: asNonEmptyString(payload.nickname),
+        target_id: targetId != null ? String(targetId) : null,
+        target_name: null,
+        payload: safeJson(payload),
+        created_at: createdAt,
+        consumed: 0,
+        consumed_at: null,
+    };
+}
+/**
+ * GET_SYSTEM_MSG 返回项 → unified_inbox_request 行（启动时首次拉取）。
+ * friend 列表项 type 语义即好友请求；group 列表项 type 为 add/invite（记 sub_type）。
+ */
+export function buildIcqqSystemRequestRow(message, kind, base) {
+    if (message.user_id == null)
+        return null;
+    const platformRequestId = asNonEmptyString(message.flag)
+        ?? (message.seq != null ? String(message.seq) : '');
+    if (!platformRequestId)
+        return null;
+    return {
+        adapter: base.adapter,
+        endpoint_id: base.endpointId,
+        platform_request_id: platformRequestId,
+        type: kind,
+        scene_type: kind === 'group' ? 'group' : null,
+        scene_id: String(kind === 'group' ? (message.group_id ?? message.user_id) : message.user_id),
+        sub_type: kind === 'group' ? (asNonEmptyString(message.type) ?? null) : null,
+        actor_id: String(message.user_id),
+        actor_name: asNonEmptyString(message.nickname),
+        comment: asNonEmptyString(message.comment),
+        created_at: toMillis(message.time),
+        resolved: 0,
+        resolved_at: null,
+        consumed: 0,
+        consumed_at: null,
+    };
+}
+function asNonEmptyString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+/** oicq 事件 time 为秒；缺失时回退当前时间。 */
+function toMillis(time) {
+    const seconds = Number(time);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : Date.now();
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value ?? {});
+    }
+    catch {
+        return '{}';
+    }
+}

package/lib/icqq-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const icqqRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/icqq-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * ICQQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `icqq endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+export const icqqRuntimeStateToken = defineEndpointRuntimeStateToken('icqq');

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { Actions, formatInboundContent, formatInboundTarget, formatOutboundBody, parseSendTarget, resolveIcqqConfig, type IcqqAdapterConfig, type IcqqInboundMessage, type IcqqWireSegment, type IpcEvent, type IpcMessage, type IpcRequest, type IpcResponse, type ParsedIcqqSendTarget, type ResolvedIcqqConfig, } from './protocol.js';
-export { IcqqIpcEndpoint, type CreateIcqqIpc, type IcqqEndpointOptions, type IcqqIpcTransport, } from './endpoint.js';
+export { IcqqIpcEndpoint, type CreateIcqqIpc, type IcqqEndpointOptions, type IcqqInboxHooks, type IcqqIpcTransport, } from './endpoint.js';
 export * from './types.js';
 export { getIcqqAgentDeps, registerIcqqAgentEndpoint, setIcqqAgentDeps, type IcqqAgentDeps, type IcqqAgentEndpoint, } from './icqq-agent-deps.js';
 export { IpcClient } from './ipc-client.js';