@napuketto/kernel 0.5.3 → 0.7.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { readFile, rename, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { parse, stringify } from "smol-toml";
@@ -1515,6 +1515,72 @@ var GroupApi = class {
 		} else res = await this.service.removeGroupEssence(param);
 		checkLooseResult(label, res);
 	}
+	/**
+	* 群公告列表（get_group_announcements；getGroupBulletin 返回形状待探测校准，
+	* 兼容 result 数组 / result.bulletins 等宽松提取）。
+	*/
+	async getGroupAnnouncements(groupCode) {
+		let raw;
+		try {
+			raw = await this.service.getGroupBulletin(groupCode);
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`getGroupBulletin 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+		unwrap("getGroupBulletin", toResultNumber(raw.result), raw.errMsg);
+		return extractBulletins(raw.result);
+	}
+	/**
+	* 发群公告（send_group_announcement；imagePath 提供时先 uploadGroupBulletinPic
+	* 再带 picId 发布——两步参数形状均待探测校准）。
+	*/
+	async publishGroupAnnouncement(groupCode, content, imagePath) {
+		let picId;
+		if (imagePath !== void 0 && imagePath !== "") picId = await this.uploadBulletinPic(groupCode, imagePath);
+		try {
+			checkLooseResult("publishGroupBulletin", await this.service.publishGroupBulletin({
+				groupCode,
+				content,
+				...picId !== void 0 ? { picId } : {}
+			}));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`publishGroupBulletin 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+	}
+	/** 删群公告（delete_group_announcement；参数待探测校准）。 */
+	async deleteGroupAnnouncement(groupCode, announcementId) {
+		try {
+			checkLooseResult("deleteGroupBulletin", await this.service.deleteGroupBulletin(groupCode, announcementId));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`deleteGroupBulletin 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+	}
+	/** 专属头衔（set_group_member_special_title；setIdentityTitleInfo 参数待校准）。 */
+	async setMemberSpecialTitle(groupCode, uid, title) {
+		try {
+			checkLooseResult("setIdentityTitleInfo", await this.service.setIdentityTitleInfo(groupCode, uid, title));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`setIdentityTitleInfo 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+	}
+	/** 群头像（set_group_avatar；GroupService.setHeader 参数待校准）。 */
+	async setGroupAvatar(groupCode, imagePath) {
+		try {
+			checkLooseResult("setHeader", await this.service.setHeader(groupCode, imagePath));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`setHeader(group) 调用失败: ${errMsgString$3(e)}`, "UNKNOWN");
+		}
+	}
+	/** 公告图片上传（uploadGroupBulletinPic 返回 picId 待校准，失败原样上抛）。 */
+	async uploadBulletinPic(groupCode, imagePath) {
+		const res = await this.service.uploadGroupBulletinPic(groupCode, imagePath);
+		checkLooseResult("uploadGroupBulletinPic", res);
+		return typeof res?.picId === "string" ? res.picId : "";
+	}
 	/** @all 剩余次数（get_group_at_all_remain）。 */
 	async getGroupRemainAtTimes(groupCode) {
 		const raw = await this.service.getGroupRemainAtTimes(groupCode);
@@ -1526,6 +1592,29 @@ var GroupApi = class {
 		};
 	}
 };
