@napuketto/kernel 0.5.2 → 0.6.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);
@@ -4446,7 +4714,6 @@ function resolveMainFromStartup(ctx) {
 *
 * - serialize：深度受限序列化（BigInt 转字符串，Map/Set/Promise 展开，循环引用防护）
 * - tryShape：解析 service getter 返回形状
-* - shapeKeyGetters：探测 service 关键数据 getter 返回形状
 */
 /** 序列化深度上限（循环引用/深层对象防护）。 */
 const MAX_SERIALIZE_DEPTH = 4;
@@ -4520,15 +4787,6 @@ function tryShape(session, getter) {
 		return "[error]";
 	}
 }
-/** 数据 getter 方法名模式（探测返回形状用）。 */
-const DATA_GETTER_RE = /^(get|query|fetch|load)/i;
-/** 探测 service 的关键数据 getter 返回形状（取前几个无参调用）。 */
-function shapeKeyGetters(session, serviceMethods) {
-	const out = {};
-	const candidates = serviceMethods.filter((m) => DATA_GETTER_RE.test(m) && !m.endsWith("Listener"));
-	for (const m of candidates.slice(0, 8)) out[m] = tryShape(session, m);
-	return out;
-}
 //#endregion
 //#region src/wrapper/probe/probe-utils.ts
 /**
@@ -4586,29 +4844,6 @@ function tryCall(obj, name) {
 function isServiceGetter(name) {
 	return name.startsWith("get") && name.endsWith("Service");
 }
-/** 非空服务实例计数（逐个调用 get*Service 数非空返回；候选可用度评分）。
-*  自建宿主下 QQ 主 session 未被 init，get*Service 恒 null（2026-10-31 实测
-*  napuketto-probe-late.json），kernel 自建 session 服务可用——主目标按此评分选取。 */
-function countNonNullServices(session) {
-	if (session === null || session === void 0) return 0;
-	let count = 0;
-	for (const name of listMethods(session)) {
-		if (!isServiceGetter(name)) continue;
-		const call = tryCall(session, name);
-		if (call.ok && call.value !== null && call.value !== void 0) count += 1;
-	}
-	return count;
-}
-/** 主探测目标选取：服务实例最多者优先，评分并列保持候选顺序（主 session 在前）。 */
-function pickPrimaryCandidate(candidates) {
-	let best = candidates[0];
-	for (const candidate of candidates.slice(1)) if (best !== void 0 && candidate.serviceNonNull > best.serviceNonNull) best = candidate;
-	return best ?? {
-		source: "own-create",
-		session: null,
-		serviceNonNull: 0
-	};
-}
 //#endregion
 //#region src/wrapper/probe/probe-services.ts
 /** 探测关键 export 构造器方法（get/create/getNTWrapperSession 等）。 */
