@zhushanwen/pi-extension-logger 0.4.1 → 0.6.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-extension-logger",
-  "version": "0.4.1",
-  "description": "Shared logging helper for Pi extensions — three-channel routing (AI realtime / audit / debug) (shared library, not a Pi extension - no install.mjs needed)",
+  "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",
   "keywords": [

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()）保持一致。
@@ -155,19 +155,19 @@ describe("extension-logger", () => {
 		afterEach(() => {
 			vi.useRealTimers();
 			if (tmpAgentDir) {
-				rmSync(tmpAgentDir, { recursive: true, force: true });
+				rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 			}
 		});
 
-		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 失败。
@@ -226,7 +226,7 @@ describe("extension-logger", () => {
 
 			// 清理：先恢复写权限才能删除
 			chmodSync(logDir, RESTORE_MODE);
-			rmSync(readonlyAgentDir, { recursive: true, force: true });
+			rmSync(readonlyAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 		});
 	});
 
@@ -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"));
@@ -269,21 +269,21 @@ describe("extension-logger", () => {
 			expect(content).not.toContain('"count"');
 
 			vi.useRealTimers();
-			rmSync(tmpAgentDir, { recursive: true, force: true });
+			rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 		});
 	});
 
 	// ============================================================
-	// 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();
 		});
@@ -291,7 +291,7 @@ describe("extension-logger", () => {
 		afterEach(() => {
 			vi.useRealTimers();
 			resetExtLogCleanupForTest();
-			rmSync(tmpAgentDir, { recursive: true, force: true });
+			rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 		});
 
 		it("均未注入时 no-op：debug/warn/error 调用后 logs 目录都不创建（裸 pi 用户零磁盘影响）", () => {
@@ -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"));
@@ -531,7 +531,7 @@ describe("extension-logger", () => {
 			const lines = content.split("\n").filter(Boolean);
 			expect(lines).toHaveLength(100);
 
-			rmSync(tmpAgentDir, { recursive: true, force: true });
+			rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 		});
 
 		it("appendEntry 抛错时降级不 throw（限流计数正常）", () => {

package/src/index.ts

@@ -1,18 +1,18 @@
 // src/index.ts
 //
-// 共享 extension logger —— 三层通道分类，按受众路由日志。
+// 共享 extension logger —— 双通道日志封装，按受众路由。
 //
 // 设计依据：pi 宿主层（ExtensionAPI/ExtensionContext）不提供 logger 接口。
 // extension 只能裸 console（污染 TUI raw stderr）或自组 ctx.ui.notify（刷屏）+
-// pi.appendEntry（持久化但用户不可见）。本模块封装这套三层通道，让 @zhushanwen/pi-*
+// pi.appendEntry（持久化但用户不可见）。本模块封装这套通道，让 @zhushanwen/pi-*
 // 各包统一调用，消除裸 console。
 //
-// 三层通道：
+// 三通道分类法（本模块实装其中两通道；通道 1 为 pi 原生行为，仅登记不封装）：
 //   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 时经
+//   2. 事后排查   → pi.appendEntry（custom entry 不进 LLM 上下文，不显 TUI）【实装】
+//   3. 开发者调试 → 文件日志，双开关分级（写 <agentDir>/logs/，均未注入默认 no-op）【实装】：
+//        - 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 全量优先）
@@ -20,6 +20,9 @@
 //
 // notify（用户操作反馈）刻意不封装——它是 UI 决策，留给各 extension 在命令/视图层
 // 直接调 ctx.ui.notify。
+//
+// fileLog 单日文件无 size cap——显式豁免，依据：写入方为每 session 短命 pi 进程
+// + 7 天保留期清理 + DEBUG 档系开发者主动排障。
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
@@ -44,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 的最大条数。 */
@@ -73,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>();
@@ -153,8 +156,8 @@ export interface PiLike {
 	appendEntry?(customType: string, data?: unknown): void;
 }
 
-/** 日志级别。debug = 开发调试；info = XYZ_AGENT_EXT_LOG 模式下 debug() 的落盘标注；warn/error = 内部降级与失败（事后排查价值）。 */
-export type LogLevel = "debug" | "info" | "warn" | "error";
+/** 日志级别。debug = 开发调试；info = TAIJI_AGENT_EXT_LOG 模式下 debug() 的落盘标注；warn/error = 内部降级与失败（事后排查价值）。 */
+type LogLevel = "debug" | "info" | "warn" | "error";
 
 /**
  * Extension logger 接口。方法名即语义——不做运行时 level filtering（pi 不支持，
@@ -162,8 +165,8 @@ export 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;
@@ -219,11 +222,12 @@ export function setPiHandle(pi: PiLike | undefined): void {
 /**
  * 创建具名 logger。
  *
- * @param extName  extension 名（如 "subagents"、"unified-hooks"），用作：
+ * @param extName  extension 名（如 "subagents"、"smart-context"），用作：
  *                  - appendEntry 的 customType 前缀（`<extName>:log`）
  *                  - 文件日志名（`<extName>-YYYY-MM-DD.log`）
  *                  - msg 前缀（`[<extName>]`，自动补）
- * @param pi       可选 pi handle；不传则用 setPiHandle 注入的全局 handle
+ * @param pi       可选 pi handle；测试隔离注入用，生产一律 setPiHandle/getLogger。
+ *                  不传则用 setPiHandle 注入的全局 handle
  * @returns        ExtensionLogger 实例（每次返回同一引用，便于模块级 const 缓存）
  */
 export function createLogger(extName: string, pi?: PiLike): ExtensionLogger {
@@ -268,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 {
@@ -343,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;
@@ -407,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`），
@@ -420,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;