@napuketto/adapter 0.4.1 → 0.5.0

package/dist/milky/index.mjs

@@ -0,0 +1,1240 @@
+import { o as ActionRegistry, r as BaseProtocolAdapter } from "../core-DyXyDUcU.mjs";
+import { n as subscribeRawMessages } from "../raw-message-D_ecJy4C.mjs";
+import { ChatType, GroupApi, 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/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/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 种中 P0 映射 12 种；
+* market_face / markdown 无 canonical 对应，unknown 一律跳过——规范兼容性
+* 要求「数组中未知项跳过」）。
+* 发送方向：OutgoingSegment → canonical（10 种中 P0 映射 9 种；forward 发送
+* 走专用内核链路，P0 显式报错不静默跳过）。
+*/
+/** 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,
+	forward: forwardToIncoming,
+	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
+		}
+	};
+}
+/** canonical forward → forward 段（title/preview/summary 无 canonical 来源，空兜底）。 */
+function forwardToIncoming(el) {
+	return {
+		type: "forward",
+		data: {
+			forward_id: el.messageIds[0] ?? "",
+			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 段发送暂未支持（P1 接内核转发链路）", "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 = 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 } : {}
+	});
+	const scene = chatTypeToScene(msg.chatType);
+	const time = Math.floor(Number(msg.msgTime) / MS_TO_SEC);
+	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),
+		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 ?? ""
+		}
+	};
+}
+//#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/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({
+		message_scene: z.enum([
+			"friend",
+			"group",
+			"temp"
+		]),
+		peer_id: z.number().int().min(10001),
+		message_seq: z.number().int().min(0)
+	});
+	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://"));
+}
+//#endregion
+//#region src/milky/action/social.ts
+/**
+* Milky 社交类动作（P0）：get_friend_list / get_group_list
+*/
+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) };
+	}
+};
+//#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 个动作）
+*
+* P0 面 = docs/protocols/milky.md §9 P0 清单：get_login_info / get_impl_info /
+* send_private_message / send_group_message / get_message / recall_*_message /
+* get_friend_list / get_group_list。P1 扩面（群管/精华/群文件/好友请求/票据）
+* 往本注册表追加。
+*/
+/** Milky 动作注册表（P0 9 动作）。 */
+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));
+	return registry;
+}
+//#endregion
+//#region src/milky/api.ts
+var MilkyApi = class {
+	msgApi;
+	groupApi;
+	friendApi;
+	profileApi;
+	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.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 段发送转换）。 */
+	uinToUid(uins) {
+		return this.groupApi.uinToUid(uins);
+	}
+	/** uid → uin（事件路径 mention 转换）。 */
+	uidToUin(uids) {
+		return this.groupApi.uidToUin(uids);
+	}
+	/**
+	* 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)
+		};
+	}
+};
+//#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();
+	/** 接收链路登记（一条消息双向写入；重复 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}`;
+	}
+	/** 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;
+	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.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);
+		}));
+	}
+	/** 退订（幂等）。 */
+	unsubscribeAll() {
+		for (const off of this.unsubscribes) off();
+		this.unsubscribes = [];
+	}
+	/** 单条消息：seq 登记 → grayTip→recall / 普通→message_receive（自消息不上报）。 */
+	async handleIncoming(msg) {
+		this.seqIndex.record(msg);
+		if (hasGrayTip(msg)) {
+			const event = await this.buildRecallEvent(msg);
+			if (event !== null) this.broadcastEvent(event);
+			return;
+		}
+		if (String(msg.senderUin) === this.api.self.uin) return;
+		const event = await this.buildMessageReceiveEvent(msg);
+		this.broadcastEvent(event);
+	}
+	/** 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);
+		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);
+	}
+	/** message_recall 组装（非撤回 grayTip 返回 null 静默）。 */
+	async buildRecallEvent(msg) {
+		const uidToUin = await this.resolveOperatorUin(msg);
+		return toMessageRecallEvent(msg, {
+			selfUin: this.api.self.uin,
+			...uidToUin !== void 0 ? { uidToUin } : {}
+		});
+	}
+	/** 撤回操作者 uid → uin（未撤回/转换失败返回 undefined，operator_id 兜底 0）。 */
+	resolveOperatorUin(msg) {
+		const operatorUid = findRevokeOperatorUid(msg);
+		if (operatorUid === void 0) return Promise.resolve(void 0);
+		return this.api.uidToUin([operatorUid]).catch(() => void 0);
+	}
+};
+/** 撤回 grayTip 的操作者 uid（非撤回消息返回 undefined）。 */
+function findRevokeOperatorUid(msg) {
+	const uid = msg.elements.find((el) => el.grayTipElement?.revokeElement !== void 0)?.grayTipElement?.revokeElement?.operatorUid;
+	return uid === void 0 || uid === "" ? void 0 : uid;
+}
+/** 是否含 grayTip 元素（与 OB11 收链路同判据）。 */
+function hasGrayTip(msg) {
+	return msg.elements.some((el) => el.grayTipElement !== void 0);
+}
+//#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