@foolsecret/pi-prompt 0.4.0

package/src/prompts.ts

@@ -0,0 +1,197 @@
+/**
+ * 三轴注入提示词（策略模式）。
+ *
+ * ⚠️ 铁律：每个策略的注入块都必须是【逐字节稳定】的恒定字符串 —— 组合仍要
+ * 恒定拼接，追加在系统提示末尾；改动任何字节都会破坏提示前缀的 KV 缓存命中，
+ * 直接抬高 input miss 成本（DeepSeek miss 1 元/百万）。发布后若要改文案，
+ * 只能文档化迁移、不能在原位编辑（认知修正 #1）。
+ *
+ * show 轴文案沿用 v0.1（逐字节未动）；write/do 为 v0.2 新增。
+ * 单块均 ≤160 token；三轴全开合计 ~450 token/轮，仍远低于 caveman 规则
+ * 每轮 1-1.5k 输入 token 的量级。
+ */
+
+import type { DoMode, RuntimeShowMode, WriteMode } from "./modes.ts";
+
+/** 单个注入块策略接口（每轴每档 = 一个策略类） */
+interface BlobStrategy {
+	/** 返回该档注入的恒定文案（不注入的档返回空串） */
+	inject(): string;
+	/** 档位一句话说明（/prompt status 与补全用） */
+	readonly description: string;
+}
+
+/** 公共基类：统一拼块结构，保证文案恒定 */
+abstract class BaseBlobStrategy implements BlobStrategy {
+	abstract readonly description: string;
+	/** 档位专属规则（各子类提供常量） */
+	protected abstract body(): string;
+
+	inject(): string {
+		const body = this.body();
+		return body === "" ? "" : body;
+	}
+}
+
+// ── show 轴（输出风格）─────────────────────────────────────────────────
+
+/** show=normal：不注入任何文案（基础行为） */
+class ShowNormalStrategy extends BaseBlobStrategy {
+	readonly description = "不注入输出风格（基础行为）";
+	protected body(): string {
+		return "";
+	}
+}
+
+/** show=lite：温和 —— 只提基本原则，风险最低 */
+class ShowLiteStrategy extends BaseBlobStrategy {
+	readonly description = "温和：直接作答、不重复上下文、不堆废话";
+	protected body(): string {
+		return "输出精炼：直接给结论/代码，不重复用户已提供的上下文，不为凑篇幅解释显然之事。保留：错误处理、安全提示、用户明确要求的信息。Be terse: answer directly, don't restate given context, skip obvious filler. Keep error handling, security notes, and explicitly requested info.";
+	}
+}
+
+/** show=full：均衡 —— 精简散文 + 明确边界（默认档位，文案同 v0.1） */
+class ShowFullStrategy extends BaseBlobStrategy {
+	readonly description = "均衡：代码/结论优先、冗长限行、保留关键信息（默认）";
+	protected body(): string {
+		return "输出精炼（ACTIVE EVERY RESPONSE）：\n- 先答/先代码，再至多三行说明；说明比代码长就删说明。\n- 不重复用户上下文；不奉承、不寒暄、不邀请追问。\n- 保留：错误处理、安全提示、用户明确要求的信息、必要的路径/报错原文。\n- 用户明确要求详细解释时，照给全文，不因精炼而砍。\nConcise every response: answer/code first, at most 3 lines of prose, no restating context or flattery; keep error handling, security, and explicitly requested detail. Turn off: /prompt";
+	}
+}
+
+/** show=ultra：激进 —— 电报式极简（caveman 精神，代价是观感冷硬） */
+class ShowUltraStrategy extends BaseBlobStrategy {
+	readonly description = "激进：电报式短句/列表，最大压缩散文";
+	protected body(): string {
+		return "极简电报式输出：\n- 单词/短句；避免散文、连接词、客套、复述与前缀铺垫。\n- 列表优先；不解释“为什么这样写”除非被问；不奉承不邀约。\n- 绝不砍：错误处理、安全与数据保护、用户点名要的信息、代码/路径/报错原文。\nUltra-terse telegraphic output: short statements or terse bullets, no prose, no filler, no repetition. Never trim error handling, security, or explicitly requested content.";
+	}
+}
+
+// ── write 轴（代码写量）───────────────────────────────────────────────
+
+/** write=normal：不注入（基线，不做额外约束） */
+class WriteNormalStrategy extends BaseBlobStrategy {
+	readonly description = "代码写量不约束（基线）";
+	protected body(): string {
+		return "";
+	}
+}
+
+/** write=minimal：最短可行 —— 保守版（不砍安全、只去超纲封装） */
+class WriteMinimalStrategy extends BaseBlobStrategy {
+	readonly description = "最小：给最短可行实现，注释只留必要、不做超纲抽象";
+	protected body(): string {
+		return "写最少能跑的代码：只交付问题所需的最小实现；注释仅在必要处；不做未要求的类/抽象/防御性扩展。不砍：错误处理与既有功能的完整可用性。Minimal runnable code: smallest change that does the job, no speculative abstraction, no unrequested expansion. Keep error handling and full usability.";
+	}
+}
+
+/** write=complete：完整交付 —— 可直接落地的完整实现 */
+class WriteCompleteStrategy extends BaseBlobStrategy {
+	readonly description = "完整：给可直接落地的完整实现（导入/类型/边界/错误处理）";
+	protected body(): string {
+		return "完整交付：给出可直接落地的完整实现，含必要的导入、类型、边界条件与错误处理；示例按可运行标准写全。Complete: ship a ready-to-run implementation with imports, types, edge cases and error handling.";
+	}
+}
+
+// ── do 轴（行为力度）───────────────────────────────────────────────────
+
+/** do=normal：不注入（基线） */
+class DoNormalStrategy extends BaseBlobStrategy {
+	readonly description = "行为力度不约束（基线）";
+	protected body(): string {
+		return "";
+	}
+}
+
+/** do=direct：只做被明确要求的事 */
+class DoDirectStrategy extends BaseBlobStrategy {
+	readonly description = "只做被明确要求的事：不自动扩大范围、不擅自调研";
+	protected body(): string {
+		return "只做被明确要求的事：不自动扩大范围、不读无关文件/跑无关命令、不预热后续步骤；需要延展时先问，而不是擅自做。Do only what's asked: no scope creep, no unrequested investigation or extra steps; ask before expanding.";
+	}
+}
+
+/** do=deep：深入钻研 —— 查根因与边界后再给结论 */
+class DoDeepStrategy extends BaseBlobStrategy {
+	readonly description = "深入：主动查证根因/边界（读源码/文档/历史）再给结论";
+	protected body(): string {
+		return "深入钻研：主动查证根因与边界（读源码/文档/历史），把一场调研做透再给结论；允许扩展范围以覆盖相邻隐患。Go deep: investigate root causes and edge cases before concluding; may expand scope to cover adjacent risks.";
+	}
+}
+
+/**
+ * 三轴策略注册表：轴 → 档 → 策略实例（含描述/文案）。
+ * 内部按轴分族组织；textFor 返回单块文案，compose 负责固定顺序拼接。
+ */
+export class PromptRegistry {
+	/** show 轴注册表：档位（不含 auto，auto 由选档器解析后再走这里） */
+	private readonly show: Readonly<Record<RuntimeShowMode, BlobStrategy>>;
+	/** write 轴注册表 */
+	private readonly write: Readonly<Record<WriteMode, BlobStrategy>>;
+	/** do 轴注册表 */
+	private readonly do: Readonly<Record<DoMode, BlobStrategy>>;
+
+	constructor() {
+		this.show = {
+			normal: new ShowNormalStrategy(),
+			lite: new ShowLiteStrategy(),
+			full: new ShowFullStrategy(),
+			ultra: new ShowUltraStrategy(),
+		};
+		this.write = {
+			minimal: new WriteMinimalStrategy(),
+			normal: new WriteNormalStrategy(),
+			complete: new WriteCompleteStrategy(),
+		};
+		this.do = {
+			direct: new DoDirectStrategy(),
+			normal: new DoNormalStrategy(),
+			deep: new DoDeepStrategy(),
+		};
+	}
+
+	/** show 轴单块文案；normal 返回 undefined（不注入此块） */
+	textForShow(mode: RuntimeShowMode): string | undefined {
+		return this.show[mode].inject() || undefined;
+	}
+
+	/** write 轴单块文案；normal 返回 undefined */
+	textForWrite(mode: WriteMode): string | undefined {
+		return this.write[mode].inject() || undefined;
+	}
+
+	/** do 轴单块文案；normal 返回 undefined */
+	textForDo(mode: DoMode): string | undefined {
+		return this.do[mode].inject() || undefined;
+	}
+
+	/** show 轴档位说明 */
+	describeShow(mode: RuntimeShowMode): string {
+		return this.show[mode].description;
+	}
+
+	/** write 轴档位说明 */
+	describeWrite(mode: WriteMode): string {
+		return this.write[mode].description;
+	}
+
+	/** do 轴档位说明 */
+	describeDo(mode: DoMode): string {
+		return this.do[mode].description;
+	}
+
+	/**
+	 * 组合注入文案：固定顺序拼接（show→write→do），头部一行档位标识。
+	 * 组合确定性 → 每个 (show,write,do) 三元组都是恒定字符串（缓存友好）。
+	 * 三块全空（show normal + write normal + do normal）返回 undefined（不注入）。
+	 */
+	compose(show: RuntimeShowMode, write: WriteMode, doMode: DoMode): string | undefined {
+		const blocks = [
+			this.textForShow(show),
+			this.textForWrite(write),
+			this.textForDo(doMode),
+		].filter((block): block is string => block !== undefined);
+		if (blocks.length === 0) return undefined;
+		return `[PI-PROMPT ${show}|${write}|${doMode}]\n${blocks.join("\n")}`;
+	}
+}

