@napuketto/kernel 0.0.4 → 0.0.6

package/dist/index.mjs

@@ -1,12 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, extname, join, resolve } from "node:path";
+import { readFile, rename, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
 import { parse, stringify } from "smol-toml";
 import process from "node:process";
 import pino from "pino";
 import pinoPretty from "pino-pretty";
 import { homedir, hostname } from "node:os";
 import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
 import { get } from "node:https";
 import { EventEmitter } from "node:events";
 //#region src/infra/errors.ts
@@ -518,24 +519,32 @@ var FriendApi = class {
 	}
 	/** 单项转换：DoubtBuddyReq → OB11 结构（可选字段条件赋值，exactOptionalPropertyTypes）。 */
 	toDoubtFriendRequestInfo(item, uinMap) {
-		const info = {
-			flag: item.uid,
-			uin: Number(uinMap.get(item.uid) ?? item.uid),
-			type: "doubt"
-		};
-		if (item.nick !== void 0) info.nick = item.nick;
-		if (item.source !== void 0) info.source = item.source;
-		if (item.reason !== void 0) info.reason = item.reason;
-		if (item.msg !== void 0) info.msg = item.msg;
-		if (item.groupCode !== void 0) info.group_code = item.groupCode;
-		if (item.reqTime !== void 0) info.time = item.reqTime;
-		return info;
+		return toDoubtFriendRequestInfo(item, uinMap);
 	}
 	/** 处理可疑好友申请（set_doubt_friends_add_request；uid=flag）。 */
 	handleDoubtFriendRequest(uid) {
 		this.service.approvalDoubtBuddyReq(uid, "", "");
 	}
 };
+/** 可选字段条件赋值（undefined 跳过，兼容 exactOptionalPropertyTypes）。 */
+function assignOptional(info, key, value) {
+	if (value !== void 0) info[key] = value;
+}
+/** 单项转换：DoubtBuddyReq → OB11 结构（导出供单测，friend.test.ts）。 */
+function toDoubtFriendRequestInfo(item, uinMap) {
+	const info = {
+		flag: item.uid,
+		uin: Number(uinMap.get(item.uid) ?? item.uid),
+		type: "doubt"
+	};
+	assignOptional(info, "nick", item.nick);
+	assignOptional(info, "source", item.source);
+	assignOptional(info, "reason", item.reason);
+	assignOptional(info, "msg", item.msg);
+	assignOptional(info, "group_code", item.groupCode);
+	assignOptional(info, "time", item.reqTime);
+	return info;
+}
 //#endregion
 //#region src/types/entities.ts
 /**
@@ -943,11 +952,9 @@ var GroupApi = class {
 		const raw = await this.service.getGroupDetailInfo(groupCode, 0);
 		const { result, errMsg } = raw;
 		if (typeof result === "number" && result !== 0) unwrap("getGroupDetailInfo", result, errMsg);
-		if (result !== null && typeof result === "object") return result;
-		const detail = raw;
-		const candidate = detail.groupInfo ?? detail.detailInfo ?? detail.info;
-		if (candidate !== void 0 && candidate !== null && typeof candidate === "object") return candidate;
-		throw kernelError(`getGroupDetailInfo 返回形状异常（groupCode=${groupCode}）: ${errMsg}`, "UNKNOWN");
+		const detail = extractGroupDetail(result, raw);
+		if (detail === null) throw kernelError(`getGroupDetailInfo 返回形状异常（groupCode=${groupCode}）: ${errMsg}`, "UNKNOWN");
+		return detail;
 	}
 	/** 群成员列表（forceFetch=true 强制拉取，默认缓存优先）。 */
 	async getGroupMemberList(groupCode, forceFetch = false) {
@@ -1084,6 +1091,19 @@ var GroupApi = class {
 		};
 	}
 };
+/**
+* 从 getGroupDetailInfo 返回提取群详情（兼容三种形状）：
+*  - result 为对象 → 详情直接在其中（最常见）
+*  - result 为 0/空 → 从 raw.groupInfo / detailInfo / info 提取
+* 提取不到返回 null（调用方抛 UNKNOWN）。导出供单测。
+*/
+function extractGroupDetail(result, raw) {
+	if (result !== null && typeof result === "object") return result;
+	const detail = raw;
+	const candidate = detail.groupInfo ?? detail.detailInfo ?? detail.info;
+	if (candidate !== void 0 && candidate !== null && typeof candidate === "object") return candidate;
+	return null;
+}
 //#endregion
 //#region src/apis/group-notify.ts
 /**
@@ -1159,15 +1179,47 @@ function extractMemberList(result) {
 *
 * 方法面（P2-1）：发送 / 撤回 / 拉历史 / 标记已读。group/friend 等后续 apis 同构。
 */
+/** 发送状态（onMsgInfoListUpdate 事件 msg.sendStatus）。 */
+const SEND_STATUS = {
+	FAILED: 0,
+	SENDING: 1,
+	SUCCESS: 2,
+	SUCCESS_NO_SEQ: 3
+};
+/** 发送确认超时（毫秒）。 */
+const SEND_CONFIRM_TIMEOUT_MS = 15e3;
+/** 读文件 stat（富媒体发送预处理；文件不存在抛 INVALID_PARAM）。 */
+async function statFile(path) {
+	try {
+		return await stat(path);
+	} catch {
+		throw kernelError(`图片文件不存在: ${path}`, "INVALID_PARAM");
+	}
+}
+/** 计算文件 md5（十六进制小写）。 */
+async function hashFile(path) {
+	try {
+		const buf = await readFile(path);
+		return createHash("md5").update(buf).digest("hex");
+	} catch {
+		throw kernelError(`图片文件读取失败: ${path}`, "INVALID_PARAM");
+	}
+}
 /** 消息 API：从 session 拿 msg service，包装成语义化方法。 */
 var MsgApi = class {
 	service;
+	/** 消息事件通道（sendMsg 后等 onMsgInfoListUpdate 确认发送结果）。 */
+	channel;
+	/** NodeQQNTWrapperUtil（富媒体发送 copyFile 用；session 拿不到时可为 null）。 */
+	util;
 	/** 上次生成 msgId 的时间（单调递增，2026-08-07 防同毫秒并发碰撞）。 */
 	lastMsgTime = 0;
-	constructor(session) {
+	constructor(session, channel, util) {
 		const service = session.getMsgService();
 		if (service === null || service === void 0) throw kernelError("getMsgService() 返回空（session 未 init）", "INVALID_STATE");
 		this.service = service;
+		this.channel = channel ?? null;
+		this.util = util !== null && util !== void 0 ? util : null;
 	}
 	/**
 	* 生成 msgId 时间戳（单调递增）。
@@ -1182,15 +1234,114 @@ var MsgApi = class {
 		return String(this.lastMsgTime);
 	}
 	/**
-	* 发送消息：canonical 元素 → NT 发送元素 → sendMsg。
+	* 发送消息：canonical 元素 → NT 发送元素 → sendMsg（NapCat 式）。
 	* 返回 NT msgId（雪花 ID）。
+	*
+	* 2026-08-11 修复（NapCat 式，实测）：
+	*  - sendMsg 第一参传 '0'（固定），msgId 塞 peer.guildId —— 传 msgId 作第一参
+	*    时 wrapper 返回 result=5（失败），NapCat 同款调用返回 result=0。
+	*  - 发送结果以 onMsgInfoListUpdate 事件确认（sendStatus===2 成功）：sendMsg
+	*    返回值 result 可能为 5 但事件仍成功（异步确认），反之亦然。
+	*  - ⚠️ 必须先注册事件监听再调 sendMsg（事件可能在 sendMsg 返回前就触发）。
 	*/
 	async sendMessage(target, elements) {
-		const sendElements = toSendElements(elements);
+		const sendElements = await this.prepareSendElements(elements);
 		const msgId = this.service.generateMsgUniqueId(target.chatType, this.nextMsgTime());
-		unwrapResult("sendMsg", await this.service.sendMsg(msgId, target, sendElements, /* @__PURE__ */ new Map()));
+		const sendPeer = {
+			...target,
+			guildId: msgId
+		};
+		if (this.channel === null) {
+			unwrapResult("sendMsg", await this.service.sendMsg("0", sendPeer, sendElements, /* @__PURE__ */ new Map()));
+			return { msgId };
+		}
+		const confirm = this.confirmSend(msgId, target);
+		await this.service.sendMsg("0", sendPeer, sendElements, /* @__PURE__ */ new Map());
+		await confirm;
 		return { msgId };
 	}
+	/**
+	* canonical 元素 → 发送元素，PIC 做 NapCat 式预处理。
+	* 2026-08-11 修复（实测）：图片发送必须 elementType=2（PIC）+ 完整 picElement
+	* （md5HexStr/fileSize/fileName/sourcePath），且文件须经 getRichMediaFilePathForGuild
+	* 计算目标路径 + util.copyFile 放置——缺任一环节 sendMsg 返回 rich media transfer failed。
+	*/
+	async prepareSendElements(elements) {
+		const out = [];
+		for (const el of elements) {
+			if (el.type !== "image") {
+				out.push(...toSendElements([el]));
+				continue;
+			}
+			out.push(await this.prepareImageElement(el.path));
+		}
+		return out;
+	}
+	/** PIC 元素 NapCat 式预处理：md5 → 目标路径 → copyFile → 完整 picElement。 */
+	async prepareImageElement(path) {
+		const service = this.service;
+		const util = this.util;
+		const stat = await statFile(path);
+		const md5 = await hashFile(path);
+		const fileSize = stat.size;
+		const fileName = basename(path);
+		const relPath = service.getRichMediaFilePathForGuild({
+			md5HexStr: md5,
+			fileName,
+			elementType: ElementType.PIC,
+			elementSubType: 0,
+			thumbSize: 0,
+			needCreate: true,
+			downloadType: 1,
+			file_uuid: ""
+		});
+		if (util !== null) {
+			const instance = typeof util.get === "function" ? util.get() : util;
+			const copy = instance["copyFile"];
+			if (typeof copy === "function") await copy.call(instance, path, relPath);
+		}
+		return {
+			elementType: ElementType.PIC,
+			elementId: "",
+			picElement: {
+				md5HexStr: md5,
+				fileSize: String(fileSize),
+				picWidth: 0,
+				picHeight: 0,
+				fileName,
+				sourcePath: relPath,
+				original: true,
+				picType: 1e3,
+				picSubType: 0,
+				fileUuid: "",
+				fileSubId: "",
+				thumbFileSize: 0,
+				summary: ""
+			}
+		};
+	}
+	/** 注册 onMsgInfoListUpdate 确认监听（返回 Promise，resolve 时发送成功）。 */
+	confirmSend(msgId, target) {
+		const channel = this.channel;
+		if (channel === null) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			const off = channel.on("Msg/onMsgInfoListUpdate", (list) => {
+				const mine = list.find((m) => m.guildId === msgId);
+				if (mine === void 0) return;
+				if (mine.sendStatus === SEND_STATUS.SUCCESS || mine.sendStatus === SEND_STATUS.SUCCESS_NO_SEQ) {
+					off();
+					resolve();
+				} else if (mine.sendStatus === SEND_STATUS.FAILED) {
+					off();
+					reject(kernelError(`sendMsg 失败: sendStatus=${mine.sendStatus}`, "SEND_FAILED"));
+				}
+			});
+			setTimeout(() => {
+				off();
+				reject(kernelError(`sendMsg 等待确认超时（msgId=${msgId}, target=${JSON.stringify(target)}）`, "SEND_FAILED"));
+			}, SEND_CONFIRM_TIMEOUT_MS);
+		});
+	}
 	/** 撤回消息（群聊管理员 / 私聊 2 分钟内）。 */
 	async recallMessage(target, msgIds) {
 		if (msgIds.length === 0) throw kernelError("recallMessage 需要至少一个 msgId", "INVALID_PARAM");
@@ -1219,14 +1370,10 @@ var MsgApi = class {
 	* → 再拉一次消息读 pttElement.text。
 	*/
 	async fetchPttText(msgId, target) {
-		const [first] = await this.fetchMsgsByMsgId(target, [msgId]);
-		if (first === void 0) throw kernelError("消息不存在", "NOT_FOUND");
-		const ptt = first.elements.find((el) => el.pttElement !== void 0);
-		if (ptt?.pttElement === void 0) throw kernelError("消息中不包含语音", "NOT_FOUND");
+		const ptt = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]));
+		if (ptt === null) throw kernelError("消息中不包含语音", "NOT_FOUND");
 		unwrapResult("translatePtt2Text", await this.service.translatePtt2Text(msgId, target, ptt));
