@zhin.js/adapter-icqq 6.0.2 → 7.0.0

package/lib/forward-msg.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 合并转发（聊天记录）解析：从 json/xml 提取 resid，经 IPC get_forward_msg 拉取正文。
+ */
+import { type MessageSegment, type QuotedMessagePayload } from 'zhin.js';
+import type { IpcClient } from "./ipc-client.js";
+import { type IcqqMessageElement } from "./icqq-inbound.js";
+/** 从 QQ 合并转发 json 元素提取 resid */
+export declare function extractForwardResidFromJsonElement(el: IcqqMessageElement): string | undefined;
+/** 从 get_msg 的 raw_message 解析 multimsg resid（XML / JSON / CQ:json） */
+export declare function extractForwardResidFromRawMessage(raw: string): string | undefined;
+/** 从 get_msg 的 message 元素数组解析 multimsg resid */
+export declare function extractForwardResidFromGetMsgElements(elements: IcqqMessageElement[] | undefined): string | undefined;
+/**
+ * 从 get_msg 响应解析合并转发 resid（优先 message 数组，其次 raw_message）。
+ */
+export declare function extractForwardResidFromGetMsg(data: unknown): string | undefined;
+export declare function extractForwardResidFromSegments(content: MessageSegment[]): string | undefined;
+export declare function extractForwardResidFromPayload(payload: QuotedMessagePayload): string | undefined;
+/** 在 get_msg / IPC 原始对象里深度搜索 resid */
+export declare function extractForwardResidDeep(root: unknown, maxDepth?: number): string | undefined;
+export declare function isForwardPlaceholderPayload(payload: QuotedMessagePayload): boolean;
+/** 将 get_forward_msg 响应格式化为可读聊天记录 */
+export declare function formatForwardMsgResponse(data: unknown): string;
+export declare function fetchForwardMsgText(ipc: IpcClient, id: string): Promise<string>;
+/** 若 payload 含合并转发，拉取并追加到 content */
+export declare function enrichQuotedPayloadWithForward(ipc: IpcClient | null | undefined, payload: QuotedMessagePayload, ipcRaw?: unknown): Promise<QuotedMessagePayload>;

package/lib/{src/forward-msg.js → forward-msg.js}

@@ -387,4 +387,3 @@ export async function enrichQuotedPayloadWithForward(ipc, payload, ipcRaw) {
     }
     return payload;
 }
-//# sourceMappingURL=forward-msg.js.map

package/lib/icqq-agent-deps.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent tool deps for icqq.
+ * Endpoints register themselves on start; tools look up by config name / QQ uin.
+ */
+import type { IpcFriendInfo, IpcGroupInfo } from './types.js';
+import type { IpcResponse } from './protocol.js';
+export interface IcqqAgentEndpoint {
+    readonly name: string;
+    readonly ipc: {
+        request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
+    };
+    readonly friends: Map<number, IpcFriendInfo>;
+    readonly groups: Map<number, IpcGroupInfo>;
+    request(action: string, params?: Record<string, unknown>): Promise<IpcResponse>;
+}
+export interface IcqqAgentDeps {
+    getEndpoint: (endpointId: string) => IcqqAgentEndpoint;
+    getAdapter?: () => {
+        getEndpoint: (id: string) => IcqqAgentEndpoint;
+    };
+}
+export declare function registerIcqqAgentEndpoint(endpointId: string, endpoint: IcqqAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setIcqqAgentDeps(deps: IcqqAgentDeps | null): void;
+export declare function getIcqqAgentDeps(): IcqqAgentDeps;

package/lib/icqq-agent-deps.js

@@ -0,0 +1,32 @@
+/**
+ * Agent tool deps for icqq.
+ * Endpoints register themselves on start; tools look up by config name / QQ uin.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerIcqqAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setIcqqAgentDeps(deps) {
+    override = deps;
+}
+function lookup(endpointId) {
+    const registered = endpoints.get(endpointId);
+    if (!registered)
+        throw new Error(`Endpoint ${endpointId} 不存在`);
+    return registered;
+}
+export function getIcqqAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint: lookup,
+        getAdapter: () => ({ getEndpoint: lookup }),
+    };
+}

package/lib/icqq-guild.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ICQQ guild (QQ 频道) catalog sync, inbound normalize, Console channel list.
+ */
+import { type MessageSegment } from "zhin.js";
+import { type IpcGuildMessageEventData } from "./protocol.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;
+    guild_id: string;
+    guild_name: string;
+}
+export interface NormalizedIcqqGuildInbound {
+    messageId: string;
+    channelId: string;
+    guildId: string;
+    guildName: string;
+    channelName: string;
+    userId: string;
+    nickname: string;
+    content: MessageSegment[];
+    rawMessage: string;
+    timestampMs: number;
+    raw: IpcGuildMessageEventData;
+}
+export declare class IcqqGuildCatalog {
+    private readonly channels;
+    private readonly guilds;
+    clear(): void;
+    syncAll(ipc: IcqqGuildRpc): Promise<void>;
+    upsertFromInbound(data: IpcGuildMessageEventData): void;
+    getGuildChannelList(): Array<{
+        id: string;
+        name: string;
+        parent: {
+            type: "guild";
+            id: string;
+            name: string;
+        };
+    }>;
+    resolveConsoleChannelNames(channelId: string, guildId?: string): {
+        channelName?: string;
+        parentName?: string;
+    };
+}
+export declare function isIcqqGuildIpcEvent(eventName: string | undefined): boolean;
+export declare function normalizeIcqqGuildInboundMessage(data: IpcGuildMessageEventData & Record<string, unknown>): NormalizedIcqqGuildInbound | null;

