@bilibili-notify/live 0.0.1-alpha.2 → 0.1.0-alpha.4

package/lib/index.cjs

@@ -168,11 +168,16 @@ var RoomContextBase = class {
 	liveSummaryRequester;
 	danmakuCollector;
 	/**
-	* 真实注入的渲染器引用,private 是因为外部应通过 `imageRenderer` getter 访问 ——
+	* 渲染器 provider —— private 是因为外部应通过 `imageRenderer` getter 访问 ——
 	* 后者会在 `config.imageEnabled === false` 时返回 null,让所有
 	* `if (this.imageRenderer?.generateXxx)` 自然落入文字回退分支。
+	* provider 形式让 LiveEngine 的 setImageRenderer 无需逐 RoomContext 推。
+	*
+	* **不要直接调 `this._getImageRenderer()` 绕过 imageEnabled 门控**,业务路径
+	* 必须通过 `this.imageRenderer` getter,否则用户在 dashboard 关掉卡片渲染时
+	* 这条路径仍会渲图。
 	*/
-	_imageRenderer;
+	_getImageRenderer;
 	emitEngineError;
 	_emitLiveState;
 	_emitViewers;
@@ -199,7 +204,7 @@ var RoomContextBase = class {
 		this.wordcloudGenerator = opts.wordcloudGenerator;
 		this.liveSummaryRequester = opts.liveSummaryRequester;
 		this.danmakuCollector = opts.danmakuCollector;
-		this._imageRenderer = opts.imageRenderer;
+		this._getImageRenderer = opts.getImageRenderer;
 		this.config = opts.config;
 		this.emitEngineError = opts.emitEngineError;
 		this._emitLiveState = opts.emitLiveState;
@@ -219,7 +224,7 @@ var RoomContextBase = class {
 	}
 	/** 受 `config.imageEnabled` 门控的渲染器视图;关闭时返回 null。 */
 	get imageRenderer() {
-		return this.config.imageEnabled === false ? null : this._imageRenderer;
+		return this.config.imageEnabled === false ? null : this._getImageRenderer();
 	}
 	updateConfig(config) {
 		this.config = config;
@@ -494,37 +499,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,
@@ -554,27 +563,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)
 		});
 	}
 	/**
@@ -583,24 +592,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
 		});
 	}
 	/**
@@ -613,19 +622,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]}`
 		});
 	}
 };
@@ -1576,11 +1585,11 @@ const WORDCLOUD_TOP_WORDS = 90;
 * platform (e.g. via `LiveContentBuilder.image`).
 */
 var WordcloudGenerator = class {
-	imageRenderer;
+	getImageRenderer;
 	isImageEnabled;
 	logger;
 	constructor(opts) {
-		this.imageRenderer = opts.imageRenderer;
+		this.getImageRenderer = opts.getImageRenderer;
 		this.isImageEnabled = opts.isImageEnabled ?? (() => true);
 		this.logger = opts.logger;
 	}
@@ -1602,9 +1611,10 @@ var WordcloudGenerator = class {
 			this.logger.debug("[wordcloud] cardStyle.enabled=false,跳过词云图片生成");
 			return;
 		}
-		if (!this.imageRenderer?.generateWordCloudImg) return void 0;
+		const renderer = this.getImageRenderer();
+		if (!renderer?.generateWordCloudImg) return void 0;
 		try {
-			return await this.imageRenderer.generateWordCloudImg(sortedWords.slice(0, 90), masterName, masterAvatarUrl);
+			return await renderer.generateWordCloudImg(sortedWords.slice(0, 90), masterName, masterAvatarUrl);
 		} catch (e) {
 			this.logger.error(`[wordcloud] 生成词云失败：${e.message}`);
 			return;
@@ -1634,14 +1644,22 @@ var LiveEngine = class {
 	danmakuCollector;
 	liveSummaryRequester;
 	config;
+	/**
+	* Image 渲染器的当前引用 —— 单一可变 state,setImageRenderer 在此更新;
+	* 所有子组件(wordcloud / listener / room-context)通过 provider 函数现取,
+	* 无需逐组件 setter 推送。
+	*/
+	currentImageRenderer;
 	constructor(opts) {
 		this.logger = opts.serviceCtx.logger;
 		this.config = opts.config;
+		this.currentImageRenderer = opts.imageRenderer ?? null;
+		const getImageRenderer = () => this.currentImageRenderer;
 		const stopwords = mergeStopWords(opts.config.wordcloudStopWords);
 		this.danmakuCollector = new DanmakuCollector(stopwords);
 		const templateRenderer = new LiveTemplateRenderer();
 		const wordcloudGenerator = new WordcloudGenerator({
-			imageRenderer: opts.imageRenderer ?? null,
+			getImageRenderer,
 			isImageEnabled: () => this.config.imageEnabled !== false,
 			logger: this.logger
 		});
@@ -1661,7 +1679,7 @@ var LiveEngine = class {
 			wordcloudGenerator,
 			liveSummaryRequester,
 			danmakuCollector: this.danmakuCollector,
-			imageRenderer: opts.imageRenderer ?? null,
+			getImageRenderer,
 			config: toListenerConfig(opts.config),
 			emitEngineError: opts.emitEngineError,
 			emitLiveState: opts.emitLiveState,
@@ -1744,6 +1762,17 @@ var LiveEngine = class {
 	setCommentary(commentary) {
 		this.liveSummaryRequester.setCommentary(commentary);
 	}
+	/**
+	* 热替换 ImageRenderer 实例。adapter 在 image 服务上下线时调用。子组件 (词云 /
+	* room-context / 卡片渲染) 都通过共享 provider 现取,这里只需更新单一 state。
+	*
+	* 主要给 koishi adapter 用 —— sibling service (-image) 启停时通过 ctx.inject
+	* 后置注入。独立端 imageRenderer 是 engine 同进程一次性 wire,不会动态消失,
+	* 不需要调用本方法 (cardStyle 热更走 imageRenderer.updateConfig)。
+	*/
+	setImageRenderer(imageRenderer) {
+		this.currentImageRenderer = imageRenderer;
+	}
 	/** Final dispose; the engine instance must not be reused after this. */
 	stop() {
 		this.listener.disposeAll();

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: "弹幕总结";
 };
 /**
@@ -433,11 +433,16 @@ declare const WORDCLOUD_TOP_WORDS = 90;
  * platform (e.g. via `LiveContentBuilder.image`).
  */
 declare class WordcloudGenerator {
-  private readonly imageRenderer;
+  private readonly getImageRenderer;
   private readonly isImageEnabled;
   private readonly logger;
   constructor(opts: {
-    imageRenderer: ImageRenderer | null;
+    /**
+     * 渲染器 provider —— 每次 generate() 现取最新引用,使 LiveEngine 在 image
+     * 服务上下线时通过 setImageRenderer 替换内部状态,词云生成自动同步,无需子组件
+     * 接 setter。
+     */
+    getImageRenderer: () => ImageRenderer | null;
     /**
      * 卡片渲染总开关查询。返回 false 时直接跳过 puppeteer 调用,与缺失 imageRenderer
      * 等价。Adapter 通常用 `() => globals.defaults.cardStyle.enabled` 填充;缺省 () => true。
@@ -502,7 +507,11 @@ interface RoomContextOptions {
   wordcloudGenerator: WordcloudGenerator;
   liveSummaryRequester: LiveSummaryRequester;
   danmakuCollector: DanmakuCollector;
-  imageRenderer: ImageRenderer | null;
+  /**
+   * 渲染器 provider —— LiveEngine 在 image 服务上下线时通过 setImageRenderer
+   * 替换内部状态;getter `imageRenderer` 每次现取,所有 RoomContext 自动同步。
+   */
+  getImageRenderer: () => ImageRenderer | null;
   config: ListenerManagerConfig;
   emitEngineError: (message: string) => void;
   /**
@@ -546,11 +555,16 @@ declare class RoomContextBase {
   readonly liveSummaryRequester: LiveSummaryRequester;
   readonly danmakuCollector: DanmakuCollector;
   /**
-   * 真实注入的渲染器引用,private 是因为外部应通过 `imageRenderer` getter 访问 ——
+   * 渲染器 provider —— private 是因为外部应通过 `imageRenderer` getter 访问 ——
    * 后者会在 `config.imageEnabled === false` 时返回 null,让所有
    * `if (this.imageRenderer?.generateXxx)` 自然落入文字回退分支。
+   * provider 形式让 LiveEngine 的 setImageRenderer 无需逐 RoomContext 推。
+   *
+   * **不要直接调 `this._getImageRenderer()` 绕过 imageEnabled 门控**,业务路径
+   * 必须通过 `this.imageRenderer` getter,否则用户在 dashboard 关掉卡片渲染时
+   * 这条路径仍会渲图。
    */
-  private readonly _imageRenderer;
+  private readonly _getImageRenderer;
   readonly emitEngineError: (message: string) => void;
   private readonly _emitLiveState;
   private readonly _emitViewers;
@@ -950,6 +964,12 @@ declare class LiveEngine {
   private readonly danmakuCollector;
   private readonly liveSummaryRequester;
   private config;
+  /**
+   * Image 渲染器的当前引用 —— 单一可变 state,setImageRenderer 在此更新;
+   * 所有子组件(wordcloud / listener / room-context)通过 provider 函数现取,
+   * 无需逐组件 setter 推送。
+   */
+  private currentImageRenderer;
   constructor(opts: LiveEngineOptions);
   /**
    * Bootstrap the engine with the initial subscription set. Idempotent —
@@ -973,6 +993,15 @@ declare class LiveEngine {
    * 配置后调用,引擎随后的直播总结会立即用新实例 (或回退到模板) ,无需重启 server。
    */
   setCommentary(commentary: CommentaryGenerator | null): void;
+  /**
+   * 热替换 ImageRenderer 实例。adapter 在 image 服务上下线时调用。子组件 (词云 /
+   * room-context / 卡片渲染) 都通过共享 provider 现取,这里只需更新单一 state。
+   *
+   * 主要给 koishi adapter 用 —— sibling service (-image) 启停时通过 ctx.inject
+   * 后置注入。独立端 imageRenderer 是 engine 同进程一次性 wire,不会动态消失,
+   * 不需要调用本方法 (cardStyle 热更走 imageRenderer.updateConfig)。
+   */
+  setImageRenderer(imageRenderer: ImageRenderer | 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. */

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: "弹幕总结";
 };
 /**
@@ -433,11 +433,16 @@ declare const WORDCLOUD_TOP_WORDS = 90;
  * platform (e.g. via `LiveContentBuilder.image`).
  */
 declare class WordcloudGenerator {
-  private readonly imageRenderer;
+  private readonly getImageRenderer;
   private readonly isImageEnabled;
   private readonly logger;
   constructor(opts: {
-    imageRenderer: ImageRenderer | null;
+    /**
+     * 渲染器 provider —— 每次 generate() 现取最新引用,使 LiveEngine 在 image
+     * 服务上下线时通过 setImageRenderer 替换内部状态,词云生成自动同步,无需子组件
+     * 接 setter。
+     */
+    getImageRenderer: () => ImageRenderer | null;
     /**
      * 卡片渲染总开关查询。返回 false 时直接跳过 puppeteer 调用,与缺失 imageRenderer
      * 等价。Adapter 通常用 `() => globals.defaults.cardStyle.enabled` 填充;缺省 () => true。
@@ -502,7 +507,11 @@ interface RoomContextOptions {
   wordcloudGenerator: WordcloudGenerator;
   liveSummaryRequester: LiveSummaryRequester;
   danmakuCollector: DanmakuCollector;
-  imageRenderer: ImageRenderer | null;
+  /**
+   * 渲染器 provider —— LiveEngine 在 image 服务上下线时通过 setImageRenderer
+   * 替换内部状态;getter `imageRenderer` 每次现取,所有 RoomContext 自动同步。
+   */
+  getImageRenderer: () => ImageRenderer | null;
   config: ListenerManagerConfig;
   emitEngineError: (message: string) => void;
   /**
@@ -546,11 +555,16 @@ declare class RoomContextBase {
   readonly liveSummaryRequester: LiveSummaryRequester;
   readonly danmakuCollector: DanmakuCollector;
   /**
-   * 真实注入的渲染器引用,private 是因为外部应通过 `imageRenderer` getter 访问 ——
+   * 渲染器 provider —— private 是因为外部应通过 `imageRenderer` getter 访问 ——
    * 后者会在 `config.imageEnabled === false` 时返回 null,让所有
    * `if (this.imageRenderer?.generateXxx)` 自然落入文字回退分支。
+   * provider 形式让 LiveEngine 的 setImageRenderer 无需逐 RoomContext 推。
+   *
+   * **不要直接调 `this._getImageRenderer()` 绕过 imageEnabled 门控**,业务路径
+   * 必须通过 `this.imageRenderer` getter,否则用户在 dashboard 关掉卡片渲染时
+   * 这条路径仍会渲图。
    */
-  private readonly _imageRenderer;
+  private readonly _getImageRenderer;
   readonly emitEngineError: (message: string) => void;
   private readonly _emitLiveState;
   private readonly _emitViewers;
@@ -950,6 +964,12 @@ declare class LiveEngine {
   private readonly danmakuCollector;
   private readonly liveSummaryRequester;
   private config;
+  /**
+   * Image 渲染器的当前引用 —— 单一可变 state,setImageRenderer 在此更新;
+   * 所有子组件(wordcloud / listener / room-context)通过 provider 函数现取,
+   * 无需逐组件 setter 推送。
+   */
+  private currentImageRenderer;
   constructor(opts: LiveEngineOptions);
   /**
    * Bootstrap the engine with the initial subscription set. Idempotent —
@@ -973,6 +993,15 @@ declare class LiveEngine {
    * 配置后调用,引擎随后的直播总结会立即用新实例 (或回退到模板) ,无需重启 server。
    */
   setCommentary(commentary: CommentaryGenerator | null): void;
+  /**
+   * 热替换 ImageRenderer 实例。adapter 在 image 服务上下线时调用。子组件 (词云 /
+   * room-context / 卡片渲染) 都通过共享 provider 现取,这里只需更新单一 state。
+   *
+   * 主要给 koishi adapter 用 —— sibling service (-image) 启停时通过 ctx.inject
+   * 后置注入。独立端 imageRenderer 是 engine 同进程一次性 wire,不会动态消失,
+   * 不需要调用本方法 (cardStyle 热更走 imageRenderer.updateConfig)。
+   */
+  setImageRenderer(imageRenderer: ImageRenderer | 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. */

package/lib/index.mjs

@@ -144,11 +144,16 @@ var RoomContextBase = class {
 	liveSummaryRequester;
 	danmakuCollector;
 	/**
-	* 真实注入的渲染器引用,private 是因为外部应通过 `imageRenderer` getter 访问 ——
+	* 渲染器 provider —— private 是因为外部应通过 `imageRenderer` getter 访问 ——
 	* 后者会在 `config.imageEnabled === false` 时返回 null,让所有
 	* `if (this.imageRenderer?.generateXxx)` 自然落入文字回退分支。
+	* provider 形式让 LiveEngine 的 setImageRenderer 无需逐 RoomContext 推。
+	*
+	* **不要直接调 `this._getImageRenderer()` 绕过 imageEnabled 门控**,业务路径
+	* 必须通过 `this.imageRenderer` getter,否则用户在 dashboard 关掉卡片渲染时
+	* 这条路径仍会渲图。
 	*/
-	_imageRenderer;
+	_getImageRenderer;
 	emitEngineError;
 	_emitLiveState;
 	_emitViewers;
@@ -175,7 +180,7 @@ var RoomContextBase = class {
 		this.wordcloudGenerator = opts.wordcloudGenerator;
 		this.liveSummaryRequester = opts.liveSummaryRequester;
 		this.danmakuCollector = opts.danmakuCollector;
-		this._imageRenderer = opts.imageRenderer;
+		this._getImageRenderer = opts.getImageRenderer;
 		this.config = opts.config;
 		this.emitEngineError = opts.emitEngineError;
 		this._emitLiveState = opts.emitLiveState;
@@ -195,7 +200,7 @@ var RoomContextBase = class {
 	}
 	/** 受 `config.imageEnabled` 门控的渲染器视图;关闭时返回 null。 */
 	get imageRenderer() {
-		return this.config.imageEnabled === false ? null : this._imageRenderer;
+		return this.config.imageEnabled === false ? null : this._getImageRenderer();
 	}
 	updateConfig(config) {
 		this.config = config;
@@ -470,37 +475,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,
@@ -530,27 +539,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)
 		});
 	}
 	/**
@@ -559,24 +568,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
 		});
 	}
 	/**
@@ -589,19 +598,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]}`
 		});
 	}
 };
@@ -1552,11 +1561,11 @@ const WORDCLOUD_TOP_WORDS = 90;
 * platform (e.g. via `LiveContentBuilder.image`).
 */
 var WordcloudGenerator = class {
-	imageRenderer;
+	getImageRenderer;
 	isImageEnabled;
 	logger;
 	constructor(opts) {
-		this.imageRenderer = opts.imageRenderer;
+		this.getImageRenderer = opts.getImageRenderer;
 		this.isImageEnabled = opts.isImageEnabled ?? (() => true);
 		this.logger = opts.logger;
 	}
@@ -1578,9 +1587,10 @@ var WordcloudGenerator = class {
 			this.logger.debug("[wordcloud] cardStyle.enabled=false,跳过词云图片生成");
 			return;
 		}
-		if (!this.imageRenderer?.generateWordCloudImg) return void 0;
+		const renderer = this.getImageRenderer();
+		if (!renderer?.generateWordCloudImg) return void 0;
 		try {
-			return await this.imageRenderer.generateWordCloudImg(sortedWords.slice(0, 90), masterName, masterAvatarUrl);
+			return await renderer.generateWordCloudImg(sortedWords.slice(0, 90), masterName, masterAvatarUrl);
 		} catch (e) {
 			this.logger.error(`[wordcloud] 生成词云失败：${e.message}`);
 			return;
@@ -1610,14 +1620,22 @@ var LiveEngine = class {
 	danmakuCollector;
 	liveSummaryRequester;
 	config;
+	/**
+	* Image 渲染器的当前引用 —— 单一可变 state,setImageRenderer 在此更新;
+	* 所有子组件(wordcloud / listener / room-context)通过 provider 函数现取,
+	* 无需逐组件 setter 推送。
+	*/
+	currentImageRenderer;
 	constructor(opts) {
 		this.logger = opts.serviceCtx.logger;
 		this.config = opts.config;
+		this.currentImageRenderer = opts.imageRenderer ?? null;
+		const getImageRenderer = () => this.currentImageRenderer;
 		const stopwords = mergeStopWords(opts.config.wordcloudStopWords);
 		this.danmakuCollector = new DanmakuCollector(stopwords);
 		const templateRenderer = new LiveTemplateRenderer();
 		const wordcloudGenerator = new WordcloudGenerator({
-			imageRenderer: opts.imageRenderer ?? null,
+			getImageRenderer,
 			isImageEnabled: () => this.config.imageEnabled !== false,
 			logger: this.logger
 		});
@@ -1637,7 +1655,7 @@ var LiveEngine = class {
 			wordcloudGenerator,
 			liveSummaryRequester,
 			danmakuCollector: this.danmakuCollector,
-			imageRenderer: opts.imageRenderer ?? null,
+			getImageRenderer,
 			config: toListenerConfig(opts.config),
 			emitEngineError: opts.emitEngineError,
 			emitLiveState: opts.emitLiveState,
@@ -1720,6 +1738,17 @@ var LiveEngine = class {
 	setCommentary(commentary) {
 		this.liveSummaryRequester.setCommentary(commentary);
 	}
+	/**
+	* 热替换 ImageRenderer 实例。adapter 在 image 服务上下线时调用。子组件 (词云 /
+	* room-context / 卡片渲染) 都通过共享 provider 现取,这里只需更新单一 state。
+	*
+	* 主要给 koishi adapter 用 —— sibling service (-image) 启停时通过 ctx.inject
+	* 后置注入。独立端 imageRenderer 是 engine 同进程一次性 wire,不会动态消失,
+	* 不需要调用本方法 (cardStyle 热更走 imageRenderer.updateConfig)。
+	*/
+	setImageRenderer(imageRenderer) {
+		this.currentImageRenderer = imageRenderer;
+	}
 	/** Final dispose; the engine instance must not be reused after this. */
 	stop() {
 		this.listener.disposeAll();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilibili-notify/live",
-  "version": "0.0.1-alpha.2",
+  "version": "0.1.0-alpha.4",
   "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/image": "^0.0.1-alpha.2",
-    "@bilibili-notify/internal": "^0.1.0-alpha.2"
+    "@bilibili-notify/api": "^0.2.0-alpha.2",
+    "@bilibili-notify/internal": "^0.1.0-alpha.3"
   },
   "devDependencies": {
     "@types/luxon": "^3.4.2",