-		const [afterFirst] = await this.fetchMsgsByMsgId(target, [msgId]);
-		if (afterFirst === void 0) throw kernelError("获取语音转文字结果失败", "UNKNOWN");
-		const text = afterFirst.elements.find((el) => el.pttElement !== void 0)?.pttElement?.text;
+		const text = findPttElement(await this.fetchMsgsByMsgId(target, [msgId]))?.pttElement?.text;
 		if (text === void 0 || text === "") throw kernelError("获取语音转文字结果失败", "UNKNOWN");
 		return text;
 	}
@@ -1257,10 +1404,8 @@ var MsgApi = class {
 	}
 	/** 获取合并转发内容（get_forward_msg；resId 取自 multiForwardMsgElement）。 */
 	async fetchForwardMessage(peer, msgId) {
-		const [first] = await this.fetchMsgsByMsgId(peer, [msgId]);
-		if (first === void 0) throw kernelError("消息不存在", "NOT_FOUND");
-		const forward = first.elements.find((el) => el.multiForwardMsgElement !== void 0)?.multiForwardMsgElement;
-		if (forward === void 0 || forward.resId === "") throw kernelError("消息不包含合并转发内容", "NOT_FOUND");
+		const forward = findForwardElement(await this.fetchMsgsByMsgId(peer, [msgId]));
+		if (forward === null || forward.resId === "") throw kernelError("消息不包含合并转发内容", "NOT_FOUND");
 		const raw = await this.service.getMultiMsg(peer, msgId, forward.resId);
 		unwrapResult("getMultiMsg", raw);
 		return raw.msgList ?? [];
@@ -1275,6 +1420,18 @@ var MsgApi = class {
 		unwrapResult("setStatus", await this.service.setStatus(opts));
 	}
 };
+/** 在消息列表中找含 pttElement 的元素（找不到返回 null）。 */
+function findPttElement(msgs) {
+	const [first] = msgs;
+	if (first === void 0) return null;
+	return first.elements.find((el) => el.pttElement !== void 0) ?? null;
+}
+/** 在消息列表中找含 multiForwardMsgElement 的元素（找不到返回 null）。 */
+function findForwardElement(msgs) {
+	const [first] = msgs;
+	if (first === void 0) return null;
+	return first.elements.find((el) => el.multiForwardMsgElement !== void 0)?.multiForwardMsgElement ?? null;
+}
 //#endregion
 //#region src/apis/stranger-info.ts
 /** 宽松取值：undefined 时给默认值（null 也归默认）。 */
@@ -1286,13 +1443,19 @@ function mergeDetail(info, byUin) {
 	const infoSimple = info.detail?.simpleInfo;
 	const byUinSimple = byUin.detail?.simpleInfo;
 	return {
-		coreInfo: infoSimple?.coreInfo ?? byUinSimple?.coreInfo,
-		baseInfo: infoSimple?.baseInfo ?? byUinSimple?.baseInfo,
-		vasInfo: infoSimple?.vasInfo ?? byUinSimple?.vasInfo,
-		commonExt: info.detail?.commonExt ?? byUin.detail?.commonExt,
-		status: infoSimple?.status?.status ?? byUinSimple?.status?.status
+		coreInfo: pickField(infoSimple, byUinSimple, (s) => s?.coreInfo),
+		baseInfo: pickField(infoSimple, byUinSimple, (s) => s?.baseInfo),
+		vasInfo: pickField(infoSimple, byUinSimple, (s) => s?.vasInfo),
+		commonExt: pickField(info.detail, byUin.detail, (d) => d?.commonExt),
+		status: pickField(infoSimple, byUinSimple, (s) => s?.status?.status)
 	};
 }
+/** 字段级回退：primary 的字段取不到回退 fallback 的同名字段（宽松取值）。 */
+function pickField(primary, fallback, get) {
+	const fromPrimary = primary !== void 0 ? get(primary) : void 0;
+	if (fromPrimary !== void 0) return fromPrimary;
+	return fallback !== void 0 ? get(fallback) : void 0;
+}
 /** 扁平化两份详情 → StrangerInfo（宽松取值，字段缺失给默认）。 */
 function flattenStrangerInfo(uin, uid, byUin, info) {
 	const d = mergeDetail(info, byUin);
@@ -1491,14 +1654,18 @@ var RichMediaApi = class {
 		if (raw.result !== 0) unwrap("transGroupFile", raw.result, raw.errMsg);
 	}
 };
