@napuketto/adapter 0.0.1 → 0.0.3

package/dist/onebot11/index.mjs

@@ -1,4 +1,5 @@
 import { a as ActionRegistry, n as BaseProtocolAdapter, r as BaseAction } from "../core-Bj5L8WeZ.mjs";
+import { i as createWsServerSchema, n as collectGrayTipUids, r as createHttpServerSchema, t as forEachRawMessage } from "../raw-message-Du7tvR1D.mjs";
 import { ChatType, GrayTipSubType, GroupApi, GroupNotifyMsgType, NTGroupMemberRole, NTGroupRequestOperateTypes, TicketApi, TipGroupElementType, WebHonorType, kernelError, toCanonicalElements } from "@napuketto/kernel";
 import { z } from "zod";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
@@ -17,6 +18,17 @@ const ob11ErrorCodeMap = {
 	UNKNOWN: 999
 };
 //#endregion
+//#region src/onebot11/action/resolve-uid.ts
+/**
+* OB11 用户 ID 解析（uin → uid，多个动作共用，2026-08-08 克隆合并）
+*/
+/** 解析单个 uin → uid（失败抛 KernelError INVALID_PARAM）。 */
+async function resolveUid(uin, uinToUid) {
+	const uid = (await uinToUid([uin])).get(uin);
+	if (uid === void 0) throw kernelError(`用户 ${uin} 的 uid 解析失败`, "INVALID_PARAM");
+	return uid;
+}
+//#endregion
 //#region src/onebot11/action/friend/delete-friend.ts
 /**
 * delete_friend 动作：删除好友（P2-11 接 kernel FriendApi.deleteFriend）
@@ -33,8 +45,7 @@ var DeleteFriendAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const uid = (await this.deps.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+		const uid = await resolveUid(String(payload.user_id), this.deps.uinToUid);
 		await this.deps.friendApi.deleteFriend(uid);
 		return null;
 	}
@@ -144,8 +155,7 @@ var SendLikeAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const uid = (await this.deps.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+		const uid = await resolveUid(String(payload.user_id), this.deps.uinToUid);
 		await this.deps.profileLikeApi.sendLike(uid, payload.times ?? 1);
 		return null;
 	}
@@ -222,16 +232,10 @@ var SetFriendRemarkAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const uid = await this.resolveUid(payload.user_id);
+		const uid = await resolveUid(String(payload.user_id), this.deps.uinToUid);
 		this.deps.friendApi.setFriendRemark(uid, payload.remark);
 		return null;
 	}
-	/** user_id（uin）→ uid。 */
-	async resolveUid(userId) {
-		const uid = (await this.deps.uinToUid([String(userId)])).get(String(userId));
-		if (uid === void 0) throw kernelError(`用户 ${userId} 的 uid 解析失败`, "INVALID_PARAM");
-		return uid;
-	}
 };
 //#endregion
 //#region src/onebot11/helper/message-unique.ts
@@ -322,15 +326,15 @@ function resolveMsgIdAndPeer(messageId, unique) {
 	};
 }
 //#endregion
-//#region src/onebot11/action/group/delete-essence-msg.ts
+//#region src/onebot11/action/group/set-essence-msg.ts
 /**
-* delete_essence_msg 动作：取消精华消息（P2-10 接 kernel GroupApi.removeGroupEssence）
+* set_essence_msg 动作：设置精华消息（P2-10 接 kernel GroupApi.addGroupEssence）
+*
+* message_id → msgId + peer（MessageUnique 反查，需群消息）→ addGroupEssence。
 */
