@bilibili-notify/live 0.0.1-alpha.0

package/lib/index.mjs

@@ -0,0 +1,1764 @@
+import { cut } from "jieba-wasm";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { GuardLevel, startListen } from "blive-message-listener";
+import { DateTime } from "luxon";
+import protobuf from "protobufjs";
+//#region src/danmaku-collector.ts
+/**
+* Per-room danmaku buffer powering the wordcloud + live-summary post-processing.
+*
+* - `recordDanmaku(roomId, content, username)` segments the danmaku via jieba
+*   and updates both word-frequency and per-user count maps for that room.
+* - `snapshot(roomId)` returns the sorted word list + raw sender map for
+*   passing to {@link WordcloudGenerator} / {@link LiveSummaryRequester}.
+* - `clear(roomId)` is invoked at live-end after the wordcloud + summary have
+*   been dispatched (or the start of a new live session for that room).
+*
+* The collector intentionally does NOT decide whether collection is enabled —
+* the listener-manager checks the wordcloud / liveSummary master+target gates
+* before calling `recordDanmaku`. This keeps the collector zero-config.
+*/
+var DanmakuCollector = class {
+	/** roomId → { word: count } */
+	weightByRoom = /* @__PURE__ */ new Map();
+	/** roomId → { username: count } */
+	senderByRoom = /* @__PURE__ */ new Map();
+	stopwords;
+	constructor(stopwords) {
+		this.stopwords = new Set(stopwords);
+	}
+	/** Replace the active stop-word set (called on config update). */
+	setStopwords(stopwords) {
+		this.stopwords.clear();
+		for (const w of stopwords) this.stopwords.add(w);
+	}
+	/** Make sure a room is being tracked (called when listener starts). */
+	registerRoom(roomId) {
+		if (!this.weightByRoom.has(roomId)) this.weightByRoom.set(roomId, {});
+		if (!this.senderByRoom.has(roomId)) this.senderByRoom.set(roomId, {});
+	}
+	/**
+	* Tokenise an incoming danmaku and update word-frequency + per-user count.
+	* Words shorter than 2 characters or in the stop-word set are dropped.
+	*/
+	recordDanmaku(roomId, content, username) {
+		this.registerRoom(roomId);
+		const wordRecord = this.weightByRoom.get(roomId);
+		const senderRecord = this.senderByRoom.get(roomId);
+		if (!wordRecord || !senderRecord) return;
+		cut(content, true).filter((word) => word.length >= 2 && !this.stopwords.has(word)).forEach((w) => {
+			wordRecord[w] = (wordRecord[w] || 0) + 1;
+		});
+		senderRecord[username] = (senderRecord[username] || 0) + 1;
+	}
+	/**
+	* Read a sorted snapshot of the current buffer for a room.
+	*
+	* - `sortedWords`: descending by frequency.
+	* - `senderRecord`: raw username → count map (consumer decides ordering).
+	* - `senderCount`: number of distinct usernames.
+	* - `danmakuCount`: total danmaku recorded.
+	*/
+	snapshot(roomId) {
+		const weights = this.weightByRoom.get(roomId) ?? {};
+		const senders = this.senderByRoom.get(roomId) ?? {};
+		const sortedWords = Object.entries(weights).sort((a, b) => b[1] - a[1]);
+		const senderCount = Object.keys(senders).length;
+		const danmakuCount = Object.values(senders).reduce((sum, val) => sum + val, 0);
+		return {
+			sortedWords,
+			senderRecord: { ...senders },
+			senderCount,
+			danmakuCount
+		};
+	}
+	/** Drop all collected data for a room (called at live-end / room-stop). */
+	clear(roomId) {
+		this.weightByRoom.delete(roomId);
+		this.senderByRoom.delete(roomId);
+	}
+	/** Drop everything (called on engine stop / auth-lost). */
+	clearAll() {
+		this.weightByRoom.clear();
+		this.senderByRoom.clear();
+	}
+};
+//#endregion
+//#region src/push-like.ts
+/** Push category enum — numeric values are the historical bilibili-notify push-type codes. */
+let LivePushType = /* @__PURE__ */ function(LivePushType) {
+	LivePushType[LivePushType["Live"] = 0] = "Live";
+	LivePushType[LivePushType["StartBroadcasting"] = 3] = "StartBroadcasting";
+	LivePushType[LivePushType["LiveGuardBuy"] = 4] = "LiveGuardBuy";
+	/** 历史上承载词云+总结合包推送;现在仅用于词云,总结走 {@link LiveSummary}。 */
+	LivePushType[LivePushType["WordCloudAndLiveSummary"] = 5] = "WordCloudAndLiveSummary";
+	LivePushType[LivePushType["Superchat"] = 6] = "Superchat";
+	LivePushType[LivePushType["UserDanmakuMsg"] = 7] = "UserDanmakuMsg";
+	LivePushType[LivePushType["UserActions"] = 8] = "UserActions";
+	LivePushType[LivePushType["LiveEnd"] = 9] = "LiveEnd";
+	LivePushType[LivePushType["LiveSummary"] = 10] = "LiveSummary";
+	return LivePushType;
+}({});
+/**
+* Subset of `LiveMasterFeature` whose subscription requires an active live-room
+* WebSocket connection. Mirrors `@bilibili-notify/push`'s `LIVE_ROOM_MASTERS`.
+*/
+const LIVE_ROOM_MASTER_KEYS = [
+	"live",
+	"liveEnd",
+	"liveGuardBuy",
+	"superchat",
+	"wordcloud",
+	"liveSummary"
+];
+//#endregion
+//#region src/room-context.ts
+/** Guard-level → official Bilibili captain/supervisor/governor image URLs. */
+const GUARD_LEVEL_IMG = {
+	[GuardLevel.None]: "",
+	[GuardLevel.Jianzhang]: "https://s1.hdslb.com/bfs/static/blive/live-pay-mono/relation/relation/assets/captain-Bjw5Byb5.png",
+	[GuardLevel.Tidu]: "https://s1.hdslb.com/bfs/static/blive/live-pay-mono/relation/relation/assets/supervisor-u43ElIjU.png",
+	[GuardLevel.Zongdu]: "https://s1.hdslb.com/bfs/static/blive/live-pay-mono/relation/relation/assets/governor-DpDXKEdA.png"
+};
+/**
+* Shared room-level infrastructure surface. Stores all engine-injected deps,
+* the per-room listener registry, and the periodic-timer registry; offers the
+* lifecycle / predicate / disposal primitives consumed by both
+* {@link import("./listener-manager").ListenerManager} and
+* {@link import("./room-session").RoomSession}.
+*
+* The data-fetch / card-render / time-format helpers live in
+* {@link import("./room-helpers").RoomContextHelpers} (a subclass of this
+* class). The split keeps each file focused: this one handles state + WS
+* lifecycle, the helpers file wraps every external API/IO call.
+*/
+var RoomContextBase = class {
+	serviceCtx;
+	logger;
+	api;
+	push;
+	contentBuilder;
+	templateRenderer;
+	wordcloudGenerator;
+	liveSummaryRequester;
+	danmakuCollector;
+	/**
+	* 真实注入的渲染器引用,private 是因为外部应通过 `imageRenderer` getter 访问 ——
+	* 后者会在 `config.imageEnabled === false` 时返回 null,让所有
+	* `if (this.imageRenderer?.generateXxx)` 自然落入文字回退分支。
+	*/
+	_imageRenderer;
+	emitEngineError;
+	_emitLiveState;
+	_emitViewers;
+	config;
+	listenerRecord = {};
+	livePushTimerManager = /* @__PURE__ */ new Map();
+	disposed = false;
+	/** Cached protobuf type for INTERACT_WORD_V2 decoding (lazy-loaded). */
+	interactWord;
+	/**
+	* Set once the proto load/lookup has failed (missing/invalid
+	* `proto/interact_word.proto`) so we degrade gracefully instead of
+	* re-attempting + error-spamming on every INTERACT_WORD_V2 frame.
+	*/
+	interactWordUnavailable = false;
+	instanceId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+	constructor(opts) {
+		this.serviceCtx = opts.serviceCtx;
+		this.logger = opts.serviceCtx.logger;
+		this.api = opts.api;
+		this.push = opts.push;
+		this.contentBuilder = opts.contentBuilder;
+		this.templateRenderer = opts.templateRenderer;
+		this.wordcloudGenerator = opts.wordcloudGenerator;
+		this.liveSummaryRequester = opts.liveSummaryRequester;
+		this.danmakuCollector = opts.danmakuCollector;
+		this._imageRenderer = opts.imageRenderer;
+		this.config = opts.config;
+		this.emitEngineError = opts.emitEngineError;
+		this._emitLiveState = opts.emitLiveState;
+		this._emitViewers = opts.emitViewers;
+	}
+	/**
+	* 安全调用方:adapter 未注入时静默 no-op,业务代码无需在调用点判空。
+	*/
+	emitLiveState(uid, status) {
+		this._emitLiveState?.(uid, status);
+	}
+	/**
+	* 同型 no-op 安全调用方。room-session 已做 per-UID 节流,这里只是分发。
+	*/
+	emitViewers(uid, viewers) {
+		this._emitViewers?.(uid, viewers);
+	}
+	/** 受 `config.imageEnabled` 门控的渲染器视图;关闭时返回 null。 */
+	get imageRenderer() {
+		return this.config.imageEnabled === false ? null : this._imageRenderer;
+	}
+	updateConfig(config) {
+		this.config = config;
+	}
+	isDisposed() {
+		return this.disposed;
+	}
+	setDisposed(value) {
+		this.disposed = value;
+	}
+	getListenerCount() {
+		return Object.keys(this.listenerRecord).length;
+	}
+	logSideEffectState(stage) {
+		this.logger.debug(`[conn] [live:${this.instanceId}] ${stage} listeners=${this.getListenerCount()} timers=${this.livePushTimerManager.size} disposed=${this.disposed}`);
+	}
+	hasTargets(sub, ...types) {
+		return types.some((t) => (sub.target?.[t]?.length ?? 0) > 0);
+	}
+	isSubscribed(sub, type) {
+		return sub[type];
+	}
+	needsLiveMonitor(sub) {
+		return LIVE_ROOM_MASTER_KEYS.some((k) => this.isSubscribed(sub, k)) || sub.customSpecialDanmakuUsers.enable || sub.customSpecialUsersEnterTheRoom.enable;
+	}
+	closeListener(roomId) {
+		const listener = this.listenerRecord[roomId];
+		if (!listener) {
+			this.logger.debug(`[conn] 直播间 [${roomId}] 连接不存在，跳过关闭`);
+			return;
+		}
+		if (listener.closed) {
+			this.logger.debug(`[conn] 直播间 [${roomId}] 连接已被远端断开`);
+			delete this.listenerRecord[roomId];
+			return;
+		}
+		listener.close();
+		delete this.listenerRecord[roomId];
+		this.logger.info(`[conn] 直播间 [${roomId}] 连接已关闭`);
+		this.logSideEffectState(`listener:closed room=${roomId}`);
+	}
+	clearListeners() {
+		this.logSideEffectState("listeners:before-clear");
+		for (const key of Object.keys(this.listenerRecord)) this.closeListener(key);
+		this.logSideEffectState("listeners:after-clear");
+	}
+	clearPushTimers() {
+		this.logSideEffectState("timers:before-clear");
+		for (const [, timer] of this.livePushTimerManager) timer?.();
+		this.livePushTimerManager.clear();
+		this.logSideEffectState("timers:after-clear");
+	}
+	stopMonitoring(reason, roomId) {
+		if (roomId) {
+			this.logger.error(`[conn] [${roomId}] ${reason}，已停止该房间的监测`);
+			this.closeListener(roomId);
+			const timer = this.livePushTimerManager.get(roomId);
+			if (timer) {
+				timer();
+				this.livePushTimerManager.delete(roomId);
+			}
+			this.emitEngineError(`[${roomId}] ${reason}`);
+			return;
+		}
+		this.logger.error(`[conn] ${reason}，直播监测已停止`);
+		this.clearListeners();
+		this.clearPushTimers();
+		this.emitEngineError(reason);
+	}
+};
+//#endregion
+//#region src/types.ts
+let LiveType = /* @__PURE__ */ function(LiveType) {
+	LiveType[LiveType["NotLiveBroadcast"] = 0] = "NotLiveBroadcast";
+	LiveType[LiveType["StartBroadcasting"] = 1] = "StartBroadcasting";
+	LiveType[LiveType["LiveBroadcast"] = 2] = "LiveBroadcast";
+	LiveType[LiveType["StopBroadcast"] = 3] = "StopBroadcast";
+	LiveType[LiveType["FirstLiveBroadcast"] = 4] = "FirstLiveBroadcast";
+	return LiveType;
+}({});
+//#endregion
+//#region src/room-helpers.ts
+/**
+* Extends {@link RoomContextBase} with the data-fetch / card-render /
+* time-format helpers — every call here either hits the Bilibili HTTP API or
+* the optional `ImageRenderer`. Keeping them on a separate class keeps the
+* base file focused on state / lifecycle while preserving the inheritance
+* chain so {@link RoomSession} sees a single `ctx.foo()` API surface.
+*/
+var RoomContext = class extends RoomContextBase {
+	/**
+	* Bring up the WebSocket listener for `roomId`.
+	*
+	* L4: returns `true` iff there is an active listener for the room *after*
+	* this call — either freshly created OR already present (the latter lets a
+	* reconnect that races with a backoff-window restore treat the room as
+	* recovered). Returns `false` on every failure mode so the reconnect caller
+	* only resets its backoff on a real success instead of the old
+	* void-swallow that recorded "reconnected" with no listener attached.
+	*/
+	async startLiveRoomListener(roomId, handler, shouldAbort) {
+		const aborted = () => this.isDisposed() || shouldAbort?.() === true;
+		if (aborted()) return false;
+		const roomIdNum = Number.parseInt(roomId, 10);
+		if (!Number.isFinite(roomIdNum) || roomIdNum <= 0) {
+			this.logger.error(`[conn] roomId 非法（"${roomId}"），跳过 listener 创建。请检查订阅配置或用户是否开通直播间`);
+			return false;
+		}
+		if (this.listenerRecord[roomId]) {
+			this.logger.warn(`[conn] 直播间 [${roomId}] 连接已存在，跳过创建`);
+			return true;
+		}
+		const cookiesStr = this.api.getCookiesHeader();
+		let mySelfInfo;
+		try {
+			mySelfInfo = await this.api.getMyselfInfo();
+		} catch (e) {
+			const message = e.message ?? String(e);
+			this.logger.warn(`[conn] 获取个人信息异常，房间 [${roomId}]：${message}`);
+			this.emitEngineError(`[${roomId}] 获取个人信息异常：${message}`);
+			return false;
+		}
+		if (mySelfInfo.code !== 0 || !mySelfInfo.data) {
+			this.logger.warn(`[conn] 获取个人信息失败 code=${mySelfInfo.code}，无法创建直播间 [${roomId}] 连接`);
+			this.emitEngineError(`[${roomId}] 获取个人信息失败 code=${mySelfInfo.code}`);
+			return false;
+		}
+		if (aborted()) return false;
+		const listener = startListen(roomIdNum, handler, { ws: {
+			headers: { Cookie: cookiesStr },
+			uid: mySelfInfo.data.mid
+		} });
+		if (aborted()) {
+			listener.close();
+			return false;
+		}
+		this.listenerRecord[roomId] = listener;
+		this.logger.info(`[conn] 直播间 [${roomId}] 连接已建立`);
+		this.logSideEffectState(`listener:created room=${roomId}`);
+		return true;
+	}
+	/** Fetch live-room info; on failure, notifies admin + tears down this room. */
+	async getLiveRoomInfo(roomId) {
+		try {
+			return (await this.api.getLiveRoomInfo(roomId)).data;
+		} catch (e) {
+			this.logger.error(`[conn] 获取直播间信息失败：${e.message}`);
+			await this.push.sendPrivateMsg(`获取直播间 [${roomId}] 信息失败：${e.message}，已停止该房间监测`);
+			this.stopMonitoring("获取直播间信息失败", roomId);
+			return;
+		}
+	}
+	/**
+	* Fetch + project a `MasterInfo` snapshot. Carries forward `liveOpenFollowerNum`
+	* across mid-session refreshes so that the live-end card reports an accurate
+	* follower delta.
+	*/
+	async getMasterInfo(uid, previous, liveType) {
+		const data = (await this.api.getMasterInfo(uid)).data;
+		let liveOpenFollowerNum;
+		let liveEndFollowerNum;
+		let liveFollowerChange;
+		if (liveType === 1 || liveType === 4) {
+			liveOpenFollowerNum = data.follower_num;
+			liveEndFollowerNum = data.follower_num;
+			liveFollowerChange = 0;
+		} else {
+			liveOpenFollowerNum = previous?.liveOpenFollowerNum ?? data.follower_num;
+			liveEndFollowerNum = data.follower_num;
+			liveFollowerChange = liveEndFollowerNum - liveOpenFollowerNum;
+		}
+		return {
+			username: data.info.uname,
+			userface: data.info.face,
+			roomId: data.room_id,
+			liveOpenFollowerNum,
+			liveEndFollowerNum,
+			liveFollowerChange,
+			medalName: data.medal_name
+		};
+	}
+	/** Fire-and-forget push wrapper; logs + drops any rejection. */
+	safeBroadcast(uid, content, type) {
+		this.push.broadcastToTargets(uid, content, type).catch((e) => {
+			this.logger.error(`[push] 推送失败 uid=${uid} type=${type}：${e.message}`);
+		});
+	}
+	/**
+	* Push a "live start / live ongoing / live end" notification card. Generates
+	* an image via {@link ImageRenderer.generateLiveCard} when available; falls
+	* back to plain text on failure.
+	*/
+	async sendLiveNotifyCard(params) {
+		const { liveType, liveData, liveRoomInfo, master, cardStyle, uid, notifyMsg } = params;
+		let buffer;
+		if (this.imageRenderer?.generateLiveCard) try {
+			buffer = await this.imageRenderer.generateLiveCard(liveRoomInfo, master.username, master.userface, liveData, liveType, cardStyle?.enable ? cardStyle : void 0);
+		} catch (e) {
+			this.logger.error(`[image] 生成直播图片失败：${e.message}，降级为文字推送`);
+		}
+		if (this.isDisposed()) return;
+		const pushType = liveType === 1 ? 3 : liveType === 3 ? 9 : 0;
+		if (!buffer) {
+			this.logger.debug(`[push] [${master.username}] 无图片，降级为文字推送`);
+			const fallbackMsg = this.contentBuilder.message([this.contentBuilder.text(notifyMsg || `直播通知 - ${master.username}`)]);
+			await this.push.broadcastToTargets(uid, fallbackMsg, pushType);
+			return;
+		}
+		const msg = this.contentBuilder.message([this.contentBuilder.image(buffer, "image/jpeg"), this.contentBuilder.text(notifyMsg || "")]);
+		await this.push.broadcastToTargets(uid, msg, pushType);
+	}
+	/** Format `dateString` (yyyy-MM-dd HH:mm:ss UTC+8) as elapsed-time text. */
+	async getTimeDifference(dateString) {
+		if (this.imageRenderer?.getTimeDifference) return this.imageRenderer.getTimeDifference(dateString);
+		const start = DateTime.fromFormat(dateString, "yyyy-MM-dd HH:mm:ss");
+		const diff = DateTime.now().diff(start, ["hours", "minutes"]);
+		const hours = Math.floor(diff.hours);
+		const minutes = Math.floor(diff.minutes % 60);
+		return hours > 0 ? `${hours}小时${minutes}分钟` : `${minutes}分钟`;
+	}
+	/**
+	* Decode a base64-encoded INTERACT_WORD_V2 protobuf payload.
+	*
+	* P0-4: 此前用 `resolve(__dirname, "./proto/interact_word.proto")` —— (a) 该
+	* .proto 文件从未随包提交、tsdown 也不拷进 lib;(b) ESM(.mjs)产物里裸
+	* `__dirname` 为 undefined。两者叠加导致每个 INTERACT_WORD_V2 帧必抛,
+	* "特别关注用户进房"特性在双端构建里全死。
+	*
+	* 现:`__dirname` 改 `import.meta.url`(与 routes/health.ts 同款,tsdown
+	* cjs/esm 双产物都正确);proto 缺失/损坏时**优雅降级**——只在首次告警一
+	* 次并置 `interactWordUnavailable`,后续帧直接返回 `{}`(调用方
+	* onInteractWordV2 对空对象天然 no-op:`msgType==="1"` 为 false,零误推),
+	* 不再每帧崩/刷屏。
+	*
+	* 注:让该特性真正可用仍需在 `src/proto/interact_word.proto` 放入**经核实
+	* 的**权威 schema(`bilibili.live.xuserreward.v1.InteractWord`)并在打包时
+	* 拷进 `lib/proto/`——字段号必须来自可信源,不可臆造,故作为独立后续任务。
+	*/
+	async decodeBase64PB(base64) {
+		if (this.interactWordUnavailable) return {};
+		if (!this.interactWord) try {
+			const protoPath = resolve(dirname(fileURLToPath(import.meta.url)), "./proto/interact_word.proto");
+			const root = await protobuf.load(protoPath);
+			this.interactWord = root.lookupType("bilibili.live.xuserreward.v1.InteractWord");
+		} catch (e) {
+			this.interactWordUnavailable = true;
+			this.logger.warn(`[live] INTERACT_WORD_V2 解码不可用,"特别关注用户进房"已禁用:缺少或无法加载 proto/interact_word.proto (${e.message})`);
+			return {};
+		}
+		try {
+			const buffer = Uint8Array.from(Buffer.from(base64, "base64"));
+			const message = this.interactWord.decode(buffer);
+			return this.interactWord.toObject(message, {
+				longs: String,
+				enums: String,
+				defaults: true
+			});
+		} catch (e) {
+			this.logger.warn(`[live] INTERACT_WORD_V2 protobuf 解码失败,跳过该帧: ${e.message}`);
+			return {};
+		}
+	}
+};
+//#endregion
+//#region src/template-renderer.ts
+/**
+* Plain string-substitution based template renderer for live-related notification
+* text. Mirrors the per-occurrence templates supported in the koishi schema:
+*
+* - `customLiveStart` / `customLive` / `customLiveEnd`
+* - `customGuardBuy.guardBuyMsg`
+* - `customSpecialDanmakuUsers.msgTemplate`
+* - `customSpecialUsersEnterTheRoom.msgTemplate`
+*
+* The variable syntax follows the existing `-name` / `-time` / `-watched` style
+* (NOT the `{key}` syntax used by `@bilibili-notify/internal`'s `interpolate`),
+* because that's what users have in their existing Koishi configs and we keep
+* 1:1 backward compatibility.
+*/
+/** Defaults applied when neither sub-level nor global config provides a template. */
+const DEFAULT_LIVE_TEMPLATES = {
+	liveStart: "-name 开播啦，当前粉丝数：-follower\n-link",
+	liveOngoing: "-name 正在直播，已播 -time，累计观看：-watched\n-link",
+	liveEnd: "-name 下播啦，本次直播了 -time，粉丝变化 -follower_change",
+	liveSummaryFallback: "弹幕总结"
+};
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* 单遍替换所有变量 token,再把 `\n` 转义展开为真换行。
+*
+* P2:此前 `for…replaceAll` 顺序替换有两个缺陷 ——
+*  1. **token 注入**:用户可控值(uname / 弹幕内容)含 `-link`/`-time` 时
+*     会被后续轮次再次替换;
+*  2. **前缀吞噬**:`-follower` 先于 `-follower_change` 替换,把后者的
+*     `-follower` 段吃掉只剩 `_change`。
+* 改为基于原始模板的**单遍正则**:token 按长度降序进 alternation(最长优先
+* 匹配),每个 token 恰好替换一次且替换值不再被回扫 → 杜绝注入与吞噬。
+*/
+function applyTemplate(template, vars) {
+	const keys = Object.keys(vars).sort((a, b) => b.length - a.length);
+	if (keys.length === 0) return template.replaceAll("\\n", "\n");
+	const re = new RegExp(keys.map(escapeRegExp).join("|"), "g");
+	return template.replace(re, (m) => vars[m] ?? m).replaceAll("\\n", "\n");
+}
+/**
+* Format follower-change as a signed magnitude string with a 1万 (10K) cutoff,
+* mirroring live-service's inline formatting.
+*/
+function formatFollowerChange(n) {
+	if (n > 0) return n >= 1e4 ? `+${(n / 1e4).toFixed(1)}万` : `+${n}`;
+	if (n <= -1e4) return `${(n / 1e4).toFixed(1)}万`;
+	return n.toString();
+}
+/** Format follower count, abbreviating ≥10K to `X.X万`. */
+function formatFollowerCount(n) {
+	return n >= 1e4 ? `${(n / 1e4).toFixed(1)}万` : n.toString();
+}
+/** Build the canonical room link from `LiveRoomInfo.data` style fields. */
+function buildRoomLink(info) {
+	return `https://live.bilibili.com/${info.short_id === 0 ? info.room_id : info.short_id}`;
+}
+/**
+* Resolve the effective template string for a sub at a given occurrence,
+* preferring per-sub override → global config → built-in default.
+*/
+function resolveCustomLive(subCustom, globalCustom, field, fallback) {
+	return subCustom[field] ?? globalCustom?.[field] ?? fallback;
+}
+var LiveTemplateRenderer = class {
+	/** Compose the "开播" notification text for a sub. */
+	renderLiveStart(params) {
+		return applyTemplate(resolveCustomLive(params.sub.customLiveMsg, params.globalCustom, "customLiveStart", DEFAULT_LIVE_TEMPLATES.liveStart), {
+			"-name": params.master.username,
+			"-time": params.diffTime,
+			"-follower": params.followerNum,
+			"-link": params.roomLink
+		});
+	}
+	/** Compose the periodic "正在直播" notification text. */
+	renderLiveOngoing(params) {
+		return applyTemplate(resolveCustomLive(params.sub.customLiveMsg, params.globalCustom, "customLive", DEFAULT_LIVE_TEMPLATES.liveOngoing), {
+			"-name": params.master.username,
+			"-time": params.diffTime,
+			"-watched": params.watched,
+			"-link": params.roomLink
+		});
+	}
+	/** Compose the "下播" notification text. */
+	renderLiveEnd(params) {
+		return applyTemplate(resolveCustomLive(params.sub.customLiveMsg, params.globalCustom, "customLiveEnd", DEFAULT_LIVE_TEMPLATES.liveEnd), {
+			"-name": params.master.username,
+			"-time": params.diffTime,
+			"-follower_change": formatFollowerChange(params.followerChange)
+		});
+	}
+	/**
+	* Compose the "上舰" notification text using the effective custom-guard
+	* config (resolved by listener-manager).
+	*/
+	renderGuardBuy(params) {
+		return applyTemplate(params.guardBuyConfig.guardBuyMsg ?? "", {
+			"-uname": params.uname,
+			"-mname": params.master?.username ?? "",
+			"-guard": params.giftName
+		});
+	}
+	/** Compose the "特别关注弹幕" notification text. */
+	renderSpecialDanmaku(params) {
+		return applyTemplate(params.template, {
+			"-mastername": params.master?.username ?? "",
+			"-uname": params.uname,
+			"-msg": params.content
+		});
+	}
+	/** Compose the "特别关注进入直播间" notification text. */
+	renderSpecialUserEnter(params) {
+		return applyTemplate(params.template, {
+			"-mastername": params.master?.username ?? "",
+			"-uname": params.uname
+		});
+	}
+	/**
+	* Compose the templated "弹幕总结" text used as the fallback when AI
+	* summarisation is unavailable. Variables: `-dmc` (sender count), `-mdn`
+	* (master medal name), `-dca` (total danmaku), `-un1..5` (top usernames),
+	* `-dc1..5` (top counts).
+	*/
+	renderLiveSummary(params) {
+		const top = params.topSenders;
+		const at = (i) => top[i] ?? ["", 0];
+		return applyTemplate(params.template, {
+			"-dmc": `${params.senderCount}`,
+			"-mdn": params.master?.medalName ?? "",
+			"-dca": `${params.danmakuCount}`,
+			"-un1": at(0)[0],
+			"-dc1": `${at(0)[1]}`,
+			"-un2": at(1)[0],
+			"-dc2": `${at(1)[1]}`,
+			"-un3": at(2)[0],
+			"-dc3": `${at(2)[1]}`,
+			"-un4": at(3)[0],
+			"-dc4": `${at(3)[1]}`,
+			"-un5": at(4)[0],
+			"-dc5": `${at(4)[1]}`
+		});
+	}
+};
+//#endregion
+//#region src/room-session-base.ts
+/**
+* Cooldown window between accepting `onLiveStart` / `onLiveEnd` events; the
+* Bilibili WS sometimes fires duplicates for the same transition.
+*/
+const LIVE_EVENT_COOLDOWN = 10 * 1e3;
+/**
+* Base class for {@link import("./room-session").RoomSession}, holding all
+* per-room mutable state and the high-level lifecycle / transition logic
+* (bootstrap, periodic-timer arm/cancel, live-end pipeline). Event handlers
+* (`onLiveStart`, `onIncomeSuperChat`, etc.) live in the subclass.
+*
+* State fields are `protected` so the subclass can read & mutate them
+* directly when handling MsgHandler events.
+*/
+var RoomSessionBase = class {
+	ctx;
+	sub;
+	liveTime;
+	liveStatus = false;
+	liveRoomInfo;
+	masterInfo;
+	liveData = { likedNum: "0" };
+	pushAtTimeTimer = null;
+	lastLiveStart = 0;
+	lastLiveEnd = 0;
+	constructor(ctx, sub) {
+		this.ctx = ctx;
+		this.sub = sub;
+	}
+	/** Whether the underlying B-station room is currently broadcasting. */
+	get isLive() {
+		return this.liveStatus;
+	}
+	/**
+	* 唯一允许翻转 `liveStatus` 的入口。只在真实 transition 时通过 RoomContext
+	* 推送 `live-state-changed` 事件,前端的"正在直播"面板靠它实时收敛。
+	* 直接赋值 `this.liveStatus = ...` 会绕过这里,**不要这样做**。
+	*/
+	setLiveStatus(next) {
+		if (this.liveStatus === next) return;
+		this.liveStatus = next;
+		this.ctx.emitLiveState(this.sub.uid, next ? "live" : "idle");
+	}
+	/**
+	* Read-only diagnostic snapshot for routes / dashboards. Includes `uid`,
+	* `roomId`, and — when `liveRoomInfo` was successfully fetched — `title`,
+	* `cover`, `areaName`, `startedAt`. Returns undefined fields rather than
+	* partial data so consumers can render fallbacks deterministically.
+	*/
+	getLiveSnapshot() {
+		const w = this.liveData.watchedNum;
+		const viewers = typeof w === "number" ? String(w) : w;
+		return {
+			uid: this.sub.uid,
+			roomId: this.sub.roomId,
+			isLive: this.liveStatus,
+			title: this.liveRoomInfo?.title,
+			cover: this.liveRoomInfo?.user_cover || this.liveRoomInfo?.keyframe || void 0,
+			areaName: this.liveRoomInfo?.area_name,
+			startedAt: this.liveRoomInfo?.live_time || void 0,
+			viewers: viewers && viewers !== "暂未获取到" ? viewers : void 0
+		};
+	}
+	/**
+	* Open the WS connection (via `RoomContext.startLiveRoomListener`), pull
+	* the initial live-room snapshot, and — if the room is already live —
+	* kick off the `restartPush` branch + arm the periodic timer.
+	*/
+	async bootstrap() {
+		if (!await this.ctx.startLiveRoomListener(this.sub.roomId, this.buildHandler())) {
+			await this.ctx.push.sendPrivateMsg(`直播间 [${this.sub.roomId}] 弹幕连接建立失败，已停止该房间监测`);
+			this.ctx.closeListener(this.sub.roomId);
+			return;
+		}
+		if (!await this.useLiveRoomInfo(4) || !await this.useMasterInfo(4) || !this.liveRoomInfo || !this.masterInfo) {
+			await this.ctx.push.sendPrivateMsg("获取直播间信息失败，启动直播间弹幕检测失败");
+			this.ctx.closeListener(this.sub.roomId);
+			return;
+		}
+		this.ctx.logger.debug(`[stat] 当前粉丝数：${this.masterInfo.liveOpenFollowerNum}`);
+		if (this.liveRoomInfo.live_status === 1) {
+			this.liveTime = this.liveRoomInfo.live_time;
+			const watched = String(this.liveData.watchedNum ?? "暂未获取到");
+			this.liveData.watchedNum = watched;
+			const diffTime = await this.ctx.getTimeDifference(this.liveTime);
+			const roomLink = buildRoomLink(this.liveRoomInfo);
+			const liveMsg = this.ctx.templateRenderer.renderLiveOngoing({
+				sub: this.sub,
+				globalCustom: this.ctx.config.customLiveMsg,
+				master: this.masterInfo,
+				diffTime,
+				watched,
+				roomLink
+			});
+			if (this.sub.restartPush ?? this.ctx.config.restartPush) await this.ctx.sendLiveNotifyCard({
+				liveType: 2,
+				liveData: this.liveData,
+				liveRoomInfo: this.liveRoomInfo,
+				master: this.masterInfo,
+				cardStyle: this.sub.customCardStyle,
+				uid: this.sub.uid,
+				notifyMsg: liveMsg
+			});
+			this.setLiveStatus(true);
+			this.armPeriodicTimer();
+		}
+	}
+	async useLiveRoomInfo(liveType) {
+		const data = await this.ctx.getLiveRoomInfo(this.sub.roomId);
+		if (!data?.uid) return false;
+		if (liveType === 1 || liveType === 4) {
+			this.liveRoomInfo = data;
+			return true;
+		}
+		this.liveRoomInfo = {
+			...data,
+			live_time: this.liveRoomInfo?.live_time ?? data.live_time
+		};
+		return true;
+	}
+	async useMasterInfo(liveType) {
+		try {
+			this.masterInfo = await this.ctx.getMasterInfo(this.liveRoomInfo?.uid.toString() ?? this.sub.uid, this.masterInfo, liveType);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Live 配置 `pushTime` 热更后调用:重新按当前(可能已变更的) `pushTime`
+	* arm 定时器。仅对正在直播的房间生效,因为只有 live 状态下才会有 timer。
+	*
+	* 注意:`setInterval` 句柄的 ms 参数是 immutable,只能 dispose 重建。
+	*/
+	rearmPeriodicTimer() {
+		if (!this.isLive) return;
+		this.cancelPeriodicTimer();
+		this.armPeriodicTimer();
+	}
+	armPeriodicTimer() {
+		const effPushTime = this.sub.pushTime ?? this.ctx.config.pushTime;
+		if (effPushTime === 0 || this.pushAtTimeTimer) return;
+		this.pushAtTimeTimer = this.ctx.serviceCtx.setInterval(() => this.tickPushAtTime(), effPushTime * 1e3 * 60 * 60);
+		this.ctx.livePushTimerManager.set(this.sub.roomId, () => this.pushAtTimeTimer?.dispose());
+		this.ctx.logSideEffectState(`timer:created room=${this.sub.roomId}`);
+	}
+	cancelPeriodicTimer() {
+		if (!this.pushAtTimeTimer) return;
+		this.pushAtTimeTimer.dispose();
+		this.pushAtTimeTimer = null;
+		this.ctx.livePushTimerManager.delete(this.sub.roomId);
+		this.ctx.logSideEffectState(`timer:deleted room=${this.sub.roomId}`);
+	}
+	/** Periodic "正在直播" tick (callback for `setInterval`). */
+	async tickPushAtTime() {
+		if (!await this.useLiveRoomInfo(2) || !this.liveRoomInfo) {
+			this.ctx.stopMonitoring("获取直播间信息失败，推送直播卡片失败", this.sub.roomId);
+			return;
+		}
+		if (this.liveRoomInfo.live_status === 0 || this.liveRoomInfo.live_status === 2) {
+			this.ctx.logger.warn(`[live] 直播间 [${this.sub.roomId}] 检测到已下播但未收到 onLiveEnd 事件，进入兜底处理`);
+			await this.ctx.push.sendPrivateMsg(`直播间 [${this.sub.roomId}] 已下播但未收到 WS 下播事件，已自动触发兜底总结`);
+			await this.handleLiveEnd("polling");
+			return;
+		}
+		if (!await this.useMasterInfo(2) || !this.masterInfo) return;
+		this.liveTime = this.liveRoomInfo.live_time;
+		const watched = String(this.liveData.watchedNum ?? "暂未获取到");
+		this.liveData.watchedNum = watched;
+		const diffTime = await this.ctx.getTimeDifference(this.liveTime);
+		const roomLink = buildRoomLink(this.liveRoomInfo);
+		const liveMsg = this.ctx.templateRenderer.renderLiveOngoing({
+			sub: this.sub,
+			globalCustom: this.ctx.config.customLiveMsg,
+			master: this.masterInfo,
+			diffTime,
+			watched,
+			roomLink
+		});
+		await this.ctx.sendLiveNotifyCard({
+			liveType: 2,
+			liveData: this.liveData,
+			liveRoomInfo: this.liveRoomInfo,
+			master: this.masterInfo,
+			cardStyle: this.sub.customCardStyle,
+			uid: this.sub.uid,
+			notifyMsg: liveMsg
+		});
+	}
+	/**
+	* Live-end pipeline (shared by the WS `onLiveEnd` event and the polling
+	* fallback in {@link tickPushAtTime}).
+	*
+	* Order: cancel periodic timer → refresh room/master info → push live-end
+	* card → kick off wordcloud + summary → drain danmaku buffer.
+	*/
+	async handleLiveEnd(source) {
+		if (!this.liveStatus) {
+			this.ctx.logger.warn(`[live] 直播间 [${this.sub.roomId}] 已经是下播状态，忽略 (source=${source})`);
+			return;
+		}
+		this.cancelPeriodicTimer();
+		if (!await this.useLiveRoomInfo(3) || !await this.useMasterInfo(3) || !this.liveRoomInfo || !this.masterInfo) {
+			this.setLiveStatus(false);
+			this.ctx.danmakuCollector.clear(this.sub.roomId);
+			if (this.ctx.isDisposed()) return;
+			this.ctx.stopMonitoring("获取直播间信息失败，推送直播下播卡片失败", this.sub.roomId);
+			return;
+		}
+		this.setLiveStatus(false);
+		this.ctx.logger.debug(`[stat] 开播时粉丝数：${this.masterInfo.liveOpenFollowerNum}，下播时粉丝数：${this.masterInfo.liveEndFollowerNum}，粉丝数变化：${this.masterInfo.liveFollowerChange}`);
+		this.liveTime = this.liveRoomInfo.live_time || DateTime.now().toFormat("yyyy-MM-dd HH:mm:ss");
+		const diffTime = await this.ctx.getTimeDifference(this.liveTime);
+		this.liveData.fansChanged = this.masterInfo.liveFollowerChange;
+		const liveEndMsg = this.ctx.templateRenderer.renderLiveEnd({
+			sub: this.sub,
+			globalCustom: this.ctx.config.customLiveMsg,
+			master: this.masterInfo,
+			diffTime,
+			followerChange: this.masterInfo.liveFollowerChange
+		});
+		try {
+			if (this.ctx.isSubscribed(this.sub, "liveEnd")) await this.ctx.sendLiveNotifyCard({
+				liveType: 3,
+				liveData: this.liveData,
+				liveRoomInfo: this.liveRoomInfo,
+				master: this.masterInfo,
+				cardStyle: this.sub.customCardStyle,
+				uid: this.sub.uid,
+				notifyMsg: liveEndMsg
+			});
+			await this.dispatchWordCloudAndSummary(this.sub.customLiveSummary.liveSummary || this.ctx.config.liveSummaryDefault);
+		} finally {
+			this.ctx.danmakuCollector.clear(this.sub.roomId);
+			this.ctx.danmakuCollector.registerRoom(this.sub.roomId);
+		}
+	}
+	/**
+	* Run wordcloud + AI live-summary in parallel and dispatch whichever
+	* succeeded. Skipped entirely when neither feature is subscribed.
+	*/
+	async dispatchWordCloudAndSummary(customLiveSummary) {
+		const wantWordcloud = this.ctx.isSubscribed(this.sub, "wordcloud");
+		const wantSummary = this.ctx.isSubscribed(this.sub, "liveSummary");
+		if (!wantWordcloud && !wantSummary) return;
+		this.ctx.logger.debug(`[wordcloud] 开始制作下播总结 wordcloud=${wantWordcloud} summary=${wantSummary}`);
+		const snapshot = this.ctx.danmakuCollector.snapshot(this.sub.roomId);
+		const [img, summary] = await Promise.all([wantWordcloud ? this.ctx.wordcloudGenerator.generate(snapshot.sortedWords, this.masterInfo?.username ?? "", this.masterInfo?.userface) : Promise.resolve(void 0), wantSummary ? this.ctx.liveSummaryRequester.generate({
+			senderRecord: snapshot.senderRecord,
+			sortedWords: snapshot.sortedWords,
+			master: this.masterInfo,
+			customLiveSummary,
+			aiOverride: this.sub.aiOverride
+		}) : Promise.resolve(void 0)]);
+		if (this.ctx.isDisposed()) return;
+		const wcMsg = img ? this.ctx.contentBuilder.image(img, "image/jpeg") : void 0;
+		const summaryMsg = summary ? this.ctx.contentBuilder.text(summary) : void 0;
+		if (wcMsg) await this.ctx.push.broadcastToTargets(this.sub.uid, wcMsg, 5);
+		if (summaryMsg) await this.ctx.push.broadcastToTargets(this.sub.uid, summaryMsg, 10);
+	}
+};
+//#endregion
+//#region src/room-session.ts
+/**
+* One {@link RoomSession} per UID/room actively being monitored.
+*
+* Extends {@link RoomSessionBase} (state + lifecycle + transitions) with the
+* {@link MsgHandler} factory and the per-event handlers (`onLiveStart`,
+* `onIncomeDanmu`, `onIncomeSuperChat`, `onGuardBuy`, `onLiveEnd`, `onError`,
+* `onWatchedChange`, `onLikedChange`, plus the `INTERACT_WORD_V2` raw branch).
+*
+* Each handler reads / mutates the protected state defined on the base.
+* `bootstrap()` (defined on the base) opens the WS connection and arms the
+* periodic timer if the room is already live; subsequent state transitions
+* are driven by the events routed through these handlers.
+*/
+/** Dashboard 端期望的"实时观看人数"采样间隔。B 站每几秒推一帧 WATCHED_CHANGE,
+* 这里 per-UID 门控成 2s 最多一次,够人眼感知,WS 不会刷屏。 */
+const VIEWERS_EMIT_THROTTLE_MS = 2e3;
+/**
+* onError 触发后的退避重连节奏(单位 ms)。失败时按下标顺序消耗,直到耗尽 → 真正放弃。
+* 重连成功后 `reconnectAttempts` 复位到 0,后续新一轮 onError 重新从 1s 开始。
+*/
+const RECONNECT_BACKOFF_MS = [
+	1e3,
+	2e3,
+	4e3,
+	8e3,
+	16e3
+];
+var RoomSession = class extends RoomSessionBase {
+	lastViewersEmitMs = 0;
+	/**
+	* 当前 RoomSession 是否已被外层(stopForUid / disposeAll / liveEnd 主动关闭)取消。
+	* 一旦设为 true,onError 跳过重连。listener-manager.stopForUid 在 closeListener
+	* 之前调用 cancel() 设置。
+	*/
+	cancelled = false;
+	reconnectAttempts = 0;
+	/**
+	* L1 单飞守卫:并发 onError(WS 错误常突发多帧)若都进入重连路径,会各自
+	* closeListener + 退避 + startLiveRoomListener,装回多个 listener。一旦一个
+	* onError 拿到重连权,其余直接返回。
+	*/
+	reconnecting = false;
+	/** L3:退避 sleep 的 Disposable + 唤醒句柄,cancel/teardown 时清掉,不留回调到 expiry。 */
+	reconnectTimer;
+	reconnectWake;
+	/** 外层主动停止 listener 时调用,阻止 onError 触发重连。 */
+	cancel() {
+		this.cancelled = true;
+		this.reconnecting = false;
+		this.clearReconnectSleep();
+	}
+	/** L3:dispose 退避定时器并唤醒重连循环,使其立刻重校 cancelled/disposed 后退出。 */
+	clearReconnectSleep() {
+		this.reconnectTimer?.dispose();
+		this.reconnectTimer = void 0;
+		this.reconnectWake?.();
+		this.reconnectWake = void 0;
+	}
+	buildHandler() {
+		const base = {
+			onError: () => this.onError(),
+			onIncomeDanmu: ({ body }) => this.onIncomeDanmu(body),
+			onIncomeSuperChat: ({ body }) => this.onIncomeSuperChat(body),
+			onWatchedChange: ({ body }) => {
+				this.liveData.watchedNum = body.text_small;
+				const now = Date.now();
+				if (now - this.lastViewersEmitMs >= VIEWERS_EMIT_THROTTLE_MS) {
+					this.lastViewersEmitMs = now;
+					this.ctx.emitViewers(this.sub.uid, body.text_small);
+				}
+			},
+			onLikedChange: ({ body }) => {
+				this.liveData.likedNum = body.count;
+			},
+			onGuardBuy: ({ body }) => this.onGuardBuy(body),
+			onLiveStart: () => this.onLiveStart(),
+			onLiveEnd: () => this.onLiveEnd()
+		};
+		if (!this.sub.customSpecialUsersEnterTheRoom.enable) return base;
+		return {
+			...base,
+			raw: { INTERACT_WORD_V2: (msg) => this.onInteractWordV2(msg) }
+		};
+	}
+	async onError() {
+		if (this.cancelled || this.ctx.isDisposed()) return;
+		if (this.reconnecting) return;
+		this.reconnecting = true;
+		try {
+			await this.reconnectLoop();
+		} finally {
+			this.reconnecting = false;
+		}
+	}
+	/**
+	* 退避重连循环(单飞,由 onError 持有)。`while` 取代旧的 `setTimeout(0)`
+	* 递归续链 —— 杜绝深栈递归 + 每步都丢弃的定时器 Disposable;每次 sleep 后
+	* 重校 cancelled/disposed,sleep 自身可被 cancel/teardown dispose。
+	*/
+	async reconnectLoop() {
+		while (this.reconnectAttempts < RECONNECT_BACKOFF_MS.length) {
+			if (this.cancelled || this.ctx.isDisposed()) return;
+			this.setLiveStatus(false);
+			this.cancelPeriodicTimer();
+			this.ctx.closeListener(this.sub.roomId);
+			const delay = RECONNECT_BACKOFF_MS[this.reconnectAttempts];
+			this.reconnectAttempts++;
+			this.ctx.logger.warn(`[conn] 直播间 [${this.sub.roomId}] 连接错误,${delay / 1e3}s 后重连(第 ${this.reconnectAttempts}/${RECONNECT_BACKOFF_MS.length} 次)`);
+			await this.sleepReconnect(delay);
+			if (this.cancelled || this.ctx.isDisposed()) return;
+			let ok = false;
+			try {
+				ok = await this.ctx.startLiveRoomListener(this.sub.roomId, this.buildHandler(), () => this.cancelled);
+			} catch (e) {
+				this.ctx.logger.warn(`[conn] 直播间 [${this.sub.roomId}] 重连发起异常:${e.message}`);
+			}
+			if (this.cancelled || this.ctx.isDisposed()) {
+				if (ok) this.ctx.closeListener(this.sub.roomId);
+				return;
+			}
+			if (ok) {
+				this.ctx.logger.info(`[conn] 直播间 [${this.sub.roomId}] 重连成功`);
+				this.reconnectAttempts = 0;
+				return;
+			}
+			this.ctx.logger.warn(`[conn] 直播间 [${this.sub.roomId}] 重连未成功,继续退避`);
+		}
+		this.reconnectAttempts = 0;
+		const msg = `直播间 [${this.sub.roomId}] 连接持续失败,重试 ${RECONNECT_BACKOFF_MS.length} 次后放弃监听`;
+		this.ctx.logger.error(`[conn] ${msg}`);
+		this.ctx.emitEngineError(msg);
+	}
+	/**
+	* L3:可被 {@link clearReconnectSleep} 取消的退避 sleep。dispose 时立即
+	* resolve,让 reconnectLoop 醒来重校 cancelled/disposed 后退出 —— 不再留
+	* 一个无法清除的延迟回调到 expiry。
+	*/
+	sleepReconnect(ms) {
+		return new Promise((resolve) => {
+			this.reconnectWake = resolve;
+			this.reconnectTimer = this.ctx.serviceCtx.setTimeout(() => {
+				this.reconnectTimer = void 0;
+				this.reconnectWake = void 0;
+				resolve();
+			}, ms);
+		});
+	}
+	onIncomeDanmu(body) {
+		if (this.ctx.isSubscribed(this.sub, "wordcloud") || this.ctx.isSubscribed(this.sub, "liveSummary")) this.ctx.danmakuCollector.recordDanmaku(this.sub.roomId, body.content, body.user.uname);
+		if (this.sub.customSpecialDanmakuUsers.enable && this.ctx.hasTargets(this.sub, "specialDanmaku") && this.sub.customSpecialDanmakuUsers.specialDanmakuUsers?.includes(body.user.uid.toString())) {
+			const text = this.ctx.templateRenderer.renderSpecialDanmaku({
+				template: this.sub.customSpecialDanmakuUsers.msgTemplate,
+				uname: body.user.uname,
+				master: this.masterInfo,
+				content: body.content
+			});
+			if (this.ctx.isDisposed()) return;
+			this.ctx.safeBroadcast(this.sub.uid, this.ctx.contentBuilder.message([this.ctx.contentBuilder.text(text)]), 7);
+		}
+	}
+	async onIncomeSuperChat(body) {
+		const collectsDanmaku = this.ctx.isSubscribed(this.sub, "wordcloud") || this.ctx.isSubscribed(this.sub, "liveSummary");
+		const pushesSC = this.ctx.isSubscribed(this.sub, "superchat");
+		if (!collectsDanmaku && !pushesSC) return;
+		if (collectsDanmaku) this.ctx.danmakuCollector.recordDanmaku(this.sub.roomId, body.content, body.user.uname);
+		if (!pushesSC) return;
+		const effMinScPrice = this.sub.minScPrice ?? this.ctx.config.minScPrice;
+		if (body.price < effMinScPrice) return;
+		const data = await this.ctx.api.getUserInfoInLive(body.user.uid.toString(), this.sub.uid);
+		if (data.code !== 0) {
+			const text = `【${this.masterInfo?.username ?? ""}的直播间】${body.user.uname}的SC:${body.content}（${body.price}元）`;
+			if (this.ctx.isDisposed()) return;
+			await this.ctx.push.broadcastToTargets(this.sub.uid, this.ctx.contentBuilder.message([this.ctx.contentBuilder.text(text)]), 6);
+			return;
+		}
+		if (this.ctx.imageRenderer?.generateSCCard) try {
+			const userInfo = data.data;
+			const buf = await this.ctx.imageRenderer.generateSCCard({
+				senderFace: userInfo.face,
+				senderName: userInfo.uname,
+				masterName: this.masterInfo?.username ?? "",
+				masterAvatarUrl: this.masterInfo?.userface ?? "",
+				text: body.content,
+				price: body.price
+			});
+			if (this.ctx.isDisposed()) return;
+			await this.ctx.push.broadcastToTargets(this.sub.uid, this.ctx.contentBuilder.image(buf, "image/jpeg"), 6);
+			return;
+		} catch (e) {
+			this.ctx.logger.error(`[sc] 生成SC图片失败：${e.message}`);
+		}
+		const fallback = `【${this.masterInfo?.username ?? ""}的直播间】${data.data.uname}的SC:${body.content}（${body.price}元）`;
+		if (this.ctx.isDisposed()) return;
+		await this.ctx.push.broadcastToTargets(this.sub.uid, this.ctx.contentBuilder.message([this.ctx.contentBuilder.text(fallback)]), 6);
+	}
+	async onGuardBuy(body) {
+		if (!this.ctx.isSubscribed(this.sub, "liveGuardBuy")) return;
+		const effMinGuardLevel = this.sub.minGuardLevel ?? this.ctx.config.minGuardLevel;
+		if (body.guard_level > effMinGuardLevel) return;
+		const guardImg = GUARD_LEVEL_IMG[body.guard_level];
+		const effectiveGuardBuy = this.sub.customGuardBuy.enable ? this.sub.customGuardBuy : this.ctx.config.customGuardBuy;
+		if (effectiveGuardBuy.enable) {
+			const customGuardImg = {
+				[GuardLevel.None]: void 0,
+				[GuardLevel.Jianzhang]: effectiveGuardBuy.captainImgUrl,
+				[GuardLevel.Tidu]: effectiveGuardBuy.supervisorImgUrl,
+				[GuardLevel.Zongdu]: effectiveGuardBuy.governorImgUrl
+			};
+			const text = this.ctx.templateRenderer.renderGuardBuy({
+				guardBuyConfig: effectiveGuardBuy,
+				uname: body.user.uname,
+				master: this.masterInfo,
+				giftName: body.gift_name
+			});
+			if (this.ctx.isDisposed()) return;
+			await this.ctx.push.broadcastToTargets(this.sub.uid, this.ctx.contentBuilder.message([this.ctx.contentBuilder.image(customGuardImg[body.guard_level] ?? guardImg), this.ctx.contentBuilder.text(text)]), 4);
+			return;
+		}
+		if (this.ctx.imageRenderer?.generateGuardCard) {
+			const data = await this.ctx.api.getUserInfoInLive(body.user.uid.toString(), this.sub.uid);
+			if (data.code === 0) try {
+				const buf = await this.ctx.imageRenderer.generateGuardCard({
+					guardLevel: body.guard_level,
+					uname: data.data.uname,
+					face: data.data.face,
+					isAdmin: data.data.is_admin
+				}, {
+					masterName: this.masterInfo?.username ?? "",
+					masterAvatarUrl: this.masterInfo?.userface ?? ""
+				});
+				if (this.ctx.isDisposed()) return;
+				await this.ctx.push.broadcastToTargets(this.sub.uid, this.ctx.contentBuilder.image(buf, "image/jpeg"), 4);
+				return;
+			} catch (e) {
+				this.ctx.logger.error(`[guard] 生成上舰图片失败：${e.message}`);
+			}
+		}
+		if (this.ctx.isDisposed()) return;
+		await this.ctx.push.broadcastToTargets(this.sub.uid, this.ctx.contentBuilder.message([this.ctx.contentBuilder.image(guardImg), this.ctx.contentBuilder.text(`【${this.masterInfo?.username ?? ""}的直播间】${body.user.uname}加入了大航海（${body.gift_name}）`)]), 4);
+	}
+	async onLiveStart() {
+		const now = Date.now();
+		if (now - this.lastLiveStart < 1e4) {
+			this.ctx.logger.debug(`[live] 直播间 [${this.sub.roomId}] 的开播事件在冷却期内，忽略`);
+			return;
+		}
+		if (this.liveStatus) {
+			this.ctx.logger.debug(`[live] 直播间 [${this.sub.roomId}] 已经是开播状态，忽略重复的开播事件`);
+			return;
+		}
+		this.lastLiveStart = now;
+		this.setLiveStatus(true);
+		if (!await this.useLiveRoomInfo(1) || !await this.useMasterInfo(1) || !this.liveRoomInfo || !this.masterInfo) {
+			this.setLiveStatus(false);
+			if (this.ctx.isDisposed()) return;
+			this.ctx.stopMonitoring("获取直播间信息失败，推送直播开播卡片失败", this.sub.roomId);
+			return;
+		}
+		this.ctx.logger.info(`[stat] 房间号：${this.masterInfo.roomId}，开播时的粉丝数：${this.masterInfo.liveOpenFollowerNum}`);
+		this.liveTime = this.liveRoomInfo.live_time || DateTime.now().toFormat("yyyy-MM-dd HH:mm:ss");
+		const diffTime = await this.ctx.getTimeDifference(this.liveTime);
+		const followerNum = this.masterInfo.liveOpenFollowerNum >= 1e4 ? `${(this.masterInfo.liveOpenFollowerNum / 1e4).toFixed(1)}万` : this.masterInfo.liveOpenFollowerNum.toString();
+		this.liveData.fansNum = this.masterInfo.liveOpenFollowerNum;
+		const roomLink = buildRoomLink(this.liveRoomInfo);
+		const liveStartMsg = this.ctx.templateRenderer.renderLiveStart({
+			sub: this.sub,
+			globalCustom: this.ctx.config.customLiveMsg,
+			master: this.masterInfo,
+			diffTime,
+			followerNum,
+			roomLink
+		});
+		await this.ctx.sendLiveNotifyCard({
+			liveType: 1,
+			liveData: this.liveData,
+			liveRoomInfo: this.liveRoomInfo,
+			master: this.masterInfo,
+			cardStyle: this.sub.customCardStyle,
+			uid: this.sub.uid,
+			notifyMsg: liveStartMsg
+		});
+		if (this.ctx.isDisposed()) return;
+		if (!this.liveStatus) {
+			this.ctx.logger.warn(`[live] 直播间 [${this.sub.roomId}] 开播流程完成时已非开播态（疑似交错下播），跳过周期任务`);
+			return;
+		}
+		this.armPeriodicTimer();
+	}
+	async onLiveEnd() {
+		const now = Date.now();
+		if (now - this.lastLiveEnd < 1e4) {
+			this.ctx.logger.debug(`[live] 直播间 [${this.sub.roomId}] 的下播事件在冷却期内，忽略`);
+			return;
+		}
+		this.lastLiveEnd = now;
+		await this.handleLiveEnd("ws");
+	}
+	async onInteractWordV2(msg) {
+		if (!this.sub.customSpecialUsersEnterTheRoom.enable || !this.ctx.hasTargets(this.sub, "specialUserEnterTheRoom")) return;
+		const pb = msg?.data?.pb;
+		if (typeof pb !== "string") {
+			this.ctx.logger.warn(`[live] INTERACT_WORD_V2 缺少 data.pb 字段，跳过 (room=${this.sub.roomId})`);
+			return;
+		}
+		const data = await this.ctx.decodeBase64PB(pb);
+		const uid = typeof data.uid === "string" ? data.uid : String(data.uid ?? "");
+		const uname = typeof data.uname === "string" ? data.uname : "";
+		if (data.msgType === "1" && this.sub.customSpecialUsersEnterTheRoom.specialUsersEnterTheRoom?.includes(uid)) {
+			const text = this.ctx.templateRenderer.renderSpecialUserEnter({
+				template: this.sub.customSpecialUsersEnterTheRoom.msgTemplate,
+				uname,
+				master: this.masterInfo
+			});
+			this.ctx.safeBroadcast(this.sub.uid, this.ctx.contentBuilder.message([this.ctx.contentBuilder.text(text)]), 8);
+		}
+	}
+};
+//#endregion
+//#region src/listener-manager.ts
+/**
+* Top-level lifecycle for live-room listeners.
+*
+* Owns:
+* - the per-uid {@link SubItemView} registry (mutable clones we update through
+*   `bilibili-notify/subscription-changed` ops).
+* - the underlying {@link RoomContext} (which in turn owns the listener
+*   record + periodic-timer record and exposes shared helpers consumed by
+*   {@link RoomSession}).
+*
+* Per-room state and the dispatcher closure live in {@link RoomSession}; the
+* manager only orchestrates start / stop / clearAll.
+*/
+var ListenerManager = class {
+	ctx;
+	subRecord = /* @__PURE__ */ new Map();
+	sessionRecord = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.ctx = new RoomContext(opts);
+	}
+	/** Replace runtime config (called when the adapter receives a config update). */
+	updateConfig(config) {
+		this.ctx.updateConfig(config);
+	}
+	isDisposed() {
+		return this.ctx.isDisposed();
+	}
+	getListenerCount() {
+		return this.ctx.getListenerCount();
+	}
+	/** Active mutable sub by uid (used by `applyOps` to detect existence). */
+	getActiveSub(uid) {
+		return this.subRecord.get(uid);
+	}
+	/**
+	* Read-only live-state snapshot for every monitored room. Each entry pairs
+	* the room's `isLive` boolean (mirrors RoomSession.liveStatus) with the
+	* latest fetched `liveRoomInfo` fields. Used by the standalone dashboard's
+	* `GET /api/live/listening` route to populate the "正在直播" panel.
+	*/
+	listLiveSnapshots() {
+		return Array.from(this.sessionRecord.values()).map((s) => s.getLiveSnapshot());
+	}
+	/**
+	* `pushTime` 热更后调用:把所有 active session 的"正在直播"复推 timer 按当前
+	* `pushTime` 重新 arm。LiveEngine.updateConfig 在检测到变化时转发。
+	*/
+	rearmAllPeriodicTimers() {
+		for (const session of this.sessionRecord.values()) session.rearmPeriodicTimer();
+	}
+	/**
+	* 单个 UID 的 pushTime 热更入口。LiveEngine.applyOps 在 update 分支检测到
+	* `LiveScopedChange.pushTime` 变化时调用,仅对该 uid 的活跃 session rearm。
+	*/
+	rearmPeriodicTimerForUid(uid) {
+		this.sessionRecord.get(uid)?.rearmPeriodicTimer();
+	}
+	/** Whether any feature on this sub requires the live-room WS connection. */
+	needsLiveMonitor(sub) {
+		return this.ctx.needsLiveMonitor(sub);
+	}
+	/** Start listeners for everything in `subs` that needs one. */
+	startAll(subs) {
+		for (const session of this.sessionRecord.values()) session.cancel();
+		this.ctx.setDisposed(false);
+		this.ctx.clearPushTimers();
+		this.ctx.clearListeners();
+		this.subRecord.clear();
+		this.sessionRecord.clear();
+		const liveSubUids = Object.values(subs).filter((s) => this.ctx.needsLiveMonitor(s)).map((s) => s.uid);
+		this.ctx.logger.debug(`[start] 启动直播监听，共 ${liveSubUids.length} 个 UID：${liveSubUids.join(", ")}`);
+		for (const sub of Object.values(subs)) if (this.ctx.needsLiveMonitor(sub)) this.startForUid(sub, "[start]");
+	}
+	/** Start a single sub's listener via a fresh {@link RoomSession}. */
+	startForUid(sub, logPrefix = "[ops]") {
+		const mutable = structuredClone(sub);
+		this.subRecord.set(sub.uid, mutable);
+		this.bootstrapForUid(mutable, logPrefix);
+	}
+	async bootstrapForUid(mutable, logPrefix) {
+		if (!mutable.roomId) {
+			const resolved = await this.resolveRoomId(mutable.uid, logPrefix);
+			if (!resolved) return;
+			mutable.roomId = resolved;
+		}
+		if (this.ctx.isDisposed()) return;
+		if (!this.subRecord.has(mutable.uid)) return;
+		this.ctx.danmakuCollector.registerRoom(mutable.roomId);
+		const session = new RoomSession(this.ctx, mutable);
+		this.sessionRecord.set(mutable.uid, session);
+		session.bootstrap().catch((e) => {
+			this.ctx.logger.error(`${logPrefix} 启动直播监听失败 UID=${mutable.uid}：${e instanceof Error ? e.message : String(e)}`);
+		});
+	}
+	async resolveRoomId(uid, logPrefix) {
+		try {
+			const roomid = (await this.ctx.api.getUserInfo(uid))?.data?.live_room?.roomid;
+			const n = Number(roomid);
+			if (!Number.isFinite(n) || n <= 0) {
+				this.ctx.logger.warn(`${logPrefix} UID=${uid} 未开通直播间或 live_room 解析失败，跳过 listener 创建`);
+				return;
+			}
+			return String(n);
+		} catch (e) {
+			this.ctx.logger.warn(`${logPrefix} UID=${uid} 解析直播间号失败：${e.message}`);
+			return;
+		}
+	}
+	/** Stop a single sub's listener and drop its bookkeeping. */
+	stopForUid(uid) {
+		const sub = this.subRecord.get(uid);
+		if (!sub) return;
+		const session = this.sessionRecord.get(uid);
+		if (session?.isLive) this.ctx.emitLiveState(uid, "idle");
+		session?.cancel();
+		this.ctx.livePushTimerManager.get(sub.roomId)?.();
+		this.ctx.livePushTimerManager.delete(sub.roomId);
+		this.ctx.closeListener(sub.roomId);
+		this.ctx.danmakuCollector.clear(sub.roomId);
+		this.subRecord.delete(uid);
+		this.sessionRecord.delete(uid);
+	}
+	/** Tear down everything. Used by engine `stop()` / `auth-lost`. */
+	disposeAll() {
+		this.ctx.logSideEffectState("stop:before-clear");
+		this.ctx.setDisposed(true);
+		for (const session of this.sessionRecord.values()) session.cancel();
+		this.ctx.clearPushTimers();
+		this.ctx.clearListeners();
+		this.subRecord.clear();
+		this.sessionRecord.clear();
+		this.ctx.danmakuCollector.clearAll();
+		this.ctx.logSideEffectState("stop:after-clear");
+	}
+	/** Tear down listeners + timers but keep registry / disposed flag intact. */
+	clearListeners() {
+		this.ctx.clearListeners();
+	}
+	/** Cancel every periodic "正在直播" timer. */
+	clearPushTimers() {
+		this.ctx.clearPushTimers();
+	}
+};
+//#endregion
+//#region src/live-summary-requester.ts
+/**
+* Threshold below which the engine refuses to generate a live summary.
+* Mirrors the original live-service heuristic.
+*/
+const LIVE_SUMMARY_MIN_SENDERS = 5;
+/**
+* Builds the AI prompt + dispatches it through {@link CommentaryGenerator},
+* falling back to the template-based summary when AI is unavailable or fails.
+*
+* Two-tier strategy (kept identical to live-service):
+* 1. If `commentary` is non-null, build a prompt summarising sender count,
+*    medal name, total danmaku, top-10 words and top-5 senders, then call
+*    `commentary.comment(prompt, "liveSummary")`.
+* 2. On failure (AI not configured / API error), fall back to the user-supplied
+*    template (`customLiveSummary` per-sub or the global default).
+*
+* Returns `undefined` when sender count is below the threshold (signals the
+* caller to skip the summary push entirely).
+*/
+var LiveSummaryRequester = class {
+	commentary;
+	isAiEnabled;
+	templateRenderer;
+	logger;
+	constructor(opts) {
+		this.commentary = opts.commentary;
+		this.isAiEnabled = opts.isAiEnabled ?? (() => true);
+		this.templateRenderer = opts.templateRenderer;
+		this.logger = opts.logger;
+	}
+	/** 热替换 CommentaryGenerator 实例。null 表示降级到模板回退。 */
+	setCommentary(commentary) {
+		this.commentary = commentary;
+	}
+	async generate(params) {
+		const { senderRecord, sortedWords, master, customLiveSummary, aiOverride } = params;
+		const senderCount = Object.keys(senderRecord).length;
+		if (senderCount < 5) {
+			this.logger.debug(`[summary] 发言人数不足5位，放弃生成直播总结`);
+			return;
+		}
+		const danmakuCount = Object.values(senderRecord).reduce((sum, val) => sum + val, 0);
+		const top5Senders = Object.entries(senderRecord).sort((a, b) => b[1] - a[1]).slice(0, 5);
+		if (this.commentary && this.isAiEnabled()) try {
+			const top10Words = sortedWords.slice(0, 10).map(([word, count]) => `${word}(${count})`);
+			const prompt = [
+				"请生成直播总结",
+				`弹幕发言人数：${senderCount}`,
+				`粉丝牌名：${master?.medalName ?? ""}`,
+				`弹幕总数：${danmakuCount}`,
+				`热词TOP10：${top10Words.join("、")}`,
+				`弹幕排行TOP5：${top5Senders.map(([u, c]) => `${u}(${c}条)`).join("、")}`
+			].join("，");
+			const aiResult = await this.commentary.comment(prompt, "liveSummary", void 0, aiOverride);
+			this.logger.debug(`[summary] AI 直播总结生成完毕，长度=${aiResult.length}`);
+			return aiResult;
+		} catch (e) {
+			this.logger.error(`[summary] AI 直播总结生成失败：${e.message}，回退到模板`);
+		}
+		return this.templateRenderer.renderLiveSummary({
+			template: customLiveSummary,
+			senderCount,
+			master,
+			danmakuCount,
+			topSenders: top5Senders
+		});
+	}
+};
+//#endregion
+//#region src/stop-words.ts
+const stopwords = new Set([
+	"，",
+	"。",
+	"！",
+	"？",
+	"：",
+	"；",
+	"“",
+	"”",
+	"‘",
+	"’",
+	"（",
+	"）",
+	"、",
+	"……",
+	"——",
+	"-",
+	"_",
+	".",
+	",",
+	"(",
+	")",
+	"【",
+	"】",
+	"而且",
+	"但是",
+	"如果",
+	"虽然",
+	"因为",
+	"所以",
+	"那么",
+	"那么就",
+	"今天",
+	"昨天",
+	"后天",
+	"明天",
+	"现在",
+	"刚刚",
+	"刚才",
+	"一直",
+	"一直在",
+	"目前",
+	"以前",
+	"以后",
+	"以前的",
+	"the",
+	"and",
+	"to",
+	"of",
+	"a",
+	"is",
+	"in",
+	"on",
+	"for",
+	"with",
+	"this",
+	"that",
+	"you",
+	"觉得",
+	"表示",
+	"发现",
+	"认为",
+	"看到",
+	"听说",
+	"了解",
+	"知道",
+	"说明",
+	"指出",
+	"讨论",
+	"讨论一下",
+	"看看",
+	"想想",
+	"说说",
+	"讲讲",
+	"一个",
+	"一些",
+	"这个",
+	"那个",
+	"每个",
+	"什么",
+	"东西",
+	"事情",
+	"这些",
+	"那些",
+	"这种",
+	"那种",
+	"怎么说",
+	"怎么会",
+	"怎么可能",
+	"不可能",
+	"有点像",
+	"真的很",
+	"特别是",
+	"有时候",
+	"每次都",
+	"一点点",
+	"哪里有",
+	"太离谱",
+	"太搞笑",
+	"太真实",
+	"为了",
+	"因为",
+	"所以",
+	"但是",
+	"而且",
+	"然后",
+	"如果",
+	"虽然",
+	"然而",
+	"不过",
+	"并且",
+	"即使",
+	"由于",
+	"那么",
+	"除非",
+	"比如",
+	"比如说",
+	"现在",
+	"刚刚",
+	"刚才",
+	"以前",
+	"以后",
+	"一直",
+	"从来",
+	"目前",
+	"最近",
+	"已经",
+	"后来",
+	"之前",
+	"某天"
+]);
+//#endregion
+//#region src/wordcloud-generator.ts
+/**
+* Threshold for refusing to render a wordcloud — stays in sync with the
+* original `live-service` heuristic: a board-level wordcloud needs a baseline
+* vocabulary or it looks empty.
+*/
+const WORDCLOUD_MIN_WORDS = 50;
+/** Cap on how many top words are passed into the wordcloud renderer. */
+const WORDCLOUD_TOP_WORDS = 90;
+/**
+* Wraps {@link ImageRenderer.generateWordCloudImg} with the engine's gating
+* logic (≥50 unique words required) and surfaces logger messages identical to
+* the original live-service.
+*
+* The output is a `Buffer` so the caller decides how to wrap it for the target
+* platform (e.g. via `LiveContentBuilder.image`).
+*/
+var WordcloudGenerator = class {
+	imageRenderer;
+	isImageEnabled;
+	logger;
+	constructor(opts) {
+		this.imageRenderer = opts.imageRenderer;
+		this.isImageEnabled = opts.isImageEnabled ?? (() => true);
+		this.logger = opts.logger;
+	}
+	/**
+	* Render a wordcloud image for `(masterName, masterAvatarUrl)`.
+	*
+	* Returns `undefined` when:
+	* - There are fewer than {@link WORDCLOUD_MIN_WORDS} unique words.
+	* - No `ImageRenderer` was injected (image-engine isn't installed).
+	* - The renderer threw; the error is logged and swallowed so the rest of
+	*   the live-end pipeline (summary + downstream push) keeps running.
+	*/
+	async generate(sortedWords, masterName, masterAvatarUrl) {
+		if (sortedWords.length < 50) {
+			this.logger.debug(`[wordcloud] 热词不足50个，放弃生成弹幕词云`);
+			return;
+		}
+		if (!this.isImageEnabled()) {
+			this.logger.debug("[wordcloud] cardStyle.enabled=false,跳过词云图片生成");
+			return;
+		}
+		if (!this.imageRenderer?.generateWordCloudImg) return void 0;
+		try {
+			return await this.imageRenderer.generateWordCloudImg(sortedWords.slice(0, 90), masterName, masterAvatarUrl);
+		} catch (e) {
+			this.logger.error(`[wordcloud] 生成词云失败：${e.message}`);
+			return;
+		}
+	}
+};
+//#endregion
+//#region src/live-engine.ts
+/**
+* Platform-neutral live-monitoring engine. Wires the five helpers
+* (listener-manager / danmaku-collector / wordcloud-generator /
+* template-renderer / live-summary-requester) together and exposes the public
+* surface previously offered by the koishi `BilibiliNotifyLive` service.
+*
+* Lifecycle:
+*
+* - {@link start}: register subscription set, open listeners for those that need them.
+* - {@link applyOps}: incremental subscription delta (add / delete / update);
+*   adapter forwards `bilibili-notify/subscription-changed` events here.
+* - {@link rebuildFromSubs}: full rebootstrap (used after `auth-restored`).
+* - {@link teardown}: tear down all listeners + records (used on `auth-lost`).
+* - {@link stop}: dispose; called by the adapter on plugin disposal.
+*/
+var LiveEngine = class {
+	logger;
+	listener;
+	danmakuCollector;
+	liveSummaryRequester;
+	config;
+	constructor(opts) {
+		this.logger = opts.serviceCtx.logger;
+		this.config = opts.config;
+		const stopwords = mergeStopWords(opts.config.wordcloudStopWords);
+		this.danmakuCollector = new DanmakuCollector(stopwords);
+		const templateRenderer = new LiveTemplateRenderer();
+		const wordcloudGenerator = new WordcloudGenerator({
+			imageRenderer: opts.imageRenderer ?? null,
+			isImageEnabled: () => this.config.imageEnabled !== false,
+			logger: this.logger
+		});
+		this.liveSummaryRequester = new LiveSummaryRequester({
+			commentary: opts.commentary ?? null,
+			isAiEnabled: () => this.config.aiEnabled !== false,
+			templateRenderer,
+			logger: this.logger
+		});
+		const liveSummaryRequester = this.liveSummaryRequester;
+		this.listener = new ListenerManager({
+			serviceCtx: opts.serviceCtx,
+			api: opts.api,
+			push: opts.push,
+			contentBuilder: opts.contentBuilder,
+			templateRenderer,
+			wordcloudGenerator,
+			liveSummaryRequester,
+			danmakuCollector: this.danmakuCollector,
+			imageRenderer: opts.imageRenderer ?? null,
+			config: toListenerConfig(opts.config),
+			emitEngineError: opts.emitEngineError,
+			emitLiveState: opts.emitLiveState,
+			emitViewers: opts.emitViewers
+		});
+	}
+	/**
+	* Bootstrap the engine with the initial subscription set. Idempotent —
+	* calling it again replaces the active set (used by `auth-restored`).
+	*/
+	start(subs) {
+		this.logger.info("[start] 直播引擎启动，正在初始化直播监听...");
+		this.listener.startAll(subs);
+	}
+	/** Tear down all listeners + per-room state, leaving the engine instance reusable. */
+	teardown() {
+		this.logger.info("[live] 关闭所有直播间监听");
+		this.listener.clearPushTimers();
+		this.listener.clearListeners();
+		this.danmakuCollector.clearAll();
+	}
+	/** Full rebootstrap. Used after auth-restored. */
+	rebuildFromSubs(subs) {
+		this.logger.info("[live] 重建直播间监听");
+		this.listener.startAll(subs);
+	}
+	/**
+	* Apply incremental subscription ops (the adapter receives these as a
+	* `bilibili-notify/subscription-changed` event payload). Handles the same
+	* three cases as the original live-service: add / delete / update.
+	*/
+	applyOps(ops, lookupFullSub) {
+		for (const op of ops) switch (op.type) {
+			case "add":
+				if (!this.listener.needsLiveMonitor(op.sub)) break;
+				this.listener.startForUid(op.sub);
+				break;
+			case "delete":
+				this.listener.stopForUid(op.uid);
+				break;
+			case "update": {
+				const liveChanges = op.changes.filter((c) => c.scope === "live");
+				const targetChanges = op.changes.filter((c) => c.scope === "target");
+				if (liveChanges.length === 0 && targetChanges.length === 0) break;
+				const existing = this.listener.getActiveSub(op.uid);
+				if (existing) {
+					const prevPushTime = existing.pushTime;
+					let nextPushTime = prevPushTime;
+					for (const change of liveChanges) {
+						const { scope: _scope, ...fields } = change;
+						if ("pushTime" in fields) nextPushTime = fields.pushTime;
+						Object.assign(existing, fields);
+					}
+					for (const change of targetChanges) existing.target = change.target;
+					if (!this.listener.needsLiveMonitor(existing)) this.listener.stopForUid(op.uid);
+					else if (nextPushTime !== prevPushTime) this.listener.rearmPeriodicTimerForUid(op.uid);
+				} else {
+					const fullSub = lookupFullSub(op.uid);
+					if (fullSub && this.listener.needsLiveMonitor(fullSub)) this.listener.startForUid(fullSub);
+				}
+				break;
+			}
+		}
+	}
+	/** Replace runtime config (called when the adapter receives a config-changed event). */
+	updateConfig(config) {
+		const pushTimeChanged = this.config.pushTime !== config.pushTime;
+		this.config = config;
+		this.danmakuCollector.setStopwords(mergeStopWords(config.wordcloudStopWords));
+		this.listener.updateConfig(toListenerConfig(config));
+		if (pushTimeChanged) {
+			this.logger.info(`[live] pushTime 已更新为 ${config.pushTime}h,重排所有定时器`);
+			this.listener.rearmAllPeriodicTimers();
+		}
+	}
+	/**
+	* 热替换 CommentaryGenerator 实例。adapter 在用户运行时打开 / 关闭 / 更换 AI
+	* 配置后调用,引擎随后的直播总结会立即用新实例 (或回退到模板) ,无需重启 server。
+	*/
+	setCommentary(commentary) {
+		this.liveSummaryRequester.setCommentary(commentary);
+	}
+	/** Final dispose; the engine instance must not be reused after this. */
+	stop() {
+		this.listener.disposeAll();
+	}
+	/** Diagnostic accessor, used by the koishi shell for `[conn] state` logging. */
+	get listenerCount() {
+		return this.listener.getListenerCount();
+	}
+	/**
+	* Per-room live-state snapshot for every active monitor. Routes / dashboards
+	* filter on `isLive` to show "正在直播" panels.
+	*/
+	listLiveSnapshots() {
+		return this.listener.listLiveSnapshots();
+	}
+	/** Read-only view of the engine config (for the koishi shell to pass through). */
+	getConfig() {
+		return this.config;
+	}
+};
+function toListenerConfig(c) {
+	return {
+		pushTime: c.pushTime,
+		restartPush: c.restartPush,
+		minScPrice: c.minScPrice,
+		minGuardLevel: c.minGuardLevel,
+		customGuardBuy: c.customGuardBuy,
+		customLiveMsg: c.customLiveMsg,
+		liveSummaryDefault: c.liveSummaryDefault,
+		imageEnabled: c.imageEnabled
+	};
+}
+/** Combine the bundled stop-words with the user's comma-separated additions. */
+function mergeStopWords(extra) {
+	if (!extra || extra.trim() === "") return new Set(stopwords);
+	const additions = extra.split(",").map((w) => w.trim()).filter((w) => w !== "");
+	return new Set([...stopwords, ...additions]);
+}
+//#endregion
+export { DEFAULT_LIVE_TEMPLATES, DanmakuCollector, LIVE_EVENT_COOLDOWN, LIVE_ROOM_MASTER_KEYS, LIVE_SUMMARY_MIN_SENDERS, ListenerManager, LiveEngine, LivePushType, LiveSummaryRequester, LiveTemplateRenderer, LiveType, RoomContext, RoomContextBase, RoomSession, RoomSessionBase, WORDCLOUD_MIN_WORDS, WORDCLOUD_TOP_WORDS, WordcloudGenerator, buildRoomLink, stopwords as defaultStopWords, formatFollowerChange, formatFollowerCount };