@zhin.js/adapter-icqq 6.0.2 → 6.0.3

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,47 @@
+/**
+ * ICQQ guild (QQ 频道) catalog sync, inbound normalize, Console channel list.
+ */
+import { type MessageSegment } from "zhin.js";
+import { type IpcGuildMessageEventData } from "./protocol.js";
+import type { IpcClient } from "./ipc-client.js";
+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: IpcClient): 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/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 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

package/lib/protocol.d.ts

@@ -0,0 +1,269 @@
+/**
+ * IPC 协议类型定义与 Action 常量 (ported from @icqqjs/cli)
+ *
+ * CLI 与守护进程通过 Unix Domain Socket 通信，
+ * 使用 JSON + 换行符（\n）分隔的文本协议。
+ *
+ * 通信流程（@icqqjs/cli `src/daemon/protocol.ts`）：
+ * 1. CLI 连接 Socket → auth（token）
+ * 2. 认证通过后发送 IpcRequest → 等待 IpcResponse
+ * 3. 认证通过后自动接收 icqq 事件推送（IpcEvent），断开连接自动停止
+ *
+ * 登录相关：**推送**走 IpcEvent（`system.login.*`）。
+ */
+/** CLI → Daemon 请求 */
+export type IpcRequest = {
+    id: string;
+    action: string;
+    params: Record<string, unknown>;
+};
+/** Daemon → CLI 响应 */
+export type IpcResponse = {
+    id: string;
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+};
+/**
+ * Daemon → CLI 事件推送（icqq client.em 分发的全部事件）
+ *
+ * 登录/重连时推送 `system.login.*`（如 `system.login.auth` 含 url + device），
+ * 语义在 `event` 字段，不在 OneBot 式 `post_type` 里。
+ */
+export type IpcEvent = {
+    /** 固定为 `"*"`，客户端应忽略，由本地 handler 按 `event` 过滤 */
+    id: string;
+    /** icqq 事件名，如 `system.login.auth`、`message.group.normal` */
+    event: string;
+    /** icqq 事件 toJSON 后的 plain object */
+    data: unknown;
+};
+export type IpcMessage = IpcResponse | IpcEvent;
+export type { IcqqIpcMessageEvent } from "./icqq-inbound.js";
+/** 从 IPC 入站 payload 解析可用于引用/撤回的消息 ID */
+export { resolveIcqqInboundMessageId } from "./icqq-inbound.js";
+/** Guild 消息事件数据 */
+export interface IpcGuildMessageEventData {
+    type: "guild";
+    guild_id: string;
+    guild_name: string;
+    channel_id: string;
+    channel_name: string;
+    nickname: string;
+    tiny_id: string;
+    raw_message: string;
+    time: number;
+    seq: number;
+}
+/**
+ * 所有 IPC 操作常量 (from @icqqjs/cli)
+ */
+export declare const Actions: {
+    readonly PING: "ping";
+    readonly LOGOUT: "logout";
+    readonly LIST_FRIENDS: "list_friends";
+    readonly LIST_GROUPS: "list_groups";
+    readonly LIST_GROUP_MEMBERS: "list_group_members";
+    readonly LIST_BLACKLIST: "list_blacklist";
+    readonly LIST_FRIEND_CLASSES: "list_friend_classes";
+    readonly GET_FRIEND_INFO: "get_friend_info";
+    readonly GET_GROUP_INFO: "get_group_info";
+    readonly GET_GROUP_MEMBER_INFO: "get_group_member_info";
+    readonly GET_STRANGER_INFO: "get_stranger_info";
+    readonly LIST_STRANGERS: "list_strangers";
+    readonly GET_PROFILE: "get_profile";
+    readonly GET_STATUS: "get_status";
+    readonly GET_ONLINE_STATUS: "get_online_status";
+    readonly GET_SELF_PROFILE: "get_self_profile";
+    readonly SEND_PRIVATE_MSG: "send_private_msg";
+    readonly SEND_GROUP_MSG: "send_group_msg";
+    readonly RECALL_MSG: "recall_msg";
+    readonly GET_MSG: "get_msg";
+    readonly HISTORY_PRIVATE: "history_private";
+    readonly HISTORY_GROUP: "history_group";
+    readonly HISTORY_BY_MSG_ID: "history_by_msg_id";
+    readonly SEND_LONG_MSG: "send_long_msg";
+    readonly MARK_READ: "mark_read";
+    readonly DELETE_MSG: "delete_msg";
+    readonly SET_NICKNAME: "set_nickname";
+    readonly SET_GENDER: "set_gender";
+    readonly SET_BIRTHDAY: "set_birthday";
+    readonly SET_SIGNATURE: "set_signature";
+    readonly SET_DESCRIPTION: "set_description";
+    readonly SET_AVATAR: "set_avatar";
+    readonly SET_ONLINE_STATUS: "set_online_status";
+    readonly SET_GROUP_NAME: "set_group_name";
+    readonly SET_GROUP_AVATAR: "set_group_avatar";
+    readonly SET_GROUP_CARD: "set_group_card";
+    readonly SET_GROUP_TITLE: "set_group_title";
+    readonly SET_GROUP_ADMIN: "set_group_admin";
+    readonly SET_GROUP_REMARK: "set_group_remark";
+    readonly GROUP_MUTE: "group_mute";
+    readonly GROUP_MUTE_ALL: "group_mute_all";
+    readonly GROUP_KICK: "group_kick";
+    readonly GROUP_QUIT: "group_quit";
+    readonly GROUP_INVITE: "group_invite";
+    readonly GROUP_POKE: "group_poke";
+    readonly GROUP_ANNOUNCE: "group_announce";
+    readonly GROUP_SIGN: "group_sign";
+    readonly GROUP_ESSENCE_ADD: "group_essence_add";
+    readonly GROUP_ESSENCE_REMOVE: "group_essence_remove";
+    readonly GROUP_ALLOW_ANONY: "group_allow_anony";
+    readonly GROUP_MUTED_LIST: "group_muted_list";
+    readonly GROUP_AT_ALL_REMAIN: "group_at_all_remain";
+    readonly FRIEND_POKE: "friend_poke";
+    readonly FRIEND_LIKE: "friend_like";
+    readonly FRIEND_DELETE: "friend_delete";
+    readonly FRIEND_REMARK: "friend_remark";
+    readonly FRIEND_CLASS: "friend_class";
+    readonly GET_SYSTEM_MSG: "get_system_msg";
+    readonly HANDLE_FRIEND_REQUEST: "handle_friend_request";
+    readonly HANDLE_GROUP_REQUEST: "handle_group_request";
+    readonly ADD_FRIEND_CLASS: "add_friend_class";
+    readonly DELETE_FRIEND_CLASS: "delete_friend_class";
+    readonly RENAME_FRIEND_CLASS: "rename_friend_class";
+    readonly GFS_LIST: "gfs_list";
+    readonly GFS_INFO: "gfs_info";
+    readonly GFS_MKDIR: "gfs_mkdir";
+    readonly GFS_DELETE: "gfs_delete";
+    readonly GFS_RENAME: "gfs_rename";
+    readonly GFS_STAT: "gfs_stat";
+    readonly GFS_MOVE: "gfs_move";
+    readonly GFS_DOWNLOAD: "gfs_download";
+    readonly IMAGE_OCR: "image_ocr";
+    readonly RELOAD_FRIEND_LIST: "reload_friend_list";
+    readonly RELOAD_GROUP_LIST: "reload_group_list";
+    readonly CLEAN_CACHE: "clean_cache";
+    readonly GET_GROUP_SHARE: "get_group_share";
+    readonly GROUP_SET_JOIN_TYPE: "group_set_join_type";
+    readonly GROUP_SET_RATE_LIMIT: "group_set_rate_limit";
+    readonly GROUP_MUTE_ANONY: "group_mute_anony";
+    readonly GROUP_ANON_INFO: "group_anon_info";
+    readonly ADD_FRIEND: "add_friend";
+    readonly SEND_TEMP_MSG: "send_temp_msg";
+    readonly GET_ROAMING_STAMP: "get_roaming_stamp";
+    readonly DELETE_STAMP: "delete_stamp";
+    readonly SEND_PRIVATE_FILE: "send_private_file";
+    readonly SEND_GROUP_FILE: "send_group_file";
+    readonly FRIEND_RECALL_FILE: "friend_recall_file";
+    readonly FRIEND_FORWARD_FILE: "friend_forward_file";
+    readonly SEARCH_SAME_GROUP: "search_same_group";
+    readonly SEND_CONTACT_SHARE: "send_contact_share";
+    readonly GFS_UPLOAD: "gfs_upload";
+    readonly GROUP_SET_REACTION: "group_set_reaction";
+    readonly GROUP_DEL_REACTION: "group_del_reaction";
+    readonly GET_FORWARD_MSG: "get_forward_msg";
+    readonly MAKE_FORWARD_MSG: "make_forward_msg";
+    readonly GUILD_LIST: "guild_list";
+    readonly GUILD_INFO: "guild_info";
+    readonly GUILD_CHANNELS: "guild_channels";
+    readonly GET_CHANNEL_INFO: "get_channel_info";
+    readonly GUILD_MEMBERS: "guild_members";
+    readonly GUILD_SEND_MSG: "guild_send_msg";
+    readonly GUILD_RECALL_MSG: "guild_recall_msg";
+    readonly GET_FILE_INFO: "get_file_info";
+    readonly GET_FILE_URL: "get_file_url";
+    readonly GET_AVATAR_URL: "get_avatar_url";
+    readonly GET_GROUP_AVATAR_URL: "get_group_avatar_url";
+    readonly SET_SCREEN_MEMBER_MSG: "set_screen_member_msg";
+    readonly GFS_FORWARD: "gfs_forward";
+    readonly GFS_FORWARD_OFFLINE: "gfs_forward_offline";
+    readonly RELOAD_BLACKLIST: "reload_blacklist";
+    readonly RELOAD_STRANGER_LIST: "reload_stranger_list";
+    readonly RELOAD_GUILDS: "reload_guilds";
+    readonly GET_STATUS_INFO: "get_status_info";
+    readonly GET_CLIENT_KEY: "get_client_key";
+    readonly GET_PSKEY: "get_pskey";
+    readonly UID2UIN: "uid2uin";
+    readonly UID2UINS: "uid2uins";
+    readonly UIN2UID: "uin2uid";
+    readonly UIN2UIDS: "uin2uids";
+    readonly GET_COOKIES: "get_cookies";
+    readonly GET_CSRF_TOKEN: "get_csrf_token";
+    readonly REFRESH_NT_PIC_RKEY: "refresh_nt_pic_rkey";
+    readonly SEND_DISCUSS_MSG: "send_discuss_msg";
+    readonly GET_VIDEO_URL: "get_video_url";
+    readonly GET_ADD_FRIEND_SETTING: "get_add_friend_setting";
+    readonly GET_FORUM_URL: "get_forum_url";
+    readonly GUILD_CHANNEL_SHARE: "guild_channel_share";
+    readonly GET_PIC_URL: "get_pic_url";
+    readonly GET_PTT_URL: "get_ptt_url";
+    readonly SUBSCRIBE: "subscribe";
+    readonly UNSUBSCRIBE: "unsubscribe";
+    readonly SET_WEBHOOK: "set_webhook";
+    readonly GET_WEBHOOK: "get_webhook";
+    readonly SET_NOTIFY: "set_notify";
+    readonly GET_NOTIFY: "get_notify";
+};
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface IcqqAdapterConfig {
+    readonly name?: string;
+    readonly autoReconnect?: boolean;
+    readonly outboundMedia?: 'file' | 'base64';
+    readonly rpc?: {
+        readonly host?: string;
+        readonly port?: number;
+        readonly token?: string;
+    };
+    /** Transitional: legacy root `endpoints[]` with `context: icqq`. */
+    readonly endpoints?: ReadonlyArray<{
+        readonly context?: string;
+        readonly name?: string;
+        readonly autoReconnect?: boolean;
+        readonly outboundMedia?: 'file' | 'base64';
+        readonly rpc?: {
+            readonly host?: string;
+            readonly port?: number;
+            readonly token?: string;
+        };
+    }>;
+}
+export interface ResolvedIcqqConfig {
+    readonly context: 'icqq';
+    readonly name: string;
+    readonly autoReconnect: boolean;
+    readonly outboundMedia?: 'file' | 'base64';
+    readonly rpc?: {
+        readonly host: string;
+        readonly port: number;
+        readonly token: string;
+    };
+}
+export interface IcqqWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface IcqqInboundMessage {
+    readonly id: string;
+    readonly target: string;
+    readonly content: string;
+    readonly sender: string;
+    readonly channelType: 'private' | 'group' | 'channel';
+    readonly metadata?: Record<string, unknown>;
+}
+export type ParsedIcqqSendTarget = {
+    readonly kind: 'private';
+    readonly userId: number;
+} | {
+    readonly kind: 'group';
+    readonly groupId: number;
+} | {
+    readonly kind: 'temp';
+    readonly groupId: number;
+    readonly userId: number;
+} | {
+    readonly kind: 'channel';
+    readonly guildId: string;
+    readonly channelId: string;
+};
+export declare function resolveIcqqConfig(config?: IcqqAdapterConfig): ResolvedIcqqConfig;
+/** Gateway reply target: `private:uid` / `group:gid` / `temp:gid:uid` / `channel:guild:channel`. */
+export declare function formatInboundTarget(input: {
+    readonly channelType: 'private' | 'group' | 'channel';
+    readonly channelId: string;
+    readonly channelParentGroupId?: string;
+    readonly guildId?: string;
+}): string;
+export declare function parseSendTarget(target: string): ParsedIcqqSendTarget;
+export declare function formatOutboundBody(payload: unknown): string;
+export declare function formatInboundContent(rawMessage: string): string;