@zhin.js/adapter-icqq 1.0.71 → 1.1.2

package/lib/protocol.d.ts

@@ -0,0 +1,258 @@
+import type { Sendable } from '@icqqjs/icqq';
+import type { ConversationRef } from '@zhin.js/im-contract';
+import type { MessageSegment } from "zhin.js";
+export type ActionResult = {
+    id: string;
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+};
+export type { IcqqMessageEvent } from "./icqq-inbound.js";
+export { resolveIcqqInboundMessageId } from "./icqq-inbound.js";
+export interface GuildMessageEventData {
+    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;
+}
+/**
+ * 所有操作常量（@icqqjs/icqq）
+ */
+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";
+};
+/** One expanded ICQQ endpoint configuration produced by AdapterIndex. */
+export interface IcqqEndpointConfig {
+    readonly id: string;
+    readonly autoReconnect?: boolean;
+    readonly outboundMedia?: 'file' | 'base64';
+    readonly password?: string;
+    readonly platform?: number;
+    readonly ver?: string;
+    readonly dataDir?: string;
+    readonly signApiAddr?: string;
+    readonly ignoreSelf?: boolean;
+    readonly resend?: boolean;
+    readonly cacheGroupMember?: boolean;
+    readonly autoServer?: boolean;
+    readonly qqnt?: boolean;
+    readonly ntLogin?: boolean;
+}
+export interface ResolvedIcqqConfig {
+    readonly context: 'icqq';
+    readonly id: string;
+    readonly autoReconnect: boolean;
+    readonly outboundMedia?: 'file' | 'base64';
+    readonly password?: string;
+    readonly platform?: number;
+    readonly ver?: string;
+    readonly dataDir?: string;
+    readonly signApiAddr?: string;
+    readonly ignoreSelf?: boolean;
+    readonly resend?: boolean;
+    readonly cacheGroupMember?: boolean;
+    readonly autoServer?: boolean;
+    readonly qqnt?: boolean;
+    readonly ntLogin?: boolean;
+}
+export interface IcqqWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface IcqqInboundMessage {
+    readonly id: string;
+    readonly conversation: ConversationRef;
+    readonly content: string;
+    /**
+     * 结构化段视图（canonical Segment，经 toCanonicalSegments 归一）。
+     * 与 content（CQ 原文纯文本视图）同源，随 gateway.receive 上送。
+     */
+    readonly segments?: readonly MessageSegment[];
+    readonly sender: {
+        readonly id: string;
+        readonly name?: string;
+    };
+    readonly channelType: 'private' | 'group' | 'channel';
+    readonly metadata?: Record<string, unknown>;
+    readonly replyTo?: {
+        readonly id: string;
+    };
+}
+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: IcqqEndpointConfig): ResolvedIcqqConfig;
+/**
+ * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
+ * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
+ */
+export declare function icqqInboundConversation(endpointKey: string, input: {
+    readonly channelType: 'private' | 'group' | 'channel';
+    readonly channelId: string;
+    readonly channelParentGroupId?: string;
+    readonly guildId?: string;
+}): ConversationRef;
+/**
+ * 出站：从 ConversationRef 派生 action 路由。
+ * 群容器（parent kind 'group'）内的 private 会话即 ICQQ 群临时会话（temp）。
+ */
+export declare function icqqOutboundTarget(conversation: ConversationRef): ParsedIcqqSendTarget;
+/**
+ * Project canonical Zhin segments directly into the native ICQQ Sendable
+ * algebra. ICQQ's direct client does not parse Zhin's historical `[image:x]`
+ * notation; passing that notation would send it as literal text.
+ */
+export declare function formatOutboundBody(payload: unknown): Sendable;
+export declare function formatInboundContent(rawMessage: string): string;

package/lib/protocol.js