@@ -4859,89 +5094,76 @@ function probeCreatedChain(ctx, created) {
 function findMainProbeId(sessionIds) {
 	return sessionIds.find((id) => id.startsWith("nt_")) ?? sessionIds[0];
 }
-/** 探测 session 与 service 方法（候选中选服务实例最多者为主目标）。
-*  自建宿主下 QQ 主 session 未被 init（get*Service 恒 null，2026-10-31 实测
-*  napuketto-probe-late.json 全服务空），kernel 自建 session 已带 adapter init
-*  服务可用——主目标按 countNonNullServices 评分选取，并列保持主 session 优先。 */
-function probeSession(ctx) {
-	const out = {};
-	const candidates = collectProbeCandidates(ctx).map(scoreCandidate);
-	const primary = pickPrimaryCandidate(candidates);
-	out["sessionSource"] = primary.source;
-	out["session"] = sessionFace(primary.session);
-	if (primary.session !== null && primary.session !== void 0) out["services"] = collectServiceGetters(primary.session);
-	if (candidates.length > 1) out["sessionAlternates"] = alternateFaces(candidates, primary);
-	return out;
-}
-/** 候选评分（非空服务实例数）。 */
-function scoreCandidate(candidate) {
-	return {
-		...candidate,
-		serviceNonNull: countNonNullServices(candidate.session)
-	};
-}
-/** 落选候选的概要面（方法数 + 评分，诊断用）。 */
-function alternateFaces(candidates, primary) {
-	return candidates.filter((candidate) => candidate !== primary).map((candidate) => ({
-		source: candidate.source,
-		methodCount: listMethods(candidate.session).length,
-		serviceNonNull: candidate.serviceNonNull
-	}));
-}
-/** 收集候选 session：kernel 自建 session + QQ 主 session（若可得）。
+/** 探测 session 与 service 方法名面。
+*  主目标 = ctx.session 快照（kernel 自建就绪 session），缺省回退 QQ 主 session；
+*  自建宿主下主 session 未被 init（get*Service 恒 null，2026-10-31 实测）。
 *  ⚠️ 先快照 ctx.session 再枚举主 session——getMainSession 有 P1-4 遗留副作用
-*  （resolveMainFromStartup 把空壳主 session 写回 ctx.session，session-resolver.ts），
-*  后读会把就绪的自建 session 读成空壳（2026-10-31 实测：候选退化为单主 session）。 */
-function collectProbeCandidates(ctx) {
+*  （resolveMainFromStartup 把空壳主 session 写回 ctx.session，session-resolver.ts）。
+*  ⚠️ names-only：不对服务实例做无参 shape 调用——活 session 上无参调原生方法
+*  = 访问违例 0xC0000005（2026-10-31 实测崩溃，tryShape 捕不住原生段错误）。 */
+/** 非空判定（null / undefined 均视为缺省）。 */
+function hasValue(value) {
+	return value !== null && value !== void 0;
+}
+function probeSession(ctx, persist) {
+	const out = {};
 	const own = ctx.session;
-	const candidates = [];
-	pushMainCandidate(ctx, candidates);
-	pushOwnCandidate(own, candidates);
-	return candidates;
+	const main = tryMainSession(ctx);
+	const primary = hasValue(own) ? own : main;
+	out["sessionSource"] = hasValue(own) ? "own-create" : "mainSession";
+	out["session"] = sessionFace(primary);
+	assignServices(out, primary, persist);
+	assignAlternates(out, own, main);
+	return out;
 }
-/** 并入 QQ 主 session 候选（枚举失败静默跳过）。 */
-function pushMainCandidate(ctx, out) {
+/** 并入主目标的服务方法名面（主目标缺省时跳过）。 */
+function assignServices(out, primary, persist) {
+	if (!hasValue(primary)) return;
+	out["services"] = collectServiceGetters(primary, persist);
+}
+/** 并入落选候选概要（仅主目标为自建 session 时记录主 session 方法数，诊断用）。 */
+function assignAlternates(out, own, main) {
+	if (!hasValue(own) || !hasValue(main)) return;
+	out["sessionAlternates"] = [{
+		source: "mainSession(getNTWrapperSession)",
+		methodCount: listMethods(main).length
+	}];
+}
+/** QQ 主 session（getMainSession 有写回 ctx.session 的副作用——调用前须已快照）。 */
+function tryMainSession(ctx) {
 	try {
-		const main = getMainSession(ctx);
-		if (main !== null) out.push({
-			source: "mainSession(getNTWrapperSession)",
-			session: main
-		});
-	} catch {}
-}
-/** 并入 kernel 自建 session 候选（与已有候选同一实例时去重）。 */
-function pushOwnCandidate(own, out) {
-	if (own === null || own === void 0) return;
-	if (out.some((candidate) => candidate.session === own)) return;
-	out.push({
-		source: "own-create",
-		session: own
-	});
+		return getMainSession(ctx);
+	} catch {
+		return null;
+	}
 }
-/** 收集 session 的 get*Service getter 方法面与返回形状。 */
-function collectServiceGetters(session) {
-	const getters = listMethods(session).filter((m) => m.startsWith("get") && m.endsWith("Service"));
+/** 收集 session 的 get*Service 方法名面（names-only，不做 shape 无参调用）。
+*  每个服务完成即 persist 一次——活 session 上个别 getter 若触发原生崩溃，
+*  文件里留下最后一个成功项，精确定位肇事 getter。 */
+function collectServiceGetters(session, persist) {
 	const services = {};
-	for (const getter of getters) services[getter] = probeServiceGetter(session, getter);
+	for (const getter of listMethods(session).filter(isServiceGetter)) {
+		services[getter] = probeServiceGetter(session, getter);
+		persist?.();
+	}
 	return services;
 }
-/** 探测单个 getter：成功记录方法面/形状，失败记录错误。 */
+/** 探测单个 getter：成功记录方法名面（不调用服务方法），失败记录错误。 */
 function probeServiceGetter(session, getter) {
 	const call = tryCall(session, getter);
 	if (!(call.ok && call.value)) return {
 		error: call.error ?? "null/undefined",
 		ok: call.ok
 	};
-	const methods = listMethods(call.value);
 	return {
-		methods,
-		ownKeys: Object.getOwnPropertyNames(call.value).slice(0, 20),
-		shapes: shapeKeyGetters(call.value, methods)
+		methods: listMethods(call.value),
+		ownKeys: Object.getOwnPropertyNames(call.value).slice(0, 20)
 	};
 }
 /**
-* 探测 wrapper 运行时：dump session 方法与各 service 方法到 JSON。
+* 探测 wrapper 运行时：dump session 方法与各 service 方法名到 JSON。
 * 返回探测结果对象；同时写文件（NAPUTO_CFG_DIR/<file>，默认 napuketto-probe.json）。
+* 服务枚举逐项增量落盘（persist）——活 session 上原生崩溃时文件保留断点。
 */
 function probeRuntime(ctx, file = "napuketto-probe.json") {
 	const result = {
@@ -4951,9 +5173,15 @@ function probeRuntime(ctx, file = "napuketto-probe.json") {
 		exportCtors: probeExportCtors(ctx),
 		engineCalls: probeEngineCalls(ctx),
 		loginService: probeLoginService(ctx),
-		startup: probeStartup(ctx),
-		...probeSession(ctx)
+		startup: probeStartup(ctx)
 	};
+	const persist = () => writeProbeFile(result, file);
+	Object.assign(result, probeSession(ctx, persist));
+	writeProbeFile(result, file);
+	return result;
+}
+/** 探测结果落盘（增量与最终共用；最终写入后记 probeFile 路径）。 */
+function writeProbeFile(result, file) {
 	try {
 		const dir = node_process.default.env["NAPUTO_CFG_DIR"] ?? node_process.default.cwd();
 		(0, node_fs.mkdirSync)(dir, { recursive: true });
@@ -4961,9 +5189,8 @@ function probeRuntime(ctx, file = "napuketto-probe.json") {
 		(0, node_fs.writeFileSync)(full, JSON.stringify(result, null, 2), "utf8");
 		result["probeFile"] = full;
 	} catch (e) {
-		result["probeFileError"] = e instanceof Error ? e.message : String(e);
+		result["probeFileError"] = errMsgString(e);
 	}
-	return result;
 }
 //#endregion
 //#region src/wrapper/wrapper-version.ts
@@ -5053,6 +5280,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;