@napuketto/kernel 0.5.3 → 0.7.0

package/dist/index.cjs

@@ -1541,6 +1541,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);
@@ -1552,6 +1618,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 为对象 → 详情直接在其中（最常见）
@@ -1725,6 +1814,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 {
@@ -1834,6 +1945,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;
@@ -1954,6 +2068,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 : (0, node_path.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 放置 → 返回目标路径。
 	*
@@ -2047,31 +2183,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 元素发送。
@@ -2238,6 +2415,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）
@@ -2283,10 +2530,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) {
@@ -2335,6 +2583,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);
@@ -4925,6 +5193,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 = node_process.default.env["NAPUTO_CFG_DIR"] ?? node_process.default.cwd();
+	(0, node_fs.mkdirSync)(dir, { recursive: true });
+	const full = (0, node_path.join)(dir, file);
+	(0, node_fs.writeFileSync)(full, "", "utf8");
+	const emit = (record) => {
+		try {
+			(0, node_fs.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）
@@ -5012,6 +5459,7 @@ exports.PathWrapper = PathWrapper;
 exports.ProfileApi = ProfileApi;
 exports.ProfileLikeApi = ProfileLikeApi;
 exports.QrLoginSession = QrLoginSession;
+exports.RecentContactApi = RecentContactApi;
 exports.RichMediaApi = RichMediaApi;
 exports.TicketApi = TicketApi;
 exports.TipGroupElementType = TipGroupElementType;
@@ -5025,6 +5473,7 @@ exports.createCoreContext = createCoreContext;
 exports.createLifecycleSessionListener = createSessionListener;
 exports.createLogger = createLogger;
 exports.createLoginListener = createLoginListener;
+exports.createRecordingListener = createRecordingListener;
 exports.createSession = createSession;
 exports.createSessionListener = createSessionListener;
 exports.createWrapper = createWrapper;
@@ -5052,6 +5501,7 @@ exports.resolveQQVersion = resolveQQVersion;
 exports.resolveQqGlobalPath = resolveQqGlobalPath;
 exports.resolveQqUserDataRoot = resolveQqUserDataRoot;
 exports.resolveWrapperPath = resolveWrapperPath;
+exports.startListenerRecording = startListenerRecording;
 exports.startNapuketto = startNapuketto;
 exports.startSession = startSession;
 exports.stringifyToml = stringifyToml;