@napuketto/adapter 0.8.3 → 0.9.0

package/dist/milky/index.mjs

@@ -1,7 +1,7 @@
-import { o as ActionRegistry, r as BaseProtocolAdapter } from "../core-DyXyDUcU.mjs";
+import { _ as BaseProtocolAdapter, b as ActionRegistry, c as nodeAt, d as toHex, f as varintAt, i as extractSysMsgEnvelope, l as recognizeSysMsg, n as decodeProtoTree, p as varintOf, s as narrowSysMsgBlobs, u as textOf } from "../core-DW5i42XH.mjs";
 import { n as firstUntranslatedGrayTip, t as collectGrayTipUids } from "../gray-tip-LwBee5mo.mjs";
 import { n as MS_TO_SEC$2, r as resolveUin, t as narrowBuddyReqs } from "../buddy-req-Q7Q4bVuz.mjs";
-import { n as subscribeRawMessages } from "../raw-message-D_ecJy4C.mjs";
+import { n as subscribeRawMessages, t as forEachRawMessage } from "../raw-message-D_ecJy4C.mjs";
 import { ChatType, GrayTipSubType, GroupApi, GroupNotifyMsgStatus, GroupNotifyMsgType, NTGroupRequestOperateTypes, TicketApi, TipGroupElementType, isKernelError, kernelError, toCanonicalElements } from "@napuketto/kernel";
 import { mkdir, rename, writeFile } from "node:fs/promises";
 import { detectFileType, downloadUrl, inferExtension } from "@napuketto/media";
@@ -2250,6 +2250,103 @@ function createMilkyActionRegistry(opts) {
 	return registry;
 }
 //#endregion
+//#region src/milky/helper/essence.ts
+/** 单个候选值 → 群号字符串（非空字符串 / 正整数）。 */
+function toGroupCode(value) {
+	if (typeof value === "string" && value !== "") return value;
+	if (typeof value === "number" && Number.isInteger(value) && value > 0) return String(value);
+	return null;
+}
+/** onGroupEssenceListChange 参数 → 群号（录制实证首项字符串；防御收窄）。 */
+function narrowEssenceGroupArg(arg) {
+	const first = Array.isArray(arg) ? arg[0] : arg;
+	if (first !== null && typeof first === "object") {
+		const rec = first;
+		for (const key of [
+			"groupCode",
+			"group_code",
+			"groupId",
+			"peerUid"
+		]) {
+			const code = toGroupCode(rec[key]);
+			if (code !== null) return code;
+		}
+		return null;
+	}
+	return toGroupCode(first);
+}
+/** 精华列表项 → 缓存操作者（add_digest_uin 缺失/空 → 空串 = 未知）。 */
+function essenceOperator(item) {
+	return typeof item.add_digest_uin === "string" && item.add_digest_uin !== "" ? item.add_digest_uin : "";
+}
+/** 列表 → 缓存 map（seq → 操作者）。 */
+function buildEssenceCache(items) {
+	const cache = /* @__PURE__ */ new Map();
+	for (const item of items) if (typeof item.msg_seq === "number") cache.set(item.msg_seq, essenceOperator(item));
+	return cache;
+}
+/** 新增项收集（cache 新键即新增）。 */
+function collectAdded(prev, cache) {
+	const added = [];
+	for (const [seq, operator] of cache) if (!prev.has(seq)) added.push({
+		messageSeq: seq,
+		operatorUin: operator === "" ? null : operator
+	});
+	return added;
+}
+/** 移除项收集（cache 无即移除；移除者不可知）。 */
+function collectRemoved(prev, cache) {
+	const removed = [];
+	for (const seq of prev.keys()) if (!cache.has(seq)) removed.push(seq);
+	return removed;
+}
+/**
+* 精华列表 diff：prev 缺省（基线未建立）时只建缓存不产出事件——
+* 首个变更事件只做基线，避免全量首推被误报为「逐条加精」。
+*/
+function diffEssenceList(prev, items) {
+	const cache = buildEssenceCache(items);
+	if (prev === void 0) return {
+		cache,
+		added: [],
+		removed: []
+	};
+	return {
+		cache,
+		added: collectAdded(prev, cache),
+		removed: collectRemoved(prev, cache)
+	};
+}
+//#endregion
+//#region src/milky/helper/file-upload.ts
+/**
+* friend_file_upload 翻译（Milky 批次三，2026-11-01 录制定型）
+*
+* 源：Msg/onRecvOfflineFileMsg 与 Msg/onFileMsgCome（同载荷 RawMessage 数组，
+* 双回调按 msgId 在适配器去重）；fileElement{fileName, fileSize 字符串,
+* file10MMd5, fileUuid, ...}，sendType 0=收到（sender=对端）/ 2=自己发出。
+*
+* 已知差异（milky.md §0.8.6）：官方 file_hash 语义为 TriSHA1，接收侧
+* fileSha/fileSha3 实测为空——取 file10MMd5（md5）充值，上传侧校准后回填。
+*/
+/** 单条 C2C 文件消息 → 事件载荷（非 C2C / 无 fileElement / 无 fileUuid → null）。 */
+function toFriendFileUploadData(msg, selfUin, uidToUin) {
+	if (msg.chatType !== ChatType.C2C) return null;
+	const file = msg.elements.find((el) => el.fileElement !== void 0)?.fileElement;
+	if (file === void 0 || typeof file.fileUuid !== "string" || file.fileUuid === "") return null;
+	const isSelf = msg.sendType === 2 || String(msg.senderUin) === selfUin;
+	const userUin = msg.senderUin !== "" ? Number(msg.senderUin) : resolveUin(msg.senderUid, uidToUin);
+	const size = Number(file.fileSize ?? 0);
+	return {
+		user_id: Number.isFinite(userUin) ? userUin : 0,
+		file_id: file.fileUuid,
+		file_name: file.fileName ?? "",
+		file_size: Number.isFinite(size) ? size : 0,
+		file_hash: file.file10MMd5 ?? file.fileSha ?? "",
+		is_self: isSelf
+	};
+}
+//#endregion
 //#region src/milky/helper/notice.ts
 /** 毫秒 → 秒（Unix 时间戳）。 */
 const MS_TO_SEC = 1e3;
