@napuketto/kernel 0.0.16 → 0.1.0

package/dist/index.mjs

@@ -429,7 +429,7 @@ var FriendApi = class {
 			if (raw.result !== 0) throw kernelError(`getBuddyListV2 失败: ${raw.errMsg}`, "UNKNOWN");
 			categories = raw.data;
 		}
-		const uids = categories.flatMap((cat) => cat.buddyUids);
+		const uids = categories.flatMap((cat) => cat.buddyList?.map((b) => b.uid) ?? cat.buddyUids ?? []);
 		let uinMap = /* @__PURE__ */ new Map();
 		if (this.uidToUin !== void 0) uinMap = await this.uidToUin(uids);
 		const out = [];
@@ -448,7 +448,7 @@ var FriendApi = class {
 		for (const friend of await this.getFriendList()) friendMap.set(friend.uid, friend);
 		return categories.map((cat) => {
 			const buddies = [];
-			for (const uid of cat.buddyUids) {
+			for (const uid of cat.buddyList?.map((b) => b.uid) ?? cat.buddyUids ?? []) {
 				const friend = friendMap.get(uid);
 				if (friend !== void 0) buddies.push(friend);
 			}
@@ -1231,6 +1231,18 @@ const PTT_WAVE_AMPLITUDES = [
 	15,
 	17
 ];
+/** downloadRichMedia 契约值（2026-09-08 B1 实测：downloadType=2 可用 / thumbSize=0）。 */
+const DOWNLOAD_TYPE_COMMON = 2;
+const THUMB_SIZE_NONE = 0;
+/** 语音下载轮询参数（300ms × 34 ≈ 10s；返回 void 只能经重拉元素观察完成）。 */
+const PTT_POLL_INTERVAL_MS = 300;
+const PTT_POLL_TIMES = 34;
+/** sleep（下载轮询间隔）。 */
+function sleep$1(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
 /** 读文件 stat（富媒体发送预处理；文件不存在抛 INVALID_PARAM）。 */
 async function statFile(path) {
 	try {
@@ -1491,6 +1503,35 @@ var MsgApi = class {
 	async markRead(target) {
 		unwrapResult("setMsgRead", await this.service.setMsgRead(target));
 	}
+	/**
+	* 语音主动下载（get_record 本地未命中兜底，2026-09-08 B1）。
+	* downloadRichMedia 返回 void（实测），完成信号 = 重拉消息元素：
+	* 轮询（300ms × 34，约 10s）直到 filePath 非空且 transferStatus 进入
+	* 已下载态（2/4）；超时但 filePath 已有值则尽力返回（磁盘命中判断留给
+	* 调用方），完全无路径抛 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 ?? "";
+		await this.service.downloadRichMedia({
+			msgId,
+			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;
+		}
+		throw kernelError("语音下载未完成（超时）", "TIMEOUT");
+	}
 	/** 发送输入状态（set_input_status；eventType=1 输入中，0 停止）。 */
 	async setInputStatus(target, eventType) {
 		await this.service.sendShowInputStatusReq(target.chatType, eventType, target.peerUid);
@@ -2091,7 +2132,8 @@ var GroupBridge = class {
 			onMemberInfoChange: (groupCode, dataSource, members) => this.channel.emit("Group/onMemberInfoChange", groupCode, dataSource, members),
 			onGroupNotifiesUpdated: (doubt, notifies) => this.channel.emit("Group/onGroupNotifiesUpdated", doubt, notifies),
 			onGroupSingleScreenNotifies: (doubt, seq, notifies) => this.channel.emit("Group/onGroupSingleScreenNotifies", doubt, seq, notifies),
-			onShutUpMemberListChanged: (groupCode, members) => this.channel.emit("Group/onShutUpMemberListChanged", groupCode, members)
+			onShutUpMemberListChanged: (groupCode, members) => this.channel.emit("Group/onShutUpMemberListChanged", groupCode, members),
+			onGroupEssenceListChange: (arg) => this.channel.emit("Group/onGroupEssenceListChange", arg)
 		};
 		this.listenerId = this.service.addKernelGroupListener(listener);
 	}
@@ -2125,7 +2167,10 @@ var MsgBridge = class {
 			onRecvMsg: (msgs) => this.channel.emit("Msg/onRecvMsg", msgs),
 			onRecvMsgReadReport: (reports) => this.channel.emit("Msg/onRecvMsgReadReport", reports),
 			onRecvMsgReceipt: (receipts) => this.channel.emit("Msg/onRecvMsgReceipt", receipts),
-			onMsgInfoListUpdate: (msgs) => this.channel.emit("Msg/onMsgInfoListUpdate", msgs)
+			onMsgInfoListUpdate: (msgs) => this.channel.emit("Msg/onMsgInfoListUpdate", msgs),
+			onRecvOfflineFileMsg: (arg) => this.channel.emit("Msg/onRecvOfflineFileMsg", arg),
+			onRecvOnlineFileMsg: (arg) => this.channel.emit("Msg/onRecvOnlineFileMsg", arg),
+			onRecvSysMsg: (arg) => this.channel.emit("Msg/onRecvSysMsg", arg)
 		};
 		this.listenerId = this.service.addKernelMsgListener(listener);
 	}
@@ -2137,6 +2182,193 @@ var MsgBridge = class {
 	}
 };
 //#endregion
+//#region src/event-channel.ts
+/**
+* 类型化事件通道（ADR-003）
+*
+* - 事件名约定 `${Service}/${method}`（如 "Msg/onRecvMsg"），签名从 Listener 接口编译期推导
+* - 事件名写错 → 编译期报错（类型推导）
+* - `on` 返回 unsubscribe；`waitFor` 注册临时监听 → filter → 超时自动清理（替代魔法字符串方案）
+* - error 兜底：监听器抛异常不打断派发，统一经 `onError` 通知
+*
+* 组合实现而非 extends EventEmitter：EventEmitter.on 返回 `this`，与设计要求的
+* 返回 unsubscribe 冲突；组合更干净，且内核无全局单例（ADR-015 推论）。
+*
+* 类型推导说明：不直接 `ListenerEvents<L, Name>[E]` 索引（泛型下会扩宽到
+* string|number|symbol 索引，索引出 unknown），而是用 Extract 按事件名从
+* `{ name, fn }` 联合精确提取 handler / 参数类型，保证实例化后签名精确。
+*/
+/** waitFor 默认超时（毫秒）。 */
+const DEFAULT_WAIT_TIMEOUT_MS = 3e4;
+/**
+* 类型化事件通道。
+*
+* @typeParam L - Listener 接口（探测产物，如 MsgListener）
+* @typeParam Name - Service 名（事件名前缀，如 "Msg"）
+*/
+var NTEventChannel = class {
+	serviceName;
+	emitter = new EventEmitter();
+	errorHandlers = /* @__PURE__ */ new Set();
+	anyHandlers = /* @__PURE__ */ new Set();
+	constructor(serviceName) {
+		this.serviceName = serviceName;
+		this.emitter.setMaxListeners(0);
+	}
+	/**
+	* 订阅事件：返回 unsubscribe（只注销该 handler，不影响其他订阅者）。
+	* 每个 Service 只注册一次原生监听，缓存维护与协议翻译都订阅这里。
+	*/
+	on(event, handler) {
+		this.emitter.addListener(event, handler);
+		return () => {
+			this.emitter.removeListener(event, handler);
+		};
+	}
+	/**
+	* 请求-响应桥：注册临时监听 → filter 命中 → resolve；超时自动清理并 reject。
+	* 替代魔法字符串事件名方案。
+	*/
+	waitFor(event, opts = {}) {
+		const timeoutMs = opts.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+		return new Promise((resolve, reject) => {
+			const handler = (...args) => {
+				if (opts.filter && !opts.filter(...args)) return;
+				cleanup();
+				resolve(args);
+			};
+			const timer = setTimeout(() => {
+				cleanup();
+				reject(new KernelError(`等待事件超时: ${event}`, "TIMEOUT"));
+			}, timeoutMs);
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.emitter.removeListener(event, handler);
+			};
+			this.emitter.addListener(event, handler);
+		});
+	}
+	/**
+	* 类型化派发：wrapper-loader 的原生回调经此推入通道。
+	* 2026-08-07 修复：原生 EventEmitter.emit 中一个 listener 抛异常会中断后续
+	* listener 派发（Node 语义）——改为快照数组逐个 try/catch，保证「单个订阅者
+	* 异常不打断派发」（协议翻译层异常不饿死缓存维护等其他订阅者）。
+	*/
+	/**
+	* 订阅所有事件（IPC 子进程模式整通道转发用：事件名 `"${service}/${method}"`
+	* 经 handler 首参透出，args 原样透传）。返回退订函数。
+	*/
+	onAny(handler) {
+		this.anyHandlers.add(handler);
+		return () => {
+			this.anyHandlers.delete(handler);
+		};
+	}
+	emit(event, ...args) {
+		for (const anyHandler of this.anyHandlers) try {
+			anyHandler(event, ...args);
+		} catch (err) {
+			this.notifyError(err);
+		}
+		const listeners = this.emitter.listeners(event);
+		for (const listener of listeners) try {
+			listener(...args);
+		} catch (err) {
+			this.notifyError(err);
+		}
+	}
+	/** 通知所有错误处理器（单个异常不打断其他处理器）。 */
+	notifyError(err) {
+		for (const handler of this.errorHandlers) handler(err);
+	}
+	/** 订阅错误通知（监听器抛出的异常 / 其他内部错误）。 */
+	onError(handler) {
+		this.errorHandlers.add(handler);
+		return () => {
+			this.errorHandlers.delete(handler);
+		};
+	}
+};
+//#endregion
+//#region src/cache/buddy-cache.ts
+/**
+* 防御性收窄 onBuddyListChange 载荷 → BuddyCategory[]（T10 实证形状；
+* 非数组返回 null，调用方打 raw 日志积累校准数据）。
+*/
+function narrowBuddyCategories(arg) {
+	if (!Array.isArray(arg)) return null;
+	for (const item of arg) if (item === null || typeof item !== "object") return null;
+	return arg;
+}
+/** 从快照分类拍平好友明细（buddyList 缺失的分类跳过）。 */
+function flattenEntries(categories) {
+	const out = [];
+	for (const cat of categories) for (const entry of cat.buddyList ?? []) if (typeof entry?.uid === "string" && entry.uid !== "") out.push(entry);
+	return out;
+}
+/** 好友缓存：快照维护 + diff 归一化事件。 */
+var BuddyCache = class {
+	channel;
+	logger;
+	/** diff 归一化事件通道（协议层订阅 friend_add / IPC 转发消费）。 */
+	events = new NTEventChannel("BuddyCache");
+	/** 好友快照（uid → entry，onBuddyListChange 全量维护）。 */
+	buddies = /* @__PURE__ */ new Map();
+	/** 首帧已建 baseline（此后快照才参与 diff）。 */
+	bootstrapped = false;
+	unsubscribes = null;
+	constructor(opts) {
+		this.channel = opts.channel;
+		this.logger = opts.logger;
+	}
+	/** 订阅 Buddy 事件通道（幂等）。 */
+	register() {
+		if (this.unsubscribes !== null) return;
+		const unsub = this.channel.on("Buddy/onBuddyListChange", (arg) => {
+			const categories = narrowBuddyCategories(arg);
+			if (categories === null) {
+				this.logger?.warn({ raw: JSON.stringify(arg)?.slice(0, 2e3) }, "BuddyCache: onBuddyListChange 未知载荷形状");
+				return;
+			}
+			this.applySnapshot(flattenEntries(categories));
+		});
+		this.unsubscribes = unsub;
+	}
+	/** 退订事件通道（幂等）。 */
+	unregister() {
+		this.unsubscribes?.();
+		this.unsubscribes = null;
+		this.buddies.clear();
+		this.bootstrapped = false;
+	}
+	/** 应用全量快照：首帧建 baseline，之后 diff 发布归一化事件。 */
+	applySnapshot(entries) {
+		if (!this.bootstrapped) {
+			for (const entry of entries) this.buddies.set(entry.uid, entry);
+			this.bootstrapped = true;
+			return;
+		}
+		const next = /* @__PURE__ */ new Map();
+		for (const entry of entries) next.set(entry.uid, entry);
+		for (const [uid, entry] of next) if (!this.buddies.has(uid)) this.events.emit("BuddyCache/onBuddyAdded", entry);
+		for (const [uid, entry] of this.buddies) if (!next.has(uid)) this.events.emit("BuddyCache/onBuddyRemoved", entry);
+		this.buddies.clear();
+		for (const [uid, entry] of next) this.buddies.set(uid, entry);
+	}
+	/** 好友快照（只读拷贝）。 */
+	listBuddies() {
+		return [...this.buddies.values()];
+	}
+	/** 单个好友（快照；undefined = 不在缓存）。 */
+	getBuddy(uid) {
+		return this.buddies.get(uid);
+	}
+	/** 快照是否已建（测试/诊断用）。 */
+	get baselineReady() {
+		return this.bootstrapped;
+	}
+};
+//#endregion
 //#region src/login/wait.ts
 /**
 * 等待/延迟工具（login 模块共享，2026-08-08 克隆合并）
@@ -3529,114 +3761,6 @@ function resolveCommonPath(ctx, wrapper) {
 	return ctx.paths.accountDir;
 }
 //#endregion
-//#region src/event-channel.ts
-/**
-* 类型化事件通道（ADR-003）
-*
-* - 事件名约定 `${Service}/${method}`（如 "Msg/onRecvMsg"），签名从 Listener 接口编译期推导
-* - 事件名写错 → 编译期报错（类型推导）
-* - `on` 返回 unsubscribe；`waitFor` 注册临时监听 → filter → 超时自动清理（替代魔法字符串方案）
-* - error 兜底：监听器抛异常不打断派发，统一经 `onError` 通知
-*
-* 组合实现而非 extends EventEmitter：EventEmitter.on 返回 `this`，与设计要求的
-* 返回 unsubscribe 冲突；组合更干净，且内核无全局单例（ADR-015 推论）。
-*
-* 类型推导说明：不直接 `ListenerEvents<L, Name>[E]` 索引（泛型下会扩宽到
-* string|number|symbol 索引，索引出 unknown），而是用 Extract 按事件名从
-* `{ name, fn }` 联合精确提取 handler / 参数类型，保证实例化后签名精确。
-*/
-/** waitFor 默认超时（毫秒）。 */
-const DEFAULT_WAIT_TIMEOUT_MS = 3e4;
-/**
-* 类型化事件通道。
-*
-* @typeParam L - Listener 接口（探测产物，如 MsgListener）
-* @typeParam Name - Service 名（事件名前缀，如 "Msg"）
-*/
-var NTEventChannel = class {
-	serviceName;
-	emitter = new EventEmitter();
-	errorHandlers = /* @__PURE__ */ new Set();
-	anyHandlers = /* @__PURE__ */ new Set();
-	constructor(serviceName) {
-		this.serviceName = serviceName;
-		this.emitter.setMaxListeners(0);
-	}
-	/**
-	* 订阅事件：返回 unsubscribe（只注销该 handler，不影响其他订阅者）。
-	* 每个 Service 只注册一次原生监听，缓存维护与协议翻译都订阅这里。
-	*/
-	on(event, handler) {
-		this.emitter.addListener(event, handler);
-		return () => {
-			this.emitter.removeListener(event, handler);
-		};
-	}
-	/**
-	* 请求-响应桥：注册临时监听 → filter 命中 → resolve；超时自动清理并 reject。
-	* 替代魔法字符串事件名方案。
-	*/
-	waitFor(event, opts = {}) {
-		const timeoutMs = opts.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
-		return new Promise((resolve, reject) => {
-			const handler = (...args) => {
-				if (opts.filter && !opts.filter(...args)) return;
-				cleanup();
-				resolve(args);
-			};
-			const timer = setTimeout(() => {
-				cleanup();
-				reject(new KernelError(`等待事件超时: ${event}`, "TIMEOUT"));
-			}, timeoutMs);
-			const cleanup = () => {
-				clearTimeout(timer);
-				this.emitter.removeListener(event, handler);
-			};
-			this.emitter.addListener(event, handler);
-		});
-	}
-	/**
-	* 类型化派发：wrapper-loader 的原生回调经此推入通道。
-	* 2026-08-07 修复：原生 EventEmitter.emit 中一个 listener 抛异常会中断后续
-	* listener 派发（Node 语义）——改为快照数组逐个 try/catch，保证「单个订阅者
-	* 异常不打断派发」（协议翻译层异常不饿死缓存维护等其他订阅者）。
-	*/
-	/**
-	* 订阅所有事件（IPC 子进程模式整通道转发用：事件名 `"${service}/${method}"`
-	* 经 handler 首参透出，args 原样透传）。返回退订函数。
-	*/
-	onAny(handler) {
-		this.anyHandlers.add(handler);
-		return () => {
-			this.anyHandlers.delete(handler);
-		};
-	}
-	emit(event, ...args) {
-		for (const anyHandler of this.anyHandlers) try {
-			anyHandler(event, ...args);
-		} catch (err) {
-			this.notifyError(err);
-		}
-		const listeners = this.emitter.listeners(event);
-		for (const listener of listeners) try {
-			listener(...args);
-		} catch (err) {
-			this.notifyError(err);
-		}
-	}
-	/** 通知所有错误处理器（单个异常不打断其他处理器）。 */
-	notifyError(err) {
-		for (const handler of this.errorHandlers) handler(err);
-	}
-	/** 订阅错误通知（监听器抛出的异常 / 其他内部错误）。 */
-	onError(handler) {
-		this.errorHandlers.add(handler);
-		return () => {
-			this.errorHandlers.delete(handler);
-		};
-	}
-};
-//#endregion
 //#region src/wrapper/session-resolver.ts
 /** 从 getSessionIdList 的 Map 提取主 sessionId（nt_ 前缀优先）。 */
 function findMainSessionId(ids) {
@@ -4211,6 +4335,6 @@ function listQQVersions(installDir) {
 	}).sort().reverse();
 }
 //#endregion
-export { ChatType, ConfigBase, DEFAULT_DATA_ROOT_NAME, ElementType, FriendApi, FriendBridge, GrayTipSubType, GroupApi, GroupBridge, GroupCache, GroupListUpdateType, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, KERNEL_ERROR_CODES, KernelError, MAIN_CONFIG_FILE, MsgApi, MsgBridge, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, PathWrapper, ProfileApi, ProfileLikeApi, QrLoginSession, RichMediaApi, TicketApi, TipGroupElementType, WebApi, WebHonorType, buildEngineConfig, buildLoginConfig, buildSessionConfig, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, parseAppidFromMajor, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
+export { BuddyCache, ChatType, ConfigBase, DEFAULT_DATA_ROOT_NAME, ElementType, FriendApi, FriendBridge, GrayTipSubType, GroupApi, GroupBridge, GroupCache, GroupListUpdateType, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, KERNEL_ERROR_CODES, KernelError, MAIN_CONFIG_FILE, MsgApi, MsgBridge, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, PathWrapper, ProfileApi, ProfileLikeApi, QrLoginSession, RichMediaApi, TicketApi, TipGroupElementType, WebApi, WebHonorType, buildEngineConfig, buildLoginConfig, buildSessionConfig, createCoreContext, createSessionListener as createLifecycleSessionListener, createSessionListener, createLogger, createLoginListener, createSession, createWrapper, electronProcessType, getExistingSession, getMainSession, initAndStartSession, initEngine, initSession, isKernelError, kernelError, listLoginAccounts, listQQVersions, narrowBuddyCategories, parseAppidFromMajor, parseToml, probeRuntime, quickLogin, readMachineGuid, resolveAppidQua, resolveConfigPath, resolveDataRoot, resolveQQVersion, resolveQqGlobalPath, resolveQqUserDataRoot, resolveWrapperPath, startNapuketto, startSession, stringifyToml, toCanonicalElements, toSendElements, waitForNetworkConnection, waitSessionReady };
 
 //# sourceMappingURL=index.mjs.map