@zhushanwen/pi-extension-logger 0.2.1 → 0.3.0

package/index.ts

@@ -1 +1 @@
-export { createLogger, getLogger, setPiHandle, type ExtensionLogger, type PiLike } from "./src/index.js";
+export { createLogger, getLogger, setPiHandle, clearRateLimiterState, type ExtensionLogger, type PiLike } from "./src/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-extension-logger",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Shared logging helper for Pi extensions — three-channel routing (AI realtime / audit / debug) (shared library, not a Pi extension - no install.mjs needed)",
   "type": "module",
   "main": "src/index.ts",
@@ -17,9 +17,10 @@
     "index.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "^0.84.1"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "scripts": {

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

@@ -7,6 +7,7 @@ import {
 	createLogger,
 	getLogger,
 	setPiHandle,
+	clearRateLimiterState,
 	type PiLike,
 } from "../index.js";
 
@@ -23,6 +24,7 @@ describe("extension-logger", () => {
 
 	afterEach(() => {
 		setPiHandle(undefined);
+		clearRateLimiterState();
 		vi.restoreAllMocks();
 		// 还原环境变量，避免文件日志测试的 XYZ_AGENT_DEBUG/PI_CODING_AGENT_DIR 泄漏到其它用例
 		process.env = { ...prevEnv };
@@ -269,4 +271,161 @@ describe("extension-logger", () => {
 			rmSync(tmpAgentDir, { recursive: true, force: true });
 		});
 	});
+
+	// ============================================================
+	// Per-message 固定窗口限流（P3 防线）
+	// ============================================================
+	describe("per-message 固定窗口限流", () => {
+		beforeEach(() => {
+			vi.useFakeTimers();
+		});
+
+		afterEach(() => {
+			vi.useRealTimers();
+		});
+
+		it("前 10 条同 msg warn 直写 appendEntry", () => {
+			const logger = createLogger("ratelimit", pi);
+			for (let i = 0; i < 10; i++) {
+				logger.warn("hot path warning");
+			}
+			expect(appendSpy).toHaveBeenCalledTimes(10);
+		});
+
+		it("第 11-100 条同 msg warn 被抑制（计数仍 10）", () => {
+			const logger = createLogger("ratelimit", pi);
+			for (let i = 0; i < 100; i++) {
+				logger.warn("hot path warning");
+			}
+			expect(appendSpy).toHaveBeenCalledTimes(10);
+		});
+
+		it("fake timers 推进 61s 后下一条触发聚合摘要 + 本条直写", () => {
+			const logger = createLogger("ratelimit", pi);
+			// 先发 100 条（10 条直写 + 90 条抑制）
+			for (let i = 0; i < 100; i++) {
+				logger.warn("hot path warning");
+			}
+			expect(appendSpy).toHaveBeenCalledTimes(10);
+
+			// 推进 61s——窗口过期
+			vi.advanceTimersByTime(61_000);
+
+			// 下一条：先写聚合摘要（+90 suppressed），再写本条
+			logger.warn("hot path warning");
+			expect(appendSpy).toHaveBeenCalledTimes(12);
+
+			// 验证聚合摘要 entry 内容
+			const summaryCall = appendSpy.mock.calls[10]!;
+			const summaryData = summaryCall[1] as { message: string };
+			expect(summaryData.message).toContain("[+90 suppressed in last 60s]");
+
+			// 验证本条 entry 是正常 warn
+			const currentCall = appendSpy.mock.calls[11]!;
+			const currentData = currentCall[1] as { message: string; level: string };
+			expect(currentData.message).toBe("[ratelimit] hot path warning");
+			expect(currentData.level).toBe("warn");
+		});
+
+		it("不同 msg 独立计数互不影响", () => {
+			const logger = createLogger("ratelimit", pi);
+			for (let i = 0; i < 15; i++) {
+				logger.warn("msg-a");
+			}
+			for (let i = 0; i < 15; i++) {
+				logger.warn("msg-b");
+			}
+			// 各自前 10 条直写 = 20
+			expect(appendSpy).toHaveBeenCalledTimes(20);
+
+			// 推进 61s 后，各触发 1 条聚合摘要 + 1 条本条 = 再加 4 条
+			vi.advanceTimersByTime(61_000);
+			logger.warn("msg-a");
+			logger.warn("msg-b");
+			expect(appendSpy).toHaveBeenCalledTimes(24);
+		});
+
+		it("Map cap 512 超限清空——所有 key 窗口重置", () => {
+			const logger = createLogger("ratelimit", pi);
+			// 填充 512 个不同 key（各发 1 条触发窗口创建）
+			for (let i = 0; i < 512; i++) {
+				logger.warn(`msg-${i}`);
+			}
+			expect(appendSpy).toHaveBeenCalledTimes(512);
+
+			// 再发 1 条触发 cap 清空——此条也打开新窗口（count=1）
+			logger.warn("msg-after-cap");
+			expect(appendSpy).toHaveBeenCalledTimes(513);
+
+			appendSpy.mockClear();
+			// 推进时间让上面窗口过期，新窗口可直写 10 条
+			vi.advanceTimersByTime(61_000);
+			for (let i = 0; i < 10; i++) {
+				logger.warn("msg-after-cap");
+			}
+			// 第一条过期后 suppressed=0 → "allow" + count=1，后 9 条 count→10 全 allow
+			expect(appendSpy).toHaveBeenCalledTimes(10);
+		});
+
+		it("fileLog 通道不受限（XYZ_AGENT_DEBUG=1 时 100 条全写文件）", () => {
+			process.env.XYZ_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"));
+
+			const logger = createLogger("rl-file", pi);
+			for (let i = 0; i < 100; i++) {
+				logger.warn("hot path warning");
+			}
+
+			// appendEntry 只被调用 10 次（限流生效）
+			expect(appendSpy).toHaveBeenCalledTimes(10);
+
+			// 但文件日志包含全部 100 条（fileLog 不受限流）
+			const logFile = join(tmpAgentDir, "logs", "rl-file-2026-08-01.log");
+			expect(existsSync(logFile)).toBe(true);
+			const content = readFileSync(logFile, "utf8");
+			const lines = content.split("\n").filter(Boolean);
+			expect(lines).toHaveLength(100);
+
+			rmSync(tmpAgentDir, { recursive: true, force: true });
+		});
+
+		it("appendEntry 抛错时降级不 throw（限流计数正常）", () => {
+			const throwingPi: PiLike = {
+				appendEntry: () => {
+					throw new Error("session disposed");
+				},
+			};
+			const logger = createLogger("rl-throw", throwingPi);
+
+			// 10 条同 msg——appendEntry 每次抛但不 throw
+			for (let i = 0; i < 10; i++) {
+				expect(() => logger.warn("disposable")).not.toThrow();
+			}
+			// appendEntry 被调了 10 次（每条都 try 了）
+			// 推进窗口过期，聚合摘要 + 本条 = 再调 2 次
+			vi.advanceTimersByTime(61_000);
+			expect(() => logger.warn("disposable")).not.toThrow();
+			// appendEntry 异常时限流计数仍正常（不 throw、后续状态机不被破坏）
+		});
+
+		it("error 与 warn 同参数限流（一套机制）", () => {
+			const logger = createLogger("ratelimit", pi);
+			for (let i = 0; i < 15; i++) {
+				logger.error("error path");
+			}
+			// error 前 10 条直写，第 11-15 条抑制
+			expect(appendSpy).toHaveBeenCalledTimes(10);
+
+			// 推进 61s 后聚合摘要 + 本条
+			vi.advanceTimersByTime(61_000);
+			logger.error("error path");
+			expect(appendSpy).toHaveBeenCalledTimes(12);
+
+			const summaryCall = appendSpy.mock.calls[10]!;
+			const summaryData = summaryCall[1] as { message: string };
+			expect(summaryData.message).toContain("[+5 suppressed in last 60s]");
+		});
+	});
 });

