@zhushanwen/pi-llm-shared 0.8.0 → 0.9.0

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@zhushanwen/pi-llm-shared",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Shared LLM invocation library for Pi extensions — model resolution (ref exact only), LLM calling (completeSimple), and config read/write with mtime+size caching. Shared library, not a Pi extension.",
   "type": "module",
   "main": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./ui-locale": {
+      "types": "./src/ui-locale.ts",
+      "import": "./src/ui-locale.ts"
+    }
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -17,9 +27,9 @@
     "src/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.6.0",
-    "@zhushanwen/pi-ext-guards": "0.4.0",
-    "@zhushanwen/pi-file-lock": "0.4.0"
+    "@zhushanwen/pi-extension-logger": "0.6.1",
+    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/pi-file-lock": "0.4.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",

package/src/__tests__/ui-locale.test.ts

@@ -0,0 +1,88 @@
+import { mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import * as fs from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { DEFAULT_UI_LOCALE, readUiLocale } from "../ui-locale.ts";
+
+// node:fs 的 ESM namespace 不可配置，vi.spyOn 对具名导出失效（vitest 限制，
+// 同 config.test.ts）：mock 包装 readFileSync/statSync（默认透传 actual），
+// 供缓存命中断言 override / 计数；其余 fs 操作原样透传。
+vi.mock("node:fs", async (importOriginal) => {
+	const actual = await importOriginal() as typeof import("node:fs");
+	return {
+		...actual,
+		readFileSync: vi.fn(actual.readFileSync),
+		statSync: vi.fn(actual.statSync),
+	};
+});
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "llm-shared-ui-locale-"));
+	vi.stubEnv("TAIJI_AGENT_DATA_DIR", dir);
+});
+
+afterEach(() => {
+	vi.mocked(fs.readFileSync).mockClear();
+	vi.mocked(fs.statSync).mockClear();
+	rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+	vi.unstubAllEnvs();
+});
+
+/** 在 <dir>/ui-preferences.json 写入 locale 并钉住 mtime（防快速连写 mtime 粒度截断）。 */
+function writePreferences(locale: unknown, mtimeSec: number): void {
+	const filePath = join(dir, "ui-preferences.json");
+	writeFileSync(filePath, JSON.stringify({ v: 1, locale, updatedAt: 0 }));
+	utimesSync(filePath, mtimeSec, mtimeSec);
+}
+
+describe("readUiLocale（<dataDir>/ui-preferences.json 读单点）", () => {
+	it("zh-CN / en-US 命中；文件缺失 / env 缺失 → 回落 en-US", () => {
+		expect(readUiLocale()).toBe(DEFAULT_UI_LOCALE); // 文件缺失
+
+		writePreferences("zh-CN", 1_000);
+		expect(readUiLocale()).toBe("zh-CN");
+
+		writePreferences("en-US", 2_000);
+		expect(readUiLocale()).toBe("en-US");
+
+		vi.stubEnv("TAIJI_AGENT_DATA_DIR", undefined);
+		expect(readUiLocale()).toBe(DEFAULT_UI_LOCALE); // env 缺失
+	});
+
+	it("locale 值域外 / 顶层非对象 / JSON 损坏 → 回落 en-US", () => {
+		// 值域外：换新目录绕开 (filePath, mtime, size) 模块缓存（同 plan i18n.test.ts 手法）
+		const dir2 = mkdtempSync(join(tmpdir(), "llm-shared-ui-locale-oor-"));
+		vi.stubEnv("TAIJI_AGENT_DATA_DIR", dir2);
+		writePreferences("fr-FR", 1_000);
+		expect(readUiLocale()).toBe(DEFAULT_UI_LOCALE);
+		rmSync(dir2, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+
+		vi.stubEnv("TAIJI_AGENT_DATA_DIR", dir);
+		writeFileSync(join(dir, "ui-preferences.json"), "not-json{{");
+		utimesSync(join(dir, "ui-preferences.json"), 3_000, 3_000);
+		expect(readUiLocale()).toBe(DEFAULT_UI_LOCALE); // JSON 损坏（缓存已驱逐，重读失败同路径）
+
+		writeFileSync(join(dir, "ui-preferences.json"), JSON.stringify([1, 2]));
+		utimesSync(join(dir, "ui-preferences.json"), 4_000, 4_000);
+		expect(readUiLocale()).toBe(DEFAULT_UI_LOCALE); // 顶层非对象
+	});
+
+	it("mtime+size 缓存：文件未变不重读；mtime 变化后重读生效", () => {
+		writePreferences("zh-CN", 1_000);
+		expect(readUiLocale()).toBe("zh-CN");
+		const readsAfterFirst = vi.mocked(fs.readFileSync).mock.calls.length;
+
+		// 未变文件：再读走缓存，readFileSync 调用数不增
+		expect(readUiLocale()).toBe("zh-CN");
+		expect(vi.mocked(fs.readFileSync).mock.calls.length).toBe(readsAfterFirst);
+
+		// runtime 写盘语义：同路径内容翻转（zh-CN→en-US 等长，size 双键失效）+ mtime 前进
+		writePreferences("en-US", 2_000);
+		expect(readUiLocale()).toBe("en-US");
+		expect(vi.mocked(fs.readFileSync).mock.calls.length).toBe(readsAfterFirst + 1);
+	});
+});

package/src/config.ts

@@ -143,7 +143,7 @@ function uniqueTmpPath(configPath: string): string {
  * @returns 成功 {success:true}；失败 {success:false, error}
  *
  * 🔒 跨进程锁（D1e/W4，integrity-hardening.md §3.1，登记表 §6 rename-session 行）：
- * ext-config 家族被 xyz runtime（如 setRenameModel 写 model 字段，W1b 已持锁）与
+ * ext-config 家族被 taiji runtime（如 setRenameModel 写 model 字段，W1b 已持锁）与
  * pi 子进程内扩展（本函数）双写。互斥只依赖同一 lockfile（<config>.lock），本侧
  * withFileLockSync 协议与 runtime 侧 settings.json 写锁逐字对齐（realpath:false +
  * stale 30s + busy-wait 1s 预算 fail-fast）。锁获取失败不降级无锁写——对端

package/src/index.ts

@@ -2,6 +2,7 @@
 // resolve: 模型解析（仅 ref 精确指定）+ selector 归一化 + thinking 级别校验
 // call: LLM 调用（completeSimple + 凭证 + 文本提取）
 // config: 泛型配置读写（mtime+size 双 key 缓存 + 原子写）
+// ui-locale: UI 语言读取单点（<dataDir>/ui-preferences.json，mtime+size 读缓存 + 降级）
 export {
 	resolveModel,
 	parseModelRef,
@@ -12,4 +13,5 @@ export {
 } from "./resolve.ts";
 export { callLLM, joinTextBlocks, extractText, type CallLLMOptions, type CallLLMResult } from "./call.ts";
 export { getConfigPath, loadConfig, saveConfig, clearConfigCache } from "./config.ts";
+export { readUiLocale, DEFAULT_UI_LOCALE, type UiLocale } from "./ui-locale.ts";
 export { migrateLegacyConfig } from "./migrate.ts";

package/src/ui-locale.ts

@@ -0,0 +1,67 @@
+/**
+ * UI 语言（u-locale-channel）读取单点：`<dataDir>/ui-preferences.json` 的 extension 侧
+ * 唯一消费实现（需求方 = plan / scheduler 等 extension 的 i18n 层，经本模块 import）。
+ *
+ * 语言归属原则：跨边界只走数据——renderer 是语言权威，进程只读派生态。文件唯一写方 =
+ * runtime `config.setUiLocale` handler → `writeUiPreferences`（tmp + rename 原子写）。
+ *
+ * @data-owner #39 `ui-preferences.json`（本模块是读缓存，非第二写方；登记行见
+ * `docs/architecture/data-source-registry.md`）。runtime 以
+ * `TAIJI_AGENT_DATA_DIR = getConfigDir()` 注入 pi 子进程；文件形如
+ * `{ v: 1, locale: 'zh-CN' | 'en-US', updatedAt }`。
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** UI 语言两值（与 ui-preferences.json 读写两端守卫测试对齐的字面量词表）。 */
+export type UiLocale = "zh-CN" | "en-US";
+
+export const DEFAULT_UI_LOCALE: UiLocale = "en-US";
+
+const UI_PREFERENCES_FILENAME = "ui-preferences.json";
+
+/**
+ * 模块级 (filePath, mtimeMs, size) 三键读缓存（先例 = system-prompt 的 mtime+size
+ * 双键读缓存；mtime+size 防 APFS 等文件系统 mtime 精度截断）：每次读仍 stat 判变
+ * （runtime 写盘后下一轮即生效），文件未变时跳过 readFileSync/JSON.parse。
+ */
+let localeCache: { filePath: string; mtimeMs: number; size: number; locale: UiLocale } | null = null;
+
+/** 读界面语言（数据目录动态推导，禁硬编码路径）；任何失败回落 en-US 且不出声。 */
+export function readUiLocale(): UiLocale {
+	const dataDir = process.env.TAIJI_AGENT_DATA_DIR;
+	if (!dataDir) return DEFAULT_UI_LOCALE;
+
+	const filePath = join(dataDir, UI_PREFERENCES_FILENAME);
+	try {
+		const stat = statSync(filePath);
+		const cached = localeCache;
+		if (
+			cached !== null &&
+			cached.filePath === filePath &&
+			cached.mtimeMs === stat.mtimeMs &&
+			cached.size === stat.size
+		) {
+			return cached.locale;
+		}
+		const parsed: unknown = JSON.parse(readFileSync(filePath, "utf-8"));
+		const locale = parseUiLocale(parsed);
+		localeCache = { filePath, mtimeMs: stat.mtimeMs, size: stat.size, locale };
+		return locale;
+	} catch {
+		// 文件缺失 / 不可读 / JSON 损坏均归此路径（设计口径：损坏 = 驱逐缓存 + 回落默认 + 无出声面）
+		localeCache = null;
+		return DEFAULT_UI_LOCALE;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function parseUiLocale(raw: unknown): UiLocale {
+	if (!isRecord(raw)) return DEFAULT_UI_LOCALE;
+	const locale = raw.locale;
+	return locale === "zh-CN" || locale === "en-US" ? locale : DEFAULT_UI_LOCALE;
+}