@napuketto/kernel 0.0.16 → 0.1.0

package/dist/index.cjs

@@ -455,7 +455,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 = [];
@@ -474,7 +474,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);
 			}
@@ -1257,6 +1257,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 {
@@ -1517,6 +1529,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);
@@ -2117,7 +2158,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);
 	}
@@ -2151,7 +2193,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);
 	}
@@ -2163,6 +2208,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 node_events.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 克隆合并）
@@ -3555,114 +3787,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 node_events.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) {
@@ -4237,6 +4361,7 @@ function listQQVersions(installDir) {
 	}).sort().reverse();
 }
 //#endregion
+exports.BuddyCache = BuddyCache;
 exports.ChatType = ChatType;
 exports.ConfigBase = ConfigBase;
 exports.DEFAULT_DATA_ROOT_NAME = DEFAULT_DATA_ROOT_NAME;
@@ -4289,6 +4414,7 @@ exports.isKernelError = isKernelError;
 exports.kernelError = kernelError;
 exports.listLoginAccounts = listLoginAccounts;
 exports.listQQVersions = listQQVersions;
+exports.narrowBuddyCategories = narrowBuddyCategories;
 exports.parseAppidFromMajor = parseAppidFromMajor;
 exports.parseToml = parseToml;
 exports.probeRuntime = probeRuntime;

package/dist/index.d.cts