package/lib/{src/icqq-guild.js → icqq-guild.js}

@@ -1,6 +1,9 @@
+/**
+ * ICQQ guild (QQ 频道) catalog sync, inbound normalize, Console channel list.
+ */
+import { toCanonicalSegments } from "zhin.js";
 import { Actions } from "./protocol.js";
 import { parseCqMessage } from "./cq-message.js";
-import { toCanonicalSegments } from "./segment-mapper.js";
 export class IcqqGuildCatalog {
     channels = new Map();
     guilds = new Map();
@@ -112,4 +115,3 @@ export function normalizeIcqqGuildInboundMessage(data) {
         raw: data,
     };
 }
-//# sourceMappingURL=icqq-guild.js.map

package/lib/icqq-inbound.d.ts

@@ -0,0 +1,139 @@
+/**
+ * icqq 守护进程 IPC 入站事件归一化（post_type / message_type / message 段）
+ */
+import { type MessageSegment, type QuotedMessagePayload } from "zhin.js";
+import type { GroupRole } from "./types.js";
+/** 守护进程推送的通用事件壳 */
+export interface IcqqIpcEventBase {
+    post_type?: string;
+    self_id?: number;
+}
+/** post_type=message 时的消息体（字段随 icqqjs/cli 演进，未知字段保留） */
+export interface IcqqIpcMessageEvent extends IcqqIpcEventBase {
+    post_type: "message";
+    message_id?: string;
+    msg_id?: string;
+    user_id: number;
+    user_uid?: string;
+    time: number;
+    seq?: number;
+    message_type: string;
+    sub_type?: string;
+    raw_message?: string;
+    message?: IcqqMessageElement[];
+    sender?: {
+        user_id?: number;
+        user_uid?: string;
+        nickname?: string;
+        card?: string;
+        /** 群临时会话来源群号 */
+        group_id?: number;
+        /** NT/IPC 群成员角色：owner | admin | member */
+        role?: GroupRole | string;
+    };
+    from_id?: number;
+    from_uid?: string;
+    group_id?: number;
+    to_id?: number;
+    nickname?: string;
+    /** 旧版 IPC 仅有 type 无 message_type */
+    type?: "group" | "private";
+    /** oicq Message#source：被引用回复的源消息 */
+    source?: IcqqMessageSource;
+}
+/** oicq 引用源消息（与 MessageEvent.source 对齐） */
+export interface IcqqMessageSource {
+    message_id?: string;
+    msg_id?: string;
+    seq?: number;
+    rand?: number;
+    time?: number;
+    user_id?: number;
+    group_id?: number;
+    raw_message?: string;
+    /** 元素数组，或 NT 推送的纯文本摘要 */
+    message?: IcqqMessageElement[] | string;
+    sender?: {
+        user_id?: number;
+        nickname?: string;
+        card?: string;
+    };
+    [key: string]: unknown;
+}
+export type IcqqMessageElement = {
+    type: string;
+    text?: string;
+    qq?: string | number;
+    user_id?: string | number;
+    id?: string | number;
+    url?: string;
+    file?: string;
+    [key: string]: unknown;
+};
+/** 归一化后供适配器使用的入站消息 */
+export interface NormalizedIcqqInbound {
+    messageId: string;
+    idSource: "message_id" | "msg_id" | "seq" | "synthetic";
+    channelType: "group" | "private";
+    channelId: string;
+    /** 群临时会话：来源群号 */
+    channelParentGroupId?: string;
+    userId: string;
+    nickname: string;
+    /** 群聊时来自 IPC sender.role（私聊无） */
+    senderRole?: GroupRole;
+    content: MessageSegment[];
+    rawMessage: string;
+    timestampMs: number;
+    raw: IcqqIpcMessageEvent;
+}
+/** 从 IPC sender.role 解析群成员角色（供 Message.$sender → resolveSenderRoles） */
+export declare function parseIcqqSenderGroupRole(sender: {
+    role?: unknown;
+} | undefined): GroupRole | undefined;
+/**
+ * 判断入站消息是否 @ 了本机账号（uin = endpoint 配置 name，即 QQ 号）。
+ * 新 Plugin Runtime 的 Message.content 为纯文本，at 信息只能经 metadata 传递，
+ * endpoint 在 admit 时用本函数标注 `metadata.mentioned`（供 Agent Host 的 @ 触发）。
+ */
+export declare function isIcqqBotMentioned(input: {
+    readonly uin: string;
+    readonly content?: readonly MessageSegment[] | null;
+    readonly rawMessage?: string;
+}): boolean;
+/** 从 IPC 事件壳中取出 OneBot/icqq 载荷（兼容 data 嵌套或字段在根级） */
+export declare function unwrapIcqqIpcEventPayload(event: {
+    data?: unknown;
+    [key: string]: unknown;
+}): unknown;
+export declare function resolveIcqqInboundUserId(data: Record<string, unknown>): number | undefined;
+export declare function isIcqqMessagePostType(data: unknown): data is IcqqIpcMessageEvent;
+export declare function shouldSkipSelfInboundMessage(data: IcqqIpcMessageEvent): boolean;
+/** 群临时会话私聊：icqq message_type=private & sub_type=group */
+export declare function isIcqqGroupTempPrivateMessage(data: IcqqIpcMessageEvent): boolean;
+export declare function resolveChannelFromIcqqMessage(data: IcqqIpcMessageEvent): {
+    channelType: "group" | "private";
+    channelId: string;
+    channelParentGroupId?: string;
+};
+export declare function resolveIcqqInboundMessageId(data: IcqqIpcMessageEvent, channelId: string): {
+    id: string;
+    source: "message_id" | "msg_id" | "seq" | "synthetic";
+};
+export declare function icqqElementsToSegments(elements: IcqqMessageElement[] | undefined): MessageSegment[] | null;
+/** IPC 载荷可能把 source 嵌在 data / event 等字段，深度查找 */
+export declare function findIcqqNestedMessageSource(root: unknown, maxDepth?: number): IcqqMessageSource | undefined;
+/** 从 oicq MessageEvent.source 解析被引用消息的 message_id */
+export declare function resolveQuoteIdFromIcqqSource(source: unknown): string | undefined;
+/** 将 source 转为 QuotedMessagePayload（供 $getMsg 缓存，避免重复拉取） */
+export declare function quotedPayloadFromIcqqSource(source: unknown): QuotedMessagePayload | null;
+/** 从 IPC 事件顶层字段解析引用 message_id（与 message 段互补） */
+export declare function resolveIcqqQuoteIdFromEvent(data: IcqqIpcMessageEvent): string | undefined;
+export declare function resolveInboundContent(data: IcqqIpcMessageEvent): MessageSegment[];
+export declare function normalizeIcqqInboundMessage(data: IcqqIpcMessageEvent): NormalizedIcqqInbound | null;
+/** 按 message_id 去重（多路 subscribe 会收到同一消息多次） */
+export declare class InboundMessageDeduper {
+    private readonly seen;
+    shouldProcess(messageId: string): boolean;
+    clear(): void;
+}