@@ -2396,6 +2493,94 @@ function toMilkyNoticeEvent(msg, ctx) {
 	return null;
 }
 //#endregion
+//#region src/milky/helper/peer-pin.ts
+/**
+* peer_pin_change 翻译（Milky 批次三，RecentContact/onRecentContactListChangedVer2）
+*
+* 回调随消息活动高频快照（含 topFlag 的全量条目 + chatType=7 影子条目），
+* 不能见条目就广播——按「同会话 topFlag 前后值翻转」检测（PinWatch）。
+* 启动期以 getPinnedContacts 播种基线（重启后首个取消置顶也能观测到）。
+*
+* 证据：2026-11-01 set_peer_pin 自触发翻转实验——changedList 条目
+* {chatType, peerUin, topFlag(1/0), topFlagTime(秒级 unix 字符串)}，与操作
+* 一一对应（milky.md §0.8.6）。
+*/
+/** uin 形判别（peer_id 必须是数字串）。 */
+const NUMERIC_RE$2 = /^\d+$/;
+/** 置顶翻转检测（每适配器实例一份，键 = chatType:peerUin——群号与 uin 数值空间可重叠）。 */
+var PinWatch = class {
+	states = /* @__PURE__ */ new Map();
+	/** 启动基线：置顶会话播种（只记状态，不产生事件）。 */
+	seed(pins) {
+		for (const pin of pins) {
+			if (pin.peerUin === void 0 || pin.peerUin === "") continue;
+			const chatType = pin.scene === "group" ? ChatType.GROUP : ChatType.C2C;
+			this.states.set(`${chatType}:${pin.peerUin}`, 1);
+		}
+	}
+	/**
+	* 观测一个变更条目：topFlag 相对上次观测翻转 → true（应广播）；
+	* 首见（基线未建立）或未变 → false。
+	*/
+	observe(chatType, peerUin, topFlag) {
+		const key = `${chatType}:${peerUin}`;
+		const prev = this.states.get(key);
+		this.states.set(key, topFlag);
+		return prev !== void 0 && prev !== topFlag;
+	}
+};
+/** 场景映射（changedList 条目 chatType → Milky message_scene；影子/其他类型丢弃）。 */
+function pinScene(chatType) {
+	if (chatType === ChatType.GROUP) return "group";
+	if (chatType === ChatType.C2C) return "friend";
+	return null;
+}
+/** 变更条目 → 事件载荷（null = 条目不含置顶字段/场景不支持，跳过不广播）。 */
+function toPeerPinChangeData(entry) {
+	const scene = pinScene(entry.chatType);
+	if (scene === null || entry.topFlag === void 0) return null;
+	const peerUin = typeof entry.peerUin === "string" && entry.peerUin !== "" ? entry.peerUin : scene === "group" ? entry.peerUid : "";
+	if (peerUin === "" || !NUMERIC_RE$2.test(peerUin)) return null;
+	return {
+		data: {
+			message_scene: scene,
+			peer_id: Number(peerUin),
+			is_pinned: entry.topFlag === 1
+		},
+		topFlagTime: typeof entry.topFlagTime === "string" ? entry.topFlagTime : void 0,
+		peerUin
+	};
+}
+//#endregion
+//#region src/milky/helper/recent-keys.ts
+/**
+* 带过期去重键缓存（Milky 批次三）
+*
+* 两个场景共用：friend_file_upload 双回调（onRecvOfflineFileMsg / onFileMsgCome
+* 同载荷，按 msgId 去重）与 group_essence_message_change 双路径（732:1 快路径
+* vs 列表 diff，按 群:seq:方向 去重）。claim 语义 = 未登记过（或已过期）则登记
+* 并返回 true——调用方据此决定是否广播。
+*/
+var RecentKeyCache = class {
+	entries = /* @__PURE__ */ new Map();
+	ttlMs;
+	constructor(ttlMs) {
+		this.ttlMs = ttlMs;
+	}
+	/** 未命中则登记并返回 true（应广播）；命中（窗口内重复）返回 false。 */
+	claim(key, now = Date.now()) {
+		this.prune(now);
+		const expiry = this.entries.get(key);
+		if (expiry !== void 0 && expiry > now) return false;
+		this.entries.set(key, now + this.ttlMs);
+		return true;
+	}
+	/** 惰性清理过期键（每次 claim 顺带执行，量级小无需定时器）。 */
+	prune(now) {
+		for (const [key, expiry] of this.entries) if (expiry <= now) this.entries.delete(key);
+	}
+};
+//#endregion
 //#region src/milky/helper/seq-index.ts
 /** 单方向最大条目数（测试用例引用容量语义）。 */
 const MAX_ENTRIES = 4096;