@@ -69,6 +69,16 @@ interface PttElement {
   otherBusinessInfo?: {
     aiVoiceType: number;
   };
+  fileId?: number;
+  fileUuid?: string;
+  translateStatus?: number;
+  /** 传输状态：实测 2=收到已下载（数据库态，此时挪走本地文件调 downloadRichMedia 不重下）、4=自己发送已上传。 */
+  transferStatus?: number;
+  progress?: number;
+  invalidState?: number;
+  fileBizId?: unknown;
+  import_rich_media_context?: unknown;
+  isInApplicationDataPath?: boolean | null;
 }
 /** 表情元素。 */
 interface FaceElement {
@@ -300,6 +310,18 @@ interface NodeIKernelMsgService {
   getMsgsByMsgId(peer: Peer, ids: string[]): Promise<GeneralCallResult & {
     msgList?: RawMessage[];
   }>;
+  /**
+   * 富媒体主动下载（get_record 语音下载，2026-09-08 B1 实测：单参数对象，
+   * resolve undefined——结果只能经重拉消息元素观察；参数残缺时静默 no-op 不抛错；
+   * transferStatus=2 已下载态调用为 no-op，详见 kernel design.md §5）。
+   */
+  downloadRichMedia(param: {
+    msgId: string;
+    elemId: string;
+    chatType: number;
+    downloadType: number;
+    thumbSize: number;
+  }): Promise<void>;
   setMsgRead(peer: Peer): Promise<GeneralCallResult>;
   /** 消息表情表态（set_msg_emoji_like；setOrCancel=true 点赞，false 取消）。 */
   setMsgEmojiLikes(peer: Peer, msgSeq: string, emojiId: string, emojiType: string, setOrCancel: boolean): Promise<GeneralCallResult>;
@@ -631,6 +653,14 @@ type GroupListener = {
   onGroupSingleScreenNotifies: (doubt: boolean, seq: string, notifies: GroupNotify[]) => void;
   /** 群禁言成员列表变化。 */
   onShutUpMemberListChanged: (groupCode: string, members: ShutUpGroupMember[]) => void;
+  /**
+   * 群精华列表变化（OB11 group_essence 候选源，2026-09-10 接线）。
+   * 证据：wrapper.node 9.9.33-52230 字符串——小写名位于 listener 反射字符串簇，
+   * 与已知 onMemberListChange/onBuddyReqChange 交错（同一字符串表页）；
+   * API 族旁证 addGroupEssence/getGroupLatestEssenceList。
+   * ⚠️ 参数形状待真实事件校准（unknown 透传，订阅方 raw 日志观测）。
+   */
+  onGroupEssenceListChange: (arg: unknown) => void;
 };
 //#endregion
 //#region src/types/listeners/msg.d.ts
@@ -663,6 +693,28 @@ type MsgListener = {
    *  2026-08-11 补齐：sendMsg 发送结果以此事件为准（NapCat 同款），
    *  sendMsg 返回值 result 可能非 0 但实际发送成功（异步确认）。 */
   onMsgInfoListUpdate: (msgs: RawMessage[]) => void;
+  /**
+   * 收到离线文件消息（OB11 offline_file 事件源，2026-09-10 接线）。
+   * 证据：wrapper.node 9.9.33-52230 字符串——小写名位于 listener 反射字符串簇
+   * （与 onRecvMsg 同页，offset 差 ~7KB）+ RTTI
+   * `OnRecvOfflineFileMsg@KernelMsgService@wrapper@nt`；API 族旁证
+   * getNewOfflineFileList。⚠️ 参数形状待真实事件校准（unknown 透传）。
+   */
+  onRecvOfflineFileMsg: (arg: unknown) => void;
+  /**
+   * 收到在线文件消息（onRecvOfflineFileMsg 同族，字符串簇相邻；
+   * OB11 无对应通知类型，仅作校准观测）。参数形状待校准。
+   */
+  onRecvOnlineFileMsg: (arg: unknown) => void;
+  /**
+   * 收到系统消息（sys msg 总闸，2026-09-10 接线）：群名片/头衔/精华/荣誉等
+   * 系统事件的根载体（二进制 55 个 OnSysMsg* 处理器；另有请求式
+   * registerSysMsgNotification(type, subType, ids, callback) 需 3 参）。
+   * 证据：小写名与 onRecvMsg 相邻（offset 差 ~1.4KB）+ 日志
+   * `OnRecvSysMsg msg_type=0x{:x} sub_type=0x{:x} is_online={}`。
+   * ⚠️ 参数形状待真实事件校准（unknown 透传，订阅方 raw 日志观测）。
+   */
+  onRecvSysMsg: (arg: unknown) => void;
 };
 //#endregion
 //#region src/types/message-element.d.ts
@@ -721,14 +773,38 @@ type CanonicalElement = {
 };
 //#endregion
 //#region src/types/services/buddy-service.d.ts
-/** 好友列表分类（getBuddyListV2 返回，说明书参考）。 */
+/** 好友核心信息（BuddyListEntry.coreInfo，2026-09-08 T10 实测）。 */
+interface BuddyCoreInfo {
+  uid: string;
+  uin: string;
+  nick?: string;
+  remark?: string;
+  [key: string]: unknown;
+}
+/** 好友列表明细（BuddyCategory.buddyList 成员，2026-09-08 T10 实测快照）。 */
+interface BuddyListEntry {
+  uid: string;
+  /** 顶层 uin（coreInfo.uin 同值；缺失时回退 coreInfo）。 */
+  uin?: string;
+  coreInfo?: BuddyCoreInfo;
+  baseInfo?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * 好友列表分类（getBuddyListV2 返回 / onBuddyListChange 全量快照载荷）。
+ * ⚠️ 2026-09-08 T10 实测：onBuddyListChange 载荷 = BuddyCategory[]，分类项
+ * 含 buddyList 明细（uid/uin/coreInfo/baseInfo）；实测样本无 buddyUids——
+ * 两字段均按 optional 防御（旧描述的 buddyUids 保留兼容）。
+ */
 interface BuddyCategory {
   categoryId: number;
   categorySortId: number;
   categroyName: string;
   categroyMbCount: number;
   onlineCount: number;
-  buddyUids: string[];
+  buddyUids?: string[];
+  /** 好友明细（onBuddyListChange 快照，T10 实证）。 */
+  buddyList?: BuddyListEntry[];
 }
 /** 好友申请（getBuddyReq 返回的 buddyReqs 成员，说明书参考，待探测校准）。 */
 interface BuddyReq {
@@ -1535,6 +1611,14 @@ declare class MsgApi {
   fetchPttText(msgId: string, target: Peer): Promise<string>;
   /** 标记会话已读。 */
   markRead(target: Peer): Promise<void>;
+  /**
+   * 语音主动下载（get_record 本地未命中兜底，2026-09-08 B1）。
+   * downloadRichMedia 返回 void（实测），完成信号 = 重拉消息元素：
+   * 轮询（300ms × 34，约 10s）直到 filePath 非空且 transferStatus 进入
+   * 已下载态（2/4）；超时但 filePath 已有值则尽力返回（磁盘命中判断留给
+   * 调用方），完全无路径抛 NOT_FOUND。
+   */
+  downloadPtt(msgId: string, target: Peer): Promise<PttElement>;
   /** 发送输入状态（set_input_status；eventType=1 输入中，0 停止）。 */
   setInputStatus(target: Peer, eventType: number): Promise<void>;
   /**
@@ -1751,6 +1835,54 @@ declare class GroupBridge {
   unregister(): void;
 }
 //#endregion
+//#region src/cache/buddy-cache.d.ts
+/** BuddyCache diff 事件 listener（归一化「新增/删除」事件）。 */
+type BuddyCacheListener = {
+  onBuddyAdded: (entry: BuddyListEntry) => void;
+  onBuddyRemoved: (entry: BuddyListEntry) => void;
+};
+/** BuddyCache diff 事件通道（事件名 BuddyCache/onBuddyAdded 等）。 */
+type BuddyCacheEventChannel = NTEventChannel<BuddyCacheListener, "BuddyCache">;
+/** BuddyCache 构造参数。 */
+interface BuddyCacheOptions {
+  /** Buddy 事件通道（FriendBridge 注册原生监听后 emit 到这里）。 */
+  channel: BuddyEventChannel;
+  /** 校准日志（可选：快照形状异常 raw 记录；缺省静默）。 */
+  logger?: {
+    warn(obj: unknown, msg?: string): void;
+  };
+}
+/**
+ * 防御性收窄 onBuddyListChange 载荷 → BuddyCategory[]（T10 实证形状；
+ * 非数组返回 null，调用方打 raw 日志积累校准数据）。
+ */
+declare function narrowBuddyCategories(arg: unknown): BuddyCategory[] | null;
+/** 好友缓存：快照维护 + diff 归一化事件。 */
+declare class BuddyCache {
+  private readonly channel;
+  private readonly logger;
+  /** diff 归一化事件通道（协议层订阅 friend_add / IPC 转发消费）。 */
+  readonly events: BuddyCacheEventChannel;
+  /** 好友快照（uid → entry，onBuddyListChange 全量维护）。 */
+  private readonly buddies;
+  /** 首帧已建 baseline（此后快照才参与 diff）。 */
+  private bootstrapped;
+  private unsubscribes;
+  constructor(opts: BuddyCacheOptions);
+  /** 订阅 Buddy 事件通道（幂等）。 */
+  register(): void;
+  /** 退订事件通道（幂等）。 */
+  unregister(): void;
+  /** 应用全量快照：首帧建 baseline，之后 diff 发布归一化事件。 */
+  private applySnapshot;
+  /** 好友快照（只读拷贝）。 */
+  listBuddies(): BuddyListEntry[];
+  /** 单个好友（快照；undefined = 不在缓存）。 */
+  getBuddy(uid: string): BuddyListEntry | undefined;
+  /** 快照是否已建（测试/诊断用）。 */
+  get baselineReady(): boolean;
+}
+//#endregion
 //#region src/cache/group-cache.d.ts
 /** GroupCache 构造参数。 */
 interface GroupCacheOptions {
@@ -2480,5 +2612,5 @@ interface QQVersionInfo {
   qua: string;
 }
 //#endregion
-export { type BootEnv, type BuddyCategory, type BuddyEventChannel, type BuddyListener, type BuddyReq, type CanonicalElement, ChatType, ConfigBase, type ConfigFormat, type ConfigOptions, type ConfigSchema, type CoreContext, type CoreContextOptions, type CoreLoginOptions, DEFAULT_DATA_ROOT_NAME, type DesktopPathConfig, type DeviceInfo, type DoubtBuddyReq, type DoubtFriendRequestInfo, ElementType, type EnginInitDesktopConfig, type EssenceMsgItem, type ForceFetchClientKeyRetType, type Friend, FriendApi, FriendBridge, type FriendCategory, type GeneralCallResult, type GetFileListParam, type GrayTipElement, type GrayTipRevokeElement, GrayTipSubType, type Group, GroupApi, GroupBridge, GroupCache, type GroupCacheOptions, type GroupDetailInfo, type GroupEventChannel, type GroupFileItemInfo, type GroupFolderInfo, type GroupHonorWebInfo, GroupListUpdateType, type GroupListener, type GroupMember, type GroupMemberDataSource, type GroupMemberListChange, type GroupNotify, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, type GroupSpaceInfo, type HonorListItem, KERNEL_ERROR_CODES, KernelError, type KernelErrorCode, type ListenerEvents, type LogLevel, type LoggerOptions, type LoginAccountInfo, type LoginListItem, type LoginProgress, type LoginResult, type LoginState, MAIN_CONFIG_FILE, MsgApi, MsgBridge, type MsgEventChannel, type MsgListener, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, type NapukettoCoreOptions, type NodeIDependsAdapter, type NodeIDispatcherAdapter, type NodeIGlobalAdapter, type NodeIKernelBuddyService, type NodeIKernelGroupService, type NodeIKernelLoginService, type NodeIKernelMsgService, type NodeIKernelProfileLikeService, type NodeIKernelProfileService, type NodeIKernelRichMediaService, type NodeIKernelSessionListener, type NodeIKernelTicketService, type NodeIQQNTStartupSessionWrapper, type NodeIQQNTWrapperEngine, type NodeIQQNTWrapperSession, type NodeQQNTWrapperUtil, type PathOptions, PathWrapper, type Peer, type PlatformType, ProfileApi, ProfileLikeApi, type QQVersionContext, type QQVersionInfo, type QrCodeData, QrLoginSession, type RDeliveryConfig, type RawElement, type RawMessage, RichMediaApi, type SelfInfo, type SendMessageElement, type SessionConfigOptions, type ShutUpGroupMember, type StartNapukettoOptions, type StrangerInfo, TicketApi, type TipAioOpGrayTipElement, type TipGroupElement, TipGroupElementType, type UserDetailInfoByUin, type VendorType, WebApi, WebHonorType, type WrapperContext, type WrapperNodeApi, type WrapperSessionInitConfig, 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 { type BootEnv, BuddyCache, type BuddyCacheEventChannel, type BuddyCacheListener, type BuddyCacheOptions, type BuddyCategory, type BuddyCoreInfo, type BuddyEventChannel, type BuddyListEntry, type BuddyListener, type BuddyReq, type CanonicalElement, ChatType, ConfigBase, type ConfigFormat, type ConfigOptions, type ConfigSchema, type CoreContext, type CoreContextOptions, type CoreLoginOptions, DEFAULT_DATA_ROOT_NAME, type DesktopPathConfig, type DeviceInfo, type DoubtBuddyReq, type DoubtFriendRequestInfo, ElementType, type EnginInitDesktopConfig, type EssenceMsgItem, type ForceFetchClientKeyRetType, type Friend, FriendApi, FriendBridge, type FriendCategory, type GeneralCallResult, type GetFileListParam, type GrayTipElement, type GrayTipRevokeElement, GrayTipSubType, type Group, GroupApi, GroupBridge, GroupCache, type GroupCacheOptions, type GroupDetailInfo, type GroupEventChannel, type GroupFileItemInfo, type GroupFolderInfo, type GroupHonorWebInfo, GroupListUpdateType, type GroupListener, type GroupMember, type GroupMemberDataSource, type GroupMemberListChange, type GroupNotify, GroupNotifyApi, GroupNotifyMsgStatus, GroupNotifyMsgType, type GroupSpaceInfo, type HonorListItem, KERNEL_ERROR_CODES, KernelError, type KernelErrorCode, type ListenerEvents, type LogLevel, type LoggerOptions, type LoginAccountInfo, type LoginListItem, type LoginProgress, type LoginResult, type LoginState, MAIN_CONFIG_FILE, MsgApi, MsgBridge, type MsgEventChannel, type MsgListener, NTEventChannel, NTGroupMemberRole, NTGroupRequestOperateTypes, NapukettoCore, type NapukettoCoreOptions, type NodeIDependsAdapter, type NodeIDispatcherAdapter, type NodeIGlobalAdapter, type NodeIKernelBuddyService, type NodeIKernelGroupService, type NodeIKernelLoginService, type NodeIKernelMsgService, type NodeIKernelProfileLikeService, type NodeIKernelProfileService, type NodeIKernelRichMediaService, type NodeIKernelSessionListener, type NodeIKernelTicketService, type NodeIQQNTStartupSessionWrapper, type NodeIQQNTWrapperEngine, type NodeIQQNTWrapperSession, type NodeQQNTWrapperUtil, type PathOptions, PathWrapper, type Peer, type PlatformType, ProfileApi, ProfileLikeApi, type QQVersionContext, type QQVersionInfo, type QrCodeData, QrLoginSession, type RDeliveryConfig, type RawElement, type RawMessage, RichMediaApi, type SelfInfo, type SendMessageElement, type SessionConfigOptions, type ShutUpGroupMember, type StartNapukettoOptions, type StrangerInfo, TicketApi, type TipAioOpGrayTipElement, type TipGroupElement, TipGroupElementType, type UserDetailInfoByUin, type VendorType, WebApi, WebHonorType, type WrapperContext, type WrapperNodeApi, type WrapperSessionInitConfig, 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.d.cts.map