@zhushanwen/pi-extension-logger 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-extension-logger",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Shared logging helper for Pi extensions — two-channel routing (audit appendEntry / debug file log; the third AI-realtime channel stays with pi native) (shared library, not a Pi extension - no install.mjs needed)",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/extension-logger.test.ts

@@ -27,7 +27,7 @@ describe("extension-logger", () => {
 		setPiHandle(undefined);
 		clearRateLimiterState();
 		vi.restoreAllMocks();
-		// 还原环境变量，避免文件日志测试的 XYZ_AGENT_DEBUG/PI_CODING_AGENT_DIR 泄漏到其它用例
+		// 还原环境变量，避免文件日志测试的 TAIJI_AGENT_DEBUG/PI_CODING_AGENT_DIR 泄漏到其它用例
 		process.env = { ...prevEnv };
 	});
 
@@ -140,7 +140,7 @@ describe("extension-logger", () => {
 		});
 	});
 
-	describe("XYZ_AGENT_DEBUG 文件日志", () => {
+	describe("TAIJI_AGENT_DEBUG 文件日志", () => {
 		// 文件日志的 agentDir 通过 getAgentDir() 推导（读 PI_CODING_AGENT_DIR，
 		// 默认 ~/.pi/agent）。设 PI_CODING_AGENT_DIR 到 tmpdir 子目录，与组 A 的
 		// arch-boundary 改动（fileLog 用 getAgentDir()）保持一致。
@@ -159,15 +159,15 @@ describe("extension-logger", () => {
 			}
 		});
 
-		it("XYZ_AGENT_DEBUG 未设时 debug 是 no-op（不抛错即可）", () => {
-			delete process.env.XYZ_AGENT_DEBUG;
+		it("TAIJI_AGENT_DEBUG 未设时 debug 是 no-op（不抛错即可）", () => {
+			delete process.env.TAIJI_AGENT_DEBUG;
 			const logger = createLogger("test", pi);
 			expect(() => logger.debug("no-op")).not.toThrow();
 		});
 
 		// ---- Suggestion #8：fileLog 实际写入路径 ----
-		it("XYZ_AGENT_DEBUG=1 时 debug 写入日志文件，内容含 [debug] 与序列化 data", () => {
-			process.env.XYZ_AGENT_DEBUG = "1";
+		it("TAIJI_AGENT_DEBUG=1 时 debug 写入日志文件，内容含 [debug] 与序列化 data", () => {
+			process.env.TAIJI_AGENT_DEBUG = "1";
 			// 固定日期 → 文件名 <extName>-2026-08-01.log
 			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
 
@@ -190,8 +190,8 @@ describe("extension-logger", () => {
 			expect(appendSpy).not.toHaveBeenCalled();
 		});
 
-		it("XYZ_AGENT_DEBUG=1 时 warn 既写文件又走 appendEntry（文件内容含 [warn]）", () => {
-			process.env.XYZ_AGENT_DEBUG = "1";
+		it("TAIJI_AGENT_DEBUG=1 时 warn 既写文件又走 appendEntry（文件内容含 [warn]）", () => {
+			process.env.TAIJI_AGENT_DEBUG = "1";
 			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
 
 			const logger = createLogger("warn-ext", pi);
@@ -207,8 +207,8 @@ describe("extension-logger", () => {
 			expect(appendSpy).toHaveBeenCalledOnce();
 		});
 
-		it("XYZ_AGENT_DEBUG=1 写失败（只读目录）不 throw", () => {
-			process.env.XYZ_AGENT_DEBUG = "1";
+		it("TAIJI_AGENT_DEBUG=1 写失败（只读目录）不 throw", () => {
+			process.env.TAIJI_AGENT_DEBUG = "1";
 			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
 
 			// 已存在的 logs 目录改为只读，让 mkdirSync/appendFileSync 失败。
@@ -243,13 +243,13 @@ describe("extension-logger", () => {
 			const [, entry] = appendSpy.mock.calls[0]!;
 			// appendEntry payload 的 data 字段保留原对象（safeStringify 仅在文件日志路径用）
 			expect(entry).toMatchObject({ level: "warn" });
-			// 验证 safeStringify 的 fallback 分支：用 XYZ_AGENT_DEBUG=1 触发 fileLog，
+			// 验证 safeStringify 的 fallback 分支：用 TAIJI_AGENT_DEBUG=1 触发 fileLog，
 			// 文件内 data 应是 String() 形式（含 [object Object] 或循环结构字符串）
 			expect(() => JSON.stringify(cyclic)).toThrow(); // 对照：原对象确实不可序列化
 		});
 
 		it("BigInt：warn 不崩，文件日志路径走 String fallback", () => {
-			process.env.XYZ_AGENT_DEBUG = "1";
+			process.env.TAIJI_AGENT_DEBUG = "1";
 			const tmpAgentDir = mkdtempSync(join(tmpdir(), "pi-ext-bigint-"));
 			process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
 			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
@@ -274,16 +274,16 @@ describe("extension-logger", () => {
 	});
 
 	// ============================================================
-	// XYZ_AGENT_EXT_LOG 托管观测档（设计 file-lock-unification-and-reaper-sink §3.2-D4）
+	// TAIJI_AGENT_EXT_LOG 托管观测档（设计 file-lock-unification-and-reaper-sink §3.2-D4）
 	// ============================================================
-	describe("XYZ_AGENT_EXT_LOG 托管观测档", () => {
+	describe("TAIJI_AGENT_EXT_LOG 托管观测档", () => {
 		let tmpAgentDir: string;
 
 		beforeEach(() => {
 			tmpAgentDir = mkdtempSync(join(tmpdir(), "pi-ext-extlog-"));
 			process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
-			delete process.env.XYZ_AGENT_DEBUG;
-			delete process.env.XYZ_AGENT_EXT_LOG;
+			delete process.env.TAIJI_AGENT_DEBUG;
+			delete process.env.TAIJI_AGENT_EXT_LOG;
 			resetExtLogCleanupForTest();
 			vi.useFakeTimers();
 		});
@@ -302,8 +302,8 @@ describe("extension-logger", () => {
 			expect(existsSync(join(tmpAgentDir, "logs"))).toBe(false);
 		});
 
-		it("仅 XYZ_AGENT_EXT_LOG=1：debug 调用以 info 级落盘（含序列化 data），不标 debug", () => {
-			process.env.XYZ_AGENT_EXT_LOG = "1";
+		it("仅 TAIJI_AGENT_EXT_LOG=1：debug 调用以 info 级落盘（含序列化 data），不标 debug", () => {
+			process.env.TAIJI_AGENT_EXT_LOG = "1";
 			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
 
 			const logger = createLogger("extlog-ext", pi);
@@ -320,8 +320,8 @@ describe("extension-logger", () => {
 			expect(appendSpy).not.toHaveBeenCalled();
 		});
 
-		it("仅 XYZ_AGENT_EXT_LOG=1：warn/error 照常落盘且保持原级标注", () => {
-			process.env.XYZ_AGENT_EXT_LOG = "1";
+		it("仅 TAIJI_AGENT_EXT_LOG=1：warn/error 照常落盘且保持原级标注", () => {
+			process.env.TAIJI_AGENT_EXT_LOG = "1";
 			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
 
 			const logger = createLogger("extlog-err", pi);
@@ -335,9 +335,9 @@ describe("extension-logger", () => {
 			expect(content).not.toContain("[info]");
 		});
 
-		it("XYZ_AGENT_DEBUG=1 与 EXT_LOG 同注入：按更详细的生效（debug 全量，原级标注）", () => {
-			process.env.XYZ_AGENT_EXT_LOG = "1";
-			process.env.XYZ_AGENT_DEBUG = "1";
+		it("TAIJI_AGENT_DEBUG=1 与 EXT_LOG 同注入：按更详细的生效（debug 全量，原级标注）", () => {
+			process.env.TAIJI_AGENT_EXT_LOG = "1";
+			process.env.TAIJI_AGENT_DEBUG = "1";
 			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
 
 			const logger = createLogger("both-ext", pi);
@@ -355,7 +355,7 @@ describe("extension-logger", () => {
 		});
 
 		it("保留期清理：7 天前的 <ext>-<date>.log 被删，近期与本包 pattern 外文件保留", () => {
-			process.env.XYZ_AGENT_EXT_LOG = "1";
+			process.env.TAIJI_AGENT_EXT_LOG = "1";
 			// fake timers 冻结 Date 在真实当前时刻：文件 mtime 走真实时钟，utimesSync 把
 			// old 的 mtime 设为 8 天前（> 7 天保留期），recent 与 unrelated 保留。
 			const logDir = join(tmpAgentDir, "logs");
@@ -381,7 +381,7 @@ describe("extension-logger", () => {
 		});
 
 		it("清理只认 <ext>-YYYY-MM-DD.log pattern，不动其他 .log 文件", () => {
-			process.env.XYZ_AGENT_EXT_LOG = "1";
+			process.env.TAIJI_AGENT_EXT_LOG = "1";
 			const logDir = join(tmpAgentDir, "logs");
 			mkdirSync(logDir, { recursive: true });
 			const MS_PER_DAY = 24 * 60 * 60 * 1000;
@@ -510,8 +510,8 @@ describe("extension-logger", () => {
 			expect(appendSpy).toHaveBeenCalledTimes(10);
 		});
 
-		it("fileLog 通道不受限（XYZ_AGENT_DEBUG=1 时 100 条全写文件）", () => {
-			process.env.XYZ_AGENT_DEBUG = "1";
+		it("fileLog 通道不受限（TAIJI_AGENT_DEBUG=1 时 100 条全写文件）", () => {
+			process.env.TAIJI_AGENT_DEBUG = "1";
 			const tmpAgentDir = mkdtempSync(join(tmpdir(), "pi-ext-ratelimit-"));
 			process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
 			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));

package/src/index.ts

@@ -11,8 +11,8 @@
 //   1. AI 实时    → tool result / block reason（pi 原生，本模块不涉及）
 //   2. 事后排查   → pi.appendEntry（custom entry 不进 LLM 上下文，不显 TUI）【实装】
 //   3. 开发者调试 → 文件日志，双开关分级（写 <agentDir>/logs/，均未注入默认 no-op）【实装】：
-//        - XYZ_AGENT_DEBUG=1 → DEBUG 全量（现状语义，level 原样标注）
-//        - XYZ_AGENT_EXT_LOG=1 → INFO 级落盘（xyz 托管环境由 runtime spawn 时经
+//        - TAIJI_AGENT_DEBUG=1 → DEBUG 全量（现状语义，level 原样标注）
+//        - TAIJI_AGENT_EXT_LOG=1 → INFO 级落盘（taiji 托管环境由 runtime spawn 时经
 //          buildOutboundChildEnv extras 注入，设计 file-lock-unification-and-reaper-sink
 //          §3.2-D4 / U3-3）+ 7 天保留期清理；debug() 调用此模式下重标 info 写入
 //        - 两变量同时注入按更详细的生效（DEBUG 全量优先）
@@ -22,8 +22,7 @@
 // 直接调 ctx.ui.notify。
 //
 // fileLog 单日文件无 size cap——显式豁免，依据：写入方为每 session 短命 pi 进程
-// + 7 天保留期清理 + DEBUG 档系开发者主动排障；重审触发条件见
-// docs/design/ext-simplify-14-shared-libs.md §7。
+// + 7 天保留期清理 + DEBUG 档系开发者主动排障。
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
@@ -48,11 +47,11 @@ import { join } from "node:path";
 //   - key = msg 原文（不包含 data 参数）。若调用方把动态 id 拼进 msg
 //     （如 `session=${id}`），每条 msg 不同则限流不命中。根治靠调用方把
 //     动态值放 data 参数（D4 已声明）。
-//   - fileLog 通道全量不限流（XYZ_AGENT_DEBUG=1 / XYZ_AGENT_EXT_LOG=1 时日志写文件）。
+//   - fileLog 通道全量不限流（TAIJI_AGENT_DEBUG=1 / TAIJI_AGENT_EXT_LOG=1 时日志写文件）。
 //   - Map cap 512 超限时全量清空（简化策略，对齐 cap-1024 先例），
 //     等价于所有 key 窗口重置，防无界增长。
 //
-// 设计依据：docs/todo/extension-log-cleanup-design.md §3.4 D4
+// 设计依据：extension-log-cleanup-design §3.4 D4
 // ============================================================
 
 /** 同 key 每窗口允许直写 appendEntry 的最大条数。 */
@@ -77,7 +76,7 @@ interface RateLimiterEntry {
  * key = `${extName}:${level}:${msg}`（msg 为原 msg，非 prefixed）。
  * 同进程所有 logger 实例共享（模块级 singleton）。
  *
- * ⚠️ 生命周期与进程一致——xyz-agent 每 session 一个独立 pi 进程
+ * ⚠️ 生命周期与进程一致——taiji 每 session 一个独立 pi 进程
  * （见 runtime process-manager.ts 的类注释），故不存在跨 session 残留问题。
  */
 const rateLimiterState = new Map<string, RateLimiterEntry>();
@@ -157,7 +156,7 @@ export interface PiLike {
 	appendEntry?(customType: string, data?: unknown): void;
 }
 
-/** 日志级别。debug = 开发调试；info = XYZ_AGENT_EXT_LOG 模式下 debug() 的落盘标注；warn/error = 内部降级与失败（事后排查价值）。 */
+/** 日志级别。debug = 开发调试；info = TAIJI_AGENT_EXT_LOG 模式下 debug() 的落盘标注；warn/error = 内部降级与失败（事后排查价值）。 */
 type LogLevel = "debug" | "info" | "warn" | "error";
 
 /**
@@ -166,8 +165,8 @@ type LogLevel = "debug" | "info" | "warn" | "error";
  */
 export interface ExtensionLogger {
 	/**
-	 * 开发调试日志。默认 no-op；XYZ_AGENT_DEBUG=1 时写文件日志（原级标注）；
-	 * XYZ_AGENT_EXT_LOG=1（无 DEBUG）时以 info 级落盘（托管环境 INFO 观测档）。
+	 * 开发调试日志。默认 no-op；TAIJI_AGENT_DEBUG=1 时写文件日志（原级标注）；
+	 * TAIJI_AGENT_EXT_LOG=1（无 DEBUG）时以 info 级落盘（托管环境 INFO 观测档）。
 	 * 不进 appendEntry。
 	 */
 	debug(msg: string, data?: unknown): void;
@@ -273,7 +272,7 @@ export function createLogger(extName: string, pi?: PiLike): ExtensionLogger {
 				// appendEntry 失败（session 已 disposed 等）→ 降级文件日志（下方 fileLog 兜底），不 throw
 				void appendErr;
 			}
-			// fileLog 全量不限流（XYZ_AGENT_DEBUG=1 排障时可见全部）
+			// fileLog 全量不限流（TAIJI_AGENT_DEBUG=1 排障时可见全部）
 			fileLog(extName, "warn", prefixed, data);
 		},
 		error(msg: string, data?: unknown): void {
@@ -348,10 +347,10 @@ function prefixMsg(extName: string, msg: string): string {
 }
 
 // ============================================================
-// XYZ_AGENT_EXT_LOG 托管观测档 + 保留期清理
+// TAIJI_AGENT_EXT_LOG 托管观测档 + 保留期清理
 // ============================================================
 
-/** 托管观测档（XYZ_AGENT_EXT_LOG=1）的日志保留天数，超期文件在首次落盘时清理。 */
+/** 托管观测档（TAIJI_AGENT_EXT_LOG=1）的日志保留天数，超期文件在首次落盘时清理。 */
 const EXT_LOG_KEEP_DAYS = 7;
 // 一天的毫秒数（数字分隔符形式对齐 session-reader hash-provider 的时间常量惯例）
 const MS_PER_DAY = 86_400_000;
@@ -412,8 +411,8 @@ export function resetExtLogCleanupForTest(): void {
  * 写文件日志到 `<agentDir>/logs/<extName>-YYYY-MM-DD.log`。
  *
  * 双开关分级（设计 file-lock-unification-and-reaper-sink §3.2-D4）：
- * - XYZ_AGENT_DEBUG=1 → DEBUG 全量，level 原样标注（现状语义不变）；
- * - 仅 XYZ_AGENT_EXT_LOG=1 → INFO 级落盘：debug() 调用重标 info 写入，warn/error 照写；
+ * - TAIJI_AGENT_DEBUG=1 → DEBUG 全量，level 原样标注（现状语义不变）；
+ * - 仅 TAIJI_AGENT_EXT_LOG=1 → INFO 级落盘：debug() 调用重标 info 写入，warn/error 照写；
  * - 均未注入 → no-op（零 fs 调用，裸 pi 独立用户零磁盘/行为影响）。
  * agentDir 通过 pi 的 SSOT `getAgentDir()` 推导（读
  * `PI_CODING_AGENT_DIR`/`${APP_NAME}_CODING_AGENT_DIR`，默认 `~/.pi/agent`），
@@ -425,8 +424,8 @@ export function resetExtLogCleanupForTest(): void {
  * 行可能交错（可接受——debug 日志不要求严格顺序）。
  */
 function fileLog(extName: string, level: LogLevel, msg: string, data?: unknown): void {
-	const debugMode = process.env.XYZ_AGENT_DEBUG === "1";
-	const extLogMode = !debugMode && process.env.XYZ_AGENT_EXT_LOG === "1";
+	const debugMode = process.env.TAIJI_AGENT_DEBUG === "1";
+	const extLogMode = !debugMode && process.env.TAIJI_AGENT_EXT_LOG === "1";
 	if (!debugMode && !extLogMode) return;
 	// 托管观测档：debug() 调用降档标注为 info（INFO 级观测，非 DEBUG 全量）
 	const effectiveLevel: LogLevel = extLogMode && level === "debug" ? "info" : level;