@@ -2474,6 +2659,102 @@ var MessageSeqIndex = class {
 	}
 };
 //#endregion
+//#region src/milky/helper/sysmsg.ts
+/**
+* Milky sysmsg 识别表（批次三，2026-11-01；识别机制共享自 core/sysmsg.ts）
+*
+* 键 = 原生分发键 "msgType:subType"，规则产出事件 data 体（信封 time/self_id/
+* event_type 由适配器统一包装）。路径依据 = 三轮录制 wire bytes 全量解码
+* （milky.md §0.8.6 识别表；临时解码脚本 .napuketto/decode-sysmsg*.mjs 不入库）。
+*
+*  - 732:16 群消息表情回应：f1.f1=群号；f3.f2.f44.f1.f1={f1 变动值, f2.f1=msgSeq,
+*    f3={f1 faceId 字符串, f5: 1=添加/2=撤销, f3:1 仅添加时存在}}。
+*    operator 不在 push（f4=bot 自身 uid 占位）——user_id 省略。
+*  - 732:1 群精华设置：f1.f1=群号, f1.f8.f8.f1=msgSeq；取消精华无独立 sysmsg
+*    （remove 走 onGroupEssenceListChange 列表 diff，helper/essence.ts）。
+*  - 528:349/381/382 多端设备同步族：不广播。
+*/
+/** 数字串判别（faceId 实证为数字字符串）。 */
+const NUMERIC_RE$1 = /^\d+$/;
+/** 732:16 → group_message_reaction。 */
+const REACTION_RULE = {
+	kind: "group_message_reaction",
+	extract: (tree) => reactionData(tree)
+};
+/** 路径提取：f1.f1=群号 + f3.f2.f44.f1.f1=回应明细（任一缺失 → null）。 */
+function reactionData(tree) {
+	const groupId = varintAt(tree, [1, 1]);
+	const detail = nodeAt(tree, [
+		3,
+		2,
+		44,
+		1,
+		1
+	]);
+	if (groupId === null || detail === null) return null;
+	return reactionDetail(groupId, detail);
+}
+/** 明细提取：f2.f1=msgSeq + f3=face 块（任一缺失 → null）。 */
+function reactionDetail(groupId, detail) {
+	const msgSeq = varintAt(detail, [2, 1]);
+	const face = nodeAt(detail, [3]);
+	if (msgSeq === null || face === null) return null;
+	return reactionFace(groupId, msgSeq, face);
+}
+/** face 块提取：faceId 实证为数字字符串（"76"/"124"…）；f5 双判据（f3 仅添加时存在）。 */
+function reactionFace(groupId, msgSeq, face) {
+	const isAdd = reactionIsAdd(face);
+	const faceId = reactionFaceId(face);
+	if (isAdd === null || faceId === null) return null;
+	return {
+		group_id: groupId,
+		message_seq: msgSeq,
+		face_id: faceId,
+		reaction_type: "face",
+		is_add: isAdd
+	};
+}
+/** faceId 字段（数字字符串 → number；缺失/非数字 → null）。 */
+function reactionFaceId(face) {
+	const faceIdText = textOf(face, 1);
+	return faceIdText !== null && NUMERIC_RE$1.test(faceIdText) ? Number(faceIdText) : null;
+}
+/** is_add 判定：f5=1 添加 / 2 撤销（f3=1 仅添加时存在，双判据）；非法 → null。 */
+function reactionIsAdd(face) {
+	const op = varintOf(face, 5);
+	if (op === 1) return true;
+	return op === 2 ? false : null;
+}
+/** (msgType, subType) → 规则表（键 = 原生分发键）。 */
+const KIND_TABLE = /* @__PURE__ */ new Map([["732:16", REACTION_RULE], ["732:1", {
+	kind: "group_essence_message_change",
+	extract: (tree) => {
+		const groupId = varintAt(tree, [1, 1]);
+		const msgSeq = varintAt(tree, [
+			1,
+			8,
+			8,
+			1
+		]);
+		if (groupId === null || msgSeq === null) return null;
+		return {
+			group_id: groupId,
+			message_seq: msgSeq,
+			is_set: true
+		};
+	}
+}]]);
+/** 已观测但未命名的键（多端设备同步族等，不广播只走校准日志）。 */
+const OBSERVED_UNNAMED = /* @__PURE__ */ new Set([
+	"528:382",
+	"528:349",
+	"528:381"
+]);
+/** (msgType, subType) → 识别结果（绑定 Milky 表；table 参数供单测注入）。 */
+function recognizeMilkySysMsg(msgType, subType, table = KIND_TABLE) {
+	return recognizeSysMsg(msgType, subType, table, OBSERVED_UNNAMED);
+}
+//#endregion
 //#region src/milky/transport.ts
 /** /event 路径（规范固定）。 */
 const EVENT_PATH = "/event";
