@xinghe-labs/pi-context-stats 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-10-27
+
+### Added
+- 状态栏常驻显示压缩次数 + 缓存读 + 花费
+- `/ctxstats` 命令展开详情:
+  - 压缩历史(时间、压缩前 tokens、原因、压缩自身花费)
+  - 缓存读(累计 / 最近一轮 / 平均每轮 / 命中率 / 缓存写)
+  - **上下文占用** (🧠 上下文 / 200k tokens(81.9%))
+  - **缓存浪费** (♻️ tokens ≈ $金额 + miss 次数)
+  - 非对话回合用量分解(cache_warm / 压缩调用)
+  - 输入(未命中) / 输出 / 请求次数 / 总花费
+- 压缩原因通过 `pi.appendEntry("context-stats.compaction", {id, reason})` 持久化,resume 后可回填
+- 压缩历史含该次压缩自身的 LLM 调用费用
+- `type:"usage"` 条目(cache_warm 保温刷新)计入统计
+- 缓存浪费算法与 pi 内置 `computeCacheWaste` 数值等价(10 场景对拍验证)
+- 噪声下限 1024 tokens:小幅波动不报警
+- 压缩/保温后基准重置,切换模型仍计 miss

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# context-stats
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![pi-package](https://img.shields.io/badge/pi--package-context--stats-blue)](https://pi.dev/packages)
+
+pi 扩展:追踪上下文压缩、prompt 缓存命中与 token 花费。**零依赖、纯 TypeScript、~360 行**。
+
+## 状态栏
+
+```
+📦1次压缩 │ 读713.6k·本轮627.2k │ $0.059
+```
+
+| 段 | 含义 |
+|---|---|
+| `📦N次压缩` | 发生过 session 压缩(never compaction 时隐藏) |
+| `读X·本轮Y` | X = 累计 cacheRead tokens;Y = 最近一次对话回合的 cacheRead |
+| `$X.XXX` | 本会话总花费 |
+
+## `/ctxstats` 命令
+
+```
+🧠 上下文:163.8k / 200.0k tokens(81.9%)
+
+📦 压缩次数:2
+   10:30 · 压缩前 19.4k tokens · threshold · $0.0025
+   11:05 · 压缩前 320.0k tokens · overflow · $0.0040
+
+💾 缓存读(累计):1.01M tokens
+   最近一轮:300.0k │ 平均每轮:356.8k
+   缓存命中率:99.6%
+   缓存写:800 tokens
+   其中非对话回合:压缩 19.4k · cache_warm 50.0k
+♻️ 缓存浪费:51.2k tokens ≈ $0.1382(1 次 miss)
+
+↑ 输入(未命中):3.0k tokens
+↓ 输出:1.0k tokens
+💬 请求次数:2
+💰 总花费:$0.068
+   其中:压缩 $0.0065 · cache_warm $0.0150
+```
+
+## 安装
+
+```bash
+pi install npm:pi-context-stats
+```
+
+或从本地路径:
+
+```bash
+pi install /path/to/context-stats
+```
+
+## 统计口径
+
+### 计入的用量来源
+
+| 来源 | 说明 |
+|---|---|
+| `message` (assistant) | 常规对话回合 |
+| `type:"usage"` 条目 | `cache_warm` 保温刷新(pi 计入 session 总量,但不进上下文) |
+| `CompactionEntry.usage` | 压缩摘要调用(走 `completeSimple`,**不触发** `message_end`) |
+
+### 压缩原因持久化
+
+压缩原因只存在于 live 事件(`session_compact.reason`),`CompactionEntry` 里没有。本扩展用 `pi.appendEntry("context-stats.compaction", {id, reason})` 持久化,resume/reload 后按 `entry.id` 回填。
+
+### 缓存浪费算法
+
+与 pi 内置 `computeCacheWaste` 数值等价(10 场景对拍验证):
+
+- 噪声下限 **1024 tokens**(小波动不报警)
+- 压缩 / 分支摘要 → **重置基准**,下一轮不误报
+- 切换模型 → **仍计 miss**(会全量重算)
+- `cache_warm` 保温刷新 → 被当作「上一轮请求」
+
+### 已知差异 vs pi 内置
+
+pi 自己的实现在 `cost` 明细缺字段时会返回 `NaN`(它写 `cost.input + cost.cacheWrite`)。本扩展用 `?? 0` 兜底,显示有限值而非 `$NaN`。代价:若 provider 真的漏报 cost 桶,数字会偏乐观(缺失桶当 0)。pi-ai 正常产出的 `Usage` 四个桶齐全,实际不会触发。
+
+## 开发
+
+```bash
+# 运行 mock 测试(11 组行为)
+node /tmp/test-context-stats.mjs
+
+# 与 pi 内置 computeCacheWaste 对拍(10 场景)
+node /tmp/crosscheck-cache-waste.mjs
+```
+
+## License
+
+MIT

package/extensions/context-stats.ts

@@ -0,0 +1,401 @@
+/**
+ * Context Stats Extension — 记录压缩次数与缓存 token 用量
+ *
+ * - 状态栏常驻显示:压缩次数 | 缓存读(累计/本轮) | 花费
+ * - /ctxstats 查看详细统计:压缩历史、平均每轮缓存读、请求次数、非对话用量
+ * - 数据从 session 分支条目重建,resume / fork 后依然准确
+ *
+ * 计入的不只是对话回合,还包括 pi 另外两类用量(否则总量会比 pi 自己报的少):
+ * - 压缩摘要的一次性 LLM 调用:CompactionEntry.usage,走 completeSimple 直调,不触发 message_end
+ * - type:"usage" 条目:如 idle 时的 prompt cache 保温刷新(kind = "cache_warm")
+ *
+ * 说明：cacheRead 是按请求累计的（每轮都重读整个缓存前缀），
+ * 所以它 ≈ 各轮上下文大小之和，大是正常的；命中率才是省钱指标。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+interface UsageLike {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost?: {
+		input?: number;
+		output?: number;
+		cacheRead?: number;
+		cacheWrite?: number;
+		total?: number;
+	};
+}
+
+/** 非对话回合的用量,按 kind 分组(如 cache_warm) */
+interface AuxUsage {
+	read: number;
+	cost: number;
+	count: number;
+}
+
+interface CompactionRecord {
+	time: string;
+	tokensBefore: number;
+	reason: string;
+	cost: number;
+}
+
+interface Stats {
+	compactions: CompactionRecord[];
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	requests: number;
+	lastRead: number; // 最近一次对话回合的缓存读
+	compactRead: number; // 压缩调用自身的缓存读(已计入 cacheRead)
+	compactCost: number;
+	aux: Map<string, AuxUsage>; // type:"usage" 条目(已计入上面的总量)
+}
+
+/** pi 判定缓存 miss 的噪声下限。复刻自 pi 内置 dist/core/cache-stats.js */
+const NOISE_FLOOR_TOKENS = 1024;
+
+interface CacheWaste {
+	missedTokens: number;
+	missedCost: number;
+	missCount: number;
+}
+
+interface RequestState {
+	promptTokens: number;
+	reportedCache: boolean;
+}
+
+interface ModelRegistryLike {
+	find(provider: string, modelId: string):
+		| { cost: { cacheRead: number } }
+		| undefined;
+}
+
+/** 用于扫描分支条目的宽类型(条目种类多,只取需要的字段) */
+interface EntryLike {
+	type?: string;
+	kind?: string;
+	usage?: UsageLike;
+	message?: {
+		role?: string;
+		provider?: string;
+		model?: string;
+		usage?: UsageLike;
+	};
+}
+
+function asPreviousRequest(
+	u: UsageLike | undefined,
+	reportedCache: boolean,
+): RequestState | undefined {
+	if (!u) return undefined;
+	const promptTokens = (u.input ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+	if (promptTokens <= 0) return undefined;
+	return {
+		promptTokens,
+		reportedCache: reportedCache || u.cacheRead + u.cacheWrite > 0,
+	};
+}
+
+/**
+ * 缓存浪费:上一轮 prompt 里本来已在缓存中的 token,这一轮却被按 input / cacheWrite 重新计费。
+ * 它比命中率更能说明「到底花了多少冤枉钱」。算法与 pi 内置的 computeCacheWaste 一致
+ * (内的 cache-stats.js 未公开导出,且本目录解析不到包内深层路径,故在此复刻)。
+ */
+function computeCacheWaste(
+	entries: readonly EntryLike[],
+	registry: ModelRegistryLike | undefined,
+): CacheWaste {
+	const totals: CacheWaste = { missedTokens: 0, missedCost: 0, missCount: 0 };
+	let prev: RequestState | undefined;
+
+	for (const entry of entries) {
+		// 上下文被合法改写(压缩/分支摘要),下一轮 prompt 是新内容,不算浪费;模型切换除外(会重新全量计费)
+		if (entry.type === "compaction" || entry.type === "branch_summary") {
+			prev = undefined;
+			continue;
+		}
+		// 保温刷新本身被视为「上一轮请求」,不作为 miss 源
+		if (entry.type === "usage" && entry.kind === "cache_warm") {
+			prev = asPreviousRequest(entry.usage, true) ?? prev;
+			continue;
+		}
+		if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+
+		const msg = entry.message;
+		const u = msg.usage;
+		const promptTokens = u
+			? (u.input ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0)
+			: 0;
+		// 首次请求、无缓存活动上报(provider 不支持缓存)都不算 miss
+		const eligible =
+			prev !== undefined &&
+			u !== undefined &&
+			promptTokens > 0 &&
+			(u.cacheRead + u.cacheWrite > 0 || prev.reportedCache);
+		if (eligible && prev && u) {
+			const missedTokens = Math.min(prev.promptTokens, promptTokens) - u.cacheRead;
+			if (missedTokens > NOISE_FLOOR_TOKENS) {
+				// 被重新计费的部分只能落在 input / cacheWrite 桶,所以实付单价直接由本条消息的成本明细得出
+				const paidTokens = u.input + u.cacheWrite;
+				const paidPerToken =
+					paidTokens > 0
+						? ((u.cost?.input ?? 0) + (u.cost?.cacheWrite ?? 0)) / paidTokens
+						: 0;
+				const readPerToken =
+					u.cacheRead > 0
+						? (u.cost?.cacheRead ?? 0) / u.cacheRead
+						: msg.provider && msg.model
+							? (registry?.find(msg.provider, msg.model)?.cost.cacheRead ?? 0) / 1_000_000
+							: 0;
+				totals.missedTokens += missedTokens;
+				totals.missedCost += missedTokens * Math.max(0, paidPerToken - readPerToken);
+				totals.missCount += 1;
+			}
+		}
+		prev = asPreviousRequest(u, prev?.reportedCache ?? false) ?? prev;
+	}
+	return totals;
+}
+
+export default function (pi: ExtensionAPI) {
+	let stats: Stats = newStats();
+	const STATUS_KEY = "ctx-stats";
+	// 压缩原因只存在于 live 事件,条目里没有;写入自定义条目以便 resume 后回填
+	const REASON_LOG = "context-stats.compaction";
+
+	function newStats(): Stats {
+		return {
+			compactions: [],
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			cost: 0,
+			requests: 0,
+			lastRead: 0,
+			compactRead: 0,
+			compactCost: 0,
+			aux: new Map(),
+		};
+	}
+
+	const fmt = (n: number): string => {
+		if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M`;
+		if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+		return `${n}`;
+	};
+
+	const fmtTime = (iso: string): string => iso.slice(11, 16); // "HH:MM"
+
+	function hitRate(s: Stats = stats): number {
+		return s.input + s.cacheRead > 0
+			? (s.cacheRead / (s.input + s.cacheRead)) * 100
+			: 0;
+	}
+
+	function updateStatus(ctx: ExtensionContext) {
+		if (!ctx.hasUI) return;
+		const theme = ctx.ui.theme;
+		const dim = (t: string) => theme.fg("dim", t);
+		const parts: string[] = [];
+
+		if (stats.compactions.length > 0) {
+			parts.push(theme.fg("warning", `📦${stats.compactions.length}次压缩`));
+		}
+		parts.push(
+			dim(`读${fmt(stats.cacheRead)}·本轮${fmt(stats.lastRead)}`),
+			theme.fg("success", `$${stats.cost.toFixed(3)}`),
+		);
+		ctx.ui.setStatus(STATUS_KEY, parts.join(dim(" │ ")));
+	}
+
+	/** 累计一次 LLM 调用。turn = 对话回合;compaction = 压缩摘要调用;aux = 非对话用量 */
+	function accumulate(
+		u: UsageLike | undefined,
+		bucket: "turn" | "aux" | "compaction" = "turn",
+	) {
+		if (!u) return;
+		stats.input += u.input ?? 0;
+		stats.output += u.output ?? 0;
+		stats.cacheRead += u.cacheRead ?? 0;
+		stats.cacheWrite += u.cacheWrite ?? 0;
+		stats.cost += u.cost?.total ?? 0;
+		if (bucket === "turn") {
+			stats.requests += 1;
+			stats.lastRead = u.cacheRead ?? 0;
+		} else if (bucket === "compaction") {
+			stats.compactRead += u.cacheRead ?? 0;
+			stats.compactCost += u.cost?.total ?? 0;
+		}
+	}
+
+	/** type:"usage" 条目,如 cache_warm 保温刷新(pi 计入 session 总量,但不进模型上下文) */
+	function accumulateAux(kind: string, u: UsageLike | undefined) {
+		if (!u) return;
+		accumulate(u, "aux");
+		const prev = stats.aux.get(kind) ?? { read: 0, cost: 0, count: 0 };
+		prev.read += u.cacheRead ?? 0;
+		prev.cost += u.cost?.total ?? 0;
+		prev.count += 1;
+		stats.aux.set(kind, prev);
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		stats = newStats();
+		const entries = ctx.sessionManager.getBranch();
+		// 先用自定义条目建 id → reason 映射(压缩条目本身不记录原因)
+		const reasons = new Map<string, string>();
+		for (const entry of entries) {
+			if (entry.type === "custom" && entry.customType === REASON_LOG) {
+				const d = entry.data as { id?: string; reason?: string } | undefined;
+				if (d?.id) reasons.set(d.id, d.reason ?? "unknown");
+			}
+		}
+		for (const entry of entries) {
+			if (entry.type === "compaction") {
+				const e = entry as {
+					id?: string;
+					tokensBefore?: number;
+					timestamp?: string;
+					usage?: UsageLike;
+				};
+				stats.compactions.push({
+					time: e.timestamp ?? "",
+					tokensBefore: e.tokensBefore ?? 0,
+					reason: (e.id ? reasons.get(e.id) : undefined) ?? "",
+					cost: e.usage?.cost?.total ?? 0,
+				});
+				accumulate(e.usage, "compaction");
+			} else if (entry.type === "usage") {
+				const e = entry as { kind?: string; usage?: UsageLike };
+				accumulateAux(e.kind ?? "usage", e.usage);
+			} else if (entry.type === "message" && entry.message.role === "assistant") {
+				accumulate((entry.message as { usage?: UsageLike }).usage);
+			}
+		}
+		updateStatus(ctx);
+	});
+
+	pi.on("message_end", async (event, ctx) => {
+		const m = event.message as { role?: string; usage?: UsageLike };
+		if (m.role !== "assistant") return;
+		accumulate(m.usage);
+		updateStatus(ctx);
+	});
+
+	pi.on("session_compact", async (event, ctx) => {
+		const entry = event.compactionEntry as {
+			id?: string;
+			tokensBefore?: number;
+			timestamp?: string;
+			usage?: UsageLike;
+		};
+		const reason = event.reason ?? "manual";
+		const cost = entry.usage?.cost?.total ?? 0;
+		stats.compactions.push({
+			time: entry.timestamp ?? "",
+			tokensBefore: entry.tokensBefore ?? 0,
+			reason,
+			cost,
+		});
+		// 压缩自身的 LLM 调用走 completeSimple 直调,不触发 message_end,必须在这里记账
+		accumulate(entry.usage, "compaction");
+		if (entry.id) pi.appendEntry(REASON_LOG, { id: entry.id, reason });
+		updateStatus(ctx);
+		if (ctx.hasUI) {
+			const costText = cost > 0 ? ` · $${cost.toFixed(4)}` : "";
+			ctx.ui.notify(
+				`📦 第 ${stats.compactions.length} 次压缩完成(压缩前 ${fmt(entry.tokensBefore ?? 0)} tokens${costText})`,
+				"info",
+			);
+		}
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+	});
+
+	pi.registerCommand("ctxstats", {
+		description: "查看压缩次数与缓存 token 统计",
+		handler: async (_args, ctx) => {
+			const avgRead = stats.requests > 0 ? stats.cacheRead / stats.requests : 0;
+			const lines: string[] = [];
+
+			// 当前上下文占用(估算,压缩后会短暂为 null)
+			const cu = ctx.getContextUsage?.();
+			if (cu && cu.tokens !== null && cu.percent !== null) {
+				lines.push(
+					`🧠 上下文:${fmt(cu.tokens)} / ${fmt(cu.contextWindow)} tokens(${cu.percent.toFixed(1)}%)`,
+					``,
+				);
+			}
+			// 压缩历史
+			lines.push(`📦 压缩次数：${stats.compactions.length}`);
+			for (const c of stats.compactions.slice(-5)) {
+				const bits: string[] = [];
+				if (c.time) bits.push(fmtTime(c.time));
+				bits.push(`压缩前 ${fmt(c.tokensBefore)} tokens`);
+				if (c.reason) bits.push(c.reason);
+				if (c.cost > 0) bits.push(`$${c.cost.toFixed(4)}`);
+				lines.push(`   ${bits.join(" · ")}`);
+			}
+
+			// 缓存统计
+			lines.push(
+				``,
+				`💾 缓存读（累计）：${fmt(stats.cacheRead)} tokens`,
+				`   最近一轮：${fmt(stats.lastRead)} │ 平均每轮：${fmt(avgRead)}`,
+				`   缓存命中率：${hitRate().toFixed(1)}%`,
+				`   缓存写:${fmt(stats.cacheWrite)} tokens`,
+			);
+
+			// 非对话回合的用量(压缩 + type:"usage" 条目)已含在累计里,这里单独列出
+			const readBits: string[] = [];
+			if (stats.compactRead > 0) readBits.push(`压缩 ${fmt(stats.compactRead)}`);
+			for (const [kind, v] of stats.aux) {
+				if (v.read > 0) readBits.push(`${kind} ${fmt(v.read)}`);
+			}
+			if (readBits.length > 0) {
+				lines.push(`   其中非对话回合:${readBits.join(" · ")}`);
+			}
+
+			// 缓存浪费:与本会话「被重复计费」的 token / 金额(按分支条目现场重算)
+			const waste = computeCacheWaste(
+				ctx.sessionManager.getBranch() as EntryLike[],
+				ctx.modelRegistry,
+			);
+			lines.push(
+				waste.missCount > 0
+					? `♻️ 缓存浪费:${fmt(waste.missedTokens)} tokens ≈ $${waste.missedCost.toFixed(4)}(${waste.missCount} 次 miss)`
+					: `♻️ 缓存浪费:未检测到重复计费`,
+			);
+
+			// 输入输出
+			lines.push(
+				``,
+				`↑ 输入（未命中）：${fmt(stats.input)} tokens`,
+				`↓ 输出：${fmt(stats.output)} tokens`,
+				`💬 请求次数：${stats.requests}`,
+				`💰 总花费:$${stats.cost.toFixed(4)}`,
+			);
+
+			const costBits: string[] = [];
+			if (stats.compactCost > 0) costBits.push(`压缩 $${stats.compactCost.toFixed(4)}`);
+			for (const [kind, v] of stats.aux) {
+				if (v.cost > 0) costBits.push(`${kind} $${v.cost.toFixed(4)}`);
+			}
+			if (costBits.length > 0) {
+				lines.push(`   其中:${costBits.join(" · ")}`);
+			}
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@xinghe-labs/pi-context-stats",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "pi 扩展:状态栏实时显示压缩次数+缓存读+花费,/ctxstats 展示压缩历史、缓存命中率、缓存浪费(miss 计费)与各项费用分解",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "context",
+    "stats",
+    "cache",
+    "compaction",
+    "tokens",
+    "cost"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/context-stats.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*"
+  },
+  "engines": {
+    "pi": ">=1.3.0"
+  },
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}