@foolsecret/pi-prompt 0.4.0 → 0.4.9

package/src/compare.ts

@@ -0,0 +1,228 @@
+/**
+ * /prompt compare：对比"注入 vs 不注入"的成本，回答"插件到底省了多少"。
+ *
+ * 诚实账本原则（本模块的核心约束）：
+ *   对比有两种口径，必须分开标注，绝不混为一谈——
+ *   1) 推算（estimate）：从当前台账反推"若无注入会怎样"，依赖 REDUCTION_BY_SHOW
+ *      先验假设（full=0.2 / ultra=0.45 …）。这是**假设**，不是实测。
+ *   2) 实测（measured）：用台账里 show=normal（不注入）的样本与注入样本对比。
+ *      这是**真实数据**，但样本非随机（normal 多来自小任务），有选择偏差。
+ * 两者都返回，由表现层分别标注；缺样本时实测列为空并给出采集指引。
+ *
+ * 口径范围：只量化 show 轴（write/do 无法诚实量化，见 AGENTS 讨论记录）。
+ *
+ * 免责（重要）：台账跨版本累积（v0.1 无 auto、v0.2 有振荡 bug、v0.4.1 才加迟滞）；
+ * 旧记录（pv=legacy）与当前行为不兼容。且 auto 选档与缓存状态强相关（非随机），
+ * 因此本模块的"实测对照"仅作参考，不是因果结论；真正结论需受控 A/B。
+ * 见 AGENTS.md 认知修正 #42/#43。
+ */
+
+import { REDUCTION_BY_SHOW, type UsageRecord } from "./stats.ts";
+import type { RuntimeShowMode } from "./modes.ts";
+import type { PricingResolver } from "./stats.ts";
+import { getActiveResolver } from "./stats.ts";
+
+/** 单个注入档的对比行 */
+export interface CompareRow {
+	/** 注入档（不含 normal，normal 是基线） */
+	mode: Exclude<RuntimeShowMode, "normal">;
+	/** 该档实际产生的输出 token（台账实测） */
+	actualOutput: number;
+	/** 该档的记录数 */
+	turns: number;
+	/** 推算的"若无注入"输出（actualOutput / (1 − reduction)） */
+	estimatedBaselineOutput: number;
+	/** 推算省下的输出 token */
+	estimatedSavedTokens: number;
+	/** 推算省下的钱（¥） */
+	estimatedSavedCNY: number;
+}
+
+/** 实测对照（仅当有可比样本时给出） */
+export interface MeasuredContrast {
+	/** 不注入样本数（show=normal） */
+	normalTurns: number;
+	/** 不注入样本的中位输出 token */
+	normalMedianOutput: number;
+	/** 注入样本数（show≠normal） */
+	injectedTurns: number;
+	/** 注入样本的中位输出 token */
+	injectedMedianOutput: number;
+	/** 实测缩减率 = 1 − injected/normal（中位数口径） */
+	measuredReduction: number;
+	/**
+	 * 偏差警告：样本非随机（normal 样本多来自小任务），
+	 * 直接比较可能高估或低估。有值即表示应谨慎解读。
+	 */
+	biasNote?: string;
+}
+
+/** /prompt compare 的完整结果 */
+export interface CompareResult {
+	/** 实际花费（¥，读时按当前价表算） */
+	actualCostCNY: number;
+	/** 推算总省（¥） */
+	estimatedSavedCNY: number;
+	/** 推算总省（输出 token） */
+	estimatedSavedTokens: number;
+	/** 按档拆分的推算行 */
+	rows: CompareRow[];
+	/** 实测对照（样本不足时为 undefined） */
+	measured?: MeasuredContrast;
+	/** 是否有任何记录 */
+	hasData: boolean;
+}
+
+/** 中位数（偶数取中间两数均值；空数组返回 0） */
+function median(values: readonly number[]): number {
+	if (values.length === 0) return 0;
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+/** 归一化 show 档（历史 off 视为 normal；未知回退 normal） */
+function runtimeShow(record: UsageRecord): RuntimeShowMode {
+	const show = record.show as string;
+	if (show === "off") return "normal";
+	return show === "normal" || show === "lite" || show === "full" || show === "ultra" ? show : "normal";
+}
+
+/** 缩减率先验：未知档回退 0（不虚报） */
+function reductionOf(mode: RuntimeShowMode): number {
+	return REDUCTION_BY_SHOW[mode] ?? 0;
+}
+
+/**
+ * 对比注入与不注入（纯函数）。
+ * @param records 台账记录
+ * @param price 价格解析器（默认读当前 activeResolver，与 /prompt usage 同源）
+ */
+export function compareInjection(
+	records: readonly UsageRecord[],
+	price: PricingResolver = getActiveResolver(),
+): CompareResult {
+	if (records.length === 0) {
+		return { actualCostCNY: 0, estimatedSavedCNY: 0, estimatedSavedTokens: 0, rows: [], hasData: false };
+	}
+
+	// 按档聚合输出 token（推算用）
+	const byMode = new Map<RuntimeShowMode, { output: number; turns: number; costCNY: number }>();
+	// 实测对照分两组收集（normal vs 注入），逐条保留输出量算中位数
+	const normalOutputs: number[] = [];
+	const injectedOutputs: number[] = [];
+	let actualCostCNY = 0;
+
+	for (const record of records) {
+		const mode = runtimeShow(record);
+		const p = price(record.model, record.provider, record.ts);
+		const cost = (record.input * p.inputMiss + record.cacheRead * p.inputHit + record.output * p.output) / 1e6;
+		actualCostCNY += cost;
+
+		const agg = byMode.get(mode) ?? { output: 0, turns: 0, costCNY: 0 };
+		agg.output += record.output;
+		agg.turns += 1;
+		agg.costCNY += cost;
+		byMode.set(mode, agg);
+
+		if (mode === "normal") normalOutputs.push(record.output);
+		else injectedOutputs.push(record.output);
+	}
+
+	// 按档推算："若无注入"输出 = 实际 / (1 − reduction)
+	const rows: CompareRow[] = [];
+	let estimatedSavedTokens = 0;
+	let estimatedSavedCNY = 0;
+	for (const mode of ["lite", "full", "ultra"] as const) {
+		const agg = byMode.get(mode);
+		if (!agg || agg.turns === 0) continue;
+		const reduction = reductionOf(mode);
+		if (reduction <= 0 || reduction >= 1) continue;
+		const baseline = agg.output / (1 - reduction);
+		const savedTokens = baseline - agg.output;
+		// 输出单价：按该档记录的均价近似（用实际成本/实际输出反推平均输出单价）
+		const avgOutputPrice = agg.output > 0 ? (agg.costCNY / agg.output) * 1e6 : 0;
+		const savedCNY = (savedTokens / 1e6) * avgOutputPrice;
+		estimatedSavedTokens += savedTokens;
+		estimatedSavedCNY += savedCNY;
+		rows.push({
+			mode,
+			actualOutput: agg.output,
+			turns: agg.turns,
+			estimatedBaselineOutput: baseline,
+			estimatedSavedTokens: savedTokens,
+			estimatedSavedCNY: savedCNY,
+		});
+	}
+
+	// 实测对照：需两组都有足够样本（阈值对齐 calibration：对照组 ≥5）
+	const MIN_SAMPLES = 5;
+	let measured: MeasuredContrast | undefined;
+	if (normalOutputs.length >= MIN_SAMPLES && injectedOutputs.length >= MIN_SAMPLES) {
+		const normalMedian = median(normalOutputs);
+		const injectedMedian = median(injectedOutputs);
+		measured = {
+			normalTurns: normalOutputs.length,
+			normalMedianOutput: normalMedian,
+			injectedTurns: injectedOutputs.length,
+			injectedMedianOutput: injectedMedian,
+			measuredReduction: normalMedian > 0 ? 1 - injectedMedian / normalMedian : 0,
+			biasNote:
+				"样本非随机：不注入样本多来自小任务，与注入样本任务分布不同，实测缩减率仅供参考",
+		};
+	}
+
+	return { actualCostCNY, estimatedSavedCNY, estimatedSavedTokens, rows, measured, hasData: true };
+}
+
+/** 人读金额（¥，保留 4 位；0 显示 0） */
+export function fmtCNY(value: number): string {
+	return `¥${value.toFixed(4)}`;
+}
+
+/** 人读 token（千分位） */
+export function fmtTok(value: number): string {
+	return Math.round(value).toLocaleString("en-US");
+}
+
+/**
+ * 渲染纯文本对比表（headless 与 TUI 共用；表现层只做展示，不做计算）。
+ * 诚实标注：推算列标"估算（假设）"，实测列标"实测（N 样本）"。
+ */
+export function renderCompare(result: CompareResult): string {
+	if (!result.hasData) return "pi-prompt 台账为空，暂无可对比数据。";
+
+	const lines: string[] = ["pi-prompt 对比：注入 vs 不注入（只量化 show 轴）"];
+	lines.push(`实际花费: ${fmtCNY(result.actualCostCNY)}`);
+	lines.push(
+		`省下（估算）: ${fmtCNY(result.estimatedSavedCNY)} · 输出 ${fmtTok(result.estimatedSavedTokens)} token（基于先验缩减率，非实测）`,
+	);
+	lines.push("");
+	lines.push("按档（估算）:");
+	lines.push("  档位  |  实际输出  |  若无注入  |  省下 token  |  省下");
+	if (result.rows.length === 0) {
+		lines.push("  （无 lite/full/ultra 注入记录）");
+	}
+	for (const row of result.rows) {
+		lines.push(
+			`  ${row.mode.padEnd(5)} | ${fmtTok(row.actualOutput).padStart(9)} | ${fmtTok(row.estimatedBaselineOutput).padStart(9)} | ${fmtTok(row.estimatedSavedTokens).padStart(11)} | ${fmtCNY(row.estimatedSavedCNY)}`,
+		);
+	}
+
+	lines.push("");
+	if (result.measured) {
+		const m = result.measured;
+		lines.push("实测对照（不注入 vs 注入）:");
+		lines.push(`  不注入中位输出: ${fmtTok(m.normalMedianOutput)}（${m.normalTurns} 样本）`);
+		lines.push(`  注入中位输出:   ${fmtTok(m.injectedMedianOutput)}（${m.injectedTurns} 样本）`);
+		lines.push(`  实测缩减率: ${(m.measuredReduction * 100).toFixed(1)}%`);
+		if (m.biasNote) lines.push(`  ⚠ ${m.biasNote}`);
+		lines.push("  ⚠ 非因果：auto 选档与缓存状态相关，且台账含旧版本（pv=legacy）记录；");
+		lines.push("    精确结论需受控 A/B（同批任务随机关/开注入）。");
+	} else {
+		lines.push("实测对照: 样本不足（需不注入 ≥5 且注入 ≥5）");
+		lines.push("  跑 /prompt check --calibrate 采集不注入对照组，或开启 autoSample 自动采样");
+	}
+
+	return lines.join("\n");
+}

package/src/config.ts

@@ -55,9 +55,46 @@ export interface PromptConfigFile {
 	autoSampleInterval?: number;
 	/** 当日抽样上限（默认 3） */
 	autoSampleMaxPerDay?: number;
+	/** auto 选档迟滞比例（默认 0.5；0 关闭迟滞=旧的无状态 argmax） */
+	hysteresis?: number;
+	/** 自动上下文压缩（默认关；true 开启） */
+	autoCompact?: boolean;
+	/** 自动压缩的绝对上限 token（缺省 400000）；触发时取 min(此值, percent×窗口) */
+	autoCompactMaxTokens?: number;
+	/** 自动压缩的窗口百分比上限（缺省 0.6） */
+	autoCompactPercent?: number;
+	/** 会话至少跑多少轮才允许自动压（缺省 50；短会话压不划算） */
+	autoCompactMinTurns?: number;
+	/**
+	 * 追加给 pi 压缩的指令（引导摘要保留“工作状态”）。
+	 * 空串 = 不追加（回到 pi 原生行为）。
+	 */
+	compactInstructions?: string;
+	/** 工具输出截断（默认关；对象形式开启并分层） */
+	toolOutput?: ToolOutputConfig;
 	perProvider?: Record<string, string | ProviderAxes>;
 }
 
+/** 工具输出截断配置（字节；0 = 不截该工具） */
+export interface ToolOutputConfig {
+	/** 总开关（默认 false） */
+	enabled?: boolean;
+	/** 兵底上限（默认 8192） */
+	default?: number;
+	/** 按工具覆盖上限 */
+	grep?: number;
+	read?: number;
+	bash?: number;
+}
+
+/**
+ * 内置压缩指令（用户可用配置/env 覆盖，显式空串=不追加）。
+ * 为何需要：pi 的摘要器倾向“总结历史对话”，压缩后会丢失“当前在干什么”，
+ * 导致后续回合重新勘测、重复劳动。这条指令引导它保留工作状态。
+ */
+export const DEFAULT_COMPACT_INSTRUCTIONS =
+	"摘要时请额外保留：当前正在进行的任务、已完成到哪一步、下一步计划、未解决的阻塞。不要只总结历史对话，要保留工作状态。";
+
 /** env 布尔开关解析：值存在且非空/0/false/no 视为真；未设置返回 undefined */
 function envTruthy(env: NodeJS.ProcessEnv | undefined, name: string): boolean | undefined {
 	const value = env?.[name];
@@ -90,7 +127,13 @@ export class PromptConfigManager {
 		this.loaded = config !== undefined;
 	}
 
-	/** 惰性读档（strip BOM；损坏回退空配置；v0.1 defaultMode → defaultShow） */
+	/**
+	 * 惰性读档（strip BOM；损坏回退空配置；v0.1 defaultMode → defaultShow）。
+	 *
+	 * 注意：必须原样保留**所有**已知字段——早期版本只白名单了 6 个，导致
+	 * peakUpgrade / maxTokensCap / autoSample / hysteresis / autoCompact /
+	 * toolOutput 等从配置文件写入后重读会被静默丢弃（只有 env 与内存注入生效）。
+	 */
 	private load(): PromptConfigFile {
 		if (this.loaded) return this.config;
 		this.loaded = true;
@@ -98,6 +141,7 @@ export class PromptConfigManager {
 			const raw = readFileSync(this.configPath, "utf8").replace(/^\uFEFF/, "");
 			const parsed = JSON.parse(raw) as (Partial<PromptConfigFile> & { defaultMode?: unknown }) | null;
 			this.config = {
+				...parsed,
 				defaultShow:
 					typeof parsed?.defaultShow === "string"
 						? parsed.defaultShow
@@ -237,6 +281,104 @@ export class PromptConfigManager {
 		return typeof v === "number" && v >= 1 ? v : 3;
 	}
 
+	/**
+	 * auto 选档迟滞比例（默认 0.5；0 = 关闭迟滞，退回旧的无状态 argmax）。
+	 * env PI_PROMPT_HYSTERESIS 优先（非负数字）；其次配置 hysteresis。
+	 * 语义：新最优档净收益必须比上一轮档位高出 bestNet×比例才换档。
+	 * P0 实测：注入在系统提示中段，换档浪费 ∝ 前缀大小，故要"值得"才换。
+	 */
+	hysteresis(): number {
+		const envRaw = this.env?.PI_PROMPT_HYSTERESIS?.trim();
+		if (envRaw !== undefined && envRaw !== "" && /^\d+(\.\d+)?$/.test(envRaw)) return Number(envRaw);
+		const v = this.load().hysteresis;
+		return typeof v === "number" && v >= 0 ? v : 0.5;
+	}
+
+	/**
+	 * 自动上下文压缩是否开启（默认**关**）。
+	 * 为何默认关：压缩是"投资"——DeepSeek 缓存读极便宜（0.02 元/百万），
+	 * 重发旧上下文几乎免费，而压缩需整段重算（价差 0.98）。
+	 * 算下：剩 ≤30 轮时压缩**永远不划算**；只有长会话才值。
+	 * env PI_PROMPT_AUTO_COMPACT=true/false 优先；其次配置 autoCompact。
+	 */
+	isAutoCompact(): boolean {
+		const env = envTruthy(this.env, "PI_PROMPT_AUTO_COMPACT");
+		if (env !== undefined) return env;
+		return this.load().autoCompact === true;
+	}
+
+	/** 自动压缩的绝对上限 token（默认 400000；防 1M 窗口下比例阈值形同虚设） */
+	autoCompactMaxTokens(): number {
+		const envRaw = this.env?.PI_PROMPT_AUTO_COMPACT_MAX_TOKENS?.trim();
+		if (envRaw !== undefined && envRaw !== "" && /^\d+$/.test(envRaw)) return Number(envRaw);
+		const v = this.load().autoCompactMaxTokens;
+		return typeof v === "number" && v > 0 ? v : 400_000;
+	}
+
+	/** 自动压缩的窗口百分比上限（默认 0.6；与绝对上限取小） */
+	autoCompactPercent(): number {
+		const envRaw = this.env?.PI_PROMPT_AUTO_COMPACT_PERCENT?.trim();
+		if (envRaw !== undefined && envRaw !== "" && /^\d+(\.\d+)?$/.test(envRaw)) {
+			const v = Number(envRaw);
+			return v > 0 && v < 1 ? v : 0.6;
+		}
+		const v = this.load().autoCompactPercent;
+		return typeof v === "number" && v > 0 && v < 1 ? v : 0.6;
+	}
+
+	/** 会话至少跑多少轮才允许自动压（默认 50；短会话压不划算） */
+	autoCompactMinTurns(): number {
+		const envRaw = this.env?.PI_PROMPT_AUTO_COMPACT_MIN_TURNS?.trim();
+		if (envRaw !== undefined && envRaw !== "" && /^\d+$/.test(envRaw)) return Number(envRaw);
+		const v = this.load().autoCompactMinTurns;
+		return typeof v === "number" && v >= 0 ? v : 50;
+	}
+
+	/**
+	 * 追加给 pi 压缩的指令（引导摘要保留“工作状态”）。
+	 * 优先级：env PI_PROMPT_COMPACT_INSTRUCTIONS > 配置 compactInstructions > 内置默认。
+	 * 显式空串（env/配置）= 不追加，回到 pi 原生行为。
+	 */
+	compactInstructions(): string {
+		const envRaw = this.env?.PI_PROMPT_COMPACT_INSTRUCTIONS;
+		if (envRaw !== undefined) return envRaw.trim();
+		const v = this.load().compactInstructions;
+		if (typeof v === "string") return v.trim();
+		return DEFAULT_COMPACT_INSTRUCTIONS;
+	}
+
+	/**
+	 * 工具输出截断是否开启（默认 **关**）。
+	 * 为何默认关：pi 自己已把工具输出截到 50KB（read/grep/bash/find）。
+	 * 本项是“更激进的上限”，会改变模型看到的内容（行为风险）——由用户显式开。
+	 * env PI_PROMPT_TOOL_OUTPUT=true/false 优先；其次配置 toolOutput.enabled。
+	 */
+	isToolOutputCap(): boolean {
+		const env = envTruthy(this.env, "PI_PROMPT_TOOL_OUTPUT");
+		if (env !== undefined) return env;
+		return this.load().toolOutput?.enabled === true;
+	}
+
+	/**
+	 * 取某工具的输出上限（字节；0 = 该工具不截）。
+	 * 优先级：env PI_TOOL_CAP_<TOOL> > 配置 toolOutput.<tool> > 配置 default > 内置默认。
+	 * 内置默认：grep/bash/default 8192（均输出小、信息冗余高）；
+	 * read 16384（模型主动要看，砍很会引发重读 → 反增输出成本）。
+	 */
+	toolOutputCap(tool: "grep" | "read" | "bash" | "default"): number {
+		const envName = `PI_PROMPT_TOOL_CAP_${tool.toUpperCase()}`;
+		const envRaw = this.env?.[envName]?.trim();
+		if (envRaw !== undefined && envRaw !== "" && /^\d+$/.test(envRaw)) return Number(envRaw);
+		const cfg = this.load().toolOutput;
+		const v = cfg?.[tool];
+		if (typeof v === "number" && v >= 0) return v;
+		if (tool !== "default") {
+			const d = cfg?.default;
+			if (typeof d === "number" && d >= 0) return d;
+		}
+		return tool === "read" ? 16_384 : 8_192;
+	}
+
 	/** 持久化某轴默认档（按轴校验；非法拒绝返回 false） */
 	writeDefaultAxis(axis: "show" | "write" | "do", value: string): boolean {
 		switch (axis) {
@@ -258,6 +400,41 @@ export class PromptConfigManager {
 		}
 	}
 
+	/** 持久化布尔开关（合并写，不丢未展示字段） */
+	writeFlag(name: "peakUpgrade" | "quietStartup" | "hideStatus" | "autoSample" | "autoCompact", value: boolean): boolean {
+		return this.persist({ [name]: value } as Partial<PromptConfigFile>);
+	}
+
+	/**
+	 * 持久化数值参数（校验：非负；percent 类必须 0~1）。
+	 * @param name 顶层数值字段名
+	 * @param value 数值；非法返回 false
+	 */
+	writeNumber(
+		name: "maxTokensCap" | "autoSampleInterval" | "autoSampleMaxPerDay" | "hysteresis" | "autoCompactMaxTokens" | "autoCompactPercent" | "autoCompactMinTurns",
+		value: number,
+	): boolean {
+		if (!Number.isFinite(value) || value < 0) return false;
+		if (name === "autoCompactPercent" && value >= 1) return false;
+		return this.persist({ [name]: value } as Partial<PromptConfigFile>);
+	}
+
+	/** 持久化某工具输出上限（合并写；0 = 该工具不截） */
+	writeToolOutput(patch: Partial<ToolOutputConfig>): boolean {
+		const merged: ToolOutputConfig = { ...this.load().toolOutput, ...patch };
+		return this.persist({ toolOutput: merged });
+	}
+
+	/** 当前内存/磁盘配置的原始快照（供草稿层深拷贝） */
+	rawSnapshot(): PromptConfigFile {
+		return structuredClone(this.load());
+	}
+
+	/** 合并写任意配置字段（草稿层 save 用；合并写保证不丢未展示字段） */
+	persistMerged(patch: Partial<PromptConfigFile>): boolean {
+		return this.persist(patch);
+	}
+
 	/** 写盘（mkdirSync 防御目录缺失）：合并当前磁盘内容（防多写互相覆盖）；失败返回 false */
 	private persist(patch: Partial<PromptConfigFile>): boolean {
 		try {

package/src/context.ts

@@ -0,0 +1,136 @@
+/**
+ * 自动上下文压缩决策（纯函数，可单测）。
+ *
+ * 背景（勘测 2026-09-12）：
+ *   - pi 自带的压缩阈值为 `contextWindow − reserveTokens`。对 1M 窗口模型
+ *     （本用户的 deepseek-v4-pro / glm-5.3-flash 均为 1,000,000）== 983,616 token，
+ *     正常使用下**永远不会触发** → 上下文一直涨（实测会话峰值 33 万仍在涨）。
+ *   - 但**压缩不是免费的**：压缩会整段重算（miss 价），而不压缩只是每轮付
+ *     缓存读价（hit 价）。以 DeepSeek 为例 miss=1 / hit=0.02（元/百万），
+ *     价差 0.98 —— 压缩一次 ≈ 重发 48 次的缓存读成本。
+ *
+ * 平衡点（成本数学）：设当前上下文 T、压缩后降到 K、还会走 N 轮——
+ *   不压：N × T × hit
+ *   压：  T × (miss − hit) + N × K × hit
+ *   两者相等 → T_be = N × K × hit / (N × hit − (miss − hit))
+ *   DeepSeek（hit=0.02, gap=0.98）下 N≤30 无解（永远不划算）；
+ *   N=100 需 T>3.9 万；N=200 需 T>2.6 万。
+ *
+ * 策略：**三重条件**（不是单一阈值）——
+ *   1) 绝对上限：`min(autoCompactMaxTokens, percent × contextWindow)` 以上必压（防失控）；
+ *   2) 会话够长：已跑 ≥ autoCompactMinTurns 轮（说明是长会话，还会继续）；
+ *   3) 成本划算：预期省 > 0（用真实价表算）。
+ * 三者同时满足才压。
+ */
+
+/** 压缩决策所需输入 */
+export interface CompactDecisionInput {
+	/** 当前上下文 token（getContextUsage().tokens；null = 未知，不压） */
+	tokens: number | null;
+	/** 模型上下文窗口 */
+	contextWindow: number;
+	/** 本会话已跑轮数 */
+	turns: number;
+	/** 输入 miss 价（¥/百万） */
+	inputMissPrice: number;
+	/** 输入 hit 价（¥/百万） */
+	inputHitPrice: number;
+	/** 压缩后预计降到多少 token（pi 的 keepRecentTokens，默认 20000） */
+	keepRecentTokens?: number;
+	/** 绝对上限 token */
+	maxTokens: number;
+	/** 窗口百分比上限（0~1） */
+	percent: number;
+	/** 会话最少轮数 */
+	minTurns: number;
+	/** 距离上次压缩的轮数（冷却；< cooldown 则跳过） */
+	turnsSinceLastCompact?: number;
+	/** 冷却轮数（默认 10） */
+	compactCooldown?: number;
+	/** 预估本次会话还会走多少轮（用户无法预知；用会话平均轮数近似，默认 100） */
+	expectedRemainingTurns?: number;
+}
+
+/** 压缩决策结果（含归因，便于 /prompt check 显示"为何压/不压"） */
+export interface CompactDecision {
+	/** 是否应触发压缩 */
+	should: boolean;
+	/** 不压的原因（should=false 时有值） */
+	reason?: "unknown-usage" | "below-threshold" | "too-few-turns" | "cooldown" | "not-worth-it";
+	/** 触发阈值（min(绝对, 比例×窗口)） */
+	threshold: number;
+	/** 机会成本比较：省下的钱（¥；负=压缩亏） */
+	netSavingCNY: number;
+}
+
+/** 默认压缩后保留量（对齐 pi 的 keepRecentTokens） */
+const DEFAULT_KEEP = 20_000;
+
+/** 默认冷却轮数 */
+const DEFAULT_COOLDOWN = 10;
+
+/** 默认预期剩余轮数（保守：不清高估收益） */
+const DEFAULT_REMAINING = 100;
+
+/**
+ * 成本比较（纯函数）：压缩 vs 不压缩的**预期差**（¥；正 = 压缩更省）。
+ *   不压：remaining × T × hit
+ *   压：  T × (miss − hit) + remaining × K × hit
+ * 注意：这里比的是"从现在到会话结束"，不含已花的部分。
+ */
+export function compactionSaving(
+	tokens: number,
+	contextWindow: number,
+	inputMissPrice: number,
+	inputHitPrice: number,
+	keepRecentTokens: number = DEFAULT_KEEP,
+	expectedRemainingTurns: number = DEFAULT_REMAINING,
+): number {
+	const gap = Math.max(0, inputMissPrice - inputHitPrice);
+	const noCompact = (expectedRemainingTurns * tokens * inputHitPrice) / 1e6;
+	const compact = (tokens * gap + expectedRemainingTurns * keepRecentTokens * inputHitPrice) / 1e6;
+	return noCompact - compact;
+}
+
+/**
+ * 自动压缩决策（纯函数）。
+ * @param input 见 CompactDecisionInput
+ */
+export function decideCompact(input: CompactDecisionInput): CompactDecision {
+	const threshold = Math.min(input.maxTokens, input.percent * input.contextWindow);
+	const keep = input.keepRecentTokens ?? DEFAULT_KEEP;
+	const cooldown = input.compactCooldown ?? DEFAULT_COOLDOWN;
+	const remaining = input.expectedRemainingTurns ?? DEFAULT_REMAINING;
+
+	// 1) 用量未知（压缩后/首帧）不动
+	if (input.tokens === null || input.tokens <= 0) {
+		return { should: false, reason: "unknown-usage", threshold, netSavingCNY: 0 };
+	}
+	// 2) 成本划算（先算，供返回）
+	const netSaving = compactionSaving(
+		input.tokens,
+		input.contextWindow,
+		input.inputMissPrice,
+		input.inputHitPrice,
+		keep,
+		remaining,
+	);
+	// 3) 低于阈值不压
+	if (input.tokens < threshold) {
+		return { should: false, reason: "below-threshold", threshold, netSavingCNY: netSaving };
+	}
+	// 4) 会话太短不压（短会话压缩纯亏）
+	if (input.turns < input.minTurns) {
+		return { should: false, reason: "too-few-turns", threshold, netSavingCNY: netSaving };
+	}
+	// 5) 冷却中不压（防抖动）
+	const since = input.turnsSinceLastCompact ?? Number.POSITIVE_INFINITY;
+	if (since < cooldown) {
+		return { should: false, reason: "cooldown", threshold, netSavingCNY: netSaving };
+	}
+	// 6) 成本不划算不压（关键：缓存太便宜时压缩反而亏）
+	if (netSaving <= 0) {
+		return { should: false, reason: "not-worth-it", threshold, netSavingCNY: netSaving };
+	}
+	return { should: true, threshold, netSavingCNY: netSaving };
+}