package/src/request.ts

@@ -0,0 +1,25 @@
+/**
+ * 请求层纯函数：before_provider_request 事件辅助。
+ *
+ * v0.3.0：max_tokens 上限钳制（默认关；config `maxTokensCap`）。
+ * payload 为 OpenAI 兼容结构，字段 `max_tokens`；
+ * 防御式：非对象/无字段/非法值一律原样返回，只在值存在且正整数时执行 Math.min。
+ */
+
+/**
+ * 将 payload 中的 max_tokens（或 max_completion_tokens）钳制到 cap。
+ * 返回新对象（引用安全）；payload 非对象/缺字段/值非法时返回原引用。
+ */
+export function clampMaxTokens(payload: unknown, cap: number | null): unknown {
+	if (cap === null || typeof payload !== "object" || payload === null) return payload;
+	const p = payload as Record<string, unknown>;
+	const result = { ...p };
+	if (typeof p.max_tokens === "number" && p.max_tokens > 0) {
+		result.max_tokens = Math.min(p.max_tokens, cap);
+	}
+	// max_completion_tokens 是 OpenAI 新字段，同样钳制以保安全
+	if (typeof p.max_completion_tokens === "number" && p.max_completion_tokens > 0) {
+		result.max_completion_tokens = Math.min(p.max_completion_tokens, cap);
+	}
+	return result;
+}