-const deleteEssenceMsgSchema = z.object({ message_id: z.union([z.number(), z.string()]) });
-/** 取消精华消息（P2-10 接 kernel removeGroupEssence）。 */
-var DeleteEssenceMsgAction = class extends BaseAction {
-	name = "delete_essence_msg";
-	schema = deleteEssenceMsgSchema;
+const setEssenceMsgSchema = z.object({ message_id: z.union([z.number(), z.string()]) });
+/** 精华消息基类（set/delete 共用实现，2026-08-08 克隆合并）。 */
+var EssenceMsgBase = class extends BaseAction {
 	errorCodeMap = ob11ErrorCodeMap;
 	deps;
 	constructor(deps) {
@@ -340,10 +344,32 @@ var DeleteEssenceMsgAction = class extends BaseAction {
 	async _handle(payload) {
 		const { msgId, peer } = resolveMsgIdAndPeer(payload.message_id, this.deps.messageUnique);
 		if (peer.chatType !== ChatType.GROUP) throw kernelError("精华消息仅支持群聊消息", "INVALID_PARAM");
-		await this.deps.groupApi.removeGroupEssence(peer.peerUid, msgId);
+		await this.operate(peer.peerUid, msgId);
 		return null;
 	}
 };
+/** 设置精华消息（P2-10 接 kernel addGroupEssence）。 */
+var SetEssenceMsgAction = class extends EssenceMsgBase {
+	name = "set_essence_msg";
+	schema = setEssenceMsgSchema;
+	async operate(groupCode, msgId) {
+		await this.deps.groupApi.addGroupEssence(groupCode, msgId);
+	}
+};
+//#endregion
+//#region src/onebot11/action/group/delete-essence-msg.ts
+/**
+* delete_essence_msg 动作：取消精华消息（P2-10 接 kernel GroupApi.removeGroupEssence）
+*/
+const deleteEssenceMsgSchema = z.object({ message_id: z.union([z.number(), z.string()]) });
+/** 取消精华消息（P2-10 接 kernel removeGroupEssence）。 */
+var DeleteEssenceMsgAction = class extends EssenceMsgBase {
+	name = "delete_essence_msg";
+	schema = deleteEssenceMsgSchema;
+	async operate(groupCode, msgId) {
+		await this.deps.groupApi.removeGroupEssence(groupCode, msgId);
+	}
+};
 //#endregion
 //#region src/onebot11/action/group/get-essence-msg-list.ts
 const getEssenceMsgListSchema = z.object({ group_id: z.number() });
@@ -1020,31 +1046,6 @@ function toGroupFolderInfo(folder) {
 	};
 }
 //#endregion
-//#region src/onebot11/action/group/set-essence-msg.ts
-/**
-* set_essence_msg 动作：设置精华消息（P2-10 接 kernel GroupApi.addGroupEssence）
-*
-* message_id → msgId + peer（MessageUnique 反查，需群消息）→ addGroupEssence。
-*/
-const setEssenceMsgSchema = z.object({ message_id: z.union([z.number(), z.string()]) });
-/** 设置精华消息（P2-10 接 kernel addGroupEssence）。 */
-var SetEssenceMsgAction = class extends BaseAction {
-	name = "set_essence_msg";
-	schema = setEssenceMsgSchema;
-	errorCodeMap = ob11ErrorCodeMap;
-	deps;
-	constructor(deps) {
-		super();
-		this.deps = deps;
-	}
-	async _handle(payload) {
-		const { msgId, peer } = resolveMsgIdAndPeer(payload.message_id, this.deps.messageUnique);
-		if (peer.chatType !== ChatType.GROUP) throw kernelError("精华消息仅支持群聊消息", "INVALID_PARAM");
-		await this.deps.groupApi.addGroupEssence(peer.peerUid, msgId);
-		return null;
-	}
-};
-//#endregion
 //#region src/onebot11/action/group/set-group-add-request.ts
 /**
 * set_group_add_request 动作：处理加群请求（P2-13 接 kernel GroupNotifyApi）
@@ -1110,8 +1111,7 @@ var SetGroupAdminAction = class extends BaseAction {
 		this.groupApi = groupApi;
 	}
 	async _handle(payload) {
-		const uid = (await this.groupApi.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+		const uid = await resolveUid(String(payload.user_id), (uins) => this.groupApi.uinToUid(uins));
 		let role = NTGroupMemberRole.MEMBER;
 		if (payload.enable) role = NTGroupMemberRole.ADMIN;
 		this.groupApi.setMemberRole(String(payload.group_id), uid, role);
@@ -1120,11 +1120,6 @@ var SetGroupAdminAction = class extends BaseAction {
 };
 //#endregion
 //#region src/onebot11/action/group/set-group-ban.ts
-/**
-* set_group_ban 动作：群组单人禁言（P2-10 接 kernel GroupApi.setMemberShutUp）
-*
-* duration 秒（0 解除禁言）；user_id → uinToUid。
-*/
 const setGroupBanSchema = z.object({
 	group_id: z.number(),
 	user_id: z.number(),
@@ -1142,8 +1137,7 @@ var SetGroupBanAction = class extends BaseAction {
 		this.groupApi = groupApi;
 	}
 	async _handle(payload) {
-		const uid = (await this.groupApi.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+		const uid = await resolveUid(String(payload.user_id), (uins) => this.groupApi.uinToUid(uins));
 		await this.groupApi.setMemberShutUp(String(payload.group_id), [{
 			uid,
 			duration: payload.duration
@@ -1153,9 +1147,6 @@ var SetGroupBanAction = class extends BaseAction {
 };
 //#endregion
 //#region src/onebot11/action/group/set-group-card.ts
-/**
-* set_group_card 动作：设置群名片（P2-10 接 kernel GroupApi.setMemberCardName）
-*/
 const setGroupCardSchema = z.object({
 	group_id: z.number(),
 	user_id: z.number(),
@@ -1173,8 +1164,7 @@ var SetGroupCardAction = class extends BaseAction {
 		this.groupApi = groupApi;
 	}
 	async _handle(payload) {
-		const uid = (await this.groupApi.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+		const uid = await resolveUid(String(payload.user_id), (uins) => this.groupApi.uinToUid(uins));
 		this.groupApi.setMemberCardName(String(payload.group_id), uid, payload.card);
 		return null;
 	}
@@ -1331,20 +1321,14 @@ var FetchPttTextAction = class extends BaseAction {
 	}
 };
 //#endregion
-//#region src/onebot11/action/message/forward-single-msg.ts
+//#region src/onebot11/action/message/resolve-peer.ts
 /**
-* forward_group_single_msg / forward_friend_single_msg 动作：单条转发（P2-12）
+* OB11 目标 Peer 解析 / 单条消息拉取（多个动作共用，2026-08-08 克隆合并）
 *
-* message_id 反查源 msgId + peer；group_id/user_id 为目标 →
-* MsgApi.forwardSingleMessage(srcPeer, [msgId], dstPeer)。
+* group_id 直通（群消息 peerUid = 群号）；user_id 经 uin→uid 解析。
 */
-const forwardSingleMsgSchema = z.object({
-	message_id: z.union([z.number(), z.string()]),
-	group_id: z.number().optional(),
-	user_id: z.number().optional()
-});
 /** 解析目标 Peer（group_id 直通；user_id 经 uin→uid）。 */
-async function resolveTargetPeer(payload, deps) {
+async function resolveTargetPeer(payload, deps, missingHint) {
 	if (payload.group_id !== void 0) return {
 		chatType: ChatType.GROUP,
 		peerUid: String(payload.group_id)
@@ -1357,8 +1341,35 @@ async function resolveTargetPeer(payload, deps) {
 			peerUid: uid
 		};
 	}
-	throw kernelError("单条转发需要 group_id 或 user_id", "INVALID_PARAM");
+	throw kernelError(missingHint, "INVALID_PARAM");
+}
+/**
+* 按 message_id（OB11 int32 或 NT msgId）拉取单条消息。
+* 消息不存在/已被撤回 → 抛 KernelError NOT_FOUND。
+*/
+async function fetchMsgById(messageId, messageUnique, msgApi) {
+	const { msgId, peer } = resolveMsgIdAndPeer(messageId, messageUnique);
+	const [msg] = await msgApi.fetchMsgsByMsgId(peer, [msgId]);
+	if (msg === void 0) throw kernelError(`消息 ${messageId} 不存在或已被撤回`, "NOT_FOUND");
+	return {
+		msg,
+		peer,
+		msgId
+	};
 }
+//#endregion
+//#region src/onebot11/action/message/forward-single-msg.ts
+/**
+* forward_group_single_msg / forward_friend_single_msg 动作：单条转发（P2-12）
+*
+* message_id 反查源 msgId + peer；group_id/user_id 为目标 →
+* MsgApi.forwardSingleMessage(srcPeer, [msgId], dstPeer)。
+*/
+const forwardSingleMsgSchema = z.object({
+	message_id: z.union([z.number(), z.string()]),
+	group_id: z.number().optional(),
+	user_id: z.number().optional()
+});
 /** 单条转发基类（两个动作共用实现）。 */
 var ForwardSingleMsgBase = class extends BaseAction {
 	errorCodeMap = ob11ErrorCodeMap;
@@ -1369,7 +1380,7 @@ var ForwardSingleMsgBase = class extends BaseAction {
 	}
 	async _handle(payload) {
 		const { msgId, peer: sourcePeer } = resolveMsgIdAndPeer(payload.message_id, this.deps.messageUnique);
-		const dstPeer = await resolveTargetPeer(payload, this.deps);
+		const dstPeer = await resolveTargetPeer(payload, this.deps, "单条转发需要 group_id 或 user_id");
 		await this.deps.msgApi.forwardSingleMessage(sourcePeer, [msgId], dstPeer);
 		return null;
 	}
@@ -1385,90 +1396,7 @@ var ForwardFriendSingleMsgAction = class extends ForwardSingleMsgBase {
 	schema = forwardSingleMsgSchema;
 };
 //#endregion
-//#region src/onebot11/helper/config.ts
-/**
-* OneBot 11 协议配置（zod schema，归属本包，ADR-012）
-* 协议配置 schema 在各自协议包，kernel 只提供 ConfigBase 基类。
-*
-* 2026-08-07 多实例化（P2-18）：对齐 NapCat——httpServers / httpPostUrls / wsServers /
-* wsReverseUrls 四个数组实例（每实例可覆盖全局 token）；旧单对象字段 http/httpPost/ws/
-* wsReverse 废弃（zod strip 静默忽略，不兼容迁移）。
-*/
-/** HTTP 反向服务器默认端口。 */
-const DEFAULT_HTTP_PORT = 3e3;
-/** 反向 WS server 默认端口。 */
-const DEFAULT_WS_PORT = 3001;
-/** 心跳 meta 事件默认间隔（毫秒）。 */
-const DEFAULT_HEARTBEAT_INTERVAL_MS = 3e3;
-/** WS 传输 ping 默认间隔（毫秒）。 */
-const DEFAULT_WS_HEARTBEAT_MS = 3e4;
-/** WS 反向断线重连默认延迟（毫秒）。 */
-const DEFAULT_RECONNECT_DELAY_MS = 5e3;
-/** 消息内容格式（NapCat messagePostFormat）。 */
-const MESSAGE_FORMATS = ["array", "string"];
-/** HTTP 反向服务器实例（第三方 POST 指令入口）。 */
-const httpServerSchema = z.object({
-	enabled: z.boolean().default(false),
-	host: z.string().default("127.0.0.1"),
-	port: z.number().int().default(DEFAULT_HTTP_PORT),
-	/** 实例级 token，覆盖全局 token（缺省继承全局）。 */
-	token: z.string().optional()
-});
-/** HTTP 正向上报实例（Webhook 事件推送）。 */
-const httpPostSchema = z.object({
-	enabled: z.boolean().default(false),
-	url: z.string().optional(),
-	/** 实例级 token，覆盖全局 token（缺省继承全局）。 */
-	token: z.string().optional(),
-	/** 上报超时（毫秒），缺省不超时。 */
-	timeoutMs: z.number().int().optional()
-});
-/** 反向 WS server 实例（第三方 WS 连入）。 */
-const wsServerSchema = z.object({
-	enabled: z.boolean().default(false),
-	host: z.string().default("127.0.0.1"),
-	port: z.number().int().default(DEFAULT_WS_PORT),
-	/** 实例级 token，覆盖全局 token（缺省继承全局）。 */
-	token: z.string().optional(),
-	/** WS ping 间隔（毫秒）。 */
-	heartbeatInterval: z.number().int().default(DEFAULT_WS_HEARTBEAT_MS)
-});
-/** 正向 WS client 实例（主动连接第三方，双向）。 */
-const wsReverseSchema = z.object({
-	enabled: z.boolean().default(false),
-	url: z.string().optional(),
-	/** 实例级 token，覆盖全局 token（缺省继承全局）。 */
-	token: z.string().optional(),
-	/** 断线重连延迟（毫秒）。 */
-	reconnectDelayMs: z.number().int().default(DEFAULT_RECONNECT_DELAY_MS),
-	/** 最大重连次数（缺省无限）。 */
-	maxReconnectAttempts: z.number().int().optional(),
-	/** wss:// 是否校验证书（自签证书场景设 false，对齐 NapCat enableSelfSigned）。 */
-	rejectUnauthorized: z.boolean().default(true),
-	/** WS ping 间隔（毫秒）。 */
-	heartbeatInterval: z.number().int().default(DEFAULT_WS_HEARTBEAT_MS)
-});
-/** OB11 配置 schema。 */
-const ob11ConfigSchema = z.object({
-	/** 鉴权 token（全局默认，实例未指定时继承）。 */
-	token: z.string().optional(),
-	/** 心跳 meta 事件间隔（毫秒），0 关闭心跳。 */
-	heartbeatInterval: z.number().int().default(DEFAULT_HEARTBEAT_INTERVAL_MS),
-	/** 是否上报机器人自己发的消息（缺省 false = OB11 规范行为）。 */
-	reportSelfMessage: z.boolean().default(false),
-	/** 消息内容格式：array = 消息段数组（标准），string = CQ 码字符串。 */
-	messagePostFormat: z.enum(MESSAGE_FORMATS).default("array"),
-	/** HTTP 反向服务器列表。 */
-	httpServers: z.array(httpServerSchema).default([]),
-	/** HTTP 正向上报列表。 */
-	httpPostUrls: z.array(httpPostSchema).default([]),
-	/** 反向 WS server 列表。 */
-	wsServers: z.array(wsServerSchema).default([]),
-	/** 正向 WS client 列表。 */
-	wsReverseUrls: z.array(wsReverseSchema).default([])
-});
-//#endregion
-//#region src/onebot11/helper/cqcode.ts
+//#region src/onebot11/helper/codec/cqcode.ts
 /**
 * CQ 码编解码（OneBot 11 消息段序列化格式）
 *
@@ -1537,7 +1465,7 @@ function serializeCqParts(parts) {
 	return out;
 }
 //#endregion
-//#region src/onebot11/helper/data.ts
+//#region src/onebot11/helper/codec/segment.ts
 /** OB11 媒体段 data（image/record/video 共用，url 可选）。 */
 function mediaData(file, url) {
 	const data = { file };
@@ -1573,80 +1501,95 @@ function rawToString(raw) {
 	if (typeof raw === "string") return raw;
 	return JSON.stringify(raw);
 }
-/** canonical 元素 → OB11 segment（null = OB11 无法表达，跳过）。 */
-function canonicalToSegment(el) {
-	if (el.type === "text") return {
+/** canonical 元素 → OB11 segment 转换器（键 = canonical type，判别字段收窄）。 */
+const CANONICAL_TO_SEGMENT = {
+	text: (el) => ({
 		type: "text",
 		data: { text: el.text }
-	};
-	if (el.type === "at") return {
+	}),
+	at: (el) => ({
 		type: "at",
 		data: atData(el.target, el.display)
-	};
-	if (el.type === "image") return {
+	}),
+	image: (el) => ({
 		type: "image",
 		data: mediaData(el.path, el.url)
-	};
-	if (el.type === "face") return {
+	}),
+	face: (el) => ({
 		type: "face",
 		data: { id: el.id }
-	};
-	if (el.type === "voice") return {
+	}),
+	voice: (el) => ({
 		type: "record",
 		data: mediaData(el.path, el.url)
-	};
-	if (el.type === "video") return {
+	}),
+	video: (el) => ({
 		type: "video",
 		data: mediaData(el.path, el.url)
-	};
-	if (el.type === "reply") return {
+	}),
+	reply: (el) => ({
 		type: "reply",
 		data: { id: el.messageId }
-	};
-	if (el.type === "forward") return {
+	}),
+	forward: (el) => ({
 		type: "forward",
 		data: { id: el.messageIds[0] ?? "" }
-	};
-	if (el.type === "json") return {
+	}),
+	json: (el) => ({
 		type: "json",
 		data: { data: rawToString(el.raw) }
-	};
-	if (el.type === "xml") return {
+	}),
+	xml: (el) => ({
 		type: "xml",
 		data: { data: rawToString(el.raw) }
-	};
-	return null;
+	})
+};
+/** canonical 元素 → OB11 segment（null = OB11 无法表达，跳过）。 */
+function canonicalToSegment(el) {
+	const builder = CANONICAL_TO_SEGMENT[el.type];
+	return builder === void 0 ? null : builder(el);
 }
-/** OB11 segment → canonical 元素。 */
-function segmentToCanonical(seg) {
-	if (seg.type === "text" || seg.type === "string") return {
+/** OB11 segment → canonical 元素转换器（键 = segment type）。 */
+const SEGMENT_TO_CANONICAL = {
+	text: (seg) => ({
 		type: "text",
 		text: seg.data.text
-	};
-	if (seg.type === "at") return canonicalAt(seg.data.qq, seg.data.name);
-	if (seg.type === "face") return {
+	}),
+	string: (seg) => ({
+		type: "text",
+		text: seg.data.text
+	}),
+	at: (seg) => canonicalAt(seg.data.qq, seg.data.name),
+	face: (seg) => ({
 		type: "face",
 		id: seg.data.id
-	};
-	if (seg.type === "image") return canonicalMedia("image", seg.data.file, seg.data.url);
-	if (seg.type === "record") return canonicalMedia("voice", seg.data.file, seg.data.url);
-	if (seg.type === "video") return canonicalMedia("video", seg.data.file, seg.data.url);
-	if (seg.type === "reply") return {
+	}),
+	image: (seg) => canonicalMedia("image", seg.data.file, seg.data.url),
+	record: (seg) => canonicalMedia("voice", seg.data.file, seg.data.url),
+	video: (seg) => canonicalMedia("video", seg.data.file, seg.data.url),
+	reply: (seg) => ({
 		type: "reply",
 		messageId: seg.data.id
-	};
-	if (seg.type === "forward") return {
+	}),
+	forward: (seg) => ({
 		type: "forward",
 		messageIds: [seg.data.id]
-	};
-	if (seg.type === "json") return {
+	}),
+	json: (seg) => ({
 		type: "json",
 		raw: seg.data.data
-	};
-	return {
+	}),
+	xml: (seg) => ({
 		type: "xml",
 		raw: seg.data.data
-	};
+	})
+};
+/** OB11 segment → canonical 元素（未知 type 兜底按 xml 处理，保持既有行为）。 */
+function segmentToCanonical(seg) {
+	const builder = SEGMENT_TO_CANONICAL[seg.type];
+	if (builder !== void 0) return builder(seg);
+	const xmlBuilder = SEGMENT_TO_CANONICAL["xml"];
+	return xmlBuilder === void 0 ? null : xmlBuilder(seg);
 }
 /** 已知 CQ 类型 → segment 构造器。 */
 const CQ_SEGMENT_BUILDERS = {
@@ -1700,6 +1643,86 @@ function cqCodeToSegment(code) {
 	};
 	return builder(code.params);
 }
+/** OB11 segment 数组 → CQ 码字符串（text 段转义拼接，特殊段编码）。 */
+function segmentsToCqMessage(segments) {
+	let out = "";
+	for (const seg of segments) if (seg.type === "text" || seg.type === "string") out += escapeCqText(seg.data.text);
+	else out += encodeCqCode(seg.type, seg.data);
+	return out;
+}
+//#endregion
+//#region src/onebot11/helper/config.ts
+/**
+* OneBot 11 协议配置（zod schema，归属本包，ADR-012）
+* 协议配置 schema 在各自协议包，kernel 只提供 ConfigBase 基类。
+*
+* 2026-08-07 多实例化（P2-18）：对齐 NapCat——httpServers / httpPostUrls / wsServers /
+* wsReverseUrls 四个数组实例（每实例可覆盖全局 token）；旧单对象字段 http/httpPost/ws/
+* wsReverse 废弃（zod strip 静默忽略，不兼容迁移）。
+*/
+/** HTTP 反向服务器默认端口。 */
+const DEFAULT_HTTP_PORT = 3e3;
+/** 反向 WS server 默认端口。 */
+const DEFAULT_WS_PORT = 3001;
+/** 心跳 meta 事件默认间隔（毫秒）。 */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 3e3;
+/** WS 传输 ping 默认间隔（毫秒）。 */
+const DEFAULT_WS_HEARTBEAT_MS = 3e4;
+/** WS 反向断线重连默认延迟（毫秒）。 */
+const DEFAULT_RECONNECT_DELAY_MS = 5e3;
+/** 消息内容格式（NapCat messagePostFormat）。 */
+const MESSAGE_FORMATS = ["array", "string"];
+/** HTTP 反向服务器实例（第三方 POST 指令入口）。 */
+const httpServerSchema = createHttpServerSchema(DEFAULT_HTTP_PORT);
+/** HTTP 正向上报实例（Webhook 事件推送）。 */
+const httpPostSchema = z.object({
+	enabled: z.boolean().default(false),
+	url: z.string().optional(),
+	/** 实例级 token，覆盖全局 token（缺省继承全局）。 */
+	token: z.string().optional(),
+	/** 上报超时（毫秒），缺省不超时。 */
+	timeoutMs: z.number().int().optional()
+});
+/** 反向 WS server 实例（第三方 WS 连入，带 WS ping 间隔扩展字段）。 */
+const wsServerSchema = createWsServerSchema(DEFAULT_WS_PORT).extend({ 
+/** WS ping 间隔（毫秒）。 */
+heartbeatInterval: z.number().int().default(DEFAULT_WS_HEARTBEAT_MS) });
+/** 正向 WS client 实例（主动连接第三方，双向）。 */
+const wsReverseSchema = z.object({
+	enabled: z.boolean().default(false),
+	url: z.string().optional(),
+	/** 实例级 token，覆盖全局 token（缺省继承全局）。 */
+	token: z.string().optional(),
+	/** 断线重连延迟（毫秒）。 */
+	reconnectDelayMs: z.number().int().default(DEFAULT_RECONNECT_DELAY_MS),
+	/** 最大重连次数（缺省无限）。 */
+	maxReconnectAttempts: z.number().int().optional(),
+	/** wss:// 是否校验证书（自签证书场景设 false，对齐 NapCat enableSelfSigned）。 */
+	rejectUnauthorized: z.boolean().default(true),
+	/** WS ping 间隔（毫秒）。 */
+	heartbeatInterval: z.number().int().default(DEFAULT_WS_HEARTBEAT_MS)
+});
+/** OB11 配置 schema。 */
+const ob11ConfigSchema = z.object({
+	/** 鉴权 token（全局默认，实例未指定时继承）。 */
+	token: z.string().optional(),
+	/** 心跳 meta 事件间隔（毫秒），0 关闭心跳。 */
+	heartbeatInterval: z.number().int().default(DEFAULT_HEARTBEAT_INTERVAL_MS),
+	/** 是否上报机器人自己发的消息（缺省 false = OB11 规范行为）。 */
+	reportSelfMessage: z.boolean().default(false),
+	/** 消息内容格式：array = 消息段数组（标准），string = CQ 码字符串。 */
+	messagePostFormat: z.enum(MESSAGE_FORMATS).default("array"),
+	/** HTTP 反向服务器列表。 */
+	httpServers: z.array(httpServerSchema).default([]),
+	/** HTTP 正向上报列表。 */
+	httpPostUrls: z.array(httpPostSchema).default([]),
+	/** 反向 WS server 列表。 */
+	wsServers: z.array(wsServerSchema).default([]),
+	/** 正向 WS client 列表。 */
+	wsReverseUrls: z.array(wsReverseSchema).default([])
+});
+//#endregion
+//#region src/onebot11/helper/data.ts
 /** canonical 元素数组 → OB11 segment 数组（无法表达的元素静默跳过）。 */
 function canonicalToSegments(elements) {
 	const segments = [];
@@ -1718,13 +1741,6 @@ function segmentsToCanonical(segments) {
 	}
 	return elements;
 }
-/** OB11 segment 数组 → CQ 码字符串（text 段转义拼接，特殊段编码）。 */
-function segmentsToCqMessage(segments) {
-	let out = "";
-	for (const seg of segments) if (seg.type === "text" || seg.type === "string") out += escapeCqText(seg.data.text);
-	else out += encodeCqCode(seg.type, seg.data);
-	return out;
-}
 /**
 * 收集 canonical 元素里需要转换的 at uid / reply NT msgId（接收方向）。
 * 调用方据此批量 uidToUin（一次异步调用），避免逐元素查询。
@@ -1878,23 +1894,6 @@ const MS_TO_SEC$2 = 1e3;
 function hasGrayTip(msg) {
 	return msg.elements.some((el) => el.grayTipElement !== void 0);
 }
-/** 收集 grayTip 涉及的 uid（批量 uidToUin 用）。 */
-function collectGrayTipUids(msg) {
-	const uids = /* @__PURE__ */ new Set();
-	for (const el of msg.elements) {
-		const g = el.grayTipElement;
-		if (g === void 0) continue;
-		const revoke = g.revokeElement;
-		if (revoke?.operatorUid !== void 0 && revoke.operatorUid !== "") uids.add(revoke.operatorUid);
-		const grp = g.groupElement;
-		if (grp === void 0) continue;
-		if (grp.memberUid !== void 0 && grp.memberUid !== "") uids.add(grp.memberUid);
-		if (grp.adminUid !== void 0 && grp.adminUid !== "") uids.add(grp.adminUid);
-		if (grp.shutUp?.admin?.uid !== void 0 && grp.shutUp.admin.uid !== "") uids.add(grp.shutUp.admin.uid);
-		if (grp.shutUp?.member?.uid !== void 0 && grp.shutUp.member.uid !== "") uids.add(grp.shutUp.member.uid);
-	}
-	return [...uids];
-}
 /** uid → uin（上下文映射缺省退化为 uid）。 */
 function toUin(uid, ctx) {
 	const uin = ctx.uidToUin.get(uid);
@@ -1925,59 +1924,79 @@ function toRecall(msg, g, ctx) {
 function toGroupChange(msg, g, ctx) {
 	const grp = g?.groupElement;
 	if (grp === void 0 || grp.type === void 0) return null;
-	const groupId = Number(msg.peerUid);
-	const time = Math.floor(Number(msg.msgTime) / MS_TO_SEC$2);
-	const selfId = Number(ctx.selfUin);
-	const memberUid = grp.memberUid ?? "";
-	const adminUid = grp.adminUid ?? "";
+	const common = {
+		time: Math.floor(Number(msg.msgTime) / MS_TO_SEC$2),
+		selfId: Number(ctx.selfUin),
+		groupId: Number(msg.peerUid),
+		memberUid: grp.memberUid ?? "",
+		adminUid: grp.adminUid ?? ""
+	};
 	switch (grp.type) {
-		case TipGroupElementType.MEMBER_ADD: return {
-			time,
-			self_id: selfId,
-			post_type: "notice",
-			notice_type: "group_increase",
-			sub_type: adminUid === memberUid ? "approve" : "invite",
-			group_id: groupId,
-			operator_id: toUin(adminUid, ctx),
-			user_id: toUin(memberUid, ctx)
-		};
-		case TipGroupElementType.QUIT: return {
-			time,
-			self_id: selfId,
-			post_type: "notice",
-			notice_type: "group_decrease",
-			sub_type: "leave",
-			group_id: groupId,
-			operator_id: toUin(adminUid, ctx),
-			user_id: toUin(memberUid, ctx)
-		};
+		case TipGroupElementType.MEMBER_ADD: return toMemberAdd(common, ctx);
+		case TipGroupElementType.QUIT: return toQuit(common, ctx);
 		case TipGroupElementType.BLOCK:
-		case TipGroupElementType.UNBLOCK: return {
-			time,
-			self_id: selfId,
-			post_type: "notice",
-			notice_type: "group_admin",
-			sub_type: grp.type === TipGroupElementType.BLOCK ? "set" : "unset",
-			group_id: groupId,
-			user_id: toUin(memberUid === "" ? adminUid : memberUid, ctx)
-		};
-		case TipGroupElementType.SHUT_UP: {
-			const shutUp = grp.shutUp;
-			return {
-				time,
-				self_id: selfId,
-				post_type: "notice",
-				notice_type: "group_ban",
-				sub_type: Number(shutUp?.duration ?? 0) > 0 ? "ban" : "lift_ban",
-				group_id: groupId,
-				operator_id: toUin(shutUp?.admin?.uid ?? adminUid, ctx),
-				user_id: toUin(shutUp?.member?.uid ?? memberUid, ctx),
-				duration: Number(shutUp?.duration ?? 0)
-			};
-		}
+		case TipGroupElementType.UNBLOCK: return toAdminChange(common, grp, ctx);
+		case TipGroupElementType.SHUT_UP: return toBan(common, grp, ctx);
 		default: return null;
 	}
 }
+/** 群成员增加（approve=管理员操作 / invite=普通邀请）。 */
+function toMemberAdd(common, ctx) {
+	const { time, selfId, groupId, memberUid, adminUid } = common;
+	return {
+		time,
+		self_id: selfId,
+		post_type: "notice",
+		notice_type: "group_increase",
+		sub_type: adminUid === memberUid ? "approve" : "invite",
+		group_id: groupId,
+		operator_id: toUin(adminUid, ctx),
+		user_id: toUin(memberUid, ctx)
+	};
+}
+/** 群成员退出（leave）。 */
+function toQuit(common, ctx) {
+	const { time, selfId, groupId, memberUid, adminUid } = common;
+	return {
+		time,
+		self_id: selfId,
+		post_type: "notice",
+		notice_type: "group_decrease",
+		sub_type: "leave",
+		group_id: groupId,
+		operator_id: toUin(adminUid, ctx),
+		user_id: toUin(memberUid, ctx)
+	};
+}
+/** 管理员变更（BLOCK=set / UNBLOCK=unset）。 */
+function toAdminChange(common, grp, ctx) {
+	const { time, selfId, groupId, memberUid, adminUid } = common;
+	return {
+		time,
+		self_id: selfId,
+		post_type: "notice",
+		notice_type: "group_admin",
+		sub_type: grp.type === TipGroupElementType.BLOCK ? "set" : "unset",
+		group_id: groupId,
+		user_id: toUin(memberUid === "" ? adminUid : memberUid, ctx)
+	};
+}
+/** 禁言（duration>0=ban / 否则 lift_ban）。 */
+function toBan(common, grp, ctx) {
+	const { time, selfId, groupId, adminUid, memberUid } = common;
+	const shutUp = grp.shutUp;
+	return {
+		time,
+		self_id: selfId,
+		post_type: "notice",
+		notice_type: "group_ban",
+		sub_type: Number(shutUp?.duration ?? 0) > 0 ? "ban" : "lift_ban",
+		group_id: groupId,
+		operator_id: toUin(shutUp?.admin?.uid ?? adminUid, ctx),
+		user_id: toUin(shutUp?.member?.uid ?? memberUid, ctx),
+		duration: Number(shutUp?.duration ?? 0)
+	};
+}
 /** RawMessage → OB11 notice 事件（无 grayTip 返回 null）。 */
 function toOb11NoticeEvent(msg, ctx) {
 	for (const el of msg.elements) {
@@ -2024,6 +2043,48 @@ var GetForwardMsgAction = class extends BaseAction {
 		return { messages: (await this.deps.msgApi.fetchForwardMessage(peer, msgId)).map((msg) => toOb11MessageInfo(msg, this.deps.messageUnique)) };
 	}
 };
+/** 历史消息公共参数（message_seq / count / 反向排序）。 */
+const msgHistoryParamsSchema = {
+	/** 起始消息序号（message_seq，缺省从最新拉）。 */
+	message_seq: z.union([z.number(), z.string()]).optional(),
+	count: z.number().default(20),
+	/** 是否反向排序（NapCat 扩展）。 */
+	reverse_order: z.boolean().optional(),
+	reverseOrder: z.boolean().optional()
+};
+/** 解析 message_seq → 起始 msgId（int32 经 MessageUnique 反查，否则原样透传）。 */
+function resolveStartMsgId(messageSeq, messageUnique) {
+	if (messageSeq === void 0) return;
+	const raw = String(messageSeq);
+	const shortId = Number(raw);
+	if (Number.isFinite(shortId)) return messageUnique.getMsgId(shortId) ?? raw;
+	return raw;
+}
+/**
+* 拉取历史消息并翻译为 OB11 消息信息数组。
+* 收集全部消息 at uid → 一次批量 uidToUin → 上下文注入（P2-19）。
+*/
+async function fetchAndTranslateHistory(peer, messageSeq, count, deps) {
+	const startMsgId = resolveStartMsgId(messageSeq, deps.messageUnique);
+	const opts = { count };
+	if (startMsgId !== void 0) opts.msgId = startMsgId;
+	const msgs = await deps.msgApi.fetchMessages(peer, opts);
+	if (msgs.length === 0) throw kernelError(`消息 ${messageSeq ?? "0"} 不存在`, "NOT_FOUND");
+	const atUids = /* @__PURE__ */ new Set();
+	for (const m of msgs) {
+		const { atUids: uids } = collectReceiveNeeds(toCanonicalElements(m));
+		for (const u of uids) atUids.add(u);
+	}
+	let uidToUin;
+	if (atUids.size > 0) try {
+		uidToUin = await deps.uidToUin([...atUids]);
+	} catch {}
+	const ctx = {
+		...uidToUin !== void 0 ? { uidToUin } : {},
+		msgIdToOb11Id: (m) => deps.messageUnique.getMessageId(m)
+	};
+	return { messages: msgs.map((msg) => toOb11MessageInfo(msg, deps.messageUnique, ctx)) };
+}
 //#endregion
 //#region src/onebot11/action/message/get-friend-msg-history.ts
 /**
@@ -2033,10 +2094,7 @@ var GetForwardMsgAction = class extends BaseAction {
 */
 const getFriendMsgHistorySchema = z.object({
 	user_id: z.number(),
-	message_seq: z.union([z.number(), z.string()]).optional(),
-	count: z.number().default(20),
-	reverse_order: z.boolean().optional(),
-	reverseOrder: z.boolean().optional()
+	...msgHistoryParamsSchema
 });
 /** 获取私聊历史消息（P2-10 接 kernel fetchMessages）。 */
 var GetFriendMsgHistoryAction = class extends BaseAction {
@@ -2049,37 +2107,11 @@ var GetFriendMsgHistoryAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const uid = (await this.deps.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
-		const peer = {
+		const uid = await resolveUid(String(payload.user_id), this.deps.uinToUid);
+		return await fetchAndTranslateHistory({
 			chatType: ChatType.C2C,
 			peerUid: uid
-		};
-		let startMsgId;
-		if (payload.message_seq !== void 0) {
-			const raw = String(payload.message_seq);
-			const shortId = Number(raw);
-			if (Number.isFinite(shortId)) startMsgId = this.deps.messageUnique.getMsgId(shortId);
-			startMsgId ??= raw;
-		}
-		const opts = { count: payload.count };
-		if (startMsgId !== void 0) opts.msgId = startMsgId;
-		const msgs = await this.deps.msgApi.fetchMessages(peer, opts);
-		if (msgs.length === 0) throw kernelError(`消息 ${payload.message_seq ?? "0"} 不存在`, "NOT_FOUND");
-		const atUids = /* @__PURE__ */ new Set();
-		for (const m of msgs) {
-			const { atUids: uids } = collectReceiveNeeds(toCanonicalElements(m));
-			for (const u of uids) atUids.add(u);
-		}
-		let uidToUin;
-		if (atUids.size > 0) try {
-			uidToUin = await this.deps.uidToUin([...atUids]);
-		} catch {}
-		const ctx = {
-			...uidToUin !== void 0 ? { uidToUin } : {},
-			msgIdToOb11Id: (m) => this.deps.messageUnique.getMessageId(m)
-		};
-		return { messages: msgs.map((msg) => toOb11MessageInfo(msg, this.deps.messageUnique, ctx)) };
+		}, payload.message_seq, payload.count, this.deps);
 	}
 };
 //#endregion
@@ -2092,12 +2124,7 @@ var GetFriendMsgHistoryAction = class extends BaseAction {
 */
 const getGroupMsgHistorySchema = z.object({
 	group_id: z.number(),
-	/** 起始消息序号（message_seq，缺省从最新拉）。 */
-	message_seq: z.union([z.number(), z.string()]).optional(),
-	count: z.number().default(20),
-	/** 是否反向排序（NapCat 扩展）。 */
-	reverse_order: z.boolean().optional(),
-	reverseOrder: z.boolean().optional()
+	...msgHistoryParamsSchema
 });
 /** 获取群历史消息（P2-10 接 kernel fetchMessages）。 */
 var GetGroupMsgHistoryAction = class extends BaseAction {
@@ -2110,35 +2137,10 @@ var GetGroupMsgHistoryAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const peer = {
+		return await fetchAndTranslateHistory({
 			chatType: ChatType.GROUP,
 			peerUid: String(payload.group_id)
-		};
-		let startMsgId;
-		if (payload.message_seq !== void 0) {
-			const raw = String(payload.message_seq);
-			const shortId = Number(raw);
-			if (Number.isFinite(shortId)) startMsgId = this.deps.messageUnique.getMsgId(shortId);
-			startMsgId ??= raw;
-		}
-		const opts = { count: payload.count };
-		if (startMsgId !== void 0) opts.msgId = startMsgId;
-		const msgs = await this.deps.msgApi.fetchMessages(peer, opts);
-		if (msgs.length === 0) throw kernelError(`消息 ${payload.message_seq ?? "0"} 不存在`, "NOT_FOUND");
-		const atUids = /* @__PURE__ */ new Set();
-		for (const m of msgs) {
-			const { atUids: uids } = collectReceiveNeeds(toCanonicalElements(m));
-			for (const u of uids) atUids.add(u);
-		}
-		let uidToUin;
-		if (atUids.size > 0) try {
-			uidToUin = await this.deps.uidToUin([...atUids]);
-		} catch {}
-		const ctx = {
-			...uidToUin !== void 0 ? { uidToUin } : {},
-			msgIdToOb11Id: (m) => this.deps.messageUnique.getMessageId(m)
-		};
-		return { messages: msgs.map((msg) => toOb11MessageInfo(msg, this.deps.messageUnique, ctx)) };
+		}, payload.message_seq, payload.count, this.deps);
 	}
 };
 //#endregion
@@ -2154,19 +2156,38 @@ const getMediaSchema = z.object({
 	file: z.string().optional(),
 	message_id: z.union([z.number(), z.string()]).optional()
 });
+/**
+* 反查消息并提取媒体元素路径。
+* 返回 null = 消息不存在；extract 返回 undefined = 无匹配元素。
+*/
+async function resolveMedia(id, label, deps, extract) {
+	const { msgId, peer } = resolveMsgIdAndPeer(id, deps.messageUnique);
+	const [first] = await deps.msgApi.fetchMsgsByMsgId(peer, [msgId]);
+	if (first === void 0) throw kernelError(`消息 ${id} 不存在或已被撤回`, "NOT_FOUND");
+	for (const el of first.elements) {
+		const found = extract(el);
+		if (found !== void 0) return found;
+	}
+	throw kernelError(`消息 ${id} 不包含${label}`, "NOT_FOUND");
+}
 /** 从消息元素提取媒体路径与 URL（PIC/PTT，纯函数）。 */
 function extractMediaPath(element) {
 	const pic = element.picElement;
 	if (pic !== void 0) {
 		const out = {};
 		const path = pic.sourcePath ?? pic.picPath;
-		if (path !== void 0) out.path = path;
+		if (path !== void 0) out.file = path;
 		if (pic.picUrl !== void 0) out.url = pic.picUrl;
+		if (Object.keys(out).length === 0) return;
 		return out;
 	}
 	const ptt = element.pttElement;
-	if (ptt !== void 0 && ptt.filePath !== void 0) return { path: ptt.filePath };
-	return {};
+	if (ptt !== void 0 && ptt.filePath !== void 0) return { file: ptt.filePath };
+}
+/** 提取语音元素（get_record 用）。 */
+function extractPttPath(element) {
+	const ptt = element.pttElement;
+	if (ptt !== void 0 && ptt.filePath !== void 0) return { file: ptt.filePath };
 }
 /** 获取图片信息（P2-14）。 */
 var GetImageAction = class extends BaseAction {
@@ -2179,28 +2200,12 @@ var GetImageAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	_handle(payload) {
-		return this.resolveMedia(payload, "图片", "get_image");
+		return this.resolve(payload, "图片", "get_image");
 	}
-	/** 反查消息并提取媒体元素路径。 */
-	async resolveMedia(payload, label, actionName) {
+	resolve(payload, label, actionName) {
 		const id = payload.message_id ?? payload.file;
 		if (id === void 0) throw kernelError(`${actionName} 需要 message_id 或 file`, "INVALID_PARAM");
-		const { msgId, peer } = resolveMsgIdAndPeer(id, this.deps.messageUnique);
-		const [first] = await this.deps.msgApi.fetchMsgsByMsgId(peer, [msgId]);
-		if (first === void 0) throw kernelError(`消息 ${id} 不存在或已被撤回`, "NOT_FOUND");
-		let found;
-		for (const el of first.elements) {
-			const media = extractMediaPath(el);
-			if (media.path !== void 0 || media.url !== void 0) {
-				found = media;
-				break;
-			}
-		}
-		if (found === void 0) throw kernelError(`消息 ${id} 不包含${label}`, "NOT_FOUND");
-		const result = {};
-		if (found.path !== void 0) result.file = found.path;
-		if (found.url !== void 0) result.url = found.url;
-		return result;
+		return resolveMedia(id, label, this.deps, extractMediaPath);
 	}
 };
 /** 获取语音信息（P2-14）。 */
@@ -2216,14 +2221,7 @@ var GetRecordAction = class extends BaseAction {
 	async _handle(payload) {
 		const id = payload.message_id ?? payload.file;
 		if (id === void 0) throw kernelError("get_record 需要 message_id 或 file", "INVALID_PARAM");
-		const { msgId, peer } = resolveMsgIdAndPeer(id, this.deps.messageUnique);
-		const [first] = await this.deps.msgApi.fetchMsgsByMsgId(peer, [msgId]);
-		if (first === void 0) throw kernelError(`消息 ${id} 不存在或已被撤回`, "NOT_FOUND");
-		for (const el of first.elements) {
-			const ptt = el.pttElement;
-			if (ptt !== void 0 && ptt.filePath !== void 0) return { file: ptt.filePath };
-		}
-		throw kernelError(`消息 ${id} 不包含语音`, "NOT_FOUND");
+		return await resolveMedia(id, "语音", this.deps, extractPttPath);
 	}
 };
 //#endregion
@@ -2245,9 +2243,7 @@ var GetMsgAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const { msgId, peer } = resolveMsgIdAndPeer(payload.message_id, this.deps.messageUnique);
-		const [msg] = await this.deps.msgApi.fetchMsgsByMsgId(peer, [msgId]);
-		if (msg === void 0) throw kernelError(`消息 ${payload.message_id} 不存在或已被撤回`, "NOT_FOUND");
+		const { msg } = await fetchMsgById(payload.message_id, this.deps.messageUnique, this.deps.msgApi);
 		const { atUids } = collectReceiveNeeds(toCanonicalElements(msg));
 		let uidToUin;
 		if (atUids.length > 0) try {
@@ -2292,8 +2288,7 @@ var MarkMsgAsReadAction = class extends BaseAction {
 			return null;
 		}
 		if (payload.user_id !== void 0) {
-			const uid = (await this.deps.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-			if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+			const uid = await resolveUid(String(payload.user_id), this.deps.uinToUid);
 			await this.deps.msgApi.markRead({
 				chatType: ChatType.C2C,
 				peerUid: uid
@@ -2324,8 +2319,7 @@ var MarkPrivateMsgAsReadAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const uid = (await this.deps.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+		const uid = await resolveUid(String(payload.user_id), this.deps.uinToUid);
 		await this.deps.msgApi.markRead({
 			chatType: ChatType.C2C,
 			peerUid: uid
@@ -2393,6 +2387,14 @@ function resolveSourceMessages(messages, unique) {
 	}
 	return out;
 }
+/** 合并转发发送（群/私聊共用：解析源消息 → 发送 → 映射 message_id）。 */
+async function sendForward(messages, target, deps) {
+	const sources = resolveSourceMessages(messages, deps.messageUnique);
+	const [firstSource] = sources;
+	if (firstSource === void 0) throw kernelError("合并转发需要至少一条可解析的源消息（node.id）", "INVALID_PARAM");
+	const { msgId } = await deps.msgApi.sendForwardMessage(target, firstSource.peer, sources.map((s) => s.msgId));
+	return { message_id: deps.messageUnique.alloc(msgId, target) };
+}
 /** 发送群合并转发（P2-12 接 kernel sendForwardMessage）。 */
 var SendGroupForwardMsgAction = class extends BaseAction {
 	name = "send_group_forward_msg";
@@ -2404,15 +2406,11 @@ var SendGroupForwardMsgAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const sources = resolveSourceMessages(payload.messages, this.deps.messageUnique);
-		const [firstSource] = sources;
-		if (firstSource === void 0) throw kernelError("合并转发需要至少一条可解析的源消息（node.id）", "INVALID_PARAM");
 		const target = {
 			chatType: ChatType.GROUP,
 			peerUid: String(payload.group_id)
 		};
-		const { msgId } = await this.deps.msgApi.sendForwardMessage(target, firstSource.peer, sources.map((s) => s.msgId));
-		return { message_id: this.deps.messageUnique.alloc(msgId, target) };
+		return await sendForward(payload.messages, target, this.deps);
 	}
 };
 /** 发送私聊合并转发（P2-12）。 */
@@ -2426,31 +2424,16 @@ var SendPrivateForwardMsgAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const sources = resolveSourceMessages(payload.messages, this.deps.messageUnique);
-		const [firstSource] = sources;
-		if (firstSource === void 0) throw kernelError("合并转发需要至少一条可解析的源消息（node.id）", "INVALID_PARAM");
-		const uid = (await this.deps.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+		const uid = await resolveUid(String(payload.user_id), this.deps.uinToUid);
 		const target = {
 			chatType: ChatType.C2C,
 			peerUid: uid
 		};
-		const { msgId } = await this.deps.msgApi.sendForwardMessage(target, firstSource.peer, sources.map((s) => s.msgId));
-		return { message_id: this.deps.messageUnique.alloc(msgId, target) };
+		return await sendForward(payload.messages, target, this.deps);
 	}
 };
 //#endregion
 //#region src/onebot11/action/message/send-msg.ts
-/**
-* send_msg 动作：发送消息（群聊/私聊）+ 共享发送核心 sendOb11Message
-*
-* P2-3 真实化：注入 kernel MsgApi，message 参数（CQ 码字符串或 segment 数组）
-* 翻译为 canonical 元素 → MsgApi.sendMessage → 返回真实 message_id。
-* send_private_msg / send_group_msg 复用 sendOb11Message（P2-10）。
-*
-* 群聊：group_id → Peer{ chatType: GROUP, peerUid: String(group_id) }（群消息 peerUid=群号）。
-* 私聊：user_id 经 uin→uid → Peer{ chatType: C2C, peerUid: uid }。
-*/
 const sendMsgSchema = z.object({
 	message_type: z.enum(["group", "private"]).optional(),
 	user_id: z.number().optional(),
@@ -2458,25 +2441,9 @@ const sendMsgSchema = z.object({
 	message: z.union([z.string(), z.array(z.unknown())]),
 	auto_escape: z.boolean().optional()
 });
-/** 解析目标 Peer（group_id 直通；user_id 经 uin→uid）。 */
-async function resolvePeer(payload, deps) {
-	if (payload.group_id !== void 0) return {
-		chatType: ChatType.GROUP,
-		peerUid: String(payload.group_id)
-	};
-	if (payload.user_id !== void 0) {
-		const uid = (await deps.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
-		return {
-			chatType: ChatType.C2C,
-			peerUid: uid
-		};
-	}
-	throw kernelError("send_msg 需要 group_id 或 user_id", "INVALID_PARAM");
-}
 /** 共享发送核心：解析 Peer → canonical 翻译（含 auto_escape）→ sendMessage → 映射 message_id。 */
 async function sendOb11Message(payload, deps) {
-	const peer = await resolvePeer(payload, deps);
+	const peer = await resolveTargetPeer(payload, deps, "send_msg 需要 group_id 或 user_id");
 	let canonical;
 	if (Array.isArray(payload.message)) canonical = segmentsToCanonical(payload.message);
 	else canonical = cqMessageToCanonical(payload.message);
@@ -2592,8 +2559,7 @@ var SetInputStatusAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const uid = (await this.deps.uinToUid([String(payload.user_id)])).get(String(payload.user_id));
-		if (uid === void 0) throw kernelError(`用户 ${payload.user_id} 的 uid 解析失败`, "INVALID_PARAM");
+		const uid = await resolveUid(String(payload.user_id), this.deps.uinToUid);
 		await this.deps.msgApi.setInputStatus({
 			chatType: ChatType.C2C,
 			peerUid: uid
@@ -2628,9 +2594,7 @@ var SetMsgEmojiLikeAction = class extends BaseAction {
 		this.deps = deps;
 	}
 	async _handle(payload) {
-		const { msgId, peer } = resolveMsgIdAndPeer(payload.message_id, this.deps.messageUnique);
-		const [msg] = await this.deps.msgApi.fetchMsgsByMsgId(peer, [msgId]);
-		if (msg === void 0) throw kernelError(`消息 ${payload.message_id} 不存在或已被撤回`, "NOT_FOUND");
+		const { msg, peer } = await fetchMsgById(payload.message_id, this.deps.messageUnique, this.deps.msgApi);
 		await this.deps.msgApi.setMsgEmojiLike(peer, {
 			msgSeq: msg.msgSeq,
 			emojiId: String(payload.emoji_id),
@@ -3131,6 +3095,9 @@ var TranslateEn2ZhAction = class extends BaseAction {
 * OneBot 11 动作注册表（ADR-013 延伸）
 * 各协议维护自己的 ActionRegistry，由协议 adapter 挂到请求分发。
 * P2-16：deps 收敛为 { api: OneBotApi } 单聚合对象（基础设施第一项）。
+*
+* 同时是 action 域 barrel：re-export 全部动作类 + error-map + resolve-uid，
+* 协议外部只从本入口消费动作面。
 */
 /** 构建 OB11 动作注册表（所有 OB11 动作在此注册，按组拆分控制行数）。 */
 function createOb11ActionRegistry(deps) {
@@ -3424,15 +3391,27 @@ function makeAuthorize(token) {
 		return hasAccessTokenQuery(ctx.url, token);
 	};
 }
+/**
+* OneBot 客户端标识头：koishi 的 onebot 适配器按
+* x-client-role === "Universal" 与 x-self-id 校验 WS 连接（NapCat 同款头），
+* 缺失会被 close(1008) 拒绝——连接虽握手成功但应用层不认。
+*/
+function oneBotClientHeaders(selfUin) {
+	return {
+		"X-Self-ID": selfUin,
+		"x-client-role": "Universal",
+		"User-Agent": "OneBot/11"
+	};
+}
 /** 按配置装配 OB11 传输。 */
 function assembleOb11Transports(opts) {
-	const { config, broadcaster, handleRequest } = opts;
+	const { config, broadcaster, handleRequest, selfUin } = opts;
 	const servers = [];
 	const transports = [];
 	assembleHttpServers(config, handleRequest, servers);
 	assembleWsServers(config, handleRequest, servers);
-	assembleHttpPosts(config, transports);
-	assembleWsReverses(config, handleRequest, transports);
+	assembleHttpPosts(config, selfUin, transports);
+	assembleWsReverses(config, selfUin, handleRequest, transports);
 	for (const t of transports) broadcaster.register(t);
 	for (const s of servers) broadcaster.register(s);
 	return {
@@ -3474,19 +3453,27 @@ function assembleWsServers(config, handleRequest, servers) {
 	}
 }
 /** 装配 HTTP 正向上报 client 列表（fire-and-forget）。 */
-function assembleHttpPosts(config, transports) {
+function assembleHttpPosts(config, selfUin, transports) {
 	for (const item of config.httpPostUrls) if (item.enabled && item.url !== void 0) {
-		const headers = authorizeHeader(item.token ?? config.token);
-		const options = { url: item.url };
-		if (headers !== void 0) options.headers = headers;
+		const headers = {
+			"x-self-id": selfUin,
+			...authorizeHeader(item.token ?? config.token) ?? {}
+		};
+		const options = {
+			url: item.url,
+			headers
+		};
 		if (item.timeoutMs !== void 0) options.timeoutMs = item.timeoutMs;
 		transports.push(new HttpClient(options));
 	}
 }
 /** 装配正向 WS client 列表（双向，心跳 + 重连 + 证书选项）。 */
-function assembleWsReverses(config, handleRequest, transports) {
+function assembleWsReverses(config, selfUin, handleRequest, transports) {
 	for (const item of config.wsReverseUrls) if (item.enabled && item.url !== void 0) {
-		const headers = authorizeHeader(item.token ?? config.token);
+		const headers = {
+			...oneBotClientHeaders(selfUin),
+			...authorizeHeader(item.token ?? config.token) ?? {}
+		};
 		const reconnect = {
 			enabled: true,
 			delayMs: item.reconnectDelayMs
@@ -3494,11 +3481,11 @@ function assembleWsReverses(config, handleRequest, transports) {
 		if (item.maxReconnectAttempts !== void 0) reconnect.maxAttempts = item.maxReconnectAttempts;
 		const options = {
 			url: item.url,
+			headers,
 			heartbeat: { intervalMs: item.heartbeatInterval },
 			reconnect,
 			rejectUnauthorized: item.rejectUnauthorized
 		};
-		if (headers !== void 0) options.headers = headers;
 		const client = new WsClient(options);
 		client.onRequest = handleRequest;
 		transports.push(client);
@@ -3552,6 +3539,7 @@ var NapukettoOneBot11Adapter = class extends BaseProtocolAdapter {
 			this.transports = assembleOb11Transports({
 				config,
 				broadcaster,
+				selfUin: this.selfUin,
 				handleRequest: (req, respond) => {
 					this.handleRequest(req, respond).catch((err) => {
 						let message = String(err);
@@ -3611,16 +3599,14 @@ var NapukettoOneBot11Adapter = class extends BaseProtocolAdapter {
 	subscribe() {
 		if (this.unsubscribe !== null) return;
 		this.unsubscribe = this.msgChannel.on("Msg/onRecvMsg", (msgs) => {
-			const list = Array.isArray(msgs) ? msgs : [msgs];
-			for (const msg of list) {
-				if (!msg || typeof msg !== "object") continue;
+			forEachRawMessage(msgs, (msg) => {
 				if (hasGrayTip(msg)) {
 					this.broadcastNotice(msg).catch(() => {});
-					continue;
+					return;
 				}
-				if (!this.reportSelfMessage && String(msg.senderUin) === this.selfUin) continue;
+				if (!this.reportSelfMessage && String(msg.senderUin) === this.selfUin) return;
 				this.broadcastMessageEvent(msg);
-			}
+			});
 		});
 	}
 	/**