@napuketto/kernel 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,2252 @@
+import pino from "pino";
+//#region src/types/entities.d.ts
+/**
+ * 实体类型层（运行时探测产物 + 公开资料作说明书，ADR-006）
+ *
+ * ⚠️ 部分字段按公开资料（wrapper 外部契约）自研描述，待下一次进程内
+ * 探测（probe.ts）校准——接口签名是外部系统事实，自研描述其形状。
+ */
+/** 会话类型（QQ wrapper 外部契约）。 */
+declare const ChatType: {
+  readonly C2C: 1;
+  readonly GROUP: 2;
+  readonly DISC: 3;
+  readonly GUILD: 4;
+  readonly C2C_TEMP: 100;
+};
+type ChatType = (typeof ChatType)[keyof typeof ChatType];
+/** 会话对象（peer 目标：群号 / 用户 uid）。 */
+interface Peer {
+  chatType: ChatType;
+  peerUid: string;
+  guildId?: string;
+}
+/** 文本元素（at 用 atType + atUid 表达）。 */
+interface TextElement {
+  content: string;
+  atType?: number;
+  atUid?: string;
+}
+/** 图片元素（发送时 picPath 必须；接收含 url）。 */
+interface PicElement {
+  picPath?: string;
+  picUrl?: string;
+  picType?: number;
+  picWidth?: number;
+  picHeight?: number;
+  md5?: string;
+  fileName?: string;
+  sourcePath?: string;
+  thumbPath?: string;
+}
+/** 语音元素（silk）。 */
+interface PttElement {
+  filePath?: string;
+  md5?: string;
+  fileName?: string;
+  duration?: number;
+  /** 语音转文字结果（translatePtt2Text 异步写回）。 */
+  text?: string;
+}
+/** 表情元素。 */
+interface FaceElement {
+  faceIndex: number;
+  faceType?: number;
+}
+/** 回复元素（引用消息）。 */
+interface ReplyElement {
+  replayMsgId: string;
+  replayMsgSeq?: string;
+  replayMsgTime?: string;
+  senderUid?: string;
+  senderUin?: string;
+}
+/** 视频元素。 */
+interface VideoElement {
+  filePath?: string;
+  videoUrl?: string;
+  fileName?: string;
+  fileSize?: string;
+}
+/** 文件元素。 */
+interface FileElement {
+  filePath?: string;
+  fileName?: string;
+  fileSize?: string;
+  fileUuid?: string;
+}
+/** 灰色提示子类型（系统事件类型，QQ wrapper 契约）。 */
+declare const GrayTipSubType: {
+  readonly REVOKE: 1;
+  readonly PROCLAMATION: 2;
+  readonly GROUP: 4;
+  readonly BUDDY: 5;
+  readonly FEED: 6;
+  readonly ESSENCE: 7;
+  readonly GROUP_NOTIFY: 8;
+  readonly BUDDY_NOTIFY: 9;
+  readonly FILE: 10;
+  readonly JSON: 17;
+};
+type GrayTipSubType = (typeof GrayTipSubType)[keyof typeof GrayTipSubType];
+/** 群成员变动类型（TipGroupElement.type）。 */
+declare const TipGroupElementType: {
+  readonly MEMBER_ADD: 1;
+  readonly DISBANDED: 2;
+  readonly QUIT: 3;
+  readonly CREATED: 4;
+  readonly GROUP_NAME_MODIFIED: 5;
+  readonly BLOCK: 6;
+  readonly UNBLOCK: 7;
+  readonly SHUT_UP: 8;
+};
+type TipGroupElementType = (typeof TipGroupElementType)[keyof typeof TipGroupElementType];
+/** 撤回元素（revokeElement）。 */
+interface GrayTipRevokeElement {
+  operatorUid: string;
+  operatorNick?: string;
+  operatorRole?: string;
+  isSelfOperate?: boolean;
+  wording?: string;
+}
+/** AIOP 操作元素（戳一戳等，aioOpGrayTipElement）。 */
+interface TipAioOpGrayTipElement {
+  operateType?: number;
+  peerUid?: string;
+  fromGrpCodeOfTmpChat?: string;
+}
+/** 群成员变动元素（groupElement 内的 TipGroupElement）。 */
+interface TipGroupElement {
+  type?: TipGroupElementType;
+  groupName?: string;
+  memberUid?: string;
+  memberNick?: string;
+  memberRemark?: string;
+  adminUid?: string;
+  adminNick?: string;
+  adminRemark?: string;
+  shutUp?: {
+    curTime?: string;
+    duration?: string;
+    admin?: {
+      uid?: string;
+      card?: string;
+      name?: string;
+      role?: number;
+    };
+    member?: {
+      uid?: string;
+      card?: string;
+      name?: string;
+      role?: number;
+    };
+  };
+}
+/** 灰色提示元素（elementType=8，系统事件载体）。 */
+interface GrayTipElement {
+  subElementType?: GrayTipSubType;
+  revokeElement?: GrayTipRevokeElement;
+  groupElement?: TipGroupElement;
+  aioOpGrayTipElement?: TipAioOpGrayTipElement;
+  xmlElement?: {
+    busiId?: string;
+    content?: string;
+    templId?: string;
+  };
+  jsonGrayTipElement?: {
+    busiId?: string;
+    jsonStr?: string;
+  };
+}
+/** 消息元素（RawMessage.elements 成员，elementType + 子元素互斥）。 */
+interface RawElement {
+  elementType: number;
+  elementId?: string;
+  textElement?: TextElement;
+  picElement?: PicElement;
+  pttElement?: PttElement;
+  faceElement?: FaceElement;
+  replyElement?: ReplyElement;
+  videoElement?: VideoElement;
+  fileElement?: FileElement;
+  grayTipElement?: GrayTipElement;
+  /** 合并转发元素（elementType=16 MULTI_FORWARD）。 */
+  multiForwardMsgElement?: {
+    resId: string;
+    fileName: string;
+    xmlContent: string;
+  };
+}
+/** QQ 消息（RawMessage，说明书参考字段，探测后校准）。 */
+interface RawMessage {
+  msgId: string;
+  msgSeq: string;
+  msgTime: string;
+  msgRandom?: string;
+  msgType: number;
+  chatType: ChatType;
+  peerUid: string;
+  peerUin: string;
+  senderUid: string;
+  senderUin: string;
+  peerName: string;
+  sendNickName: string;
+  sendMemberName?: string;
+  elements: RawElement[];
+  records?: RawMessage[];
+  guildId?: string;
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/types/services/msg-service.d.ts
+/** 原生通用返回：result 非 0 即失败（errMsg 附原因）。 */
+interface GeneralCallResult {
+  result: number;
+  errMsg: string;
+}
+/** 消息元素类型枚举（QQ wrapper 外部契约，自研描述）。 */
+declare const ElementType: {
+  readonly UNKNOWN: 0;
+  readonly TEXT: 1;
+  readonly PIC: 2;
+  readonly FILE: 3;
+  readonly PTT: 4;
+  readonly VIDEO: 5;
+  readonly FACE: 6;
+  readonly REPLY: 7;
+  readonly GRAY_TIP: 8;
+  readonly WALLET: 9;
+  readonly ARK: 10;
+  readonly MFACE: 11;
+  readonly LIVE_GIFT: 12;
+  readonly STRUCT_LONG_MSG: 13;
+  readonly MARKDOWN: 14;
+  readonly GIPHY: 15;
+  readonly MULTI_FORWARD: 16;
+  readonly INLINE_KEYBOARD: 17;
+  readonly INTEXT_GIFT: 18;
+  readonly CALENDAR: 19;
+};
+type ElementType = (typeof ElementType)[keyof typeof ElementType];
+/** 发送消息元素（session 发送用，elementType + 各子元素互斥）。 */
+interface SendMessageElement {
+  elementType: ElementType;
+  elementId?: string;
+  textElement?: TextElement;
+  faceElement?: FaceElement;
+  replyElement?: ReplyElement;
+  picElement?: PicElement;
+  pttElement?: PttElement;
+}
+/** 消息服务：apis/msg 用到的核心方法面。 */
+interface NodeIKernelMsgService {
+  addKernelMsgListener(listener: unknown): number;
+  removeKernelMsgListener(listenerId: number): void;
+  generateMsgUniqueId(chatType: number, time: string): string;
+  sendMsg(msgId: string, peer: Peer, elements: SendMessageElement[], map: Map<number, unknown>): Promise<GeneralCallResult>;
+  recallMsg(peer: Peer, msgIds: string[]): Promise<GeneralCallResult>;
+  getMsgs(peer: Peer, msgId: string, count: number, queryOrder: boolean): Promise<GeneralCallResult & {
+    msgList?: RawMessage[];
+  }>;
+  /** 按 msgId 批量拉取消息（get_msg / 精华消息 / ptt 转文字共用）。 */
+  getMsgsByMsgId(peer: Peer, ids: string[]): Promise<GeneralCallResult & {
+    msgList?: RawMessage[];
+  }>;
+  setMsgRead(peer: Peer): Promise<GeneralCallResult>;
+  /** 消息表情表态（set_msg_emoji_like；setOrCancel=true 点赞，false 取消）。 */
+  setMsgEmojiLikes(peer: Peer, msgSeq: string, emojiId: string, emojiType: string, setOrCancel: boolean): Promise<GeneralCallResult>;
+  /** 语音转文字（fetch_ptt_text；异步转写，结果写回 pttElement.text）。 */
+  translatePtt2Text(msgId: string, peer: Peer, msgElement: unknown): Promise<GeneralCallResult>;
+  /** 输入状态（set_input_status；eventType=1 输入中，0 停止）。 */
+  sendShowInputStatusReq(chatType: number, eventType: number, toUid: string): Promise<unknown>;
+  /** 合并转发组装（send_group/private_forward_msg；返回 MULTI_FORWARD 元素）。 */
+  buildMultiForwardMsg(req: {
+    srcMsgIds: string[];
+    srcContact: Peer;
+  }): Promise<GeneralCallResult & {
+    rspInfo?: {
+      elements?: SendMessageElement[];
+    };
+  }>;
+  /** 获取合并转发内容（get_forward_msg；resId 取自 multiForwardMsgElement）。 */
+  getMultiMsg(peer: Peer, msgId: string, resId: string): Promise<GeneralCallResult & {
+    msgList?: RawMessage[];
+  }>;
+  /** 单条转发（forward_group/friend_single_msg；msgIds 源、dstPeers 目标）。 */
+  forwardMsg(msgIds: string[], peer: Peer, dstPeers: Peer[], commentElements: unknown): Promise<GeneralCallResult>;
+  /** 设置在线状态（set_online_status；customStatus 为自定义状态）。 */
+  setStatus(args: {
+    status: number;
+    extStatus: number;
+    batteryStatus: number;
+    customStatus?: {
+      faceId: string;
+      wording: string;
+      faceType: string;
+    };
+  }): Promise<GeneralCallResult>;
+}
+//#endregion
+//#region src/types/services/buddy-service.d.ts
+/** 好友列表分类（getBuddyListV2 返回，说明书参考）。 */
+interface BuddyCategory {
+  categoryId: number;
+  categorySortId: number;
+  categroyName: string;
+  categroyMbCount: number;
+  onlineCount: number;
+  buddyUids: string[];
+}
+/** 好友申请（getBuddyReq 返回的 buddyReqs 成员，说明书参考，待探测校准）。 */
+interface BuddyReq {
+  reqTime: string;
+  friendUid: string;
+  friendNick?: string;
+  sourceId?: number;
+  sourceName?: string;
+  [key: string]: unknown;
+}
+/** 可疑好友申请（getDoubtBuddyReq 返回的 doubtList 成员，说明书参考）。 */
+interface DoubtBuddyReq {
+  uid: string;
+  nick?: string;
+  source?: string;
+  reason?: string;
+  msg?: string;
+  groupCode?: string;
+  reqTime?: string;
+  [key: string]: unknown;
+}
+/** 好友服务：apis/friend 用到的核心方法面。 */
+interface NodeIKernelBuddyService {
+  addKernelBuddyListener(listener: unknown): number;
+  removeKernelBuddyListener(listenerId: number): void;
+  getBuddyListV2(callFrom: string, isPullRefresh: boolean, reqType: number): Promise<GeneralCallResult & {
+    data: BuddyCategory[];
+  }>;
+  getBuddyListFromCache(reqType: number): Promise<BuddyCategory[]>;
+  getBuddyNick(uid: string): string;
+  getBuddyRemark(uid: string): string;
+  isBuddy(uid: string): boolean;
+  /** 好友申请列表（set_friend_add_request 应答前查找匹配项）。 */
+  getBuddyReq(): Promise<GeneralCallResult & {
+    buddyReqs?: BuddyReq[];
+  }>;
+  /** 同意/拒绝加好友请求（set_friend_add_request）。 */
+  approvalFriendRequest(arg: {
+    friendUid: string;
+    reqTime: string;
+    accept: boolean;
+  }): Promise<void>;
+  /** 设置好友备注（set_friend_remark；void 语义乐观处理）。 */
+  setBuddyRemark(param: {
+    uid: string;
+    remark: string;
+  }): void;
+  /** 删除好友（delete_friend）。 */
+  delBuddy(param: {
+    friendUid: string;
+    tempBlock: boolean;
+    tempBothDel: boolean;
+  }): Promise<unknown>;
+  /** 可疑好友申请列表（get_doubt_friends_add_request；reqId 作回执匹配）。 */
+  getDoubtBuddyReq(reqId: string, num: number, uk: string): Promise<GeneralCallResult & {
+    doubtList?: DoubtBuddyReq[];
+  }>;
+  /** 处理可疑好友申请（set_doubt_friends_add_request；str1/str2 语义未知，传空串）。 */
+  approvalDoubtBuddyReq(uid: string, str1: string, str2: string): void;
+}
+//#endregion
+//#region src/types/wrapper.d.ts
+/**
+ * wrapper.node 的 NAPI 接口面（自研描述，非移植）
+ *
+ * 来源：wrapper.node 在 QQ 定制版 Electron 里通过 napi_define_class / napi_set_named_property
+ * 注册的 JS 类（2026-08-05 Ghidra 反编译 FUN_180c6274a / FUN_180c80224 确认类名）。
+ * 这些接口是 wrapper.node 对外暴露的外部系统契约——我们自研描述其形状，未复制任何第三方代码。
+ *
+ * 注意：这里所有对象由 QQ 运行时的 NAPI 层自动构建/转换，业务层禁止触碰 C++ ABI。
+ */
+/** 平台类型（与 wrapper.node 的 platform 字段对应）。 */
+declare const PlatformType: {
+  readonly KUNKNOWN: 0;
+  readonly KANDROID: 1;
+  readonly KIOS: 2;
+  readonly KWINDOWS: 3;
+  readonly KMAC: 4;
+  readonly KLINUX: 5;
+};
+type PlatformType = (typeof PlatformType)[keyof typeof PlatformType];
+/** 厂商类型（deviceInfo.vendorType）。 */
+declare const VendorType: {
+  readonly KNOSETONIOS: 0;
+  readonly KUNSUPPORTANDROIDPUSH: 1;
+  readonly KSUPPORTTPNS: 2;
+  readonly KSUPPORTHMS: 3;
+  readonly KSUPPORTOPPOPUSH: 4;
+  readonly KSUPPORTVIVOPUSH: 5;
+  readonly KSUPPORTGOOGLEPUSH: 99;
+};
+type VendorType = (typeof VendorType)[keyof typeof VendorType];
+/** NodeQQNTWrapperUtil：通用工具类（静态服务）。 */
+interface NodeQQNTWrapperUtil {
+  get(): NodeQQNTWrapperUtil;
+  getNTUserDataInfoConfig(): string;
+  getFileSize(path: string): Promise<number>;
+  fileIsExist(path: string): unknown;
+  makeDirByPath(path: string): unknown;
+}
+/** engine 初始化配置（initWithDeskTopConfig 第一参，JS 对象直接传）。 */
+interface EnginInitDesktopConfig {
+  base_path_prefix: string;
+  platform_type: PlatformType;
+  app_type: 4;
+  app_version: string;
+  os_version: string;
+  use_xlog: boolean;
+  qua: string;
+  global_path_config: {
+    desktopGlobalPath: string;
+  };
+  thumb_config: {
+    maxSide: 324;
+    minSide: 48;
+    longLimit: 6;
+    density: 2;
+  };
+}
+/** NodeIQQNTWrapperEngine 实例方法。 */
+interface NodeIQQNTWrapperEngine {
+  initWithDeskTopConfig(config: EnginInitDesktopConfig, adapter: NodeIGlobalAdapter): void;
+  initWithMobileConfig(config: unknown, adapter: NodeIGlobalAdapter): void;
+  initLog(arg: unknown): void;
+  setLogLevel(arg: unknown): void;
+  onSendSSOReply(a: unknown, b: unknown, c: unknown, d: unknown, e: unknown): void;
+}
+/** NodeIQQNTWrapperEngine 构造器（含静态 get()）。 */
+type NodeIQQNTWrapperEngineCtor = new () => NodeIQQNTWrapperEngine & {
+  get(): NodeIQQNTWrapperEngine;
+};
+/** desktopPathConfig 结构。 */
+interface DesktopPathConfig {
+  account_path: string;
+}
+/** rdeliveryConfig 结构。 */
+interface RDeliveryConfig {
+  appKey: string;
+  systemId: number;
+  appId: string;
+  logicEnvironment: string;
+  platform: PlatformType;
+  language: string;
+  sdkVersion: string;
+  userId: string;
+  appVersion: string;
+  osVersion: string;
+  bundleId: string;
+  serverUrl: string;
+  fixedAfterHitKeys: string[];
+}
+/** deviceInfo 结构。 */
+interface DeviceInfo {
+  guid: string;
+  buildVer: string;
+  localId: number;
+  devName: string;
+  devType: string;
+  vendorName: string;
+  osVer: string;
+  vendorOsName: string;
+  setMute: boolean;
+  vendorType: VendorType;
+}
+/** session.init 的完整配置（JS 对象，NAPI 自动转换）。 */
+interface WrapperSessionInitConfig {
+  selfUin: string;
+  selfUid: string;
+  desktopPathConfig: DesktopPathConfig;
+  clientVer: string;
+  a2: string;
+  d2: string;
+  d2Key: string;
+  machineId: string;
+  platform: PlatformType;
+  platVer: string;
+  appid: string;
+  rdeliveryConfig: RDeliveryConfig;
+  defaultFileDownloadPath: string;
+  deviceInfo: DeviceInfo;
+  deviceConfig: string;
+}
+/** NodeIQQNTWrapperSession 构造器（含静态 get / getNTWrapperSession / create）。 */
+type NodeIQQNTWrapperSessionCtor = {
+  new (): NodeIQQNTWrapperSession;
+  get(): NodeIQQNTWrapperSession;
+  getNTWrapperSession(name: string): NodeIQQNTWrapperSession;
+  create(): NodeIQQNTWrapperSession;
+};
+/** NodeIQQNTWrapperSession：会话主入口（实例方法）。 */
+interface NodeIQQNTWrapperSession {
+  init(config: WrapperSessionInitConfig, depends: NodeIDependsAdapter, dispatcher: NodeIDispatcherAdapter, listener: NodeIKernelSessionListener): void;
+  startNT(sessionId?: number): void;
+  close(arg: unknown): void;
+  onLine(arg: unknown): void;
+  offLine(arg: unknown): void;
+  disableIpDirect(arg: unknown): void;
+  getAccountPath(arg: unknown): string;
+  updateTicket(arg: unknown): void;
+  getMsgService(): unknown;
+  getGroupService(): unknown;
+  getBuddyService(): unknown;
+  getTicketService(): unknown;
+  getRichMediaService(): unknown;
+  getProfileService(): unknown;
+  getProfileLikeService(): unknown;
+  getTipOffService(): unknown;
+}
+/** NodeIQQNTStartupSessionWrapper：启动会话实例方法。 */
+interface NodeIQQNTStartupSessionWrapper {
+  stop(): void;
+  start(): void;
+  createWithModuleList(uk: unknown): unknown;
+  getSessionIdList(): Promise<Map<unknown, unknown>>;
+}
+/** NodeIQQNTStartupSessionWrapper 构造器（含静态 create）。 */
+type NodeIQQNTStartupSessionWrapperCtor = new () => NodeIQQNTStartupSessionWrapper & {
+  create(): NodeIQQNTStartupSessionWrapper;
+};
+/** NodeIKernelLoginService 实例方法。 */
+interface NodeIKernelLoginService {
+  addKernelLoginListener(listener: unknown): number;
+  removeKernelLoginListener(listener: number): void;
+  initConfig(config: unknown): void;
+  connect(): void;
+  getLoginList(): Promise<{
+    result: number;
+    LocalLoginInfoList: unknown[];
+  }>;
+  quickLoginWithUin(uin: string): Promise<unknown>;
+  getQRCodePicture(): boolean;
+  getMsfStatus(): number;
+}
+/** NodeIKernelLoginService 构造器（含静态 get）。 */
+type NodeIKernelLoginServiceCtor = new () => NodeIKernelLoginService & {
+  get(): NodeIKernelLoginService;
+};
+/** NodeIO3MiscService：O3 杂项服务。 */
+interface NodeIO3MiscService {
+  get(): NodeIO3MiscService;
+  addO3MiscListener(listener: unknown): number;
+}
+interface NodeIGlobalAdapter {
+  onLog?(...args: unknown[]): void;
+  onGetSrvCalTime?(...args: unknown[]): void;
+  onShowErrUITips?(...args: unknown[]): void;
+  fixPicImgType?(...args: unknown[]): unknown;
+  getAppSetting?(...args: unknown[]): unknown;
+  onInstallFinished?(...args: unknown[]): void;
+  onUpdateGeneralFlag?(...args: unknown[]): void;
+  onGetOfflineMsg?(...args: unknown[]): void;
+}
+/** session.init 第二参：依赖回调（普通 JS 对象）。 */
+interface NodeIDependsAdapter {
+  onMSFStatusChange?(statusType: number, changeReasonType: number): void;
+  onMSFSsoError?(code: number, desc: string): void;
+  getGroupCode?(...args: unknown[]): unknown;
+}
+/** session.init 第三参：请求分发回调（普通 JS 对象）。 */
+interface NodeIDispatcherAdapter {
+  dispatchRequest?(arg: unknown): void;
+  dispatchCall?(arg: unknown): void;
+  dispatchCallWithJson?(arg: unknown): void;
+}
+/** 登录监听器接口（普通 JS 对象，传给 loginService.addKernelLoginListener）。自研描述。 */
+interface IKernelLoginListener {
+  onLoginConnected?(...args: unknown[]): void;
+  onLoginDisConnected?(...args: unknown[]): void;
+  onLoginConnecting?(...args: unknown[]): void;
+  onQRCodeGetPicture?(arg: {
+    pngBase64QrcodeData: string;
+    qrcodeUrl: string;
+  }): void;
+  onQRCodeLoginPollingStarted?(...args: unknown[]): void;
+  onQRCodeSessionUserScaned?(...args: unknown[]): void;
+  onQRCodeLoginSucceed?(loginResult: {
+    uid: string;
+    uin: string;
+    nick?: string;
+  }): void;
+  onQRCodeSessionFailed?(errType: number, errCode: number, errMsg: string): void;
+  onLoginFailed?(args: unknown): void;
+  onLogoutSucceed?(...args: unknown[]): void;
+  onLogoutFailed?(...args: unknown[]): void;
+  onUserLoggedIn?(userid: string): void;
+  onQRCodeSessionQuickLoginFailed?(...args: unknown[]): void;
+  onPasswordLoginFailed?(...args: unknown[]): void;
+  onQQLoginNumLimited?(...args: unknown[]): void;
+  onLoginState?(...args: unknown[]): void;
+}
+/**
+ * NodeIKernelSessionListener：session.init 第四参监听器（普通 JS 对象）。
+ * init 完成信号：以 onOpentelemetryInit(is_init===true) 为准（onSessionInitComplete 为辅）。
+ */
+interface NodeIKernelSessionListener {
+  onNTSessionCreate?(sessionId: string): void;
+  onGProSessionCreate?(sessionId: string): void;
+  onSessionInitComplete?(result: unknown): void;
+  onOpentelemetryInit?(info: {
+    is_init: boolean;
+    is_report: boolean;
+  }): void;
+  onUserOnlineResult?(result: unknown): void;
+  onGetSelfTinyId?(result: unknown): void;
+}
+/** wrapper.node 的 NAPI 顶层导出（module.exports）。 */
+interface WrapperNodeApi {
+  NodeIO3MiscService: NodeIO3MiscService;
+  NodeQQNTWrapperUtil: NodeQQNTWrapperUtil;
+  /** 构造器：`new wrapper.NodeIQQNTWrapperSession()`。 */
+  NodeIQQNTWrapperSession: NodeIQQNTWrapperSessionCtor;
+  NodeIQQNTStartupSessionWrapper: NodeIQQNTStartupSessionWrapperCtor;
+  /** 构造器：`new wrapper.NodeIQQNTWrapperEngine()`。 */
+  NodeIQQNTWrapperEngine: NodeIQQNTWrapperEngineCtor;
+  /** 构造器：`new wrapper.NodeIKernelLoginService()`。 */
+  NodeIKernelLoginService: NodeIKernelLoginServiceCtor;
+}
+//#endregion
+//#region src/apis/friend.d.ts
+/** 好友条目（uid + 昵称/备注，昵称由 buddy service 缓存补全）。 */
+interface Friend {
+  uid: string;
+  uin: string;
+  nickname: string;
+  remark: string;
+}
+/** 带分类的好友列表项（get_friends_with_category 返回）。 */
+interface FriendCategory {
+  categoryId: number;
+  categorySortId: number;
+  categoryName: string;
+  categoryMbCount: number;
+  onlineCount: number;
+  buddyList: Friend[];
+}
+/** 可疑好友申请（OB11 结构，get_doubt_friends_add_request 返回）。 */
+interface DoubtFriendRequestInfo {
+  flag: string;
+  uin: number;
+  nick?: string;
+  source?: string;
+  reason?: string;
+  msg?: string;
+  group_code?: string;
+  time?: string;
+  type: "doubt";
+}
+/** FriendApi 构造选项。 */
+interface FriendApiOptions {
+  /** uid→uin 转换器（通常注入 GroupApi.uidToUin）；缺省 uin 退化为 uid。 */
+  uidToUin?: (uids: string[]) => Promise<Map<string, string>>;
+}
+/** 好友 API：从 session 拿 buddy service，包装成语义化方法。 */
+declare class FriendApi {
+  private readonly service;
+  private readonly uidToUin;
+  constructor(session: NodeIQQNTWrapperSession, opts?: FriendApiOptions);
+  /** 好友列表（分类拍平为 Friend[]；昵称/备注从 service 缓存读取）。 */
+  getFriendList(): Promise<Friend[]>;
+  /** 带分类的好友列表（get_friends_with_category，分类保留）。 */
+  getFriendCategories(): Promise<FriendCategory[]>;
+  /** 原始分类（getBuddyListV2 / 缓存）。 */
+  private getBuddyCategories;
+  /** 判断是否好友。 */
+  isBuddy(uid: string): boolean;
+  /** 好友申请列表（set_friend_add_request 应答前查找匹配项）。 */
+  getBuddyReqList(): Promise<BuddyReq[]>;
+  /** 应答好友申请（accept=true 同意；remark 由调用方另行 setFriendRemark）。 */
+  handleFriendRequest(notify: BuddyReq, accept: boolean): Promise<void>;
+  /** 设置好友备注（void 语义乐观处理）。 */
+  setFriendRemark(uid: string, remark: string): void;
+  /** 删除好友（tempBlock=拉黑，tempBothDel=双向删除）。 */
+  deleteFriend(uid: string, tempBlock?: boolean, tempBothDel?: boolean): Promise<void>;
+  /** 可疑好友申请列表（get_doubt_friends_add_request；uin 经 uidToUin 转换）。 */
+  getDoubtFriendRequest(count: number): Promise<DoubtFriendRequestInfo[]>;
+  /** 单项转换：DoubtBuddyReq → OB11 结构（可选字段条件赋值，exactOptionalPropertyTypes）。 */
+  private toDoubtFriendRequestInfo;
+  /** 处理可疑好友申请（set_doubt_friends_add_request；uid=flag）。 */
+  handleDoubtFriendRequest(uid: string): void;
+}
+//#endregion
+//#region src/types/services/group-service.d.ts
+/** 群成员角色（QQ wrapper 契约）。 */
+declare const NTGroupMemberRole: {
+  readonly UNSPECIFIED: 0;
+  readonly STRANGER: 1;
+  readonly MEMBER: 2;
+  readonly ADMIN: 3;
+  readonly OWNER: 4;
+};
+type NTGroupMemberRole = (typeof NTGroupMemberRole)[keyof typeof NTGroupMemberRole];
+/** 踢人请求项（KickMemberV2Req.kickList 成员，说明书参考，字段值待探测校准）。 */
+interface KickMemberInfo {
+  optFlag: number;
+  optOperate: number;
+  optMemberUid: string;
+  optBytesMsg: string;
+}
+/** 踢人请求（set_group_kick 的 kickMemberV2 参数，说明书参考）。 */
+interface KickMemberV2Req {
+  groupCode: string;
+  kickFlag: number;
+  kickList: KickMemberInfo[];
+  kickListUids: string[];
+  kickMsg: string;
+}
+/** @all 剩余次数（getGroupRemainAtTimes 返回）。 */
+interface GroupRemainAtTimes {
+  canAtAll: boolean;
+  remainAtAllCountForUin: number;
+  remainAtAllCountForGroup: number;
+  atTimesMsg: string;
+  canNotAtAllMsg: string;
+}
+/** 群通知类型（GroupNotifyMsgType，说明书参考）。 */
+declare const GroupNotifyMsgType: {
+  readonly UN_SPECIFIED: 0;
+  readonly INVITED_BY_MEMBER: 1;
+  readonly REFUSE_INVITED: 2;
+  readonly REFUSED_BY_ADMINI_STRATOR: 3;
+  readonly AGREED_TOJOIN_DIRECT: 4;
+  readonly INVITED_NEED_ADMINI_STRATOR_PASS: 5;
+  readonly AGREED_TO_JOIN_BY_ADMINI_STRATOR: 6;
+  readonly REQUEST_JOIN_NEED_ADMINI_STRATOR_PASS: 7;
+  readonly SET_ADMIN: 8;
+  readonly KICK_MEMBER_NOTIFY_ADMIN: 9;
+  readonly KICK_MEMBER_NOTIFY_KICKED: 10;
+  readonly MEMBER_LEAVE_NOTIFY_ADMIN: 11;
+  readonly CANCEL_ADMIN_NOTIFY_CANCELED: 12;
+  readonly CANCEL_ADMIN_NOTIFY_ADMIN: 13;
+  readonly TRANSFER_GROUP_NOTIFY_OLDOWNER: 14;
+  readonly TRANSFER_GROUP_NOTIFY_ADMIN: 15;
+};
+type GroupNotifyMsgType = (typeof GroupNotifyMsgType)[keyof typeof GroupNotifyMsgType];
+/** 群通知处理状态（GroupNotifyMsgStatus，说明书参考）。 */
+declare const GroupNotifyMsgStatus: {
+  readonly KINIT: 0;
+  readonly KUNHANDLE: 1;
+  readonly KAGREED: 2;
+  readonly KREFUSED: 3;
+  readonly KIGNORED: 4;
+};
+type GroupNotifyMsgStatus = (typeof GroupNotifyMsgStatus)[keyof typeof GroupNotifyMsgStatus];
+/** 群请求操作类型（NTGroupRequestOperateTypes，说明书参考）。 */
+declare const NTGroupRequestOperateTypes: {
+  readonly KUNSPECIFIED: 0;
+  readonly KAGREE: 1;
+  readonly KREFUSE: 2;
+  readonly KIGNORE: 3;
+  readonly KDELETE: 4;
+};
+type NTGroupRequestOperateTypes = (typeof NTGroupRequestOperateTypes)[keyof typeof NTGroupRequestOperateTypes];
+/** 群通知（getSingleScreenNotifies 返回项，说明书参考，待探测校准）。 */
+interface GroupNotify {
+  seq: string;
+  type: GroupNotifyMsgType;
+  status: GroupNotifyMsgStatus;
+  group?: {
+    groupCode: string;
+    groupName: string;
+  };
+  user1?: {
+    uid: string;
+    nickName: string;
+  };
+  user2?: {
+    uid: string;
+    nickName: string;
+  };
+  actionTime?: string;
+  postscript?: string;
+  warningTips?: string;
+}
+/** 禁言成员（getGroupShutUpMemberList 返回项，说明书参考，待探测校准）。 */
+interface ShutUpGroupMember {
+  uid: string;
+  qid: string;
+  uin: string;
+  nick: string;
+  remark: string;
+  cardName: string;
+  shutUpTime: number;
+  memberSpecialTitle?: string;
+}
+/** 群列表项（Group 实体，说明书参考）。 */
+interface Group {
+  groupCode: string;
+  groupName: string;
+  memberCount: number;
+  maxMember: number;
+  remarkName?: string;
+  groupOwnerId?: {
+    memberUin: string;
+    memberUid: string;
+  };
+  memberRole?: number;
+  isTop?: boolean;
+  [key: string]: unknown;
+}
+/** 群详情（getGroupDetailInfo 返回，说明书参考）。 */
+interface GroupDetailInfo {
+  groupCode: string;
+  groupUin: string;
+  ownerUin: string;
+  ownerUid?: string;
+  groupName: string;
+  memberNum: number;
+  maxMemberNum: number;
+  remarkName?: string;
+  isTop?: boolean;
+  groupCreateTime?: number;
+  [key: string]: unknown;
+}
+/** 群成员（getAllMemberList result.infos 的 value，说明书参考）。 */
+interface GroupMember {
+  uid: string;
+  uin: string;
+  nick: string;
+  cardName: string;
+  remark: string;
+  role: NTGroupMemberRole;
+  shutUpTime: number;
+  joinTime: string;
+  lastSpeakTime: string;
+  memberSpecialTitle?: string;
+  sex?: number;
+  age?: number;
+  isRobot?: boolean;
+  [key: string]: unknown;
+}
+/** 群服务：apis/group 用到的核心方法面。 */
+interface NodeIKernelGroupService {
+  addKernelGroupListener(listener: unknown): number;
+  removeKernelGroupListener(listenerId: number): void;
+  getGroupList(force: boolean): Promise<GeneralCallResult>;
+  getGroupDetailInfo(groupCode: string, groupInfoSource: number): Promise<GeneralCallResult>;
+  getAllMemberList(groupCode: string, forceFetch: boolean): Promise<{
+    errCode: number;
+    errMsg: string;
+    result: {
+      ids: Array<{
+        uid: string;
+        index: number;
+      }>;
+      infos: Map<string, GroupMember>;
+      finish: boolean;
+    };
+  }>;
+  getMemberInfo(groupCode: string, uids: string[], forceFetch: boolean): Promise<GeneralCallResult>;
+  /** uin → uid（私聊发送等需要，说明书参考）。 */
+  getUidByUins(uins: string[]): Promise<{
+    errCode: number;
+    errMsg: string;
+    uids: Map<string, string>;
+  }>;
+  /** uid → uin。 */
+  getUinByUids(uids: string[]): Promise<{
+    errCode: number;
+    errMsg: string;
+    uins: Map<string, string>;
+  }>;
+  /** 踢人（set_group_kick）。 */
+  kickMemberV2(param: KickMemberV2Req): Promise<GeneralCallResult>;
+  /** 成员禁言（set_group_ban；timeStamp=0 解除禁言）。 */
+  setMemberShutUp(groupCode: string, memberTimes: Array<{
+    uid: string;
+    timeStamp: number;
+  }>): Promise<GeneralCallResult>;
+  /** 全员禁言（set_group_whole_ban）。 */
+  setGroupShutUp(groupCode: string, shutUp: boolean): Promise<GeneralCallResult>;
+  /** 设置管理员（set_group_admin；void 语义，乐观处理）。 */
+  modifyMemberRole(groupCode: string, uid: string, role: NTGroupMemberRole): void;
+  /** 设置群名片（set_group_card；void 语义）。 */
+  modifyMemberCardName(groupCode: string, uid: string, cardName: string): void;
+  /** 修改群名（set_group_name）。 */
+  modifyGroupName(groupCode: string, groupName: string, isNormalMember: boolean): Promise<GeneralCallResult>;
+  /** 退群（set_group_leave）。 */
+  quitGroupV2(param: {
+    groupCode: string;
+    needDeleteLocalMsg: boolean;
+  }): Promise<GeneralCallResult>;
+  /** 设置精华消息（msgSeq/msgRandom 取自消息本体）。 */
+  addGroupEssence(param: {
+    groupCode: string;
+    msgRandom: number;
+    msgSeq: number;
+  }): Promise<unknown>;
+  /** 取消精华消息。 */
+  removeGroupEssence(param: {
+    groupCode: string;
+    msgRandom: number;
+    msgSeq: number;
+  }): Promise<unknown>;
+  /** @all 剩余次数（get_group_at_all_remain）。 */
+  getGroupRemainAtTimes(groupCode: string): Promise<Omit<GeneralCallResult, "result"> & {
+    errCode: number;
+    atInfo: GroupRemainAtTimes;
+  }>;
+  /** 单屏通知列表（get_group_system_msg / set_group_add_request 共用；列表可能走 listener，宽松解包）。 */
+  getSingleScreenNotifies(doubt: boolean, startSeq: string, count: number): Promise<GeneralCallResult & {
+    result?: unknown;
+  }>;
+  /** 禁言成员列表（get_group_shut_list；同 listener 风格，宽松解包）。 */
+  getGroupShutUpMemberList(groupCode: string): Promise<GeneralCallResult & {
+    result?: unknown;
+  }>;
+  /** 处理群请求（set_group_add_request 应答；postscript 空值可能导致失败，默认空格）。 */
+  operateSysNotify(doubt: boolean, operateMsg: {
+    operateType: NTGroupRequestOperateTypes;
+    targetMsg: {
+      seq: string;
+      type: GroupNotifyMsgType;
+      groupCode: string;
+      postscript: string;
+    };
+  }): Promise<void>;
+}
+//#endregion
+//#region src/apis/group.d.ts
+/** 群 API：从 session 拿 group service，包装成语义化方法。 */
+declare class GroupApi {
+  private readonly service;
+  /** 精华消息需要 msg service（按 msgId 拉消息取 msgSeq/msgRandom）。 */
+  private readonly msgService;
+  constructor(session: NodeIQQNTWrapperSession);
+  /** 群列表（force=true 强制刷新，默认缓存）。 */
+  getGroupList(force?: boolean): Promise<Group[]>;
+  /** 群详情（groupCode 为群号字符串）。
+   * getGroupDetailInfo 返回形状：失败 result=错误码；成功详情可能直接在 result
+   * 对象里，也可能在 groupInfo/detailInfo 字段——三种形状都兼容（探测校准）。
+   * 2026-08-07 修复：成功（result=0）时不再把 {result:0,errMsg} 原样当详情返回，
+   * 而是提取详情字段；形状异常抛 UNKNOWN 而非静默返回垃圾数据。 */
+  getGroupInfo(groupCode: string): Promise<GroupDetailInfo>;
+  /** 群成员列表（forceFetch=true 强制拉取，默认缓存优先）。 */
+  getGroupMemberList(groupCode: string, forceFetch?: boolean): Promise<GroupMember[]>;
+  /** 群成员详情（uids 为空返回空数组）。 */
+  getGroupMemberInfo(groupCode: string, uids: string[]): Promise<GroupMember[]>;
+  /** uin → uid（私聊发送等需要）。 */
+  uinToUid(uins: string[]): Promise<Map<string, string>>;
+  /** uid → uin。 */
+  uidToUin(uids: string[]): Promise<Map<string, string>>;
+  /** 群成员角色 → OB11 role 字符串。 */
+  static roleToString(role: NTGroupMemberRole): "owner" | "admin" | "member";
+  /**
+   * 踢人（set_group_kick）。memberUids 为成员 uid；refuseForever=true 拉黑拒绝再次入群。
+   * kickMemberV2 的 kickFlag/kickList 字段值待探测校准（TODO P3 联调）。
+   */
+  kickMember(groupCode: string, memberUids: string[], refuseForever: boolean, reason?: string): Promise<void>;
+  /** 成员禁言（duration 秒，0 解除禁言）。 */
+  setMemberShutUp(groupCode: string, members: Array<{
+    uid: string;
+    duration: number;
+  }>): Promise<void>;
+  /** 全员禁言（enable=true 开启全群禁言）。 */
+  setGroupShutUp(groupCode: string, enable: boolean): Promise<void>;
+  /** 设置管理员（role=ADMIN 设管理，MEMBER 取消；void 语义乐观处理）。 */
+  setMemberRole(groupCode: string, uid: string, role: NTGroupMemberRole): void;
+  /** 设置群名片（void 语义乐观处理）。 */
+  setMemberCardName(groupCode: string, uid: string, cardName: string): void;
+  /** 修改群名。 */
+  modifyGroupName(groupCode: string, groupName: string): Promise<void>;
+  /** 退群（needDeleteLocalMsg=is_dismiss：是否解散群，仅群主）。 */
+  quitGroup(groupCode: string, needDeleteLocalMsg?: boolean): Promise<void>;
+  /** 设置精华消息（msgId 经 msgService 取 msgSeq/msgRandom）。 */
+  addGroupEssence(groupCode: string, msgId: string): Promise<void>;
+  /** 取消精华消息。 */
+  removeGroupEssence(groupCode: string, msgId: string): Promise<void>;
+  /** 精华消息公共流程：按 msgId 拉消息 → add/removeGroupEssence。 */
+  private setEssence;
+  /** @all 剩余次数（get_group_at_all_remain）。 */
+  getGroupRemainAtTimes(groupCode: string): Promise<{
+    canAtAll: boolean;
+    remainAtAllCountForUin: number;
+    remainAtAllCountForGroup: number;
+  }>;
+}
+//#endregion
+//#region src/apis/group-notify.d.ts
+/** 群通知 API：从 session 拿 group service，包装成语义化方法。 */
+declare class GroupNotifyApi {
+  private readonly service;
+  constructor(session: NodeIQQNTWrapperSession);
+  /** 单屏通知列表（get_group_system_msg / set_group_add_request 共用）。 */
+  getSingleScreenNotifies(doubt: boolean, count: number): Promise<GroupNotify[]>;
+  /** 禁言成员列表（get_group_shut_list）。 */
+  getGroupShutUpMemberList(groupCode: string): Promise<GroupMember[]>;
+  /** 处理群请求（set_group_add_request 应答；approve=true 同意 / false 拒绝）。 */
+  handleGroupRequest(doubt: boolean, notify: GroupNotify, operateType: NTGroupRequestOperateTypes, reason: string): Promise<void>;
+}
+//#endregion
+//#region src/types/message-element.d.ts
+/** NT RawMessage → canonical 元素（与 toSendElements 对称，接收方向）。 */
+declare function toCanonicalElements(msg: RawMessage): CanonicalElement[];
+/** canonical 元素 → NT 发送元素（text/at/face/image/voice/reply 核心五类）。 */
+declare function toSendElements(elements: CanonicalElement[]): SendMessageElement[];
+/** 协议无关的规范消息元素。 */
+type CanonicalElement = {
+  type: "text";
+  text: string;
+} | {
+  type: "at";
+  target: string;
+  display?: string;
+} | {
+  type: "image";
+  path: string;
+  url?: string;
+  size?: {
+    width: number;
+    height: number;
+  };
+} | {
+  type: "face";
+  id: string;
+} | {
+  type: "voice";
+  path: string;
+  durationMs?: number;
+  url?: string;
+} | {
+  type: "video";
+  path: string;
+  url?: string;
+} | {
+  type: "file";
+  path: string;
+  name?: string;
+  size?: number;
+} | {
+  type: "reply";
+  messageId: string;
+} | {
+  type: "forward";
+  messageIds: string[];
+} | {
+  type: "json";
+  raw: unknown;
+} | {
+  type: "xml";
+  raw: unknown;
+} | {
+  type: "unknown";
+  raw: unknown;
+};
+//#endregion
+//#region src/apis/msg.d.ts
+/** 消息 API：从 session 拿 msg service，包装成语义化方法。 */
+declare class MsgApi {
+  private readonly service;
+  /** 上次生成 msgId 的时间（单调递增，2026-08-07 防同毫秒并发碰撞）。 */
+  private lastMsgTime;
+  constructor(session: NodeIQQNTWrapperSession);
+  /**
+   * 生成 msgId 时间戳（单调递增）。
+   * generateMsgUniqueId(chatType, time) 以 time 区分消息——同毫秒并发发送
+   * （机器人群发/多会话同时回复）Date.now() 会碰撞，msgId 相同导致 wrapper
+   * 拒绝或覆盖。严格单调递增保证进程内唯一。
+   */
+  private nextMsgTime;
+  /**
+   * 发送消息：canonical 元素 → NT 发送元素 → sendMsg。
+   * 返回 NT msgId（雪花 ID）。
+   */
+  sendMessage(target: Peer, elements: CanonicalElement[]): Promise<{
+    msgId: string;
+  }>;
+  /** 撤回消息（群聊管理员 / 私聊 2 分钟内）。 */
+  recallMessage(target: Peer, msgIds: string[]): Promise<void>;
+  /** 拉取历史消息（msgId 为空从最新拉；count 条，时间倒序）。 */
+  fetchMessages(target: Peer, opts: {
+    count: number;
+    msgId?: string;
+  }): Promise<RawMessage[]>;
+  /** 按 msgId 批量拉取消息（get_msg / 精华消息 / ptt 转文字共用）。 */
+  fetchMsgsByMsgId(target: Peer, ids: string[]): Promise<RawMessage[]>;
+  /** 消息表情表态（set_msg_emoji_like；like=true 点赞，false 取消）。 */
+  setMsgEmojiLike(target: Peer, opts: {
+    msgSeq: string;
+    emojiId: string;
+    emojiType: string;
+    like: boolean;
+  }): Promise<void>;
+  /**
+   * 语音转文字（fetch_ptt_text）。
+   * 流程：按 msgId 拉消息 → 找 PTT 元素 → translatePtt2Text（异步转写）
+   * → 再拉一次消息读 pttElement.text。
+   */
+  fetchPttText(msgId: string, target: Peer): Promise<string>;
+  /** 标记会话已读。 */
+  markRead(target: Peer): Promise<void>;
+  /** 发送输入状态（set_input_status；eventType=1 输入中，0 停止）。 */
+  setInputStatus(target: Peer, eventType: number): Promise<void>;
+  /**
+   * 发送合并转发（send_group/private_forward_msg）。
+   * buildMultiForwardMsg 组装 MULTI_FORWARD 元素 → 直接作 sendMsg 元素发送。
+   */
+  sendForwardMessage(target: Peer, sourcePeer: Peer, srcMsgIds: string[]): Promise<{
+    msgId: string;
+  }>;
+  /** 获取合并转发内容（get_forward_msg；resId 取自 multiForwardMsgElement）。 */
+  fetchForwardMessage(peer: Peer, msgId: string): Promise<RawMessage[]>;
+  /** 单条转发（forward_group/friend_single_msg；srcMsgIds 源、dstPeer 目标）。 */
+  forwardSingleMessage(sourcePeer: Peer, srcMsgIds: string[], dstPeer: Peer): Promise<void>;
+  /** 设置在线状态（set_online_status；customStatus 为自定义状态）。 */
+  setOnlineStatus(opts: {
+    status: number;
+    extStatus: number;
+    batteryStatus: number;
+    customStatus?: {
+      faceId: string;
+      wording: string;
+      faceType: string;
+    };
+  }): Promise<void>;
+}
+//#endregion
+//#region src/types/services/ticket-service.d.ts
+/** forceFetchClientKey 返回（get_clientkey 直接返回，get_cookies 用 clientKey 换跳转票据）。 */
+interface ForceFetchClientKeyRetType extends GeneralCallResult {
+  url: string;
+  keyIndex: string;
+  clientKey: string;
+  expireTime: string;
+}
+/** 票据服务。 */
+interface NodeIKernelTicketService {
+  addKernelTicketListener(listener: unknown): number;
+  removeKernelTicketListener(listenerId: number): void;
+  forceFetchClientKey(arg: string): Promise<ForceFetchClientKeyRetType>;
+  isNull(): boolean;
+}
+//#endregion
+//#region src/apis/ticket.d.ts
+/** 票据 API：从 session 拿 ticket service，包装成语义化方法。 */
+declare class TicketApi {
+  private readonly service;
+  constructor(session: NodeIQQNTWrapperSession);
+  /** 获取 clientKey（get_clientkey）。 */
+  getClientKey(): Promise<ForceFetchClientKeyRetType>;
+  /** 获取指定域名的 cookies（get_cookies；uin 为机器人 QQ 号）。 */
+  getCookies(domain: string, uin: string): Promise<Record<string, string>>;
+  /** 计算 bkn（get_csrf_token 与 web 接口共用；skey → bkn 哈希）。 */
+  static getBkn(skey: string): string;
+}
+//#endregion
+//#region src/apis/profile.d.ts
+/** 陌生人信息（get_stranger_info 返回）。 */
+interface StrangerInfo {
+  user_id: number;
+  uid: string;
+  nickname: string;
+  age: number;
+  qid: string;
+  qq_level: number;
+  sex: "male" | "female" | "unknown";
+  long_nick: string;
+  reg_time: number;
+  is_vip: boolean;
+  is_years_vip: boolean;
+  vip_level: number;
+  remark: string;
+  status: number;
+  login_days: number;
+}
+/** 资料 API：从 session 拿 profile service，包装成语义化方法。 */
+declare class ProfileApi {
+  private readonly service;
+  constructor(session: NodeIQQNTWrapperSession);
+  /** 设置个性签名（set_self_longnick）。 */
+  setLongNick(longNick: string): Promise<void>;
+  /** 设置昵称（set_qq_profile）。 */
+  setNickName(nickName: string): Promise<void>;
+  /** 设置头像（set_qq_avatar；filePath 为本地路径）。 */
+  setHeader(filePath: string): Promise<void>;
+  /** 获取陌生人信息（get_stranger_info；uin 为用户 QQ 号）。 */
+  getStrangerInfo(uin: string): Promise<StrangerInfo>;
+}
+//#endregion
+//#region src/apis/profile-like.d.ts
+/** 点赞 API：从 session 拿 profile like service，包装成语义化方法。 */
+declare class ProfileLikeApi {
+  private readonly service;
+  constructor(session: NodeIQQNTWrapperSession);
+  /** 点赞（send_like；uid 为目标 uid，count 次数）。 */
+  sendLike(uid: string, count?: number): Promise<void>;
+}
+//#endregion
+//#region src/types/services/richmedia-service.d.ts
+/** 群文件列表参数（getGroupFileList，说明书参考）。 */
+interface GetFileListParam {
+  sortType: number;
+  fileCount: number;
+  startIndex: number;
+  sortOrder: number;
+  showOnlinedocFolder: number;
+}
+/** 群文件项（getGroupFileList 返回的 fileInfo，说明书参考，待探测校准）。 */
+interface GroupFileItemInfo {
+  fileId: string;
+  fileName: string;
+  fileSize: string;
+  fileUuid?: string;
+  parent?: string;
+  uploadTime?: number;
+  modifyTime?: number;
+  uploaderUid?: string;
+  uploaderUin?: string;
+  [key: string]: unknown;
+}
+/** 群文件夹项（getGroupFileList 返回的 folderInfo，说明书参考，待探测校准）。 */
+interface GroupFolderInfo {
+  folderId: string;
+  folderName: string;
+  folderPath?: string;
+  folderUid?: string;
+  [key: string]: unknown;
+}
+/** 群文件空间信息（getGroupFileList 的 groupSpaceResult，说明书参考）。 */
+interface GroupSpaceInfo {
+  retCode: number;
+  retMsg: string;
+  clientWording: string;
+  totalSpace: number;
+  usedSpace: number;
+  allUpload: boolean;
+}
+/** 富媒体服务。 */
+interface NodeIKernelRichMediaService {
+  addKernelRichMediaListener(listener: unknown): number;
+  removeKernelRichMediaListener(listenerId: number): void;
+  /** 英文单词翻译（translate_en2zh）。 */
+  translateEnWordToZn(words: string[]): Promise<GeneralCallResult & {
+    words?: string[];
+  }>;
+  /** 群文件列表（get_group_root_files / get_group_files_by_folder）。 */
+  getGroupFileList(groupCode: string, params: GetFileListParam): Promise<GeneralCallResult & {
+    groupSpaceResult?: GroupSpaceInfo;
+    result?: unknown;
+  }>;
+  /** 创建群文件夹（create_group_file_folder）。 */
+  createGroupFolder(groupCode: string, folderName: string): Promise<GeneralCallResult>;
+  /** 删除群文件（delete_group_file；params 业务类型，Files 为文件 ID 列表）。 */
+  deleteGroupFile(groupCode: string, params: number[], files: string[]): Promise<GeneralCallResult>;
+  /** 删除群文件夹（delete_group_folder）。 */
+  deleteGroupFolder(groupCode: string, folderId: string): Promise<GeneralCallResult>;
+  /** 重命名群文件（rename_group_file；参数待探测校准）。 */
+  renameGroupFile(arg1: string, arg2: number, arg3: string, arg4: string, arg5: string): Promise<unknown>;
+  /** 移动群文件（move_group_file）。 */
+  moveGroupFile(groupCode: string, busId: number[], fileList: string[], currentParentDirectory: string, targetParentDirectory: string): Promise<GeneralCallResult>;
+  /** 转存群文件（trans_group_file）。 */
+  transGroupFile(groupCode: string, fileId: string): Promise<GeneralCallResult>;
+  /** 批量群文件数（get_group_file_system_info 补充）。 */
+  batchGetGroupFileCount(groupCodes: string[]): Promise<GeneralCallResult & {
+    groupCodes?: string[];
+    groupFileCounts?: number[];
+  }>;
+  isNull(): boolean;
+}
+//#endregion
+//#region src/apis/richmedia.d.ts
+/** 群文件列表条目（fileInfo/folderInfo 取其一）。 */
+interface GroupFileListItem {
+  fileInfo?: GroupFileItemInfo;
+  folderInfo?: GroupFolderInfo;
+}
+/** 群文件系统信息。 */
+interface GroupFileSystemInfo {
+  fileCount: number;
+  limitCount: number;
+  usedSpace: number;
+  totalSpace: number;
+}
+/** 富媒体 API：从 session 拿 rich media service，包装成语义化方法。 */
+declare class RichMediaApi {
+  private readonly service;
+  constructor(session: NodeIQQNTWrapperSession);
+  /** 英文单词翻译（translate_en2zh）。 */
+  translateWords(words: string[]): Promise<string[]>;
+  /** 群文件列表（get_group_root_files；parent 缺省根目录）。 */
+  getGroupFileList(groupCode: string, parentFolderId?: string, fileCount?: number): Promise<GroupFileListItem[]>;
+  /** 群文件系统信息（get_group_file_system_info；getGroupFileList 的 groupSpaceResult）。 */
+  getGroupFileSystemInfo(groupCode: string): Promise<GroupFileSystemInfo>;
+  /** 创建群文件夹（create_group_file_folder）。 */
+  createGroupFolder(groupCode: string, folderName: string): Promise<string>;
+  /** 删除群文件（delete_group_file）。 */
+  deleteGroupFile(groupCode: string, fileIds: string[]): Promise<void>;
+  /** 删除群文件夹（delete_group_folder）。 */
+  deleteGroupFolder(groupCode: string, folderId: string): Promise<void>;
+  /** 重命名群文件（rename_group_file；参数语义待探测校准）。 */
+  renameGroupFile(groupCode: string, fileId: string, newName: string): Promise<void>;
+  /** 移动群文件（move_group_file；targetFolder 空为根目录）。 */
+  moveGroupFile(groupCode: string, fileIds: string[], targetFolderId: string): Promise<void>;
+  /** 转存群文件（trans_group_file）。 */
+  transGroupFile(groupCode: string, fileId: string): Promise<void>;
+}
+//#endregion
+//#region src/apis/webapi.d.ts
+/** 精华消息项（digest_list 返回 data.msg_list 成员，说明书参考）。 */
+interface EssenceMsgItem {
+  msg_seq: number;
+  msg_random: number;
+  sender_uin: string;
+  sender_nick: string;
+  add_digest_uin: string;
+  add_digest_nick: string;
+  add_digest_time: number;
+  msg_content: Array<{
+    msg_type?: number;
+    text?: string;
+    image_url?: string;
+  }>;
+}
+/** 群荣誉项（honorlist 返回列表项，说明书参考）。 */
+interface HonorListItem {
+  uin: string;
+  name: string;
+  avatar: string;
+  desc: string;
+}
+/** 群荣誉信息（getGroupHonorInfo 返回）。 */
+interface GroupHonorWebInfo {
+  group_id: number;
+  current_talkative: HonorListItem | null;
+  talkative_list: HonorListItem[];
+  performer_list: HonorListItem[];
+  legend_list: HonorListItem[];
+  emotion_list: HonorListItem[];
+  strong_newbie_list: HonorListItem[];
+}
+/** 群荣誉类型（1=龙王 2=群聊之火 3=群聊炽热 6=快乐源泉）。 */
+declare const WebHonorType: {
+  readonly ALL: 0;
+  readonly TALKATIVE: 1;
+  readonly PERFORMER: 2;
+  readonly LEGEND: 3;
+  readonly EMOTION: 6;
+};
+type WebHonorType = (typeof WebHonorType)[keyof typeof WebHonorType];
+/** 群空间 web API（Cookie 经 TicketApi 注入）。 */
+declare class WebApi {
+  private readonly getCookies;
+  constructor(opts: {
+    getCookies: (domain: string) => Promise<Record<string, string>>;
+  });
+  /** 获取群精华消息列表（get_essence_msg_list；分页拉取至 is_end）。 */
+  getEssenceMsgList(groupCode: string): Promise<EssenceMsgItem[]>;
+  /** 获取群荣誉信息（get_group_honor_info；type 0=全部）。 */
+  getGroupHonorInfo(groupCode: string, type: WebHonorType): Promise<GroupHonorWebInfo>;
+  /** 拉取单类荣誉列表（honorlist 接口，正则提取 __INITIAL_STATE__）。 */
+  private fetchHonorList;
+}
+//#endregion
+//#region src/event-channel.d.ts
+/** Listener 接口形状（宽约束；精确签名由实例化时的具体接口保证）。 */
+type ListenerShape = Record<string, unknown>;
+/** 事件名：`${Service}/${method}`。 */
+type EventName<L extends ListenerShape, Name extends string> = `${Name}/${keyof L & string}`;
+/** 按事件名从 Listener 精确提取 handler 类型（条件类型 infer，泛型安全）。 */
+type EventHandler<L extends ListenerShape, Name extends string, E extends EventName<L, Name>> = Extract<{ [K in keyof L]: L[K] extends ((...args: infer A) => infer R) ? {
+  name: `${Name}/${K & string}`;
+  fn: (...args: A) => R;
+} : never; }[keyof L], {
+  name: E;
+}>["fn"];
+/** 按事件名从 Listener 精确提取参数类型。 */
+type EventArgs<L extends ListenerShape, Name extends string, E extends EventName<L, Name>> = Extract<{ [K in keyof L]: L[K] extends ((...args: infer A) => unknown) ? {
+  name: `${Name}/${K & string}`;
+  args: A;
+} : never; }[keyof L], {
+  name: E;
+}>["args"];
+/** 从 Listener 接口推导事件映射（文档/调试用）：`{ "Msg/onRecvMsg": fn }`。 */
+type ListenerEvents<L extends ListenerShape, Name extends string> = { [K in keyof L as `${Name}/${K & string}`]: L[K]; };
+/**
+ * 类型化事件通道。
+ *
+ * @typeParam L - Listener 接口（探测产物，如 MsgListener）
+ * @typeParam Name - Service 名（事件名前缀，如 "Msg"）
+ */
+declare class NTEventChannel<L extends ListenerShape, Name extends string> {
+  readonly serviceName: Name;
+  private readonly emitter;
+  private readonly errorHandlers;
+  constructor(serviceName: Name);
+  /**
+   * 订阅事件：返回 unsubscribe（只注销该 handler，不影响其他订阅者）。
+   * 每个 Service 只注册一次原生监听，缓存维护与协议翻译都订阅这里。
+   */
+  on<E extends EventName<L, Name>>(event: E, handler: EventHandler<L, Name, E>): () => void;
+  /**
+   * 请求-响应桥：注册临时监听 → filter 命中 → resolve；超时自动清理并 reject。
+   * 替代魔法字符串事件名方案。
+   */
+  waitFor<E extends EventName<L, Name>>(event: E, opts?: {
+    filter?: (...args: EventArgs<L, Name, E>) => boolean;
+    timeout?: number;
+  }): Promise<EventArgs<L, Name, E>>;
+  /**
+   * 类型化派发：wrapper-loader 的原生回调经此推入通道。
+   * 2026-08-07 修复：原生 EventEmitter.emit 中一个 listener 抛异常会中断后续
+   * listener 派发（Node 语义）——改为快照数组逐个 try/catch，保证「单个订阅者
+   * 异常不打断派发」（协议翻译层异常不饿死缓存维护等其他订阅者）。
+   */
+  emit<E extends EventName<L, Name>>(event: E, ...args: EventArgs<L, Name, E>): void;
+  /** 订阅错误通知（监听器抛出的异常 / 其他内部错误）。 */
+  onError(handler: (err: unknown) => void): () => void;
+}
+//#endregion
+//#region src/types/listeners/group.d.ts
+/** 群列表更新类型（说明书参考，值待探测校准）。 */
+declare const GroupListUpdateType: {
+  /** 全量更新（groupList 为完整列表）。 */
+  readonly ALL: 0;
+  /** 增量更新（合并到现有缓存）。 */
+  readonly PARTIAL: 1;
+};
+type GroupListUpdateType = (typeof GroupListUpdateType)[keyof typeof GroupListUpdateType];
+/** 成员数据来源（onMemberInfoChange 第二参，说明书参考）。 */
+declare const GroupMemberDataSource: {
+  /** 本地缓存。 */
+  readonly CACHE: 0;
+  /** 网络拉取。 */
+  readonly NETWORK: 1;
+};
+type GroupMemberDataSource = (typeof GroupMemberDataSource)[keyof typeof GroupMemberDataSource];
+/** onMemberListChange 参数（sceneId 为群号 groupCode）。 */
+interface GroupMemberListChange {
+  sceneId: string;
+  ids: string[];
+  /** uid → GroupMember。 */
+  infos: Map<string, GroupMember>;
+  hasPrev: boolean;
+  hasNext: boolean;
+  hasRobot: boolean;
+}
+/** 群服务（GroupService）的原生回调监听接口。 */
+type GroupListener = {
+  /** 群列表初始化完成（listEmpty：是否无群）。 */
+  onGroupListInited: (listEmpty: boolean) => void;
+  /** 群列表更新。 */
+  onGroupListUpdate: (updateType: GroupListUpdateType, groupList: Group[]) => void;
+  /** 群详情变化。 */
+  onGroupDetailInfoChange: (detailInfo: GroupDetailInfo) => void;
+  /** 群成员列表变化（sceneId=groupCode）。 */
+  onMemberListChange: (arg: GroupMemberListChange) => void;
+  /** 群成员信息变化（dataSource 区分本地缓存/网络）。 */
+  onMemberInfoChange: (groupCode: string, dataSource: GroupMemberDataSource, members: Map<string, GroupMember>) => void;
+  /** 群通知更新（doubt：是否可疑/忽略列表）。 */
+  onGroupNotifiesUpdated: (doubt: boolean, notifies: GroupNotify[]) => void;
+  /** 群通知单屏（分页 seq）。 */
+  onGroupSingleScreenNotifies: (doubt: boolean, seq: string, notifies: GroupNotify[]) => void;
+  /** 群禁言成员列表变化。 */
+  onShutUpMemberListChanged: (groupCode: string, members: ShutUpGroupMember[]) => void;
+};
+//#endregion
+//#region src/bridge/group-bridge.d.ts
+/** 群事件通道的固定类型（事件名前缀 "Group"）。 */
+type GroupEventChannel = NTEventChannel<GroupListener, "Group">;
+/**
+ * 群事件桥：注册原生监听 → 回调 emit 到 channel。
+ * 无全局单例（ADR-015 推论）——每进程每 session 实例化一份。
+ */
+declare class GroupBridge {
+  private readonly service;
+  private readonly channel;
+  private listenerId;
+  constructor(session: NodeIQQNTWrapperSession, channel: GroupEventChannel);
+  /** 注册原生监听（幂等）。 */
+  register(): void;
+  /** 注销原生监听（幂等）。 */
+  unregister(): void;
+}
+//#endregion
+//#region src/types/listeners/msg.d.ts
+/** 消息已读上报（peer + 已读 seq）。 */
+interface MsgReadReportItem {
+  peer: unknown;
+  readSeq: string;
+}
+/** 消息回执（msgId + 已读 seq）。 */
+interface MsgReceipt {
+  msgId: string;
+  readSeq: string;
+}
+/** 消息服务（MsgService）的原生回调监听接口。
+ * 用 type 别名（非 interface）：需满足 ListenerShape（Record<string, unknown>）
+ * 约束——interface 无隐式索引签名不兼容；type 对象类型天然满足。
+ *
+ * ⚠️ 2026-08-07 运行时探测实证（自建宿主，QQ 9.9.33）：onRecvMsg 回调参数是
+ * **消息数组**（多条批量推送），非单条 RawMessage——此前单条签名错误（收到数组后
+ * msg.msgId/elements 全 undefined）。信号链：原生回调 → MsgBridge 透传数组 →
+ * 事件通道 → 订阅方遍历处理。 */
+type MsgListener = {
+  /** 收到新消息（批量数组，运行时实证）。 */
+  onRecvMsg: (msgs: RawMessage[]) => void;
+  /** 消息已读上报。 */
+  onRecvMsgReadReport: (reports: MsgReadReportItem[]) => void;
+  /** 消息回执。 */
+  onRecvMsgReceipt: (receipts: MsgReceipt[]) => void;
+};
+//#endregion
+//#region src/bridge/msg-bridge.d.ts
+/** 消息事件通道的固定类型（事件名前缀 "Msg"）。 */
+type MsgEventChannel = NTEventChannel<MsgListener, "Msg">;
+/**
+ * 消息事件桥：注册原生监听 → 回调 emit 到 channel。
+ * 无全局单例（ADR-015 推论）——每进程每 session 实例化一份。
+ */
+declare class MsgBridge {
+  private readonly service;
+  private readonly channel;
+  private listenerId;
+  constructor(session: NodeIQQNTWrapperSession, channel: MsgEventChannel);
+  /** 注册原生监听（幂等）。 */
+  register(): void;
+  /** 注销原生监听（幂等）。 */
+  unregister(): void;
+}
+//#endregion
+//#region src/cache/group-cache.d.ts
+/** GroupCache 构造参数。 */
+interface GroupCacheOptions {
+  /** 群事件通道（GroupBridge 注册原生监听后 emit 到这里）。 */
+  channel: GroupEventChannel;
+  /** 群 API（惰性回填用）。 */
+  groupApi: GroupApi;
+}
+/**
+ * 群/成员缓存：事件主动维护 + 查询惰性回填。
+ * 只读接口 getGroupDetail / getMembers / getMember / getGroup（列表项）。
+ */
+declare class GroupCache {
+  private readonly channel;
+  private readonly groupApi;
+  /** 群列表项（onGroupListUpdate / getGroupList 回填）。 */
+  private readonly groupList;
+  /** 群详情（onGroupDetailInfoChange / getGroupInfo 回填）。 */
+  private readonly groupDetails;
+  /** 群成员：groupCode → (uid → GroupMember)。 */
+  private readonly members;
+  /** 惰性回填 in-flight 去重。 */
+  private readonly inFlight;
+  private unsubscribes;
+  constructor(opts: GroupCacheOptions);
+  /** 订阅群事件通道（幂等）。 */
+  register(): void;
+  /** 退订事件通道（幂等）。 */
+  unregister(): void;
+  /** 合并成员到该群缓存（uid → GroupMember）。 */
+  private upsertMembers;
+  /** 群列表是否已有缓存（同步判断）。 */
+  hasGroup(groupCode: string): boolean;
+  /**
+   * 群列表项（只读；缺失惰性回填 getGroupList）。
+   * 返回 undefined 表示群不存在。
+   */
+  getGroup(groupCode: string): Promise<Group | undefined>;
+  /**
+   * 群详情（只读；缺失惰性回填 getGroupInfo）。
+   * getGroupInfo 恒返回对象（失败抛 KernelError），直接缓存。
+   */
+  getGroupDetail(groupCode: string): Promise<GroupDetailInfo>;
+  /**
+   * 群成员列表（只读；缺失惰性回填 getAllMemberList(forceFetch=true)）。
+   * 返回空数组表示该群无成员（或拉取失败已由 GroupApi 抛 KernelError）。
+   */
+  getMembers(groupCode: string): Promise<GroupMember[]>;
+  /**
+   * 群成员（只读；缺失回填：先整群拉取，再按 uid 取；仍无则 getMemberInfo 单查）。
+   * 返回 undefined 表示成员不在群。
+   */
+  getMember(groupCode: string, uid: string): Promise<GroupMember | undefined>;
+  /** 惰性回填全量群列表（getGroup 缺失时）。 */
+  private loadGroupList;
+  /** 惰性回填并发去重：同 key 并发只拉一次。 */
+  private dedupe;
+}
+//#endregion
+//#region src/infra/paths.d.ts
+/** 默认数据根目录名（用户目录下，程序目录可能只读，见 ADR-016）。 */
+declare const DEFAULT_DATA_ROOT_NAME = ".napuketto";
+/** 全局配置文件名。 */
+declare const MAIN_CONFIG_FILE = "napuketto.toml";
+interface PathOptions {
+  /** 显式数据根（cli `--data-dir` 传入，优先级最高）。 */
+  dataRoot?: string;
+  /** QQ 号，用于多账号隔离；缺省时直接使用数据根本身。 */
+  account?: string;
+}
+/**
+ * 解析数据根：显式参数 > 环境变量 > 用户目录默认。
+ * 返回绝对路径。独立导出便于 cli / 探测脚本复用。
+ */
+declare function resolveDataRoot(dataRoot?: string): string;
+interface ConfigPathOptions {
+  /** 兜底数据根（探测全部失败时用 `<dataRoot>/napuketto.toml`，保持旧行为）。 */
+  dataRoot?: string;
+}
+/**
+ * 全局配置文件路径解析（2026-08-07 用户拍板：**配置文件放项目根目录，
+ * 数据仍按数据根组织**——数据根只承载账号目录/日志/缓存/QQ 数据）。
+ *
+ * 优先级：
+ *  1. `NAPKETTO_CONFIG` 环境变量（显式指定完整路径，任意场景可用）
+ *  2. 入口模块向上找 `pnpm-workspace.yaml`（monorepo 开发场景，即项目根）
+ *  3. 运行目录（cwd）向上找 `pnpm-workspace.yaml` / `package.json`（发布后用户项目）
+ *  4. 数据根兜底 `<dataRoot>/napuketto.toml`（旧行为兼容）
+ *
+ * 返回绝对路径。独立导出便于 cli / loader 装配链复用。
+ */
+declare function resolveConfigPath(opts?: ConfigPathOptions): string;
+/**
+ * 路径装配器：持有账号数据目录下的全部子目录。
+ * 无全局单例（ADR-015 推论）——每账号每进程实例化一份。
+ */
+declare class PathWrapper {
+  /** 数据根（绝对路径）。 */
+  readonly root: string;
+  /** 账号数据目录（绝对路径），缺省 account 时等于 root。 */
+  readonly accountDir: string;
+  /** config 目录（napuketto.json + 各协议配置）。 */
+  readonly configDir: string;
+  /** logs 目录（pino 文件日志）。 */
+  readonly logsDir: string;
+  /** cache 目录（临时文件、媒体缓存）。 */
+  readonly cacheDir: string;
+  constructor(opts?: PathOptions);
+  /** 递归创建全部目录，启动装配时调用一次。 */
+  ensure(): void;
+  /** 账号目录内的文件路径（如 `file('config', 'napuketto.json')`）。 */
+  file(...segments: string[]): string;
+  /**
+   * 清空缓存目录（clean_cache 动作经注入回调消费）。
+   * 只删除 cacheDir 下的条目，保留目录本身。
+   */
+  clearCache(): void;
+}
+//#endregion
+//#region src/wrapper/wrapper-loader.d.ts
+/**
+ * Electron 进程类型（Node 的 process 类型无此字段）。
+ * - "browser"：QQ 主进程（V1 模式）
+ * - "utility"：utilityProcess Worker（路线 B，2026-08-06）
+ */
+declare function electronProcessType(): string | undefined;
+/**
+ * 解析 QQ 用户数据根（登录数据目录，如 `C:\Users\<user>\Documents\Tencent Files`）。
+ * 优先 NodeQQNTWrapperUtil.getNTUserDataInfoConfig()（QQ 官方 API），回退默认位置。
+ *
+ * 背景（2026-08-06 P2-1 实测）：worker（utilityProcess）模式下 loginService 是
+ * `new NodeIKernelLoginService()` 新建的，其 initConfig 的 commonPath 必须指向
+ * QQ 真实数据路径才能读到历史账号——cli 的 `.napuketto\default` 数据目录读不到
+ * （getLoginList 返回空 → 只能 QR 登录）。V1 主进程模式 QQ 自己 initConfig 过
+ * 正确路径，无需此解析。
+ */
+declare function resolveQqUserDataRoot(exports: WrapperNodeApi): string | null;
+/** QQ 版本信息（登录握手用）。 */
+interface QQVersionContext {
+  fullVersion: string;
+  buildVersion: string;
+}
+/** 已引导的 wrapper 上下文（运行在 QQ Electron 主进程内）。 */
+interface WrapperContext {
+  /** wrapper.node 的 NAPI 顶层导出。 */
+  exports: WrapperNodeApi;
+  /** engine 单例（get() 已调用）。 */
+  engine: NodeIQQNTWrapperEngine;
+  /** 版本信息（供登录握手等使用）。 */
+  versionInfo: QQVersionContext;
+  /** 会话（QQ 拦截捕获 / createSession 后填充）。 */
+  session: NodeIQQNTWrapperSession | null;
+  /** 启动会话包装（NapCat 同款：StartupSessionWrapper.create()，start() 替代 startNT）。 */
+  startupSession: NodeIQQNTStartupSessionWrapper | null;
+  /** QQ 的 loginService 实例（拦截 new 捕获，可为 null）。 */
+  loginService: unknown;
+}
+/**
+ * 从 loader 截获的 NAPI exports 创建 wrapper 上下文。
+ * 在 QQ 主进程内调用（boot.cjs → kernel 入口）。
+ */
+declare function createWrapper(exports: WrapperNodeApi, versionInfo: QQVersionContext): WrapperContext;
+/** engine 初始化（wrapper 契约：先 engine 后 session）。config 为普通 JS 对象。 */
+declare function initEngine(ctx: WrapperContext, config: EnginInitDesktopConfig): void;
+/**
+ * 创建会话（2026-08-06 P2-0 实测修正——NapCat 方式自研等价）：
+ *  1. StartupSessionWrapper.create()（启动会话包装）
+ *  2. getNTWrapperSession("nt_1")（QQ 主 session，带完整 cpp_impl）
+ *  3. S.create() 回退
+ *
+ * 背景：`new NodeIQQNTWrapperSession()` 构造对象缺 cpp_impl，session.init 断言
+ * "implementation of IQQNTWrapperSession is not valid"（P2-0 实测确认）。
+ * NapCat 用 StartupSessionWrapper.create() + getNTWrapperSession('nt_1') 解决——
+ * 返回带完整实现的实例。worker（utilityProcess）继承 QQ env 后同样有效。
+ */
+declare function createSession(ctx: WrapperContext): NodeIQQNTWrapperSession;
+/** session 初始化（4 参全为 JS 对象，NAPI 自动转换）。 */
+declare function initSession(ctx: WrapperContext, config: WrapperSessionInitConfig, listener: NodeIKernelSessionListener): void;
+/**
+ * 启动会话（有 startupSession 用 start()，否则 startNT(0)）。
+ *
+ * ⚠️ 2026-08-07 V9 修正：单纯 start() 只在「已 init」的 session 上有效。
+ * 自建宿主必须走 initAndStartSession（先 session.init 再 startupSession.start()）——
+ * 先 start 后 init 业务 service 不挂载（HANDOVER-V9 实测）。本函数保留给
+ * 已 init 的 session 补启动用；新路径请用 initAndStartSession。
+ */
+declare function startSession(ctx: WrapperContext): void;
+/**
+ * boot 装配入口：createWrapper → initEngine → session。
+ *
+ * **session 来源（2026-08-05 修正）**：
+ *  1. qqSession（boot.cjs 拦截 `new` 窃取的 QQ 已 init session）——尚未落地
+ *  2. createSession（`new NodeIQQNTWrapperSession()`）——实测可用，默认路径
+ *  （getMainSession 实测为空壳：service 全 null + 缺 startNT，仅 probe 探测参考）
+ *
+ * 由 loader runtime/boot.cjs 在 QQ 主进程内调用（import kernel dist 后）。
+ * 返回 WrapperContext；失败抛 KernelError。
+ */
+declare function startNapuketto(options: StartNapukettoOptions): WrapperContext;
+/** startNapuketto 的引导环境（由 loader launcher 注入环境变量，boot.cjs 透传）。 */
+interface BootEnv {
+  /** QQ 版本（如 "9.9.31-49919"）。 */
+  qqVersion?: string;
+  /** 用户数据目录（cfgDir 的父级，用于 desktopPathConfig）。 */
+  dataDir?: string;
+  /** 账号 uin（可选，提供则一步 init+start）。 */
+  selfUin?: string;
+  /** 账号 uid（可选）。 */
+  selfUid?: string;
+}
+/** startNapuketto 选项。 */
+interface StartNapukettoOptions {
+  /** 截获的 wrapper.node NAPI exports（boot.cjs 传入）。 */
+  wrapperExports: WrapperNodeApi;
+  /** 引导环境（版本/数据目录/账号）。 */
+  env?: BootEnv;
+  /** 覆盖 engine 配置（联调用）。 */
+  engineConfig?: EnginInitDesktopConfig;
+  /** 覆盖 session 配置（联调用，提供则自动 init+start）。 */
+  sessionConfig?: WrapperSessionInitConfig;
+  /** QQ 已 init 的 session（boot.cjs 拦截 new 捕获）。 */
+  qqSession?: NodeIQQNTWrapperSession | null;
+  /** QQ 的 loginService 实例（boot.cjs 拦截 new 捕获）。 */
+  qqLoginService?: unknown;
+}
+//#endregion
+//#region src/login/lifecycle.d.ts
+/**
+ * 等待 QQ 自己完成 session 初始化（framework 复用模式，2026-08-05 修正）。
+ *
+ * 背景：QQ 9.9.31 实测——session 由 QQ 主进程自己创建并 init（登录后）。
+ * 我们不自己 init（重复 init 断言 "implementation of IQQNTWrapperSession is not valid"），
+ * 也不自己 create（登录前 create() 干扰 QQ，实测 QQ 退出 code=0）。
+ * 正确做法：等 QQ 的 session 就绪（getMsgService 非 null = 核心 service 已挂载）。
+ */
+declare function waitSessionReady(ctx: WrapperContext, opts: {
+  timeoutMs?: number;
+}): Promise<void>;
+/** 登录结果（QR 或快速登录）。 */
+interface LoginResult {
+  uin: string;
+  uid: string;
+  nick: string;
+}
+/** 登录列表项（getLoginList 返回，说明书参考）。 */
+interface LoginAccountInfo {
+  uin: string;
+  uid?: string;
+  nickName?: string;
+  isQuickLogin?: boolean;
+}
+/**
+ * 等待网络连接就绪（loginService.getMsfStatus() === 3）。
+ * 参考 NapCat waitForNetworkConnection 思路（自研实现）：快速登录在 QQ 刚拉起、
+ * 网络栈未初始化时报 1006511 网络异常——等待 MSF 连接后再重试。
+ * @returns 是否在超时前就绪。
+ */
+declare function waitForNetworkConnection(ctx: WrapperContext, opts?: {
+  timeoutMs?: number;
+}): Promise<boolean>;
+/** 列出历史登录账号（boot.cjs 启动横幅用，「可用快速登录 of QQ」）。 */
+declare function listLoginAccounts(ctx: WrapperContext): Promise<LoginAccountInfo[]>;
+/**
+ * 快速登录：遍历历史登录列表尝试。
+ * P2-1：失败且错误为网络异常（1006511）时，等网络就绪后重试（最多 NETWORK_RETRY_MAX 次）。
+ */
+declare function quickLogin(ctx: WrapperContext, opts: {
+  uin?: string;
+  timeoutMs?: number;
+}): Promise<LoginResult>;
+/** session 初始化（4 参全为普通 JS 对象，等 init 完成信号）。 */
+declare function initAndStartSession(ctx: WrapperContext, config: WrapperSessionInitConfig, listener: NodeIKernelSessionListener, opts: {
+  timeoutMs?: number;
+}): Promise<void>;
+//#endregion
+//#region src/context.d.ts
+interface CoreContextOptions {
+  /** pino logger（console + 可选文件，由装配层创建）。 */
+  logger: pino.Logger;
+  /** 账号数据目录布局（config/logs/cache）。 */
+  paths: PathWrapper;
+}
+/**
+ * 装配根：持有进程级共享对象。
+ * wrapper / login 由 NapukettoCore 装配后填充，未装配前为 null。
+ */
+interface CoreContext {
+  readonly logger: pino.Logger;
+  readonly paths: PathWrapper;
+  /** QQ wrapper 上下文（attachWrapper 后填充）。 */
+  wrapper: WrapperContext | null;
+  /** 登录结果（login 成功后填充）。 */
+  login: LoginResult | null;
+}
+/** 创建装配根（初始 wrapper/login 为 null）。 */
+declare function createCoreContext(opts: CoreContextOptions): CoreContext;
+//#endregion
+//#region src/infra/logger.d.ts
+/** 日志级别（pino 标准级别 + silent）。 */
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
+interface LoggerOptions {
+  /** 日志级别，默认 `info`。 */
+  level?: LogLevel;
+  /** 是否输出到 console（pretty 模式），默认 true。 */
+  console?: boolean;
+  /** 文件日志路径；不传则不写文件（父目录自动创建）。 */
+  file?: string;
+  /** 附加基础字段（如 `{ name: 'kernel' }`），自动保留 pid；name 用 pino 保留字段
+   * （logger name），pino-pretty 渲染为 `(name/pid)` 元数据头。 */
+  base?: Record<string, unknown>;
+  /** 追加的敏感字段路径（默认内置 token/票据等，见 DEFAULT_REDACT_PATHS）。 */
+  redact?: string[];
+}
+/**
+ * 创建 pino logger：console（pretty）+ 可选文件，统一 level / redact。
+ *
+ * 文件目的地用同步写入（`sync: true`）：日志量级下性能可接受，且进程退出不丢日志，
+ * 无需额外的 flush 步骤（对比异步 SonicBoom 的 flushSync 时序陷阱）。
+ */
+declare function createLogger(opts?: LoggerOptions): pino.Logger;
+//#endregion
+//#region src/core.d.ts
+interface NapukettoCoreOptions {
+  /** 数据根 / 账号（透传给 PathWrapper，见 ADR-016）。 */
+  paths?: PathOptions;
+  /** 日志级别，默认 info。 */
+  logLevel?: LogLevel;
+  /** 文件日志路径；不传则默认 `logs/napuketto.log`（父目录自动创建）。 */
+  logFile?: string;
+  /** 是否输出 console，默认 true。 */
+  consoleLog?: boolean;
+}
+/** login 参数。 */
+interface CoreLoginOptions {
+  /** appid（登录握手，兜底 537237765）。 */
+  appid: string;
+  /** session.init 超时（毫秒），默认 15s。 */
+  initTimeoutMs?: number;
+  /** 指定快速登录账号（缺省遍历历史列表）。 */
+  quickUin?: string;
+  /** 快速登录失败时回退 QR 登录（二维码写缓存目录），默认 false。 */
+  qrFallback?: boolean;
+  /** QR 二维码图片保存路径（默认缓存目录 qrcode.png）。 */
+  qrCodePath?: string;
+}
+/**
+ * 核心装配器：持有 CoreContext，负责启动/停止编排。
+ * 无全局单例（ADR-015 推论）——每账号每进程实例化一份。
+ */
+declare class NapukettoCore {
+  /** 装配根（协议层 / apis / cache 的消费入口）。 */
+  readonly ctx: CoreContext;
+  /** 由 create() 装配，不直接 new。 */
+  private constructor();
+  /**
+   * 装配：paths（建目录）→ logger → CoreContext。
+   * 不加载 wrapper / 不登录——启动阶段由 attachWrapper + login 完成。
+   */
+  static create(opts?: NapukettoCoreOptions): NapukettoCore;
+  /**
+   * 装配 wrapper：wrapperExports → startNapuketto（engine.init + session 创建），
+   * 结果挂到 ctx.wrapper。在 QQ 主进程内调用（boot.cjs 截获 exports 后）。
+   * captured：boot.cjs 拦截 `new` 捕获的 QQ 实例（session/loginService，优先使用）。
+   */
+  attachWrapper(wrapperExports: WrapperNodeApi, env?: BootEnv, captured?: {
+    qqSession?: NodeIQQNTWrapperSession | null;
+    qqLoginService?: unknown;
+  }): WrapperContext;
+  /**
+   * 登录 + session 初始化（wrapper 契约，2026-08-05 实测确认）：
+   * loginService.initConfig → 登录（快速/QR）→ **登录成功后** create session + init
+   * → 等 onOpentelemetryInit(is_init) 完成信号。成功后填 ctx.login。
+   *
+   * 关键（实测）：登录前 create()/init 均断言失败（session 未 init / 干扰 QQ）；
+   * 登录后 QQ 自己 init 并触发 listener.onOpentelemetryInit——我们只需在登录后
+   * create + init 并监听该信号。
+   */
+  login(opts: CoreLoginOptions): Promise<LoginResult>;
+  /**
+   * 替换当前 session（登录后 Proxy 捕获的 QQ 新实例替换自己 create 的无效实例）。
+   * 在 QQ 主进程内由 boot.cjs 调用（登录成功后）。
+   */
+  setSession(session: NodeIQQNTWrapperSession): void;
+  /** QR 登录：QrLoginSession 状态机 + 二维码写缓存目录（无 UI，cli 可打印路径）。 */
+  private loginByQr;
+  /** 停止：日志收尾（资源清理留给 P2 常驻管理）。 */
+  stop(): void;
+}
+//#endregion
+//#region src/infra/config.d.ts
+/** 配置文本格式。 */
+type ConfigFormat = "json" | "toml";
+/**
+ * 校验器最小接口。zod 的 `ZodType<T>`（`parse(data: unknown): T`）天然满足；
+ * 手写校验器包装成该形状即可。
+ */
+interface ConfigSchema<T> {
+  parse: (input: unknown) => T;
+}
+interface ConfigOptions<T> {
+  /** 配置文件绝对路径。 */
+  path: string;
+  /** 校验器（协议 schema 用 zod；kernel 主配置用手写校验器包装）。 */
+  schema: ConfigSchema<T>;
+  /** 默认值：文件缺失时生成并落盘；校验以它为兜底。 */
+  defaults: T;
+  /** 内存初值（已校验对象）：load() 时直接使用，跳过文件读写（全局 TOML 分段的装配方式）。 */
+  seed?: T | undefined;
+  /** 文本格式（缺省按扩展名推断）。 */
+  format?: ConfigFormat | undefined;
+}
+/**
+ * 配置基类。每次 `load()` / `save()` 都经过 schema 校验，
+ * 校验失败抛 `KernelError('INVALID_PARAM')`，不静默吞掉。
+ * - `load()`：seed 存在 → 直接用 seed；否则读文件（缺失落默认值）。
+ * - `save()`：按格式序列化（TOML/JSON）原子写。
+ */
+declare class ConfigBase<T> {
+  readonly path: string;
+  readonly defaults: T;
+  private readonly schema;
+  private readonly format;
+  private readonly seed;
+  private value;
+  constructor(opts: ConfigOptions<T>);
+  /** 当前内存值（只读消费；外部不得直接修改返回对象）。 */
+  get(): T;
+  /**
+   * 加载配置：
+   * - seed 存在 → 直接用 seed（已校验，不读文件；全局 TOML 分段装配方式）；
+   * - 文件缺失 → 写入默认值并落盘（首次运行自动生成），返回默认值；
+   * - 文件存在 → 读取 + 校验，更新内存，返回。
+   */
+  load(): Promise<T>;
+  /** 重新从磁盘加载（外部变更后的热更新入口，P2 配置热更新使用）。 */
+  reload(): Promise<T>;
+  /** 校验并落盘（原子写：临时文件 + rename），随后更新内存。 */
+  save(next: T): Promise<void>;
+  /** 对象 → 文本（TOML/JSON）。 */
+  private serialize;
+  /** 文本 → 对象（TOML/JSON）。 */
+  private deserialize;
+  /** 反序列化 + schema 校验，错误统一包装为 KernelError。 */
+  private parse;
+}
+/** 解析 TOML 文本 → 对象（boot.cjs / 探测脚本等无 ConfigBase 场景复用）。 */
+declare function parseToml(text: string): Record<string, unknown>;
+/** 对象 → TOML 文本（config init 生成全局配置文件等场景）。 */
+declare function stringifyToml(value: Record<string, unknown>): string;
+//#endregion
+//#region src/infra/errors.d.ts
+/**
+ * kernel 类型化错误（ADR-009 / ADR-017）
+ *
+ * apis 层内部解包原生 `{ result, errMsg }`：成功返回纯业务值，失败抛 KernelError。
+ * 协议层只需维护 `KernelErrorCode → 协议错误码` 映射表，不解析错误逻辑。
+ */
+/**
+ * 错误码分类。P1 探测真实错误返回后再增删。
+ * 当前 INVALID_PARAM 也承担基础设施层（配置校验失败等）的错误语义。
+ */
+type KernelErrorCode = "SEND_FAILED" | "PERMISSION_DENIED" | "NOT_FOUND" | "TIMEOUT" | "NOT_LOGIN" | "INVALID_PARAM" | "INVALID_STATE" | "UNKNOWN";
+/**
+ * 全部错误码集合。协议层映射表可据此推导：
+ * `Record<(typeof KERNEL_ERROR_CODES)[number], number>`。
+ */
+declare const KERNEL_ERROR_CODES: readonly ["SEND_FAILED", "PERMISSION_DENIED", "NOT_FOUND", "TIMEOUT", "NOT_LOGIN", "INVALID_PARAM", "INVALID_STATE", "UNKNOWN"];
+/** kernel 类型化错误：apis / 基础设施层抛出的统一错误形态。 */
+declare class KernelError extends Error {
+  readonly code: KernelErrorCode;
+  constructor(message: string, code?: KernelErrorCode, options?: ErrorOptions);
+}
+/** 便捷构造：`kernelError('消息不存在', 'NOT_FOUND', { cause })`。 */
+declare function kernelError(message: string, code?: KernelErrorCode, options?: ErrorOptions): KernelError;
+/** 类型守卫：协议层 catch 统一映射时区分 KernelError 与意外错误。 */
+declare function isKernelError(err: unknown): err is KernelError;
+//#endregion
+//#region src/login/login.d.ts
+/** 登录状态。 */
+type LoginState = "idle" | "waiting_scan" | "scanned" | "logged_in" | "failed";
+/** 二维码数据（png base64 + 解码 url）。 */
+interface QrCodeData {
+  pngBase64: string;
+  qrcodeUrl: string;
+}
+/** selfInfo（登录成功后填写）。 */
+interface SelfInfo {
+  uin: string;
+  uid: string;
+  nick: string;
+}
+/** 快速登录项。 */
+interface LoginListItem {
+  uin: string;
+  uid?: string;
+  nickName?: string;
+  isQuickLogin?: boolean;
+}
+/** QR 登录会话（状态机 + 回调订阅）。 */
+declare class QrLoginSession {
+  private readonly loginService;
+  private state;
+  private listenerId;
+  private self;
+  private readonly qrCodeHandlers;
+  private readonly stateHandlers;
+  constructor(loginService: unknown);
+  /** 当前状态。 */
+  get currentState(): LoginState;
+  /** selfInfo（登录成功后有值）。 */
+  get selfInfo(): SelfInfo | null;
+  /** 订阅二维码（png base64 + url）。返回退订函数。 */
+  onQrCode(cb: (qr: QrCodeData) => void): () => void;
+  /** 订阅状态变化。返回退订函数。 */
+  onStateChange(cb: (state: LoginState) => void): () => void;
+  /** 开始登录：注册监听 → connect → 快速登录（指定账号）或触发二维码。 */
+  start(opts?: {
+    quickUin?: string;
+  }): void;
+  /** 刷新二维码（手动 / 过期自动）。 */
+  refresh(): void;
+  /** 构建登录监听（普通 JS 对象，NAPI 反射）。 */
+  private buildListener;
+  /** 停止：注销监听（登录成功后调用，防重复回调）。 */
+  stop(): void;
+  private setState;
+  private emitQrCode;
+}
+//#endregion
+//#region src/types/services/profile-like-service.d.ts
+/**
+ * NodeIKernelProfileLikeService：资料点赞服务接口面（自研描述，非移植）
+ *
+ * 依据：运行时反射 + wrapper 外部契约（接口签名是 QQ 的外部事实，自研描述其形状，
+ * 零复制实现）。
+ * （接口签名是外部系统的事实，我们自研描述其形状，零复制实现）。
+ * 只收录 apis/profile-like 需要的方法；其余按需探测后补齐。
+ */
+/** 点赞返回（setBuddyProfileLike，说明书参考）。 */
+interface BuddyProfileLikeResult {
+  result: number;
+  errMsg: string;
+  succCounts: number;
+}
+/** 资料点赞服务。 */
+interface NodeIKernelProfileLikeService {
+  addKernelProfileLikeListener(listener: unknown): number;
+  removeKernelProfileLikeListener(listenerId: number): void;
+  /** 点赞（send_like；sourceId=71 赞来源，doLikeCount 次数）。 */
+  setBuddyProfileLike(arg: {
+    friendUid: string;
+    sourceId: number;
+    doLikeCount: number;
+    doLikeTollCount: number;
+  }): Promise<BuddyProfileLikeResult>;
+  isNull(): boolean;
+}
+//#endregion
+//#region src/types/services/profile-service.d.ts
+/** 用户详情（getUserDetailInfoByUin / getUserDetailInfo 返回，宽松自研描述，待探测校准）。 */
+interface UserDetailInfoByUin {
+  detail?: {
+    uid?: string;
+    uin?: string;
+    simpleInfo?: {
+      coreInfo?: {
+        nick?: string;
+        remark?: string;
+      };
+      baseInfo?: {
+        age?: number;
+        qid?: string;
+        sex?: number;
+        longNick?: string;
+      };
+      vasInfo?: {
+        svipFlag?: boolean;
+        yearVipFlag?: boolean;
+        vipLevel?: number;
+      };
+      status?: {
+        status?: number;
+      };
+      relationFlags?: Record<string, unknown>;
+    };
+    commonExt?: {
+      qqLevel?: number;
+      regTime?: number;
+    };
+  };
+  [key: string]: unknown;
+}
+/** 资料服务。 */
+interface NodeIKernelProfileService {
+  addKernelProfileListener(listener: unknown): number;
+  removeKernelProfileListener(listenerId: number): void;
+  /** 设置个性签名（set_self_longnick）。 */
+  setLongNick(longNick: string): Promise<unknown>;
+  /** 设置昵称（set_qq_profile）。 */
+  setNickName(nickName: string): Promise<unknown>;
+  /** 设置头像（set_qq_avatar）。 */
+  setHeader(filePath: string): Promise<GeneralCallResult>;
+  /** 按 uin 获取用户详情（get_stranger_info 第一步）。 */
+  getUserDetailInfoByUin(uin: string): Promise<UserDetailInfoByUin>;
+  /** 按 uid 获取用户详情（get_stranger_info 第二步，noCache=true 强制刷新）。 */
+  getUserDetailInfo(uid: string): Promise<UserDetailInfoByUin>;
+  isNull(): boolean;
+}
+//#endregion
+//#region src/wrapper/probe.d.ts
+/**
+ * 探测 wrapper 运行时：dump session 方法与各 service 方法到 JSON。
+ * 返回探测结果对象；同时写文件（NAPUTO_CFG_DIR/<file>，默认 napuketto-probe.json）。
+ */
+declare function probeRuntime(ctx: WrapperContext, file?: string): Record<string, unknown>;
+//#endregion
+//#region src/wrapper/qq-data-path.d.ts
+/**
+ * QQ 数据根路径解析（P2-1，2026-08-06）
+ *
+ * 从 `getNTUserDataInfoConfig()` 的返回值中提取 QQ 真实数据根路径：
+ * worker（utilityProcess）模式下 loginService 是 new 的，commonPath 必须指向
+ * QQ 真实数据路径才能读到历史账号（cli 的 `.napuketto\default` 读不到，
+ * getLoginList 空，P2-1 实测）。
+ *
+ * 返回值形态可能是 JSON 字符串（对象/数组）或纯路径字符串，此处做宽容解析。
+ */
+/**
+ * QQ 全局数据目录（commonPath / desktopGlobalPath = 数据根/nt_qq/global，
+ * HANDOVER-V6 自建宿主三要素之三，p0-kernel-flow 实证）。
+ *
+ * 防御：已含 nt_qq/global 后缀（worker 环境下 getNTUserDataInfoConfig 可能
+ * 返回完整路径）则不重复拼接，避免 `nt_qq/global/nt_qq/global` 错位。
+ */
+declare function resolveQqGlobalPath(root: string): string;
+//#endregion
+//#region src/wrapper/session-resolver.d.ts
+/**
+ * 复用 QQ 已有 session（P1-4：QQ 已登录，直接拿单例避免重复 init）。
+ * 优先 `NodeIQQNTWrapperSession.get()`；返回 null 时回退 createSession。
+ */
+declare function getExistingSession(ctx: WrapperContext): NodeIQQNTWrapperSession | null;
+/**
+ * 复用 QQ 主 session（P1-4 实测链路）：
+ * `NodeIQQNTStartupSessionWrapper.create()` → `start()` → `getSessionIdList()`（Map
+ * {nt:"nt_3", gpro:"gpro_3"}）→ `NodeIQQNTWrapperSession.getNTWrapperSession("nt_3")`。
+ * 注：实测这些 session 是空壳（核心 service null），真正可用的是 new + init（lifecycle.ts）。
+ */
+declare function getMainSession(ctx: WrapperContext): NodeIQQNTWrapperSession | null;
+//#endregion
+//#region src/wrapper/wrapper-adapters.d.ts
+/** 会话监听器选项。 */
+interface SessionListenerOptions {
+  /** 事件日志回调（默认静默——boot 阶段事件对用户是噪音；调试时可传回调观察）。 */
+  onEvent?: (name: string, ...args: unknown[]) => void;
+}
+/**
+ * 创建会话监听器（默认静默，boot 阶段默认；login 模块接入后可覆盖）。
+ * 回调方法必须存在（NAPI 按方法名反射），但输出与否由调用方决定——
+ * onNTSessionCreate / onOpentelemetryInit 等对用户无信息量，默认不打 stdout。
+ */
+declare function createSessionListener(opts?: SessionListenerOptions): NodeIKernelSessionListener;
+/** 创建登录监听器（占位，登录器接入时填充）。 */
+declare function createLoginListener(): IKernelLoginListener;
+//#endregion
+//#region src/wrapper/wrapper-config.d.ts
+/**
+ * 从 major.node 提取 appid（NapCat parseAppidFromMajorV2 的自研等价实现）。
+ * major.node 含 `QQAppId/` 标记后跟数字（腾讯工具链产物，实测确认）。
+ * 返回 null 表示解析失败（调用方回退硬编码表）。
+ */
+declare function parseAppidFromMajor(majorPath: string): string | null;
+/**
+ * 解析 appid / qua（自研，参考 NapCat QQBasicInfoWrapper 思路但独立实现）：
+ *  1. 优先从 major.node 提取 appid（实测 9.9.33-51802 = 537376818）
+ *  2. 回退硬编码表（旧版 537237765）
+ * majorPath 传 wrapper.node 同目录 major.node；不传则跳过 major 解析。
+ */
+declare function resolveAppidQua(fullVersion: string, majorPath?: string): {
+  appid: string;
+  qua: string;
+};
+/** 生成 engine 桌面配置（wrapper 契约字段）。majorPath 可选（解析 appid/qua）。 */
+declare function buildEngineConfig(fullVersion: string, dataPathGlobal: string, majorPath?: string): EnginInitDesktopConfig;
+/** 生成登录初始化配置（externalVersion: false 与 NapCat 同款，扫码兼容关键）。 */
+declare function buildLoginConfig(appid: string, fullVersion: string, commonPath: string): Record<string, unknown>;
+/** buildSessionConfig 参数。 */
+interface SessionConfigOptions {
+  appid: string;
+  fullVersion: string;
+  selfUin: string;
+  selfUid: string;
+  accountPath: string;
+  downloadPath: string;
+}
+/** 生成 session 初始化配置（登录成功后调用）。 */
+declare function buildSessionConfig(options: SessionConfigOptions): WrapperSessionInitConfig;
+//#endregion
+//#region src/wrapper/wrapper-version.d.ts
+/**
+ * QQ 安装目录探测（ADR-018）
+ *
+ * wrapper.node 路径随 QQ 版本变化：`<安装目录>/versions/<版本>/resources/app/wrapper.node`。
+ * 加载前必须知道版本（登录握手参数 appid/qua 与版本强相关）。
+ *
+ * 已实测确认（2026-08-05，QQ 9.9.31-49919）：
+ * - 目录结构：versions/<9.9.31-49919>/resources/app/wrapper.node
+ * - 版本信息在 versions/<版本>/resources/app/package.json（name=qq-chat / version / buildVersion）
+ * - wrapper.node 是 C++ ABI 模块（非 N-API），导出 INTSessionShell 等符号
+ */
+/** 解析 wrapper.node 绝对路径（按 ADR-018 目录约定）。 */
+declare function resolveWrapperPath(installDir: string, version: string): string;
+/**
+ * 探测指定版本信息（校验 wrapper.node 存在）。
+ * 版本号不匹配目录时抛 NOT_FOUND（明确失败而非静默）。
+ */
+declare function resolveQQVersion(installDir: string, version: string): QQVersionInfo;
+/** 扫描 versions 目录，取可加载的版本列表（按目录名倒序，最新在前）。 */
+declare function listQQVersions(installDir: string): string[];
+/** QQ 版本信息。 */
+interface QQVersionInfo {
+  /** 完整版本号，如 "9.9.31-49919"。 */
+  fullVersion: string;
+  /** 构建号，如 "49919"。 */
+  buildVersion: string;
+  /** wrapper.node 绝对路径。 */
+  wrapperPath: string;
+  /** 登录握手参数（P1 探测脚本产出，暂为空串）。 */
+  appid: string;
+  /** 登录握手参数（P1 探测脚本产出，暂为空串）。 */
+  qua: string;
+}
+//#endregion
+export { type BootEnv, type BuddyCategory, type BuddyReq, type CanonicalElement, ChatType, ConfigBase, type ConfigFormat, type ConfigOptions, type ConfigSchema, type CoreContext, type CoreContextOptions, type CoreLoginOptions, DEFAULT_DATA_ROOT_NAME, type DesktopPathConfig, type DeviceInfo, type DoubtBuddyReq, type DoubtFriendRequestInfo, ElementType, type EnginInitDesktopConfig, type EssenceMsgItem, type ForceFetchClientKeyRetType, type Friend, FriendApi, type FriendCategory, type GeneralCallResult, type GetFileListParam, type GrayTipElement, type GrayTipRevokeElement, GrayTipSubType, type Group, GroupApi, GroupBridge, GroupCache, type GroupCacheOptions, type GroupDetailInfo, type GroupEventChannel, type GroupFileItemInfo, type GroupFolderInfo, type GroupHonorWebInfo, GroupListUpdateType, type GroupListener, type GroupMember, type GroupMemberDataSource, type GroupMemberListChange, type GroupNotify, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, type GroupSpaceInfo, type HonorListItem, KERNEL_ERROR_CODES, KernelError, type KernelErrorCode, type ListenerEvents, type LogLevel, type LoggerOptions, type LoginAccountInfo, type LoginListItem, type LoginResult, type LoginState, MAIN_CONFIG_FILE, MsgApi, MsgBridge, type MsgEventChannel, type MsgListener, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, type NapukettoCoreOptions, type NodeIDependsAdapter, type NodeIDispatcherAdapter, type NodeIGlobalAdapter, type NodeIKernelBuddyService, type NodeIKernelGroupService, type NodeIKernelLoginService, type NodeIKernelMsgService, type NodeIKernelProfileLikeService, type NodeIKernelProfileService, type NodeIKernelRichMediaService, type NodeIKernelSessionListener, type NodeIKernelTicketService, type NodeIQQNTStartupSessionWrapper, type NodeIQQNTWrapperEngine, type NodeIQQNTWrapperSession, type NodeQQNTWrapperUtil, type PathOptions, PathWrapper, type Peer, type PlatformType, ProfileApi, ProfileLikeApi, type QQVersionContext, type QQVersionInfo, type QrCodeData, QrLoginSession, type RDeliveryConfig, type RawElement, type RawMessage, RichMediaApi, type SelfInfo, type SendMessageElement, type SessionConfigOptions, type ShutUpGroupMember, type StartNapukettoOptions, type StrangerInfo, TicketApi, type TipAioOpGrayTipElement, type TipGroupElement, TipGroupElementType, type UserDetailInfoByUin, type VendorType, WebApi, WebHonorType, type WrapperContext, type WrapperNodeApi, type WrapperSessionInitConfig, buildEngineConfig, buildLoginConfig, buildSessionConfig, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, parseAppidFromMajor, parseToml, probeRuntime, quickLogin, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
+//# sourceMappingURL=index.d.mts.map