@bilibili-notify/live 0.0.1-alpha.3 → 0.1.0-alpha.5

package/lib/index.cjs

@@ -185,6 +185,8 @@ var RoomContextBase = class {
 	listenerRecord = {};
 	livePushTimerManager = /* @__PURE__ */ new Map();
 	disposed = false;
+	/** stopMonitoring 主动关闭 listener 时置位;RoomSession.onClose 消费后不做自愈重连。 */
+	intentionalCloseRooms = /* @__PURE__ */ new Set();
 	/** Cached protobuf type for INTERACT_WORD_V2 decoding (lazy-loaded). */
 	interactWord;
 	/**
@@ -222,6 +224,11 @@ var RoomContextBase = class {
 	emitViewers(uid, viewers) {
 		this._emitViewers?.(uid, viewers);
 	}
+	consumeIntentionalClose(roomId) {
+		const hit = this.intentionalCloseRooms.has(roomId);
+		this.intentionalCloseRooms.delete(roomId);
+		return hit;
+	}
 	/** 受 `config.imageEnabled` 门控的渲染器视图;关闭时返回 null。 */
 	get imageRenderer() {
 		return this.config.imageEnabled === false ? null : this._getImageRenderer();
@@ -253,10 +260,12 @@ var RoomContextBase = class {
 	closeListener(roomId) {
 		const listener = this.listenerRecord[roomId];
 		if (!listener) {
+			this.intentionalCloseRooms.delete(roomId);
 			this.logger.debug(`[conn] 直播间 [${roomId}] 连接不存在，跳过关闭`);
 			return;
 		}
 		if (listener.closed) {
+			this.intentionalCloseRooms.delete(roomId);
 			this.logger.debug(`[conn] 直播间 [${roomId}] 连接已被远端断开`);
 			delete this.listenerRecord[roomId];
 			return;
@@ -280,6 +289,7 @@ var RoomContextBase = class {
 	stopMonitoring(reason, roomId) {
 		if (roomId) {
 			this.logger.error(`[conn] [${roomId}] ${reason}，已停止该房间的监测`);
+			this.intentionalCloseRooms.add(roomId);
 			this.closeListener(roomId);
 			const timer = this.livePushTimerManager.get(roomId);
 			if (timer) {
@@ -337,6 +347,7 @@ var RoomContext = class extends RoomContextBase {
 			this.logger.warn(`[conn] 直播间 [${roomId}] 连接已存在，跳过创建`);
 			return true;
 		}
+		this.consumeIntentionalClose(roomId);
 		const cookiesStr = this.api.getCookiesHeader();
 		let mySelfInfo;
 		try {
@@ -499,37 +510,41 @@ var RoomContext = class extends RoomContextBase {
 * - `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.
+* 占位符统一 `{name}` / `{time}` / `{watched}` 语法(与 `@bilibili-notify/internal`
+* 的 `interpolate` 同源)。`applyTemplate` 同时接受 koishi 旧存档里的 legacy
+* `-name` / `-time` 写法 —— 老用户已保存的 `-key` 模板继续生效,新默认与文档
+* 一律走 `{key}`,二者不冲突(单遍正则,longest-first)。
 */
 /** 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",
+	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` 转义展开为真换行。
+* 单遍替换所有变量 token,再把 `\n` 转义展开为真换行。`vars` 以**裸键**(`name`/
+* `follower_change`)给出,每个键同时匹配 `{name}`(主)与 legacy `-name`(兼容)。
 *
 * P2:此前 `for…replaceAll` 顺序替换有两个缺陷 ——
-*  1. **token 注入**:用户可控值(uname / 弹幕内容)含 `-link`/`-time` 时
+*  1. **token 注入**:用户可控值(uname / 弹幕内容)含 `{link}`/`-link` 时
 *     会被后续轮次再次替换;
-*  2. **前缀吞噬**:`-follower` 先于 `-follower_change` 替换,把后者的
+*  2. **前缀吞噬**:legacy `-follower` 先于 `-follower_change` 替换,把后者的
 *     `-follower` 段吃掉只剩 `_change`。
-* 改为基于原始模板的**单遍正则**:token 按长度降序进 alternation(最长优先
-* 匹配),每个 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");
+	const alts = keys.flatMap((k) => [`\\{${escapeRegExp(k)}\\}`, `-${escapeRegExp(k)}`]);
+	const re = new RegExp(alts.join("|"), "g");
+	return template.replace(re, (m) => {
+		return vars[m.charCodeAt(0) === 123 ? m.slice(1, -1) : m.slice(1)] ?? m;
+	}).replaceAll("\\n", "\n");
 }
 /**
 * Format follower-change as a signed magnitude string with a 1万 (10K) cutoff,
@@ -559,27 +574,27 @@ 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
+			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
+			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)
+			name: params.master.username,
+			time: params.diffTime,
+			follower_change: formatFollowerChange(params.followerChange)
 		});
 	}
 	/**
@@ -588,24 +603,24 @@ var LiveTemplateRenderer = class {
 	*/
 	renderGuardBuy(params) {
 		return applyTemplate(params.guardBuyConfig.guardBuyMsg ?? "", {
-			"-uname": params.uname,
-			"-mname": params.master?.username ?? "",
-			"-guard": params.giftName
+			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
+			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
+			mastername: params.master?.username ?? "",
+			uname: params.uname
 		});
 	}
 	/**
@@ -618,19 +633,19 @@ var LiveTemplateRenderer = class {
 		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]}`
+			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]}`
 		});
 	}
 };
@@ -707,14 +722,17 @@ var RoomSessionBase = class {
 	async bootstrap() {
 		if (!await this.ctx.startLiveRoomListener(this.sub.roomId, this.buildHandler())) {
 			await this.ctx.push.sendPrivateMsg(`直播间 [${this.sub.roomId}] 弹幕连接建立失败，已停止该房间监测`);
+			this.onMonitoringStopped();
 			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.onMonitoringStopped();
 			this.ctx.closeListener(this.sub.roomId);
 			return;
 		}
+		this.onListenerStarted();
 		this.ctx.logger.debug(`[stat] 当前粉丝数：${this.masterInfo.liveOpenFollowerNum}`);
 		if (this.liveRoomInfo.live_status === 1) {
 			this.liveTime = this.liveRoomInfo.live_time;
@@ -743,6 +761,10 @@ var RoomSessionBase = class {
 			this.armPeriodicTimer();
 		}
 	}
+	/** Hook for subclass-owned connection-health bookkeeping after listener bootstrap succeeds. */
+	onListenerStarted() {}
+	/** Hook for subclass-owned cleanup before this session intentionally stops monitoring. */
+	onMonitoringStopped() {}
 	async useLiveRoomInfo(liveType) {
 		const data = await this.ctx.getLiveRoomInfo(this.sub.roomId);
 		if (!data?.uid) return false;
@@ -792,6 +814,7 @@ var RoomSessionBase = class {
 	/** Periodic "正在直播" tick (callback for `setInterval`). */
 	async tickPushAtTime() {
 		if (!await this.useLiveRoomInfo(2) || !this.liveRoomInfo) {
+			this.onMonitoringStopped();
 			this.ctx.stopMonitoring("获取直播间信息失败，推送直播卡片失败", this.sub.roomId);
 			return;
 		}
@@ -842,6 +865,7 @@ var RoomSessionBase = class {
 			this.setLiveStatus(false);
 			this.ctx.danmakuCollector.clear(this.sub.roomId);
 			if (this.ctx.isDisposed()) return;
+			this.onMonitoringStopped();
 			this.ctx.stopMonitoring("获取直播间信息失败，推送直播下播卡片失败", this.sub.roomId);
 			return;
 		}
@@ -926,6 +950,8 @@ const RECONNECT_BACKOFF_MS = [
 	8e3,
 	16e3
 ];
+/** B 站 live WS 静默自愈:每分钟检查一次,3 分钟无 heartbeat/消息即主动重连。 */
+const LIVE_WS_WATCHDOG_INTERVAL_MS = 6e4;
 var RoomSession = class extends RoomSessionBase {
 	lastViewersEmitMs = 0;
 	/**
@@ -944,10 +970,15 @@ var RoomSession = class extends RoomSessionBase {
 	/** L3:退避 sleep 的 Disposable + 唤醒句柄,cancel/teardown 时清掉,不留回调到 expiry。 */
 	reconnectTimer;
 	reconnectWake;
-	/** 外层主动停止 listener 时调用,阻止 onError 触发重连。 */
+	lastLiveWsActivityAt = 0;
+	lastLiveWsActivityReason = "connected";
+	watchdogTimer;
+	watchdogReconnectCount = 0;
+	/** 外层主动停止 listener 时调用,阻止 onError/onClose/watchdog 触发重连。 */
 	cancel() {
 		this.cancelled = true;
 		this.reconnecting = false;
+		this.stopLiveWsWatchdog();
 		this.clearReconnectSleep();
 	}
 	/** L3:dispose 退避定时器并唤醒重连循环,使其立刻重校 cancelled/disposed 后退出。 */
@@ -957,12 +988,62 @@ var RoomSession = class extends RoomSessionBase {
 		this.reconnectWake?.();
 		this.reconnectWake = void 0;
 	}
+	onListenerStarted() {
+		this.markLiveWsActivity("connected");
+		this.startLiveWsWatchdog();
+	}
+	onMonitoringStopped() {
+		this.cancel();
+	}
+	getWsHealthSnapshot() {
+		return {
+			lastActivityAt: this.lastLiveWsActivityAt,
+			lastActivityReason: this.lastLiveWsActivityReason,
+			watchdogReconnectCount: this.watchdogReconnectCount
+		};
+	}
+	markLiveWsActivity(reason) {
+		this.lastLiveWsActivityAt = Date.now();
+		this.lastLiveWsActivityReason = reason;
+	}
+	startLiveWsWatchdog() {
+		if (this.watchdogTimer || this.cancelled || this.ctx.isDisposed()) return;
+		this.watchdogTimer = this.ctx.serviceCtx.setInterval(() => this.checkLiveWsWatchdog(), LIVE_WS_WATCHDOG_INTERVAL_MS);
+	}
+	stopLiveWsWatchdog() {
+		this.watchdogTimer?.dispose();
+		this.watchdogTimer = void 0;
+	}
+	checkLiveWsWatchdog() {
+		if (this.cancelled || this.ctx.isDisposed() || this.reconnecting) return;
+		if (this.lastLiveWsActivityAt <= 0) return;
+		const staleMs = Date.now() - this.lastLiveWsActivityAt;
+		if (staleMs < 18e4) return;
+		this.watchdogReconnectCount++;
+		this.reconnect("watchdog", `${Math.floor(staleMs / 1e3)}s 无 heartbeat/消息(last=${this.lastLiveWsActivityReason},watchdog=${this.watchdogReconnectCount})`);
+	}
 	buildHandler() {
 		const base = {
+			onOpen: () => this.markLiveWsActivity("open"),
+			onStartListen: () => this.markLiveWsActivity("start-listen"),
+			onClose: () => {
+				if (this.cancelled || this.ctx.isDisposed()) return;
+				if (this.ctx.consumeIntentionalClose(this.sub.roomId)) return;
+				this.markLiveWsActivity("close");
+				this.reconnect("close");
+			},
 			onError: () => this.onError(),
-			onIncomeDanmu: ({ body }) => this.onIncomeDanmu(body),
-			onIncomeSuperChat: ({ body }) => this.onIncomeSuperChat(body),
+			onAttentionChange: () => this.markLiveWsActivity("heartbeat"),
+			onIncomeDanmu: ({ body }) => {
+				this.markLiveWsActivity("danmu");
+				this.onIncomeDanmu(body);
+			},
+			onIncomeSuperChat: ({ body }) => {
+				this.markLiveWsActivity("superchat");
+				return this.onIncomeSuperChat(body);
+			},
 			onWatchedChange: ({ body }) => {
+				this.markLiveWsActivity("watched");
 				this.liveData.watchedNum = body.text_small;
 				const now = Date.now();
 				if (now - this.lastViewersEmitMs >= VIEWERS_EMIT_THROTTLE_MS) {
@@ -971,42 +1052,61 @@ var RoomSession = class extends RoomSessionBase {
 				}
 			},
 			onLikedChange: ({ body }) => {
+				this.markLiveWsActivity("liked");
 				this.liveData.likedNum = body.count;
 			},
-			onGuardBuy: ({ body }) => this.onGuardBuy(body),
-			onLiveStart: () => this.onLiveStart(),
-			onLiveEnd: () => this.onLiveEnd()
+			onGuardBuy: ({ body }) => {
+				this.markLiveWsActivity("guard");
+				return this.onGuardBuy(body);
+			},
+			onLiveStart: () => {
+				this.markLiveWsActivity("live-start");
+				return this.onLiveStart();
+			},
+			onLiveEnd: () => {
+				this.markLiveWsActivity("live-end");
+				return this.onLiveEnd();
+			}
 		};
 		if (!this.sub.customSpecialUsersEnterTheRoom.enable) return base;
 		return {
 			...base,
-			raw: { INTERACT_WORD_V2: (msg) => this.onInteractWordV2(msg) }
+			raw: { INTERACT_WORD_V2: (msg) => {
+				this.markLiveWsActivity("interact");
+				return this.onInteractWordV2(msg);
+			} }
 		};
 	}
-	async onError() {
+	onError() {
+		return this.reconnect("error");
+	}
+	async reconnect(reason, detail) {
 		if (this.cancelled || this.ctx.isDisposed()) return;
 		if (this.reconnecting) return;
 		this.reconnecting = true;
 		try {
-			await this.reconnectLoop();
+			await this.reconnectLoop(reason, detail);
 		} finally {
 			this.reconnecting = false;
 		}
 	}
 	/**
-	* 退避重连循环(单飞,由 onError 持有)。`while` 取代旧的 `setTimeout(0)`
+	* 退避重连循环(单飞,由 reconnect 持有)。`while` 取代旧的 `setTimeout(0)`
 	* 递归续链 —— 杜绝深栈递归 + 每步都丢弃的定时器 Disposable;每次 sleep 后
 	* 重校 cancelled/disposed,sleep 自身可被 cancel/teardown dispose。
 	*/
-	async reconnectLoop() {
+	async reconnectLoop(reason, detail) {
 		while (this.reconnectAttempts < RECONNECT_BACKOFF_MS.length) {
 			if (this.cancelled || this.ctx.isDisposed()) return;
-			this.setLiveStatus(false);
-			this.cancelPeriodicTimer();
+			if (reason === "error") {
+				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} 次)`);
+			const reasonText = this.describeReconnectReason(reason, detail);
+			this.ctx.logger.warn(`[conn] 直播间 [${this.sub.roomId}] ${reasonText},${delay / 1e3}s 后重连(第 ${this.reconnectAttempts}/${RECONNECT_BACKOFF_MS.length} 次)`);
 			await this.sleepReconnect(delay);
 			if (this.cancelled || this.ctx.isDisposed()) return;
 			let ok = false;
@@ -1020,6 +1120,7 @@ var RoomSession = class extends RoomSessionBase {
 				return;
 			}
 			if (ok) {
+				this.onListenerStarted();
 				this.ctx.logger.info(`[conn] 直播间 [${this.sub.roomId}] 重连成功`);
 				this.reconnectAttempts = 0;
 				return;
@@ -1027,9 +1128,15 @@ var RoomSession = class extends RoomSessionBase {
 			this.ctx.logger.warn(`[conn] 直播间 [${this.sub.roomId}] 重连未成功,继续退避`);
 		}
 		this.reconnectAttempts = 0;
-		const msg = `直播间 [${this.sub.roomId}] 连接持续失败,重试 ${RECONNECT_BACKOFF_MS.length} 次后放弃监听`;
+		const msg = `直播间 [${this.sub.roomId}] ${this.describeReconnectReason(reason, detail)}后连接持续失败,重试 ${RECONNECT_BACKOFF_MS.length} 次后放弃监听`;
 		this.ctx.logger.error(`[conn] ${msg}`);
 		this.ctx.emitEngineError(msg);
+		this.cancel();
+	}
+	describeReconnectReason(reason, detail) {
+		if (reason === "error") return "连接错误";
+		if (reason === "close") return "连接关闭";
+		return detail ? `连接静默(${detail})` : "连接静默";
 	}
 	/**
 	* L3:可被 {@link clearReconnectSleep} 取消的退避 sleep。dispose 时立即
@@ -1152,6 +1259,7 @@ var RoomSession = class extends RoomSessionBase {
 		if (!await this.useLiveRoomInfo(1) || !await this.useMasterInfo(1) || !this.liveRoomInfo || !this.masterInfo) {
 			this.setLiveStatus(false);
 			if (this.ctx.isDisposed()) return;
+			this.onMonitoringStopped();
 			this.ctx.stopMonitoring("获取直播间信息失败，推送直播开播卡片失败", this.sub.roomId);
 			return;
 		}
@@ -1693,9 +1801,7 @@ var LiveEngine = class {
 	/** 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();
+		this.listener.disposeAll();
 	}
 	/** Full rebootstrap. Used after auth-restored. */
 	rebuildFromSubs(subs) {

package/lib/index.d.cts

@@ -274,16 +274,16 @@ type LivePushTimerManager = Map<string, () => void>;
  * - `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.
+ * 占位符统一 `{name}` / `{time}` / `{watched}` 语法(与 `@bilibili-notify/internal`
+ * 的 `interpolate` 同源)。`applyTemplate` 同时接受 koishi 旧存档里的 legacy
+ * `-name` / `-time` 写法 —— 老用户已保存的 `-key` 模板继续生效,新默认与文档
+ * 一律走 `{key}`,二者不冲突(单遍正则,longest-first)。
  */
 /** Defaults applied when neither sub-level nor global config provides a template. */
 declare const DEFAULT_LIVE_TEMPLATES: {
-  readonly liveStart: "-name 开播啦，当前粉丝数：-follower\n-link";
-  readonly liveOngoing: "-name 正在直播，已播 -time，累计观看：-watched\n-link";
-  readonly liveEnd: "-name 下播啦，本次直播了 -time，粉丝变化 -follower_change";
+  readonly liveStart: "{name} 开播啦，当前粉丝数：{follower}\n{link}";
+  readonly liveOngoing: "{name} 正在直播，已播 {time}，累计观看：{watched}\n{link}";
+  readonly liveEnd: "{name} 下播啦，本次直播了 {time}，粉丝变化 {follower_change}";
   readonly liveSummaryFallback: "弹幕总结";
 };
 /**
@@ -572,6 +572,8 @@ declare class RoomContextBase {
   readonly listenerRecord: Record<string, MessageListener>;
   readonly livePushTimerManager: Map<string, () => void>;
   private disposed;
+  /** stopMonitoring 主动关闭 listener 时置位;RoomSession.onClose 消费后不做自愈重连。 */
+  private readonly intentionalCloseRooms;
   /** Cached protobuf type for INTERACT_WORD_V2 decoding (lazy-loaded). */
   protected interactWord?: protobuf.Type;
   /**
@@ -590,6 +592,7 @@ declare class RoomContextBase {
    * 同型 no-op 安全调用方。room-session 已做 per-UID 节流,这里只是分发。
    */
   emitViewers(uid: string, viewers: string): void;
+  consumeIntentionalClose(roomId: string): boolean;
   /** 受 `config.imageEnabled` 门控的渲染器视图;关闭时返回 null。 */
   get imageRenderer(): ImageRenderer | null;
   updateConfig(config: ListenerManagerConfig): void;
@@ -737,6 +740,10 @@ declare abstract class RoomSessionBase {
   bootstrap(): Promise<void>;
   /** Build the platform-specific {@link MsgHandler}; provided by the subclass. */
   protected abstract buildHandler(): MsgHandler;
+  /** Hook for subclass-owned connection-health bookkeeping after listener bootstrap succeeds. */
+  protected onListenerStarted(): void;
+  /** Hook for subclass-owned cleanup before this session intentionally stops monitoring. */
+  protected onMonitoringStopped(): void;
   protected useLiveRoomInfo(liveType: LiveType): Promise<boolean>;
   protected useMasterInfo(liveType: LiveType): Promise<boolean>;
   /**
@@ -766,6 +773,7 @@ declare abstract class RoomSessionBase {
 }
 //#endregion
 //#region src/room-session.d.ts
+type LiveWsActivityReason = "connected" | "open" | "start-listen" | "heartbeat" | "danmu" | "superchat" | "watched" | "liked" | "guard" | "live-start" | "live-end" | "interact" | "close";
 declare class RoomSession extends RoomSessionBase {
   private lastViewersEmitMs;
   /**
@@ -784,18 +792,35 @@ declare class RoomSession extends RoomSessionBase {
   /** L3:退避 sleep 的 Disposable + 唤醒句柄,cancel/teardown 时清掉,不留回调到 expiry。 */
   private reconnectTimer?;
   private reconnectWake?;
-  /** 外层主动停止 listener 时调用,阻止 onError 触发重连。 */
+  private lastLiveWsActivityAt;
+  private lastLiveWsActivityReason;
+  private watchdogTimer?;
+  private watchdogReconnectCount;
+  /** 外层主动停止 listener 时调用,阻止 onError/onClose/watchdog 触发重连。 */
   cancel(): void;
   /** L3:dispose 退避定时器并唤醒重连循环,使其立刻重校 cancelled/disposed 后退出。 */
   private clearReconnectSleep;
+  protected onListenerStarted(): void;
+  protected onMonitoringStopped(): void;
+  getWsHealthSnapshot(): {
+    lastActivityAt: number;
+    lastActivityReason: LiveWsActivityReason;
+    watchdogReconnectCount: number;
+  };
+  private markLiveWsActivity;
+  private startLiveWsWatchdog;
+  private stopLiveWsWatchdog;
+  private checkLiveWsWatchdog;
   protected buildHandler(): MsgHandler;
   private onError;
+  private reconnect;
   /**
-   * 退避重连循环(单飞,由 onError 持有)。`while` 取代旧的 `setTimeout(0)`
+   * 退避重连循环(单飞,由 reconnect 持有)。`while` 取代旧的 `setTimeout(0)`
    * 递归续链 —— 杜绝深栈递归 + 每步都丢弃的定时器 Disposable;每次 sleep 后
    * 重校 cancelled/disposed,sleep 自身可被 cancel/teardown dispose。
    */
   private reconnectLoop;
+  private describeReconnectReason;
   /**
    * L3:可被 {@link clearReconnectSleep} 取消的退避 sleep。dispose 时立即
    * resolve,让 reconnectLoop 醒来重校 cancelled/disposed 后退出 —— 不再留

package/lib/index.d.mts

@@ -274,16 +274,16 @@ type LivePushTimerManager = Map<string, () => void>;
  * - `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.
+ * 占位符统一 `{name}` / `{time}` / `{watched}` 语法(与 `@bilibili-notify/internal`
+ * 的 `interpolate` 同源)。`applyTemplate` 同时接受 koishi 旧存档里的 legacy
+ * `-name` / `-time` 写法 —— 老用户已保存的 `-key` 模板继续生效,新默认与文档
+ * 一律走 `{key}`,二者不冲突(单遍正则,longest-first)。
  */
 /** Defaults applied when neither sub-level nor global config provides a template. */
 declare const DEFAULT_LIVE_TEMPLATES: {
-  readonly liveStart: "-name 开播啦，当前粉丝数：-follower\n-link";
-  readonly liveOngoing: "-name 正在直播，已播 -time，累计观看：-watched\n-link";
-  readonly liveEnd: "-name 下播啦，本次直播了 -time，粉丝变化 -follower_change";
+  readonly liveStart: "{name} 开播啦，当前粉丝数：{follower}\n{link}";
+  readonly liveOngoing: "{name} 正在直播，已播 {time}，累计观看：{watched}\n{link}";
+  readonly liveEnd: "{name} 下播啦，本次直播了 {time}，粉丝变化 {follower_change}";
   readonly liveSummaryFallback: "弹幕总结";
 };
 /**
@@ -572,6 +572,8 @@ declare class RoomContextBase {
   readonly listenerRecord: Record<string, MessageListener>;
   readonly livePushTimerManager: Map<string, () => void>;
   private disposed;
+  /** stopMonitoring 主动关闭 listener 时置位;RoomSession.onClose 消费后不做自愈重连。 */
+  private readonly intentionalCloseRooms;
   /** Cached protobuf type for INTERACT_WORD_V2 decoding (lazy-loaded). */
   protected interactWord?: protobuf.Type;
   /**
@@ -590,6 +592,7 @@ declare class RoomContextBase {
    * 同型 no-op 安全调用方。room-session 已做 per-UID 节流,这里只是分发。
    */
   emitViewers(uid: string, viewers: string): void;
+  consumeIntentionalClose(roomId: string): boolean;
   /** 受 `config.imageEnabled` 门控的渲染器视图;关闭时返回 null。 */
   get imageRenderer(): ImageRenderer | null;
   updateConfig(config: ListenerManagerConfig): void;
@@ -737,6 +740,10 @@ declare abstract class RoomSessionBase {
   bootstrap(): Promise<void>;
   /** Build the platform-specific {@link MsgHandler}; provided by the subclass. */
   protected abstract buildHandler(): MsgHandler;
+  /** Hook for subclass-owned connection-health bookkeeping after listener bootstrap succeeds. */
+  protected onListenerStarted(): void;
+  /** Hook for subclass-owned cleanup before this session intentionally stops monitoring. */
+  protected onMonitoringStopped(): void;
   protected useLiveRoomInfo(liveType: LiveType): Promise<boolean>;
   protected useMasterInfo(liveType: LiveType): Promise<boolean>;
   /**
@@ -766,6 +773,7 @@ declare abstract class RoomSessionBase {
 }
 //#endregion
 //#region src/room-session.d.ts
+type LiveWsActivityReason = "connected" | "open" | "start-listen" | "heartbeat" | "danmu" | "superchat" | "watched" | "liked" | "guard" | "live-start" | "live-end" | "interact" | "close";
 declare class RoomSession extends RoomSessionBase {
   private lastViewersEmitMs;
   /**
@@ -784,18 +792,35 @@ declare class RoomSession extends RoomSessionBase {
   /** L3:退避 sleep 的 Disposable + 唤醒句柄,cancel/teardown 时清掉,不留回调到 expiry。 */
   private reconnectTimer?;
   private reconnectWake?;
-  /** 外层主动停止 listener 时调用,阻止 onError 触发重连。 */
+  private lastLiveWsActivityAt;
+  private lastLiveWsActivityReason;
+  private watchdogTimer?;
+  private watchdogReconnectCount;
+  /** 外层主动停止 listener 时调用,阻止 onError/onClose/watchdog 触发重连。 */
   cancel(): void;
   /** L3:dispose 退避定时器并唤醒重连循环,使其立刻重校 cancelled/disposed 后退出。 */
   private clearReconnectSleep;
+  protected onListenerStarted(): void;
+  protected onMonitoringStopped(): void;
+  getWsHealthSnapshot(): {
+    lastActivityAt: number;
+    lastActivityReason: LiveWsActivityReason;
+    watchdogReconnectCount: number;
+  };
+  private markLiveWsActivity;
+  private startLiveWsWatchdog;
+  private stopLiveWsWatchdog;
+  private checkLiveWsWatchdog;
   protected buildHandler(): MsgHandler;
   private onError;
+  private reconnect;
   /**
-   * 退避重连循环(单飞,由 onError 持有)。`while` 取代旧的 `setTimeout(0)`
+   * 退避重连循环(单飞,由 reconnect 持有)。`while` 取代旧的 `setTimeout(0)`
    * 递归续链 —— 杜绝深栈递归 + 每步都丢弃的定时器 Disposable;每次 sleep 后
    * 重校 cancelled/disposed,sleep 自身可被 cancel/teardown dispose。
    */
   private reconnectLoop;
+  private describeReconnectReason;
   /**
    * L3:可被 {@link clearReconnectSleep} 取消的退避 sleep。dispose 时立即
    * resolve,让 reconnectLoop 醒来重校 cancelled/disposed 后退出 —— 不再留

package/lib/index.mjs

@@ -161,6 +161,8 @@ var RoomContextBase = class {
 	listenerRecord = {};
 	livePushTimerManager = /* @__PURE__ */ new Map();
 	disposed = false;
+	/** stopMonitoring 主动关闭 listener 时置位;RoomSession.onClose 消费后不做自愈重连。 */
+	intentionalCloseRooms = /* @__PURE__ */ new Set();
 	/** Cached protobuf type for INTERACT_WORD_V2 decoding (lazy-loaded). */
 	interactWord;
 	/**
@@ -198,6 +200,11 @@ var RoomContextBase = class {
 	emitViewers(uid, viewers) {
 		this._emitViewers?.(uid, viewers);
 	}
+	consumeIntentionalClose(roomId) {
+		const hit = this.intentionalCloseRooms.has(roomId);
+		this.intentionalCloseRooms.delete(roomId);
+		return hit;
+	}
 	/** 受 `config.imageEnabled` 门控的渲染器视图;关闭时返回 null。 */
 	get imageRenderer() {
 		return this.config.imageEnabled === false ? null : this._getImageRenderer();
@@ -229,10 +236,12 @@ var RoomContextBase = class {
 	closeListener(roomId) {
 		const listener = this.listenerRecord[roomId];
 		if (!listener) {
+			this.intentionalCloseRooms.delete(roomId);
 			this.logger.debug(`[conn] 直播间 [${roomId}] 连接不存在，跳过关闭`);
 			return;
 		}
 		if (listener.closed) {
+			this.intentionalCloseRooms.delete(roomId);
 			this.logger.debug(`[conn] 直播间 [${roomId}] 连接已被远端断开`);
 			delete this.listenerRecord[roomId];
 			return;
@@ -256,6 +265,7 @@ var RoomContextBase = class {
 	stopMonitoring(reason, roomId) {
 		if (roomId) {
 			this.logger.error(`[conn] [${roomId}] ${reason}，已停止该房间的监测`);
+			this.intentionalCloseRooms.add(roomId);
 			this.closeListener(roomId);
 			const timer = this.livePushTimerManager.get(roomId);
 			if (timer) {
@@ -313,6 +323,7 @@ var RoomContext = class extends RoomContextBase {
 			this.logger.warn(`[conn] 直播间 [${roomId}] 连接已存在，跳过创建`);
 			return true;
 		}
+		this.consumeIntentionalClose(roomId);
 		const cookiesStr = this.api.getCookiesHeader();
 		let mySelfInfo;
 		try {
@@ -475,37 +486,41 @@ var RoomContext = class extends RoomContextBase {
 * - `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.
+* 占位符统一 `{name}` / `{time}` / `{watched}` 语法(与 `@bilibili-notify/internal`
+* 的 `interpolate` 同源)。`applyTemplate` 同时接受 koishi 旧存档里的 legacy
+* `-name` / `-time` 写法 —— 老用户已保存的 `-key` 模板继续生效,新默认与文档
+* 一律走 `{key}`,二者不冲突(单遍正则,longest-first)。
 */
 /** 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",
+	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` 转义展开为真换行。
+* 单遍替换所有变量 token,再把 `\n` 转义展开为真换行。`vars` 以**裸键**(`name`/
+* `follower_change`)给出,每个键同时匹配 `{name}`(主)与 legacy `-name`(兼容)。
 *
 * P2:此前 `for…replaceAll` 顺序替换有两个缺陷 ——
-*  1. **token 注入**:用户可控值(uname / 弹幕内容)含 `-link`/`-time` 时
+*  1. **token 注入**:用户可控值(uname / 弹幕内容)含 `{link}`/`-link` 时
 *     会被后续轮次再次替换;
-*  2. **前缀吞噬**:`-follower` 先于 `-follower_change` 替换,把后者的
+*  2. **前缀吞噬**:legacy `-follower` 先于 `-follower_change` 替换,把后者的
 *     `-follower` 段吃掉只剩 `_change`。
-* 改为基于原始模板的**单遍正则**:token 按长度降序进 alternation(最长优先
-* 匹配),每个 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");
+	const alts = keys.flatMap((k) => [`\\{${escapeRegExp(k)}\\}`, `-${escapeRegExp(k)}`]);
+	const re = new RegExp(alts.join("|"), "g");
+	return template.replace(re, (m) => {
+		return vars[m.charCodeAt(0) === 123 ? m.slice(1, -1) : m.slice(1)] ?? m;
+	}).replaceAll("\\n", "\n");
 }
 /**
 * Format follower-change as a signed magnitude string with a 1万 (10K) cutoff,
@@ -535,27 +550,27 @@ 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
+			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
+			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)
+			name: params.master.username,
+			time: params.diffTime,
+			follower_change: formatFollowerChange(params.followerChange)
 		});
 	}
 	/**
@@ -564,24 +579,24 @@ var LiveTemplateRenderer = class {
 	*/
 	renderGuardBuy(params) {
 		return applyTemplate(params.guardBuyConfig.guardBuyMsg ?? "", {
-			"-uname": params.uname,
-			"-mname": params.master?.username ?? "",
-			"-guard": params.giftName
+			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
+			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
+			mastername: params.master?.username ?? "",
+			uname: params.uname
 		});
 	}
 	/**
@@ -594,19 +609,19 @@ var LiveTemplateRenderer = class {
 		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]}`
+			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]}`
 		});
 	}
 };
@@ -683,14 +698,17 @@ var RoomSessionBase = class {
 	async bootstrap() {
 		if (!await this.ctx.startLiveRoomListener(this.sub.roomId, this.buildHandler())) {
 			await this.ctx.push.sendPrivateMsg(`直播间 [${this.sub.roomId}] 弹幕连接建立失败，已停止该房间监测`);
+			this.onMonitoringStopped();
 			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.onMonitoringStopped();
 			this.ctx.closeListener(this.sub.roomId);
 			return;
 		}
+		this.onListenerStarted();
 		this.ctx.logger.debug(`[stat] 当前粉丝数：${this.masterInfo.liveOpenFollowerNum}`);
 		if (this.liveRoomInfo.live_status === 1) {
 			this.liveTime = this.liveRoomInfo.live_time;
@@ -719,6 +737,10 @@ var RoomSessionBase = class {
 			this.armPeriodicTimer();
 		}
 	}
+	/** Hook for subclass-owned connection-health bookkeeping after listener bootstrap succeeds. */
+	onListenerStarted() {}
+	/** Hook for subclass-owned cleanup before this session intentionally stops monitoring. */
+	onMonitoringStopped() {}
 	async useLiveRoomInfo(liveType) {
 		const data = await this.ctx.getLiveRoomInfo(this.sub.roomId);
 		if (!data?.uid) return false;
@@ -768,6 +790,7 @@ var RoomSessionBase = class {
 	/** Periodic "正在直播" tick (callback for `setInterval`). */
 	async tickPushAtTime() {
 		if (!await this.useLiveRoomInfo(2) || !this.liveRoomInfo) {
+			this.onMonitoringStopped();
 			this.ctx.stopMonitoring("获取直播间信息失败，推送直播卡片失败", this.sub.roomId);
 			return;
 		}
@@ -818,6 +841,7 @@ var RoomSessionBase = class {
 			this.setLiveStatus(false);
 			this.ctx.danmakuCollector.clear(this.sub.roomId);
 			if (this.ctx.isDisposed()) return;
+			this.onMonitoringStopped();
 			this.ctx.stopMonitoring("获取直播间信息失败，推送直播下播卡片失败", this.sub.roomId);
 			return;
 		}
@@ -902,6 +926,8 @@ const RECONNECT_BACKOFF_MS = [
 	8e3,
 	16e3
 ];
+/** B 站 live WS 静默自愈:每分钟检查一次,3 分钟无 heartbeat/消息即主动重连。 */
+const LIVE_WS_WATCHDOG_INTERVAL_MS = 6e4;
 var RoomSession = class extends RoomSessionBase {
 	lastViewersEmitMs = 0;
 	/**
@@ -920,10 +946,15 @@ var RoomSession = class extends RoomSessionBase {
 	/** L3:退避 sleep 的 Disposable + 唤醒句柄,cancel/teardown 时清掉,不留回调到 expiry。 */
 	reconnectTimer;
 	reconnectWake;
-	/** 外层主动停止 listener 时调用,阻止 onError 触发重连。 */
+	lastLiveWsActivityAt = 0;
+	lastLiveWsActivityReason = "connected";
+	watchdogTimer;
+	watchdogReconnectCount = 0;
+	/** 外层主动停止 listener 时调用,阻止 onError/onClose/watchdog 触发重连。 */
 	cancel() {
 		this.cancelled = true;
 		this.reconnecting = false;
+		this.stopLiveWsWatchdog();
 		this.clearReconnectSleep();
 	}
 	/** L3:dispose 退避定时器并唤醒重连循环,使其立刻重校 cancelled/disposed 后退出。 */
@@ -933,12 +964,62 @@ var RoomSession = class extends RoomSessionBase {
 		this.reconnectWake?.();
 		this.reconnectWake = void 0;
 	}
+	onListenerStarted() {
+		this.markLiveWsActivity("connected");
+		this.startLiveWsWatchdog();
+	}
+	onMonitoringStopped() {
+		this.cancel();
+	}
+	getWsHealthSnapshot() {
+		return {
+			lastActivityAt: this.lastLiveWsActivityAt,
+			lastActivityReason: this.lastLiveWsActivityReason,
+			watchdogReconnectCount: this.watchdogReconnectCount
+		};
+	}
+	markLiveWsActivity(reason) {
+		this.lastLiveWsActivityAt = Date.now();
+		this.lastLiveWsActivityReason = reason;
+	}
+	startLiveWsWatchdog() {
+		if (this.watchdogTimer || this.cancelled || this.ctx.isDisposed()) return;
+		this.watchdogTimer = this.ctx.serviceCtx.setInterval(() => this.checkLiveWsWatchdog(), LIVE_WS_WATCHDOG_INTERVAL_MS);
+	}
+	stopLiveWsWatchdog() {
+		this.watchdogTimer?.dispose();
+		this.watchdogTimer = void 0;
+	}
+	checkLiveWsWatchdog() {
+		if (this.cancelled || this.ctx.isDisposed() || this.reconnecting) return;
+		if (this.lastLiveWsActivityAt <= 0) return;
+		const staleMs = Date.now() - this.lastLiveWsActivityAt;
+		if (staleMs < 18e4) return;
+		this.watchdogReconnectCount++;
+		this.reconnect("watchdog", `${Math.floor(staleMs / 1e3)}s 无 heartbeat/消息(last=${this.lastLiveWsActivityReason},watchdog=${this.watchdogReconnectCount})`);
+	}
 	buildHandler() {
 		const base = {
+			onOpen: () => this.markLiveWsActivity("open"),
+			onStartListen: () => this.markLiveWsActivity("start-listen"),
+			onClose: () => {
+				if (this.cancelled || this.ctx.isDisposed()) return;
+				if (this.ctx.consumeIntentionalClose(this.sub.roomId)) return;
+				this.markLiveWsActivity("close");
+				this.reconnect("close");
+			},
 			onError: () => this.onError(),
-			onIncomeDanmu: ({ body }) => this.onIncomeDanmu(body),
-			onIncomeSuperChat: ({ body }) => this.onIncomeSuperChat(body),
+			onAttentionChange: () => this.markLiveWsActivity("heartbeat"),
+			onIncomeDanmu: ({ body }) => {
+				this.markLiveWsActivity("danmu");
+				this.onIncomeDanmu(body);
+			},
+			onIncomeSuperChat: ({ body }) => {
+				this.markLiveWsActivity("superchat");
+				return this.onIncomeSuperChat(body);
+			},
 			onWatchedChange: ({ body }) => {
+				this.markLiveWsActivity("watched");
 				this.liveData.watchedNum = body.text_small;
 				const now = Date.now();
 				if (now - this.lastViewersEmitMs >= VIEWERS_EMIT_THROTTLE_MS) {
@@ -947,42 +1028,61 @@ var RoomSession = class extends RoomSessionBase {
 				}
 			},
 			onLikedChange: ({ body }) => {
+				this.markLiveWsActivity("liked");
 				this.liveData.likedNum = body.count;
 			},
-			onGuardBuy: ({ body }) => this.onGuardBuy(body),
-			onLiveStart: () => this.onLiveStart(),
-			onLiveEnd: () => this.onLiveEnd()
+			onGuardBuy: ({ body }) => {
+				this.markLiveWsActivity("guard");
+				return this.onGuardBuy(body);
+			},
+			onLiveStart: () => {
+				this.markLiveWsActivity("live-start");
+				return this.onLiveStart();
+			},
+			onLiveEnd: () => {
+				this.markLiveWsActivity("live-end");
+				return this.onLiveEnd();
+			}
 		};
 		if (!this.sub.customSpecialUsersEnterTheRoom.enable) return base;
 		return {
 			...base,
-			raw: { INTERACT_WORD_V2: (msg) => this.onInteractWordV2(msg) }
+			raw: { INTERACT_WORD_V2: (msg) => {
+				this.markLiveWsActivity("interact");
+				return this.onInteractWordV2(msg);
+			} }
 		};
 	}
-	async onError() {
+	onError() {
+		return this.reconnect("error");
+	}
+	async reconnect(reason, detail) {
 		if (this.cancelled || this.ctx.isDisposed()) return;
 		if (this.reconnecting) return;
 		this.reconnecting = true;
 		try {
-			await this.reconnectLoop();
+			await this.reconnectLoop(reason, detail);
 		} finally {
 			this.reconnecting = false;
 		}
 	}
 	/**
-	* 退避重连循环(单飞,由 onError 持有)。`while` 取代旧的 `setTimeout(0)`
+	* 退避重连循环(单飞,由 reconnect 持有)。`while` 取代旧的 `setTimeout(0)`
 	* 递归续链 —— 杜绝深栈递归 + 每步都丢弃的定时器 Disposable;每次 sleep 后
 	* 重校 cancelled/disposed,sleep 自身可被 cancel/teardown dispose。
 	*/
-	async reconnectLoop() {
+	async reconnectLoop(reason, detail) {
 		while (this.reconnectAttempts < RECONNECT_BACKOFF_MS.length) {
 			if (this.cancelled || this.ctx.isDisposed()) return;
-			this.setLiveStatus(false);
-			this.cancelPeriodicTimer();
+			if (reason === "error") {
+				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} 次)`);
+			const reasonText = this.describeReconnectReason(reason, detail);
+			this.ctx.logger.warn(`[conn] 直播间 [${this.sub.roomId}] ${reasonText},${delay / 1e3}s 后重连(第 ${this.reconnectAttempts}/${RECONNECT_BACKOFF_MS.length} 次)`);
 			await this.sleepReconnect(delay);
 			if (this.cancelled || this.ctx.isDisposed()) return;
 			let ok = false;
@@ -996,6 +1096,7 @@ var RoomSession = class extends RoomSessionBase {
 				return;
 			}
 			if (ok) {
+				this.onListenerStarted();
 				this.ctx.logger.info(`[conn] 直播间 [${this.sub.roomId}] 重连成功`);
 				this.reconnectAttempts = 0;
 				return;
@@ -1003,9 +1104,15 @@ var RoomSession = class extends RoomSessionBase {
 			this.ctx.logger.warn(`[conn] 直播间 [${this.sub.roomId}] 重连未成功,继续退避`);
 		}
 		this.reconnectAttempts = 0;
-		const msg = `直播间 [${this.sub.roomId}] 连接持续失败,重试 ${RECONNECT_BACKOFF_MS.length} 次后放弃监听`;
+		const msg = `直播间 [${this.sub.roomId}] ${this.describeReconnectReason(reason, detail)}后连接持续失败,重试 ${RECONNECT_BACKOFF_MS.length} 次后放弃监听`;
 		this.ctx.logger.error(`[conn] ${msg}`);
 		this.ctx.emitEngineError(msg);
+		this.cancel();
+	}
+	describeReconnectReason(reason, detail) {
+		if (reason === "error") return "连接错误";
+		if (reason === "close") return "连接关闭";
+		return detail ? `连接静默(${detail})` : "连接静默";
 	}
 	/**
 	* L3:可被 {@link clearReconnectSleep} 取消的退避 sleep。dispose 时立即
@@ -1128,6 +1235,7 @@ var RoomSession = class extends RoomSessionBase {
 		if (!await this.useLiveRoomInfo(1) || !await this.useMasterInfo(1) || !this.liveRoomInfo || !this.masterInfo) {
 			this.setLiveStatus(false);
 			if (this.ctx.isDisposed()) return;
+			this.onMonitoringStopped();
 			this.ctx.stopMonitoring("获取直播间信息失败，推送直播开播卡片失败", this.sub.roomId);
 			return;
 		}
@@ -1669,9 +1777,7 @@ var LiveEngine = class {
 	/** 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();
+		this.listener.disposeAll();
 	}
 	/** Full rebootstrap. Used after auth-restored. */
 	rebuildFromSubs(subs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilibili-notify/live",
-  "version": "0.0.1-alpha.3",
+  "version": "0.1.0-alpha.5",
   "repository": {
     "type": "git",
     "url": "https://github.com/Akokk0/bilibili-notify"
@@ -30,10 +30,10 @@
     "jieba-wasm": "^2.4.0",
     "luxon": "^3.5.0",
     "protobufjs": "^7.4.0",
-    "@bilibili-notify/api": "^0.2.0-alpha.2",
     "@bilibili-notify/ai": "^0.0.1-alpha.1",
-    "@bilibili-notify/internal": "^0.1.0-alpha.2",
-    "@bilibili-notify/image": "^0.0.1-alpha.2"
+    "@bilibili-notify/image": "^0.0.1-alpha.2",
+    "@bilibili-notify/internal": "^0.1.0-alpha.4",
+    "@bilibili-notify/api": "^0.2.0-alpha.2"
   },
   "devDependencies": {
     "@types/luxon": "^3.4.2",