package/lib/{src/icqq-inbound.js → icqq-inbound.js}

@@ -1,9 +1,8 @@
 /**
  * icqq 守护进程 IPC 入站事件归一化（post_type / message_type / message 段）
  */
-import { Message } from "zhin.js";
+import { Message, toCanonicalSegments } from "zhin.js";
 import { parseCqMessage } from "./cq-message.js";
-import { toCanonicalSegments } from "./segment-mapper.js";
 import { extractForwardResidFromJsonElement } from "./forward-msg.js";
 const DEDUPE_TTL_MS = 120_000;
 const ICQQ_GROUP_ROLES = new Set(["owner", "admin", "member"]);
@@ -15,6 +14,32 @@ export function parseIcqqSenderGroupRole(sender) {
     const role = raw.trim().toLowerCase();
     return ICQQ_GROUP_ROLES.has(role) ? role : undefined;
 }
+/**
+ * 判断入站消息是否 @ 了本机账号（uin = endpoint 配置 name，即 QQ 号）。
+ * 新 Plugin Runtime 的 Message.content 为纯文本，at 信息只能经 metadata 传递，
+ * endpoint 在 admit 时用本函数标注 `metadata.mentioned`（供 Agent Host 的 @ 触发）。
+ */
+export function isIcqqBotMentioned(input) {
+    const uin = String(input.uin ?? "").trim();
+    if (!uin)
+        return false;
+    for (const seg of input.content ?? []) {
+        if (!seg || (seg.type !== "at" && seg.type !== "mention"))
+            continue;
+        const data = (seg.data ?? {});
+        const target = String(data.qq ?? data.user_id ?? data.id ?? data.target ?? "").trim();
+        if (target && target !== "all" && Number(target) === Number(uin)) {
+            return true;
+        }
+    }
+    const raw = input.rawMessage ?? "";
+    if (!raw)
+        return false;
+    const escaped = uin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // OneBot CQ 码 `[CQ:at,qq=uin]`；QQ 频道 markdown `<@!uin>`
+    return new RegExp(`\\[CQ:at,qq=${escaped}\\]`, "u").test(raw)
+        || new RegExp(`<@!?${escaped}>`, "u").test(raw);
+}
 const MESSAGE_POST_TYPES = new Set(["message"]);
 function isMessagePostType(postType) {
     if (typeof postType !== "string" || postType === "")
@@ -538,4 +563,3 @@ export class InboundMessageDeduper {
         this.seen.clear();
     }
 }
