@bilibili-notify/live 0.0.1-alpha.0

package/lib/index.d.cts

@@ -0,0 +1,1002 @@
+import { CommentaryCallOverride, CommentaryGenerator } from "@bilibili-notify/ai";
+import { BilibiliAPI, LiveRoomInfo } from "@bilibili-notify/api";
+import { ImageRenderer } from "@bilibili-notify/image";
+import { Disposable, Logger, ServiceContext } from "@bilibili-notify/internal";
+import { MessageListener, MsgHandler } from "blive-message-listener";
+import protobuf from "protobufjs";
+
+//#region src/content-builder.d.ts
+/**
+ * Platform-neutral content-builder injection point.
+ *
+ * The original koishi `BilibiliNotifyLive` constructed messages with
+ * `h("message", [...])` / `h.image(buffer, mime)` / `h.text(...)` / `h.image(url)`
+ * and `h.at("all")` and shipped them straight to `BilibiliPush.broadcastToTargets`.
+ *
+ * To stay decoupled from `koishi`'s `h(...)` factory, live-engine builds these
+ * fragments through a `LiveContentBuilder` provided by the adapter. The koishi
+ * shell wires the builder to the real `h` exports; the standalone runtime maps
+ * each call onto its own `NotificationPayload` shape.
+ *
+ * Each method returns an opaque `unknown` — the engine never inspects the
+ * result; it only passes the value back to the adapter via `PushLike`.
+ */
+interface LiveContentBuilder {
+  /** Wrap a plain text run. Equivalent to `h.text(text)`. */
+  text(text: string): unknown;
+  /**
+   * Wrap a remote image URL or in-memory buffer.
+   * `mime` is provided when `source` is a `Buffer`.
+   */
+  image(source: string | Buffer, mime?: string): unknown;
+  /** Equivalent to `h.at("all")` (i.e. mention everyone in a group / channel). */
+  atAll(): unknown;
+  /**
+   * Compose a message with an array of segments (text / image / atAll fragments
+   * created by this same builder, plus `null` / `undefined` placeholders that
+   * are dropped). Equivalent to `h("message", segments)`.
+   */
+  message(segments: Array<unknown>): unknown;
+}
+//#endregion
+//#region src/danmaku-collector.d.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.
+ */
+declare class DanmakuCollector {
+  /** roomId → { word: count } */
+  private readonly weightByRoom;
+  /** roomId → { username: count } */
+  private readonly senderByRoom;
+  private readonly stopwords;
+  constructor(stopwords: Iterable<string>);
+  /** Replace the active stop-word set (called on config update). */
+  setStopwords(stopwords: Iterable<string>): void;
+  /** Make sure a room is being tracked (called when listener starts). */
+  registerRoom(roomId: string): void;
+  /**
+   * 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: string, content: string, username: string): void;
+  /**
+   * 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: string): {
+    sortedWords: Array<[string, number]>;
+    senderRecord: Record<string, number>;
+    senderCount: number;
+    danmakuCount: number;
+  };
+  /** Drop all collected data for a room (called at live-end / room-stop). */
+  clear(roomId: string): void;
+  /** Drop everything (called on engine stop / auth-lost). */
+  clearAll(): void;
+}
+//#endregion
+//#region src/push-like.d.ts
+/** Push category enum — numeric values are the historical bilibili-notify push-type codes. */
+declare enum LivePushType {
+  Live = 0,
+  StartBroadcasting = 3,
+  LiveGuardBuy = 4,
+  /** 历史上承载词云+总结合包推送;现在仅用于词云,总结走 {@link LiveSummary}。 */
+  WordCloudAndLiveSummary = 5,
+  Superchat = 6,
+  UserDanmakuMsg = 7,
+  UserActions = 8,
+  LiveEnd = 9,
+  LiveSummary = 10
+}
+/**
+ * Channel-level feature keys (mirror `@bilibili-notify/push`'s `PushFeature`).
+ * Each entry on `SubItemView.target` maps to a list of resolved channel
+ * identifiers; an empty / missing list means "not subscribed for this feature".
+ */
+type LivePushFeature = "dynamic" | "live" | "liveEnd" | "liveGuardBuy" | "superchat" | "wordcloud" | "liveSummary" | "specialDanmaku" | "specialUserEnterTheRoom";
+/**
+ * Master-level feature keys — the boolean toggles set per-UP. Subset of
+ * `LivePushFeature` which omits `specialDanmaku` / `specialUserEnterTheRoom`
+ * (those are gated by `customSpecial*.enable` instead).
+ */
+type LiveMasterFeature = Exclude<LivePushFeature, "specialDanmaku" | "specialUserEnterTheRoom">;
+/**
+ * Subset of `LiveMasterFeature` whose subscription requires an active live-room
+ * WebSocket connection. Mirrors `@bilibili-notify/push`'s `LIVE_ROOM_MASTERS`.
+ */
+declare const LIVE_ROOM_MASTER_KEYS: readonly LiveMasterFeature[];
+/** Sub-level customisation blocks copied from `@bilibili-notify/push`. */
+interface CustomCardStyleLike {
+  enable: boolean;
+  cardColorStart?: string;
+  cardColorEnd?: string;
+}
+interface CustomLiveMsgLike {
+  enable: boolean;
+  customLiveStart?: string;
+  customLive?: string;
+  customLiveEnd?: string;
+}
+interface CustomGuardBuyLike {
+  enable: boolean;
+  guardBuyMsg?: string;
+  captainImgUrl?: string;
+  supervisorImgUrl?: string;
+  governorImgUrl?: string;
+}
+interface CustomLiveSummaryLike {
+  enable: boolean;
+  liveSummary?: string;
+}
+interface CustomSpecialDanmakuUsersLike {
+  enable: boolean;
+  specialDanmakuUsers?: string[];
+  msgTemplate: string;
+}
+interface CustomSpecialUsersEnterTheRoomLike {
+  enable: boolean;
+  specialUsersEnterTheRoom?: string[];
+  msgTemplate: string;
+}
+/** Per-feature target list (already resolved to channel identifiers). */
+type SubItemTargetLike = Partial<Record<LivePushFeature, unknown[]>>;
+/**
+ * Platform-neutral view of a single subscription, structurally compatible with
+ * `@bilibili-notify/push`'s `SubItem`. The live engine only reads this shape; the
+ * adapter is responsible for providing instances (the Koishi shell hands its
+ * `SubItem`s through unchanged, since their fields match by name).
+ */
+interface SubItemView {
+  uid: string;
+  uname: string;
+  roomId: string;
+  dynamic: boolean;
+  live: boolean;
+  liveEnd: boolean;
+  liveGuardBuy: boolean;
+  superchat: boolean;
+  wordcloud: boolean;
+  liveSummary: boolean;
+  target: SubItemTargetLike;
+  customCardStyle: CustomCardStyleLike;
+  customLiveMsg: CustomLiveMsgLike;
+  customGuardBuy: CustomGuardBuyLike;
+  customLiveSummary: CustomLiveSummaryLike;
+  customSpecialDanmakuUsers: CustomSpecialDanmakuUsersLike;
+  customSpecialUsersEnterTheRoom: CustomSpecialUsersEnterTheRoomLike;
+  /**
+   * Per-UP 覆盖项。adapter 已通过 `resolve(sub, defaults)` 折叠 globals + overrides,
+   * 这里只保留实际跟全局可能不同的字段;undefined 表示「按全局走」。room-session /
+   * room-session-base / live-summary-requester 在用值前一律 `?? ctx.config.X` 回退。
+   *
+   * 这些字段也会随 LiveScopedChange 增量推送给 LiveEngine.applyOps,Object.assign
+   * 合进活跃 sub 后,SC / 上舰 / restartPush / liveSummary 调用点会读到新值;pushTime
+   * 因 setInterval 句柄 ms 不可变,engine 在 update 时检测变化后会单独 rearm。
+   */
+  minScPrice?: number;
+  minGuardLevel?: 1 | 2 | 3;
+  pushTime?: number;
+  restartPush?: boolean;
+  aiOverride?: CommentaryCallOverride;
+}
+type SubscriptionsView = Record<string, SubItemView>;
+/**
+ * Scoped change object — mirrors `koishi-plugin-bilibili-notify`'s
+ * `SubChange` so the koishi adapter can forward incremental subscription
+ * updates without translation.
+ */
+type LiveScopedChange = {
+  scope: "live";
+} & Partial<Pick<SubItemView, "live" | "liveEnd" | "liveGuardBuy" | "superchat" | "wordcloud" | "liveSummary" | "uname" | "roomId" | "customCardStyle" | "customLiveMsg" | "customGuardBuy" | "customLiveSummary" | "customSpecialDanmakuUsers" | "customSpecialUsersEnterTheRoom" | "minScPrice" | "minGuardLevel" | "pushTime" | "restartPush" | "aiOverride">>;
+type DynamicScopedChange = {
+  scope: "dynamic";
+} & Partial<Pick<SubItemView, "dynamic">>;
+type TargetScopedChange = {
+  scope: "target";
+} & Pick<SubItemView, "target">;
+type LiveSubChange = LiveScopedChange | DynamicScopedChange | TargetScopedChange;
+type LiveSubscriptionOp = {
+  type: "add";
+  sub: SubItemView;
+} | {
+  type: "delete";
+  uid: string;
+} | {
+  type: "update";
+  uid: string;
+  changes: LiveSubChange[];
+};
+/**
+ * Push-out interface required by live-engine. Mirrors the methods on
+ * `@bilibili-notify/push`'s `BilibiliPush` we actually call.
+ *
+ * `content` is intentionally `unknown` — the koishi adapter passes koishi's
+ * `h(...)` element fragments while the standalone adapter will pass its own
+ * `NotificationPayload`. The engine only forwards the value through.
+ */
+interface PushLike {
+  broadcastToTargets(uid: string, content: unknown, type: LivePushType): Promise<void>;
+  sendPrivateMsg(content: string): Promise<void>;
+}
+//#endregion
+//#region src/types.d.ts
+declare enum LiveType {
+  NotLiveBroadcast = 0,
+  StartBroadcasting = 1,
+  LiveBroadcast = 2,
+  StopBroadcast = 3,
+  FirstLiveBroadcast = 4
+}
+interface MasterInfo {
+  username: string;
+  userface: string;
+  roomId: number;
+  liveOpenFollowerNum: number;
+  liveEndFollowerNum: number;
+  liveFollowerChange: number;
+  medalName: string;
+}
+interface LiveData {
+  watchedNum?: string | number;
+  likedNum?: string | number;
+  fansNum?: string | number;
+  fansChanged?: string | number;
+}
+interface UserInfoInLiveData {
+  uid: number;
+  uname: string;
+  face: string;
+  is_admin: number;
+}
+type LivePushTimerManager = Map<string, () => void>;
+//#endregion
+//#region src/template-renderer.d.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. */
+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 liveSummaryFallback: "弹幕总结";
+};
+/**
+ * Format follower-change as a signed magnitude string with a 1万 (10K) cutoff,
+ * mirroring live-service's inline formatting.
+ */
+declare function formatFollowerChange(n: number): string;
+/** Format follower count, abbreviating ≥10K to `X.X万`. */
+declare function formatFollowerCount(n: number): string;
+/** Build the canonical room link from `LiveRoomInfo.data` style fields. */
+declare function buildRoomLink(info: {
+  short_id: number;
+  room_id: number;
+}): string;
+declare class LiveTemplateRenderer {
+  /** Compose the "开播" notification text for a sub. */
+  renderLiveStart(params: {
+    sub: SubItemView;
+    globalCustom?: CustomLiveMsgLike;
+    master: MasterInfo;
+    diffTime: string;
+    followerNum: string;
+    roomLink: string;
+  }): string;
+  /** Compose the periodic "正在直播" notification text. */
+  renderLiveOngoing(params: {
+    sub: SubItemView;
+    globalCustom?: CustomLiveMsgLike;
+    master: MasterInfo;
+    diffTime: string;
+    watched: string;
+    roomLink: string;
+  }): string;
+  /** Compose the "下播" notification text. */
+  renderLiveEnd(params: {
+    sub: SubItemView;
+    globalCustom?: CustomLiveMsgLike;
+    master: MasterInfo;
+    diffTime: string;
+    followerChange: number;
+  }): string;
+  /**
+   * Compose the "上舰" notification text using the effective custom-guard
+   * config (resolved by listener-manager).
+   */
+  renderGuardBuy(params: {
+    guardBuyConfig: CustomGuardBuyLike;
+    uname: string;
+    master: MasterInfo | undefined;
+    giftName: string;
+  }): string;
+  /** Compose the "特别关注弹幕" notification text. */
+  renderSpecialDanmaku(params: {
+    template: string;
+    uname: string;
+    master: MasterInfo | undefined;
+    content: string;
+  }): string;
+  /** Compose the "特别关注进入直播间" notification text. */
+  renderSpecialUserEnter(params: {
+    template: string;
+    uname: string;
+    master: MasterInfo | undefined;
+  }): string;
+  /**
+   * 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: {
+    template: string;
+    senderCount: number;
+    master: MasterInfo | undefined;
+    danmakuCount: number;
+    topSenders: Array<[string, number]>;
+  }): string;
+}
+//#endregion
+//#region src/live-summary-requester.d.ts
+/**
+ * Threshold below which the engine refuses to generate a live summary.
+ * Mirrors the original live-service heuristic.
+ */
+declare 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).
+ */
+declare class LiveSummaryRequester {
+  private commentary;
+  private readonly isAiEnabled;
+  private readonly templateRenderer;
+  private readonly logger;
+  constructor(opts: {
+    commentary: CommentaryGenerator | null;
+    /**
+     * AI 总开关查询。返回 false 时跳过 commentary 调用,直接走模板回退,
+     * 与 commentary === null 行为等价。Adapter 用 `() => globals.defaults.ai.enabled` 填充,
+     * 缺省 () => true。
+     */
+    isAiEnabled?: () => boolean;
+    templateRenderer: LiveTemplateRenderer;
+    logger: Logger;
+  });
+  /** 热替换 CommentaryGenerator 实例。null 表示降级到模板回退。 */
+  setCommentary(commentary: CommentaryGenerator | null): void;
+  generate(params: {
+    senderRecord: Record<string, number>;
+    sortedWords: Array<[string, number]>;
+    master: MasterInfo | undefined;
+    customLiveSummary: string;
+    /**
+     * per-UP AI 覆盖。adapter 在 SubItemView.aiOverride 上注入,room-session 在调
+     * `generate()` 时透传过来。CommentaryGenerator 内部 `?? this.config` 兜底,
+     * 缺失字段不影响其它字段生效。
+     */
+    aiOverride?: CommentaryCallOverride;
+  }): Promise<string | undefined>;
+}
+//#endregion
+//#region src/wordcloud-generator.d.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.
+ */
+declare const WORDCLOUD_MIN_WORDS = 50;
+/** Cap on how many top words are passed into the wordcloud renderer. */
+declare 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`).
+ */
+declare class WordcloudGenerator {
+  private readonly imageRenderer;
+  private readonly isImageEnabled;
+  private readonly logger;
+  constructor(opts: {
+    imageRenderer: ImageRenderer | null;
+    /**
+     * 卡片渲染总开关查询。返回 false 时直接跳过 puppeteer 调用,与缺失 imageRenderer
+     * 等价。Adapter 通常用 `() => globals.defaults.cardStyle.enabled` 填充;缺省 () => true。
+     */
+    isImageEnabled?: () => boolean;
+    logger: 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.
+   */
+  generate(sortedWords: Array<[string, number]>, masterName: string, masterAvatarUrl?: string): Promise<Buffer | undefined>;
+}
+//#endregion
+//#region src/room-context.d.ts
+/**
+ * Configuration that listener-manager + room-session both consume.
+ * Mirrors the koishi `BilibiliNotifyLiveConfig` minus the `logLevel` /
+ * `wordcloudStopWords` fields (those are owned at the LiveEngine level).
+ */
+interface ListenerManagerConfig {
+  pushTime: number;
+  restartPush: boolean;
+  minScPrice: number;
+  minGuardLevel: 1 | 2 | 3;
+  customGuardBuy: {
+    enable: boolean;
+    guardBuyMsg?: string;
+    captainImgUrl?: string;
+    supervisorImgUrl?: string;
+    governorImgUrl?: string;
+  };
+  customLiveMsg: {
+    enable: boolean;
+    customLiveStart?: string;
+    customLive?: string;
+    customLiveEnd?: string;
+  };
+  /** Default global `liveSummary` template (joined with `\n`). */
+  liveSummaryDefault: string;
+  /**
+   * 图片卡片渲染总开关。`false` 时 RoomContext 暴露的 imageRenderer 始终为 null,
+   * 直播开播 / SC / 上舰 等路径自然走 `if (renderer?.generateXxx)` 落入文字回退。缺省视为 true。
+   */
+  imageEnabled?: boolean;
+}
+/**
+ * Constructor options for {@link RoomContext}. Mirrors the dependency set
+ * passed into `LiveEngine`; the engine builds one `RoomContext` and shares it
+ * with both {@link import("./listener-manager").ListenerManager} (for lifecycle
+ * + connection setup) and {@link import("./room-session").RoomSession} (for
+ * per-room dispatcher).
+ */
+interface RoomContextOptions {
+  serviceCtx: ServiceContext;
+  api: BilibiliAPI;
+  push: PushLike;
+  contentBuilder: LiveContentBuilder;
+  templateRenderer: LiveTemplateRenderer;
+  wordcloudGenerator: WordcloudGenerator;
+  liveSummaryRequester: LiveSummaryRequester;
+  danmakuCollector: DanmakuCollector;
+  imageRenderer: ImageRenderer | null;
+  config: ListenerManagerConfig;
+  emitEngineError: (message: string) => void;
+  /**
+   * 推送 per-UID 直播状态变化(`onLiveStart` / `onLiveEnd` / `bootstrap 已开播` /
+   * `stopMonitoring 时挂掉的活房间`)。Adapter 实现:
+   *   - standalone: `(uid, status) => bus.emit("live-state-changed", uid, status)`
+   *   - koishi:     `(uid, status) => ctx.emit("bilibili-notify/live-state-changed", uid, status)`
+   * 可选;缺省时不推送 —— 仅在 dashboard 走 WS 实时刷新"正在直播"面板时有意义。
+   */
+  emitLiveState?: (uid: string, status: "live" | "idle") => void;
+  /**
+   * 推送 per-UID 累计观看人数变化(B 站 `WATCHED_CHANGE` 帧节流后转发)。Adapter
+   * 实现与 emitLiveState 同型:
+   *   - standalone: `(uid, viewers) => bus.emit("live-viewers-changed", uid, viewers)`
+   *   - koishi:     `(uid, viewers) => ctx.emit("bilibili-notify/live-viewers-changed", uid, viewers)`
+   * 可选;缺省时不推送。room-session 在调用前做 per-UID 2s throttle,所以这里收到
+   * 的频率已经稀疏(每个直播间最多每 2s 一次)。
+   */
+  emitViewers?: (uid: string, viewers: string) => void;
+}
+/**
+ * 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.
+ */
+declare class RoomContextBase {
+  readonly serviceCtx: ServiceContext;
+  readonly logger: Logger;
+  readonly api: BilibiliAPI;
+  readonly push: PushLike;
+  readonly contentBuilder: LiveContentBuilder;
+  readonly templateRenderer: LiveTemplateRenderer;
+  readonly wordcloudGenerator: WordcloudGenerator;
+  readonly liveSummaryRequester: LiveSummaryRequester;
+  readonly danmakuCollector: DanmakuCollector;
+  /**
+   * 真实注入的渲染器引用,private 是因为外部应通过 `imageRenderer` getter 访问 ——
+   * 后者会在 `config.imageEnabled === false` 时返回 null,让所有
+   * `if (this.imageRenderer?.generateXxx)` 自然落入文字回退分支。
+   */
+  private readonly _imageRenderer;
+  readonly emitEngineError: (message: string) => void;
+  private readonly _emitLiveState;
+  private readonly _emitViewers;
+  config: ListenerManagerConfig;
+  readonly listenerRecord: Record<string, MessageListener>;
+  readonly livePushTimerManager: Map<string, () => void>;
+  private disposed;
+  /** Cached protobuf type for INTERACT_WORD_V2 decoding (lazy-loaded). */
+  protected interactWord?: protobuf.Type;
+  /**
+   * 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.
+   */
+  protected interactWordUnavailable: boolean;
+  private readonly instanceId;
+  constructor(opts: RoomContextOptions);
+  /**
+   * 安全调用方:adapter 未注入时静默 no-op,业务代码无需在调用点判空。
+   */
+  emitLiveState(uid: string, status: "live" | "idle"): void;
+  /**
+   * 同型 no-op 安全调用方。room-session 已做 per-UID 节流,这里只是分发。
+   */
+  emitViewers(uid: string, viewers: string): void;
+  /** 受 `config.imageEnabled` 门控的渲染器视图;关闭时返回 null。 */
+  get imageRenderer(): ImageRenderer | null;
+  updateConfig(config: ListenerManagerConfig): void;
+  isDisposed(): boolean;
+  setDisposed(value: boolean): void;
+  getListenerCount(): number;
+  logSideEffectState(stage: string): void;
+  hasTargets(sub: SubItemView, ...types: LivePushFeature[]): boolean;
+  isSubscribed(sub: SubItemView, type: LiveMasterFeature): boolean;
+  needsLiveMonitor(sub: SubItemView): boolean;
+  closeListener(roomId: string): void;
+  clearListeners(): void;
+  clearPushTimers(): void;
+  stopMonitoring(reason: string, roomId?: string): void;
+}
+//#endregion
+//#region src/room-helpers.d.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.
+ */
+declare class RoomContext 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.
+   */
+  startLiveRoomListener(roomId: string, handler: MsgHandler, shouldAbort?: () => boolean): Promise<boolean>;
+  /** Fetch live-room info; on failure, notifies admin + tears down this room. */
+  getLiveRoomInfo(roomId: string): Promise<LiveRoomInfo["data"] | undefined>;
+  /**
+   * Fetch + project a `MasterInfo` snapshot. Carries forward `liveOpenFollowerNum`
+   * across mid-session refreshes so that the live-end card reports an accurate
+   * follower delta.
+   */
+  getMasterInfo(uid: string, previous: MasterInfo | undefined, liveType: LiveType): Promise<MasterInfo>;
+  /** Fire-and-forget push wrapper; logs + drops any rejection. */
+  safeBroadcast(uid: string, content: unknown, type: LivePushType): void;
+  /**
+   * 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.
+   */
+  sendLiveNotifyCard(params: {
+    liveType: LiveType;
+    liveData: LiveData;
+    liveRoomInfo: LiveRoomInfo["data"];
+    master: MasterInfo;
+    cardStyle: SubItemView["customCardStyle"];
+    uid: string;
+    notifyMsg: string;
+  }): Promise<void>;
+  /** Format `dateString` (yyyy-MM-dd HH:mm:ss UTC+8) as elapsed-time text. */
+  getTimeDifference(dateString: string): Promise<string>;
+  /**
+   * 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/`——字段号必须来自可信源,不可臆造,故作为独立后续任务。
+   */
+  decodeBase64PB(base64: string): Promise<Record<string, unknown>>;
+}
+//#endregion
+//#region src/room-session-base.d.ts
+/**
+ * Cooldown window between accepting `onLiveStart` / `onLiveEnd` events; the
+ * Bilibili WS sometimes fires duplicates for the same transition.
+ */
+declare const LIVE_EVENT_COOLDOWN: number;
+/**
+ * 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.
+ */
+declare abstract class RoomSessionBase {
+  protected readonly ctx: RoomContext;
+  protected readonly sub: SubItemView;
+  protected liveTime: string;
+  protected liveStatus: boolean;
+  protected liveRoomInfo: LiveRoomInfo["data"] | undefined;
+  protected masterInfo: MasterInfo | undefined;
+  protected readonly liveData: LiveData;
+  protected pushAtTimeTimer: Disposable | null;
+  protected lastLiveStart: number;
+  protected lastLiveEnd: number;
+  constructor(ctx: RoomContext, sub: SubItemView);
+  /** Whether the underlying B-station room is currently broadcasting. */
+  get isLive(): boolean;
+  /**
+   * 唯一允许翻转 `liveStatus` 的入口。只在真实 transition 时通过 RoomContext
+   * 推送 `live-state-changed` 事件,前端的"正在直播"面板靠它实时收敛。
+   * 直接赋值 `this.liveStatus = ...` 会绕过这里,**不要这样做**。
+   */
+  protected setLiveStatus(next: boolean): void;
+  /**
+   * 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(): {
+    uid: string;
+    roomId: string;
+    isLive: boolean;
+    title?: string;
+    cover?: string;
+    areaName?: string;
+    startedAt?: string;
+    /**
+     * B 站 WS `WATCHED_CHANGE` 帧给出的"累计观看人数",预格式化字符串(如 "1.2万")。
+     * 还没收到该帧时为 undefined,前端显示 "—"。我们不存原始 num,因为 bilibili 自己
+     * 给的 text_small 已是用户预期的中文压缩形式。
+     */
+    viewers?: string;
+  };
+  /**
+   * 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.
+   */
+  bootstrap(): Promise<void>;
+  /** Build the platform-specific {@link MsgHandler}; provided by the subclass. */
+  protected abstract buildHandler(): MsgHandler;
+  protected useLiveRoomInfo(liveType: LiveType): Promise<boolean>;
+  protected useMasterInfo(liveType: LiveType): Promise<boolean>;
+  /**
+   * Live 配置 `pushTime` 热更后调用:重新按当前(可能已变更的) `pushTime`
+   * arm 定时器。仅对正在直播的房间生效,因为只有 live 状态下才会有 timer。
+   *
+   * 注意:`setInterval` 句柄的 ms 参数是 immutable,只能 dispose 重建。
+   */
+  rearmPeriodicTimer(): void;
+  protected armPeriodicTimer(): void;
+  protected cancelPeriodicTimer(): void;
+  /** Periodic "正在直播" tick (callback for `setInterval`). */
+  protected tickPushAtTime(): Promise<void>;
+  /**
+   * 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.
+   */
+  protected handleLiveEnd(source: "ws" | "polling"): Promise<void>;
+  /**
+   * Run wordcloud + AI live-summary in parallel and dispatch whichever
+   * succeeded. Skipped entirely when neither feature is subscribed.
+   */
+  protected dispatchWordCloudAndSummary(customLiveSummary: string): Promise<void>;
+}
+//#endregion
+//#region src/room-session.d.ts
+declare class RoomSession extends RoomSessionBase {
+  private lastViewersEmitMs;
+  /**
+   * 当前 RoomSession 是否已被外层(stopForUid / disposeAll / liveEnd 主动关闭)取消。
+   * 一旦设为 true,onError 跳过重连。listener-manager.stopForUid 在 closeListener
+   * 之前调用 cancel() 设置。
+   */
+  private cancelled;
+  private reconnectAttempts;
+  /**
+   * L1 单飞守卫:并发 onError(WS 错误常突发多帧)若都进入重连路径,会各自
+   * closeListener + 退避 + startLiveRoomListener,装回多个 listener。一旦一个
+   * onError 拿到重连权,其余直接返回。
+   */
+  private reconnecting;
+  /** L3:退避 sleep 的 Disposable + 唤醒句柄,cancel/teardown 时清掉,不留回调到 expiry。 */
+  private reconnectTimer?;
+  private reconnectWake?;
+  /** 外层主动停止 listener 时调用,阻止 onError 触发重连。 */
+  cancel(): void;
+  /** L3:dispose 退避定时器并唤醒重连循环,使其立刻重校 cancelled/disposed 后退出。 */
+  private clearReconnectSleep;
+  protected buildHandler(): MsgHandler;
+  private onError;
+  /**
+   * 退避重连循环(单飞,由 onError 持有)。`while` 取代旧的 `setTimeout(0)`
+   * 递归续链 —— 杜绝深栈递归 + 每步都丢弃的定时器 Disposable;每次 sleep 后
+   * 重校 cancelled/disposed,sleep 自身可被 cancel/teardown dispose。
+   */
+  private reconnectLoop;
+  /**
+   * L3:可被 {@link clearReconnectSleep} 取消的退避 sleep。dispose 时立即
+   * resolve,让 reconnectLoop 醒来重校 cancelled/disposed 后退出 —— 不再留
+   * 一个无法清除的延迟回调到 expiry。
+   */
+  private sleepReconnect;
+  private onIncomeDanmu;
+  private onIncomeSuperChat;
+  private onGuardBuy;
+  private onLiveStart;
+  private onLiveEnd;
+  private onInteractWordV2;
+}
+//#endregion
+//#region src/listener-manager.d.ts
+/**
+ * Constructor options for {@link ListenerManager}. Same shape as
+ * {@link RoomContextOptions}; the manager builds its `RoomContext` internally.
+ */
+type ListenerManagerOptions = RoomContextOptions;
+/**
+ * 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.
+ */
+declare class ListenerManager {
+  private readonly ctx;
+  private readonly subRecord;
+  private readonly sessionRecord;
+  constructor(opts: ListenerManagerOptions);
+  /** Replace runtime config (called when the adapter receives a config update). */
+  updateConfig(config: ListenerManagerConfig): void;
+  isDisposed(): boolean;
+  getListenerCount(): number;
+  /** Active mutable sub by uid (used by `applyOps` to detect existence). */
+  getActiveSub(uid: string): SubItemView | undefined;
+  /**
+   * 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(): ReturnType<RoomSession["getLiveSnapshot"]>[];
+  /**
+   * `pushTime` 热更后调用:把所有 active session 的"正在直播"复推 timer 按当前
+   * `pushTime` 重新 arm。LiveEngine.updateConfig 在检测到变化时转发。
+   */
+  rearmAllPeriodicTimers(): void;
+  /**
+   * 单个 UID 的 pushTime 热更入口。LiveEngine.applyOps 在 update 分支检测到
+   * `LiveScopedChange.pushTime` 变化时调用,仅对该 uid 的活跃 session rearm。
+   */
+  rearmPeriodicTimerForUid(uid: string): void;
+  /** Whether any feature on this sub requires the live-room WS connection. */
+  needsLiveMonitor(sub: SubItemView): boolean;
+  /** Start listeners for everything in `subs` that needs one. */
+  startAll(subs: Record<string, SubItemView>): void;
+  /** Start a single sub's listener via a fresh {@link RoomSession}. */
+  startForUid(sub: SubItemView, logPrefix?: string): void;
+  private bootstrapForUid;
+  private resolveRoomId;
+  /** Stop a single sub's listener and drop its bookkeeping. */
+  stopForUid(uid: string): void;
+  /** Tear down everything. Used by engine `stop()` / `auth-lost`. */
+  disposeAll(): void;
+  /** Tear down listeners + timers but keep registry / disposed flag intact. */
+  clearListeners(): void;
+  /** Cancel every periodic "正在直播" timer. */
+  clearPushTimers(): void;
+}
+//#endregion
+//#region src/live-engine.d.ts
+/**
+ * Top-level platform-neutral configuration for {@link LiveEngine}.
+ *
+ * Mirrors the runtime-relevant subset of `BilibiliNotifyLiveConfig` (the koishi
+ * Schema). Adapters translate their native config into this struct.
+ *
+ * The engine intentionally drops `logLevel` (the adapter sets it on the
+ * provided logger before construction) and folds `liveSummary` (originally a
+ * `string[]` joined by `\n`) into a single `liveSummaryDefault` string per the
+ * plan's §七 "customLiveSummary string vs string[]" cleanup.
+ */
+interface LiveEngineConfig {
+  /**
+   * Comma-separated additional stop-words appended to the bundled
+   * Chinese-stop-word list before tokenisation.
+   */
+  wordcloudStopWords?: string;
+  /** Hours between periodic "正在直播" pushes; `0` disables. */
+  pushTime: number;
+  /** Whether to push a "正在直播" card immediately on engine start when a sub is live. */
+  restartPush: boolean;
+  /** SC minimum-price gate (yuan); SC under this value is dropped. */
+  minScPrice: number;
+  /**
+   * Lowest allowed guard tier to push (1 = governor, 2 = supervisor,
+   * 3 = captain — preserves Bilibili semantics).
+   */
+  minGuardLevel: 1 | 2 | 3;
+  /** Default global "弹幕总结" template (single string; adapter joins lines if needed). */
+  liveSummaryDefault: string;
+  customGuardBuy: ListenerManagerConfig["customGuardBuy"];
+  customLiveMsg: ListenerManagerConfig["customLiveMsg"];
+  /**
+   * 是否启用图片卡片渲染。`false` 时直播开播 / SC / 上舰 / 弹幕词云全部走文字回退。
+   * 缺省视为 true。Adapter 通常用 `globals.defaults.cardStyle.enabled` 填充。
+   */
+  imageEnabled?: boolean;
+  /**
+   * 是否启用 AI 直播总结。`false` 时跳过 commentary 调用,直接走模板回退。
+   * 缺省视为 true。Adapter 通常用 `globals.defaults.ai.enabled` 填充。
+   */
+  aiEnabled?: boolean;
+}
+interface LiveEngineOptions {
+  serviceCtx: ServiceContext;
+  api: BilibiliAPI;
+  push: PushLike;
+  contentBuilder: LiveContentBuilder;
+  /** Optional — if absent, image-based pushes are skipped / fall back to text. */
+  imageRenderer?: ImageRenderer | null;
+  /** Optional — if absent, live summaries fall back to the configured template. */
+  commentary?: CommentaryGenerator | null;
+  config: LiveEngineConfig;
+  /**
+   * Called by the engine to surface an `engine-error` to the host. Adapters
+   * forward this to their MessageBus / koishi `ctx.emit('bilibili-notify/engine-error')`.
+   */
+  emitEngineError: (message: string) => void;
+  /**
+   * Optional — adapter pipe for per-UID live-state transitions. Adapter forwards
+   * to `bus.emit("live-state-changed", uid, status)`. When absent the engine
+   * runs without state broadcasts (koishi shell may opt out if it has nothing
+   * subscribing).
+   */
+  emitLiveState?: (uid: string, status: "live" | "idle") => void;
+  /**
+   * Optional — adapter pipe for per-UID watched-count updates. Adapter forwards
+   * to `bus.emit("live-viewers-changed", uid, viewers)`. Throttled per-UID to
+   * 2s at the room-session boundary.
+   */
+  emitViewers?: (uid: string, viewers: string) => void;
+}
+/**
+ * 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.
+ */
+declare class LiveEngine {
+  private readonly logger;
+  private readonly listener;
+  private readonly danmakuCollector;
+  private readonly liveSummaryRequester;
+  private config;
+  constructor(opts: LiveEngineOptions);
+  /**
+   * Bootstrap the engine with the initial subscription set. Idempotent —
+   * calling it again replaces the active set (used by `auth-restored`).
+   */
+  start(subs: SubscriptionsView): void;
+  /** Tear down all listeners + per-room state, leaving the engine instance reusable. */
+  teardown(): void;
+  /** Full rebootstrap. Used after auth-restored. */
+  rebuildFromSubs(subs: SubscriptionsView): void;
+  /**
+   * 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: LiveSubscriptionOp[], lookupFullSub: (uid: string) => SubItemView | undefined): void;
+  /** Replace runtime config (called when the adapter receives a config-changed event). */
+  updateConfig(config: LiveEngineConfig): void;
+  /**
+   * 热替换 CommentaryGenerator 实例。adapter 在用户运行时打开 / 关闭 / 更换 AI
+   * 配置后调用,引擎随后的直播总结会立即用新实例 (或回退到模板) ,无需重启 server。
+   */
+  setCommentary(commentary: CommentaryGenerator | null): void;
+  /** Final dispose; the engine instance must not be reused after this. */
+  stop(): void;
+  /** Diagnostic accessor, used by the koishi shell for `[conn] state` logging. */
+  get listenerCount(): number;
+  /**
+   * Per-room live-state snapshot for every active monitor. Routes / dashboards
+   * filter on `isLive` to show "正在直播" panels.
+   */
+  listLiveSnapshots(): ReturnType<ListenerManager["listLiveSnapshots"]>;
+  /** Read-only view of the engine config (for the koishi shell to pass through). */
+  getConfig(): LiveEngineConfig;
+}
+//#endregion
+//#region src/stop-words.d.ts
+declare const stopwords: Set<string>;
+//#endregion
+export { type CustomCardStyleLike, type CustomGuardBuyLike, type CustomLiveMsgLike, type CustomLiveSummaryLike, type CustomSpecialDanmakuUsersLike, type CustomSpecialUsersEnterTheRoomLike, DEFAULT_LIVE_TEMPLATES, DanmakuCollector, type DynamicScopedChange, LIVE_EVENT_COOLDOWN, LIVE_ROOM_MASTER_KEYS, LIVE_SUMMARY_MIN_SENDERS, ListenerManager, type ListenerManagerConfig, type ListenerManagerOptions, type LiveContentBuilder, type LiveData, LiveEngine, type LiveEngineConfig, type LiveEngineOptions, type LiveMasterFeature, type LivePushFeature, type LivePushTimerManager, LivePushType, type LiveScopedChange, type LiveSubChange, type LiveSubscriptionOp, LiveSummaryRequester, LiveTemplateRenderer, LiveType, type MasterInfo, type PushLike, RoomContext, RoomContextBase, type RoomContextOptions, RoomSession, RoomSessionBase, type SubItemTargetLike, type SubItemView, type SubscriptionsView, type TargetScopedChange, type UserInfoInLiveData, WORDCLOUD_MIN_WORDS, WORDCLOUD_TOP_WORDS, WordcloudGenerator, buildRoomLink, stopwords as defaultStopWords, formatFollowerChange, formatFollowerCount };