@napuketto/kernel 0.0.1 → 0.0.2

package/dist/index.d.mts

@@ -287,631 +287,929 @@ interface NodeIKernelMsgService {
   }): 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;
+//#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;
 }
-/** 可疑好友申请（getDoubtBuddyReq 返回的 doubtList 成员，说明书参考）。 */
-interface DoubtBuddyReq {
-  uid: string;
-  nick?: string;
-  source?: string;
-  reason?: string;
-  msg?: string;
-  groupCode?: string;
-  reqTime?: string;
-  [key: string]: unknown;
+/** 踢人请求（set_group_kick 的 kickMemberV2 参数，说明书参考）。 */
+interface KickMemberV2Req {
+  groupCode: string;
+  kickFlag: number;
+  kickList: KickMemberInfo[];
+  kickListUids: string[];
+  kickMsg: string;
 }
-/** 好友服务：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;
+/** @all 剩余次数（getGroupRemainAtTimes 返回）。 */
+interface GroupRemainAtTimes {
+  canAtAll: boolean;
+  remainAtAllCountForUin: number;
+  remainAtAllCountForGroup: number;
+  atTimesMsg: string;
+  canNotAtAllMsg: string;
 }
-//#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;
+/** 群通知类型（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 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 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 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;
+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;
   };
-  thumb_config: {
-    maxSide: 324;
-    minSide: 48;
-    longLimit: 6;
-    density: 2;
+  user1?: {
+    uid: string;
+    nickName: string;
+  };
+  user2?: {
+    uid: string;
+    nickName: string;
   };
+  actionTime?: string;
+  postscript?: string;
+  warningTips?: string;
 }
-/** 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;
+/** 禁言成员（getGroupShutUpMemberList 返回项，说明书参考，待探测校准）。 */
+interface ShutUpGroupMember {
+  uid: string;
+  qid: string;
+  uin: string;
+  nick: string;
+  remark: string;
+  cardName: string;
+  shutUpTime: number;
+  memberSpecialTitle?: string;
 }
-/** NodeIQQNTWrapperEngine 构造器（含静态 get()）。 */
-type NodeIQQNTWrapperEngineCtor = new () => NodeIQQNTWrapperEngine & {
-  get(): NodeIQQNTWrapperEngine;
-};
-/** desktopPathConfig 结构。 */
-interface DesktopPathConfig {
-  account_path: 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;
 }
-/** 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[];
+/** 群详情（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;
 }
-/** deviceInfo 结构。 */
-interface DeviceInfo {
-  guid: string;
-  buildVer: string;
-  localId: number;
-  devName: string;
-  devType: string;
-  vendorName: string;
-  osVer: string;
-  vendorOsName: string;
-  setMute: boolean;
-  vendorType: VendorType;
+/** 群成员（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;
 }
-/** 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;
+/** 群服务：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>;
 }
-/** NodeIQQNTWrapperSession 构造器（含静态 get / getNTWrapperSession / create）。 */
-type NodeIQQNTWrapperSessionCtor = {
-  new (): NodeIQQNTWrapperSession;
-  get(): NodeIQQNTWrapperSession;
-  getNTWrapperSession(name: string): NodeIQQNTWrapperSession;
-  create(): NodeIQQNTWrapperSession;
+//#endregion
+//#region src/types/listeners/group.d.ts
+/** 群列表更新类型（说明书参考，值待探测校准）。 */
+declare const GroupListUpdateType: {
+  /** 全量更新（groupList 为完整列表）。 */
+  readonly ALL: 0;
+  /** 增量更新（合并到现有缓存）。 */
+  readonly PARTIAL: 1;
 };
-/** 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;
+type GroupListUpdateType = (typeof GroupListUpdateType)[keyof typeof GroupListUpdateType];
+/** 成员数据来源（onMemberInfoChange 第二参，说明书参考）。 */
+declare const GroupMemberDataSource: {
+  /** 本地缓存。 */
+  readonly CACHE: 0;
+  /** 网络拉取。 */
+  readonly NETWORK: 1;
 };
-/** 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;
+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;
 }
-/** NodeIKernelLoginService 构造器（含静态 get）。 */
-type NodeIKernelLoginServiceCtor = new () => NodeIKernelLoginService & {
-  get(): NodeIKernelLoginService;
+/** 群服务（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;
 };
-/** NodeIO3MiscService：O3 杂项服务。 */
-interface NodeIO3MiscService {
-  get(): NodeIO3MiscService;
-  addO3MiscListener(listener: unknown): number;
+//#endregion
+//#region src/types/listeners/msg.d.ts
+/** 消息已读上报（peer + 已读 seq）。 */
+interface MsgReadReportItem {
+  peer: unknown;
+  readSeq: string;
 }
-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;
+/** 消息回执（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/apis/friend.d.ts
-/** 好友条目（uid + 昵称/备注，昵称由 buddy service 缓存补全）。 */
-interface Friend {
-  uid: string;
-  uin: string;
-  nickname: string;
-  remark: string;
-}
-/** 带分类的好友列表项（get_friends_with_category 返回）。 */
-interface FriendCategory {
+//#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/types/services/buddy-service.d.ts
+/** 好友列表分类（getBuddyListV2 返回，说明书参考）。 */
+interface BuddyCategory {
   categoryId: number;
   categorySortId: number;
-  categoryName: string;
-  categoryMbCount: number;
+  categroyName: string;
+  categroyMbCount: number;
   onlineCount: number;
-  buddyList: Friend[];
+  buddyUids: string[];
 }
-/** 可疑好友申请（OB11 结构，get_doubt_friends_add_request 返回）。 */
-interface DoubtFriendRequestInfo {
-  flag: string;
-  uin: number;
+/** 好友申请（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;
-  group_code?: string;
-  time?: string;
-  type: "doubt";
-}
-/** FriendApi 构造选项。 */
-interface FriendApiOptions {
-  /** uid→uin 转换器（通常注入 GroupApi.uidToUin）；缺省 uin 退化为 uid。 */
-  uidToUin?: (uids: string[]) => Promise<Map<string, string>>;
+  groupCode?: string;
+  reqTime?: string;
+  [key: string]: unknown;
 }
-/** 好友 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;
-  /** 判断是否好友。 */
+/** 好友服务：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 应答前查找匹配项）。 */
-  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;
+  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/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;
+//#region src/types/services/profile-like-service.d.ts
+/**
+ * NodeIKernelProfileLikeService：资料点赞服务接口面（自研描述，非移植）
+ *
+ * 依据：运行时反射 + wrapper 外部契约（接口签名是 QQ 的外部事实，自研描述其形状，
+ * 零复制实现）。
+ * （接口签名是外部系统的事实，我们自研描述其形状，零复制实现）。
+ * 只收录 apis/profile-like 需要的方法；其余按需探测后补齐。
+ */
+/** 点赞返回（setBuddyProfileLike，说明书参考）。 */
+interface BuddyProfileLikeResult {
+  result: number;
+  errMsg: string;
+  succCounts: number;
 }
-/** @all 剩余次数（getGroupRemainAtTimes 返回）。 */
-interface GroupRemainAtTimes {
-  canAtAll: boolean;
-  remainAtAllCountForUin: number;
-  remainAtAllCountForGroup: number;
-  atTimesMsg: string;
-  canNotAtAllMsg: string;
+/** 资料点赞服务。 */
+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;
 }
-/** 群通知类型（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;
+//#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;
+    };
   };
-  actionTime?: string;
-  postscript?: string;
-  warningTips?: string;
+  [key: string]: unknown;
 }
-/** 禁言成员（getGroupShutUpMemberList 返回项，说明书参考，待探测校准）。 */
-interface ShutUpGroupMember {
-  uid: string;
-  qid: string;
-  uin: string;
-  nick: string;
-  remark: string;
-  cardName: string;
-  shutUpTime: number;
-  memberSpecialTitle?: string;
+/** 资料服务。 */
+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;
 }
-/** 群列表项（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;
+//#endregion
+//#region src/types/services/richmedia-service.d.ts
+/** 群文件列表参数（getGroupFileList，说明书参考）。 */
+interface GetFileListParam {
+  sortType: number;
+  fileCount: number;
+  startIndex: number;
+  sortOrder: number;
+  showOnlinedocFolder: number;
 }
-/** 群详情（getGroupDetailInfo 返回，说明书参考）。 */
-interface GroupDetailInfo {
-  groupCode: string;
-  groupUin: string;
-  ownerUin: string;
-  ownerUid?: string;
-  groupName: string;
-  memberNum: number;
-  maxMemberNum: number;
-  remarkName?: string;
-  isTop?: boolean;
-  groupCreateTime?: 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;
 }
-/** 群成员（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;
+/** 群文件夹项（getGroupFileList 返回的 folderInfo，说明书参考，待探测校准）。 */
+interface GroupFolderInfo {
+  folderId: string;
+  folderName: string;
+  folderPath?: string;
+  folderUid?: string;
   [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;
+/** 群文件空间信息（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_system_msg / set_group_add_request 共用；列表可能走 listener，宽松解包）。 */
-  getSingleScreenNotifies(doubt: boolean, startSeq: string, count: number): Promise<GeneralCallResult & {
+  /** 群文件列表（get_group_root_files / get_group_files_by_folder）。 */
+  getGroupFileList(groupCode: string, params: GetFileListParam): Promise<GeneralCallResult & {
+    groupSpaceResult?: GroupSpaceInfo;
     result?: unknown;
   }>;
-  /** 禁言成员列表（get_group_shut_list；同 listener 风格，宽松解包）。 */
-  getGroupShutUpMemberList(groupCode: string): Promise<GeneralCallResult & {
-    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[];
   }>;
-  /** 处理群请求（set_group_add_request 应答；postscript 空值可能导致失败，默认空格）。 */
-  operateSysNotify(doubt: boolean, operateMsg: {
-    operateType: NTGroupRequestOperateTypes;
-    targetMsg: {
-      seq: string;
-      type: GroupNotifyMsgType;
-      groupCode: string;
-      postscript: string;
-    };
-  }): Promise<void>;
+  isNull(): boolean;
+}
+//#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/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/apis/group.d.ts
@@ -986,61 +1284,6 @@ declare class GroupNotifyApi {
   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 {
@@ -1112,36 +1355,7 @@ declare class MsgApi {
   }): 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
+//#region src/apis/stranger-info.d.ts
 /** 陌生人信息（get_stranger_info 返回）。 */
 interface StrangerInfo {
   user_id: number;
@@ -1160,6 +1374,8 @@ interface StrangerInfo {
   status: number;
   login_days: number;
 }
+//#endregion
+//#region src/apis/profile.d.ts
 /** 资料 API：从 session 拿 profile service，包装成语义化方法。 */
 declare class ProfileApi {
   private readonly service;
@@ -1183,78 +1399,6 @@ declare class ProfileLikeApi {
   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 {
@@ -1292,6 +1436,19 @@ declare class RichMediaApi {
   transGroupFile(groupCode: string, fileId: string): Promise<void>;
 }
 //#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/webapi.d.ts
 /** 精华消息项（digest_list 返回 data.msg_list 成员，说明书参考）。 */
 interface EssenceMsgItem {
@@ -1379,6 +1536,7 @@ declare class NTEventChannel<L extends ListenerShape, Name extends string> {
   readonly serviceName: Name;
   private readonly emitter;
   private readonly errorHandlers;
+  private readonly anyHandlers;
   constructor(serviceName: Name);
   /**
    * 订阅事件：返回 unsubscribe（只注销该 handler，不影响其他订阅者）。
@@ -1399,58 +1557,16 @@ declare class NTEventChannel<L extends ListenerShape, Name extends string> {
    * listener 派发（Node 语义）——改为快照数组逐个 try/catch，保证「单个订阅者
    * 异常不打断派发」（协议翻译层异常不饿死缓存维护等其他订阅者）。
    */
+  /**
+   * 订阅所有事件（IPC 子进程模式整通道转发用：事件名 `"${service}/${method}"`
+   * 经 handler 首参透出，args 原样透传）。返回退订函数。
+   */
+  onAny(handler: (event: string, ...args: unknown[]) => void): () => void;
   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">;
@@ -1469,34 +1585,6 @@ declare class GroupBridge {
   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">;
@@ -1574,8 +1662,120 @@ declare class GroupCache {
   private dedupe;
 }
 //#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/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/infra/paths.d.ts
-/** 默认数据根目录名（用户目录下，程序目录可能只读，见 ADR-016）。 */
+/** 默认数据根目录名（项目根下，2026-08-08 用户拍板：不放用户目录）。 */
 declare const DEFAULT_DATA_ROOT_NAME = ".napuketto";
 /** 全局配置文件名。 */
 declare const MAIN_CONFIG_FILE = "napuketto.toml";
@@ -1586,7 +1786,8 @@ interface PathOptions {
   account?: string;
 }
 /**
- * 解析数据根：显式参数 > 环境变量 > 用户目录默认。
+ * 解析数据根：显式参数 > 环境变量 > `<项目根>/.napuketto`（默认）> 用户目录兜底（裸脚本）。
+ * 支持 `~` 前缀（展开为用户主目录）与相对路径（相对 cwd 解析）。
  * 返回绝对路径。独立导出便于 cli / 探测脚本复用。
  */
 declare function resolveDataRoot(dataRoot?: string): string;
@@ -1600,9 +1801,8 @@ interface ConfigPathOptions {
  *
  * 优先级：
  *  1. `NAPKETTO_CONFIG` 环境变量（显式指定完整路径，任意场景可用）
- *  2. 入口模块向上找 `pnpm-workspace.yaml`（monorepo 开发场景，即项目根）
- *  3. 运行目录（cwd）向上找 `pnpm-workspace.yaml` / `package.json`（发布后用户项目）
- *  4. 数据根兜底 `<dataRoot>/napuketto.toml`（旧行为兼容）
+ *  2. 项目根探测（入口模块向上找 pnpm-workspace.yaml → cwd 向上找，见 resolveProjectRoot）
+ *  3. 数据根兜底 `<dataRoot>/napuketto.toml`（旧行为兼容）
  *
  * 返回绝对路径。独立导出便于 cli / loader 装配链复用。
  */
@@ -1741,18 +1941,7 @@ interface StartNapukettoOptions {
   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>;
+//#region src/login/login-connect.d.ts
 /** 登录结果（QR 或快速登录）。 */
 interface LoginResult {
   uin: string;
@@ -1785,11 +1974,77 @@ declare function quickLogin(ctx: WrapperContext, opts: {
   uin?: string;
   timeoutMs?: number;
 }): Promise<LoginResult>;
+//#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>;
+/** 登录连接 + 快速登录（quickLogin 等）已拆到 login-connect.ts（见文件头 re-export）。 */
 /** session 初始化（4 参全为普通 JS 对象，等 init 完成信号）。 */
 declare function initAndStartSession(ctx: WrapperContext, config: WrapperSessionInitConfig, listener: NodeIKernelSessionListener, opts: {
   timeoutMs?: number;
 }): Promise<void>;
 //#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/context.d.ts
 interface CoreContextOptions {
   /** pino logger（console + 可选文件，由装配层创建）。 */
@@ -1812,30 +2067,6 @@ interface CoreContext {
 /** 创建装配根（初始 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）。 */
@@ -1847,6 +2078,15 @@ interface NapukettoCoreOptions {
   /** 是否输出 console，默认 true。 */
   consoleLog?: boolean;
 }
+/** 登录进度（IPC 子进程模式经 onLoginProgress 转发；koishi 插件展示二维码/状态用）。 */
+interface LoginProgress {
+  /** 登录状态（QR 状态机）。 */
+  state: LoginState;
+  /** 二维码数据（state=waiting_scan 时有）。 */
+  qr?: QrCodeData;
+  /** 登录成功 selfInfo（state=logged_in 时有）。 */
+  selfInfo?: SelfInfo;
+}
 /** login 参数。 */
 interface CoreLoginOptions {
   /** appid（登录握手，兜底 537237765）。 */
@@ -1859,6 +2099,8 @@ interface CoreLoginOptions {
   qrFallback?: boolean;
   /** QR 二维码图片保存路径（默认缓存目录 qrcode.png）。 */
   qrCodePath?: string;
+  /** 登录进度回调（QR 阶段：二维码数据 + 状态变化）。子进程 IPC 模式转发用。 */
+  onLoginProgress?: (progress: LoginProgress) => void;
 }
 /**
  * 核心装配器：持有 CoreContext，负责启动/停止编排。
@@ -1904,227 +2146,7 @@ declare class NapukettoCore {
   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
+//#region src/wrapper/probe/probe.d.ts
 /**
  * 探测 wrapper 运行时：dump session 方法与各 service 方法到 JSON。
  * 返回探测结果对象；同时写文件（NAPUTO_CFG_DIR/<file>，默认 napuketto-probe.json）。
@@ -2248,5 +2270,5 @@ interface QQVersionInfo {
   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 };
+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 LoginProgress, 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