@napuketto/adapter 0.4.2 → 0.6.0

package/dist/milky/index.mjs

@@ -0,0 +1,2513 @@
+import { o as ActionRegistry, r as BaseProtocolAdapter } from "../core-DyXyDUcU.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 { 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";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { HttpClient, HttpServer, createSseResponse } from "@napuketto/network";
+import { WebSocket } from "ws";
+import { fileURLToPath } from "node:url";
+//#region src/milky/api.ts
+var MilkyApi = class {
+	msgApi;
+	groupApi;
+	friendApi;
+	profileApi;
+	profileLikeApi;
+	ticketApi;
+	webApi;
+	groupNotifyApi;
+	richMediaApi;
+	self;
+	groupCache;
+	qqVersion;
+	implVersion;
+	mediaDir;
+	/** message_seq ↔ msgId 双向映射（接收链路 record，动作侧反查）。 */
+	seqIndex;
+	constructor(opts, seqIndex) {
+		this.msgApi = opts.msgApi;
+		this.groupApi = opts.groupApi;
+		this.friendApi = opts.friendApi;
+		this.profileApi = opts.profileApi;
+		this.profileLikeApi = opts.profileLikeApi;
+		this.ticketApi = opts.ticketApi;
+		this.webApi = opts.webApi;
+		this.groupNotifyApi = opts.groupNotifyApi;
+		this.richMediaApi = opts.richMediaApi;
+		this.self = opts.self;
+		this.groupCache = opts.groupCache;
+		this.qqVersion = opts.qqVersion;
+		this.implVersion = opts.implVersion;
+		this.mediaDir = opts.mediaDir;
+		this.seqIndex = seqIndex;
+	}
+	/** uin → uid（私聊目标 / at 段发送转换 / 群管动作的 uid 入参）。 */
+	uinToUid(uins) {
+		return this.groupApi.uinToUid(uins);
+	}
+	/** uid → uin（事件路径 mention 转换）。 */
+	uidToUin(uids) {
+		return this.groupApi.uidToUin(uids);
+	}
+	/**
+	* uin（数字）→ uid（群管动作入参转换）；转换失败抛 INVALID_PARAM
+	* （Milky 入参 user_id 都是 uin，kernel 群管 API 要 uid）。
+	*/
+	async resolveUidFromUin(uin) {
+		const uinStr = String(uin);
+		try {
+			const uid = (await this.uinToUid([uinStr])).get(uinStr);
+			if (uid !== void 0 && uid !== "") return uid;
+		} catch {}
+		throw kernelError(`用户 ${uinStr} 不存在或 uin→uid 转换失败`, "INVALID_PARAM");
+	}
+	/**
+	* message_scene + 数字 ID → NT Peer。
+	* group = 群号直作 peerUid；friend/temp = uin → uid（失败退 uin 原样，交 QQ 端判断）。
+	*/
+	async resolvePeer(scene, id) {
+		if (scene === "group") return {
+			chatType: ChatType.GROUP,
+			peerUid: String(id)
+		};
+		const uin = String(id);
+		let uid;
+		try {
+			uid = (await this.uinToUid([uin])).get(uin);
+		} catch {}
+		return {
+			chatType: scene === "friend" ? ChatType.C2C : ChatType.C2C_TEMP,
+			peerUid: uid ?? uin
+		};
+	}
+	/**
+	* seq → msgId（索引优先，未登记扫描近段历史兜底）。
+	* 两层都未命中返回 undefined（调用方抛 NOT_FOUND）。
+	*/
+	async resolveMsgIdBySeq(peer, seq, chatType) {
+		const indexed = this.seqIndex.resolveMsgId(chatType, peer.peerUid, seq);
+		if (indexed !== void 0) return indexed;
+		const hit = (await this.msgApi.fetchMessages(peer, { count: 60 }).catch(() => [])).find((m) => Number(m.msgSeq) === seq);
+		if (hit === void 0) return;
+		this.seqIndex.record(hit);
+		return hit.msgId;
+	}
+	/** 发送结果回查：msgId → {message_seq, time}（sendMessage 只回 msgId）。 */
+	async resolveSentOutput(peer, msgId) {
+		const [sent] = await this.msgApi.fetchMsgsByMsgId(peer, [msgId]);
+		if (sent === void 0) throw kernelError("发送结果回查失败（msgId 未命中）", "UNKNOWN");
+		this.seqIndex.record(sent);
+		return {
+			message_seq: Number(sent.msgSeq),
+			time: Math.floor(Number(sent.msgTime) / 1e3)
+		};
+	}
+};
+/** 通知查找默认搜索数量（单屏全量，OB11 DEFAULT_COUNT 同值）。 */
+const NOTIFY_SEARCH_COUNT$1 = 100;
+/**
+* 按通知 seq 查找群通知（先非可疑后可疑，OB11 set_group_add_request 同路径）。
+* 未找到抛 NOT_FOUND（应答动作的 seq 无效或已过期）。
+* 模块级函数（非类成员）：应答动作的公共入口，OB11 同路径。
+*/
+async function findGroupNotify(api, seq) {
+	const hit = (await api.groupNotifyApi.getSingleScreenNotifies(false, NOTIFY_SEARCH_COUNT$1)).find((item) => item.seq === seq);
+	if (hit !== void 0) return hit;
+	const doubtHit = (await api.groupNotifyApi.getSingleScreenNotifies(true, NOTIFY_SEARCH_COUNT$1)).find((item) => item.seq === seq);
+	if (doubtHit !== void 0) return doubtHit;
+	throw kernelError(`未找到通知 ${seq}（无效或已过期）`, "NOT_FOUND");
+}
+/** 按发起者 uid 查找好友申请（getBuddyReqList 匹配 friendUid）；未找到抛 NOT_FOUND。 */
+async function findBuddyReq(api, initiatorUid) {
+	const hit = (await api.friendApi.getBuddyReqList()).find((req) => req.friendUid === initiatorUid);
+	if (hit === void 0) throw kernelError(`未找到来自 ${initiatorUid} 的好友申请`, "NOT_FOUND");
+	return hit;
+}
+//#endregion
+//#region src/milky/helper/entities.ts
+/** GroupDetailInfo / Group → GroupEntity（detail 缺失时全兜底）。 */
+function toGroupEntity(detail, groupCode) {
+	return {
+		group_id: Number(groupCode),
+		group_name: detail?.groupName ?? "",
+		member_count: detail?.memberNum ?? 0,
+		max_member_count: detail?.maxMemberNum ?? 0,
+		remark: detail?.remarkName ?? "",
+		created_time: detail?.groupCreateTime ?? 0,
+		description: "",
+		question: "",
+		announcement: ""
+	};
+}
+/** 群列表项（GroupCache Group）→ GroupEntity。 */
+function groupListToEntity(group) {
+	return {
+		group_id: Number(group.groupCode),
+		group_name: group.groupName,
+		member_count: group.memberCount,
+		max_member_count: group.maxMember,
+		remark: "",
+		created_time: 0,
+		description: "",
+		question: "",
+		announcement: ""
+	};
+}
+/** GroupMember → GroupMemberEntity（member 缺失时按 uin 兜底最小实体）。 */
+function toGroupMemberEntity(member, groupCode, uin) {
+	const shutUpSeconds = member?.shutUpTime ?? 0;
+	return {
+		user_id: Number(member?.uin !== void 0 && member.uin !== "" ? member.uin : uin),
+		nickname: member?.nick ?? "",
+		sex: "unknown",
+		group_id: Number(groupCode),
+		card: member?.cardName ?? "",
+		title: member?.memberSpecialTitle ?? "",
+		level: 0,
+		role: GroupApi.roleToString(member?.role ?? 2),
+		join_time: Number(member?.joinTime) || 0,
+		last_sent_time: Number(member?.lastSpeakTime) || 0,
+		shut_up_end_time: shutUpSeconds > 0 ? Math.floor(Date.now() / 1e3) + shutUpSeconds : null
+	};
+}
+/** Friend → FriendEntity（kernel 无 qid/分类挂载，按最小实体兜底）。 */
+function toFriendEntity(friend, uin, nick) {
+	return {
+		user_id: Number(friend?.uin !== void 0 && friend.uin !== "" ? friend.uin : uin),
+		nickname: friend?.nickname ?? nick,
+		sex: "unknown",
+		qid: "",
+		remark: friend?.remark ?? "",
+		category: {
+			category_id: 0,
+			category_name: ""
+		}
+	};
+}
+//#endregion
+//#region src/milky/helper/request.ts
+/** uid → uin（core 共享解析；ctx 携带映射）。 */
+function toUin$1(uid, ctx) {
+	return resolveUin(uid, ctx.uidToUin);
+}
+/** BuddyReq → friend_request 事件（comment 取 words 字段，形状待校准，缺省空串）。 */
+function toFriendRequestEvent(req, ctx) {
+	const words = req["words"];
+	return {
+		time: Math.floor(Date.now() / MS_TO_SEC$2),
+		self_id: Number(ctx.selfUin),
+		event_type: "friend_request",
+		data: {
+			initiator_id: toUin$1(req.friendUid, ctx),
+			initiator_uid: req.friendUid,
+			comment: typeof words === "string" ? words : "",
+			via: req.sourceName ?? ""
+		}
+	};
+}
+/** GroupNotify → Milky 群请求事件（非未处理状态 / 非请求类返回 null）。 */
+function toGroupRequestEvent(notify, doubt, ctx) {
+	if (notify.status !== GroupNotifyMsgStatus.KUNHANDLE) return null;
+	const groupId = Number(notify.group?.groupCode ?? 0);
+	const seq = Number(notify.seq);
+	const time = Math.floor(Date.now() / MS_TO_SEC$2);
+	const selfId = Number(ctx.selfUin);
+	switch (notify.type) {
+		case GroupNotifyMsgType.REQUEST_JOIN_NEED_ADMINI_STRATOR_PASS: return {
+			time,
+			self_id: selfId,
+			event_type: "group_join_request",
+			data: {
+				group_id: groupId,
+				notification_seq: seq,
+				is_filtered: doubt,
+				initiator_id: toUin$1(notify.user1?.uid, ctx),
+				comment: notify.postscript ?? ""
+			}
+		};
+		case GroupNotifyMsgType.INVITED_NEED_ADMINI_STRATOR_PASS: return {
+			time,
+			self_id: selfId,
+			event_type: "group_invited_join_request",
+			data: {
+				group_id: groupId,
+				notification_seq: seq,
+				initiator_id: toUin$1(notify.user1?.uid, ctx),
+				target_user_id: toUin$1(notify.user2?.uid, ctx)
+			}
+		};
+		case GroupNotifyMsgType.INVITED_BY_MEMBER: return {
+			time,
+			self_id: selfId,
+			event_type: "group_invitation",
+			data: {
+				group_id: groupId,
+				invitation_seq: seq,
+				initiator_id: toUin$1(notify.user1?.uid, ctx),
+				source_group_id: null
+			}
+		};
+		default: return null;
+	}
+}
+/**
+* 群通知涉及的 uid 集合（去重；get_group_notifications 与事件广播共用）。
+* kernel GroupEventChannel 的 onGroupNotifiesUpdated 回调参数已类型化
+* （GroupNotify[]），无需防御收窄。
+*/
+function collectNotifyUids(notifies) {
+	const uids = /* @__PURE__ */ new Set();
+	for (const n of notifies) for (const uid of [n.user1?.uid, n.user2?.uid]) if (uid !== void 0 && uid !== "") uids.add(uid);
+	return [...uids];
+}
+//#endregion
+//#region src/milky/action/error-map.ts
+const milkyErrorCodeMap = {
+	SEND_FAILED: -500,
+	PERMISSION_DENIED: -405,
+	NOT_FOUND: -404,
+	TIMEOUT: -504,
+	NOT_LOGIN: -403,
+	INVALID_PARAM: -400,
+	INVALID_STATE: -409,
+	UNKNOWN: -500
+};
+//#endregion
+//#region src/milky/action/base-action.ts
+/**
+* MilkyAction：Milky 动作基类（zod 校验 + KernelError → 负数 retcode）
+*
+* 与 OB11 BaseAction 分离的原因：Milky 响应信封无 echo、参数解析失败恒
+* retcode=-400（规范），不复用 OB11 的 400/1400 语义。
+* 响应信封由 transport 组装（status/retcode/data/message）。
+*/
+/** zod 错误摘要（单行，issues 取前 3 条）。 */
+function zodSummary(error) {
+	const parts = [];
+	for (const issue of error.issues.slice(0, 3)) parts.push(`${issue.path.map(String).join(".")}: ${issue.message}`);
+	return parts.join("; ");
+}
+var MilkyAction = class {
+	/** 校验并执行（HTTP /api 入口；WS /event 不承载动作）。 */
+	async handle(payload) {
+		const parsed = this.schema.safeParse(payload);
+		if (!parsed.success) return {
+			status: "failed",
+			retcode: -400,
+			data: null,
+			message: `参数解析失败: ${zodSummary(parsed.error)}`
+		};
+		try {
+			return {
+				status: "ok",
+				retcode: 0,
+				data: await this._handle(parsed.data),
+				message: ""
+			};
+		} catch (err) {
+			if (isKernelError(err)) return {
+				status: "failed",
+				retcode: this.errorCodeMap[err.code] ?? this.errorCodeMap.UNKNOWN,
+				data: null,
+				message: err.message
+			};
+			return {
+				status: "failed",
+				retcode: this.errorCodeMap.UNKNOWN,
+				data: null,
+				message: err instanceof Error ? err.message : "未知错误"
+			};
+		}
+	}
+};
+/**
+* 持 MilkyApi 的动作基类：api 注入 + 统一错误映射表（milkyErrorCodeMap）收拢，
+* 动作子类只写 name / schema / _handle。
+*/
+var MilkyApiAction = class extends MilkyAction {
+	errorCodeMap = milkyErrorCodeMap;
+	api;
+	constructor(api) {
+		super();
+		this.api = api;
+	}
+};
+//#endregion
+//#region src/milky/action/group.ts
+const groupIdField$1 = { group_id: z.number().int().min(10001) };
+const userIdField = { user_id: z.number().int().min(10001) };
+const optBool = z.boolean().nullable().optional();
+const optStr$1 = z.string().nullable().optional();
+/** get_group_info：获取群信息（GroupCache 详情缓存优先）。 */
+var GetGroupInfoAction = class extends MilkyApiAction {
+	name = "get_group_info";
+	schema = z.object({
+		...groupIdField$1,
+		no_cache: optBool
+	});
+	async _handle(payload) {
+		const groupCode = String(payload.group_id);
+		return { group: toGroupEntity(this.api.groupCache !== void 0 ? await this.api.groupCache.getGroupDetail(groupCode) : await this.api.groupApi.getGroupInfo(groupCode), groupCode) };
+	}
+};
+/** get_group_member_list：获取群成员列表（GroupCache 惰性回填）。 */
+var GetGroupMemberListAction = class extends MilkyApiAction {
+	name = "get_group_member_list";
+	schema = z.object({
+		...groupIdField$1,
+		no_cache: optBool
+	});
+	async _handle(payload) {
+		return { members: (await membersOf(this.api, String(payload.group_id))).map((m) => toGroupMemberEntity(m, String(payload.group_id), m.uin)) };
+	}
+};
+/** get_group_member_info：获取群成员信息（user_id = uin → 成员单查）。 */
+var GetGroupMemberInfoAction = class extends MilkyApiAction {
+	name = "get_group_member_info";
+	schema = z.object({
+		...groupIdField$1,
+		...userIdField,
+		no_cache: optBool
+	});
+	async _handle(payload) {
+		return { member: toGroupMemberEntity(await memberOf(this.api, payload.group_id, payload.user_id), String(payload.group_id), String(payload.user_id)) };
+	}
+};
+/** set_group_name：设置群名。 */
+var SetGroupNameAction = class extends MilkyApiAction {
+	name = "set_group_name";
+	schema = z.object({
+		...groupIdField$1,
+		new_group_name: z.string()
+	});
+	async _handle(payload) {
+		await this.api.groupApi.modifyGroupName(String(payload.group_id), payload.new_group_name);
+		return {};
+	}
+};
+/** set_group_member_card：设置群名片。 */
+var SetGroupMemberCardAction = class extends MilkyApiAction {
+	name = "set_group_member_card";
+	schema = z.object({
+		...groupIdField$1,
+		...userIdField,
+		card: z.string()
+	});
+	async _handle(payload) {
+		const uid = await this.api.resolveUidFromUin(payload.user_id);
+		this.api.groupApi.setMemberCardName(String(payload.group_id), uid, payload.card);
+		return {};
+	}
+};
+/** set_group_member_admin：设置/取消管理员（is_set 缺省 true）。 */
+var SetGroupMemberAdminAction = class extends MilkyApiAction {
+	name = "set_group_member_admin";
+	schema = z.object({
+		...groupIdField$1,
+		...userIdField,
+		is_set: optBool
+	});
+	async _handle(payload) {
+		const uid = await this.api.resolveUidFromUin(payload.user_id);
+		this.api.groupApi.setMemberRole(String(payload.group_id), uid, payload.is_set === false ? NTGroupMemberRoleMember : NTGroupMemberRoleAdmin);
+		return {};
+	}
+};
+/** set_group_member_mute：禁言成员（duration 秒，0 解除）。 */
+var SetGroupMemberMuteAction = class extends MilkyApiAction {
+	name = "set_group_member_mute";
+	schema = z.object({
+		...groupIdField$1,
+		...userIdField,
+		duration: z.number().int().min(0).nullable().optional()
+	});
+	async _handle(payload) {
+		const uid = await this.api.resolveUidFromUin(payload.user_id);
+		await this.api.groupApi.setMemberShutUp(String(payload.group_id), [{
+			uid,
+			duration: payload.duration ?? 0
+		}]);
+		return {};
+	}
+};
+/** set_group_whole_mute：全员禁言开关（is_mute 缺省 true）。 */
+var SetGroupWholeMuteAction = class extends MilkyApiAction {
+	name = "set_group_whole_mute";
+	schema = z.object({
+		...groupIdField$1,
+		is_mute: optBool
+	});
+	async _handle(payload) {
+		await this.api.groupApi.setGroupShutUp(String(payload.group_id), payload.is_mute !== false);
+		return {};
+	}
+};
+/** kick_group_member：移除成员（reject_add_request 默认 false）。 */
+var KickGroupMemberAction = class extends MilkyApiAction {
+	name = "kick_group_member";
+	schema = z.object({
+		...groupIdField$1,
+		...userIdField,
+		reject_add_request: optBool
+	});
+	async _handle(payload) {
+		const uid = await this.api.resolveUidFromUin(payload.user_id);
+		await this.api.groupApi.kickMember(String(payload.group_id), [uid], payload.reject_add_request === true);
+		return {};
+	}
+};
+/** quit_group：退出群聊。 */
+var QuitGroupAction = class extends MilkyApiAction {
+	name = "quit_group";
+	schema = z.object({ ...groupIdField$1 });
+	async _handle(payload) {
+		await this.api.groupApi.quitGroup(String(payload.group_id));
+		return {};
+	}
+};
+/**
+* get_group_essence_messages：获取精华消息列表。
+* WebApi.getEssenceMsgList 全量拉取后按 page_index/page_size 客户端分页
+* （kernel 无分页参数）；message_time 无源取 operation_time 兜底。
+*/
+var GetGroupEssenceMessagesAction = class extends MilkyApiAction {
+	name = "get_group_essence_messages";
+	schema = z.object({
+		...groupIdField$1,
+		page_index: z.number().int().min(0),
+		page_size: z.number().int().min(0)
+	});
+	async _handle(payload) {
+		const items = await this.api.webApi.getEssenceMsgList(String(payload.group_id));
+		const start = payload.page_index * payload.page_size;
+		const page = items.slice(start, start + payload.page_size);
+		return {
+			messages: page.map((item) => essenceToEntity(item, payload.group_id)),
+			is_end: start + page.length >= items.length
+		};
+	}
+};
+/** set_group_essence_message：设置/取消精华（seq → msgId 反查）。 */
+var SetGroupEssenceMessageAction = class extends MilkyApiAction {
+	name = "set_group_essence_message";
+	schema = z.object({
+		...groupIdField$1,
+		message_seq: z.number().int().min(0),
+		is_set: optBool
+	});
+	async _handle(payload) {
+		const groupCode = String(payload.group_id);
+		const peer = {
+			chatType: ChatType.GROUP,
+			peerUid: groupCode
+		};
+		const msgId = await this.api.resolveMsgIdBySeq(peer, payload.message_seq, ChatType.GROUP);
+		if (msgId === void 0) throw kernelError(`消息 ${payload.message_seq} 不存在`, "NOT_FOUND");
+		if (payload.is_set === false) await this.api.groupApi.removeGroupEssence(groupCode, msgId);
+		else await this.api.groupApi.addGroupEssence(groupCode, msgId);
+		return {};
+	}
+};
+/** send_group_message_reaction：消息表情表态（reaction_type face→"1" / emoji→"2"）。 */
+var SendGroupMessageReactionAction = class extends MilkyApiAction {
+	name = "send_group_message_reaction";
+	schema = z.object({
+		...groupIdField$1,
+		message_seq: z.number().int().min(0),
+		reaction: z.string().min(1),
+		reaction_type: z.enum(["face", "emoji"]).nullable().optional(),
+		is_add: z.boolean().nullable().optional()
+	});
+	async _handle(payload) {
+		const peer = {
+			chatType: ChatType.GROUP,
+			peerUid: String(payload.group_id)
+		};
+		await this.api.msgApi.setMsgEmojiLike(peer, {
+			msgSeq: String(payload.message_seq),
+			emojiId: payload.reaction,
+			emojiType: payload.reaction_type === "emoji" ? "2" : "1",
+			like: payload.is_add !== false
+		});
+		return {};
+	}
+};
+/**
+* get_group_notifications：获取群通知列表。
+* kernel getSingleScreenNotifies 为单屏快照（无翻页）——start_notification_seq
+* 作客户端过滤（取 seq 更小的记录）；next = 本页最小 seq（仍有余量时）。
+*/
+var GetGroupNotificationsAction = class extends MilkyApiAction {
+	name = "get_group_notifications";
+	schema = z.object({
+		start_notification_seq: z.number().int().min(0).nullable().optional(),
+		is_filtered: optBool,
+		limit: z.number().int().min(0).nullable().optional()
+	});
+	async _handle(payload) {
+		const notifies = await this.api.groupNotifyApi.getSingleScreenNotifies(payload.is_filtered === true, NOTIFY_SEARCH_COUNT);
+		const start = payload.start_notification_seq;
+		const filtered = notifies.filter((n) => start === void 0 || start === null || Number(n.seq) < start);
+		const uidToUin = await this.collectUidToUin(filtered);
+		const entities = filtered.map((n) => notifyToEntity(n, payload.is_filtered === true, uidToUin)).filter((e) => e !== null);
+		const limit = payload.limit ?? NOTIFICATIONS_DEFAULT_LIMIT;
+		const page = entities.slice(0, limit);
+		const minSeq = page.reduce((acc, e) => acc === null ? e.notification_seq : Math.min(acc, e.notification_seq), null);
+		return {
+			notifications: page,
+			next_notification_seq: entities.length > page.length && minSeq !== null ? minSeq : null
+		};
+	}
+	/** 通知 user1/user2 uid → uin 批量转换（失败退空 Map，实体 id 兜底 0）。 */
+	async collectUidToUin(notifies) {
+		const uids = collectNotifyUids(notifies);
+		if (uids.length === 0) return /* @__PURE__ */ new Map();
+		return await this.api.uidToUin(uids).catch(() => /* @__PURE__ */ new Map());
+	}
+};
+/** accept/reject 群请求 / 群邀请公共基类：seq → 通知匹配 → handleGroupRequest。 */
+var HandleGroupNotifyBase = class extends MilkyApiAction {
+	async respond(seq, doubt) {
+		const notify = await findGroupNotify(this.api, String(seq));
+		await this.api.groupNotifyApi.handleGroupRequest(doubt, notify, this.approve ? NTGroupRequestOperateTypes.KAGREE : NTGroupRequestOperateTypes.KREFUSE, " ");
+		return {};
+	}
+};
+/** accept_group_request：同意入群请求（notification_type/group_id 仅 schema 校验）。 */
+var AcceptGroupRequestAction = class extends HandleGroupNotifyBase {
+	name = "accept_group_request";
+	schema = z.object({
+		notification_seq: z.number().int().min(0),
+		notification_type: z.enum(["join_request", "invited_join_request"]),
+		...groupIdField$1,
+		is_filtered: optBool
+	});
+	approve = true;
+	async _handle(payload) {
+		return await this.respond(payload.notification_seq, payload.is_filtered === true);
+	}
+};
+/** reject_group_request：拒绝入群请求（reason 无源，kernel postscript 占位空格）。 */
+var RejectGroupRequestAction = class extends HandleGroupNotifyBase {
+	name = "reject_group_request";
+	schema = z.object({
+		notification_seq: z.number().int().min(0),
+		notification_type: z.enum(["join_request", "invited_join_request"]),
+		...groupIdField$1,
+		is_filtered: optBool,
+		reason: optStr$1
+	});
+	approve = false;
+	async _handle(payload) {
+		return await this.respond(payload.notification_seq, payload.is_filtered === true);
+	}
+};
+/** accept_group_invitation：接受入群邀请（按 invitation_seq 匹配）。 */
+var AcceptGroupInvitationAction = class extends HandleGroupNotifyBase {
+	name = "accept_group_invitation";
+	schema = z.object({
+		...groupIdField$1,
+		invitation_seq: z.number().int().min(0)
+	});
+	approve = true;
+	async _handle(payload) {
+		return await this.respond(payload.invitation_seq, false);
+	}
+};
+/** reject_group_invitation：拒绝入群邀请。 */
+var RejectGroupInvitationAction = class extends HandleGroupNotifyBase {
+	name = "reject_group_invitation";
+	schema = z.object({
+		...groupIdField$1,
+		invitation_seq: z.number().int().min(0)
+	});
+	approve = false;
+	async _handle(payload) {
+		return await this.respond(payload.invitation_seq, false);
+	}
+};
+/** ---------- 内部辅助 ---------- */
+/** 通知查找数量（单屏全量，OB11 DEFAULT_COUNT 同值）。 */
+const NOTIFY_SEARCH_COUNT = 100;
+/** get_group_notifications 默认 limit（规范 default 20）。 */
+const NOTIFICATIONS_DEFAULT_LIMIT = 20;
+/** NTGroupMemberRole 数值（ADMIN=3 / MEMBER=2，setMemberRole 入参）。 */
+const NTGroupMemberRoleAdmin = 3;
+const NTGroupMemberRoleMember = 2;
+/** 成员列表（GroupCache 优先，未装配直查）。 */
+async function membersOf(api, groupCode) {
+	if (api.groupCache !== void 0) return await api.groupCache.getMembers(groupCode);
+	return await api.groupApi.getGroupMemberList(groupCode, true);
+}
+/** 成员单查（user_id = uin；缓存路径经 uid，直查路径按 uin 匹配）。 */
+async function memberOf(api, groupId, userId) {
+	const groupCode = String(groupId);
+	const uin = String(userId);
+	if (api.groupCache !== void 0) {
+		const uid = await api.resolveUidFromUin(userId).catch(() => uin);
+		const member = await api.groupCache.getMember(groupCode, uid);
+		if (member === void 0) throw kernelError(`成员 ${uin} 不在群 ${groupCode}`, "NOT_FOUND");
+		return member;
+	}
+	const hit = (await api.groupApi.getGroupMemberList(groupCode, true)).find((m) => m.uin === uin);
+	if (hit === void 0) throw kernelError(`成员 ${uin} 不在群 ${groupCode}`, "NOT_FOUND");
+	return hit;
+}
+/** 精华项 → GroupEssenceMessage（msg_content 近似翻译：text / image）。 */
+function essenceToEntity(item, groupId) {
+	const segments = [];
+	for (const c of item.msg_content) if (c.text !== void 0 && c.text !== "") segments.push({
+		type: "text",
+		data: { text: c.text }
+	});
+	else if (c.image_url !== void 0 && c.image_url !== "") segments.push({
+		type: "image",
+		data: {
+			resource_id: c.image_url,
+			temp_url: c.image_url,
+			width: 0,
+			height: 0,
+			summary: "",
+			sub_type: "normal"
+		}
+	});
+	return {
+		group_id: groupId,
+		message_seq: item.msg_seq,
+		message_time: item.add_digest_time,
+		sender_id: Number(item.sender_uin) || 0,
+		sender_name: item.sender_nick,
+		operator_id: Number(item.add_digest_uin) || 0,
+		operator_name: item.add_digest_nick,
+		operation_time: item.add_digest_time,
+		segments
+	};
+}
+/**
+* GroupNotify → GroupNotificationEntity（uidToUin 已由调用方批量转换）。
+* 类型→构造器表：7=入群申请 / 5=成员邀请他人 / 8=设管理 / 12,13=取消管理 /
+* 9,10=踢出 / 11=退群；1=邀请自身无实体变体（事件层表达），其余 null。
+*/
+const NOTIFY_ENTITY_BUILDERS = {
+	7: (n, uinOf) => ({
+		type: "join_request",
+		group_id: Number(n.group?.groupCode ?? 0),
+		notification_seq: Number(n.seq),
+		is_filtered: false,
+		initiator_id: uinOf(n.user1?.uid),
+		state: "pending",
+		operator_id: null,
+		comment: n.postscript ?? ""
+	}),
+	5: (n, uinOf) => ({
+		type: "invited_join_request",
+		group_id: Number(n.group?.groupCode ?? 0),
+		notification_seq: Number(n.seq),
+		initiator_id: uinOf(n.user1?.uid),
+		target_user_id: uinOf(n.user2?.uid),
+		state: "pending",
+		operator_id: null
+	}),
+	8: (n, uinOf) => adminChangeEntity(n, uinOf, true),
+	12: (n, uinOf) => adminChangeEntity(n, uinOf, false),
+	13: (n, uinOf) => adminChangeEntity(n, uinOf, false),
+	9: (n, uinOf) => kickEntity(n, uinOf),
+	10: (n, uinOf) => kickEntity(n, uinOf),
+	11: (n, uinOf) => ({
+		type: "quit",
+		group_id: Number(n.group?.groupCode ?? 0),
+		notification_seq: Number(n.seq),
+		target_user_id: uinOf(n.user1?.uid)
+	})
+};
+/** admin_change 实体（8/12/13 共用）。 */
+function adminChangeEntity(n, uinOf, isSet) {
+	return {
+		type: "admin_change",
+		group_id: Number(n.group?.groupCode ?? 0),
+		notification_seq: Number(n.seq),
+		target_user_id: uinOf(n.user1?.uid),
+		is_set: isSet,
+		operator_id: uinOf(n.user2?.uid)
+	};
+}
+/** kick 实体（9/10 共用）。 */
+function kickEntity(n, uinOf) {
+	return {
+		type: "kick",
+		group_id: Number(n.group?.groupCode ?? 0),
+		notification_seq: Number(n.seq),
+		target_user_id: uinOf(n.user1?.uid),
+		operator_id: uinOf(n.user2?.uid)
+	};
+}
+/** GroupNotify → 实体（isFiltered 透传给 join_request；未识别类型 null）。 */
+function notifyToEntity(notify, isFiltered, uidToUin) {
+	const uinOf = (uid) => uid === void 0 || uid === "" ? 0 : Number(uidToUin.get(uid) ?? 0) || 0;
+	const builder = NOTIFY_ENTITY_BUILDERS[notify.type];
+	if (builder === void 0) return null;
+	const entity = builder(notify, uinOf);
+	if (entity.type === "join_request") entity.is_filtered = isFiltered;
+	return entity;
+}
+//#endregion
+//#region src/milky/action/group-file.ts
+const groupIdField = { group_id: z.number().int().min(10001) };
+const fileIdField = { file_id: z.string().min(1) };
+const optStr = z.string().nullable().optional();
+/** get_group_files：获取群文件列表（根目录或指定文件夹；过滤 parent 匹配项）。 */
+var GetGroupFilesAction = class extends MilkyApiAction {
+	name = "get_group_files";
+	schema = z.object({
+		...groupIdField,
+		parent_folder_id: optStr
+	});
+	async _handle(payload) {
+		const groupCode = String(payload.group_id);
+		const parent = payload.parent_folder_id ?? "";
+		const items = await this.api.richMediaApi.getGroupFileList(groupCode, parent);
+		const files = [];
+		const folders = [];
+		for (const item of items) if (item.fileInfo !== void 0) files.push(fileToEntity(item.fileInfo, payload.group_id));
+		else if (item.folderInfo !== void 0) folders.push(folderToEntity(item.folderInfo, payload.group_id));
+		return {
+			files,
+			folders
+		};
+	}
+};
+/** move_group_file：移动文件（target_folder_id 空 = 移到根目录；parent 入参仅 schema 兼容）。 */
+var MoveGroupFileAction = class extends MilkyApiAction {
+	name = "move_group_file";
+	schema = z.object({
+		...groupIdField,
+		...fileIdField,
+		parent_folder_id: optStr,
+		target_folder_id: optStr
+	});
+	async _handle(payload) {
+		await this.api.richMediaApi.moveGroupFile(String(payload.group_id), [payload.file_id], payload.target_folder_id ?? "");
+		return {};
+	}
+};
+/** rename_group_file：重命名文件。 */
+var RenameGroupFileAction = class extends MilkyApiAction {
+	name = "rename_group_file";
+	schema = z.object({
+		...groupIdField,
+		...fileIdField,
+		parent_folder_id: optStr,
+		new_file_name: z.string().min(1)
+	});
+	async _handle(payload) {
+		await this.api.richMediaApi.renameGroupFile(String(payload.group_id), payload.file_id, payload.new_file_name);
+		return {};
+	}
+};
+/** delete_group_file：删除文件。 */
+var DeleteGroupFileAction = class extends MilkyApiAction {
+	name = "delete_group_file";
+	schema = z.object({
+		...groupIdField,
+		...fileIdField
+	});
+	async _handle(payload) {
+		await this.api.richMediaApi.deleteGroupFile(String(payload.group_id), [payload.file_id]);
+		return {};
+	}
+};
+/**
+* persist_group_file：转存文件（RichMediaApi.transGroupFile，转存语义待对齐）。
+*/
+var PersistGroupFileAction = class extends MilkyApiAction {
+	name = "persist_group_file";
+	schema = z.object({
+		...groupIdField,
+		...fileIdField
+	});
+	async _handle(payload) {
+		await this.api.richMediaApi.transGroupFile(String(payload.group_id), payload.file_id);
+		return {};
+	}
+};
+/** create_group_folder：创建文件夹（返回 folder_id）。 */
+var CreateGroupFolderAction = class extends MilkyApiAction {
+	name = "create_group_folder";
+	schema = z.object({
+		...groupIdField,
+		folder_name: z.string().min(1)
+	});
+	async _handle(payload) {
+		return { folder_id: await this.api.richMediaApi.createGroupFolder(String(payload.group_id), payload.folder_name) };
+	}
+};
+/** delete_group_folder：删除文件夹。 */
+var DeleteGroupFolderAction = class extends MilkyApiAction {
+	name = "delete_group_folder";
+	schema = z.object({
+		...groupIdField,
+		folder_id: z.string().min(1)
+	});
+	async _handle(payload) {
+		await this.api.richMediaApi.deleteGroupFolder(String(payload.group_id), payload.folder_id);
+		return {};
+	}
+};
+/** GroupFileItemInfo → GroupFileEntity（fileSize 原生为字符串；无源字段兜底）。 */
+function fileToEntity(info, groupId) {
+	return {
+		group_id: groupId,
+		file_id: info.fileId,
+		file_name: info.fileName,
+		parent_folder_id: info.parent ?? "",
+		file_size: Number(info.fileSize) || 0,
+		uploaded_time: Number(info.uploadTime) || 0,
+		expire_time: null,
+		uploader_id: Number(info.uploaderUin) || 0,
+		downloaded_times: 0
+	};
+}
+/** GroupFolderInfo → GroupFolderEntity（元数据无类型字段防御读取，缺省 0）。 */
+function folderToEntity(info, groupId) {
+	const num = (key) => {
+		const v = info[key];
+		return typeof v === "number" ? v : Number(v) || 0;
+	};
+	return {
+		group_id: groupId,
+		folder_id: info.folderId,
+		parent_folder_id: info.folderUid ?? "",
+		folder_name: info.folderName,
+		created_time: num("createTime"),
+		last_modified_time: num("modifyTime"),
+		creator_id: 0,
+		file_count: num("totalFileCount")
+	};
+}
+//#endregion
+//#region src/milky/helper/media-uri.ts
+/**
+* 发送媒体 URI 解析（Milky OutgoingSegment uri → 本地路径）
+*
+* 规范支持 file:// / http(s):// / base64:// 三种（image/record/video 共用）：
+*  - file:// → 平台路径（segments.ts 的同步面已处理）
+*  - base64:// → 解码落盘 cacheDir/milky/，file-type 探测扩展名后改名
+*  - http(s):// → @napuketto/media downloadUrl 落盘 cacheDir/milky/
+* 未配置 mediaDir 时远程 URI 报错（不发静默空消息）。
+*/
+/** 解析远程媒体 URI 为本地绝对路径（base64:// / http(s)://；file:// 走同步面）。 */
+async function resolveMediaUri(uri, mediaDir) {
+	if (mediaDir === void 0 || mediaDir === "") throw kernelError("远程媒体发送需要配置 [accounts.milky] cacheDir（下载缓存目录）", "INVALID_PARAM");
+	if (uri.startsWith("base64://")) return await writeBase64(uri.slice(9), mediaDir);
+	const dest = join(mediaDir, `${randomUUID()}${inferExtension(null, uri)}`);
+	await downloadUrl(uri, dest);
+	return dest;
+}
+/** base64 载荷 → 落盘（先写 .bin，探测到扩展名再改名）。 */
+async function writeBase64(payload, mediaDir) {
+	let bytes;
+	try {
+		bytes = Buffer.from(payload, "base64");
+	} catch {
+		throw kernelError("base64:// 载荷解码失败", "INVALID_PARAM");
+	}
+	if (bytes.length === 0) throw kernelError("base64:// 载荷为空", "INVALID_PARAM");
+	await mkdir(mediaDir, { recursive: true });
+	const raw = join(mediaDir, `${randomUUID()}.bin`);
+	await writeFile(raw, bytes);
+	try {
+		const { ext } = await detectFileType(raw);
+		const final = join(mediaDir, `${randomUUID()}${ext}`);
+		await rename(raw, final);
+		return final;
+	} catch {
+		return raw;
+	}
+}
+//#endregion
+//#region src/milky/helper/segments.ts
+/**
+* Milky 消息段 ↔ canonical 元素转换（纯函数，ADR-008）
+*
+* 接收方向：canonical → IncomingSegment（规范 14 种中映射 12 种；market_face /
+* markdown 无 canonical 对应（MFACE/MARKDOWN 原始元素形状未探测），unknown 一律
+* 跳过——规范兼容性要求「数组中未知项跳过」）。forward 接收段不经 canonical：
+* kernel 无 MULTI_FORWARD 分支，adapter 从 RawMessage 提取 resId 后经
+* incomingForwardSegment + ctx 注入。
+* 发送方向：OutgoingSegment → canonical（10 种中映射 9 种；forward 发送需要
+* kernel 组装任意内容的新转发（未探测），显式报错不静默跳过）。
+*/
+/** uin 字符串 → Milky user_id（非有限正数 = 转换失败）。 */
+function toUserId(uin) {
+	const n = Number(uin);
+	return Number.isFinite(n) && n >= 10001 ? n : void 0;
+}
+/** canonical 元素 → IncomingSegment 列表（unknown / 转换失败段跳过）。 */
+function canonicalToIncomingSegments(elements, ctx = {}) {
+	const out = [];
+	for (const el of elements) {
+		const seg = canonicalToIncomingSegment(el, ctx);
+		if (seg !== null) out.push(seg);
+	}
+	return out;
+}
+/** canonical image → image 段（resource_id = 本地路径优先，url 兜底）。 */
+function imageToIncoming(el) {
+	return {
+		type: "image",
+		data: {
+			resource_id: el.path !== "" ? el.path : el.url ?? "",
+			temp_url: el.url ?? "",
+			width: el.size?.width ?? 0,
+			height: el.size?.height ?? 0,
+			summary: "",
+			sub_type: "normal"
+		}
+	};
+}
+/** canonical voice → record 段。 */
+function voiceToIncoming(el) {
+	return {
+		type: "record",
+		data: {
+			resource_id: el.path !== "" ? el.path : el.url ?? "",
+			temp_url: el.url ?? "",
+			duration: el.durationMs !== void 0 ? Math.round(el.durationMs / 1e3) : 0
+		}
+	};
+}
+/** canonical video → video 段。 */
+function videoToIncoming(el) {
+	return {
+		type: "video",
+		data: {
+			resource_id: el.path !== "" ? el.path : el.url ?? "",
+			temp_url: el.url ?? "",
+			width: el.width ?? 0,
+			height: el.height ?? 0,
+			duration: el.durationSec ?? 0
+		}
+	};
+}
+/** 按类型分发的段映射器表（键 = canonical type；缺项 = 跳过）。 */
+const INCOMING_MAPPERS = {
+	text: (el) => ({
+		type: "text",
+		data: { text: el.text }
+	}),
+	at: atToIncoming,
+	face: (el) => ({
+		type: "face",
+		data: {
+			face_id: el.id,
+			is_large: false
+		}
+	}),
+	reply: replyToIncoming,
+	image: imageToIncoming,
+	voice: voiceToIncoming,
+	video: videoToIncoming,
+	file: fileToIncoming,
+	json: (el) => ({
+		type: "light_app",
+		data: {
+			app_name: parseAppName(el.raw),
+			json_payload: rawToPayload(el.raw)
+		}
+	}),
+	xml: (el) => ({
+		type: "xml",
+		data: {
+			service_id: 0,
+			xml_payload: rawToPayload(el.raw)
+		}
+	})
+};
+function canonicalToIncomingSegment(el, ctx) {
+	const mapper = INCOMING_MAPPERS[el.type];
+	return mapper === void 0 ? null : mapper(el, ctx);
+}
+/** canonical at → mention / mention_all（uid→uin 失败跳过该段）。 */
+function atToIncoming(el, ctx) {
+	if (el.target === "all") return {
+		type: "mention_all",
+		data: {}
+	};
+	const userId = toUserId(ctx.uidToUin?.get(el.target) ?? el.target);
+	if (userId === void 0) return null;
+	return {
+		type: "mention",
+		data: {
+			user_id: userId,
+			name: el.display ?? ""
+		}
+	};
+}
+/** canonical reply → reply 段（引用元信息经 ctx 回填，未命中全 0 兜底）。 */
+function replyToIncoming(el, ctx) {
+	const meta = ctx.replyMeta?.get(el.messageId);
+	return {
+		type: "reply",
+		data: {
+			message_seq: meta?.messageSeq ?? 0,
+			sender_id: meta?.senderId ?? 0,
+			sender_name: null,
+			time: meta?.time ?? 0,
+			segments: []
+		}
+	};
+}
+/** canonical file → file 段。 */
+function fileToIncoming(el) {
+	return {
+		type: "file",
+		data: {
+			file_id: el.path,
+			file_name: el.name ?? "",
+			file_size: el.size ?? 0
+		}
+	};
+}
+/**
+* 合并转发 → forward 段（P1）。
+* 接收方向 canonical 不承载 MULTI_FORWARD（kernel toCanonicalElement 无此分支），
+* 由 adapter 从 RawMessage 提取 resId 后调用本函数经 ctx 注入（翻译保持纯函数）。
+* title 取 NT fileName（转发卡片标题语义）。
+*/
+function incomingForwardSegment(resId, title) {
+	return {
+		type: "forward",
+		data: {
+			forward_id: resId,
+			title,
+			preview: [],
+			summary: ""
+		}
+	};
+}
+/** json 载荷 → 小程序名（spec app_name：JSON 顶层 app 字段，取不到空串）。 */
+function parseAppName(raw) {
+	let obj = raw;
+	if (typeof raw === "string") try {
+		obj = JSON.parse(raw);
+	} catch {
+		return "";
+	}
+	if (typeof obj !== "object" || obj === null || !("app" in obj)) return "";
+	const app = obj["app"];
+	return typeof app === "string" ? app : "";
+}
+/** canonical json/xml raw → 字符串载荷（字符串原样，其余 JSON 序列化）。 */
+function rawToPayload(raw) {
+	if (typeof raw === "string") return raw;
+	try {
+		return JSON.stringify(raw) ?? "";
+	} catch {
+		return "";
+	}
+}
+/**
+* OutgoingSegment 数组 → canonical 元素（同步映射；媒体 URI 解析与 at uin→uid
+* 由调用方在返回值上继续处理）。
+* forward 显式报错（发送走 kernel 专用链路，P1 接）。
+*/
+function outgoingSegmentsToCanonical(segments) {
+	const elements = [];
+	const atUins = [];
+	const replySeqs = [];
+	for (const seg of segments) switch (seg.type) {
+		case "text":
+			elements.push({
+				type: "text",
+				text: seg.data.text
+			});
+			break;
+		case "mention": {
+			const uin = String(seg.data.user_id);
+			atUins.push(uin);
+			elements.push({
+				type: "at",
+				target: uin
+			});
+			break;
+		}
+		case "mention_all":
+			elements.push({
+				type: "at",
+				target: "all"
+			});
+			break;
+		case "face":
+			elements.push({
+				type: "face",
+				id: seg.data.face_id
+			});
+			break;
+		case "reply":
+			replySeqs.push(seg.data.message_seq);
+			elements.push({
+				type: "reply",
+				messageId: String(seg.data.message_seq)
+			});
+			break;
+		case "image":
+			elements.push({
+				type: "image",
+				path: resolveUriToPathPlaceholder(seg.data.uri)
+			});
+			break;
+		case "record":
+			elements.push({
+				type: "voice",
+				path: resolveUriToPathPlaceholder(seg.data.uri)
+			});
+			break;
+		case "video":
+			elements.push({
+				type: "video",
+				path: resolveUriToPathPlaceholder(seg.data.uri)
+			});
+			break;
+		case "light_app":
+			elements.push({
+				type: "json",
+				raw: seg.data.json_payload
+			});
+			break;
+		case "forward": throw kernelError("forward 段发送暂未支持（需 kernel 组装任意内容的新转发，P2 探测）", "INVALID_PARAM");
+	}
+	return {
+		elements,
+		atUins,
+		replySeqs
+	};
+}
+/**
+* 媒体 URI → 本地路径（同步面：file:// / 裸路径直接给 canonical；base64:// 与
+* http(s):// 需要异步落盘，由 send 核心在 canonical 上二次解析——此处先放原始
+* URI 作占位，send 核心按元素类型调用 resolveMediaUri 替换）。
+*/
+function resolveUriToPathPlaceholder(uri) {
+	if (uri.startsWith("file://")) return fileUriToPath(uri);
+	if (uri.startsWith("http://") || uri.startsWith("https://") || uri.startsWith("base64://")) return uri;
+	return uri;
+}
+/** file:// 前缀（fileURLToPath 失败时的裸剥离兜底）。 */
+const FILE_URI_PREFIX_RE = /^file:\/\//;
+/** file:// URI → 平台路径（Windows 盘符兼容）。 */
+function fileUriToPath(uri) {
+	try {
+		return fileURLToPath(uri);
+	} catch {
+		return uri.replace(FILE_URI_PREFIX_RE, "");
+	}
+}
+//#endregion
+//#region src/milky/helper/translate.ts
+/**
+* Milky 事件翻译（RawMessage → Milky 事件，纯函数，ADR-008）
+*
+* P0 事件两种：message_receive（onRecvMsg）/ message_recall（grayTip REVOKE）。
+* 实体与 reply 回填在广播路径异步取得后经 ctx 注入（翻译保持纯函数）；
+* 撤回事件的 sender_id 取 RawMessage.senderUin（grayTip 系统消息的 sender
+* 即被撤回原消息的发送者，口径待真实事件校准）。
+*/
+/** 毫秒 → 秒（Unix 时间戳）。 */
+const MS_TO_SEC$1 = 1e3;
+/** chatType → message_scene。 */
+function chatTypeToScene(chatType) {
+	if (chatType === ChatType.GROUP) return "group";
+	if (chatType === ChatType.C2C_TEMP) return "temp";
+	return "friend";
+}
+/** peer_id：群聊 = 群号（peerUid）；好友/临时 = 对端 uin（peerUin，空退 peerUid）。 */
+function peerIdOf(msg, scene) {
+	const raw = scene === "group" ? msg.peerUid : msg.peerUin !== "" ? msg.peerUin : msg.peerUid;
+	return Number(raw);
+}
+/** RawMessage → message_receive 事件（实体缺省最小合法值，schema 形状完整）。 */
+function toMessageReceiveEvent(msg, ctx) {
+	const segments = canonicalToIncomingSegments(toCanonicalElements(msg), {
+		...ctx.uidToUin !== void 0 ? { uidToUin: ctx.uidToUin } : {},
+		...ctx.replyMeta !== void 0 ? { replyMeta: ctx.replyMeta } : {}
+	});
+	if (ctx.forwardSegments !== void 0) segments.push(...ctx.forwardSegments);
+	const scene = chatTypeToScene(msg.chatType);
+	const time = Math.floor(Number(msg.msgTime) / MS_TO_SEC$1);
+	let data;
+	if (scene === "group") data = {
+		message_scene: "group",
+		peer_id: peerIdOf(msg, scene),
+		message_seq: Number(msg.msgSeq),
+		sender_id: Number(msg.senderUin),
+		time,
+		segments,
+		group: ctx.groupEntity ?? toGroupEntity(void 0, msg.peerUid),
+		group_member: ctx.groupMemberEntity ?? toGroupMemberEntity(void 0, msg.peerUid, msg.senderUin)
+	};
+	else if (scene === "friend") data = {
+		message_scene: "friend",
+		peer_id: peerIdOf(msg, scene),
+		message_seq: Number(msg.msgSeq),
+		sender_id: Number(msg.senderUin),
+		time,
+		segments,
+		friend: ctx.friendEntity ?? toFriendEntity(void 0, msg.peerUin !== "" ? msg.peerUin : msg.senderUin, msg.peerName)
+	};
+	else data = {
+		message_scene: "temp",
+		peer_id: peerIdOf(msg, scene),
+		message_seq: Number(msg.msgSeq),
+		sender_id: Number(msg.senderUin),
+		time,
+		segments,
+		group: ctx.groupEntity ?? null
+	};
+	return {
+		time,
+		self_id: Number(ctx.selfUin),
+		event_type: "message_receive",
+		data
+	};
+}
+/** 撤回 grayTip → message_recall 事件（非撤回 grayTip 返回 null）。 */
+function toMessageRecallEvent(msg, ctx) {
+	const revoke = (msg.elements.find((el) => el.grayTipElement !== void 0)?.grayTipElement)?.revokeElement;
+	if (revoke === void 0) return null;
+	const scene = chatTypeToScene(msg.chatType);
+	const operatorUin = ctx.uidToUin?.get(revoke.operatorUid) ?? revoke.operatorUid;
+	return {
+		time: Math.floor(Number(msg.msgTime) / MS_TO_SEC$1),
+		self_id: Number(ctx.selfUin),
+		event_type: "message_recall",
+		data: {
+			message_scene: scene,
+			peer_id: peerIdOf(msg, scene),
+			message_seq: Number(msg.msgSeq),
+			sender_id: Number(msg.senderUin),
+			operator_id: Number(operatorUin) || 0,
+			display_suffix: revoke.wording ?? ""
+		}
+	};
+}
+/** 群文件上传事件（群场景文件消息 → group_file_upload，替代 message_receive）。 */
+function toGroupFileUploadEvent(msg, selfUin) {
+	if (msg.chatType !== ChatType.GROUP) return null;
+	const file = msg.elements.find((el) => el.fileElement !== void 0)?.fileElement;
+	if (file === void 0) return null;
+	return {
+		time: Math.floor(Number(msg.msgTime) / MS_TO_SEC$1),
+		self_id: Number(selfUin),
+		event_type: "group_file_upload",
+		data: {
+			group_id: Number(msg.peerUid),
+			user_id: Number(msg.senderUin) || 0,
+			file_id: file.fileUuid ?? file.fileName ?? "",
+			file_name: file.fileName ?? "",
+			file_size: Number(file.fileSize ?? 0)
+		}
+	};
+}
+//#endregion
+//#region src/milky/action/message.ts
+/**
+* OutgoingSegment 宽松校验：入口只保证「{type, data}」形状，字段级转换在
+* outgoingSegmentsToCanonical 内做（未知段跳过 = 规范兼容性要求）。
+*/
+const outgoingSegmentSchema = z.object({
+	type: z.string(),
+	data: z.record(z.string(), z.unknown())
+}).loose();
+const sendMessageFields = { message: z.array(outgoingSegmentSchema).min(1) };
+const recallFields = { message_seq: z.number().int().min(0) };
+/** send_private_message：发送私聊消息。 */
+var SendPrivateMessageAction = class extends MilkyApiAction {
+	name = "send_private_message";
+	schema = z.object({
+		user_id: z.number().int().min(10001),
+		...sendMessageFields
+	});
+	async _handle(payload) {
+		return await sendMilkyMessage(await this.api.resolvePeer("friend", payload.user_id), payload.message, this.api);
+	}
+};
+/** send_group_message：发送群聊消息。 */
+var SendGroupMessageAction = class extends MilkyApiAction {
+	name = "send_group_message";
+	schema = z.object({
+		group_id: z.number().int().min(10001),
+		...sendMessageFields
+	});
+	async _handle(payload) {
+		return await sendMilkyMessage(await this.api.resolvePeer("group", payload.group_id), payload.message, this.api);
+	}
+};
+/** get_message：获取单条消息（seq → msgId 反查 + 实体回填）。 */
+var GetMessageAction = class extends MilkyApiAction {
+	name = "get_message";
+	schema = z.object({ ...peerMessageFields });
+	async _handle(payload) {
+		const peer = await this.api.resolvePeer(payload.message_scene, payload.peer_id);
+		const msgId = await this.api.resolveMsgIdBySeq(peer, payload.message_seq, peer.chatType);
+		if (msgId === void 0) throw kernelError(`消息 ${payload.message_seq} 不存在`, "NOT_FOUND");
+		const [msg] = await this.api.msgApi.fetchMsgsByMsgId(peer, [msgId]);
+		if (msg === void 0) throw kernelError(`消息 ${payload.message_seq} 不存在`, "NOT_FOUND");
+		return { message: await this.translateWithEntities(payload.message_scene, peer, msg) };
+	}
+	/** 实体回填（group 场景 schema 要求完整实体）→ IncomingMessage。 */
+	async translateWithEntities(scene, peer, msg) {
+		const ctx = { selfUin: this.api.self.uin };
+		if (scene === "group") {
+			const [detail, member] = await Promise.all([this.api.groupCache?.getGroupDetail(peer.peerUid).catch(() => void 0), this.api.groupCache?.getMember(peer.peerUid, msg.senderUid).catch(() => void 0)]);
+			ctx.groupEntity = toGroupEntity(detail, peer.peerUid);
+			ctx.groupMemberEntity = toGroupMemberEntity(member, peer.peerUid, msg.senderUin);
+		}
+		return toMessageReceiveEvent(msg, ctx).data;
+	}
+};
+/** recall_private_message：撤回私聊消息。 */ var RecallPrivateMessageAction = class extends MilkyApiAction {
+	name = "recall_private_message";
+	schema = z.object({
+		user_id: z.number().int().min(10001),
+		...recallFields
+	});
+	async _handle(payload) {
+		await recallBySeq(await this.api.resolvePeer("friend", payload.user_id), payload.message_seq, this.api);
+		return {};
+	}
+};
+/** recall_group_message：撤回群消息。 */
+var RecallGroupMessageAction = class extends MilkyApiAction {
+	name = "recall_group_message";
+	schema = z.object({
+		group_id: z.number().int().min(10001),
+		...recallFields
+	});
+	async _handle(payload) {
+		await recallBySeq(await this.api.resolvePeer("group", payload.group_id), payload.message_seq, this.api);
+		return {};
+	}
+};
+/** seq → msgId（反查）→ recallMessage。 */
+async function recallBySeq(peer, seq, api) {
+	const msgId = await api.resolveMsgIdBySeq(peer, seq, peer.chatType);
+	if (msgId === void 0) throw kernelError(`消息 ${seq} 不存在`, "NOT_FOUND");
+	await api.msgApi.recallMessage(peer, [msgId]);
+}
+/** 发送核心：segments → canonical（URI/ID 转换）→ sendMessage → 回查输出。 */
+async function sendMilkyMessage(peer, segments, api) {
+	const { elements, atUins } = outgoingSegmentsToCanonical(segments);
+	const resolved = await resolveElements(elements, atUins, api);
+	if (resolved.length === 0) throw kernelError("消息内容为空（全部消息段不可用）", "INVALID_PARAM");
+	const { msgId } = await api.msgApi.sendMessage(peer, resolved);
+	return await api.resolveSentOutput(peer, msgId);
+}
+/** 元素二次解析：at uin→uid + 远程媒体 URI 落盘（reply seq 已在映射层兜底原样）。 */
+async function resolveElements(elements, atUins, api) {
+	const uinToUid = await resolveAtUins(atUins, api);
+	const out = [];
+	for (const el of elements) out.push(await resolveElement(el, uinToUid, api));
+	return out;
+}
+/** at uin→uid 批量转换（失败返回 undefined：at 原样 uin，交 QQ 端判断）。 */
+async function resolveAtUins(atUins, api) {
+	if (atUins.length === 0) return;
+	try {
+		return await api.uinToUid(atUins);
+	} catch {
+		return;
+	}
+}
+/** 单元素解析：at 目标替换 / 远程媒体 URI 落盘 / 其余原样。 */
+async function resolveElement(el, uinToUid, api) {
+	if (el.type === "at" && el.target !== "all") return {
+		...el,
+		target: uinToUid?.get(el.target) ?? el.target
+	};
+	if (isRemoteMediaUri(el)) {
+		const media = el;
+		return {
+			...media,
+			path: await resolveMediaUri(media.path, api.mediaDir)
+		};
+	}
+	return el;
+}
+/** 远程媒体元素（image/voice/video 且 path 为需落盘的 URI）。 */
+function isRemoteMediaUri(el) {
+	return (el.type === "image" || el.type === "voice" || el.type === "video") && (el.path.startsWith("http://") || el.path.startsWith("https://") || el.path.startsWith("base64://"));
+}
+/** get_history_messages：获取历史消息（start seq 锚点 → 原生翻页 → 升序输出）。 */
+var GetHistoryMessagesAction = class extends MilkyApiAction {
+	name = "get_history_messages";
+	schema = z.object({
+		message_scene: z.enum([
+			"friend",
+			"group",
+			"temp"
+		]),
+		peer_id: z.number().int().min(10001),
+		start_message_seq: z.number().int().min(0).nullable().optional(),
+		limit: z.number().int().min(0).nullable().optional()
+	});
+	async _handle(payload) {
+		const limit = payload.limit ?? HISTORY_DEFAULT_LIMIT;
+		const peer = await this.api.resolvePeer(payload.message_scene, payload.peer_id);
+		const anchor = await this.resolveAnchor(peer, payload.start_message_seq);
+		const msgs = await this.api.msgApi.fetchMessages(peer, {
+			count: limit,
+			...anchor !== void 0 ? { msgId: anchor } : {}
+		});
+		for (const m of msgs) this.api.seqIndex.record(m);
+		const groupData = payload.message_scene === "group" ? await this.loadGroupData(peer.peerUid) : null;
+		const ordered = [...msgs].reverse();
+		const messages = ordered.map((m) => this.translateHistoryMessage(m, peer.peerUid, groupData));
+		const hasMore = msgs.length >= limit;
+		const oldest = ordered[0];
+		return {
+			messages,
+			next_message_seq: hasMore && oldest !== void 0 ? Number(oldest.msgSeq) : null
+		};
+	}
+	/** start_message_seq → 锚点 msgId（给了 seq 却反查不到 = NOT_FOUND）。 */
+	async resolveAnchor(peer, startSeq) {
+		if (startSeq === void 0 || startSeq === null) return;
+		const msgId = await this.api.resolveMsgIdBySeq(peer, startSeq, peer.chatType);
+		if (msgId === void 0) throw kernelError(`起始消息 ${startSeq} 不存在`, "NOT_FOUND");
+		return msgId;
+	}
+	/** 群场景回填数据（详情 + 成员表；缓存未装配返回空数据）。 */
+	async loadGroupData(groupCode) {
+		if (this.api.groupCache === void 0) return {
+			detail: void 0,
+			members: /* @__PURE__ */ new Map()
+		};
+		const [detail, members] = await Promise.all([this.api.groupCache.getGroupDetail(groupCode).catch(() => void 0), this.api.groupCache.getMembers(groupCode).catch(() => [])]);
+		const memberByUid = /* @__PURE__ */ new Map();
+		for (const m of members) memberByUid.set(m.uid, m);
+		return {
+			detail,
+			members: memberByUid
+		};
+	}
+	/** 单条历史消息 → IncomingMessage（群场景注入实体，fail-soft）。 */
+	translateHistoryMessage(msg, peerUid, groupData) {
+		const ctx = { selfUin: this.api.self.uin };
+		if (groupData !== null) {
+			if (groupData.detail !== void 0) ctx.groupEntity = toGroupEntity(groupData.detail, peerUid);
+			const member = groupData.members.get(msg.senderUid);
+			if (member !== void 0) ctx.groupMemberEntity = toGroupMemberEntity(member, peerUid, msg.senderUin);
+		}
+		return toMessageReceiveEvent(msg, ctx).data;
+	}
+};
+/** get_forwarded_messages：获取合并转发内容（resId → 转发索引 → fetchForwardMessage）。 */
+var GetForwardedMessagesAction = class extends MilkyApiAction {
+	name = "get_forwarded_messages";
+	schema = z.object({ forward_id: z.string().min(1) });
+	async _handle(payload) {
+		const entry = this.api.seqIndex.resolveForward(payload.forward_id);
+		if (entry === void 0) throw kernelError(`转发消息 ${payload.forward_id} 不存在（未登记）`, "NOT_FOUND");
+		const peer = {
+			chatType: entry.chatType,
+			peerUid: entry.peerUid
+		};
+		const msgs = await this.api.msgApi.fetchForwardMessage(peer, entry.msgId);
+		for (const m of msgs) this.api.seqIndex.record(m);
+		const uidToUin = await this.collectUidToUin(msgs);
+		const messages = [];
+		for (const m of msgs) messages.push({
+			message_seq: Number(m.msgSeq),
+			sender_name: await this.senderNameOf(m),
+			avatar_url: avatarUrlOf(m.senderUin),
+			time: Math.floor(Number(m.msgTime) / 1e3),
+			segments: receiveSegmentsOf(m, uidToUin)
+		});
+		return { messages };
+	}
+	/** at 段 uid → uin 批量转换（mention 翻译；失败退空 Map）。 */
+	async collectUidToUin(msgs) {
+		const uids = /* @__PURE__ */ new Set();
+		for (const m of msgs) for (const el of toCanonicalElements(m)) if (el.type === "at" && el.target !== "all") uids.add(el.target);
+		if (uids.size === 0) return /* @__PURE__ */ new Map();
+		return await this.api.uidToUin([...uids]).catch(() => /* @__PURE__ */ new Map());
+	}
+	/** 发送者名（群场景成员缓存昵称/名片，失败退 uin 字符串）。 */
+	async senderNameOf(msg) {
+		if (this.api.groupCache !== void 0 && msg.chatType === ChatType.GROUP) {
+			const member = await this.api.groupCache.getMember(msg.peerUid, msg.senderUid).catch(() => void 0);
+			const name = member?.cardName !== void 0 && member.cardName !== "" ? member.cardName : member?.nick;
+			if (name !== void 0 && name !== "") return name;
+		}
+		return msg.senderUin;
+	}
+};
+/** mark_message_as_read：标记会话已读（NT setMsgRead 以会话为粒度，seq 入参仅兼容 schema）。 */
+var MarkMessageAsReadAction = class extends MilkyApiAction {
+	name = "mark_message_as_read";
+	schema = z.object({ ...peerMessageFields });
+	async _handle(payload) {
+		const peer = await this.api.resolvePeer(payload.message_scene, payload.peer_id);
+		await this.api.msgApi.markRead(peer);
+		return {};
+	}
+};
+/** 历史消息默认条数（规范 default 20）。 */
+const HISTORY_DEFAULT_LIMIT = 20;
+/** get_message / mark_message_as_read 共入参（场景 + 对端 + seq）。 */
+const peerMessageFields = {
+	message_scene: z.enum([
+		"friend",
+		"group",
+		"temp"
+	]),
+	peer_id: z.number().int().min(10001),
+	message_seq: z.number().int().min(0)
+};
+/** 单条消息 → 接收段（canonical 映射 + forward 段注入，forward 不经 canonical）。 */
+function receiveSegmentsOf(msg, uidToUin) {
+	const segments = canonicalToIncomingSegments(toCanonicalElements(msg), { ...uidToUin.size > 0 ? { uidToUin } : {} });
+	const fwd = msg.elements.find((el) => el.multiForwardMsgElement !== void 0)?.multiForwardMsgElement;
+	if (fwd !== void 0) segments.push(incomingForwardSegment(fwd.resId, fwd.fileName));
+	return segments;
+}
+/** QQ 头像 URL（公开头像服务，640px）。 */
+function avatarUrlOf(uin) {
+	return uin === "" ? "" : `https://q1.qlogo.cn/g?b=qq&nk=${uin}&s=640`;
+}
+//#endregion
+//#region src/milky/action/profile.ts
+/**
+* Milky 资料类动作（P1）：get_user_profile / get_friend_info / set_avatar /
+* set_nickname / set_bio / get_cookies / get_csrf_token
+*
+* set_avatar 的 uri 经 media-uri 解析（本地路径 / file:// 直用，http(s)/base64
+* 落盘 mediaDir）；get_cookies 输出规范为单字符串（k=v 分号拼接）；
+* get_csrf_token = qun.qq.com cookies 的 skey → bkn（OB11 get_csrf_token 同口径）。
+*/
+/** CSRF 计算域名（bkn 口径，OB11 get_csrf_token 同源）。 */
+const CSRF_DOMAIN = "qun.qq.com";
+/** get_user_profile：获取用户个人信息（陌生人信息 API；country/city/school 无源空兜底）。 */
+var GetUserProfileAction = class extends MilkyApiAction {
+	name = "get_user_profile";
+	schema = z.object({ user_id: z.number().int().min(10001) });
+	async _handle(payload) {
+		const info = await this.api.profileApi.getStrangerInfo(String(payload.user_id));
+		return {
+			nickname: info.nickname,
+			qid: info.qid,
+			age: info.age,
+			sex: info.sex,
+			remark: info.remark,
+			bio: info.long_nick,
+			level: info.qq_level,
+			country: "",
+			city: "",
+			school: ""
+		};
+	}
+};
+/** get_friend_info：获取好友信息（好友列表单查）。 */
+var GetFriendInfoAction = class extends MilkyApiAction {
+	name = "get_friend_info";
+	schema = z.object({
+		user_id: z.number().int().min(10001),
+		no_cache: z.boolean().nullable().optional()
+	});
+	async _handle(payload) {
+		const uin = String(payload.user_id);
+		const friend = (await this.api.friendApi.getFriendList()).find((f) => f.uin === uin);
+		if (friend === void 0) throw kernelError(`好友 ${uin} 不存在`, "NOT_FOUND");
+		return { friend: toFriendEntity(friend, friend.uin, friend.nickname) };
+	}
+};
+/** set_avatar：设置头像（uri → 本地路径）。 */
+var SetAvatarAction = class extends MilkyApiAction {
+	name = "set_avatar";
+	schema = z.object({ uri: z.string().min(1) });
+	async _handle(payload) {
+		const path = await resolveMediaUri(payload.uri, this.api.mediaDir);
+		await this.api.profileApi.setHeader(path);
+		return {};
+	}
+};
+/** set_nickname：设置昵称。 */
+var SetNicknameAction = class extends MilkyApiAction {
+	name = "set_nickname";
+	schema = z.object({ new_nickname: z.string() });
+	async _handle(payload) {
+		await this.api.profileApi.setNickName(payload.new_nickname);
+		return {};
+	}
+};
+/** set_bio：设置个性签名。 */
+var SetBioAction = class extends MilkyApiAction {
+	name = "set_bio";
+	schema = z.object({ new_bio: z.string() });
+	async _handle(payload) {
+		await this.api.profileApi.setLongNick(payload.new_bio);
+		return {};
+	}
+};
+/** get_cookies：获取 cookies（规范输出为 k=v 分号拼接字符串）。 */
+var GetCookiesAction = class extends MilkyApiAction {
+	name = "get_cookies";
+	schema = z.object({ domain: z.string().min(1) });
+	async _handle(payload) {
+		const cookies = await this.api.ticketApi.getCookies(payload.domain, this.api.self.uin);
+		return { cookies: Object.entries(cookies).map(([k, v]) => `${k}=${v}`).join("; ") };
+	}
+};
+/** get_csrf_token：bkn（qun.qq.com skey 派生，OB11 get_csrf_token 同口径）。 */
+var GetCSRFTokenAction = class extends MilkyApiAction {
+	name = "get_csrf_token";
+	schema = z.object({}).strict();
+	async _handle() {
+		const cookies = await this.api.ticketApi.getCookies(CSRF_DOMAIN, this.api.self.uin);
+		return { csrf_token: TicketApi.getBkn(cookies["skey"] ?? "") };
+	}
+};
+//#endregion
+//#region src/milky/action/social.ts
+/**
+* Milky 社交类动作（P0：get_friend_list / get_group_list；
+* P1 +5：send_profile_like / delete_friend / get_friend_requests /
+* accept_friend_request / reject_friend_request）
+*/
+const emptySchema$1 = z.object({}).strict();
+/** get_friend_list：获取好友列表。 */
+var GetFriendListAction = class extends MilkyApiAction {
+	name = "get_friend_list";
+	schema = emptySchema$1;
+	async _handle() {
+		return { friends: (await this.api.friendApi.getFriendList()).map((f) => toFriendEntity(f, f.uin, f.nickname)) };
+	}
+};
+/** get_group_list：获取群列表。
+* 实测校准（2026-08-08，OB11 同款）：原生 getGroupList 返回值无数据，列表经
+* onGroupListUpdate 事件进 GroupCache——缓存优先，为空触发刷新回填。
+*/
+var GetGroupListAction = class extends MilkyApiAction {
+	name = "get_group_list";
+	schema = emptySchema$1;
+	async _handle() {
+		return { groups: (this.api.groupCache !== void 0 ? await this.api.groupCache.listGroupsRefreshed() : await this.api.groupApi.getGroupList(true)).map(groupListToEntity) };
+	}
+};
+/** send_profile_like：发送好友赞（count 缺省 1，规范 default 同值）。 */
+var SendProfileLikeAction = class extends MilkyApiAction {
+	name = "send_profile_like";
+	schema = z.object({
+		user_id: z.number().int().min(10001),
+		count: z.number().int().min(0).nullable().optional()
+	});
+	async _handle(payload) {
+		const uid = await this.api.resolveUidFromUin(payload.user_id);
+		await this.api.profileLikeApi.sendLike(uid, payload.count ?? 1);
+		return {};
+	}
+};
+/** delete_friend：删除好友。 */
+var DeleteFriendAction = class extends MilkyApiAction {
+	name = "delete_friend";
+	schema = z.object({ user_id: z.number().int().min(10001) });
+	async _handle(payload) {
+		const uid = await this.api.resolveUidFromUin(payload.user_id);
+		await this.api.friendApi.deleteFriend(uid);
+		return {};
+	}
+};
+/**
+* get_friend_requests：获取好友请求列表。
+* kernel getBuddyReqList 无过滤/数量参数——is_filtered 入参仅作 schema 兼容
+* （全量返回）；state 无源字段恒 pending（真实状态待探测校准）。
+*/
+var GetFriendRequestsAction = class extends MilkyApiAction {
+	name = "get_friend_requests";
+	schema = z.object({
+		limit: z.number().int().min(0).nullable().optional(),
+		is_filtered: z.boolean().nullable().optional()
+	});
+	async _handle(payload) {
+		const reqs = await this.api.friendApi.getBuddyReqList();
+		let uidToUin = /* @__PURE__ */ new Map();
+		if (reqs.length > 0) uidToUin = await this.api.uidToUin(reqs.map((req) => req.friendUid)).catch(() => /* @__PURE__ */ new Map());
+		const requests = reqs.map((req) => ({
+			time: Number(req.reqTime) || 0,
+			initiator_id: Number(uidToUin.get(req.friendUid)) || 0,
+			initiator_uid: req.friendUid,
+			target_user_id: Number(this.api.self.uin),
+			target_user_uid: this.api.self.uid ?? "",
+			state: "pending",
+			comment: typeof req["words"] === "string" ? req["words"] : "",
+			via: req.sourceName ?? "",
+			is_filtered: false
+		}));
+		const limit = payload.limit ?? requests.length;
+		return { requests: requests.slice(0, limit) };
+	}
+};
+/**
+* accept/reject_friend_request 公共基类：initiator_uid → 查申请 → 应答。
+* kernel handleFriendRequest 无 reason 参数（拒绝理由无源，入参仅 schema 兼容）。
+*/
+var HandleFriendRequestBase = class extends MilkyApiAction {
+	schema = z.object({
+		initiator_uid: z.string().min(1),
+		is_filtered: z.boolean().nullable().optional(),
+		reason: z.string().nullable().optional()
+	});
+	async _handle(payload) {
+		const notify = await findBuddyReq(this.api, payload.initiator_uid);
+		await this.api.friendApi.handleFriendRequest(notify, this.accept);
+		return {};
+	}
+};
+/** accept_friend_request：同意好友申请。 */
+var AcceptFriendRequestAction = class extends HandleFriendRequestBase {
+	name = "accept_friend_request";
+	accept = true;
+};
+/** reject_friend_request：拒绝好友申请。 */
+var RejectFriendRequestAction = class extends HandleFriendRequestBase {
+	name = "reject_friend_request";
+	accept = false;
+};
+//#endregion
+//#region src/milky/action/system.ts
+/**
+* Milky 系统类动作（P0）：get_login_info / get_impl_info
+*
+* get_impl_info 是 Milky 的版本协商面（规范 §compatibility）：milky_version
+* 固定 "1.3"（目标协议版本 1.3.0），qq_protocol_type 固定 windows（自建宿主）。
+*/
+/** Milky 协议版本（docs/protocols/milky.md：目标 1.3.0）。 */
+const MILKY_VERSION = "1.3";
+const emptySchema = z.object({}).strict();
+/** get_login_info：获取登录信息。 */
+var GetLoginInfoAction = class extends MilkyApiAction {
+	name = "get_login_info";
+	schema = emptySchema;
+	async _handle() {
+		return {
+			uin: Number(this.api.self.uin),
+			nickname: this.api.self.nickname
+		};
+	}
+};
+/** get_impl_info：获取协议端信息（版本协商）。 */
+var GetImplInfoAction = class extends MilkyApiAction {
+	name = "get_impl_info";
+	schema = emptySchema;
+	async _handle() {
+		return {
+			impl_name: "napukettoqq",
+			impl_version: this.api.implVersion,
+			qq_protocol_version: this.api.qqVersion,
+			qq_protocol_type: "windows",
+			milky_version: MILKY_VERSION
+		};
+	}
+};
+//#endregion
+//#region src/milky/action/index.ts
+/**
+* Milky 动作注册表（P0 9 个 + P1 40 个 = 49 个）
+*
+* P0 面 = docs/protocols/milky.md §9 P0 清单；P1 面 = §9 P1 清单（群管/精华/
+* 群文件/好友操作/票据/历史与转发）。延后项（nudge 发送 / rename_folder /
+* download_url / resource 反查 / 置顶 / 公告 / 上传）见 milky.md §6。
+*/
+/** Milky 动作注册表（P0+P1 49 动作）。 */
+function createMilkyActionRegistry(opts) {
+	const registry = new ActionRegistry();
+	const { api } = opts;
+	registry.register(new GetLoginInfoAction(api));
+	registry.register(new GetImplInfoAction(api));
+	registry.register(new SendPrivateMessageAction(api));
+	registry.register(new SendGroupMessageAction(api));
+	registry.register(new GetMessageAction(api));
+	registry.register(new RecallPrivateMessageAction(api));
+	registry.register(new RecallGroupMessageAction(api));
+	registry.register(new GetFriendListAction(api));
+	registry.register(new GetGroupListAction(api));
+	registry.register(new GetUserProfileAction(api));
+	registry.register(new GetFriendInfoAction(api));
+	registry.register(new SetAvatarAction(api));
+	registry.register(new SetNicknameAction(api));
+	registry.register(new SetBioAction(api));
+	registry.register(new GetCookiesAction(api));
+	registry.register(new GetCSRFTokenAction(api));
+	registry.register(new SendProfileLikeAction(api));
+	registry.register(new DeleteFriendAction(api));
+	registry.register(new GetFriendRequestsAction(api));
+	registry.register(new AcceptFriendRequestAction(api));
+	registry.register(new RejectFriendRequestAction(api));
+	registry.register(new GetHistoryMessagesAction(api));
+	registry.register(new GetForwardedMessagesAction(api));
+	registry.register(new MarkMessageAsReadAction(api));
+	registry.register(new GetGroupInfoAction(api));
+	registry.register(new GetGroupMemberListAction(api));
+	registry.register(new GetGroupMemberInfoAction(api));
+	registry.register(new SetGroupNameAction(api));
+	registry.register(new SetGroupMemberCardAction(api));
+	registry.register(new SetGroupMemberAdminAction(api));
+	registry.register(new SetGroupMemberMuteAction(api));
+	registry.register(new SetGroupWholeMuteAction(api));
+	registry.register(new KickGroupMemberAction(api));
+	registry.register(new QuitGroupAction(api));
+	registry.register(new GetGroupEssenceMessagesAction(api));
+	registry.register(new SetGroupEssenceMessageAction(api));
+	registry.register(new SendGroupMessageReactionAction(api));
+	registry.register(new GetGroupNotificationsAction(api));
+	registry.register(new AcceptGroupRequestAction(api));
+	registry.register(new RejectGroupRequestAction(api));
+	registry.register(new AcceptGroupInvitationAction(api));
+	registry.register(new RejectGroupInvitationAction(api));
+	registry.register(new GetGroupFilesAction(api));
+	registry.register(new MoveGroupFileAction(api));
+	registry.register(new RenameGroupFileAction(api));
+	registry.register(new DeleteGroupFileAction(api));
+	registry.register(new PersistGroupFileAction(api));
+	registry.register(new CreateGroupFolderAction(api));
+	registry.register(new DeleteGroupFolderAction(api));
+	return registry;
+}
+//#endregion
+//#region src/milky/helper/notice.ts
+/** 毫秒 → 秒（Unix 时间戳）。 */
+const MS_TO_SEC = 1e3;
+/** uid → uin（core 共享解析；ctx 携带映射）。 */
+function toUin(uid, ctx) {
+	return resolveUin(uid, ctx.uidToUin);
+}
+/** 事件信封公共字段。 */
+function envelope(msg, ctx, eventType, data) {
+	return {
+		time: Math.floor(Number(msg.msgTime) / MS_TO_SEC),
+		self_id: Number(ctx.selfUin),
+		event_type: eventType,
+		data
+	};
+}
+/** 单个 grayTip → Milky notice 事件（null = 不可翻译）。 */
+function translateGrayTip(msg, g, ctx) {
+	if (g.aioOpGrayTipElement !== void 0) return aioOpToEvent(msg, g, ctx);
+	if (g.subElementType === GrayTipSubType.GROUP) return groupElementToEvent(msg, g.groupElement, ctx);
+	return null;
+}
+/** 群成员变动类映射器表（键 = TipGroupElementType；缺项 = 不可翻译返回 null）。 */
+const GROUP_CHANGE_MAPPERS = {
+	[TipGroupElementType.MEMBER_ADD]: toMemberIncrease,
+	[TipGroupElementType.QUIT]: toMemberDecrease,
+	[TipGroupElementType.SHUT_UP]: toShutUpEvent,
+	[TipGroupElementType.GROUP_NAME_MODIFIED]: toNameChange,
+	[TipGroupElementType.DISBANDED]: toDisband
+};
+function groupElementToEvent(msg, grp, ctx) {
+	if (grp === void 0 || grp.type === void 0) return null;
+	const mapper = GROUP_CHANGE_MAPPERS[grp.type];
+	if (mapper === void 0) return null;
+	return mapper(msg, groupChangeCommon(grp, Number(msg.peerUid)), grp, ctx);
+}
+/** 禁言载荷优先（shutUp.member/admin 覆盖顶层 memberUid/adminUid）。 */
+function groupChangeCommon(grp, groupId) {
+	return {
+		groupId,
+		memberUid: grp.shutUp?.member?.uid ?? grp.memberUid ?? "",
+		adminUid: grp.shutUp?.admin?.uid ?? grp.adminUid ?? ""
+	};
+}
+/** 群成员增加（管理员同意 → operator_id；邀请入群 → invitor_id）。 */
+function toMemberIncrease(msg, common, _grp, ctx) {
+	const { groupId, memberUid, adminUid } = common;
+	return envelope(msg, ctx, "group_member_increase", {
+		group_id: groupId,
+		user_id: toUin(memberUid, ctx),
+		operator_id: adminUid !== "" && adminUid === memberUid ? toUin(adminUid, ctx) : null,
+		invitor_id: adminUid !== "" && adminUid !== memberUid ? toUin(adminUid, ctx) : null
+	});
+}
+/** 群成员减少（操作者与本人不同 = 被踢；主动退群无操作者）。 */
+function toMemberDecrease(msg, common, _grp, ctx) {
+	const { groupId, memberUid, adminUid } = common;
+	return envelope(msg, ctx, "group_member_decrease", {
+		group_id: groupId,
+		user_id: toUin(memberUid, ctx),
+		operator_id: adminUid !== "" && adminUid !== memberUid ? toUin(adminUid, ctx) : null
+	});
+}
+/** 禁言（member 空 = 全员禁言口径；is_mute = 是否处于禁言态）。 */
+function toShutUpEvent(msg, common, grp, ctx) {
+	const { groupId, memberUid, adminUid } = common;
+	const duration = Number(grp.shutUp?.duration ?? 0);
+	if (memberUid === "") return envelope(msg, ctx, "group_whole_mute", {
+		group_id: groupId,
+		operator_id: toUin(adminUid, ctx),
+		is_mute: duration > 0
+	});
+	return envelope(msg, ctx, "group_mute", {
+		group_id: groupId,
+		user_id: toUin(memberUid, ctx),
+		operator_id: toUin(adminUid, ctx),
+		duration
+	});
+}
+/** 改名 / 解散公共守卫：操作者 uid 不可得时不产出（schema operator_id 下限）。 */
+function operatorOf(common) {
+	return common.adminUid !== "" ? common.adminUid : common.memberUid;
+}
+function toNameChange(msg, common, grp, ctx) {
+	const operatorUid = operatorOf(common);
+	if (operatorUid === "") return null;
+	return envelope(msg, ctx, "group_name_change", {
+		group_id: common.groupId,
+		new_group_name: grp.groupName ?? "",
+		operator_id: toUin(operatorUid, ctx)
+	});
+}
+function toDisband(msg, common, _grp, ctx) {
+	const operatorUid = operatorOf(common);
+	if (operatorUid === "") return null;
+	return envelope(msg, ctx, "group_disband", {
+		group_id: common.groupId,
+		operator_id: toUin(operatorUid, ctx)
+	});
+}
+/**
+* aioOp → 戳一戳事件（friend_nudge / group_nudge）。
+* aioOp 载荷完整字段形状未经实测（已证字段仅 operateType/peerUid）：
+* sender 取消息发送者、receiver 取 aioOp.peerUid（口径与 OB11 poke 一致，待校准）；
+* display_* 字段无来源，恒空串；始终打 raw 日志积累校准数据。
+*/
+function aioOpToEvent(msg, g, ctx) {
+	const aioOp = g.aioOpGrayTipElement;
+	ctx.logger?.warn({ raw: JSON.stringify(g)?.slice(0, 2e3) }, "milky: aioOp grayTip raw（戳一戳待真实事件校准）");
+	if (msg.chatType === ChatType.GROUP) return envelope(msg, ctx, "group_nudge", {
+		group_id: Number(msg.peerUid),
+		sender_id: toUin(msg.senderUid, ctx),
+		receiver_id: toUin(aioOp?.peerUid ?? "", ctx),
+		display_action: "",
+		display_suffix: "",
+		display_action_img_url: ""
+	});
+	const senderUin = toUin(msg.senderUid, ctx);
+	return envelope(msg, ctx, "friend_nudge", {
+		user_id: senderUin,
+		is_self_send: senderUin === Number(ctx.selfUin),
+		is_self_receive: senderUin !== Number(ctx.selfUin),
+		display_action: "",
+		display_suffix: "",
+		display_action_img_url: ""
+	});
+}
+/**
+* RawMessage → Milky notice 事件（无 grayTip / 不可翻译返回 null）。
+* 未知子类型打 raw JSON 日志（JSON/BUDDY/ESSENCE/FILE 等——校准数据积累入口）。
+*/
+function toMilkyNoticeEvent(msg, ctx) {
+	for (const el of msg.elements) {
+		const g = el.grayTipElement;
+		if (g === void 0) continue;
+		const event = translateGrayTip(msg, g, ctx);
+		if (event !== null) return event;
+	}
+	const untranslated = firstUntranslatedGrayTip(msg);
+	if (untranslated !== void 0) ctx.logger?.warn({
+		subType: untranslated.subElementType,
+		raw: JSON.stringify(untranslated)?.slice(0, 2e3)
+	}, "milky: 未翻译的 grayTip 子类型（raw 校准数据）");
+	return null;
+}
+//#endregion
+//#region src/milky/helper/seq-index.ts
+/** 单方向最大条目数（测试用例引用容量语义）。 */
+const MAX_ENTRIES = 4096;
+var MessageSeqIndex = class {
+	/** `${chatType}:${peerUid}:${seq}` → msgId。 */
+	seqToMsg = /* @__PURE__ */ new Map();
+	/** msgId → seq 元信息。 */
+	msgToMeta = /* @__PURE__ */ new Map();
+	/** 合并转发 resId → 定位信息（P1：get_forwarded_messages）。 */
+	forwards = /* @__PURE__ */ new Map();
+	/** 接收链路登记（一条消息双向写入；重复 msgId 覆盖）。 */
+	record(msg) {
+		const seq = Number(msg.msgSeq);
+		if (!Number.isFinite(seq) || seq < 0) return;
+		this.seqToMsg.set(this.key(msg.chatType, msg.peerUid, seq), msg.msgId);
+		this.msgToMeta.set(msg.msgId, {
+			seq,
+			senderUin: msg.senderUin,
+			timeSec: Math.floor(Number(msg.msgTime) / 1e3)
+		});
+		this.evict();
+	}
+	/** seq → msgId（反查；未登记返回 undefined）。 */
+	resolveMsgId(chatType, peerUid, seq) {
+		return this.seqToMsg.get(this.key(chatType, peerUid, seq));
+	}
+	/**
+	* 批量回填 reply 引用元信息（msgId → Milky reply 段 data 所需三元组）。
+	* 未命中的 id 不进表（翻译层按 0 兜底）。
+	*/
+	collectReplyMeta(msgIds) {
+		const out = /* @__PURE__ */ new Map();
+		for (const id of msgIds) {
+			const m = this.msgToMeta.get(id);
+			if (m !== void 0) out.set(id, {
+				messageSeq: m.seq,
+				senderId: Number(m.senderUin) || 0,
+				time: m.timeSec
+			});
+		}
+		return out;
+	}
+	/** key 规则（chatType 数值 + peerUid + seq；peerUid 群聊=群号，C2C=uid）。 */
+	key(chatType, peerUid, seq) {
+		return `${chatType}:${peerUid}:${seq}`;
+	}
+	/**
+	* 登记合并转发（接收链路：消息含 multiForwardMsgElement 时调用）。
+	* resId 是 Milky forward_id 的来源；同一 resId 重复覆盖。
+	*/
+	recordForward(resId, entry) {
+		if (resId === "") return;
+		this.forwards.set(resId, entry);
+		while (this.forwards.size > MAX_ENTRIES) {
+			const oldest = this.forwards.keys().next().value;
+			if (oldest === void 0) break;
+			this.forwards.delete(oldest);
+		}
+	}
+	/** resId → 转发定位（get_forwarded_messages；未登记返回 undefined）。 */
+	resolveForward(resId) {
+		return this.forwards.get(resId);
+	}
+	/** FIFO 淘汰到容量上限内。 */
+	evict() {
+		while (this.seqToMsg.size > MAX_ENTRIES) {
+			const oldest = this.seqToMsg.keys().next().value;
+			if (oldest === void 0) break;
+			this.seqToMsg.delete(oldest);
+		}
+		while (this.msgToMeta.size > MAX_ENTRIES) {
+			const oldest = this.msgToMeta.keys().next().value;
+			if (oldest === void 0) break;
+			this.msgToMeta.delete(oldest);
+		}
+	}
+};
+//#endregion
+//#region src/milky/transport.ts
+/** /event 路径（规范固定）。 */
+const EVENT_PATH = "/event";
+/** /api/ 前缀 + 动作名（小写字母开头，小写/数字/下划线）。 */
+const API_PATH_RE = /^\/api\/([a-z][a-z0-9_]*)$/;
+/** Bearer 前缀。 */
+const BEARER_PREFIX = "Bearer ";
+/**
+* Milky 事件枢纽：SSE 客户端 + WS 客户端集合，send 即广播。
+* 传输适配器面（open/close/send，EventBroadcaster 多态派发）——生命周期随
+* HttpServer。连接注册经 attachTo 挂到 HttpServer 注入点（本类内部闭环）；
+* WS 入帧忽略（规范：/event 为纯事件推送通道）。
+*/
+var MilkyEventHub = class {
+	sseClients = /* @__PURE__ */ new Set();
+	sockets = /* @__PURE__ */ new Set();
+	/** 把 /event 的 SSE（onRawRequest）与 WS 升级（onUpgrade）挂到 HTTP server。 */
+	attachTo(server, config) {
+		server.onRawRequest = (ctx) => {
+			if (ctx.path !== EVENT_PATH || ctx.method !== "GET") return;
+			if (!config.eventModes.includes("sse")) return new Response("event mode sse disabled", { status: 404 });
+			return createSseResponse((client) => {
+				this.sseClients.add(client);
+				return () => {
+					this.sseClients.delete(client);
+				};
+			});
+		};
+		server.onUpgrade = (req, accept, reject) => {
+			if (pathnameOf(req.url) !== EVENT_PATH) return;
+			if (!config.eventModes.includes("ws")) {
+				reject(404, "event mode ws disabled");
+				return;
+			}
+			if (config.token !== "" && !tokenMatches(req, config.token)) {
+				reject(401, "unauthorized");
+				return;
+			}
+			accept((socket) => {
+				this.sockets.add(socket);
+				const remove = () => {
+					this.sockets.delete(socket);
+				};
+				socket.on("close", remove);
+				socket.on("error", remove);
+			});
+		};
+	}
+	/** 广播事件（EventBroadcaster emit 入口）。 */
+	send(event) {
+		const json = JSON.stringify(event);
+		for (const client of this.sseClients) client.send(json, "milky_event");
+		for (const socket of this.sockets) if (socket.readyState === WebSocket.OPEN) socket.send(json);
+	}
+	open() {}
+	async close() {
+		for (const client of this.sseClients) client.close();
+		this.sseClients.clear();
+		for (const socket of this.sockets) socket.close(1001, "server shutdown");
+		this.sockets.clear();
+	}
+	onRequest;
+};
+/** 按配置装配 Milky 传输。 */
+function assembleMilkyTransports(opts) {
+	const { config, broadcaster, registry, logger } = opts;
+	const hub = new MilkyEventHub();
+	const token = config.token;
+	const authorize = token !== "" ? makeMilkyAuthorize(token) : void 0;
+	const server = new HttpServer({
+		host: config.host,
+		port: config.port,
+		...authorize !== void 0 ? { authorize } : {}
+	});
+	hub.attachTo(server, config);
+	server.onPathRequest = (ctx, req, respond) => {
+		handleMilkyHttpRequest(ctx, req, respond, registry);
+	};
+	const adapters = [server, hub];
+	for (const url of config.webhooks) {
+		const client = new HttpClient({
+			url,
+			...token !== "" ? { headers: { authorization: `${BEARER_PREFIX}${token}` } } : {},
+			timeoutMs: 5e3,
+			onError: (err) => {
+				logger?.warn({
+					url,
+					err: String(err)
+				}, "milky: webhook 推送失败");
+			}
+		});
+		adapters.push(client);
+	}
+	for (const adapter of adapters) broadcaster.register(adapter);
+	return {
+		adapters,
+		close: async () => {
+			await server.close();
+			await hub.close();
+			for (const adapter of adapters) broadcaster.unregister(adapter);
+		}
+	};
+}
+/** HTTP /api 分发（规范信封 + 404/415 语义）。 */
+function handleMilkyHttpRequest(ctx, req, respond, registry) {
+	if (ctx.method !== "POST") {
+		respond(void 0, 404);
+		return;
+	}
+	const match = API_PATH_RE.exec(ctx.path);
+	if (match === null) {
+		respond(void 0, 404);
+		return;
+	}
+	const contentType = ctx.headers?.["content-type"];
+	if (contentType !== void 0 && !contentType.toLowerCase().includes("application/json")) {
+		respond(void 0, 415);
+		return;
+	}
+	const action = registry.get(match[1] ?? "");
+	if (action === void 0) {
+		respond(void 0, 404);
+		return;
+	}
+	action.handle(req).then((result) => {
+		if (result.status === "ok") respond({
+			status: "ok",
+			retcode: 0,
+			data: result.data ?? {}
+		});
+		else respond({
+			status: "failed",
+			retcode: result.retcode,
+			data: null,
+			message: result.message
+		});
+	}).catch(() => {
+		respond({
+			status: "failed",
+			retcode: -500,
+			data: null,
+			message: "internal error"
+		});
+	});
+}
+/** 鉴权钩子：Bearer 头或 access_token 查询参数（规范允许 SSE/WS 查询参数兜底）。 */
+function makeMilkyAuthorize(token) {
+	return (ctx) => tokenMatches(ctx, token);
+}
+/** 请求凭据匹配（头优先，查询参数兜底）。 */
+function tokenMatches(ctx, token) {
+	const auth = ctx.headers["authorization"] ?? ctx.headers["Authorization"];
+	if (auth?.startsWith(BEARER_PREFIX)) return auth.slice(7) === token;
+	try {
+		return new URL(ctx.url, "http://localhost").searchParams.get("access_token") === token;
+	} catch {
+		return false;
+	}
+}
+/** URL 路径部分（无 scheme 相对 url 容错）。 */
+function pathnameOf(url) {
+	try {
+		return new URL(url, "http://localhost").pathname;
+	} catch {
+		return url.split("?")[0] ?? "";
+	}
+}
+//#endregion
+//#region src/milky/adapter.ts
+var NapukettoMilkyAdapter = class extends BaseProtocolAdapter {
+	protocol = "milky";
+	msgChannel;
+	groupChannel;
+	buddyChannel;
+	calibLogger;
+	api;
+	seqIndex = new MessageSeqIndex();
+	/** 动作注册表（公共只读：装配方/测试枚举）。 */
+	registry;
+	unsubscribes = [];
+	stopTransports = null;
+	constructor(opts) {
+		super({
+			config: opts.config,
+			broadcaster: opts.broadcaster,
+			hooks: {
+				onStart: (config) => this.startTransports(config),
+				onStop: () => this.stopAll(),
+				onReload: (config) => this.reloadTransports(config)
+			}
+		});
+		this.msgChannel = opts.msgChannel;
+		this.groupChannel = opts.groupChannel;
+		this.buddyChannel = opts.buddyChannel;
+		this.calibLogger = opts.logger;
+		this.api = new MilkyApi(opts, this.seqIndex);
+		this.registry = createMilkyActionRegistry({ api: this.api });
+	}
+	/** 启动传输 + 订阅（enabled=false 空转：不订阅不起传输）。 */
+	async startTransports(config) {
+		if (!config.enabled) {
+			this.calibLogger?.info({}, "milky: 未启用（enabled=false），跳过装配");
+			return;
+		}
+		const broadcaster = this.getBroadcaster();
+		if (broadcaster !== void 0) {
+			const set = assembleMilkyTransports({
+				config,
+				broadcaster,
+				registry: this.registry,
+				...this.calibLogger !== void 0 ? { logger: this.calibLogger } : {}
+			});
+			this.stopTransports = set.close;
+		}
+		this.subscribe();
+		this.calibLogger?.info({
+			host: config.host,
+			port: config.port,
+			modes: config.eventModes
+		}, "milky: adapter started");
+	}
+	/** 热更新：停止重建（enabled 切换生效）。 */
+	async reloadTransports(config) {
+		await this.stopAll();
+		await this.startTransports(config);
+	}
+	/** 停止：退订 + 关传输。 */
+	async stopAll() {
+		this.unsubscribeAll();
+		if (this.stopTransports !== null) {
+			await this.stopTransports();
+			this.stopTransports = null;
+		}
+	}
+	/** 订阅 kernel 事件（消息 + 群通知 + 好友请求，幂等）。 */
+	subscribe() {
+		if (this.unsubscribes.length > 0) return;
+		this.unsubscribes.push(subscribeRawMessages(this.msgChannel, (msg) => {
+			this.handleIncoming(msg);
+		}));
+		if (this.groupChannel !== void 0) {
+			const groupChannel = this.groupChannel;
+			this.unsubscribes.push(groupChannel.on("Group/onGroupNotifiesUpdated", (doubt, notifies) => {
+				this.handleGroupNotifies(doubt, notifies);
+			}));
+		}
+		if (this.buddyChannel !== void 0) {
+			const buddyChannel = this.buddyChannel;
+			this.unsubscribes.push(buddyChannel.on("Buddy/onBuddyReqChange", (arg) => {
+				this.handleBuddyReqs(arg);
+			}));
+		}
+	}
+	/** 退订（幂等）。 */
+	unsubscribeAll() {
+		for (const off of this.unsubscribes) off();
+		this.unsubscribes = [];
+	}
+	/** 单条消息：seq 登记 → grayTip→notice / 群文件上传 / message_receive（自消息不上报）。 */
+	async handleIncoming(msg) {
+		this.seqIndex.record(msg);
+		this.recordForward(msg);
+		if (hasGrayTip(msg)) {
+			await this.broadcastNotice(msg);
+			return;
+		}
+		const upload = toGroupFileUploadEvent(msg, this.api.self.uin);
+		if (upload !== null) {
+			this.broadcastEvent(upload);
+			return;
+		}
+		if (String(msg.senderUin) === this.api.self.uin) return;
+		this.broadcastEvent(await this.buildMessageReceiveEvent(msg));
+	}
+	/** grayTip → notice 事件广播（REVOKE 走 message_recall，其余走 notice 翻译）。 */
+	async broadcastNotice(msg) {
+		const uidToUin = await this.resolveUidToUin(collectGrayTipUids(msg));
+		const event = findRevokeElement(msg) !== void 0 ? toMessageRecallEvent(msg, {
+			selfUin: this.api.self.uin,
+			...uidToUin !== void 0 ? { uidToUin } : {}
+		}) : toMilkyNoticeEvent(msg, this.noticeCtx(uidToUin));
+		if (event !== null) this.broadcastEvent(event);
+	}
+	/** notice 翻译上下文（uidToUin 缺省空 Map；logger 透传校准日志）。 */
+	noticeCtx(uidToUin) {
+		return {
+			selfUin: this.api.self.uin,
+			...uidToUin !== void 0 ? { uidToUin } : { uidToUin: /* @__PURE__ */ new Map() },
+			...this.calibLogger !== void 0 ? { logger: this.calibLogger } : {}
+		};
+	}
+	/** 群通知通道：入群请求 / 成员邀请 / 邀请自身（uid→uin 批量后翻译）。 */
+	async handleGroupNotifies(doubt, notifies) {
+		const ctx = await this.requestCtx(collectNotifyUids(notifies));
+		for (const notify of notifies) {
+			const event = toGroupRequestEvent(notify, doubt, ctx);
+			if (event !== null) this.broadcastEvent(event);
+		}
+	}
+	/** 好友请求通道：Buddy/onBuddyReqChange（防御收窄，未知形状 raw 日志）。 */
+	handleBuddyReqs(arg) {
+		const reqs = narrowBuddyReqs(arg);
+		if (reqs === null) {
+			this.calibLogger?.warn({ raw: truncate(JSON.stringify(arg)) }, "milky: onBuddyReqChange 未知参数形状");
+			return;
+		}
+		(async () => {
+			const ctx = await this.requestCtx(reqs.map((req) => req.friendUid));
+			for (const req of reqs) this.broadcastEvent(toFriendRequestEvent(req, ctx));
+		})();
+	}
+	/** request 翻译上下文（uid→uin 批量转换）。 */
+	async requestCtx(uids) {
+		const uidToUin = await this.resolveUidToUin(uids);
+		return {
+			selfUin: this.api.self.uin,
+			...uidToUin !== void 0 ? { uidToUin } : { uidToUin: /* @__PURE__ */ new Map() }
+		};
+	}
+	/** message_receive 组装：at uid→uin + reply 回填 + 群实体回填 + 转发段（全部 fail-soft）。 */
+	async buildMessageReceiveEvent(msg) {
+		const elements = toCanonicalElements(msg);
+		const ctx = { selfUin: this.api.self.uin };
+		await this.fillMentionUids(elements, ctx);
+		this.fillReplyMeta(elements, ctx);
+		await this.fillGroupEntities(msg, ctx);
+		const forward = msg.elements.find((el) => el.multiForwardMsgElement !== void 0)?.multiForwardMsgElement;
+		if (forward !== void 0) ctx.forwardSegments = [incomingForwardSegment(forward.resId, forward.fileName)];
+		return toMessageReceiveEvent(msg, ctx);
+	}
+	/** at uid → uin 批量转换（mention.user_id 用；失败 mention 段跳过）。 */
+	async fillMentionUids(elements, ctx) {
+		const atUids = elements.filter((el) => el.type === "at" && el.target !== "all").map((el) => el.target);
+		if (atUids.length === 0) return;
+		try {
+			ctx.uidToUin = await this.api.uidToUin(atUids);
+		} catch {}
+	}
+	/** reply 引用元信息回填（seqIndex 命中即用；未命中不强查）。 */
+	fillReplyMeta(elements, ctx) {
+		const replyIds = elements.filter((el) => el.type === "reply").map((el) => el.messageId);
+		const meta = this.seqIndex.collectReplyMeta(replyIds);
+		if (meta.size > 0) ctx.replyMeta = meta;
+	}
+	/** 群场景实体回填（GroupCache 缓存优先，失败最小实体兜底）。 */
+	async fillGroupEntities(msg, ctx) {
+		if (msg.chatType !== ChatType.GROUP || this.api.groupCache === void 0) return;
+		const [detail, member] = await Promise.all([this.api.groupCache.getGroupDetail(msg.peerUid).catch(() => void 0), this.api.groupCache.getMember(msg.peerUid, msg.senderUid).catch(() => void 0)]);
+		ctx.groupEntity = toGroupEntity(detail, msg.peerUid);
+		ctx.groupMemberEntity = toGroupMemberEntity(member, msg.peerUid, msg.senderUin);
+	}
+	/** 转发 resId → 定位登记（get_forwarded_messages 反查用）。 */
+	recordForward(msg) {
+		const forward = msg.elements.find((el) => el.multiForwardMsgElement !== void 0)?.multiForwardMsgElement;
+		if (forward !== void 0 && forward.resId !== "") this.seqIndex.recordForward(forward.resId, {
+			chatType: msg.chatType,
+			peerUid: msg.peerUid,
+			msgId: msg.msgId
+		});
+	}
+	/** uid 批量 → uin（空集/失败返回 undefined 语义：调用方用空 Map）。 */
+	resolveUidToUin(uids) {
+		const unique = [...new Set(uids.filter((uid) => uid !== ""))];
+		if (unique.length === 0) return Promise.resolve(void 0);
+		return this.api.uidToUin(unique).catch(() => void 0);
+	}
+};
+/** 是否含 grayTip 元素（与 OB11 收链路同判据）。 */
+function hasGrayTip(msg) {
+	return msg.elements.some((el) => el.grayTipElement !== void 0);
+}
+/** 撤回 grayTip 元素（非撤回消息返回 undefined）。 */
+function findRevokeElement(msg) {
+	return msg.elements.find((el) => el.grayTipElement?.revokeElement !== void 0)?.grayTipElement?.revokeElement;
+}
+/** 字符串截断（raw 日志防刷屏）。 */
+function truncate(raw) {
+	return raw === void 0 ? "" : raw.slice(0, 2e3);
+}
+//#endregion
+//#region src/milky/config.ts
+/**
+* Milky 协议配置（zod schema，归属本包，ADR-012）
+*
+* 单一 TOML 的 `[accounts.milky]` 账号段（docs/protocols/milky.md §4）：
+* 单端口 HTTP 模型（/api + /event 同端口），`enabled` 缺省 false = 不启用。
+*/
+/** Milky 配置 schema。 */
+const milkyConfigSchema = z.object({
+	/** 启用开关（缺省 false：账号段存在但 enabled 未开 = 装配为空转）。 */
+	enabled: z.boolean().default(false),
+	/** HTTP 监听地址。 */
+	host: z.string().min(1).default("127.0.0.1"),
+	/** HTTP 监听端口（/api 与 /event 同端口）。 */
+	port: z.number().int().min(0).max(65535).default(3001),
+	/** access_token（空 = 不校验，仅限内网）。 */
+	token: z.string().default(""),
+	/** /event 允许的连接形态（缺省两者都开）。 */
+	eventModes: z.array(z.enum(["sse", "ws"])).default(["sse", "ws"]),
+	/** 额外事件推送地址（WebHook，可多个；协议端在请求头发 Bearer token）。 */
+	webhooks: z.array(z.string().min(1)).default([]),
+	/** 发送媒体 http(s) URI 下载缓存目录（缺省不下载 = http(s) 发送媒体不可用）。 */
+	cacheDir: z.string().optional()
+});
+//#endregion
+export { NapukettoMilkyAdapter, milkyConfigSchema };
+
+//# sourceMappingURL=index.mjs.map