-//# sourceMappingURL=icqq-inbound.js.map

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/index.d.ts

@@ -0,0 +1,6 @@
+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 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';
+export { resolveIcqqInboundMessageId, } from './icqq-inbound.js';

package/lib/index.js

@@ -0,0 +1,6 @@
+export { Actions, formatInboundContent, formatInboundTarget, formatOutboundBody, parseSendTarget, resolveIcqqConfig, } from './protocol.js';
+export { IcqqIpcEndpoint, } from './endpoint.js';
+export * from './types.js';
+export { getIcqqAgentDeps, registerIcqqAgentEndpoint, setIcqqAgentDeps, } from './icqq-agent-deps.js';
+export { IpcClient } from './ipc-client.js';
+export { resolveIcqqInboundMessageId, } from './icqq-inbound.js';

package/lib/ipc-client.d.ts

@@ -0,0 +1,73 @@
+import type { IpcResponse, IpcEvent } from "./protocol.js";
+export declare class IpcClient {
+    private socket;
+    private buffer;
+    private pending;
+    private eventHandlers;
+    private _closed;
+    /** 是否为客户端主动 close()（与对端断线区分） */
+    private _userClosed;
+    private _remoteDisconnectEmitted;
+    private onRemoteDisconnect;
+    private constructor();
+    get closed(): boolean;
+    /**
+     * 注册「对端断开 / 连接异常关闭」回调（不含本端 close()）。
+     * 传入 null 可清除回调。
+     */
+    setOnRemoteDisconnect(handler: (() => void) | null): void;
+    /** 注册数据处理 handler（RPC 模式延迟到 challenge 完成后调用） */
+    private attachDataHandler;
+    /**
+     * 通过 IPC（Unix Socket）连接守护进程并完成认证。
+     * @param uin - 目标账号的 QQ 号
+     * @returns 已认证的 IpcClient 实例
+     * @throws 守护进程未运行或认证失败时抛出错误
+     */
+    static connect(uin: number): Promise<IpcClient>;
+    /**
+     * 通过 RPC（TCP）连接守护进程并完成 HMAC 挑战-响应认证。
+     *
+     * 流程：
+     *   1. 服务端连接后发送 { challenge: "<hex>" }
+     *   2. 客户端用 HMAC-SHA256(token, challenge) 生成 digest
+     *   3. 客户端发送 { action: "auth", params: { digest: "<hex>" } }
+     *   4. 服务端验证 digest，通过则认证成功
+     *
+     * token 不会明文传输，防止中间人嗅探。
+     *
+     * @param options.host - 远程主机地址
+     * @param options.port - 远程端口
+     * @param options.token - 认证 token（用于 HMAC 计算，不会明文传输）
+     */
+    static connectRpc(options: {
+        host: string;
+        port: number;
+        token: string;
+    }): Promise<IpcClient>;
+    /**
+     * 通过 RPC 连接守护进程（自动从 daemon.rpc 文件读取地址）。
+     * @param uin - 目标账号的 QQ 号
+     */
+    static connectRpcByUin(uin: number): Promise<IpcClient>;
+    private onData;
+    /**
+     * 注册 icqq 事件回调。
+     * 新版守护进程在认证后会自动广播事件（event.id = "*"）。
+     */
+    onEvent(onEvent: (event: IpcEvent) => void): () => void;
+    /**
+     * 发送 IPC 请求并等待响应。
+     */
+    request(action: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<IpcResponse>;
+    /**
+     * @deprecated 兼容旧调用方式：服务端已自动推送事件，type/id 过滤在客户端完成。
+     * @returns 订阅句柄，包含 unsubscribe() 方法
+     */
+    subscribe(_action: string, params: Record<string, unknown>, onEvent: (event: IpcEvent) => void): {
+        id: string;
+        unsubscribe: () => Promise<void>;
+    };
+    /** 关闭连接 */
+    close(): void;
+}

package/lib/{src/ipc-client.js → ipc-client.js}

@@ -356,4 +356,3 @@ export class IpcClient {
         this.socket.destroy();
     }
 }
