pi-extensions-i18n 0.5.0 → 0.6.0

package/README.md

@@ -14,7 +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 prefixes every user-visible notice with a short source tag in the package's own label colour. Pi renders `info` notices as dim, unprefixed text, so without a tag you cannot tell which extension spoke.
+- 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
 
@@ -66,7 +67,7 @@ const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };
 notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "warning", message: i18n.t("failed") });
 ```
 
-This renders as `[distill] message`: the tag carries the package colour, the message stays untouched, and `level` still decides Pi's yellow `Warning:` / red `Error:` prefix. Colours are only added in tui mode; rpc/print/json get plain text so no ANSI leaks into other frontends. Use `formatNotice({ source, message, mode, theme })` when you only need the rendered string.
+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:
 

package/README.zh-CN.md

@@ -14,7 +14,8 @@ Pi 扩展公共国际化运行时。它提供基于 catalog 的小型 API，支
 - 提供 `/config:language` 交互式命令，也支持 `/config:language en-US` 直接设置。
 - 加载并校验 catalog，要求每个消息 key 同时提供两种语言。
 - 为 UI、命令描述和 Agent prompt 提供用户文案插值。
-- 提供统一的用户提示出口 `notifyWithSource`：给提示加「来源标签 + 固定颜色」，解决 Pi 对 `info` 级提示只显示暗灰无前缀文本、用户分不清消息来自哪个扩展的问题。
+- 提供统一的用户提示出口 `notifyWithSource`：把提示画成会话区里的**带底色消息块**（用户消息同款底色，见下条），并配上「来源标签 + 固定颜色」，解决 Pi 对 `info` 级提示只显示暗灰无前缀文本、用户既分不清来源也不容易注意到的问题。
+- 提示落在消息下方、不进 LLM 上下文：通过 Pi 的自定义条目（`appendEntry` + `registerEntryRenderer`）实现，条目只在本地渲染，不消耗上下文窗口。
 
 ## 安装
 
@@ -39,7 +40,13 @@ const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };
 notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "warning", message: i18n.t("failed") });
 ```
 
-输出形如 `[distill] 提示正文`：标签按扩展固定色，正文保持原样，`level` 仍然决定 Pi 侧的黄色 `Warning:` / 红色 `Error:` 前缀。颜色只在 tui 模式添加，rpc/print/json 模式输出纯文本，不会出现 ANSI 乱码。
+输出是一个和用户消息同款的**实心底色块**，首行是 `[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 })` 只取文本。
 

package/SKILL.md

@@ -23,10 +23,15 @@ description: "配置 Pi 扩展共享语言并排查 locale 优先级、持久化
 
 ## 统一提示出口
 
-功能包的用户可见提示必须走 `notifyWithSource`（而不是直接 `ctx.ui.notify`），否则 Pi 会把 `info` 级提示渲染成暗灰无前缀文本，用户分不清消息来自哪个扩展：
+功能包的用户可见提示必须走 `notifyWithSource`（而不是直接 `ctx.ui.notify`），否则 Pi 会把 `info` 级提示渲染成暗灰无前缀的一行文字，用户既分不清来源也不容易注意到：
 
 ```ts
 notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "warning", message: i18n.t("failed") });
 ```
 
-每个包用短的唯一 tag 与固定颜色；颜色只在 tui 模式添加（自动处理，不要自己在调用点拼 ANSI）。排查提示显示问题时，先确认调用是否走了这个出口，再看 tag 与 level 是否合理。
+- 呈现：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.5.0",
+  "version": "0.6.0",
   "description": "Shared i18n catalog loader & translator for pi extensions",
   "type": "module",
   "main": "./index.ts",
@@ -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,7 +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 { notifyWithSource, type NoticeColor, type NoticeSource } from "./notice.ts";
+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];
@@ -273,15 +278,27 @@ 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,

package/src/notice.ts

@@ -1,26 +1,38 @@
 /**
- * 用户可见提示的统一呈现：给每条提示加「来源标签」，并按级别上色。
+ * 用户可见提示的统一呈现：把提示画成会话区里的「带底色消息块」，并标出来源扩展。
  *
- * 背景：Pi 的 ui.notify 只有 info（暗灰、无前缀）/ warning（黄色 Warning:）/ error（红色 Error:）
- * 三种呈现，多数扩展全部用 info，用户在会话里无法分辨消息来自哪个扩展。
- * 这里给每个扩展一个固定短标签与固定颜色，让提示一眼可辨。
+ * 背景：Pi 的 ui.notify(info) 只是一行暗灰色文字（warning/error 才有黄色/红色前缀），
+ * 各扩展全用 info 时用户在会话里既分不清来源，也分不清哪条是提示。
  *
- * 本模块不依赖 Pi 的具体实现，只用结构化类型，便于独立测试。
+ * 做法：提示改走 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 = "info" | "warning" | "error";
-
-/** 主题色名；取值是 Pi 主题色的子集，避免依赖具体主题实现。 */
-export type NoticeColor =
-  | "accent"
-  | "success"
-  | "warning"
-  | "error"
-  | "muted"
-  | "dim"
-  | "text"
-  | "toolTitle";
+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 {
@@ -32,10 +44,10 @@ export interface NoticeSource {
 
 /** 渲染提示所需的最小 UI 上下文。 */
 export interface NoticeContext {
-  /** 运行模式；只有 tui 能安全地显示 ANSI 颜色。 */
+  /** 运行模式；只有 tui 会渲染成带底色的消息块。 */
   mode?: string;
   ui: {
-    /** Pi 的提示出口。 */
+    /** Pi 的提示出口；非 TUI 模式仍走这里。 */
     notify(message: string, type?: NoticeLevel): void;
     /** 主题；缺失时不加颜色。 */
     theme?: { fg(color: NoticeColor, text: string): string };
@@ -60,18 +72,189 @@ export interface NoticeSendOptions {
   ctx: NoticeContext;
   /** 来源标签与颜色。 */
   source: NoticeSource;
-  /** 提示级别；决定 Pi 侧的前缀与主色。 */
+  /** 提示级别；决定正文颜色（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 序列转发给前端。
@@ -84,11 +267,30 @@ export function formatNotice(options: NoticeRenderOptions): string {
 }
 
 /**
- * 统一的提示出口：加来源标签后交给 Pi 的 notify。
- * 级别仍由调用方指定，保证 warning/error 依然带 Pi 自带的黄色/红色前缀。
+ * 统一的提示出口。
+ *
+ * TUI：写一条自定义条目，由 registerEntryRenderer 画成带底色的消息块。
+ * 其它模式（RPC/print/json）：仍走 ui.notify，行为与改造前一致。
+ * 条目写入失败时退回 ui.notify，保证提示不会因为渲染方式而丢失。
  */
 export function notifyWithSource(options: NoticeSendOptions): void {
-  const { ctx, source, level, message } = options;
+  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);
 }