+/** result 字段宽松取数（数字直接用，缺省 0 = 成功语义）。 */
+function toResultNumber(result) {
+	return typeof result === "number" ? result : 0;
+}
+/** 公告列表宽松提取（result 数组 / { bulletins } / { result: 数组 } 兼容，形状待校准）。 */
+function extractBulletins(result) {
+	const candidates = [result];
+	if (result !== null && typeof result === "object") {
+		const rec = result;
+		for (const key of [
+			"bulletins",
+			"announcementList",
+			"result",
+			"list"
+		]) candidates.push(rec[key]);
+	}
+	for (const candidate of candidates) if (Array.isArray(candidate)) return candidate.filter((item) => item !== null && typeof item === "object");
+	return [];
+}
+/** 未知异常 → 消息字符串。 */
+function errMsgString$3(e) {
+	return e instanceof Error ? e.message : String(e);
+}
 /**
 * 从 getGroupDetailInfo 返回提取群详情（兼容三种形状）：
 *  - result 为对象 → 详情直接在其中（最常见）
@@ -1699,6 +1788,28 @@ function sleep$1(ms) {
 		setTimeout(resolve, ms);
 	});
 }
+/** 未知异常 → 消息字符串。 */
+function errMsgString$2(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+/** 语音下载完成判定：有路径且（传输完成或末次轮询）才返回元素，否则 null。 */
+function pttDownloadResult(latest, isLastPoll) {
+	if (latest === void 0) return null;
+	const hasPath = latest.filePath !== void 0 && latest.filePath !== "";
+	const done = latest.transferStatus === 2 || latest.transferStatus === 4;
+	return hasPath && (done || isLastPoll) ? latest : null;
+}
+/** 收藏表情项 → url（字段名待校准，url/imageUrl/emojiUrl 逐个兜底）。 */
+function extractFavEmojiUrls(list) {
+	const out = [];
+	for (const item of list) {
+		if (item === null || typeof item !== "object") continue;
+		const rec = item;
+		const url = rec["url"] ?? rec["imageUrl"] ?? rec["emojiUrl"];
+		if (typeof url === "string" && url !== "") out.push(url);
+	}
+	return out;
+}
 /** 读文件 stat（富媒体发送预处理；文件不存在抛 INVALID_PARAM）。 */
 async function statFile(path, label = "图片") {
 	try {
@@ -1808,6 +1919,9 @@ var MsgApi = class {
 			case "video":
 				out.push(await this.prepareVideoElement(el));
 				break;
+			case "file":
+				out.push(await this.prepareFileElement(el));
+				break;
 			default: out.push(...toSendElements([el]));
 		}
 		return out;
@@ -1928,6 +2042,28 @@ var MsgApi = class {
 		};
 	}
 	/**
+	* FILE 元素预处理（P2-2 预留口子，upload_private/group_file 落地）：
+	* pic/ptt/video 同款 NapCat 式链路——md5 → getRichMediaFilePathForGuild(FILE)
+	* → copyFile → 完整 fileElement。链路模式已验证（三类媒体同构）；fileElement
+	* 字段值（fileSize 字符串形态、fileUuid 空串等）待探测校准。
+	*/
+	async prepareFileElement(el) {
+		const file = await statFile(el.path, "文件");
+		const md5 = await hashFile(el.path, "文件");
+		const fileName = el.name !== void 0 && el.name !== "" ? el.name : basename(el.path);
+		const relPath = await this.placeMediaFile(el.path, ElementType.FILE, md5, fileName);
+		return {
+			elementType: ElementType.FILE,
+			elementId: "",
+			fileElement: {
+				fileName,
+				filePath: relPath,
+				fileSize: String(file.size),
+				fileUuid: ""
+			}
+		};
+	}
+	/**
 	* 富媒体文件放置（PIC/PTT/VIDEO 共用）：md5 + 文件名 → QQ 内部目标路径
 	* （getRichMediaFilePathForGuild）→ util.copyFile 放置 → 返回目标路径。
 	*
@@ -2021,31 +2157,72 @@ var MsgApi = class {
 	* 调用方），完全无路径抛 NOT_FOUND。
 	*/
 	async downloadPtt(msgId, target) {
-		const el = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]));
-		const ptt = el?.pttElement;
-		if (el === null || ptt === void 0) throw kernelError("消息中不包含语音", "NOT_FOUND");
-		const elemId = el.elementId ?? "";
+		const found = await this.pttElementOf(msgId, target);
+		if (found === null) throw kernelError("消息中不包含语音", "NOT_FOUND");
 		await this.service.downloadRichMedia({
 			msgId,
-			elemId,
+			elemId: found.elemId,
 			chatType: target.chatType,
 			downloadType: DOWNLOAD_TYPE_COMMON,
 			thumbSize: THUMB_SIZE_NONE
 		});
 		for (let i = 0; i < PTT_POLL_TIMES; i++) {
 			await sleep$1(PTT_POLL_INTERVAL_MS);
-			const latest = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]))?.pttElement;
-			if (latest === void 0) continue;
-			const done = latest.transferStatus === 2 || latest.transferStatus === 4;
-			if (latest.filePath !== void 0 && latest.filePath !== "" && done) return latest;
-			if (i === 33 && latest.filePath !== void 0 && latest.filePath !== "") return latest;
+			const result = pttDownloadResult(findPttElement(await this.fetchMsgsByMsgId(target, [msgId]))?.pttElement, i === 33);
+			if (result !== null) return result;
 		}
 		throw kernelError("语音下载未完成（超时）", "TIMEOUT");
 	}
