pi-extensions-i18n 0.4.1 → 0.6.0

package/README.md

@@ -14,6 +14,8 @@ Independent Pi extensions still need the same operational pieces: a portable con
 - `/config:language` interactive command, plus `/config:language en-US` direct selection.
 - Catalog loading and validation requiring both language entries for every message key.
 - Translator interpolation for user-facing UI, command descriptions, and agent prompts.
+- A single notice outlet, `notifyWithSource`, that draws every user-visible notice as a filled background block in the transcript (the same block Pi uses for extension messages) with a short source tag in the package's own label colour. Pi renders `info` notices as dim, unprefixed text, so without the block and tag you cannot tell which extension spoke.
+- Notices land below the message and stay out of the LLM context: they are written as Pi custom entries (`appendEntry` + `registerEntryRenderer`) and only affect the transcript.
 
 ## Install
 
@@ -50,8 +52,24 @@ PI_EXTENSIONS_LOCALE=en-US pi
 ```
 
 ## Extension author API
+The package exports the locale and catalog primitives used by the feature packages, plus the shared notice outlet:
 
-The package exports the locale and catalog primitives used by the feature packages:
+```ts
+import { notifyWithSource, type NoticeColor, type NoticeSource } from "pi-extensions-i18n";
+
+/** Short, unique notice tag for this package. */
+const NOTICE_TAG = "distill";
+/** Label colour; keep it distinct from sibling packages. */
+const NOTICE_COLOR: NoticeColor = "muted";
+/** This package's notice source. */
+const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };
+
+notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "warning", message: i18n.t("failed") });
+```
+
+This renders as a filled background block with `[distill] message` on its first line: the tag carries the package colour, the body colour follows `level` (`warning` yellow, `error` red, `info` the extension message text colour), and `textColor` overrides the body colour for verdict-style lines that carry their own semantic colour. In tui mode the notice is written as a Pi custom entry below the message; rpc/print/json keep using `ctx.ui.notify` with plain `[distill] message` text so no ANSI leaks into other frontends. The block is registered once by this package's own extension entry, so a package that uses the helper must load `../pi-extensions-i18n/index.ts` in its `pi.extensions` list. Use `formatNotice({ source, message, mode, theme })` when you only need the rendered string.
+
+Other exports:
 
 ```ts
 import {

package/README.zh-CN.md

@@ -14,6 +14,8 @@ Pi 扩展公共国际化运行时。它提供基于 catalog 的小型 API，支
 - 提供 `/config:language` 交互式命令，也支持 `/config:language en-US` 直接设置。
 - 加载并校验 catalog，要求每个消息 key 同时提供两种语言。
 - 为 UI、命令描述和 Agent prompt 提供用户文案插值。
+- 提供统一的用户提示出口 `notifyWithSource`：把提示画成会话区里的**带底色消息块**（用户消息同款底色，见下条），并配上「来源标签 + 固定颜色」，解决 Pi 对 `info` 级提示只显示暗灰无前缀文本、用户既分不清来源也不容易注意到的问题。
+- 提示落在消息下方、不进 LLM 上下文：通过 Pi 的自定义条目（`appendEntry` + `registerEntryRenderer`）实现，条目只在本地渲染，不消耗上下文窗口。
 
 ## 安装
 
@@ -23,6 +25,31 @@ pi install npm:pi-extensions-i18n
 
 各功能包会自动安装并加载这个公共依赖，因此安装任意使用它的功能包即可使用语言命令。只有不安装其他功能包、想单独使用语言命令时，才需要直接安装本包。
 
+## 统一的提示出口
+
+```ts
+import { notifyWithSource, type NoticeColor, type NoticeSource } from "pi-extensions-i18n";
+
+/** 本扩展的提示标签；短且唯一。 */
+const NOTICE_TAG = "distill";
+/** 提示标签颜色；与其它扩展错开。 */
+const NOTICE_COLOR: NoticeColor = "muted";
+/** 本扩展的提示来源。 */
+const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };
+
+notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "warning", message: i18n.t("failed") });
+```
+
+输出是一个和用户消息同款的**实心底色块**，首行是 `[distill] 提示正文`：标签按扩展固定色，正文颜色由 `level` 决定（`warning` 黄、`error` 红、`info` 用扩展消息正文色），也可以用 `textColor` 覆盖成结论行自带的语义色（`dim`/`success` 等）。
+
+渲染细节：
+
+- 只有 TUI 会把提示画成底色块；rpc/print/json 仍走 `ctx.ui.notify`，输出纯文本 `[distill] 提示正文`，不会出现 ANSI 乱码。
+- 底色块由本包的扩展入口 `installNoticeRenderer(pi)` 注册一次，因此使用本包的功能包必须在自己的 `pi.extensions` 里加载 `../pi-extensions-i18n/index.ts`。
+- 老版本 Pi 没有这两个能力时不会注入，提示自动退回 `ctx.ui.notify`（仍然可见，只是没有底色）。
+
+需要更细粒度控制时用 `formatNotice({ source, message, mode, theme })` 只取文本。
+
 安装后重新加载 Pi：
 
 ```text

package/SKILL.md

@@ -20,3 +20,18 @@ description: "配置 Pi 扩展共享语言并排查 locale 优先级、持久化
 ## 验证
 
 执行语言命令后观察下一个使用共享 i18n 的扩展文案。若环境变量存在，它会覆盖持久化值；必须先报告这个覆盖关系，不能反复改 JSON。修改 catalog 时，每个 key 必须同时有 `zh-CN` 与 `en-US`，缺失翻译应作为加载错误修复，不能静默 fallback。
+
+## 统一提示出口
+
+功能包的用户可见提示必须走 `notifyWithSource`（而不是直接 `ctx.ui.notify`），否则 Pi 会把 `info` 级提示渲染成暗灰无前缀的一行文字，用户既分不清来源也不容易注意到：
+
+```ts
+notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "warning", message: i18n.t("failed") });
+```
+
+- 呈现：TUI 下画成会话区里的带底色消息块（落在消息下方，不进 LLM 上下文）；rpc/print/json 仍走 `ctx.ui.notify` 的纯文本。
+- 标签：每个包用短的唯一 tag 与固定颜色；颜色只在 tui 模式添加（自动处理，不要自己在调用点拼 ANSI）。
+- 依赖：底色块的渲染器由本包的扩展入口 `installNoticeRenderer(pi)` 注册一次，所以用它的包必须在 `pi.extensions` 里加载 `../pi-extensions-i18n/index.ts`，否则提示会退回纯文本（不报错、不丢提示）。
+- 自带语义色的结论行（如「已打断，未判定」）用 `textColor` 传色，不要再自己写页脚状态行。
+
+排查提示显示问题时，先确认包声明里加载了 i18n 入口，再看调用是否走了这个出口，最后看 tag 与 level 是否合理。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensions-i18n",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Shared i18n catalog loader & translator for pi extensions",
   "type": "module",
   "main": "./index.ts",
@@ -17,7 +17,7 @@
     "tsconfig.json"
   ],
   "scripts": {
-    "test": "tsx --test tests/pi-i18n.test.ts",
+    "test": "tsx --test tests/*.test.ts",
     "typecheck": "tsc --noEmit --pretty false",
     "build": "npm run typecheck",
     "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
@@ -54,10 +54,12 @@
     "coding-agent"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.80.0"
+    "@earendil-works/pi-coding-agent": ">=0.80.0",
+    "@earendil-works/pi-tui": ">=0.80.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "@types/node": "24.12.4",
     "tsx": "4.23.1",
     "typescript": "5.9.3"

package/src/index.ts

@@ -6,6 +6,12 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
+import {
+  installNoticeRenderer,
+  notifyWithSource,
+  type NoticeColor,
+  type NoticeSource,
+} from "./notice.ts";
 
 export const SUPPORTED_LOCALES = ["zh-CN", "en-US"] as const;
 export type Locale = (typeof SUPPORTED_LOCALES)[number];
@@ -190,20 +196,32 @@ const commandMessages = loadCatalog(
   new URL("../locales/command.json", import.meta.url),
 );
 
+/** 本扩展的提示标签；短且唯一，便于在会话里定位来源。 */
+const NOTICE_TAG = "language";
+/** 提示标签颜色；与其它扩展错开。 */
+const NOTICE_COLOR: NoticeColor = "accent";
+/** 本扩展的提示来源。 */
+const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };
+
 function registerLocaleCommand(pi: ExtensionAPI): void {
   const i18n = createTranslator(commandMessages);
   const command = {
     description: i18n.t("description"),
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       if (!ctx.hasUI) {
-        ctx.ui.notify(i18n.t("noUi"), "warning");
+        notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "warning", message: i18n.t("noUi") });
         return;
       }
 
       const requested = args.trim();
       const directPreference = requested ? parseLocalePreference(requested) : undefined;
       if (requested && !directPreference) {
-        ctx.ui.notify(i18n.t("invalid", { value: requested }), "error");
+        notifyWithSource({
+          ctx,
+          source: NOTICE_SOURCE,
+          level: "error",
+          message: i18n.t("invalid", { value: requested }),
+        });
         return;
       }
 
@@ -238,12 +256,19 @@ function registerLocaleCommand(pi: ExtensionAPI): void {
         const overrideNotice = envOverride
           ? `\n${i18n.t("envOverride", { env: LOCALE_ENV })}`
           : "";
-        ctx.ui.notify(
-          `${i18n.t("saved", { locale: preference })}${overrideNotice}\n${configPath}`,
-          "info",
-        );
+        notifyWithSource({
+          ctx,
+          source: NOTICE_SOURCE,
+          level: "info",
+          message: `${i18n.t("saved", { locale: preference })}${overrideNotice}\n${configPath}`,
+        });
       } catch (error) {
-        ctx.ui.notify(i18n.t("failed", { error: String(error) }), "error");
+        notifyWithSource({
+          ctx,
+          source: NOTICE_SOURCE,
+          level: "error",
+          message: i18n.t("failed", { error: String(error) }),
+        });
       }
     },
   };
@@ -253,5 +278,29 @@ function registerLocaleCommand(pi: ExtensionAPI): void {
 }
 
 export default function piI18n(pi: ExtensionAPI): void {
+  // 提示改走会话区的自定义条目（带底色消息块），渲染器在这里一次性注册。
+  installNoticeRenderer(pi);
   registerLocaleCommand(pi);
 }
+
+export {
+  formatNotice,
+  notifyWithSource,
+  installNoticeRenderer,
+  hasNoticeRenderer,
+  resetNoticeRenderer,
+  renderNoticeEntry,
+  noticeBodyColor,
+  NOTICE_BACKGROUND_COLOR,
+  NOTICE_COLOR_MODE,
+  NOTICE_ENTRY_TYPE,
+  type NoticeApi,
+  type NoticeColor,
+  type NoticeContext,
+  type NoticeEntryData,
+  type NoticeEntryTheme,
+  type NoticeLevel,
+  type NoticeRenderOptions,
+  type NoticeSendOptions,
+  type NoticeSource,
+} from "./notice.ts";

package/src/notice.ts

@@ -0,0 +1,296 @@
+/**
+ * 用户可见提示的统一呈现：把提示画成会话区里的「带底色消息块」，并标出来源扩展。
+ *
+ * 背景：Pi 的 ui.notify(info) 只是一行暗灰色文字（warning/error 才有黄色/红色前缀），
+ * 各扩展全用 info 时用户在会话里既分不清来源，也分不清哪条是提示。
+ *
+ * 做法：提示改走 Pi 的自定义条目（appendEntry + registerEntryRenderer），
+ * 渲染成和用户消息同款的实心底色块（主题色 customMessageBg），左侧标注来源扩展的短标签。
+ * 这些条目不进入 LLM 上下文，只影响会话区外观。
+ *
+ * 本模块只用结构化类型，不直接依赖 Pi 的实现，便于独立测试。
+ */
+import { Box, Text, type Component } from "@earendil-works/pi-tui";
+
+/** 允许使用的提示级别；同时是运行时校验的唯一真值来源。 */
+const NOTICE_LEVELS = ["info", "warning", "error"] as const;
+
+/** 提示级别，与 Pi 的 ui.notify 类型一致。 */
+export type NoticeLevel = (typeof NOTICE_LEVELS)[number];
+
+/** 允许使用的主题色名（Pi 主题色的子集）；同时是运行时校验的唯一真值来源。 */
+const NOTICE_COLORS = [
+  "accent",
+  "success",
+  "warning",
+  "error",
+  "muted",
+  "dim",
+  "text",
+  "customMessageText",
+  "toolTitle",
+] as const;
+
+/** 提示用到的主题色名。 */
+export type NoticeColor = (typeof NOTICE_COLORS)[number];
+
+/** 一个扩展的提示来源：短标签 + 固定颜色。 */
+export interface NoticeSource {
+  /** 展示在消息前的短标签，例如 "naming"。建议用包名去掉 pi- 前缀。 */
+  tag: string;
+  /** 该扩展的固定标签颜色，用来在会话里快速定位来源。 */
+  color: NoticeColor;
+}
+
+/** 渲染提示所需的最小 UI 上下文。 */
+export interface NoticeContext {
+  /** 运行模式；只有 tui 会渲染成带底色的消息块。 */
+  mode?: string;
+  ui: {
+    /** Pi 的提示出口；非 TUI 模式仍走这里。 */
+    notify(message: string, type?: NoticeLevel): void;
+    /** 主题；缺失时不加颜色。 */
+    theme?: { fg(color: NoticeColor, text: string): string };
+  };
+}
+
+/** 一次提示的渲染输入。 */
+export interface NoticeRenderOptions {
+  /** 来源标签与颜色。 */
+  source: NoticeSource;
+  /** 提示正文（已本地化）。 */
+  message: string;
+  /** 运行模式；非 tui 时输出纯文本。 */
+  mode: string | undefined;
+  /** 主题；缺失时输出纯文本。 */
+  theme: NoticeContext["ui"]["theme"];
+}
+
+/** 一次带来源的提示调用。 */
+export interface NoticeSendOptions {
+  /** 目标 UI 上下文；运行模式与主题从它上面读取。 */
+  ctx: NoticeContext;
+  /** 来源标签与颜色。 */
+  source: NoticeSource;
+  /** 提示级别；决定正文颜色（warning 黄、error 红、info 用正文色）。 */
+  level: NoticeLevel;
+  /** 提示正文（已本地化）。 */
+  message: string;
+  /** 正文颜色覆盖；例如判定结论行自带语义色（dim/success）时用它。 */
+  textColor?: NoticeColor;
+  /** 展开时才显示的细节行，平时只占一行，避免刷屏。 */
+  details?: string[];
+}
+
+/** 只有 TUI 模式能安全地看到 ANSI 颜色。 */
+export const NOTICE_COLOR_MODE = "tui";
+
+/** 提示条目的类型名；所有扩展共用一种，渲染器只需注册一次。 */
+export const NOTICE_ENTRY_TYPE = "pi-extensions-notice";
+
+/** 提示块的底色主题色：和 Pi 的扩展消息同款，视觉效果接近输入框。 */
+export const NOTICE_BACKGROUND_COLOR = "customMessageBg";
+
+/** 标签与消息之间的分隔符。 */
+const TAG_SEPARATOR = " ";
+
+/** 落进会话的提示条目数据；渲染器只依赖这些字段，重启后也能原样重建。 */
+export interface NoticeEntryData {
+  /** 来源短标签。 */
+  tag: string;
+  /** 标签颜色。 */
+  color: NoticeColor;
+  /** 提示级别；决定正文默认颜色。 */
+  level: NoticeLevel;
+  /** 提示正文。 */
+  message: string;
+  /** 正文颜色覆盖。 */
+  textColor?: NoticeColor;
+  /** 展开时才显示的细节行（Ctrl+O 展开工具输出时一起展开）。 */
+  details?: string[];
+}
+
+/** 渲染器拿到的主题：只需要前景色与底色。 */
+export interface NoticeEntryTheme {
+  /** 前景色。 */
+  fg(color: NoticeColor, text: string): string;
+  /** 底色。 */
+  bg(color: typeof NOTICE_BACKGROUND_COLOR, text: string): string;
+}
+
+/** 提示渲染所需的 Pi 能力：写入自定义条目 + 注册条目渲染器。 */
+export interface NoticeApi {
+  /** 追加一条不进 LLM 上下文的自定义条目。 */
+  appendEntry(customType: string, data?: unknown): void;
+  /** 注册自定义条目的 TUI 渲染器；Pi 会把展开状态一起传进来。 */
+  registerEntryRenderer(
+    customType: string,
+    renderer: (
+      entry: { data?: unknown },
+      options: { expanded?: boolean },
+      theme: NoticeEntryTheme,
+    ) => Component,
+  ): void;
+}
+
+/** 判断一个未知值是不是普通对象。 */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** 运行时校验主题色名。 */
+function isNoticeColor(value: unknown): value is NoticeColor {
+  return typeof value === "string" && NOTICE_COLORS.some((color) => color === value);
+}
+
+/** 运行时校验提示级别。 */
+function isNoticeLevel(value: unknown): value is NoticeLevel {
+  return typeof value === "string" && NOTICE_LEVELS.some((level) => level === value);
+}
+
+/**
+ * 当前会话的提示出口。
+ *
+ * 这是本模块唯一的可变状态，注入点是扩展入口的 installNoticeRenderer：
+ * 提示调用点分散在 15 个包的几十处（含 tps、turn-elapsed 等拿不到 pi 的模块），
+ * 逐个传参会把 Pi 的写入能力扩散到所有业务函数里，因此只在入口注入一次。
+ * 扩展重载会重新执行入口，这里始终保存最近一次的 Pi 实例。
+ */
+let noticeApi: NoticeApi | undefined;
+
+/**
+ * 注入提示出口并注册条目渲染器。
+ * 由 pi-extensions-i18n 的扩展入口调用；依赖它的扩展会自动带上这个入口。
+ * 老版本 Pi 没有这两个能力时直接不注入，提示会退回 ui.notify（仍然可见，只是没有底色）。
+ */
+/** 提示块的水平内边距：让文字不贴边。 */
+const NOTICE_PADDING_X = 1;
+/** 提示块的垂直内边距：0 表示只占一行，避免提示刷屏。 */
+const NOTICE_PADDING_Y = 0;
+
+/**
+ * 注册提示条目渲染器，并记下用于写入条目的 Pi 实例。
+ * 由 pi-extensions-i18n 的扩展入口调用；依赖它的扩展会自动带上这个入口。
+ * 老版本 Pi 没有这两个能力时直接不注入，提示会退回 ui.notify（仍然可见，只是没有底色）。
+ */
+export function installNoticeRenderer(api: NoticeApi): void {
+  if (typeof api.appendEntry !== "function" || typeof api.registerEntryRenderer !== "function") {
+    return;
+  }
+  api.registerEntryRenderer(NOTICE_ENTRY_TYPE, (entry, options, theme) =>
+    renderNoticeEntry(entry, theme, isExpanded(options)));
+  noticeApi = api;
+}
+
+/** 当前是否已具备把提示画成带底色消息块的能力。 */
+export function hasNoticeRenderer(): boolean {
+  return noticeApi !== undefined;
+}
+
+/** 测试与重载用：清掉已注入的提示出口。 */
+export function resetNoticeRenderer(): void {
+  noticeApi = undefined;
+}
+
+/** 正文默认颜色：warning 黄、error 红、info 用扩展消息正文色。 */
+export function noticeBodyColor(level: NoticeLevel, textColor?: NoticeColor): NoticeColor {
+  if (textColor !== undefined) return textColor;
+  if (level === "warning") return "warning";
+  if (level === "error") return "error";
+  return "customMessageText";
+}
+
+/**
+ * 把未知的条目数据收敛成提示条目数据。
+ * 逐字段运行时校验；缺失或类型不符时给出可读兜底，不信任外来数据。
+ */
+function readNoticeEntryData(input: unknown): NoticeEntryData {
+  const raw = isRecord(input) && isRecord(input.data) ? input.data : {};
+  const tag = typeof raw.tag === "string" && raw.tag !== "" ? raw.tag : "notice";
+  const message = typeof raw.message === "string" ? raw.message : "";
+  return {
+    tag,
+    color: isNoticeColor(raw.color) ? raw.color : "muted",
+    level: isNoticeLevel(raw.level) ? raw.level : "info",
+    message,
+    textColor: isNoticeColor(raw.textColor) ? raw.textColor : undefined,
+    details: readDetails(raw.details),
+  };
+}
+
+/** 只保留非空字符串细节行，避免渲染出空气泡。 */
+function readDetails(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const lines = value.filter((line): line is string => typeof line === "string" && line.trim() !== "");
+  return lines.length > 0 ? lines : undefined;
+}
+
+/** 判断渲染器是否处于展开状态（Ctrl+O）；缺省视为收起。 */
+function isExpanded(options: unknown): boolean {
+  return isRecord(options) && options.expanded === true;
+}
+
+/**
+ * 把一个提示条目渲染成带底色的消息块。
+ *
+ * 默认只占一行（上下不加空白），避免提示刷屏；细节行只在展开（Ctrl+O）时追加。
+ * 这里直接构造 pi-tui 的 Box/Text：带底色消息块的排版（整块铺底色、按宽度换行）
+ * 由 pi-tui 提供，Pi 自带的扩展消息渲染也是同样写法，属于有意为之的绑定。
+ */
+export function renderNoticeEntry(
+  input: unknown,
+  theme: NoticeEntryTheme,
+  expanded = false,
+): Component {
+  const data = readNoticeEntryData(input);
+  const label = theme.fg(data.color, `[${data.tag}]`);
+  const body = theme.fg(noticeBodyColor(data.level, data.textColor), data.message);
+  const box = new Box(NOTICE_PADDING_X, NOTICE_PADDING_Y, (text) => theme.bg(NOTICE_BACKGROUND_COLOR, text));
+  box.addChild(new Text(`${label}${TAG_SEPARATOR}${body}`, 0, 0));
+  if (expanded && data.details !== undefined) {
+    for (const line of data.details) {
+      box.addChild(new Text(theme.fg("dim", line), 0, 0));
+    }
+  }
+  return box;
+}
+
+/**
+ * 给提示文本加上来源标签与颜色。
+ * 非 TUI 模式或没有主题时返回纯文本，避免把 ANSI 序列转发给前端。
+ */
+export function formatNotice(options: NoticeRenderOptions): string {
+  const { source, message, mode, theme } = options;
+  const tag = `[${source.tag}]`;
+  if (mode !== NOTICE_COLOR_MODE || theme === undefined) return `${tag}${TAG_SEPARATOR}${message}`;
+  return `${theme.fg(source.color, tag)}${TAG_SEPARATOR}${message}`;
+}
+
+/**
+ * 统一的提示出口。
+ *
+ * TUI：写一条自定义条目，由 registerEntryRenderer 画成带底色的消息块。
+ * 其它模式（RPC/print/json）：仍走 ui.notify，行为与改造前一致。
+ * 条目写入失败时退回 ui.notify，保证提示不会因为渲染方式而丢失。
+ */
+export function notifyWithSource(options: NoticeSendOptions): void {
+  const { ctx, source, level, message, textColor, details } = options;
+  if (ctx.mode === NOTICE_COLOR_MODE && noticeApi !== undefined) {
+    const data: NoticeEntryData = {
+      tag: source.tag,
+      color: source.color,
+      level,
+      message,
+      textColor,
+      details,
+    };
+    try {
+      noticeApi.appendEntry(NOTICE_ENTRY_TYPE, data);
+      return;
+    } catch {
+      // 落到下面的 ui.notify：提示照常可见，只是没有底色。
+    }
+  }
+  const text = formatNotice({ source, message, mode: ctx.mode, theme: ctx.ui.theme });
+  ctx.ui.notify(text, level);
+}