-/** 从 getGroupFileList 返回提取文件列表（兼容数组 / { items } / { fileList }）。 */
+/** 从 getGroupFileList 返回提取文件列表（兼容数组 / { items } / { fileList }）。导出供单测。 */
 function extractFileList(result) {
 	if (Array.isArray(result)) return result;
-	if (result !== null && typeof result === "object") {
-		const obj = result;
-		if (Array.isArray(obj.items)) return obj.items;
-		if (Array.isArray(obj.fileList)) return obj.fileList;
-		if (Array.isArray(obj.list)) return obj.list;
+	if (result === null || typeof result !== "object") return [];
+	const obj = result;
+	for (const key of [
+		"items",
+		"fileList",
+		"list"
+	]) {
+		const value = obj[key];
+		if (Array.isArray(value)) return value;
 	}
 	return [];
 }
@@ -1610,24 +1777,31 @@ var WebApi = class {
 	constructor(opts) {
 		this.getCookies = opts.getCookies;
 	}
+	/** 拉取单页精华消息（失败/retcode 非 0 返回 null）。 */
+	async fetchEssencePage(groupCode, cookie, bkn, page) {
+		const ret = await fetchQunJson("https://qun.qq.com/cgi-bin/group_digest/digest_list?" + new URLSearchParams({
+			bkn,
+			page_start: String(page * ESSENCE_PAGE_LIMIT),
+			page_limit: String(ESSENCE_PAGE_LIMIT),
+			group_code: groupCode
+		}).toString(), cookie);
+		if (ret === null || ret.retcode !== 0) return null;
+		const list = ret.data?.msg_list;
+		return {
+			items: Array.isArray(list) ? list.filter((item) => item !== null) : [],
+			isEnd: ret.data?.is_end === true
+		};
+	}
 	/** 获取群精华消息列表（get_essence_msg_list；分页拉取至 is_end）。 */
 	async getEssenceMsgList(groupCode) {
 		const cookie = await this.getCookies(QUN_DOMAIN);
 		const bkn = TicketApi.getBkn(cookie["skey"] ?? "");
 		const out = [];
 		for (let page = 0; page < ESSENCE_MAX_PAGES; page += 1) {
-			const ret = await fetchQunJson("https://qun.qq.com/cgi-bin/group_digest/digest_list?" + new URLSearchParams({
-				bkn,
-				page_start: String(page * ESSENCE_PAGE_LIMIT),
-				page_limit: String(ESSENCE_PAGE_LIMIT),
-				group_code: groupCode
-			}).toString(), cookie);
-			if (ret === null || ret.retcode !== 0) break;
-			const list = ret.data?.msg_list;
-			if (Array.isArray(list)) {
-				for (const item of list) if (item !== null) out.push(item);
-			}
-			if (ret.data?.is_end === true) break;
+			const result = await this.fetchEssencePage(groupCode, cookie, bkn, page);
+			if (result === null) break;
+			out.push(...result.items);
+			if (result.isEnd) break;
 		}
 		return out;
 	}
@@ -1643,17 +1817,20 @@ var WebApi = class {
 			emotion_list: [],
 			strong_newbie_list: []
 		};
-		if (type === WebHonorType.TALKATIVE || type === WebHonorType.ALL) {
-			const talkative = await this.fetchHonorList(groupCode, cookie, WebHonorType.TALKATIVE);
-			result.talkative_list = talkative;
-			const [first] = talkative;
-			if (first !== void 0) result.current_talkative = first;
-		}
-		if (type === WebHonorType.PERFORMER || type === WebHonorType.ALL) result.performer_list = await this.fetchHonorList(groupCode, cookie, WebHonorType.PERFORMER);
-		if (type === WebHonorType.LEGEND || type === WebHonorType.ALL) result.legend_list = await this.fetchHonorList(groupCode, cookie, WebHonorType.LEGEND);
-		if (type === WebHonorType.EMOTION || type === WebHonorType.ALL) result.emotion_list = await this.fetchHonorList(groupCode, cookie, WebHonorType.EMOTION);
+		await this.fillHonorLists(result, groupCode, cookie, type);
 		return result;
 	}
+	/** 按 type 填充荣誉列表（ALL 拉全部，单类型只拉对应类）。 */
+	async fillHonorLists(result, groupCode, cookie, type) {
+		for (const target of honorTargets(type)) {
+			const list = await this.fetchHonorList(groupCode, cookie, target.kind);
+			result[target.listKey] = list;
+			if (target.kind === WebHonorType.TALKATIVE) {
+				const [first] = list;
+				if (first !== void 0) result.current_talkative = first;
+			}
+		}
+	}
 	/** 拉取单类荣誉列表（honorlist 接口，正则提取 __INITIAL_STATE__）。 */
 	async fetchHonorList(groupCode, cookie, type) {
 		const text = await fetchQunText("https://qun.qq.com/interactive/honorlist?" + new URLSearchParams({
@@ -1664,9 +1841,11 @@ var WebApi = class {
 		return parseHonorList(text, type);
 	}
 };
+/** honorlist 页面 __INITIAL_STATE__ 提取。 */
+const INITIAL_STATE_RE = /window\.__INITIAL_STATE__=(.*?);/;
 /** 从 honorlist 页面提取 __INITIAL_STATE__ → 荣誉列表（解析失败返回空）。 */
 function parseHonorList(text, type) {
-	const match = /window\.__INITIAL_STATE__=(.*?);/.exec(text);
+	const match = INITIAL_STATE_RE.exec(text);
 	if (match === null || match[1] === void 0) return [];
 	let state;
 	try {
@@ -1718,6 +1897,29 @@ function cookieToString(cookie) {
 	for (const [key, value] of Object.entries(cookie)) parts.push(`${key}=${value}`);
 	return parts.join("; ");
 }
+/** 荣誉类型 → 目标列表（ALL 拉全部，单类型只拉对应类）。 */
+function honorTargets(type) {
+	const all = [
+		{
+			kind: WebHonorType.TALKATIVE,
+			listKey: "talkative_list"
+		},
+		{
+			kind: WebHonorType.PERFORMER,
+			listKey: "performer_list"
+		},
+		{
+			kind: WebHonorType.LEGEND,
+			listKey: "legend_list"
+		},
+		{
+			kind: WebHonorType.EMOTION,
+			listKey: "emotion_list"
+		}
+	];
+	if (type === WebHonorType.ALL) return [...all];
+	return all.filter((target) => target.kind === type);
+}
 //#endregion
 //#region src/bridge/group-bridge.ts
 /**
@@ -1778,7 +1980,8 @@ var MsgBridge = class {
 		const listener = {
 			onRecvMsg: (msgs) => this.channel.emit("Msg/onRecvMsg", msgs),
 			onRecvMsgReadReport: (reports) => this.channel.emit("Msg/onRecvMsgReadReport", reports),
-			onRecvMsgReceipt: (receipts) => this.channel.emit("Msg/onRecvMsgReceipt", receipts)
+			onRecvMsgReceipt: (receipts) => this.channel.emit("Msg/onRecvMsgReceipt", receipts),
+			onMsgInfoListUpdate: (msgs) => this.channel.emit("Msg/onMsgInfoListUpdate", msgs)
 		};
 		this.listenerId = this.service.addKernelMsgListener(listener);
 	}
@@ -1947,21 +2150,22 @@ var GroupCache = class {
 	* 返回 undefined 表示成员不在群。
 	*/
 	async getMember(groupCode, uid) {
+		const cached = await this.getCachedMember(groupCode, uid);
+		if (cached !== void 0) return cached;
+		const [member] = await this.dedupe(`member:${groupCode}:${uid}`, () => this.groupApi.getGroupMemberInfo(groupCode, [uid]));
+		if (member === void 0) return;
+		const target = this.members.get(groupCode);
+		if (target !== void 0) target.set(member.uid, member);
+		return member;
+	}
+	/** 读缓存成员（缺失先整群回填一次）。 */
+	async getCachedMember(groupCode, uid) {
 		let map = this.members.get(groupCode);
 		if (map === void 0 || map.size === 0) {
 			await this.getMembers(groupCode);
 			map = this.members.get(groupCode);
 		}
-		const cached = map?.get(uid);
-		if (cached !== void 0) return cached;
-		const members = await this.dedupe(`member:${groupCode}:${uid}`, () => this.groupApi.getGroupMemberInfo(groupCode, [uid]));
-		if (members.length === 0) return;
-		const [member] = members;
-		if (member !== void 0) {
-			const target = this.members.get(groupCode);
-			if (target !== void 0) target.set(member.uid, member);
-		}
-		return member;
+		return map?.get(uid);
 	}
 	/** 惰性回填全量群列表（getGroup 缺失时）。 */
 	async loadGroupList() {
@@ -2102,9 +2306,12 @@ async function listLoginAccounts(ctx) {
 async function ensureLoginConnected(ctx, opts) {
 	const raw = ctx.loginService;
 	if (raw === null || typeof raw.connect !== "function") return;
-	const connect = raw.connect;
-	const addListener = raw.addKernelLoginListener;
-	await new Promise((resolve) => {
+	await waitLoginConnected(raw, opts.timeoutMs);
+	await sleep(CONNECTION_SETTLE_MS);
+}
+/** 等 onLoginConnected（注册临时监听 + connect + 超时兜底）。 */
+function waitLoginConnected(raw, timeoutMs) {
+	return new Promise((resolve) => {
 		let settled = false;
 		const finish = () => {
 			if (!settled) {
@@ -2112,25 +2319,29 @@ async function ensureLoginConnected(ctx, opts) {
 				resolve();
 			}
 		};
+		tryRegisterConnectListener(raw, finish);
+		setTimeout(finish, timeoutMs ?? NETWORK_READY_TIMEOUT_MS);
 		try {
-			const listener = createLoginListener();
-			listener.onLoginConnected = () => {
-				finish();
-			};
-			if (typeof addListener === "function") addListener(listener);
-		} catch {}
-		setTimeout(finish, opts.timeoutMs ?? NETWORK_READY_TIMEOUT_MS);
-		try {
-			connect();
+			raw.connect?.();
 		} catch {
 			finish();
 		}
 	});
-	await sleep(CONNECTION_SETTLE_MS);
+}
+/** 注册临时登录连接监听（失败不阻塞连接）。 */
+function tryRegisterConnectListener(raw, finish) {
+	try {
+		const listener = createLoginListener();
+		listener.onLoginConnected = () => {
+			finish();
+		};
+		if (typeof raw.addKernelLoginListener === "function") raw.addKernelLoginListener(listener);
+	} catch {}
 }
 /**
 * 目标账号选择（2026-08-07 修复：显式 uin 不在列表时**报错**而非静默 fallback——
 * 之前会退到第一个可快速登录账号，导致 `-q <uin>` 实际登成别的号）。
+* 导出供单测（login-connect.test.ts）。
 */
 function pickLoginTarget(items, uin) {
 	if (uin !== void 0) {
@@ -2151,18 +2362,34 @@ function pickLoginTarget(items, uin) {
 async function loginWithNetworkRetry(ctx, loginService, target, opts) {
 	let lastErrMsg = "";
 	for (let attempt = 1; attempt <= NETWORK_RETRY_MAX; attempt += 1) {
-		const { errMsg } = (await loginService.quickLoginWithUin(target.uin)).loginErrorInfo;
-		if (!errMsg) return {
-			uin: target.uin,
-			uid: target.uid ?? "",
-			nick: target.nickName ?? ""
-		};
-		lastErrMsg = errMsg;
-		if (!(errMsg.includes(NETWORK_ERROR_CODE) || errMsg.includes(CONNECTION_ERROR_HINT)) || attempt >= NETWORK_RETRY_MAX) break;
+		const attemptResult = await attemptQuickLogin(loginService, target);
+		if (attemptResult.ok) return attemptResult.result;
+		lastErrMsg = attemptResult.errMsg;
+		if (!(isNetworkError(lastErrMsg) && attempt < NETWORK_RETRY_MAX)) break;
 		if (!await waitForNetworkConnection(ctx, { timeoutMs: opts.timeoutMs ?? NETWORK_READY_TIMEOUT_MS })) break;
 	}
 	throw kernelError(`快速登录失败: ${lastErrMsg}`, "NOT_LOGIN");
 }
+/** 单次快速登录尝试（成功带结果，失败带错误消息）。 */
+async function attemptQuickLogin(loginService, target) {
+	const { errMsg } = (await loginService.quickLoginWithUin(target.uin)).loginErrorInfo;
+	if (errMsg) return {
+		ok: false,
+		errMsg
+	};
+	return {
+		ok: true,
+		result: {
+			uin: target.uin,
+			uid: target.uid ?? "",
+			nick: target.nickName ?? ""
+		}
+	};
+}
+/** 判定快速登录失败是否为网络异常（重试语义）。导出供单测。 */
+function isNetworkError(errMsg) {
+	return errMsg.includes(NETWORK_ERROR_CODE) || errMsg.includes(CONNECTION_ERROR_HINT);
+}
 /**
 * 快速登录：遍历历史登录列表尝试。
 * P2-1：失败且错误为网络异常（1006511）时，等网络就绪后重试（最多 NETWORK_RETRY_MAX 次）。
@@ -2232,7 +2459,14 @@ async function initAndStartSession(ctx, config, listener, opts) {
 	if (session === null || session === void 0) throw kernelError("session 未创建", "INVALID_STATE");
 	const depends = new DependsAdapter();
 	const dispatcher = new DispatcherAdapter();
-	const initComplete = new Promise((resolve, reject) => {
+	const initComplete = watchInitSignal(listener);
+	session.init(config, depends, dispatcher, listener);
+	startSessionBestEffort(ctx, session);
+	if (!await Promise.race([initComplete.then(() => true), waitFor(() => false, opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS).then(() => false)])) throw kernelError("session init 超时", "TIMEOUT");
+}
+/** 监听 init 完成信号：onOpentelemetryInit(is_init) 为主，onSessionInitComplete(0) 为辅。 */
+function watchInitSignal(listener) {
+	return new Promise((resolve, reject) => {
 		const onOpentelemetry = listener.onOpentelemetryInit;
 		listener.onOpentelemetryInit = (info) => {
 			if (info.is_init) resolve();
@@ -2245,19 +2479,33 @@ async function initAndStartSession(ctx, config, listener, opts) {
 			if (typeof onInitComplete === "function") onInitComplete(r);
 		};
 	});
-	session.init(config, depends, dispatcher, listener);
-	const { startupSession } = ctx;
-	if (startupSession !== null && typeof startupSession.start === "function") try {
-		startupSession.start();
-	} catch {}
-	else try {
+}
+/**
+* 启动会话（best effort，失败不致命）：
+* **先 init 后 start（2026-08-07 V9 决定性修正）**。
+* 自建宿主实测（HANDOVER-V9，p0-napcat-min）：必须先 session.init 再
+* startupSession.start()——顺序颠倒（先 start 后 init）业务 service 不挂载
+* （getMsgService null）；init 后用 startNT（非 startupSession.start）也失败。
+* NapCat initializeSession 同款：有 startupSession 用 start()，否则 startNT(0)。
+*/
+function startSessionBestEffort(ctx, session) {
+	if (startupSessionStart(ctx)) return;
+	try {
 		session.startNT(0);
 	} catch {
 		try {
 			session.startNT();
 		} catch {}
 	}
-	if (!await Promise.race([initComplete.then(() => true), waitFor(() => false, opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS).then(() => false)])) throw kernelError("session init 超时", "TIMEOUT");
+}
+/** 有 startupSession 则 start()（失败不致命），返回是否已处理。 */
+function startupSessionStart(ctx) {
+	const { startupSession } = ctx;
+	if (startupSession === null || typeof startupSession.start !== "function") return false;
+	try {
+		startupSession.start();
+	} catch {}
+	return true;
 }
 //#endregion
 //#region src/login/login.ts
@@ -2475,20 +2723,27 @@ function parseAppidFromMajor(majorPath) {
 	} catch {
 		return null;
 	}
+	return scanAppidMarkers(buf);
+}
+/** 扫描 buf 中所有 QQAppId/ 标记，返回第一个纯数字串（无则 null）。 */
+function scanAppidMarkers(buf) {
 	const marker = Buffer.from("QQAppId/", "utf-8");
 	let pos = 0;
 	while (pos < buf.length) {
 		const idx = buf.indexOf(marker, pos);
 		if (idx === -1) return null;
-		const start = idx + marker.length;
-		let end = start;
-		while (end < buf.length && buf[end] !== 0) end += 1;
-		const str = buf.subarray(start, end).toString("utf-8");
+		const str = readMarkerValue(buf, idx + marker.length);
 		if (DIGITS_ONLY_RE.test(str)) return str;
-		pos = end + 1;
+		pos = idx + marker.length + str.length + 1;
 	}
 	return null;
 }
+/** 读取标记后的 C 字符串（到首个 0 字节为止）。 */
+function readMarkerValue(buf, start) {
+	let end = start;
+	while (end < buf.length && buf[end] !== 0) end += 1;
+	return buf.subarray(start, end).toString("utf-8");
+}
 /** Windows 兜底 appid / qua（major.node 解析失败时）。 */
 function fallbackAppidQua(fullVersion) {
 	return {
@@ -2608,14 +2863,12 @@ function buildSessionConfig(options) {
 */
 /** 默认 engine 配置（KWINDOWS + 版本号，字段待首个真实联调确认）。 */
 function defaultEngineConfig(env, qqDataPath) {
-	let osVersion = process.platform;
-	if (process.platform === "win32") osVersion = "win32";
 	return {
 		base_path_prefix: env.dataDir ?? "",
 		platform_type: PlatformType.KWINDOWS,
 		app_type: 4,
 		app_version: env.qqVersion ?? "",
-		os_version: osVersion,
+		os_version: process.platform,
 		use_xlog: false,
 		qua: "",
 		global_path_config: { desktopGlobalPath: qqDataPath ?? env.dataDir ?? "" },
@@ -2646,14 +2899,15 @@ function electronProcessType() {
 * 正确路径，无需此解析。
 */
 function resolveQqUserDataRoot(exports) {
+	return extractUserDataRoot(exports) ?? join(homedir(), "Documents", "Tencent Files");
+}
+/** 从 QQ 官方 API 提取数据根（不可用返回 null，调用方回退默认）。 */
+function extractUserDataRoot(exports) {
 	try {
-		const raw = (exports.NodeQQNTWrapperUtil?.get?.())?.getNTUserDataInfoConfig?.();
-		if (typeof raw === "string" && raw.trim() !== "") {
-			const extracted = extractDataRoot(raw.trim());
-			if (extracted !== null) return extracted;
-		}
+		const raw = exports.NodeQQNTWrapperUtil?.get?.().getNTUserDataInfoConfig?.();
+		if (typeof raw === "string" && raw.trim() !== "") return extractDataRoot(raw.trim());
 	} catch {}
-	return join(homedir(), "Documents", "Tencent Files");
+	return null;
 }
 /**
 * 从 loader 截获的 NAPI exports 创建 wrapper 上下文。
@@ -2689,27 +2943,37 @@ function initEngine(ctx, config) {
 * 返回带完整实现的实例。worker（utilityProcess）继承 QQ env 后同样有效。
 */
 function createSession(ctx) {
-	const X = ctx.exports;
-	const S = X.NodeIQQNTWrapperSession;
-	let session = null;
+	const S = ctx.exports.NodeIQQNTWrapperSession;
+	const session = createStartupSession(ctx) ?? getNTWrapperSession(S) ?? createNewSession(S) ?? new S();
+	ctx.session = session;
+	return session;
+}
+/** 步骤 1：StartupSessionWrapper.create()（建立启动 session，失败忽略）。 */
+function createStartupSession(ctx) {
+	const Ssw = ctx.exports.NodeIQQNTStartupSessionWrapper;
+	if (Ssw === void 0 || typeof Ssw.create !== "function") return null;
 	try {
-		const Ssw = X.NodeIQQNTStartupSessionWrapper;
-		if (Ssw !== void 0 && typeof Ssw.create === "function") ctx.startupSession = Ssw.create();
+		ctx.startupSession = Ssw.create();
 	} catch {}
+	return null;
+}
+/** 步骤 2：getNTWrapperSession("nt_1")（QQ 主 session，带 cpp_impl）。 */
+function getNTWrapperSession(S) {
+	if (typeof S.getNTWrapperSession !== "function") return null;
 	try {
-		if (typeof S.getNTWrapperSession === "function") {
-			const got = S.getNTWrapperSession("nt_1");
-			if (got !== null && got !== void 0) session = got;
-		}
-	} catch {}
-	if (session === null) try {
-		if (typeof S.create === "function") session = S.create();
+		return S.getNTWrapperSession("nt_1");
 	} catch {
-		session = null;
+		return null;
+	}
+}
+/** 步骤 3：S.create() 回退。 */
+function createNewSession(S) {
+	if (typeof S.create !== "function") return null;
+	try {
+		return S.create();
+	} catch {
+		return null;
 	}
-	if (session === null) session = new S();
-	ctx.session = session;
-	return session;
 }
 /** session 初始化（4 参全为 JS 对象，NAPI 自动转换）。 */
 function initSession(ctx, config, listener) {
@@ -2749,18 +3013,36 @@ function startNapuketto(options) {
 		fullVersion: env?.qqVersion ?? "",
 		buildVersion: env?.qqVersion ?? ""
 	});
+	const hasCapturedSession = captureSession(ctx, qqSession);
 	const isSelfHost = electronProcessType() === void 0;
-	if (qqSession !== void 0 && qqSession !== null) ctx.session = qqSession;
-	else if (isSelfHost) createSession(ctx);
-	initEngine(ctx, engineConfig ?? defaultEngineConfig(env ?? {}, resolveBootQqGlobalPath(ctx)));
+	prepareSession(ctx, hasCapturedSession, isSelfHost);
+	initEngine(ctx, resolveEngineConfig(ctx, env, engineConfig));
 	resolveLoginService(ctx, qqLoginService);
-	if (qqSession !== void 0 && qqSession !== null) ctx.session = qqSession;
-	else if (!isSelfHost) createSession(ctx);
+	finishSession(ctx, hasCapturedSession, isSelfHost, sessionConfig);
+	return ctx;
+}
+/** engine 前 session 准备（自建宿主必须先建，顺序决定性）。 */
+function prepareSession(ctx, hasCaptured, isSelfHost) {
+	if (!hasCaptured && isSelfHost) createSession(ctx);
+}
+/** engine 后收尾：非自建宿主补建 session；配置了 sessionConfig 则 init+start。 */
+function finishSession(ctx, hasCaptured, isSelfHost, sessionConfig) {
+	if (!hasCaptured && !isSelfHost) createSession(ctx);
 	if (sessionConfig !== void 0) {
 		initSession(ctx, sessionConfig, createSessionListener());
 		startSession(ctx);
 	}
-	return ctx;
+}
+/** engine 配置：显式覆盖优先，否则默认（含 QQ 数据根 global 路径解析）。 */
+function resolveEngineConfig(ctx, env, engineConfig) {
+	if (engineConfig !== void 0) return engineConfig;
+	return defaultEngineConfig(env ?? {}, resolveBootQqGlobalPath(ctx));
+}
+/** 捕获 QQ 已 init 的 session（boot.cjs 拦截 `new` 窃取），返回是否捕获成功。 */
+function captureSession(ctx, qqSession) {
+	if (qqSession === void 0 || qqSession === null) return false;
+	ctx.session = qqSession;
+	return true;
 }
 /**
 * 解析 QQ 真实数据目录的 global 路径（desktopGlobalPath 三要素之三）。
@@ -2785,12 +3067,16 @@ function resolveLoginService(ctx, qqLoginService) {
 		ctx.loginService = qqLoginService;
 		return;
 	}
+	ctx.loginService = getOrCreateLoginService(ctx.exports);
+}
+/** 单例 get() 优先，缺失回退 new（都失败返回 null）。 */
+function getOrCreateLoginService(exports) {
 	try {
-		const loginSvcCtor = ctx.exports.NodeIKernelLoginService;
-		if (loginSvcCtor !== null && typeof loginSvcCtor.get === "function") ctx.loginService = loginSvcCtor.get();
-		else ctx.loginService = new ctx.exports.NodeIKernelLoginService();
+		const loginSvcCtor = exports.NodeIKernelLoginService;
+		if (loginSvcCtor !== null && typeof loginSvcCtor.get === "function") return loginSvcCtor.get();
+		return new exports.NodeIKernelLoginService();
 	} catch {
-		ctx.loginService = null;
+		return null;
 	}
 }
 //#endregion
@@ -2870,18 +3156,7 @@ var NapukettoCore = class NapukettoCore {
 	async login(opts) {
 		const { wrapper } = this.ctx;
 		if (wrapper === null) throw kernelError("wrapper 未装配，无法登录", "INVALID_STATE");
-		const loginService = wrapper.loginService;
-		if (loginService !== null && typeof loginService.initConfig === "function") {
-			let qqGlobalPath = null;
-			if (electronProcessType() !== "browser") {
-				const root = resolveQqUserDataRoot(wrapper.exports);
-				if (root !== null) qqGlobalPath = resolveQqGlobalPath(root);
-			}
-			const commonPath = qqGlobalPath ?? this.ctx.paths.accountDir;
-			const loginCfg = buildLoginConfig(opts.appid, wrapper.versionInfo.fullVersion, commonPath);
-			loginService.initConfig(loginCfg);
-			this.ctx.logger.info({ commonPath }, "loginService.initConfig OK");
-		} else this.ctx.logger.warn("loginService 不可用，跳过 initConfig");
+		this.initLoginConfig(wrapper, opts.appid);
 		let loginResult;
 		try {
 			const quickOpts = {};
@@ -2899,6 +3174,25 @@ var NapukettoCore = class NapukettoCore {
 		return loginResult;
 	}
 	/**
+	* loginService.initConfig（worker/自建宿主需指定 QQ 真实数据路径）。
+	* worker（utilityProcess）模式 + 自建宿主（标准 node）下 loginService 是
+	* new 的，commonPath 必须指向 QQ 真实数据目录（数据根/nt_qq/global，
+	* HANDOVER-V6 三要素之三）才能读到历史账号——cli 的 `.napuketto\default`
+	* 读不到（getLoginList 空，P2-1 实测 2026-08-06）。
+	* QQ 主进程（V1）模式 QQ 自己 initConfig 过正确路径，无需解析。
+	*/
+	initLoginConfig(wrapper, appid) {
+		const loginService = wrapper.loginService;
+		if (loginService === null || typeof loginService.initConfig !== "function") {
+			this.ctx.logger.warn("loginService 不可用，跳过 initConfig");
+			return;
+		}
+		const commonPath = resolveCommonPath(this.ctx, wrapper);
+		const loginCfg = buildLoginConfig(appid, wrapper.versionInfo.fullVersion, commonPath);
+		loginService.initConfig(loginCfg);
+		this.ctx.logger.info({ commonPath }, "loginService.initConfig OK");
+	}
+	/**
 	* 替换当前 session（登录后 Proxy 捕获的 QQ 新实例替换自己 create 的无效实例）。
 	* 在 QQ 主进程内由 boot.cjs 调用（登录成功后）。
 	*/
@@ -2912,6 +3206,22 @@ var NapukettoCore = class NapukettoCore {
 		if (wrapper === null || wrapper.loginService === null) throw kernelError("wrapper/loginService 不可用，无法 QR 登录", "INVALID_STATE");
 		const session = new QrLoginSession(wrapper.loginService);
 		const qrPath = opts.qrCodePath ?? this.ctx.paths.file("cache", "qrcode.png");
+		this.subscribeQrProgress(session, opts, qrPath);
+		const startOpts = {};
+		if (opts.quickUin !== void 0) startOpts.quickUin = opts.quickUin;
+		session.start(startOpts);
+		await waitQrLoggedIn(session);
+		const self = session.selfInfo;
+		if (self === null) throw kernelError("QR 登录成功但 selfInfo 为空", "INVALID_STATE");
+		session.stop();
+		return {
+			uin: self.uin,
+			uid: self.uid,
+			nick: self.nick
+		};
+	}
+	/** 订阅 QR 进度：二维码写盘 + 状态机经 onLoginProgress 转发。 */
+	subscribeQrProgress(session, opts, qrPath) {
 		session.onQrCode((qr) => {
 			this.ctx.logger.warn(`请扫描二维码登录（保存: ${qrPath} | URL: ${qr.qrcodeUrl}）`);
 			if (qr.pngBase64 !== "") writeQrCodePng(qrPath, qr.pngBase64);
@@ -2924,28 +3234,6 @@ var NapukettoCore = class NapukettoCore {
 			this.ctx.logger.info({ state }, "QR 登录状态");
 			opts.onLoginProgress?.({ state });
 		});
-		const startOpts = {};
-		if (opts.quickUin !== void 0) startOpts.quickUin = opts.quickUin;
-		session.start(startOpts);
-		await new Promise((resolve, reject) => {
-			const offState = session.onStateChange((state) => {
-				if (state === "logged_in") {
-					offState();
-					resolve();
-				} else if (state === "failed") {
-					offState();
-					reject(kernelError("QR 登录失败", "NOT_LOGIN"));
-				}
-			});
-		});
-		const self = session.selfInfo;
-		if (self === null) throw kernelError("QR 登录成功但 selfInfo 为空", "INVALID_STATE");
-		session.stop();
-		return {
-			uin: self.uin,
-			uid: self.uid,
-			nick: self.nick
-		};
 	}
 	/** 停止：日志收尾（资源清理留给 P2 常驻管理）。 */
 	stop() {
@@ -2959,6 +3247,32 @@ function writeQrCodePng(filePath, pngBase64) {
 		writeFileSync(filePath, Buffer.from(pngBase64, "base64"));
 	} catch {}
 }
+/** 等待 QR 登录终态：logged_in resolve，failed reject。 */
+function waitQrLoggedIn(session) {
+	return new Promise((resolve, reject) => {
+		const offState = session.onStateChange((state) => {
+			if (state === "logged_in") {
+				offState();
+				resolve();
+			} else if (state === "failed") {
+				offState();
+				reject(kernelError("QR 登录失败", "NOT_LOGIN"));
+			}
+		});
+	});
+}
+/**
+* loginService.initConfig 的 commonPath：
+* worker/自建宿主（非 browser）优先 QQ 真实数据目录（数据根/nt_qq/global），
+* 否则回退账号目录。
+*/
+function resolveCommonPath(ctx, wrapper) {
+	if (electronProcessType() !== "browser") {
+		const root = resolveQqUserDataRoot(wrapper.exports);
+		if (root !== null) return resolveQqGlobalPath(root);
+	}
+	return ctx.paths.accountDir;
+}
 //#endregion
 //#region src/event-channel.ts
 /**
@@ -3046,15 +3360,19 @@ var NTEventChannel = class {
 		for (const anyHandler of this.anyHandlers) try {
 			anyHandler(event, ...args);
 		} catch (err) {
-			for (const errorHandler of this.errorHandlers) errorHandler(err);
+			this.notifyError(err);
 		}
 		const listeners = this.emitter.listeners(event);
 		for (const listener of listeners) try {
 			listener(...args);
 		} catch (err) {
-			for (const handler of this.errorHandlers) handler(err);
+			this.notifyError(err);
 		}
 	}
+	/** 通知所有错误处理器（单个异常不打断其他处理器）。 */
+	notifyError(err) {
+		for (const handler of this.errorHandlers) handler(err);
+	}
 	/** 订阅错误通知（监听器抛出的异常 / 其他内部错误）。 */
 	onError(handler) {
 		this.errorHandlers.add(handler);
@@ -3067,41 +3385,48 @@ var NTEventChannel = class {
 //#region src/wrapper/session-resolver.ts
 /** 从 getSessionIdList 的 Map 提取主 sessionId（nt_ 前缀优先）。 */
 function findMainSessionId(ids) {
-	for (const [k, v] of ids) if (typeof v === "string") {
-		if (v.startsWith("nt_")) return v;
-	} else if (typeof k === "string" && k.startsWith("nt_")) return k;
-	for (const [, v] of ids) if (typeof v === "string") return v;
-	for (const k of ids.keys()) if (typeof k === "string") return k;
+	return firstStringId(ids, (s) => s.startsWith("nt_")) ?? firstStringId(ids, () => true);
+}
+/** 遍历 Map 找第一个满足谓词的字符串 id（值优先，其次键）。 */
+function firstStringId(ids, pred) {
+	for (const [k, v] of ids) {
+		if (typeof v === "string" && pred(v)) return v;
+		if (typeof k === "string" && pred(k)) return k;
+	}
 	return null;
 }
 /** 通过 getNTWrapperSession 拿主 session（内部辅助）。 */
 function resolveMainSession(created, getNTWrapperSession) {
-	if (typeof created.start === "function") created.start();
-	if (typeof created.getSessionIdList !== "function") return null;
-	const ids = created.getSessionIdList();
+	created.start?.();
+	const ids = typeof created.getSessionIdList === "function" ? created.getSessionIdList() : null;
 	if (!(ids instanceof Map)) return null;
 	const mainId = findMainSessionId(ids);
 	if (mainId === null) return null;
 	const maybe = getNTWrapperSession(mainId);
-	if (maybe !== null && maybe !== void 0 && typeof maybe.getMsgService === "function") return maybe;
-	return null;
+	return maybe !== null && maybe !== void 0 && typeof maybe.getMsgService === "function" ? maybe : null;
 }
 /**
 * 复用 QQ 已有 session（P1-4：QQ 已登录，直接拿单例避免重复 init）。
 * 优先 `NodeIQQNTWrapperSession.get()`；返回 null 时回退 createSession。
 */
 function getExistingSession(ctx) {
+	const got = trySessionGet(ctx);
+	if (got !== null) {
+		ctx.session = got;
+		return got;
+	}
+	return null;
+}
+/** NodeIQQNTWrapperSession.get() 单例（无效/异常返回 null）。 */
+function trySessionGet(ctx) {
 	try {
 		const S = ctx.exports.NodeIQQNTWrapperSession;
-		if (typeof S.get === "function") {
-			const got = S.get();
-			if (got && typeof got.getMsgService === "function") {
-				ctx.session = got;
-				return got;
-			}
-		}
-	} catch {}
-	return null;
+		if (typeof S.get !== "function") return null;
+		const got = S.get();
+		return got && typeof got.getMsgService === "function" ? got : null;
+	} catch {
+		return null;
+	}
 }
 /**
 * 复用 QQ 主 session（P1-4 实测链路）：
@@ -3111,17 +3436,22 @@ function getExistingSession(ctx) {
 */
 function getMainSession(ctx) {
 	try {
-		const startupRaw = ctx.exports.NodeIQQNTStartupSessionWrapper;
-		const sessionCtor = ctx.exports.NodeIQQNTWrapperSession;
-		if (typeof startupRaw.create !== "function" || typeof sessionCtor.getNTWrapperSession !== "function") return null;
-		const created = startupRaw.create();
-		if (!created) return null;
-		const getSession = (id) => sessionCtor.getNTWrapperSession(id);
-		const session = resolveMainSession(created, getSession);
-		if (session !== null) ctx.session = session;
-		return session;
-	} catch {}
-	return null;
+		return resolveMainFromStartup(ctx) ?? null;
+	} catch {
+		return null;
+	}
+}
+/** startup.create → start → getSessionIdList → getNTWrapperSession 链路。 */
+function resolveMainFromStartup(ctx) {
+	const startupRaw = ctx.exports.NodeIQQNTStartupSessionWrapper;
+	const sessionCtor = ctx.exports.NodeIQQNTWrapperSession;
+	if (typeof startupRaw.create !== "function" || typeof sessionCtor.getNTWrapperSession !== "function") return null;
+	const created = startupRaw.create();
+	if (!created) return null;
+	const getSession = (id) => sessionCtor.getNTWrapperSession(id);
+	const session = resolveMainSession(created, getSession);
+	if (session !== null) ctx.session = session;
+	return session;
 }
 //#endregion
 //#region src/wrapper/probe/probe-serialize.ts
@@ -3225,13 +3555,25 @@ function shapeKeyGetters(session, serviceMethods) {
 function listMethods(obj) {
 	if (obj === null || obj === void 0) return [];
 	const names = /* @__PURE__ */ new Set();
+	collectPrototypeNames(obj, names);
+	collectOwnNames(obj, names);
+	return [...names].sort();
+}
+/** 收集原型链上的属性名（到 Object/Function.prototype 为止，去构造器）。 */
+function collectPrototypeNames(obj, names) {
 	let proto = Object.getPrototypeOf(obj);
-	while (proto && proto !== Object.prototype && proto !== Function.prototype) {
+	while (isProbeProto(proto)) {
 		for (const name of Object.getOwnPropertyNames(proto)) if (name !== "constructor") names.add(name);
 		proto = Object.getPrototypeOf(proto);
 	}
+}
+/** 是否仍需遍历的原型（非 Object/Function.prototype 且非空）。 */
+function isProbeProto(proto) {
+	return proto !== null && proto !== Object.prototype && proto !== Function.prototype;
+}
+/** 收集自有属性名（去构造器）。 */
+function collectOwnNames(obj, names) {
 	for (const name of Object.getOwnPropertyNames(obj)) if (name !== "constructor") names.add(name);
-	return [...names].sort();
 }
 /** 安全调用：尝试调用方法拿返回值，失败记录错误（不中断探测）。 */
 function tryCall(obj, name) {
@@ -3278,41 +3620,52 @@ function probeExportCtors(ctx) {
 /** 探测 engine 关键调用（getDeviceInfo / getECDHService / getThirdPartySigService）。 */
 function probeEngineCalls(ctx) {
 	const out = {};
-	for (const m of [
-		"getDeviceInfo",
-		"getECDHService",
-		"getThirdPartySigService",
-		"readyToShow"
-	]) {
-		const call = tryCall(ctx.engine, m);
-		out[m] = call.ok ? {
-			value: serialize(call.value),
-			methods: call.value ? listMethods(call.value) : []
-		} : { error: call.error ?? "null/undefined" };
-	}
+	for (const m of ENGINE_CALL_PROBES) out[m] = probeEngineCall(ctx, m);
 	return out;
 }
+/** 探测单个 engine 方法调用（成功记录方法面/形状，失败记录错误）。 */
+function probeEngineCall(ctx, m) {
+	const call = tryCall(ctx.engine, m);
+	return call.ok ? {
+		value: serialize(call.value),
+		methods: call.value ? listMethods(call.value) : []
+	} : { error: call.error ?? "null/undefined" };
+}
+/** engine 关键调用候选。 */
+const ENGINE_CALL_PROBES = [
+	"getDeviceInfo",
+	"getECDHService",
+	"getThirdPartySigService",
+	"readyToShow"
+];
 /** 探测 LoginService 实例（QQ 已登录凭据入口）。 */
 function probeLoginService(ctx) {
 	const ctor = ctx.exports.NodeIKernelLoginService;
 	if (ctor === null || typeof ctor.get !== "function") return null;
 	const inst = tryCall(ctor, "get");
 	if (!(inst.ok && inst.value)) return { get: inst.error ?? "null/undefined" };
-	const out = {
+	return {
 		methods: listMethods(inst.value),
-		ownKeys: Object.getOwnPropertyNames(inst.value).slice(0, 30)
+		ownKeys: Object.getOwnPropertyNames(inst.value).slice(0, 30),
+		...probeLoginGetters(inst.value)
 	};
-	for (const m of [
-		"getAccountInfo",
-		"getLoginInfo",
-		"getA2",
-		"getTicket",
-		"getUin",
-		"getUid",
-		"getSelfUin"
-	]) if (typeof inst.value[m] === "function") out[m] = tryShape(inst.value, m);
+}
+/** 尝试关键登录信息 getter（无参调用，探测形状）。 */
+function probeLoginGetters(inst) {
+	const out = {};
+	for (const m of LOGIN_GETTER_PROBES) if (typeof inst[m] === "function") out[m] = tryShape(inst, m);
 	return out;
 }
+/** 登录信息 getter 候选（无参调用，探测形状）。 */
+const LOGIN_GETTER_PROBES = [
+	"getAccountInfo",
+	"getLoginInfo",
+	"getA2",
+	"getTicket",
+	"getUin",
+	"getUid",
+	"getSelfUin"
+];
 //#endregion
 //#region src/wrapper/probe/probe.ts
 /**
@@ -3332,55 +3685,77 @@ function probeLoginService(ctx) {
 /** 枚举候选 sessionId（nt_0..nt_9 / gpro_0..gpro_9）找 QQ 已 init 的 session。 */
 function enumerateSessionIds(ctx) {
 	const S = ctx.exports.NodeIQQNTWrapperSession;
-	const enumFn = S["getNTWrapperSession"];
+	const enumFn = getNTWrapperSessionFn(ctx);
+	if (enumFn === null) return {};
 	const out = {};
-	if (typeof enumFn !== "function") return out;
-	const ids = [];
-	for (let i = 0; i < 10; i += 1) ids.push(`nt_${i}`, `gpro_${i}`);
-	for (const id of ids) try {
-		const value = enumFn.call(S, id);
-		if (!value) continue;
-		const rec = value;
-		const hasGetter = typeof rec["getMsgService"] === "function";
-		let msgService = null;
-		let msgError = null;
-		try {
-			msgService = rec["getMsgService"].call(value);
-		} catch (e) {
-			msgError = e instanceof Error ? e.message : String(e);
-		}
-		out[id] = {
-			hasMsgServiceGetter: hasGetter,
-			msgServiceOk: msgService !== null && msgService !== void 0,
-			msgServiceMethods: msgService ? listMethods(msgService).length : 0,
-			msgError,
-			methods: listMethods(value)
-		};
-	} catch {}
+	for (let i = 0; i < 10; i += 1) {
+		probeSessionId(enumFn, S, `nt_${i}`, out);
+		probeSessionId(enumFn, S, `gpro_${i}`, out);
+	}
 	return out;
 }
+/** 探测单个 sessionId（getter 存在性 + getMsgService 调用结果）。 */
+function probeSessionId(enumFn, thisCtx, id, out) {
+	try {
+		const value = enumFn.call(thisCtx, id);
+		if (!value) return;
+		out[id] = probeSessionRecord(value);
+	} catch {}
+}
+/** 探测单个 session 记录（getter 存在性 + msgService 调用结果 + 方法面）。 */
+function probeSessionRecord(value) {
+	const rec = value;
+	const msg = tryMsgService(rec, value);
+	return {
+		hasMsgServiceGetter: typeof rec["getMsgService"] === "function",
+		msgServiceOk: msg.service !== null,
+		msgServiceMethods: msg.service ? listMethods(msg.service).length : 0,
+		msgError: msg.error,
+		methods: listMethods(value)
+	};
+}
+/** 尝试调用 getMsgService（失败记录错误，成功返回实例）。 */
+function tryMsgService(rec, thisCtx) {
+	try {
+		return {
+			service: rec["getMsgService"].call(thisCtx) ?? null,
+			error: null
+		};
+	} catch (e) {
+		return {
+			service: null,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/** 取 NodeIQQNTWrapperSession.getNTWrapperSession 函数（无则 null）。 */
+function getNTWrapperSessionFn(ctx) {
+	const fn = ctx.exports.NodeIQQNTWrapperSession["getNTWrapperSession"];
+	return typeof fn === "function" ? fn : null;
+}
 /** 探测 startup 实例：start() + getSessionIdList()，提取 sessionIds（Map 值或键）。 */
 function probeStartupChain(created) {
 	const started = tryCall(created, "start");
 	const ids = tryCall(created, "getSessionIdList");
-	const sessionIds = [];
-	if (ids.ok && ids.value instanceof Map) for (const [k, v] of ids.value) {
-		const id = typeof v === "string" ? v : String(k);
-		sessionIds.push(id);
-	}
 	return {
 		start: started.ok ? { ok: true } : { error: started.error },
 		createdGetSessionIdList: ids.ok ? { value: serialize(ids.value) } : { error: ids.error },
-		sessionIds
+		sessionIds: extractSessionIds(ids)
 	};
 }
+/** 从 getSessionIdList 结果提取 sessionIds（Map 值或键优先）。 */
+function extractSessionIds(ids) {
+	if (!(ids.ok && ids.value instanceof Map)) return [];
+	const out = [];
+	for (const [k, v] of ids.value) out.push(typeof v === "string" ? v : String(k));
+	return out;
+}
 /** 用真实 sessionId 取主 session（getNTWrapperSession(nt_x)）并记录方法面。 */
 function probeSessionById(ctx, id) {
-	const S = ctx.exports.NodeIQQNTWrapperSession;
-	const fn = S["getNTWrapperSession"];
-	if (typeof fn !== "function") return null;
+	const fn = getNTWrapperSessionFn(ctx);
+	if (fn === null) return null;
 	try {
-		const value = fn.call(S, id);
+		const value = fn.call(ctx.exports.NodeIQQNTWrapperSession, id);
 		return value ? {
 			methods: listMethods(value),
 			ownKeys: Object.getOwnPropertyNames(value)
@@ -3391,7 +3766,6 @@ function probeSessionById(ctx, id) {
 }
 /** 兜底：候选名字 getNTWrapperSession（无 Map 数据时）。 */
 function probeByNameFallback(ctx) {
-	const S = ctx.exports.NodeIQQNTWrapperSession;
 	const candidates = [
 		"main",
 		"primary",
@@ -3400,17 +3774,22 @@ function probeByNameFallback(ctx) {
 		""
 	];
 	const getResults = {};
-	for (const name of candidates) try {
-		const fn = S["getNTWrapperSession"];
-		const value = typeof fn === "function" ? fn.call(S, name) : null;
-		getResults[name === "" ? "<empty>" : name] = value ? {
+	for (const name of candidates) getResults[name === "" ? "<empty>" : name] = probeSessionByName(ctx, name);
+	return getResults;
+}
+/** 探测单个候选名（getNTWrapperSession(name)，记录方法面或错误）。 */
+function probeSessionByName(ctx, name) {
+	try {
+		const fn = getNTWrapperSessionFn(ctx);
+		if (fn === null) return null;
+		const value = fn.call(ctx.exports.NodeIQQNTWrapperSession, name);
+		return value ? {
 			methods: listMethods(value),
 			ownKeys: Object.getOwnPropertyNames(value)
 		} : null;
 	} catch (e) {
-		getResults[name === "" ? "<empty>" : name] = { error: e instanceof Error ? e.message : String(e) };
+		return { error: e instanceof Error ? e.message : String(e) };
 	}
-	return getResults;
 }
 /** 探测 startup session 链路：create() → start() → getSessionIdList → getNTWrapperSession。 */
 function probeStartup(ctx) {
@@ -3422,60 +3801,76 @@ function probeStartup(ctx) {
 		methods: created.value ? listMethods(created.value) : [],
 		value: serialize(created.value)
 	} : { error: created.error };
-	if (created.ok && created.value) {
-		const chain = probeStartupChain(created.value);
-		out["start"] = chain.start;
-		out["createdGetSessionIdList"] = chain.createdGetSessionIdList;
-		out["sessionIds"] = chain.sessionIds;
-		const mainId = chain.sessionIds.find((id) => id.startsWith("nt_")) ?? chain.sessionIds[0];
-		if (mainId !== void 0) {
-			out["mainSessionId"] = mainId;
-			out["mainSession"] = probeSessionById(ctx, mainId);
-		}
-	}
+	if (created.ok && created.value) Object.assign(out, probeCreatedChain(ctx, created.value));
 	out["enumSessionIds"] = enumerateSessionIds(ctx);
 	if (out["sessionIds"] === void 0) out["getNTWrapperSession"] = probeByNameFallback(ctx);
 	return out;
 }
+/** 探测 create 后的实例链：start / getSessionIdList / 主 session。 */
+function probeCreatedChain(ctx, created) {
+	const chain = probeStartupChain(created);
+	const out = {
+		start: chain.start,
+		createdGetSessionIdList: chain.createdGetSessionIdList,
+		sessionIds: chain.sessionIds
+	};
+	const mainId = findMainProbeId(chain.sessionIds);
+	if (mainId !== void 0) {
+		out["mainSessionId"] = mainId;
+		out["mainSession"] = probeSessionById(ctx, mainId);
+	}
+	return out;
+}
+/** 选主 sessionId（nt_ 前缀优先，否则第一个）。 */
+function findMainProbeId(sessionIds) {
+	return sessionIds.find((id) => id.startsWith("nt_")) ?? sessionIds[0];
+}
 /** 探测 session 与 service 方法（优先复用 QQ 主 session）。 */
 function probeSession(ctx) {
 	const out = {};
-	let session = null;
+	const session = pickProbeSession(ctx, out);
+	out["session"] = session ? {
+		methods: listMethods(session),
+		ownKeys: Object.getOwnPropertyNames(session)
+	} : null;
+	if (session !== null && session !== void 0) out["services"] = collectServiceGetters(session);
+	return out;
+}
+/** 选探测目标 session：优先 QQ 主 session（getMainSession），回退 ctx.session。 */
+function pickProbeSession(ctx, out) {
 	try {
 		const main = getMainSession(ctx);
 		if (main !== null) {
-			session = main;
 			out["sessionSource"] = "mainSession(getNTWrapperSession)";
+			return main;
 		}
 	} catch {}
-	if (session === null && ctx.session !== null) {
-		session = ctx.session;
+	if (ctx.session !== null) {
 		out["sessionSource"] = "own-create";
+		return ctx.session;
 	}
-	out["session"] = session ? {
-		methods: listMethods(session),
-		ownKeys: Object.getOwnPropertyNames(session)
-	} : null;
-	if (session !== null && session !== void 0) {
-		const getters = listMethods(session).filter((m) => m.startsWith("get") && m.endsWith("Service"));
-		const services = {};
-		for (const getter of getters) {
-			const call = tryCall(session, getter);
-			if (call.ok && call.value) {
-				const methods = listMethods(call.value);
-				services[getter] = {
-					methods,
-					ownKeys: Object.getOwnPropertyNames(call.value).slice(0, 20),
-					shapes: shapeKeyGetters(call.value, methods)
-				};
-			} else services[getter] = {
-				error: call.error ?? "null/undefined",
-				ok: call.ok
-			};
-		}
-		out["services"] = services;
-	}
-	return out;
+	return null;
+}
+/** 收集 session 的 get*Service getter 方法面与返回形状。 */
+function collectServiceGetters(session) {
+	const getters = listMethods(session).filter((m) => m.startsWith("get") && m.endsWith("Service"));
+	const services = {};
+	for (const getter of getters) services[getter] = probeServiceGetter(session, getter);
+	return services;
+}
+/** 探测单个 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)
+	};
 }
 /**
 * 探测 wrapper 运行时：dump session 方法与各 service 方法到 JSON。
@@ -3522,12 +3917,11 @@ function readVersionPackage(installDir, version) {
 	if (!existsSync(pkgPath)) throw kernelError(`QQ 版本目录缺少 package.json: ${pkgPath}`, "NOT_FOUND");
 	try {
 		const raw = JSON.parse(readFileSync(pkgPath, "utf8"));
-		const result = {
+		return {
 			name: raw.name ?? "",
-			version: raw.version ?? ""
+			version: raw.version ?? "",
+			...raw.buildVersion !== void 0 ? { buildVersion: raw.buildVersion } : {}
 		};
-		if (raw.buildVersion !== void 0) result.buildVersion = raw.buildVersion;
-		return result;
 	} catch (cause) {
 		throw kernelError(`QQ 版本 package.json 解析失败: ${pkgPath}`, "INVALID_PARAM", { cause });
 	}