-//# sourceMappingURL=ipc-client.js.map

package/lib/outbound-media.d.ts

@@ -0,0 +1,13 @@
+import type { SendContent } from "zhin.js";
+import type { IcqqEndpointConfig } from "./types.js";
+export type IcqqOutboundMediaMode = "file" | "base64";
+/**
+ * 出站媒体模式：file=本机落盘后 CQ [image:path]（与 icqq 同机时可用）；
+ * base64=保留 segment.base64，CQ 编码为 [image:base64://...] 经 IPC 交给守护进程解码（异机 RPC 默认）。
+ */
+export declare function resolveIcqqOutboundMediaMode(config: Pick<IcqqEndpointConfig, "rpc" | "outboundMedia">): IcqqOutboundMediaMode;
+/**
+ * file 模式：将 segment.data.base64 物化为本机路径。
+ * base64 模式：不改动（由 toCqString 生成 base64://，供异机守护进程读取）。
+ */
+export declare function materializeOutboundBase64(content: SendContent, mode?: IcqqOutboundMediaMode): SendContent;

package/lib/{src/outbound-media.js → outbound-media.js}

@@ -63,4 +63,3 @@ export function materializeOutboundBase64(content, mode = "file") {
         return seg;
     });
 }
-//# sourceMappingURL=outbound-media.js.map