@@ -0,0 +1,422 @@
+import { resolveIcqqMediaFile } from "./cq-message.js";
+export { resolveIcqqInboundMessageId } from "./icqq-inbound.js";
+/**
+ * 所有操作常量（@icqqjs/icqq）
+ */
+export const Actions = {
+    PING: "ping",
+    LOGOUT: "logout",
+    // ── 列表查询 ──
+    LIST_FRIENDS: "list_friends",
+    LIST_GROUPS: "list_groups",
+    LIST_GROUP_MEMBERS: "list_group_members",
+    LIST_BLACKLIST: "list_blacklist",
+    LIST_FRIEND_CLASSES: "list_friend_classes",
+    // ── 信息查询 ──
+    GET_FRIEND_INFO: "get_friend_info",
+    GET_GROUP_INFO: "get_group_info",
+    GET_GROUP_MEMBER_INFO: "get_group_member_info",
+    GET_STRANGER_INFO: "get_stranger_info",
+    LIST_STRANGERS: "list_strangers",
+    GET_PROFILE: "get_profile",
+    GET_STATUS: "get_status",
+    GET_ONLINE_STATUS: "get_online_status",
+    GET_SELF_PROFILE: "get_self_profile",
+    // ── 消息发送 ──
+    SEND_PRIVATE_MSG: "send_private_msg",
+    SEND_GROUP_MSG: "send_group_msg",
+    // ── 消息操作 ──
+    RECALL_MSG: "recall_msg",
+    GET_MSG: "get_msg",
+    HISTORY_PRIVATE: "history_private",
+    HISTORY_GROUP: "history_group",
+    HISTORY_BY_MSG_ID: "history_by_msg_id",
+    SEND_LONG_MSG: "send_long_msg",
+    MARK_READ: "mark_read",
+    DELETE_MSG: "delete_msg",
+    // ── 个人设置 ──
+    SET_NICKNAME: "set_nickname",
+    SET_GENDER: "set_gender",
+    SET_BIRTHDAY: "set_birthday",
+    SET_SIGNATURE: "set_signature",
+    SET_DESCRIPTION: "set_description",
+    SET_AVATAR: "set_avatar",
+    SET_ONLINE_STATUS: "set_online_status",
+    // ── 群设置 ──
+    SET_GROUP_NAME: "set_group_name",
+    SET_GROUP_AVATAR: "set_group_avatar",
+    SET_GROUP_CARD: "set_group_card",
+    SET_GROUP_TITLE: "set_group_title",
+    SET_GROUP_ADMIN: "set_group_admin",
+    SET_GROUP_REMARK: "set_group_remark",
+    // ── 群管理 ──
+    GROUP_MUTE: "group_mute",
+    GROUP_MUTE_ALL: "group_mute_all",
+    GROUP_KICK: "group_kick",
+    GROUP_QUIT: "group_quit",
+    GROUP_INVITE: "group_invite",
+    GROUP_POKE: "group_poke",
+    GROUP_ANNOUNCE: "group_announce",
+    GROUP_SIGN: "group_sign",
+    GROUP_ESSENCE_ADD: "group_essence_add",
+    GROUP_ESSENCE_REMOVE: "group_essence_remove",
+    GROUP_ALLOW_ANONY: "group_allow_anony",
+    GROUP_MUTED_LIST: "group_muted_list",
+    GROUP_AT_ALL_REMAIN: "group_at_all_remain",
+    // ── 好友操作 ──
+    FRIEND_POKE: "friend_poke",
+    FRIEND_LIKE: "friend_like",
+    FRIEND_DELETE: "friend_delete",
+    FRIEND_REMARK: "friend_remark",
+    FRIEND_CLASS: "friend_class",
+    // ── 系统消息/请求 ──
+    GET_SYSTEM_MSG: "get_system_msg",
+    HANDLE_FRIEND_REQUEST: "handle_friend_request",
+    HANDLE_GROUP_REQUEST: "handle_group_request",
+    // ── 好友分组 ──
+    ADD_FRIEND_CLASS: "add_friend_class",
+    DELETE_FRIEND_CLASS: "delete_friend_class",
+    RENAME_FRIEND_CLASS: "rename_friend_class",
+    // ── 群文件系统 ──
+    GFS_LIST: "gfs_list",
+    GFS_INFO: "gfs_info",
+    GFS_MKDIR: "gfs_mkdir",
+    GFS_DELETE: "gfs_delete",
+    GFS_RENAME: "gfs_rename",
+    GFS_STAT: "gfs_stat",
+    GFS_MOVE: "gfs_move",
+    GFS_DOWNLOAD: "gfs_download",
+    // ── 其他功能 ──
+    IMAGE_OCR: "image_ocr",
+    RELOAD_FRIEND_LIST: "reload_friend_list",
+    RELOAD_GROUP_LIST: "reload_group_list",
+    CLEAN_CACHE: "clean_cache",
+    GET_GROUP_SHARE: "get_group_share",
+    // ── 群管理扩展 ──
+    GROUP_SET_JOIN_TYPE: "group_set_join_type",
+    GROUP_SET_RATE_LIMIT: "group_set_rate_limit",
+    GROUP_MUTE_ANONY: "group_mute_anony",
+    GROUP_ANON_INFO: "group_anon_info",
+    // ── 好友操作扩展 ──
+    ADD_FRIEND: "add_friend",
+    SEND_TEMP_MSG: "send_temp_msg",
+    // ── 漫游表情 ──
+    GET_ROAMING_STAMP: "get_roaming_stamp",
+    DELETE_STAMP: "delete_stamp",
+    // ── 文件传输 ──
+    SEND_PRIVATE_FILE: "send_private_file",
+    SEND_GROUP_FILE: "send_group_file",
+    FRIEND_RECALL_FILE: "friend_recall_file",
+    FRIEND_FORWARD_FILE: "friend_forward_file",
+    SEARCH_SAME_GROUP: "search_same_group",
+    SEND_CONTACT_SHARE: "send_contact_share",
+    GFS_UPLOAD: "gfs_upload",
+    // ── 群消息表态 ──
+    GROUP_SET_REACTION: "group_set_reaction",
+    GROUP_DEL_REACTION: "group_del_reaction",
+    // ── 转发消息 ──
+    GET_FORWARD_MSG: "get_forward_msg",
+    MAKE_FORWARD_MSG: "make_forward_msg",
+    // ── 频道系统 ──
+    GUILD_LIST: "guild_list",
+    GUILD_INFO: "guild_info",
+    GUILD_CHANNELS: "guild_channels",
+    GET_CHANNEL_INFO: "get_channel_info",
+    GUILD_MEMBERS: "guild_members",
+    GUILD_SEND_MSG: "guild_send_msg",
+    GUILD_RECALL_MSG: "guild_recall_msg",
+    // ── 用户文件操作 ──
+    GET_FILE_INFO: "get_file_info",
+    GET_FILE_URL: "get_file_url",
+    GET_AVATAR_URL: "get_avatar_url",
+    GET_GROUP_AVATAR_URL: "get_group_avatar_url",
+    // ── 屏蔽群成员消息 ──
+    SET_SCREEN_MEMBER_MSG: "set_screen_member_msg",
+    // ── 群文件转发 ──
+    GFS_FORWARD: "gfs_forward",
+    GFS_FORWARD_OFFLINE: "gfs_forward_offline",
+    // ── 重载列表 ──
+    RELOAD_BLACKLIST: "reload_blacklist",
+    RELOAD_STRANGER_LIST: "reload_stranger_list",
+    RELOAD_GUILDS: "reload_guilds",
+    // ── 在线状态查询 ──
+    GET_STATUS_INFO: "get_status_info",
+    // ── 密钥/工具 ──
+    GET_CLIENT_KEY: "get_client_key",
+    GET_PSKEY: "get_pskey",
+    UID2UIN: "uid2uin",
+    UID2UINS: "uid2uins",
+    UIN2UID: "uin2uid",
+    UIN2UIDS: "uin2uids",
+    GET_COOKIES: "get_cookies",
+    GET_CSRF_TOKEN: "get_csrf_token",
+    REFRESH_NT_PIC_RKEY: "refresh_nt_pic_rkey",
+    SEND_DISCUSS_MSG: "send_discuss_msg",
+    // ── 视频/加好友设置 ──
+    GET_VIDEO_URL: "get_video_url",
+    GET_ADD_FRIEND_SETTING: "get_add_friend_setting",
+    // ── 频道扩展 ──
+    GET_FORUM_URL: "get_forum_url",
+    GUILD_CHANNEL_SHARE: "guild_channel_share",
+    // ── 获取图片/语音 URL ──
+    GET_PIC_URL: "get_pic_url",
+    GET_PTT_URL: "get_ptt_url",
+    // ── 消息订阅 ──
+    SUBSCRIBE: "subscribe",
+    UNSUBSCRIBE: "unsubscribe",
+    // ── Webhook ──
+    SET_WEBHOOK: "set_webhook",
+    GET_WEBHOOK: "get_webhook",
+    // ── 系统通知 ──
+    SET_NOTIFY: "set_notify",
+    GET_NOTIFY: "get_notify",
+};
+export function resolveIcqqConfig(config) {
+    const id = typeof config.id === 'string' ? config.id.trim() : '';
+    if (!/^\d+$/.test(id)) {
+        throw new TypeError('ICQQ endpoint requires a numeric id (QQ uin)');
+    }
+    const autoReconnect = config.autoReconnect ?? true;
+    const outboundMedia = config.outboundMedia;
+    const password = config.password;
+    const platform = config.platform ?? 2;
+    const ver = config.ver ?? '9.1.70';
+    const dataDir = config.dataDir ?? `data/icqq/${id}`;
+    const signApiAddr = config.signApiAddr;
+    const ignoreSelf = config.ignoreSelf ?? true;
+    const resend = config.resend;
+    const cacheGroupMember = config.cacheGroupMember ?? true;
+    const autoServer = config.autoServer ?? true;
+    const qqnt = config.qqnt;
+    const ntLogin = config.ntLogin;
+    return {
+        context: 'icqq',
+        id,
+        autoReconnect,
+        ...(outboundMedia ? { outboundMedia } : {}),
+        ...(password ? { password } : {}),
+        ...(platform != null ? { platform: Number(platform) } : {}),
+        ...(ver ? { ver } : {}),
+        ...(dataDir ? { dataDir } : {}),
+        ...(signApiAddr ? { signApiAddr } : {}),
+        ...(ignoreSelf != null ? { ignoreSelf } : {}),
+        ...(resend != null ? { resend } : {}),
+        ...(cacheGroupMember != null ? { cacheGroupMember } : {}),
+        ...(autoServer != null ? { autoServer } : {}),
+        ...(qqnt != null ? { qqnt } : {}),
+        ...(ntLogin != null ? { ntLogin } : {}),
+    };
+}
+/**
+ * 入站归一化 → ConversationRef：群临时会话（temp）映射为群容器内的 private
+ * 会话（parent kind 'group'）；频道消息的所属 guild 进 `parent`（kind 'channel'）。
+ */
+export function icqqInboundConversation(endpointKey, input) {
+    const endpoint = { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey };
+    if (input.channelType === 'private' && input.channelParentGroupId) {
+        return {
+            endpoint,
+            kind: 'private',
+            id: input.channelId,
+            parent: { kind: 'group', id: input.channelParentGroupId },
+        };
+    }
+    if (input.channelType === 'channel' && input.guildId) {
+        return {
+            endpoint,
+            kind: 'channel',
+            id: input.channelId,
+            parent: { kind: 'channel', id: input.guildId },
+        };
+    }
+    return { endpoint, kind: input.channelType, id: input.channelId };
+}
+/**
+ * 出站：从 ConversationRef 派生 action 路由。
+ * 群容器（parent kind 'group'）内的 private 会话即 ICQQ 群临时会话（temp）。
+ */
+export function icqqOutboundTarget(conversation) {
+    if (conversation.kind === 'private' && conversation.parent?.kind === 'group') {
+        return {
+            kind: 'temp',
+            groupId: Number(conversation.parent.id),
+            userId: Number(conversation.id),
+        };
+    }
+    if (conversation.kind === 'private') {
+        return { kind: 'private', userId: Number(conversation.id) };
+    }
+    if (conversation.kind === 'group') {
+        return { kind: 'group', groupId: Number(conversation.id) };
+    }
+    const guildId = conversation.parent?.kind === 'channel' ? conversation.parent.id : undefined;
+    if (!guildId) {
+        throw new TypeError(`Invalid icqq channel conversation (missing guild parent): ${conversation.id}`);
+    }
+    return { kind: 'channel', guildId, channelId: conversation.id };
+}
+const ICQQ_STANDALONE_ELEMENTS = new Set([
+    'record',
+    'video',
+    'file',
+    'json',
+    'share',
+    'long_msg',
+]);
+/**
+ * Project canonical Zhin segments directly into the native ICQQ Sendable
+ * algebra. ICQQ's direct client does not parse Zhin's historical `[image:x]`
+ * notation; passing that notation would send it as literal text.
+ */
+export function formatOutboundBody(payload) {
+    if (typeof payload === 'string') {
+        const text = payload.trim();
+        return text || '\u200b';
+    }
+    if (payload == null)
+        return '\u200b';
+    if (!Array.isArray(payload)) {
+        // 单个段对象（非数组）按单元素数组处理，杜绝 String(object) → '[object Object]'
+        if (isWireSegment(payload)) {
+            return formatOutboundBody([payload]);
+        }
+        if (typeof payload === 'object' && payload !== null && 'text' in payload) {
+            const text = String(payload.text ?? '').trim();
+            return text || '\u200b';
+        }
+        const text = String(payload).trim();
+        return text || '\u200b';
+    }
+    const elements = payload.flatMap((seg) => {
+        if (typeof seg === 'string')
+            return seg;
+        const item = seg;
+        switch (item.type) {
+            case 'text':
+                return String(item.data?.text ?? '');
+            case 'at':
+            case 'mention': {
+                const target = item.data?.qq ?? item.data?.id ?? item.data?.target;
+                if (target === 'all')
+                    return { type: 'at', qq: 'all' };
+                const qq = Number(target);
+                if (!Number.isSafeInteger(qq) || qq <= 0) {
+                    throw new TypeError(`Invalid ICQQ mention target: ${String(target ?? '')}`);
+                }
+                return { type: 'at', qq };
+            }
+            case 'image': {
+                const arg = resolveIcqqMediaFile(item.data);
+                if (!arg)
+                    throw new TypeError('ICQQ image segment requires canonical data.media');
+                return { type: 'image', file: arg };
+            }
+            case 'face': {
+                const id = Number(item.data?.id);
+                if (!Number.isSafeInteger(id) || id < 0) {
+                    throw new TypeError(`Invalid ICQQ face id: ${String(item.data?.id ?? '')}`);
+                }
+                return { type: 'face', id };
+            }
+            case 'reply': {
+                const id = String(item.data?.message_id ?? item.data?.id ?? '').trim();
+                if (!id)
+                    throw new TypeError('ICQQ reply segment requires message_id');
+                return { type: 'reply', id };
+            }
+            case 'record':
+            case 'audio': {
+                const arg = resolveIcqqMediaFile(item.data);
+                if (!arg)
+                    throw new TypeError('ICQQ audio segment requires canonical data.media');
+                return { type: 'record', file: arg };
+            }
+            case 'video': {
+                const arg = resolveIcqqMediaFile(item.data);
+                if (!arg)
+                    throw new TypeError('ICQQ video segment requires canonical data.media');
+                return { type: 'video', file: arg };
+            }
+            case 'file': {
+                const arg = resolveIcqqMediaFile(item.data);
+                if (!arg)
+                    throw new TypeError('ICQQ file segment requires canonical data.media');
+                const name = String(item.data?.name ?? '').trim();
+                return { type: 'file', file: arg, ...(name ? { name } : {}) };
+            }
+            case 'dice':
+                return { type: 'dice' };
+            case 'rps':
+                return { type: 'rps' };
+            case 'forward': {
+                const resid = String(item.data?.forward_id ?? item.data?.resid ?? item.data?.id ?? '').trim();
+                if (!resid)
+                    throw new TypeError('ICQQ forward segment requires forward_id');
+                return { type: 'long_msg', resid };
+            }
+            case 'share':
+                return formatShare(item.data);
+            default: {
+                const text = item.data?.text;
+                if (typeof text === 'string' && text)
+                    return text;
+                throw new TypeError(`Unsupported ICQQ outbound segment: ${item.type}`);
+            }
+        }
+    }).filter((element) => typeof element !== 'string' || element.length > 0);
+    if (elements.length === 0)
+        return '\u200b';
+    const standalone = elements.find((element) => typeof element !== 'string' && ICQQ_STANDALONE_ELEMENTS.has(element.type));
+    if (standalone && elements.length !== 1) {
+        throw new TypeError(`ICQQ ${standalone.type} element must be sent as a standalone message`);
+    }
+    return elements.length === 1 ? elements[0] : elements;
+}
+export function formatInboundContent(rawMessage) {
+    return rawMessage;
+}
+/** 段对象判定：`{ type: string, data? }`（非数组 payload 的防御入口）。 */
+function isWireSegment(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.type === 'string';
+}
+function formatShare(data) {
+    if (!data)
+        throw new TypeError('ICQQ share segment requires data');
+    const config = data.config;
+    const title = String(data.title ?? '').trim();
+    const url = String(data.url ?? '').trim();
+    if (!title)
+        throw new TypeError('ICQQ share segment requires title');
+    if (!url)
+        throw new TypeError('ICQQ share segment requires url');
+    const optionalString = (value) => {
+        const text = String(value ?? '').trim();
+        return text || undefined;
+    };
+    const appid = Number(config?.appid);
+    const appname = optionalString(config?.package);
+    const appsign = optionalString(config?.sign);
+    const shareConfig = Number.isSafeInteger(appid) && appid > 0
+        ? {
+            appid,
+            ...(appname ? { appname } : {}),
+            ...(appsign ? { appsign } : {}),
+        }
+        : undefined;
+    const summary = optionalString(data.artist);
+    const content = optionalString(data.content);
+    const image = optionalString(data.image);
+    const audio = optionalString(data.audio);
+    return {
+        type: 'share',
+        title,
+        url,
+        ...(summary ? { summary } : {}),
+        ...(content ? { content } : {}),
+        ...(image ? { image } : {}),
+        ...(audio ? { audio } : {}),
+        ...(shareConfig ? { config: shareConfig } : {}),
+    };
+}