pi-extensions-i18n 0.4.0 → 0.5.0

package/README.md

@@ -14,6 +14,7 @@ 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.
 
 ## Install
 
@@ -50,8 +51,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 `[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.
+
+Other exports:
 
 ```ts
 import {

package/README.zh-CN.md

@@ -14,6 +14,7 @@ Pi 扩展公共国际化运行时。它提供基于 catalog 的小型 API，支
 - 提供 `/config:language` 交互式命令，也支持 `/config:language en-US` 直接设置。
 - 加载并校验 catalog，要求每个消息 key 同时提供两种语言。
 - 为 UI、命令描述和 Agent prompt 提供用户文案插值。
+- 提供统一的用户提示出口 `notifyWithSource`：给提示加「来源标签 + 固定颜色」，解决 Pi 对 `info` 级提示只显示暗灰无前缀文本、用户分不清消息来自哪个扩展的问题。
 
 ## 安装
 
@@ -23,6 +24,25 @@ 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` 仍然决定 Pi 侧的黄色 `Warning:` / 红色 `Error:` 前缀。颜色只在 tui 模式添加，rpc/print/json 模式输出纯文本，不会出现 ANSI 乱码。
+
+需要更细粒度控制时用 `formatNotice({ source, message, mode, theme })` 只取文本。
+
 安装后重新加载 Pi：
 
 ```text

package/SKILL.md

@@ -20,3 +20,13 @@ 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") });
+```
+
+每个包用短的唯一 tag 与固定颜色；颜色只在 tui 模式添加（自动处理，不要自己在调用点拼 ANSI）。排查提示显示问题时，先确认调用是否走了这个出口，再看 tag 与 level 是否合理。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensions-i18n",
-  "version": "0.4.0",
+  "version": "0.5.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,10 @@
     "coding-agent"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0"
+    "@earendil-works/pi-coding-agent": ">=0.80.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@earendil-works/pi-coding-agent": "0.85.1",
     "@types/node": "24.12.4",
     "tsx": "4.23.1",
     "typescript": "5.9.3"

package/src/index.ts

@@ -6,6 +6,7 @@ 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";
 
 export const SUPPORTED_LOCALES = ["zh-CN", "en-US"] as const;
 export type Locale = (typeof SUPPORTED_LOCALES)[number];
@@ -190,20 +191,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 +251,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) }),
+        });
       }
     },
   };
@@ -255,3 +275,15 @@ function registerLocaleCommand(pi: ExtensionAPI): void {
 export default function piI18n(pi: ExtensionAPI): void {
   registerLocaleCommand(pi);
 }
+
+export {
+  formatNotice,
+  notifyWithSource,
+  NOTICE_COLOR_MODE,
+  type NoticeColor,
+  type NoticeContext,
+  type NoticeLevel,
+  type NoticeRenderOptions,
+  type NoticeSendOptions,
+  type NoticeSource,
+} from "./notice.ts";

package/src/notice.ts

@@ -0,0 +1,94 @@
+/**
+ * 用户可见提示的统一呈现：给每条提示加「来源标签」，并按级别上色。
+ *
+ * 背景：Pi 的 ui.notify 只有 info（暗灰、无前缀）/ warning（黄色 Warning:）/ error（红色 Error:）
+ * 三种呈现，多数扩展全部用 info，用户在会话里无法分辨消息来自哪个扩展。
+ * 这里给每个扩展一个固定短标签与固定颜色，让提示一眼可辨。
+ *
+ * 本模块不依赖 Pi 的具体实现，只用结构化类型，便于独立测试。
+ */
+
+/** 提示级别，与 Pi 的 ui.notify 类型一致。 */
+export type NoticeLevel = "info" | "warning" | "error";
+
+/** 主题色名；取值是 Pi 主题色的子集，避免依赖具体主题实现。 */
+export type NoticeColor =
+  | "accent"
+  | "success"
+  | "warning"
+  | "error"
+  | "muted"
+  | "dim"
+  | "text"
+  | "toolTitle";
+
+/** 一个扩展的提示来源：短标签 + 固定颜色。 */
+export interface NoticeSource {
+  /** 展示在消息前的短标签，例如 "naming"。建议用包名去掉 pi- 前缀。 */
+  tag: string;
+  /** 该扩展的固定标签颜色，用来在会话里快速定位来源。 */
+  color: NoticeColor;
+}
+
+/** 渲染提示所需的最小 UI 上下文。 */
+export interface NoticeContext {
+  /** 运行模式；只有 tui 能安全地显示 ANSI 颜色。 */
+  mode?: string;
+  ui: {
+    /** Pi 的提示出口。 */
+    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;
+  /** 提示级别；决定 Pi 侧的前缀与主色。 */
+  level: NoticeLevel;
+  /** 提示正文（已本地化）。 */
+  message: string;
+}
+
+/** 只有 TUI 模式能安全地看到 ANSI 颜色。 */
+export const NOTICE_COLOR_MODE = "tui";
+
+/** 标签与消息之间的分隔符。 */
+const TAG_SEPARATOR = " ";
+
+/**
+ * 给提示文本加上来源标签与颜色。
+ * 非 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}`;
+}
+
+/**
+ * 统一的提示出口：加来源标签后交给 Pi 的 notify。
+ * 级别仍由调用方指定，保证 warning/error 依然带 Pi 自带的黄色/红色前缀。
+ */
+export function notifyWithSource(options: NoticeSendOptions): void {
+  const { ctx, source, level, message } = options;
+  const text = formatNotice({ source, message, mode: ctx.mode, theme: ctx.ui.theme });
+  ctx.ui.notify(text, level);
+}