package/src/index.ts

@@ -19,6 +19,117 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 
+// ============================================================
+// Per-message 固定窗口限流（P3 防线）
+//
+// 语义：同一个 (extName, level, msg) 三元组在 60s 窗口内，前 10 条 warn/error
+// 直写 pi.appendEntry（session JSONL），第 11 条起抑制并在内存计数。窗口
+// 过期后下一条到来时，先写 1 条聚合摘要（"...[+M suppressed in last 60s]"），
+// 再正常写本条并开新窗口。纯惰性实现——无 timer，全部状态在调用时检查
+// （Date.now() 判断窗口是否过期）。
+//
+// 已知限制：
+//   - key = msg 原文（不包含 data 参数）。若调用方把动态 id 拼进 msg
+//     （如 `session=${id}`），每条 msg 不同则限流不命中。根治靠调用方把
+//     动态值放 data 参数（D4 已声明）。
+//   - fileLog 通道全量不限流（XYZ_AGENT_DEBUG=1 时所有日志写文件）。
+//   - Map cap 512 超限时全量清空（简化策略，对齐 cap-1024 先例），
+//     等价于所有 key 窗口重置，防无界增长。
+//
+// 设计依据：docs/todo/extension-log-cleanup-design.md §3.4 D4
+// ============================================================
+
+/** 同 key 每窗口允许直写 appendEntry 的最大条数。 */
+const RATE_LIMIT_MAX = 10;
+/** 固定窗口时长（ms）。 */
+const RATE_LIMIT_WINDOW_MS = 60_000;
+/** 限流状态 Map 的容量上限——超限全量清空（对齐 cap-1024 先例的简化策略）。 */
+const RATE_LIMIT_STATE_CAP = 512;
+
+interface RateLimiterEntry {
+	/** 当前窗口起始时间戳（ms）。 */
+	windowStart: number;
+	/** 当前窗口内已直写 appendEntry 的条数。 */
+	count: number;
+	/** 当前窗口内被抑制的条数（窗口过期后用于聚合摘要）。 */
+	suppressed: number;
+}
+
+/**
+ * per-msg 限流状态。
+ *
+ * key = `${extName}:${level}:${msg}`（msg 为原 msg，非 prefixed）。
+ * 同进程所有 logger 实例共享（模块级 singleton）。
+ *
+ * ⚠️ 生命周期与进程一致——xyz-agent 每 session 一个独立 pi 进程
+ * （process-manager.ts L142-143），故不存在跨 session 残留问题。
+ */
+const rateLimiterState = new Map<string, RateLimiterEntry>();
+
+/**
+ * 检查并更新 per-msg 限流状态。返回值：
+ *   - "allow": 直写 appendEntry
+ *   - "suppress": 抑制（不写 appendEntry，内存计数）
+ *   - { emitSummary: M }: 窗口过期后首条——先写聚合摘要（M = 被抑制数），再写本条
+ *
+ * 纯惰性实现：无 timer，窗口过期判断在调用时通过 Date.now() 计算。
+ */
+function checkRateLimiter(
+	key: string,
+): "allow" | "suppress" | { emitSummary: number } {
+	// 防无界增长：超限清空（等价所有 key 窗口重置）
+	if (rateLimiterState.size >= RATE_LIMIT_STATE_CAP) {
+		rateLimiterState.clear();
+	}
+
+	const now = Date.now();
+	const entry = rateLimiterState.get(key);
+
+	if (!entry) {
+		// 首次见到该 key：开新窗口，count=1（本条是第 1 条）
+		rateLimiterState.set(key, {
+			windowStart: now,
+			count: 1,
+			suppressed: 0,
+		});
+		return "allow";
+	}
+
+	const elapsed = now - entry.windowStart;
+
+	if (elapsed >= RATE_LIMIT_WINDOW_MS) {
+		// 窗口过期：本条触发新窗口。若有被抑制数，先返回聚合摘要。
+		const suppressed = entry.suppressed;
+		// 开新窗口（count=1 计入本条）
+		rateLimiterState.set(key, {
+			windowStart: now,
+			count: 1,
+			suppressed: 0,
+		});
+		if (suppressed > 0) {
+			return { emitSummary: suppressed };
+		}
+		return "allow";
+	}
+
+	// 窗口内
+	if (entry.count < RATE_LIMIT_MAX) {
+		entry.count++;
+		return "allow";
+	}
+
+	// 已满额：抑制，计数
+	entry.suppressed++;
+	return "suppress";
+}
+
+/**
+ * 清空限流状态（测试用导出，生产代码不调用）。
+ */
+export function clearRateLimiterState(): void {
+	rateLimiterState.clear();
+}
+
 /**
  * Pi ExtensionAPI 的最小子集——仅 appendEntry（持久化审计通道）。
  *
@@ -110,34 +221,74 @@ export function createLogger(extName: string, pi?: PiLike): ExtensionLogger {
 		warn(msg: string, data?: unknown): void {
 			const piResolved = resolvePi();
 			const prefixed = prefixMsg(extName, msg);
-			// appendEntry 不进 LLM 上下文（session-manager.js: custom entry 不参与 context）
+			// appendEntry 通道：per-msg 固定窗口限流（debug 不限流——只走 fileLog）
+			const rateLimitKey = `${extName}:warn:${msg}`;
+			const rateLimitResult = checkRateLimiter(rateLimitKey);
 			try {
-				piResolved?.appendEntry?.(`${extName}:log`, {
-					timestamp: Date.now(),
-					level: "warn",
-					message: prefixed,
-					data,
-				});
+				if (rateLimitResult === "allow") {
+					piResolved?.appendEntry?.(`${extName}:log`, {
+						timestamp: Date.now(),
+						level: "warn",
+						message: prefixed,
+						data,
+					});
+				} else if (typeof rateLimitResult === "object") {
+					// 窗口过期后首条：先写聚合摘要
+					piResolved?.appendEntry?.(`${extName}:log`, {
+						timestamp: Date.now(),
+						level: "warn",
+						message: `${prefixed} ... [+${rateLimitResult.emitSummary} suppressed in last 60s]`,
+					});
+					// 再写本条
+					piResolved?.appendEntry?.(`${extName}:log`, {
+						timestamp: Date.now(),
+						level: "warn",
+						message: prefixed,
+						data,
+					});
+				}
+				// else: "suppress" — 不写 appendEntry
 			} catch (appendErr) {
 				// appendEntry 失败（session 已 disposed 等）→ 降级文件日志（下方 fileLog 兜底），不 throw
 				void appendErr;
 			}
+			// fileLog 全量不限流（XYZ_AGENT_DEBUG=1 排障时可见全部）
 			fileLog(extName, "warn", prefixed, data);
 		},
 		error(msg: string, data?: unknown): void {
 			const piResolved = resolvePi();
 			const prefixed = prefixMsg(extName, msg);
+			// appendEntry 通道：per-msg 固定窗口限流（与 warn 同参数，一套机制）
+			const rateLimitKey = `${extName}:error:${msg}`;
+			const rateLimitResult = checkRateLimiter(rateLimitKey);
 			try {
-				piResolved?.appendEntry?.(`${extName}:log`, {
-					timestamp: Date.now(),
-					level: "error",
-					message: prefixed,
-					data,
-				});
+				if (rateLimitResult === "allow") {
+					piResolved?.appendEntry?.(`${extName}:log`, {
+						timestamp: Date.now(),
+						level: "error",
+						message: prefixed,
+						data,
+					});
+				} else if (typeof rateLimitResult === "object") {
+					// 窗口过期后首条：先写聚合摘要
+					piResolved?.appendEntry?.(`${extName}:log`, {
+						timestamp: Date.now(),
+						level: "error",
+						message: `${prefixed} ... [+${rateLimitResult.emitSummary} suppressed in last 60s]`,
+					});
+					// 再写本条
+					piResolved?.appendEntry?.(`${extName}:log`, {
+						timestamp: Date.now(),
+						level: "error",
+						message: prefixed,
+						data,
+					});
+				}
 			} catch (appendErr) {
 				// 同 warn：appendEntry 失败降级文件日志，不 throw
 				void appendErr;
 			}
+			// fileLog 全量不限流
 			fileLog(extName, "error", prefixed, data);
 		},
 	};