@bilibili-notify/live 0.1.0-alpha.4 → 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 {
@@ -711,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;
@@ -747,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;
@@ -796,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;
 		}
@@ -846,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;
 		}
@@ -930,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;
 	/**
@@ -948,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 后退出。 */
@@ -961,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) {
@@ -975,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;
@@ -1024,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;
@@ -1031,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 时立即
@@ -1156,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;
 		}
@@ -1697,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

@@ -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

@@ -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 {
@@ -687,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;
@@ -723,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;
@@ -772,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;
 		}
@@ -822,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;
 		}
@@ -906,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;
 	/**
@@ -924,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 后退出。 */
@@ -937,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) {
@@ -951,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;
@@ -1000,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;
@@ -1007,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 时立即
@@ -1132,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;
 		}
@@ -1673,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.1.0-alpha.4",
+  "version": "0.1.0-alpha.5",
   "repository": {
     "type": "git",
     "url": "https://github.com/Akokk0/bilibili-notify"
@@ -32,8 +32,8 @@
     "protobufjs": "^7.4.0",
     "@bilibili-notify/ai": "^0.0.1-alpha.1",
     "@bilibili-notify/image": "^0.0.1-alpha.2",
-    "@bilibili-notify/api": "^0.2.0-alpha.2",
-    "@bilibili-notify/internal": "^0.1.0-alpha.3"
+    "@bilibili-notify/internal": "^0.1.0-alpha.4",
+    "@bilibili-notify/api": "^0.2.0-alpha.2"
   },
   "devDependencies": {
     "@types/luxon": "^3.4.2",