@@ -2648,6 +2929,18 @@ var NapukettoMilkyAdapter = class extends BaseProtocolAdapter {
 	msgChannel;
 	groupChannel;
 	buddyChannel;
+	recentContactChannel;
+	loginChannel;
+	/** peer_pin 翻转检测（批次三；启动期 getPinnedContacts 播种）。 */
+	pinWatch = new PinWatch();
+	/** friend_file_upload 双回调去重（同载荷，按 msgId）。 */
+	fileKeys = new RecentKeyCache(6e5);
+	/** essence 双路径去重（732:1 快路径 vs 列表 diff，键 群:seq:方向）。 */
+	essenceKeys = new RecentKeyCache(3e5);
+	/** 精华列表缓存（群号 → seq → 操作者 uin，空串 = 未知）。 */
+	essenceCaches = /* @__PURE__ */ new Map();
+	/** 精华列表拉取串行链（并发回写乱序会把新列表覆盖成旧列表）。 */
+	essenceChain = Promise.resolve();
 	calibLogger;
 	api;
 	seqIndex = new MessageSeqIndex();
@@ -2668,6 +2961,8 @@ var NapukettoMilkyAdapter = class extends BaseProtocolAdapter {
 		this.msgChannel = opts.msgChannel;
 		this.groupChannel = opts.groupChannel;
 		this.buddyChannel = opts.buddyChannel;
+		this.recentContactChannel = opts.recentContactChannel;
+		this.loginChannel = opts.loginChannel;
 		this.calibLogger = opts.logger;
 		this.api = new MilkyApi(opts, this.seqIndex);
 		this.registry = createMilkyActionRegistry({ api: this.api });
@@ -2687,6 +2982,7 @@ var NapukettoMilkyAdapter = class extends BaseProtocolAdapter {
 				...this.calibLogger !== void 0 ? { logger: this.calibLogger } : {}
 			});
 			this.stopTransports = set.close;
+			await Promise.all(set.adapters.map((a) => a.open()));
 		}
 		this.subscribe();
 		this.calibLogger?.info({
@@ -2714,6 +3010,19 @@ var NapukettoMilkyAdapter = class extends BaseProtocolAdapter {
 		this.unsubscribes.push(subscribeRawMessages(this.msgChannel, (msg) => {
 			this.handleIncoming(msg);
 		}));
+		this.unsubscribes.push(this.msgChannel.on("Msg/onRecvSysMsg", (arg) => {
+			this.handleSysMsg(arg);
+		}));
+		this.unsubscribes.push(this.msgChannel.on("Msg/onRecvOfflineFileMsg", (msgs) => {
+			this.handleFileMessages(msgs);
+		}), this.msgChannel.on("Msg/onFileMsgCome", (msgs) => {
+			this.handleFileMessages(msgs);
+		}));
+		this.subscribeGroupAndBuddy();
+		this.subscribeBatch3();
+	}
+	/** 群通知 + 好友请求通道（P1 事件源；通道缺省不订阅）。 */
+	subscribeGroupAndBuddy() {
 		if (this.groupChannel !== void 0) {
 			const groupChannel = this.groupChannel;
 			this.unsubscribes.push(groupChannel.on("Group/onGroupNotifiesUpdated", (doubt, notifies) => {
@@ -2727,6 +3036,30 @@ var NapukettoMilkyAdapter = class extends BaseProtocolAdapter {
 			}));
 		}
 	}
+	/** 批次三通道：精华列表变更 / 置顶翻转（含播种基线）/ bot_offline。 */
+	subscribeBatch3() {
+		if (this.groupChannel !== void 0) {
+			const groupChannel = this.groupChannel;
+			this.unsubscribes.push(groupChannel.on("Group/onGroupEssenceListChange", (arg) => {
+				this.handleEssenceChange(arg);
+			}));
+		}
+		if (this.recentContactChannel !== void 0) {
+			const recentContactChannel = this.recentContactChannel;
+			this.unsubscribes.push(recentContactChannel.on("RecentContact/onRecentContactListChangedVer2", (lists) => {
+				this.handlePinChanges(lists);
+			}));
+			this.seedPinWatch();
+		}
+		if (this.loginChannel !== void 0) {
+			const loginChannel = this.loginChannel;
+			this.unsubscribes.push(loginChannel.on("Login/onLoginDisConnected", (...args) => {
+				this.broadcastBotOffline("disconnected", args);
+			}), loginChannel.on("Login/onLogoutSucceed", (...args) => {
+				this.broadcastBotOffline("logout", args);
+			}));
+		}
+	}
 	/** 退订（幂等）。 */
 	unsubscribeAll() {
 		for (const off of this.unsubscribes) off();
@@ -2834,6 +3167,200 @@ var NapukettoMilkyAdapter = class extends BaseProtocolAdapter {
 			msgId: msg.msgId
 		});
 	}
+	/**
+	* sysmsg 总闸：解码 → 识别 → 表命中才广播（732:16 表情回应 / 732:1 精华
+	* 设置）；未识别 debug 校准日志。规则提取失败不广播半成品事件。
+	*/
+	handleSysMsg(arg) {
+		const blobs = narrowSysMsgBlobs(arg);
+		if (blobs === null) {
+			this.calibLogger?.warn({ raw: truncate(JSON.stringify(arg)) }, "milky: onRecvSysMsg 未知参数形状");
+			return;
+		}
+		for (const blob of blobs) this.handleSysMsgBlob(blob);
+	}
+	/** 单条字节块：解码 → 识别 → 提取；任一步失败走校准日志返回 null。 */
+	handleSysMsgBlob(blob) {
+		const hit = this.sysMsgHit(blob);
+		if (hit === null) return;
+		if (!this.claimEssenceFastPath(hit)) return;
+		this.broadcastEvent({
+			time: hit.env.time ?? Math.floor(Date.now() / 1e3),
+			self_id: Number(this.api.self.uin),
+			event_type: hit.rule.kind,
+			data: hit.data
+		});
+	}
+	/** 解码 + 识别 + 提取（每步失败各自打 debug 校准日志）。 */
+	sysMsgHit(blob) {
+		const tree = decodeProtoTree(blob);
+		if (tree === null) {
+			this.calibLogger?.debug({ raw: toHex(blob).slice(0, 1024) }, "milky: onRecvSysMsg protobuf 解码失败");
+			return null;
+		}
+		const env = extractSysMsgEnvelope(tree);
+		const rule = this.sysMsgRule(env, tree, blob);
+		if (rule === null) return null;
+		return {
+			env,
+			rule: rule.rule,
+			data: rule.data
+		};
+	}
+	/** 识别 + 规则提取（未识别/提取失败 → 校准日志 + null）。 */
+	sysMsgRule(env, tree, blob) {
+		const rec = recognizeMilkySysMsg(env.msgType, env.subType);
+		if (rec.kind !== "notice") {
+			this.calibLogger?.debug({
+				verdict: rec.kind,
+				msgType: env.msgType,
+				subType: env.subType,
+				strings: env.strings,
+				raw: toHex(blob).slice(0, 1024)
+			}, "milky: onRecvSysMsg 校准数据（未识别，不广播）");
+			return null;
+		}
+		const ctx = {
+			selfUin: Number(this.api.self.uin),
+			time: env.time ?? Math.floor(Date.now() / 1e3)
+		};
+		const data = rec.rule.extract(tree, env, () => 0, ctx);
+		if (data === null) {
+			this.calibLogger?.debug({
+				kind: rec.rule.kind,
+				msgType: env.msgType,
+				subType: env.subType
+			}, "milky: sysmsg 规则提取失败（不广播）");
+			return null;
+		}
+		return {
+			rule: rec.rule,
+			data
+		};
+	}
+	/** 精华快路径去重守卫：非精华事件恒 true；精华事件 claim 失败（已由列表 diff 抢发）→ false。 */
+	claimEssenceFastPath(hit) {
+		if (hit.rule.kind !== "group_essence_message_change") return true;
+		const essence = hit.data;
+		return this.essenceKeys.claim(`${essence.group_id}:${essence.message_seq}:1`);
+	}
+	/** 私聊文件消息 → friend_file_upload（双回调同载荷，按 msgId 去重）。 */
+	handleFileMessages(msgs) {
+		forEachRawMessage(msgs, (msg) => {
+			const data = toFriendFileUploadData(msg, this.api.self.uin, /* @__PURE__ */ new Map());
+			if (data === null) return;
+			if (data.user_id === 0) this.calibLogger?.debug({
+				msgId: msg.msgId,
+				senderUid: msg.senderUid
+			}, "milky: friend_file_upload senderUin 缺失（user_id=0）");
+			if (!this.fileKeys.claim(`file:${msg.msgId}`)) return;
+			this.broadcastEvent({
+				time: secondsOf(msg.msgTime),
+				self_id: Number(this.api.self.uin),
+				event_type: "friend_file_upload",
+				data
+			});
+		});
+	}
+	/** 精华列表变更：拉全量列表 diff（remove 路径 + operator 回填；串行防乱序）。 */
+	handleEssenceChange(arg) {
+		const groupCode = narrowEssenceGroupArg(arg);
+		if (groupCode === null) {
+			this.calibLogger?.warn({ raw: truncate(JSON.stringify(arg)) }, "milky: onGroupEssenceListChange 未知参数形状");
+			return;
+		}
+		this.essenceChain = this.essenceChain.then(() => this.syncEssenceList(groupCode), () => void 0);
+	}
+	/** 单群精华列表同步：拉取 → diff → 广播 → 更新缓存（基线未建立只建基线）。 */
+	async syncEssenceList(groupCode) {
+		let items;
+		try {
+			items = await this.api.webApi.getEssenceMsgList(groupCode);
+		} catch (e) {
+			this.calibLogger?.warn({
+				group: groupCode,
+				err: String(e)
+			}, "milky: 精华列表拉取失败（diff 跳过）");
+			return;
+		}
+		const prev = this.essenceCaches.get(groupCode);
+		const { cache, added, removed } = diffEssenceList(prev, items);
+		this.essenceCaches.set(groupCode, cache);
+		if (prev === void 0) return;
+		const selfId = Number(this.api.self.uin);
+		const now = Math.floor(Date.now() / 1e3);
+		this.broadcastEssenceAdded(groupCode, added, now, selfId);
+		this.broadcastEssenceRemoved(groupCode, removed, now, selfId);
+	}
+	/** diff 新增项广播（is_set=true；operator = add_digest_uin；快路径已发则跳过）。 */
+	broadcastEssenceAdded(groupCode, added, now, selfId) {
+		for (const item of added) {
+			if (!this.essenceKeys.claim(`${groupCode}:${item.messageSeq}:1`)) continue;
+			const data = essenceAddedData(groupCode, item);
+			this.broadcastEvent({
+				time: now,
+				self_id: selfId,
+				event_type: "group_essence_message_change",
+				data
+			});
+		}
+	}
+	/** diff 移除项广播（is_set=false；取消无 sysmsg，operator 不可得省略）。 */
+	broadcastEssenceRemoved(groupCode, removed, now, selfId) {
+		for (const seq of removed) {
+			if (!this.essenceKeys.claim(`${groupCode}:${seq}:0`)) continue;
+			this.broadcastEvent({
+				time: now,
+				self_id: selfId,
+				event_type: "group_essence_message_change",
+				data: {
+					group_id: Number(groupCode),
+					message_seq: seq,
+					is_set: false
+				}
+			});
+		}
+	}
+	/** 会话列表变更 → peer_pin_change（topFlag 翻转检测，条目自带 chatType 判场景）。 */
+	handlePinChanges(lists) {
+		const arr = Array.isArray(lists) ? lists : [lists];
+		for (const list of arr) this.handlePinChangeList(list);
+	}
+	/** 单个变更列表：changedList 逐条目翻转检测 + 广播。 */
+	handlePinChangeList(list) {
+		for (const entry of changedListOf(list)) this.handlePinEntry(entry);
+	}
+	/** 单个变更条目：翻译 + 翻转检测 + 广播（首见/未变/不支持场景静默跳过）。 */
+	handlePinEntry(entry) {
+		const payload = pinPayloadOf(entry);
+		if (payload === null) return;
+		if (!this.pinWatch.observe(payload.chatType, payload.peerUin, payload.topFlag)) return;
+		this.broadcastEvent({
+			time: secondsOf(payload.topFlagTime),
+			self_id: Number(this.api.self.uin),
+			event_type: "peer_pin_change",
+			data: payload.data
+		});
+	}
+	/** 启动基线：置顶会话播种（重启后首个取消置顶也能观测到翻转；失败静默）。 */
+	seedPinWatch() {
+		this.api.recentContactApi.getPinnedContacts().then((pins) => {
+			this.pinWatch.seed(pins);
+		}).catch(() => void 0);
+	}
+	/** bot_offline：Login 桥回调（载荷零样本，reason 固定值 + raw 校准日志待野捕）。 */
+	broadcastBotOffline(reason, args) {
+		this.calibLogger?.debug({
+			reason,
+			raw: truncate(JSON.stringify(args))
+		}, "milky: bot_offline（reason 为固定值，回调载荷待野捕校准）");
+		this.broadcastEvent({
+			time: Math.floor(Date.now() / 1e3),
+			self_id: Number(this.api.self.uin),
+			event_type: "bot_offline",
+			data: { reason }
+		});
+	}
 	/** uid 批量 → uin（空集/失败返回 undefined 语义：调用方用空 Map）。 */
 	resolveUidToUin(uids) {
 		const unique = [...new Set(uids.filter((uid) => uid !== ""))];
@@ -2853,6 +3380,52 @@ function findRevokeElement(msg) {
 function truncate(raw) {
 	return raw === void 0 ? "" : raw.slice(0, 2e3);
 }
+/** 数字串判别（uin / 秒级时间戳）。 */
+const NUMERIC_RE = /^\d+$/;
+/** diff 新增项 → 事件载荷（operator = add_digest_uin，非数字串省略）。 */
+function essenceAddedData(groupCode, item) {
+	const base = {
+		group_id: Number(groupCode),
+		message_seq: item.messageSeq
+	};
+	if (item.operatorUin !== null && NUMERIC_RE.test(item.operatorUin)) return {
+		...base,
+		operator_id: Number(item.operatorUin),
+		is_set: true
+	};
+	return {
+		...base,
+		is_set: true
+	};
+}
+/** 变更列表 → changedList 条目数组（形状不符 → 空）。 */
+function changedListOf(list) {
+	if (list === null || typeof list !== "object") return [];
+	const changed = list.changedList;
+	return Array.isArray(changed) ? changed : [];
+}
+/** 变更条目 → 翻转检测输入（null = 条目不支持/缺置顶字段）。 */
+function pinPayloadOf(entry) {
+	if (entry === null || typeof entry !== "object") return null;
+	return pinPayloadFrom(entry);
+}
+function pinPayloadFrom(contact) {
+	const topFlag = contact.topFlag;
+	const payload = toPeerPinChangeData(contact);
+	if (topFlag === void 0 || payload === null) return null;
+	return {
+		chatType: contact.chatType,
+		peerUin: payload.peerUin,
+		topFlag,
+		topFlagTime: payload.topFlagTime,
+		data: payload.data
+	};
+}
+/** 秒级时间戳归一（空/非法 → 当前时间；topFlagTime/msgTime 均为秒级字符串）。 */
+function secondsOf(raw) {
+	if (raw !== void 0 && NUMERIC_RE.test(raw)) return Number(raw);
+	return Math.floor(Date.now() / 1e3);
+}
 //#endregion
 //#region src/milky/config.ts
 /**