+	/** 取消息内语音元素（无则 null；附 elemId 供主动下载）。 */
+	async pttElementOf(msgId, target) {
+		const el = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]));
+		const ptt = el?.pttElement;
+		if (el === null || ptt === void 0) return null;
+		return {
+			elemId: el.elementId ?? "",
+			ptt
+		};
+	}
 	/** 发送输入状态（set_input_status；eventType=1 输入中，0 停止）。 */
 	async setInputStatus(target, eventType) {
 		await this.service.sendShowInputStatusReq(target.chatType, eventType, target.peerUid);
 	}
+	/** 戳一戳发送（send_friend/group_nudge；参数形状待探测校准，失败抛 UNKNOWN）。 */
+	async sendNudge(target, opts) {
+		const param = {
+			receiverUid: opts.receiverUid,
+			callerUid: opts.callerUid,
+			...target.chatType === ChatType.GROUP ? { confId: target.peerUid } : {}
+		};
+		try {
+			checkLooseResult("sendNudge", await this.service.sendNudge(param));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`sendNudge 调用失败: ${errMsgString$2(e)}`, "UNKNOWN");
+		}
+	}
+	/** 会话置顶（set_peer_pin；setContactLocalTop 参数待探测校准）。 */
+	async setContactTop(target, isTop) {
+		try {
+			checkLooseResult("setContactLocalTop", await this.service.setContactLocalTop(target, isTop));
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`setContactLocalTop 调用失败: ${errMsgString$2(e)}`, "UNKNOWN");
+		}
+	}
+	/** 收藏表情列表（get_custom_face_url_list；queryFavEmojiByDesc 形状待校准）。 */
+	async queryFavEmojis() {
+		let raw;
+		try {
+			raw = await this.service.queryFavEmojiByDesc("");
+		} catch (e) {
+			throw kernelError(`queryFavEmojiByDesc 调用失败: ${errMsgString$2(e)}`, "UNKNOWN");
+		}
+		checkLooseResult("queryFavEmojiByDesc", raw);
+		const list = raw.emojiInfoList;
+		if (!Array.isArray(list)) return [];
+		return extractFavEmojiUrls(list);
+	}
 	/**
 	* 发送合并转发（send_group/private_forward_msg）。
 	* buildMultiForwardMsg 组装 MULTI_FORWARD 元素 → 直接作 sendMsg 元素发送。
@@ -2212,6 +2389,76 @@ var ProfileLikeApi = class {
 	}
 };
 //#endregion
+//#region src/apis/recent-contact.ts
+/**
+* RecentContactApi：会话列表语义化 API（P2 批次二，get_peer_pins 数据源）
+*
+* 2026-10-31 实机探测确认 getRecentContactService 有 getRecentContactList /
+* setContactListTop 等方法；返回形状待探测校准（宽松提取）。
+* 置顶数据源：isTop 过滤（ChatType 区分 friend/group 场景）。
+*/
+/** 会话列表拉取条数（覆盖置顶集合足够大；参数值待探测校准）。 */
+const RECENT_CONTACT_FETCH_COUNT = 200;
+/** 会话列表 API：从 session 拿 recent contact service，包装成语义化方法。 */
+var RecentContactApi = class {
+	service;
+	constructor(session) {
+		const service = session.getRecentContactService();
+		if (service === null || service === void 0) throw kernelError("getRecentContactService() 返回空（session 未 init）", "INVALID_STATE");
+		this.service = service;
+	}
+	/** 置顶会话列表（get_peer_pins；getRecentContactList 返回形状待探测校准）。 */
+	async getPinnedContacts() {
+		let raw;
+		try {
+			raw = await this.service.getRecentContactList({ count: RECENT_CONTACT_FETCH_COUNT });
+		} catch (e) {
+			if (isKernelError(e)) throw e;
+			throw kernelError(`getRecentContactList 调用失败: ${errMsgString$1(e)}`, "UNKNOWN");
+		}
+		checkLooseResult("getRecentContactList", raw);
+		return extractPinnedContacts(raw);
+	}
+};
+/** 从返回形状提取置顶会话（result 数组 / 顶层 contacts / 嵌套容器兼容，待校准）。 */
+function extractPinnedContacts(raw) {
+	const candidates = [raw.result, raw];
+	for (const container of [raw.result, raw]) {
+		if (container === null || typeof container !== "object") continue;
+		const rec = container;
+		for (const key of [
+			"contacts",
+			"data",
+			"result",
+			"list"
+		]) candidates.push(rec[key]);
+	}
+	for (const candidate of candidates) {
+		if (!Array.isArray(candidate)) continue;
+		return candidate.flatMap((item) => pinnedOf(item));
+	}
+	return [];
+}
+/** 单条会话 → 置顶项（isTop 为真且场景可判定才产出）。 */
+function pinnedOf(item) {
+	if (item === null || typeof item !== "object") return [];
+	const contact = item;
+	if (contact.isTop !== true || typeof contact.peerUid !== "string") return [];
+	if (contact.chatType === ChatType.GROUP) return [{
+		peerUid: contact.peerUid,
+		scene: "group"
+	}];
+	if (contact.chatType === ChatType.C2C) return [{
+		peerUid: contact.peerUid,
+		scene: "friend"
+	}];
+	return [];
+}
+/** 未知异常 → 消息字符串。 */
+function errMsgString$1(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
 //#region src/apis/richmedia.ts
 /**
 * RichMediaApi：富媒体语义化 API（ADR-009 统一错误语义，P2-14）
@@ -2257,10 +2504,11 @@ var RichMediaApi = class {
 			showOnlinedocFolder: HIDE_ONLINEDOC_FOLDER
 		};
 		const raw = await this.service.getGroupFileList(groupCode, params);
-		if (raw.result !== 0) unwrap("getGroupFileList", raw.result, raw.errMsg);
+		checkLooseResult("getGroupFileList", raw);
 		const list = extractFileList(raw.result);
-		if (parentFolderId === "") return list;
-		return list.filter((item) => item.fileInfo !== void 0 && item.fileInfo.parent === parentFolderId || item.folderInfo !== void 0 && item.folderInfo.folderUid === parentFolderId);
+		const items = list.length > 0 ? list : extractFileList(raw);
+		if (parentFolderId === "") return items;
+		return items.filter((item) => item.fileInfo !== void 0 && item.fileInfo.parent === parentFolderId || item.folderInfo !== void 0 && item.folderInfo.folderUid === parentFolderId);
 	}
 	/** 群文件系统信息（get_group_file_system_info；getGroupFileList 的 groupSpaceResult）。 */
 	async getGroupFileSystemInfo(groupCode) {
@@ -2309,6 +2557,26 @@ var RichMediaApi = class {
 		const raw = await this.service.moveGroupFile(groupCode, [GROUP_FILE_BIZ_TYPE], fileIds, "", targetFolderId);
 		if (raw.result !== 0) unwrap("moveGroupFile", raw.result, raw.errMsg);
 	}
+	/** 重命名群文件夹（rename_group_folder；形态镜像 renameGroupFile，待校准）。 */
+	async renameGroupFolder(groupCode, folderId, newName) {
+		await this.service.renameGroupFolder(groupCode, GROUP_FILE_BIZ_TYPE, folderId, newName, "");
+	}
+	/**
+	* 群文件下载链接（get_group_file_download_url）：getGroupFileList 根列表按
+	* fileId 查找取 url 字段（字段待实机确认）。已知差异：仅根目录可达——
+	* 子目录文件需 parentFolderId 逐层定位，暂不支持。
+	*/
+	async getGroupFileDownloadUrl(groupCode, fileId) {
+		const items = await this.getGroupFileList(groupCode);
+		for (const item of items) {
+			const info = item.fileInfo;
+			if (info !== void 0 && info.fileId === fileId) {
+				if (typeof info.url === "string" && info.url !== "") return info.url;
+				throw kernelError(`群文件 ${fileId} 无下载链接（url 字段缺失，待实机校准）`, "NOT_FOUND");
+			}
+		}
+		throw kernelError(`群文件 ${fileId} 不在根目录或不存在（仅支持根目录查找）`, "NOT_FOUND");
+	}
 	/** 转存群文件（trans_group_file）。 */
 	async transGroupFile(groupCode, fileId) {
 		const raw = await this.service.transGroupFile(groupCode, fileId);
@@ -4899,6 +5167,185 @@ function writeProbeFile(result, file) {
 	}
 }
 //#endregion
+//#region src/wrapper/probe/probe-listener.ts
+/**
+* listener 录制器（批次三前置探测，docs/protocols/milky.md §0.8.1、本包 design.md §10）
+*
+* 动机：无源事件缺的不是方法名而是回调证据——现有 bridge 只注册已知回调名，
+* 原生 listener 回调面之外的派发行为从未被观测。原理：原生 listener 是普通
+* JS 对象 + NAPI 按名反射回调（MsgBridge 模式），用 Proxy get 陷阱构造万能
+* 监听器，原生调什么记什么，不需要预先知道回调名。
+*
+* 开关：NAPUTO_LISTENER_RECORD=1（loader bootstrap 挂起，位置与 runProbePhase 相邻）。
+* 产物：NAPUTO_CFG_DIR/napuketto-listener-record.jsonl（JSONL 追加，注册过程
+* 逐行落盘，原生崩溃保留断点定位肇事服务）。
+*
+* 安全边界：记录函数只序列化入参后回调 onEvent，绝不反向调用原生；录制器与
+* 业务 bridge 并存（addKernelXListener 多监听各自独立 id），不干扰协议链路。
+*/
+/** 默认仪器面：与 5 个无源事件 + sysmsg 样本采集相关的 listener 服务（design.md §10）。 */
+const INSTRUMENTED_SERVICE_GETTERS = [
+	"getMsgService",
+	"getGroupService",
+	"getRecentContactService",
+	"getBdhUploadService",
+	"getOnlineStatusService",
+	"getLockService",
+	"getFileAssistantService",
+	"getBuddyService",
+	"getProfileLikeService",
+	"getNodeMiscService"
+];
+/** 服务 getter 前缀 / 后缀（getMsgService → Msg）。 */
+const GETTER_PREFIX_RE = /^get/;
+const SERVICE_SUFFIX_RE = /Service$/;
+/** listener 注册 / 注销方法名（addKernelMsgListener / 裸 addListener 同规则）。 */
+const ADD_LISTENER_RE = /^add(Kernel)?\w*Listener$/;
+const REMOVE_LISTENER_RE = /^remove(Kernel)?\w*Listener$/;
+/** 服务简称（getMsgService → Msg；getBdhUploadService → BdhUpload）。 */
+function serviceShortName(getter) {
+	return getter.replace(GETTER_PREFIX_RE, "").replace(SERVICE_SUFFIX_RE, "");
+}
+/** 从服务方法面选 listener 注册方法（addKernelMsgListener / 裸 addListener 同规则）。 */
+function findAddMethod(service) {
+	return listMethods(service).find((m) => ADD_LISTENER_RE.test(m)) ?? null;
+}
+/** 从服务方法面选 listener 注销方法（缺失允许——录制器不主动注销）。 */
+function findRemoveMethod(service) {
+	return listMethods(service).find((m) => REMOVE_LISTENER_RE.test(m)) ?? null;
+}
+/**
+* 构造万能监听器：Proxy get 陷阱对任意字符串属性返回记录函数（同时记录原生
+* 查过的名字，即使从未调用）；has / ownKeys 也记录（判定原生按名 Get 还是
+* 枚举发现回调）；非字符串键（Symbol，如 util.inspect 触发）放行默认行为。
+*/
+function createRecordingListener(service, onEvent) {
+	const record = (event, args) => {
+		onEvent({
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			service,
+			event,
+			args
+		});
+	};
+	return new Proxy({}, {
+		get(target, prop, receiver) {
+			if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+			record("<get>", [prop]);
+			return (...args) => {
+				record(prop, [...args].map((a) => serialize(a)));
+			};
+		},
+		has(_target, prop) {
+			if (typeof prop === "string") record("<has>", [prop]);
+			return true;
+		},
+		ownKeys() {
+			record("<ownKeys>", []);
+			return [];
+		}
+	});
+}
+/**
+* 启动 listener 录制：session 十服务 + LoginService（exports 单例）逐服务注册
+* 万能监听器，JSONL 逐行追加。返回摘要；文件路径写入结果（bootstrap 日志用）。
+*
+* ⚠️ 调用时序约束：必须在任何探测（probeRuntime / getMainSession）之前调用——
+* resolveMainFromStartup 会把空壳主 session 写回 ctx.session（session-resolver.ts），
+* 空壳的 service getter 函数仍在但调用返回 null（late probe 61/63 null 的根因）。
+*/
+function startListenerRecording(ctx, file = "napuketto-listener-record.jsonl") {
+	const dir = process.env["NAPUTO_CFG_DIR"] ?? process.cwd();
+	mkdirSync(dir, { recursive: true });
+	const full = join(dir, file);
+	writeFileSync(full, "", "utf8");
+	const emit = (record) => {
+		try {
+			appendFileSync(full, `${JSON.stringify(record)}\n`, "utf8");
+		} catch {}
+	};
+	const registered = {};
+	const session = ctx.session;
+	if (session !== null && session !== void 0) for (const getter of INSTRUMENTED_SERVICE_GETTERS) registered[serviceShortName(getter)] = recordService(session, getter, emit);
+	registered["Login"] = recordLoginService(ctx, emit);
+	return {
+		file: full,
+		registered
+	};
+}
+/** 对单个服务注册万能监听器（getter 失败/null/无 add 方法均记录原因）。 */
+function recordService(session, getter, emit) {
+	const name = serviceShortName(getter);
+	try {
+		const fn = session[getter];
+		if (typeof fn !== "function") return {
+			ok: false,
+			error: `getter 缺失（typeof=${typeof fn}）`
+		};
+		const service = fn.call(session);
+		if (service === null || service === void 0) return {
+			ok: false,
+			error: "null/undefined"
+		};
+		return attachRecordingListener(name, service, emit);
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/** LoginService 单例录制（NodeIKernelLoginService.get()，bot_offline 候选源）。 */
+function recordLoginService(ctx, emit) {
+	const ctor = ctx.exports["NodeIKernelLoginService"];
+	try {
+		if (ctor === null || ctor === void 0 || typeof ctor.get !== "function") return {
+			ok: false,
+			error: "NodeIKernelLoginService.get 缺失"
+		};
+		const service = ctor.get();
+		if (service === null || service === void 0) return {
+			ok: false,
+			error: "null/undefined"
+		};
+		return attachRecordingListener("Login", service, emit);
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/** 在服务实例上挂万能监听器（add 方法自动选取；注册事件即行落盘）。 */
+function attachRecordingListener(name, service, emit) {
+	const addMethod = findAddMethod(service);
+	if (addMethod === null) return {
+		ok: false,
+		error: "无 add*Listener 方法"
+	};
+	const add = service[addMethod];
+	if (typeof add !== "function") return {
+		ok: false,
+		error: `${addMethod} 非函数`
+	};
+	const listener = createRecordingListener(name, emit);
+	const listenerId = add.call(service, listener);
+	emit({
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		service: name,
+		event: "<registered>",
+		args: [{
+			addMethod,
+			removeMethod: findRemoveMethod(service),
+			listenerId: serialize(listenerId)
+		}]
+	});
+	return {
+		ok: true,
+		...typeof listenerId === "number" ? { listenerId } : {}
+	};
+}
+//#endregion
 //#region src/wrapper/wrapper-version.ts
 /**
 * QQ 安装目录探测（ADR-018）
@@ -4956,6 +5403,6 @@ function listQQVersions(installDir) {
 	}).sort().reverse();
 }
 //#endregion
-export { BuddyCache, ChatType, ConfigBase, ConfigError, DEFAULT_DATA_ROOT_NAME, EXIT_CONFIG_INVALID, ElementType, FriendApi, FriendBridge, GrayTipSubType, GroupApi, GroupBridge, GroupCache, GroupListUpdateType, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, KERNEL_ERROR_CODES, KernelError, MAIN_CONFIG_FILE, MsgApi, MsgBridge, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, PathWrapper, ProfileApi, ProfileLikeApi, QrLoginSession, RichMediaApi, TicketApi, TipGroupElementType, WebApi, WebHonorType, buildEngineConfig, buildLoginConfig, buildSessionConfig, configError, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseLogConfig, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
+export { BuddyCache, ChatType, ConfigBase, ConfigError, DEFAULT_DATA_ROOT_NAME, EXIT_CONFIG_INVALID, ElementType, FriendApi, FriendBridge, GrayTipSubType, GroupApi, GroupBridge, GroupCache, GroupListUpdateType, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, KERNEL_ERROR_CODES, KernelError, MAIN_CONFIG_FILE, MsgApi, MsgBridge, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, PathWrapper, ProfileApi, ProfileLikeApi, QrLoginSession, RecentContactApi, RichMediaApi, TicketApi, TipGroupElementType, WebApi, WebHonorType, buildEngineConfig, buildLoginConfig, buildSessionConfig, configError, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createRecordingListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseLogConfig, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startListenerRecording, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
 
 //# sourceMappingURL=index.mjs.map