package/src/stats.ts

@@ -0,0 +1,430 @@
+/**
+ * 用量台账：turn_end 采集 token 用量 → ~/.pi/pi-prompt-usage.jsonl。
+ *
+ * 只记真实 token 数，不做权威计费 —— 钱的事交给 pi-usager（含自定义计价/峰谷）。
+ * 本模块只提供"估算节省"（保守假设，show 轴缩减率），供 /prompt usage 给用户
+ * 一个参考量级；假设全部集中在本文件（REDUCTION_BY_SHOW），诚实标注（诚实账本原则）。
+ *
+ * 台账字段（v0.2）：show/write/do 为三轴实际生效值（show 已把 auto 解析成具体档）；
+ * taskBin/decision 记录任务分桶与选档决策，供 calibration.ts 自进化拟合。
+ */
+
+import { appendFileSync, readFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { isDeepSeekPeakHours, toDate } from "./time.ts";
+import { normalizeRuntimeShow, SHOW_ICONS, type DoMode, type RuntimeShowMode, type WriteMode } from "./modes.ts";
+
+/** 台账文件路径（~/.pi/pi-prompt-usage.jsonl） */
+export const USAGE_LOG_PATH: string = join(homedir(), ".pi", "pi-prompt-usage.jsonl");
+
+/** 单轮 token 用量（口径对齐 pi 的 usage：input/output/cacheRead/cacheWrite） */
+export interface TurnUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+/** 任务粗略分桶（按用户请求 token 估算，µ 估计与校准分组用） */
+export type TaskBin = "tiny" | "short" | "mid" | "long" | "xlong";
+
+/** 一条台账记录（v0.2 字段；history 兼容 records 的 mode 字段） */
+export interface UsageRecord extends TurnUsage {
+	ts: number;
+	provider: string;
+	model: string;
+	/** show 轴实际注入档（auto 已解析）；历史记录可能只有 mode 字段 */
+	show: RuntimeShowMode;
+	/** write 轴实际档 */
+	write: WriteMode;
+	/** do 轴实际档 */
+	do: DoMode;
+	/** 任务分桶 */
+	taskBin: TaskBin;
+	/** 选档决策说明（如 "auto: µ=350,cold→ultra" 或 "manual" / "probe"） */
+	decision?: string;
+	/** 扩展实例会话号（usage 按会话展开明细用） */
+	session?: string;
+}
+
+/**
+ * show 轴缩减率先验（相对"不精简基线 normal"的保守假设）——校准数据的默认值来源。
+ * v0.2.2 别名：保留 "off" 键（=0）兜底历史台账/旧系数文件的读取。
+ */
+export const REDUCTION_BY_SHOW: Readonly<Record<RuntimeShowMode, number> & { off?: number }> = {
+	normal: 0,
+	lite: 0.08,
+	full: 0.2,
+	ultra: 0.45,
+	off: 0,
+};
+
+/** show 轴每轮注入 token 数（注入成本估算用；off 别名同 normal=0） */
+export const INJECTION_TOKENS_BY_SHOW: Readonly<Record<RuntimeShowMode, number> & { off?: number }> = {
+	normal: 0,
+	lite: 40,
+	full: 90,
+	ultra: 150,
+	off: 0,
+};
+
+/**
+ * 内置兜底价表（**非权威**）：仅在 pi-pricer 未安装 / 价格解析失败时使用。
+ *
+ * 权威价格在用户自己维护的 `~/.pi/model-pricing.json`（pi-pricer 提供）。
+ * 这里的数值只是"能让成本估算不报错"的近似先验，不保证与厂商现行价一致，
+ * 也不建模峰谷（峰谷判断见 fallbackResolver）。改动这些数字不会影响
+ * 已安装 pi-pricer 的用户。
+ */
+/** 近似输入单价（¥/百万 token）：miss 未命中 / hit 缓存命中 */
+export const INPUT_PRICE_BY_PROVIDER: Readonly<Record<string, { miss: number; hit: number }>> = {
+	deepseek: { miss: 1, hit: 0.02 },
+	glm: { miss: 0.8, hit: 0.23 },
+};
+
+/** 近似输出单价（¥/百万 token；空闲价）；权威价在 pi-pricer，峰谷见 fallbackResolver */
+export const OUTPUT_PRICE_BY_PROVIDER: Readonly<Record<string, number>> = {
+	deepseek: 4,
+	glm: 2.8,
+};
+
+/** 未知厂商兜底价（按 ¥4 输出 / miss ¥1） */
+export const FALLBACK_PRICES: { miss: number; hit: number; output: number } = { miss: 1, hit: 0.02, output: 4 };
+
+/**
+ * 计费解析器：按 (model, provider, ts) 取三类价格（等效 pi-pricer 的 ResolvedPrice）。
+ * 结构类型声明，避免对 @foolsecret/pi-pricer 的强类型绑定（可选集成）。
+ */
+export interface CostPrice {
+	inputMiss: number;
+	inputHit: number;
+	output: number;
+	isPeak?: boolean;
+}
+
+export type PricingResolver = (model: string, provider: string, timestamp?: Date | number) => CostPrice;
+
+/**
+ * 兜底解析器：pi-pricer 未安装时用内置近似价表。
+ * 峰谷：无配置源可依，只能按 DeepSeek 公开的固定时段（工作日 9-12/14-18 北京）
+ * 翻倍输出价——这是**硬编码近似**，仅在兜底路径使用；装了 pi-pricer 后峰谷
+ * 完全由用户在 model-pricing.json 里配置的 schedule 决定。
+ */
+function fallbackResolver(model: string, provider: string, timestamp?: Date | number): CostPrice {
+	const prices = INPUT_PRICE_BY_PROVIDER[provider] ?? FALLBACK_PRICES;
+	const baseOutput = OUTPUT_PRICE_BY_PROVIDER[provider] ?? FALLBACK_PRICES.output;
+	const isPeak = provider === "deepseek" && isDeepSeekPeakHours(toDate(timestamp));
+	return {
+		inputMiss: prices.miss,
+		inputHit: prices.hit,
+		output: isPeak ? baseOutput * 2 : baseOutput,
+		isPeak,
+	};
+}
+
+/**
+ * 价格来源三态：可见性用（让用户知道钱按什么价算的）。
+ * - `pi-pricer`：已加载用户 JSON 价表（权威）
+ * - `builtin`：pi-pricer 未安装，用内置近似兜底
+ * - `failed`：pi-pricer 已装但加载/解析失败，已回退兜底（附原因）
+ */
+export type PricingSource = "pi-pricer" | "builtin" | "failed";
+
+/** 当前生效的价格解析器；默认兜底，ensurePricingResolver() 调用后升级为 JSON 价表 */
+let activeResolver: PricingResolver = fallbackResolver;
+
+/** 当前价格来源状态（provider 可见性）；初始 builtin、加载成 pi-pricer、失败 failed */
+let currentSource: PricingSource = "builtin";
+
+/** 加载失败的原因（仅 source === "failed" 时有意义） */
+let lastFailure: string | undefined;
+
+/**
+ * 同步读取当前生效的价格解析器。
+ * auto/calibration 是逐回合的同步调用，不能 await —— 靠在 mount 期完成预热，
+ * 预热前读到兜底，预热后自动切到 JSON 价表，调用点无需改动。
+ */
+export function getActiveResolver(): PricingResolver {
+	return activeResolver;
+}
+
+/** 当前价格来源（含失败原因），/prompt check 与 usage 标注用 */
+export function getPricingSource(): { source: PricingSource; reason?: string } {
+	return lastFailure === undefined ? { source: currentSource } : { source: currentSource, reason: lastFailure };
+}
+
+/** 加载中的 promise（并发防抖）；null = 空闲 */
+let loading: Promise<PricingResolver> | null = null;
+
+/** 价格解析器的懒加载器（可注入便于单测兜底路径） */
+export type PricingLoader = (filePath?: string) => Promise<PricingResolver | null>;
+
+/**
+ * 默认加载器：动态 import pi-pricer 的 pricing 模块。
+ * 区分两种情况：
+ * - 模块本身 import 失败（未安装）→ 返回 null（调用方归为 builtin）
+ * - 模块在但创建解析器抛错（如 JSON 损坏）→ 向上抛（调用方归为 failed 并附原因）
+ */
+const DEFAULT_LOADER: PricingLoader = async (filePath?: string): Promise<PricingResolver | null> => {
+	let create: ((filePath?: string) => PricingResolver) | undefined;
+	// 用变量拼接说明符：pi-pricer 是可选 peer 依赖，未安装时不应让 tsc 报模块缺失
+	// （静态字面量 import() 会被 TS 在编译期解析 → 未安装环境 typecheck 失败）
+	const moduleName = "@foolsecret/pi-pricer/pricing";
+	try {
+		const mod = (await import(moduleName)) as { createPricingResolver?: (filePath?: string) => PricingResolver };
+		create = mod.createPricingResolver;
+	} catch {
+		// 未安装（或模块解析失败）：静默兜底
+		return null;
+	}
+	if (typeof create !== "function") return null;
+	// 已安装：让创建/解析错误向上传播，供 failed 状态与 /prompt check 暴露原因
+	return create(filePath);
+};
+
+/** 加载结果：拿到解析器 / 未安装（missing）/ 已装但失败（reason） */
+type LoadOutcome = { resolver: PricingResolver | null; missing?: boolean; reason?: string };
+
+/**
+ * 确保已加载 JSON 价表解析器（幂等）。
+ * 在扩展接线处调用一次；失败静默保持兜底（本地集成可选，不破坏主功能），
+ * 但会记录 source/reason 供 /prompt check 曝光。
+ */
+export async function ensurePricingResolver(
+	loader: PricingLoader = DEFAULT_LOADER,
+	filePath?: string,
+): Promise<PricingResolver> {
+	if (activeResolver !== fallbackResolver) return activeResolver;
+	if (!loading) {
+		loading = (async () => {
+			let outcome: LoadOutcome;
+			try {
+				const resolver = await loader(filePath);
+				// 约定：loader 返回 null = pi-pricer 未安装（正常情况）；抛错 = 已装但失败
+				outcome = resolver
+					? { resolver, missing: false }
+					: { resolver: null, missing: true, reason: "pi-pricer 未安装" };
+			} catch (error) {
+				// 已安装但加载/读取失败（文件损坏、模块错误等）——记为 failed 并附原因
+				outcome = { resolver: null, missing: false, reason: error instanceof Error ? error.message : String(error) };
+			}
+			if (outcome.resolver) {
+				activeResolver = outcome.resolver;
+				currentSource = "pi-pricer";
+				lastFailure = undefined;
+			} else if (outcome.missing) {
+				// 未安装：静默用兜底，不算失败（不向用户报错）
+				currentSource = "builtin";
+				lastFailure = undefined;
+			} else {
+				currentSource = "failed";
+				lastFailure = outcome.reason ?? "未知原因";
+			}
+			return activeResolver;
+		})().finally(() => {
+			loading = null;
+		});
+	}
+	return loading;
+}
+
+/** 测试专用：复位回兜底解析器与 builtin 来源，隔离 loader 注入 */
+export function resetPricingResolver(): void {
+	activeResolver = fallbackResolver;
+	currentSource = "builtin";
+	lastFailure = undefined;
+	loading = null;
+}
+
+/**
+ * 估计算法（纯函数，供单测）：只按 show 轴缩减率估节省 —— write/do 的 token
+ * 收益无法诚实量化，不编数。
+ *   savedOutput = Σ output × reduction(show)
+ *   savedCNY    = savedOutput × price(provider).output（价表优先 pi-pricer，兜底内置近似价）
+ */
+export function estimateSaved(records: readonly UsageRecord[], price: PricingResolver = activeResolver): {
+	outputTokens: number;
+	savedOutputTokens: number;
+	savedCNY: number;
+} {
+	let outputTokens = 0;
+	let savedOutputTokens = 0;
+	let savedCNY = 0;
+	for (const record of records) {
+		outputTokens += record.output;
+		const reduction = REDUCTION_BY_SHOW[record.show] ?? 0;
+		const saved = record.output * reduction;
+		savedOutputTokens += saved;
+		const p = price(record.model, record.provider, record.ts);
+		savedCNY += (saved / 1_000_000) * p.output;
+	}
+	return { outputTokens, savedOutputTokens, savedCNY };
+}
+
+/** usage 聚合行：按 天×模型 归并 */
+export interface UsageRow {
+	day: string;
+	model: string;
+	turns: number;
+	input: number;
+	cacheRead: number;
+	output: number;
+	/** 估算成本（¥；含输出与输入 miss，缓存只按 hit 价的注入成本忽略——粗口径） */
+	costCNY: number;
+	savedCNY: number;
+}
+
+/** /prompt usage 结果：聚合行 + 总览 + 按会话明细 */
+export interface UsageSummary {
+	rows: UsageRow[];
+	total: { turns: number; input: number; cacheRead: number; output: number; costCNY: number };
+	sessions: Array<{ session: string; turns: number; input: number; output: number; costCNY: number; savedCNY: number }>;
+}
+
+/**
+ * 单条记录的成本估算：升级口径 = 输入miss×miss价 + 缓存读×hit价 + 输出×输出价。
+ * 输出价由 price() 按 ts 自动含峰谷；hit 价计入后，成本更接近平台账单
+ * （旧口径忽略 cacheRead，本实现不省略）。
+ */
+export function recordCost(record: UsageRecord, price: PricingResolver = activeResolver): number {
+	const p = price(record.model, record.provider, record.ts);
+	return (record.input * p.inputMiss + record.cacheRead * p.inputHit + record.output * p.output) / 1_000_000;
+}
+
+/**
+ * 汇总台账（纯函数）：按天×模型聚合 + 按会话展开明细。
+ * 供 /prompt usage 渲染成 DeepSeek 平台风格的 token/金额表。
+ */
+export function summarizeUsage(records: readonly UsageRecord[], price: PricingResolver = activeResolver): UsageSummary {
+	const byDayModel = new Map<string, UsageRow>();
+	const bySession = new Map<string, { session: string; turns: number; input: number; output: number; costCNY: number; savedCNY: number }>();
+	let totalInput = 0;
+	let totalCache = 0;
+	let totalOutput = 0;
+	let totalTurns = 0;
+	let totalCost = 0;
+
+	for (const record of records) {
+		totalTurns += 1;
+		totalInput += record.input;
+		totalCache += record.cacheRead;
+		totalOutput += record.output;
+		const cost = recordCost(record, price);
+		totalCost += cost;
+
+		const day = new Date(record.ts).toISOString().slice(0, 10);
+		const key = `${day}|${record.model}`;
+		const row = byDayModel.get(key) ?? { day, model: record.model, turns: 0, input: 0, cacheRead: 0, output: 0, costCNY: 0, savedCNY: 0 };
+		row.turns += 1;
+		row.input += record.input;
+		row.cacheRead += record.cacheRead;
+		row.output += record.output;
+		row.costCNY += cost;
+		const reduction = REDUCTION_BY_SHOW[record.show] ?? 0;
+		row.savedCNY += ((record.output * reduction) / 1_000_000) * price(record.model, record.provider, record.ts).output;
+		byDayModel.set(key, row);
+
+		if (record.session !== undefined) {
+			const sess = bySession.get(record.session) ?? { session: record.session, turns: 0, input: 0, output: 0, costCNY: 0, savedCNY: 0 };
+			sess.turns += 1;
+			sess.input += record.input;
+			sess.output += record.output;
+			sess.costCNY += cost;
+			sess.savedCNY += ((record.output * reduction) / 1_000_000) * price(record.model, record.provider, record.ts).output;
+			bySession.set(record.session, sess);
+		}
+	}
+
+	const rows = [...byDayModel.values()].sort((a, b) => (a.day < b.day ? 1 : -1));
+	const sessions = [...bySession.values()].sort((a, b) => a.session.localeCompare(b.session));
+	return {
+		rows,
+		total: { turns: totalTurns, input: totalInput, cacheRead: totalCache, output: totalOutput, costCNY: totalCost },
+		sessions,
+	};
+}
+
+/** 台账管理器类：追加记录 + 汇总读取 + 节省估算 */
+export class UsageLedger {
+	constructor(private readonly filePath: string = USAGE_LOG_PATH) {}
+
+	/** 追写一条记录（幂等写入，无读锁需求） */
+	append(record: UsageRecord): void {
+		try {
+			mkdirSync(dirname(this.filePath), { recursive: true });
+			appendFileSync(this.filePath, JSON.stringify(record) + "\n", "utf8");
+		} catch {
+			// 写台账失败不阻断对话：静默降级
+		}
+	}
+
+	/** 读取全部历史记录（跳过损坏行）；坏行数以 integrity 形式给出 */
+	readAll(): UsageRecord[] {
+		let raw: string;
+		try {
+			raw = readFileSync(this.filePath, "utf8");
+		} catch {
+			return [];
+		}
+		const records: UsageRecord[] = [];
+		for (const line of raw.split("\n")) {
+			if (line.trim() === "") continue;
+			try {
+				const parsed = JSON.parse(line) as Partial<UsageRecord> & { mode?: string };
+				if (typeof parsed.output !== "number") continue;
+				// v0.1 记录只有 mode：迁移成 show 轴（normalizeRuntimeShow 顺带把
+				// v0.2 历史 "off" 归一为 normal）；无法识别的旧档（review 等）回退 normal
+				records.push({
+					ts: typeof parsed.ts === "number" ? parsed.ts : 0,
+					provider: typeof parsed.provider === "string" ? parsed.provider : "unknown",
+					model: typeof parsed.model === "string" ? parsed.model : "unknown",
+					show: normalizeRuntimeShow(parsed.show ?? parsed.mode) ?? "normal",
+					write: (parsed.write as WriteMode) ?? "normal",
+					do: (parsed.do as DoMode) ?? "normal",
+					taskBin: (parsed.taskBin as TaskBin) ?? "mid",
+					decision: parsed.decision,
+					session: parsed.session,
+					input: parsed.input ?? 0,
+					output: parsed.output,
+					cacheRead: parsed.cacheRead ?? 0,
+					cacheWrite: parsed.cacheWrite ?? 0,
+				});
+			} catch {
+				// 跳过无法解析的行
+			}
+		}
+		return records;
+	}
+
+	/** 台账完整性检查：总行数 / 合法行 / 损坏行（/prompt check 用） */
+	integrity(): { totalLines: number; validLines: number; damagedLines: number; filePath: string } {
+		let raw: string;
+		try {
+			raw = readFileSync(this.filePath, "utf8");
+		} catch {
+			return { totalLines: 0, validLines: 0, damagedLines: 0, filePath: this.filePath };
+		}
+		const lines = raw.split("\n").filter((line) => line.trim() !== "");
+		let valid = 0;
+		for (const line of lines) {
+			try {
+				const parsed = JSON.parse(line);
+				if (typeof parsed.output === "number") valid += 1;
+			} catch {
+				// 计入损坏
+			}
+		}
+		return { totalLines: lines.length, validLines: valid, damagedLines: lines.length - valid, filePath: this.filePath };
+	}
+}
+
+/** 状态栏/提示文案：show 档 → 带图标短标签（如 "⚡ FULL"；normal 显示 NORMAL） */
+export function showLabel(mode: RuntimeShowMode): string {
+	return `${(SHOW_ICONS[mode] ?? "")} ${mode.toUpperCase()}`.trim();
+}
+
+/** 兼容旧的 modeLabel 命名（v0.1 导出名，仅 show 轴） */
+export function modeLabel(mode: RuntimeShowMode): string {
+	return showLabel(mode);
+}