@napuketto/adapter 0.2.1 → 0.3.1

package/dist/kurobot/index.mjs

@@ -0,0 +1,998 @@
+import { r as BaseProtocolAdapter } from "../core-of7sLiQX.mjs";
+import { t as forEachRawMessage } from "../raw-message-6KdlG8kR.mjs";
+import { createRequire } from "node:module";
+import { ChatType, toCanonicalElements } from "@napuketto/kernel";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { WebSocket } from "ws";
+//#region src/kurobot/schema.ts
+/**
+* kurobridge-ws 协议 schema（镜像实现，任务书 KUROBOT-PROMPT §1.2 决策一）
+*
+* **SSOT: KuroBridge bridge/protocol**（`C:\Dev\MC-Ecosystem\KuroAdapter\bridge\protocol\src\`），
+* 镜像基线 **0.4.x**（KuroAdapter ADR-030 品牌改名：kurobot-ws.v1 → kurobridge-ws.v1，
+* PROTOCOL_VERSION 0.4.0；帧形状与 0.3.1 逐字段一致，仅品牌字符串与版本号变更）。
+* `@kuro-bridge/protocol` 已发 npm，本仓暂维持镜像（golden 帧对表测试锁漂移：
+* connection.test.ts / schema.test.ts），将来可切换为真依赖。
+*
+* 只镜像 WS 对端可见的消息集（meta / frame / messages/ws）；IPC 侧消息
+* （ready/broadcast/execute_command 等，Java↔Node 内部通道）不镜像。
+* 帧格式：`{header: {type, id?}, body}`（单行 JSON 文本帧）；事件帧无 id，
+* 请求/响应帧 id 必填（UUID 关联）；解析后 transform 为扁平消息 `{type, id?, body}`。
+*/
+const PROTOCOL_NAME = "kurobridge-ws";
+/** 语义化版本（主版本相同即兼容，ADR-026：0.2.x/0.3.0 服务端均接受 0.3.1 hello）。 */
+const PROTOCOL_VERSION = "0.4.0";
+/** WS 子协议（握手期校验，服务端 handleProtocols 不带即拒连）。 */
+const WS_SUBPROTOCOL = "kurobridge-ws.v1";
+const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
+function parseMajor(version) {
+	const match = VERSION_PATTERN.exec(version);
+	if (match === null) return null;
+	const major = Number.parseInt(match[1], 10);
+	return Number.isNaN(major) ? null : major;
+}
+/** 协议版本兼容判定（镜像 meta.ts 同名函数）：主版本号相同即兼容。 */
+function isProtocolVersionCompatible(peerVersion, serverVersion) {
+	const peer = parseMajor(peerVersion);
+	const server = parseMajor(serverVersion);
+	return peer !== null && server !== null && peer === server;
+}
+const frameHeaderSchema = z.object({
+	type: z.string().regex(/^[a-z][a-z0-9_]*$/),
+	id: z.uuid().optional()
+});
+/**
+* 通用线格式帧（两段式解析的第一段）：只约束帧骨架（type 受 snake_case、
+* id 存在时须 UUID、body 任意），供收帧侧「先取 type、再分发到具体 schema」。
+*/
+const wireFrameSchema = z.object({
+	header: frameHeaderSchema,
+	body: z.unknown()
+});
+/** 事件帧（单向通知，携带 id 即校验失败） */
+function eventFrameSchema(type, body) {
+	return z.object({
+		header: z.strictObject({ type: z.literal(type) }),
+		body
+	}).transform((frame) => {
+		const wire = frame;
+		return {
+			type: wire.header.type,
+			body: wire.body
+		};
+	});
+}
+/** 请求/响应帧（id 必填） */
+function requestFrameSchema(type, body) {
+	return z.object({
+		header: frameHeaderSchema.extend({
+			type: z.literal(type),
+			id: z.uuid()
+		}),
+		body
+	}).transform((frame) => {
+		const wire = frame;
+		return {
+			type: wire.header.type,
+			id: wire.header.id,
+			body: wire.body
+		};
+	});
+}
+/** 出帧：扁平消息 → 线格式 JSON 文本（单行，可直接走 WS 文本帧） */
+function encodeFrame(message) {
+	const header = { type: message.type };
+	if (message.id !== void 0) header.id = message.id;
+	return JSON.stringify({
+		header,
+		body: message.body
+	});
+}
+z.union([z.object({ ok: z.literal(true) }), z.object({
+	ok: z.literal(false),
+	error: z.string().min(1)
+})]);
+/** 请求-响应的命令结果体（ok 分支可选 `output`：命令输出行；与 query/命令链共用）。 */
+const commandResultBodySchema = z.union([z.object({
+	ok: z.literal(true),
+	output: z.array(z.string()).optional()
+}), z.object({
+	ok: z.literal(false),
+	error: z.string().min(1)
+})]);
+/** 对端注册（请求，服务端必须回同 id 的 hello_ack）。 */
+const helloFrame = requestFrameSchema("hello", z.object({
+	peerId: z.string().min(1),
+	platform: z.string().min(1),
+	version: z.string().min(1),
+	protocolVersion: z.string().regex(/^\d+\.\d+\.\d+$/),
+	/** 鉴权 token（服务端配置非空 token 时未带/带错 → hello_ack ok:false + close 1008）。 */
+	token: z.string().optional(),
+	/** 对端自报身份（0.3.1，MVP-3：建议 `名称/版本`，服务端仅日志辨识）。 */
+	client: z.string().optional()
+}));
+/** 心跳请求（应用层帧——服务端空闲检测只认应用层入帧，WS 层 ping 无效）。 */
+const pingFrame = requestFrameSchema("ping", z.object({ timestamp: z.number().int().nonnegative() }));
+/** 平台 → 游戏聊天（事件；服务端按绑定表过滤未绑定频道）。 */
+const platformChatFrame = eventFrameSchema("chat", z.object({
+	/** 消息来源频道（QQ 群号字符串） */
+	channel: z.string().min(1),
+	sender: z.string().min(1),
+	content: z.string().min(1)
+}));
+const commandSourceSchema = z.object({
+	/** 消息来源频道（QQ 群号字符串） */
+	channel: z.string().min(1),
+	/** 发送者 QQ 号（协议端负责从群消息提取；管理员判定在服务端） */
+	userId: z.string().min(1)
+});
+/** 群指令 → 执行游戏命令（请求；响应为同 id command_result）。 */
+const commandFrame = requestFrameSchema("command", z.object({
+	/** 待执行的命令行（不含前导斜杠，如 "whitelist list"） */
+	command: z.string().min(1),
+	source: commandSourceSchema
+}));
+/** 状态/绑定查询（请求；响应为同 id query_result）。 */
+const queryFrame = requestFrameSchema("query", z.object({ 
+/** 查询类别：status = 最近一帧服务器状态快照；bindings = 当前绑定频道列表 */
+kind: z.union([z.literal("status"), z.literal("bindings")]) }));
+const helloAckOkBodySchema = z.object({
+	ok: z.literal(true),
+	serverId: z.string().min(1),
+	version: z.string().min(1),
+	protocolVersion: z.string().regex(/^\d+\.\d+\.\d+$/),
+	/** 服务端绑定表快照（空数组合法 = 全部不发）。 */
+	channelBindings: z.array(z.string().min(1))
+});
+const helloAckErrorBodySchema = z.object({
+	ok: z.literal(false),
+	reason: z.string().min(1)
+});
+/** 握手结果（响应，同 id）。 */
+const helloAckFrame = z.union([requestFrameSchema("hello_ack", helloAckOkBodySchema), requestFrameSchema("hello_ack", helloAckErrorBodySchema)]);
+/** 心跳响应（不需要处理：收不到就等服务端 1001 关闭走重连）。 */
+const pongFrame = requestFrameSchema("pong", z.object({ timestamp: z.number().int().nonnegative() }));
+/** 游戏 → 平台聊天（事件）。 */
+const gameChatFrame = eventFrameSchema("chat", z.object({
+	/** 目标频道（服务端按绑定表逐频道 fan-out，每频道一帧） */
+	channel: z.string().min(1),
+	playerName: z.string().min(1),
+	content: z.string().min(1)
+}));
+/** 玩家进服（事件，按绑定频道 fan-out）。 */
+const joinFrame = eventFrameSchema("join", z.object({
+	channel: z.string().min(1),
+	playerName: z.string().min(1)
+}));
+/** 玩家退服（事件，按绑定频道 fan-out）。 */
+const leaveFrame = eventFrameSchema("leave", z.object({
+	channel: z.string().min(1),
+	playerName: z.string().min(1)
+}));
+/** 服务器状态（事件；无 channel——全服状态而非频道消息）。 */
+const statusFrame = eventFrameSchema("status", z.object({
+	/** 1 分钟 TPS 均值（Paper getTPS()[0]） */
+	tps: z.number().nonnegative(),
+	onlinePlayers: z.number().int().nonnegative(),
+	uptimeSeconds: z.number().int().nonnegative()
+}));
+/** 绑定表变更推送（事件）。 */
+const bindingsUpdatedFrame = eventFrameSchema("bindings_updated", z.object({ 
+/** 变更后的完整绑定列表（非增量；空数组合法 = 全部不发）。 */
+channelBindings: z.array(z.string().min(1)) }));
+/** 群指令的执行结果（响应，同 id）。 */
+const commandResultFrame = requestFrameSchema("command_result", commandResultBodySchema);
+/** 查询结果（响应，同 id）。 */
+const queryResultFrame = requestFrameSchema("query_result", z.union([z.object({
+	ok: z.literal(true),
+	/** data 形状由请求 kind 决定：status → StatusBody 同构；bindings → string[]。 */
+	data: z.unknown()
+}), z.object({
+	ok: z.literal(false),
+	error: z.string().min(1)
+})]));
+/** 玩家死亡（事件，按绑定频道 fan-out 对齐 join/leave）。 */
+const deathFrame = eventFrameSchema("death", z.object({
+	/** 目标频道（服务端按绑定表逐频道 fan-out，每频道一帧） */
+	channel: z.string().min(1),
+	/** 死亡玩家名（SSOT 原文命名 `player`——与 join/leave 的 playerName 不一致，照抄不「修正」） */
+	player: z.string().min(1),
+	/** 死亡消息文本（Bukkit deathMessage 可为 null → 服务端以空串兜底，故允许空串） */
+	message: z.string()
+}));
+//#endregion
+//#region src/kurobot/connection.ts
+/**
+* KurobotConnection：kurobridge-ws 客户端连接层（任务书 KUROBOT-PROMPT §1.2 决策二）
+*
+* 自建而不复用 network.WsClient 的四个协议语义理由（均已核实 WsClient 现状）：
+* ① 服务端 handleProtocols 校验子协议 `kurobridge-ws.v1`，不带直接拒连——WsClient
+*    不支持 Sec-WebSocket-Protocol；
+* ② 服务端空闲检测（30s）只认**应用层入帧**，WS 层 ws.ping() 不重置计时——必须发
+*    应用层 ping 帧；
+* ③ 每次连接（含重连）成功后必须立即重发 hello——WsClient 无 onOpen 回调；
+* ④ 重连需感知 close code（1002/1008 停止重连）——WsClient 是固定延迟重连。
+* 这四项都是 kurobridge-ws 协议语义，塞进协议无关的 network 违反其定位（红线：不改 network）。
+*
+* 状态机：connecting → establishing（hello 已发，等 ack）→ established（应用层 ping）
+* ↔ backoff（指数退避 1s/2s/…/60s 封顶）；hello_ack ok:false / close 1002 / 1008 →
+* 永久停止（等版本升级或配置修正，error 日志）。未 established 时发送直接丢弃（不积压）。
+*/
+/**
+* 已知 type → 具体 schema 校验（返回扁平消息；body 非法返回 null 由调用方统一 warn）。
+* 与 schema.ts 的 Server→Peer 消息集一一对应；hello_ack 在连接层单独处理，不在此表。
+*/
+const SERVER_FRAME_PARSERS = {
+	pong: (json) => {
+		const ok = pongFrame.safeParse(json);
+		return ok.success ? {
+			type: "pong",
+			id: ok.data.id,
+			body: ok.data.body
+		} : null;
+	},
+	chat: (json) => {
+		const ok = gameChatFrame.safeParse(json);
+		return ok.success ? {
+			type: "chat",
+			body: ok.data.body
+		} : null;
+	},
+	join: (json) => {
+		const ok = joinFrame.safeParse(json);
+		return ok.success ? {
+			type: "join",
+			body: ok.data.body
+		} : null;
+	},
+	leave: (json) => {
+		const ok = leaveFrame.safeParse(json);
+		return ok.success ? {
+			type: "leave",
+			body: ok.data.body
+		} : null;
+	},
+	death: (json) => {
+		const ok = deathFrame.safeParse(json);
+		return ok.success ? {
+			type: "death",
+			body: ok.data.body
+		} : null;
+	},
+	status: (json) => {
+		const ok = statusFrame.safeParse(json);
+		return ok.success ? {
+			type: "status",
+			body: ok.data.body
+		} : null;
+	},
+	bindings_updated: (json) => {
+		const ok = bindingsUpdatedFrame.safeParse(json);
+		return ok.success ? {
+			type: "bindings_updated",
+			body: ok.data.body
+		} : null;
+	},
+	command_result: (json) => {
+		const ok = commandResultFrame.safeParse(json);
+		return ok.success ? {
+			type: "command_result",
+			id: ok.data.id,
+			body: ok.data.body
+		} : null;
+	},
+	query_result: (json) => {
+		const ok = queryResultFrame.safeParse(json);
+		return ok.success ? {
+			type: "query_result",
+			id: ok.data.id,
+			body: ok.data.body
+		} : null;
+	}
+};
+/** kurobridge-ws 客户端连接（子协议 + hello + 应用层 ping + 感知 close code 的指数退避）。 */
+var KurobotConnection = class {
+	opts;
+	log;
+	state = "idle";
+	ws = null;
+	/** 用户主动 stop（其后一切 close 都不再重连、不上报 onEnded）。 */
+	userStopped = false;
+	/** 已判定永久拒绝（版本/token），不再重连。 */
+	rejected = false;
+	pendingHelloId = null;
+	helloTimer = null;
+	pingTimer = null;
+	retryTimer = null;
+	/** 连续失败计数（established 成功后清零）。 */
+	attempt = 0;
+	constructor(opts) {
+		this.opts = opts;
+		this.log = opts.logger ?? SILENT_LOGGER;
+	}
+	/** 当前是否已建立（ack ok）。 */
+	isEstablished() {
+		return this.state === "established";
+	}
+	/** 启动：发起首次连接（异步，结果经回调上报；重复调用幂等）。 */
+	start() {
+		if (this.state !== "idle") return;
+		this.connect();
+	}
+	/** 停止：关闭连接、清定时器、不再重连（幂等；不触发 onEnded）。 */
+	stop() {
+		if (this.state === "stopped") return;
+		this.userStopped = true;
+		this.clearTimers();
+		this.state = "stopped";
+		const ws = this.ws;
+		this.ws = null;
+		ws?.close(1e3, "client stop");
+	}
+	/** 发送出站帧（chat/command/query 等扁平消息）；未 established 丢弃 + debug。 */
+	send(message) {
+		const ws = this.ws;
+		if (this.state !== "established" || ws === null || ws.readyState !== WebSocket.OPEN) {
+			this.log.debug({ type: message.type }, "kurobot: 未建立连接，丢弃出站帧");
+			return false;
+		}
+		ws.send(encodeFrame(message));
+		return true;
+	}
+	/** 发起一次连接。 */
+	connect() {
+		if (this.userStopped || this.rejected) return;
+		this.state = "connecting";
+		const ws = new WebSocket(this.opts.url, WS_SUBPROTOCOL);
+		this.ws = ws;
+		ws.on("open", () => {
+			this.onOpen();
+		});
+		ws.on("message", (data) => {
+			this.onText(String(data));
+		});
+		ws.on("close", (code, reason) => {
+			this.onClose(code, reason.toString());
+		});
+		ws.on("error", (err) => {
+			this.log.warn({ err: err.message }, "kurobot: 连接错误");
+		});
+	}
+	/** 连接建立：立即发 hello（每次连接都重发——服务端按连接会话握手）。 */
+	onOpen() {
+		if (this.ws === null || this.userStopped || this.rejected) return;
+		this.state = "establishing";
+		this.pendingHelloId = randomUUID();
+		this.ws.send(encodeFrame({
+			type: "hello",
+			id: this.pendingHelloId,
+			body: this.opts.hello
+		}));
+		this.helloTimer = setTimeout(() => {
+			this.helloTimer = null;
+			if (this.state === "establishing") {
+				this.log.warn({}, "kurobot: 等待 hello_ack 超时，关闭重试");
+				this.ws?.close();
+			}
+		}, this.opts.helloTimeoutMs);
+	}
+	/** 收到文本帧：两段式解析（wire 取 type → 分发具体 schema）+ 未知帧容忍。 */
+	onText(text) {
+		let json;
+		try {
+			json = JSON.parse(text);
+		} catch {
+			this.log.warn({ text: text.slice(0, 200) }, "kurobot: 非法 JSON 帧，忽略");
+			return;
+		}
+		const wire = wireFrameSchema.safeParse(json);
+		if (!wire.success) {
+			this.log.warn({ text: text.slice(0, 200) }, "kurobot: 帧骨架非法，忽略");
+			return;
+		}
+		const { type } = wire.data.header;
+		if (type === "hello") {
+			this.log.warn({}, "kurobot: 收到非预期的 hello 帧，忽略");
+			return;
+		}
+		if (type === "hello_ack") {
+			this.handleHelloAck(json);
+			return;
+		}
+		const msg = this.parseServerFrame(type, json);
+		if (msg !== null) this.opts.onFrame(msg);
+	}
+	/** 已知 type 的具体 schema 校验（未知 type 走容忍；body 非法 warn 丢弃）。 */
+	parseServerFrame(type, json) {
+		const parser = SERVER_FRAME_PARSERS[type];
+		if (parser === void 0) {
+			this.handleUnknownFrame(type, headerId(json));
+			return null;
+		}
+		const msg = parser(json);
+		if (msg === null) this.log.warn({ type }, "kurobot: 已知帧 body 校验失败，丢弃");
+		return msg;
+	}
+	/** 未知帧容忍（对齐 ADR-026 服务端策略）：事件帧忽略；请求帧回 `<type>_result` 失败回执；`_result` 结尾不回执（防乒乓）。 */
+	handleUnknownFrame(type, id) {
+		if (id === void 0) {
+			this.log.debug({ type }, "kurobot: 未知事件帧，忽略");
+			return;
+		}
+		if (type.endsWith("_result")) {
+			this.log.debug({ type }, "kurobot: 未知响应帧，忽略（不回执防乒乓）");
+			return;
+		}
+		this.log.debug({ type }, "kurobot: 未知请求帧，回执 unknown frame type");
+		this.send({
+			type: `${type}_result`,
+			id,
+			body: {
+				ok: false,
+				error: "unknown frame type"
+			}
+		});
+	}
+	/** hello_ack 处理：ok → 建立；ok:false → 永久停止（版本/鉴权问题不可自愈）。 */
+	handleHelloAck(json) {
+		const parsed = helloAckFrame.safeParse(json);
+		if (!parsed.success) {
+			this.log.warn({ type: "hello_ack" }, "kurobot: 已知帧 body 校验失败，丢弃");
+			return;
+		}
+		if (parsed.data.id !== this.pendingHelloId) {
+			this.log.warn({}, "kurobot: hello_ack id 与请求不匹配，忽略");
+			return;
+		}
+		if (!parsed.data.body.ok) {
+			this.log.error({ reason: parsed.data.body.reason }, "kurobot: 握手被拒，停止重连");
+			this.reject(`hello_ack: ${parsed.data.body.reason}`);
+			return;
+		}
+		const ack = parsed.data.body;
+		if (!isProtocolVersionCompatible(this.opts.hello.protocolVersion, ack.protocolVersion)) this.log.warn({
+			peer: ack.protocolVersion,
+			self: this.opts.hello.protocolVersion
+		}, "kurobot: hello_ack 版本与本地声明主版本不一致");
+		if (this.helloTimer !== null) {
+			clearTimeout(this.helloTimer);
+			this.helloTimer = null;
+		}
+		this.attempt = 0;
+		this.state = "established";
+		this.startPing();
+		this.log.info({
+			serverId: ack.serverId,
+			version: ack.version,
+			protocolVersion: ack.protocolVersion
+		}, "kurobot: 握手成功");
+		this.opts.onEstablished(ack);
+	}
+	/** 应用层心跳：每 pingIntervalMs 发 ping 帧（服务端任何入帧重置 30s 空闲计时）。 */
+	startPing() {
+		this.stopPing();
+		if (this.opts.pingIntervalMs <= 0) return;
+		this.pingTimer = setInterval(() => {
+			if (this.state === "established") this.send({
+				type: "ping",
+				id: randomUUID(),
+				body: { timestamp: Date.now() }
+			});
+		}, this.opts.pingIntervalMs);
+	}
+	stopPing() {
+		if (this.pingTimer !== null) {
+			clearInterval(this.pingTimer);
+			this.pingTimer = null;
+		}
+	}
+	clearTimers() {
+		if (this.helloTimer !== null) {
+			clearTimeout(this.helloTimer);
+			this.helloTimer = null;
+		}
+		this.stopPing();
+		if (this.retryTimer !== null) {
+			clearTimeout(this.retryTimer);
+			this.retryTimer = null;
+		}
+		this.pendingHelloId = null;
+	}
+	/** 永久拒绝：关闭连接，不再重连，上报 onEnded。 */
+	reject(detail, code) {
+		this.rejected = true;
+		this.clearTimers();
+		this.state = "stopped";
+		const ws = this.ws;
+		this.ws = null;
+		ws?.close();
+		const reason = {
+			permanent: true,
+			detail
+		};
+		if (code !== void 0) reason.code = code;
+		this.opts.onEnded(reason);
+	}
+	/** close：区分用户停止 / 永久拒绝（1002/1008）/ 可重连断开。 */
+	onClose(code, reason) {
+		if (this.helloTimer !== null) {
+			clearTimeout(this.helloTimer);
+			this.helloTimer = null;
+		}
+		this.stopPing();
+		const wasEstablished = this.state === "established";
+		this.ws = null;
+		if (this.userStopped || this.rejected) {
+			this.state = "stopped";
+			return;
+		}
+		this.state = "idle";
+		if (code === 1002 || code === 1008) {
+			this.log.error({
+				code,
+				reason
+			}, "kurobot: 连接被拒（不可重试错误），停止重连");
+			this.rejected = true;
+			this.state = "stopped";
+			this.opts.onEnded({
+				permanent: true,
+				code,
+				detail: reason || `closed ${code}`
+			});
+			return;
+		}
+		if (wasEstablished) this.log.warn({
+			code,
+			reason
+		}, "kurobot: 连接断开，准备重连");
+		this.scheduleRetry();
+	}
+	/** 指数退避重连：base * 2^attempt 封顶 retryMaxDelayMs；established 成功清零。 */
+	scheduleRetry() {
+		if (this.userStopped || this.rejected || this.retryTimer !== null) return;
+		this.state = "backoff";
+		const delay = Math.min(this.opts.retryBaseDelayMs * 2 ** this.attempt, this.opts.retryMaxDelayMs);
+		this.attempt += 1;
+		this.log.debug({
+			delay,
+			attempt: this.attempt
+		}, "kurobot: 退避后重连");
+		this.retryTimer = setTimeout(() => {
+			this.retryTimer = null;
+			this.connect();
+		}, delay);
+	}
+};
+/** 从已解析的原始帧 JSON 取 header.id（容忍缺失）。 */
+function headerId(json) {
+	if (typeof json !== "object" || json === null) return;
+	const header = json.header;
+	if (typeof header !== "object" || header === null) return;
+	const id = header.id;
+	return typeof id === "string" ? id : void 0;
+}
+/** 静默日志（缺省）。 */
+const SILENT_LOGGER = {
+	debug: () => void 0,
+	info: () => void 0,
+	warn: () => void 0,
+	error: () => void 0
+};
+//#endregion
+//#region src/kurobot/translate.ts
+/**
+* 消息映射纯函数（任务书 KUROBOT-PROMPT §1.2 QQ↔MC 映射；翻译层无副作用，ADR-008）
+*
+* QQ → MC：canonical elements 富文本降级为单行文本（无法表达的类型静默跳过，
+* 对齐 OB11 收向「无法表达静默跳过」惯例）。
+* MC → QQ：渲染模板占位符替换（{player}/{content}/{message}，MVP 纯文本）+
+* 1500 字符截断。
+*/
+/** 发往 QQ 文本的总长上限（超出截断追加 …(截断)；任务书对 command_result 规定，统一套用）。 */
+const MAX_GROUP_TEXT_LENGTH = 1500;
+/** 截断追加的省略标记。 */
+const TRUNCATE_SUFFIX = "…(截断)";
+/** 超长截断（按 UTF-16 码元计，超限部分丢弃）。 */
+function truncateForGroup(text) {
+	if (text.length <= 1500) return text;
+	return `${text.slice(0, MAX_GROUP_TEXT_LENGTH)}${TRUNCATE_SUFFIX}`;
+}
+/** QQ 群消息发送者显示名：sendMemberName ?? sendNickName（双空兜底 senderUin，schema min(1)）。 */
+function resolveSenderName(msg) {
+	const member = msg.sendMemberName;
+	if (typeof member === "string" && member !== "") return member;
+	const nick = msg.sendNickName;
+	if (typeof nick === "string" && nick !== "") return nick;
+	return String(msg.senderUin);
+}
+/** at 元素 → 文本占位（@全体成员 / @{display ?? uid}）。 */
+function atToText(el) {
+	if (el.target === "all") return "@全体成员";
+	return `@${el.display ?? el.target}`;
+}
+/** canonical 元素序列 → 降级文本（text 原文、@、图片/表情/回复占位；空白返回 null = 不发）。 */
+function degradeElements(elements) {
+	const parts = [];
+	for (const el of elements) switch (el.type) {
+		case "text":
+			parts.push(el.text);
+			break;
+		case "at":
+			parts.push(atToText(el));
+			break;
+		case "image":
+			parts.push("[图片]");
+			break;
+		case "face":
+			parts.push("[表情]");
+			break;
+		case "reply": parts.push("[回复]");
+	}
+	const text = parts.join("").trim();
+	return text === "" ? null : text;
+}
+/** RawMessage → 降级文本（便捷封装；null = 空消息不发）。 */
+function degradeMessage(msg) {
+	return degradeElements(toCanonicalElements(msg));
+}
+/** 渲染模板：替换 {player}/{content}/{message} 占位符（未知占位符原样保留）。 */
+function renderTemplate(template, vars) {
+	return template.replaceAll("{player}", vars.player).replaceAll("{content}", vars.content ?? "").replaceAll("{message}", vars.message ?? "");
+}
+/** death 事件 → 群文本（message 空串时以「死亡了」代入：Bukkit deathMessage null 兜底）。 */
+function renderDeathText(template, player, message) {
+	return renderTemplate(template, {
+		player,
+		message: message === "" ? "死亡了" : message
+	});
+}
+/** command_result body → 群文本（ok 合并 output；error → 命令失败：{error}）。 */
+function renderCommandResult(body) {
+	if (!body.ok) return `命令失败：${body.error}`;
+	const output = body.output ?? [];
+	if (output.length === 0) return "（命令执行成功，无输出）";
+	return output.join("\n");
+}
+//#endregion
+//#region src/kurobot/adapter.ts
+/**
+* NapukettoKurobotAdapter：kurobridge-ws 协议适配器（KuroBot MVP-3，2026-09-13）
+*
+* - 出链路：订阅 kernel 消息事件通道 → 仅群聊 → 富文本降级 → 出站绑定过滤 →
+*   kurobridge-ws chat 帧；命令前缀消息 → command 帧（source 由本侧提取）。
+* - 入链路：KurobotConnection 收服务端帧 → chat/join/leave/death 渲染模板 →
+*   kernel 群消息 API 纯文本发送；status 仅缓存；command_result 经 pending 表
+*   关联回发群（帧无 channel 字段，靠请求 UUID 关联）。
+*
+* 生命周期走 BaseProtocolAdapter 骨架（start 校验配置 → onStart 建连接 + 订阅 →
+* onStop 清理）；连接层状态机见 connection.ts。不发协议事件给 network 广播器
+* （kurobot 是纯客户端出向协议，无第三方接入门面）。
+*/
+/** kurobot 协议适配器。 */
+var NapukettoKurobotAdapter = class extends BaseProtocolAdapter {
+	protocol = "kurobot";
+	msgChannel;
+	msgApi;
+	selfUin;
+	log;
+	connection = null;
+	unsubscribe = null;
+	/** 当前生效配置（收链路取 commandPrefix 等；onStart/onReload 刷新）。 */
+	currentConfig = null;
+	/** 出站绑定集（hello_ack 快照 + bindings_updated 全量替换；空集 = 全部不发）。 */
+	bindings = /* @__PURE__ */ new Set();
+	/** command 请求 UUID → 回发群号（command_result 帧无 channel，靠 id 关联）。 */
+	pendingCommands = /* @__PURE__ */ new Map();
+	/** query 请求 UUID → 查询类别。 */
+	pendingQueries = /* @__PURE__ */ new Map();
+	/** 最近一帧 status 快照（仅缓存不发群，M-04 决策同构）。 */
+	lastStatus = null;
+	constructor(opts) {
+		super({
+			config: opts.config,
+			hooks: {
+				onStart: (config) => this.startKurobot(config),
+				onStop: () => this.stopAll(),
+				onReload: (config) => this.reloadKurobot(config)
+			}
+		});
+		this.msgChannel = opts.msgChannel;
+		this.msgApi = opts.msgApi;
+		this.selfUin = String(opts.self.uin);
+		this.log = opts.logger;
+	}
+	/** 最近一帧 status 快照（仅缓存；无帧时 null）。 */
+	getLastStatus() {
+		return this.lastStatus;
+	}
+	/** 连接是否已建立（hello_ack ok 后为 true）。 */
+	isConnected() {
+		return this.connection?.isEstablished() ?? false;
+	}
+	/** 发起 query 请求（status/bindings）。MVP 未接 QQ 触发面——预留能力（见 design.md §8）。 */
+	query(kind) {
+		const conn = this.connection;
+		if (conn === null || !conn.isEstablished()) return false;
+		const id = randomUUID();
+		this.pendingQueries.set(id, kind);
+		return conn.send({
+			type: "query",
+			id,
+			body: { kind }
+		});
+	}
+	/** 启动：建连接（异步握手，日志可见）+ 订阅 kernel 消息。 */
+	async startKurobot(config) {
+		this.currentConfig = config;
+		this.bindings = /* @__PURE__ */ new Set();
+		this.pendingCommands.clear();
+		this.pendingQueries.clear();
+		this.lastStatus = null;
+		const hello = {
+			peerId: this.selfUin,
+			platform: "qq",
+			version: resolveAdapterVersion(),
+			protocolVersion: PROTOCOL_VERSION,
+			client: config.client ?? resolveDefaultClient()
+		};
+		if (config.token !== "") hello.token = config.token;
+		const connOptions = {
+			url: config.url,
+			hello,
+			pingIntervalMs: config.pingIntervalMs,
+			helloTimeoutMs: 1e4,
+			retryBaseDelayMs: 1e3,
+			retryMaxDelayMs: 6e4,
+			onEstablished: (ack) => this.onEstablished(ack),
+			onFrame: (msg) => this.onServerFrame(msg),
+			onEnded: (reason) => this.onEnded(reason)
+		};
+		if (this.log !== void 0) connOptions.logger = this.log;
+		this.connection = new KurobotConnection(connOptions);
+		this.connection.start();
+		this.subscribe();
+	}
+	/** 配置热更新：停旧连接/退订 → 按新配置重建（对齐 satori reloadTransports）。 */
+	async reloadKurobot(config) {
+		await this.stopAll();
+		await this.startKurobot(config);
+	}
+	/** 停止：退订 + 关连接 + 清 pending 表。 */
+	async stopAll() {
+		this.unsubscribeAll();
+		this.connection?.stop();
+		this.connection = null;
+		this.pendingCommands.clear();
+		this.pendingQueries.clear();
+	}
+	/** 握手成功：绑定集整体替换为服务端快照 + 清上一连接的 pending 表。 */
+	onEstablished(ack) {
+		this.pendingCommands.clear();
+		this.pendingQueries.clear();
+		this.bindings = new Set(ack.channelBindings);
+	}
+	/** 连接永久停止（1002/1008/hello_ack 拒绝）：清 pending（绑定集留给下次握手覆盖）。 */
+	onEnded(reason) {
+		this.pendingCommands.clear();
+		this.pendingQueries.clear();
+		this.log?.error({ reason }, "kurobot: 连接终止");
+	}
+	/** 服务端帧分发（渲染回群 / 缓存 / 绑定集维护 / 命令结果关联回发）。 */
+	onServerFrame(msg) {
+		switch (msg.type) {
+			case "pong": return;
+			case "chat":
+				this.sendToGroup(msg.body.channel, renderTemplate(this.requireConfig().chatTemplate, {
+					player: msg.body.playerName,
+					content: msg.body.content
+				}));
+				return;
+			case "join":
+				this.sendToGroup(msg.body.channel, renderTemplate(this.requireConfig().joinTemplate, { player: msg.body.playerName }));
+				return;
+			case "leave":
+				this.sendToGroup(msg.body.channel, renderTemplate(this.requireConfig().leaveTemplate, { player: msg.body.playerName }));
+				return;
+			case "death":
+				this.sendToGroup(msg.body.channel, truncateForGroup(renderDeathText(this.requireConfig().deathTemplate, msg.body.player, msg.body.message)));
+				return;
+			case "status":
+				this.lastStatus = msg.body;
+				this.log?.debug({ status: msg.body }, "kurobot: status 已缓存");
+				return;
+			case "bindings_updated":
+				this.bindings = new Set(msg.body.channelBindings);
+				this.log?.info({ bindings: msg.body.channelBindings }, "kurobot: 绑定表已更新");
+				return;
+			case "command_result": {
+				const channel = this.pendingCommands.get(msg.id);
+				if (channel === void 0) {
+					this.log?.warn({ id: msg.id }, "kurobot: command_result 无对应请求，丢弃");
+					return;
+				}
+				this.pendingCommands.delete(msg.id);
+				this.sendToGroup(channel, truncateForGroup(renderCommandResult(msg.body)));
+				return;
+			}
+			case "query_result":
+				this.onQueryResult(msg.id, msg.body);
+				return;
+		}
+	}
+	/** query_result 处理：bindings 刷新绑定集（防御性收窄）；status 缓存。 */
+	onQueryResult(id, body) {
+		const kind = this.pendingQueries.get(id);
+		if (kind === void 0) {
+			this.log?.warn({ id }, "kurobot: query_result 无对应请求，丢弃");
+			return;
+		}
+		this.pendingQueries.delete(id);
+		if (!body.ok) {
+			this.log?.warn({
+				kind,
+				error: body.error
+			}, "kurobot: 查询失败");
+			return;
+		}
+		if (kind === "bindings" && isStringArray(body.data)) {
+			this.bindings = new Set(body.data);
+			return;
+		}
+		this.log?.debug({
+			kind,
+			data: body.data
+		}, "kurobot: 查询结果已记录");
+	}
+	/** kernel 群消息 → kurobot 出站（仅群聊 + 自消息过滤 + 命令分流 + 绑定过滤）。 */
+	handleIncomingMessage(msg) {
+		const config = this.currentConfig;
+		if (config === null) return;
+		if (msg.chatType !== ChatType.GROUP) return;
+		if (String(msg.senderUin) === this.selfUin) return;
+		const channel = msg.peerUid;
+		if (channel === "") return;
+		const text = degradeMessage(msg);
+		if (text === null) return;
+		if (text.startsWith(config.commandPrefix)) {
+			const command = text.slice(config.commandPrefix.length).trim();
+			if (command === "") return;
+			this.sendCommand(channel, command, String(msg.senderUin));
+			return;
+		}
+		if (this.bindings.size === 0 || !this.bindings.has(channel)) {
+			this.log?.debug({ channel }, "kurobot: 非绑定群，跳过 chat 帧");
+			return;
+		}
+		this.sendChat(channel, resolveSenderName(msg), text);
+	}
+	/** 发 chat 事件帧（无 id）。 */
+	sendChat(channel, sender, content) {
+		this.connection?.send({
+			type: "chat",
+			body: {
+				channel,
+				sender,
+				content
+			}
+		});
+	}
+	/** 发 command 请求帧（登记 pending 表供 command_result 关联）。 */
+	sendCommand(channel, command, userId) {
+		const id = randomUUID();
+		this.pendingCommands.set(id, channel);
+		if (this.connection?.send({
+			type: "command",
+			id,
+			body: {
+				command,
+				source: {
+					channel,
+					userId
+				}
+			}
+		}) !== true) this.pendingCommands.delete(id);
+	}
+	/** 群文本发送（失败 error 日志不抛出——不影响连接与收链路）。 */
+	sendToGroup(channel, text) {
+		this.msgApi.sendMessage({
+			chatType: ChatType.GROUP,
+			peerUid: channel
+		}, [{
+			type: "text",
+			text
+		}]).then(() => {
+			this.log?.debug({ channel }, "kurobot: 群消息已发送");
+		}).catch((err) => {
+			this.log?.error({
+				channel,
+				err: err instanceof Error ? err.message : String(err)
+			}, "kurobot: 群消息发送失败");
+		});
+	}
+	/** 当前生效配置（收链路保证已 start）。 */
+	requireConfig() {
+		const config = this.currentConfig;
+		if (config === null) throw new Error("kurobot: 配置未初始化（适配器未启动）");
+		return config;
+	}
+	/** 订阅 kernel 消息事件（幂等）。 */
+	subscribe() {
+		if (this.unsubscribe !== null) return;
+		this.unsubscribe = this.msgChannel.on("Msg/onRecvMsg", (msgs) => {
+			forEachRawMessage(msgs, (msg) => {
+				this.handleIncomingMessage(msg);
+			});
+		});
+	}
+	/** 退订（幂等）。 */
+	unsubscribeAll() {
+		this.unsubscribe?.();
+		this.unsubscribe = null;
+	}
+};
+/** string[] 防御性收窄（query_result bindings data）。 */
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/** best-effort 读取 adapter 包版本（dist 与 src 双布局相对包根一致）。 */
+function resolvePackageVersion() {
+	try {
+		const pkg = createRequire(import.meta.url)("../../package.json");
+		if (typeof pkg.version === "string" && pkg.version !== "") return pkg.version;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/** hello.version：adapter 包版本（取不到用 unknown）。 */
+function resolveAdapterVersion() {
+	return resolvePackageVersion() ?? "unknown";
+}
+/** hello.client 缺省身份：napukettoqq/<版本>（取不到版本则 napukettoqq）。 */
+function resolveDefaultClient() {
+	const version = resolvePackageVersion();
+	return version === null ? "napukettoqq" : `napukettoqq/${version}`;
+}
+//#endregion
+//#region src/kurobot/config.ts
+/**
+* kurobot 协议配置（zod schema，归属本包，ADR-012；任务书 KUROBOT-PROMPT §1.2）
+*
+* 单一 TOML 的 `[accounts.kurobot]` 账号段（段存在即启用、不写不启用），
+* seed 注入对齐 onebot11/satori 的 ConfigBase 模式。
+*/
+/** kurobot 配置 schema。 */
+const kurobotConfigSchema = z.object({
+	/** KuroBot 服务端完整地址（必填，ws:// 或 wss://）。 */
+	url: z.url().refine((u) => u.startsWith("ws://") || u.startsWith("wss://"), { message: "url 必须是 ws:// 或 wss:// 地址" }),
+	/** 鉴权 token（缺省空 = 不带；服务端配置了非空 token 则必须一致，否则 close 1008）。 */
+	token: z.string().default(""),
+	/** 自报身份（缺省 napukettoqq，能取到 adapter 包版本则 napukettoqq/<版本>）。 */
+	client: z.string().min(1).optional(),
+	/** 群命令前缀（前缀开头 → command 帧，不再作为 chat 发送）。 */
+	commandPrefix: z.string().min(1).default("/"),
+	/** 应用层心跳间隔毫秒（服务端空闲阈值 30s，任何入帧重置；须显著小于 30000）。 */
+	pingIntervalMs: z.number().int().positive().default(15e3),
+	/** MC 聊天渲染模板。 */
+	chatTemplate: z.string().min(1).default("[{player}] {content}"),
+	/** 玩家进服渲染模板。 */
+	joinTemplate: z.string().min(1).default("{player} 加入了服务器"),
+	/** 玩家退服渲染模板。 */
+	leaveTemplate: z.string().min(1).default("{player} 离开了服务器"),
+	/** 玩家死亡渲染模板（message 为空串时以「死亡了」代入）。 */
+	deathTemplate: z.string().min(1).default("{player} {message}")
+});
+/**
+* ConfigBase 必填的 defaults 形参兜底值（url 必填 → 无法 `parse({})`）。
+* 装配走 seed 模式（段存在才装配，seed 已校验），defaults 不参与生效值；
+* 仅在「无 seed 且配置文件缺失」的直连场景被落盘——端口 0 地址连接会失败退避，
+* 不会静默假在线。
+*/
+function kurobotConfigDefaults() {
+	return kurobotConfigSchema.parse({ url: "ws://127.0.0.1:0" });
+}
+//#endregion
+export { KurobotConnection, MAX_GROUP_TEXT_LENGTH, NapukettoKurobotAdapter, PROTOCOL_NAME, PROTOCOL_VERSION, WS_SUBPROTOCOL, bindingsUpdatedFrame, commandFrame, commandResultFrame, deathFrame, degradeElements, degradeMessage, encodeFrame, gameChatFrame, helloAckFrame, helloFrame, isProtocolVersionCompatible, joinFrame, kurobotConfigDefaults, kurobotConfigSchema, leaveFrame, pingFrame, platformChatFrame, pongFrame, queryFrame, queryResultFrame, renderCommandResult, renderDeathText, renderTemplate, resolveSenderName, statusFrame, truncateForGroup, wireFrameSchema };
+
+//# sourceMappingURL=index.mjs.map