@foolsecret/pi-prompt 0.4.0

package/src/prompt-extension.ts

@@ -0,0 +1,623 @@
+/**
+ * pi-prompt 扩展主类：把策略/配置/台账/校准/选档器装配到 pi 事件与命令上。
+ *
+ * 职责划分（OOP）：
+ *   - PromptRegistry       三轴注入组合（恒定文案）
+ *   - PromptConfigManager  配置解析/持久化（+ v0.1 迁移）
+ *   - UsageLedger          用量台账
+ *   - CalibrationManager   自进化系数（惰性更新）
+ *   - AutoTierChooser      show=auto 时的运行时选档（成本函数）
+ *   - 本类                 事件接线 + 会话状态 + 命令分发 + 探针校准
+ *
+ * 档位解析：会话显式设档优先，否则 perProvider → env → 配置默认（show 还可 auto）。
+ */
+
+import { parsePromptCommand, type AxisName } from "./command.ts";
+import { PromptConfigManager } from "./config.ts";
+import { CalibrationManager, pricingFor } from "./calibration.ts";
+import { AutoTierChooser, beijingDate, estimateMuFromInput, taskBinForInput } from "./auto.ts";
+import { clampMaxTokens } from "./request.ts";
+import { PromptConfigDrawer } from "./ui.ts";
+import type { TaskBin } from "./stats.ts";
+import {
+	isDeactivationCommand,
+	normalizeDoMode,
+	normalizeShowMode,
+	normalizeWriteMode,
+	type DoMode,
+	type RuntimeShowMode,
+	type ShowMode,
+	type WriteMode,
+} from "./modes.ts";
+import { PromptRegistry } from "./prompts.ts";
+import { REDUCTION_BY_SHOW, UsageLedger, estimateSaved, ensurePricingResolver, getPricingSource, summarizeUsage, showLabel } from "./stats.ts";
+import { formatTokens } from "./format.ts";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+/**
+ * 会话条目的自定义载荷结构（三轴持久化 + 清除）
+ */
+interface PromptAxesEntry {
+	type: string;
+	customType: string;
+	data?: {
+		cleared?: boolean;
+		show?: string;
+		write?: string;
+		do?: string;
+		/** v0.1 遗留 prompt-mode 条目的旧字段（show 旧称 mode） */
+		mode?: string;
+	};
+}
+
+/**
+ * 状态栏灰化 ANSI：pi 的内置 footer（pwd/token 统计）是 dimGray，而扩展 status
+ * 文本默认原色渲染会偏亮；用 SGR dim 包一层与 pi-tui 内部 dim 用法（\x1b[2m…\x1b[22m）
+ * 对齐，在任何终端主题下都呈现"默认灰"。
+ */
+const DIM_ON = "\x1b[2m";
+const DIM_OFF = "\x1b[22m";
+
+/** 单轮 token 用量的真实形状（pi 的 usage 字段够用即可，超出忽略） */
+interface RawUsage {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+}
+
+/** 会话状态引用（status 刷新可能来自命令或事件） */
+type AnyContext = ExtensionContext | ExtensionCommandContext;
+
+/** 校准探针数量（/prompt check --calibrate 跑几轮对照组） */
+const PROBE_TURNS: number = 3;
+
+/** 扩展主类：装配事件与命令 */
+export class PromptExtension {
+	/** 会话显式三轴；null=未设（走自动解析）；{cleared} 已重置 */
+	private sessionAxes: { show?: ShowMode; write?: WriteMode; do?: DoMode } | null = null;
+	/** 状态栏是否隐藏（可配置，隐藏不关规则） */
+	private hideStatus = false;
+	/** 最近一次渲染上下文 */
+	private lastCtx: AnyContext | undefined;
+	/** pi API 句柄 */
+	private pi: ExtensionAPI | undefined;
+	/** 本次扩展实例会话号（usage 按会话展开明细） */
+	private readonly runId: string;
+	/** 最近一次用户消息的粗 token 估算（µ 估计输入） */
+	private lastUserTokens = 120;
+	/** 上一回合是否命中缓存（auto 成本函数输入） */
+	private cacheState = false;
+	/** 价格来源提醒是否已发过（每会话一次，避免刷屏） */
+	private pricingHintShown = false;
+	/** 最近一次 before_agent_start 的实际解析结果（台账记录用） */
+	private lastResolved: { show: RuntimeShowMode; write: WriteMode; do: DoMode; taskBin: TaskBin; decision: string } | null = null;
+	/** 剩余探针回合数（>0 时本轮不注入，采集对照组） */
+	private probeTurnsLeft = 0;
+	/** 探针采集完成后待重拟合标记 */
+	private pendingRecalibrate = false;
+	/** auto 低频抽样状态（默认关；见 config autoSample） */
+	private turnsSinceSample = 0;
+	private todaySampleDay = "";   // 北京时区 YYYY-MM-DD
+	private todaySampleCount = 0;
+
+	/** 三轴注入组合器 */
+	private readonly registry: PromptRegistry;
+	/** 配置管理器 */
+	private readonly config: PromptConfigManager;
+	/** 用量台账 */
+	private readonly ledger: UsageLedger;
+	/** 校准管理器（自进化） */
+	private readonly calibration: CalibrationManager;
+	/** show=auto 选档器 */
+	private readonly chooser: AutoTierChooser;
+	/** 三轴设置抽屉（/settings 同款交互，见 DESIGN.md） */
+	private readonly drawer: PromptConfigDrawer;
+
+	/** 依赖注入构造：测试可替换 config/registry/ledger/calibration/chooser */
+	constructor(
+		config?: PromptConfigManager,
+		registry?: PromptRegistry,
+		ledger?: UsageLedger,
+		calibration?: CalibrationManager,
+		chooser?: AutoTierChooser,
+	) {
+		this.config = config ?? new PromptConfigManager();
+		this.registry = registry ?? new PromptRegistry();
+		this.ledger = ledger ?? new UsageLedger();
+		this.calibration = calibration ?? new CalibrationManager();
+		this.chooser =
+			chooser ??
+			new AutoTierChooser(
+				(provider, model, ts) => pricingFor(provider, model, ts),
+				(provider, bin, mode) => this.calibration.reductionFor(provider, bin, mode) ?? REDUCTION_BY_SHOW[mode],
+				(provider, bin) => this.calibration.sampleCountFor(provider, bin),
+			);
+		this.runId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
+		this.drawer = new PromptConfigDrawer(
+			() => {
+				const provider = this.lastCtx?.model?.provider;
+				return {
+					session: {
+						show: this.effectiveShow(provider),
+						write: this.effectiveWrite(provider),
+						do: this.effectiveDo(provider),
+					},
+					defaults: this.config.getDefaults(),
+				};
+			},
+			{
+				onSessionAxisChange: (axis, value) => {
+					if (this.lastCtx) this.applyAxis(axis, value as ShowMode | WriteMode | DoMode, this.lastCtx);
+				},
+				onDefaultAxisChange: (axis, value) => {
+					const ok = this.config.writeDefaultAxis(axis, value);
+					if (this.lastCtx) {
+						this.lastCtx.ui.notify(ok ? `默认 ${axis}=${value} 已持久化` : `默认 ${axis}#${value} 写入失败`, ok ? "info" : "error");
+						this.syncStatus(this.lastCtx);
+					}
+				},
+			},
+			(context) => {
+				// 无 TUI（非交互模式）：回退为文字状态
+				this.showStatus(context as AnyContext);
+			},
+		);
+	}
+
+	// ── 档位解析 ────────────────────────────────────────────────────────
+
+	/** show 轴生效档位（会话显式 > perProvider/env/默认；可为 auto） */
+	private effectiveShow(provider: string | undefined): ShowMode {
+		return this.sessionAxes?.show ?? this.config.showForProvider(provider);
+	}
+
+	/** write 轴生效档位 */
+	private effectiveWrite(provider: string | undefined): WriteMode {
+		return this.sessionAxes?.write ?? this.config.writeForProvider(provider);
+	}
+
+	/** do 轴生效档位 */
+	private effectiveDo(provider: string | undefined): DoMode {
+		return this.sessionAxes?.do ?? this.config.doForProvider(provider);
+	}
+
+	/** 读取会话持久化的三轴（末尾优先；prompt-axes 优先于旧 prompt-mode） */
+	private readSessionAxes(ctx: ExtensionContext): { show?: ShowMode; write?: WriteMode; do?: DoMode } | null {
+		const entries = (ctx.sessionManager.getEntries() as PromptAxesEntry[]) ?? [];
+		let legacyShow: ShowMode | null = null;
+		for (let i = entries.length - 1; i >= 0; i -= 1) {
+			const entry = entries[i];
+			if (entry?.type !== "custom") continue;
+			if (entry.customType === "prompt-axes") {
+				const data = entry.data;
+				// 最近一条 prompt-axes 决定会话覆盖：cleared → 无覆盖
+				if (data?.cleared === true) return null;
+				const axes: { show?: ShowMode; write?: WriteMode; do?: DoMode } = {};
+				const show = normalizeShowMode(data?.show);
+				const write = normalizeWriteMode(data?.write);
+				const doMode = normalizeDoMode(data?.do);
+				if (show !== null) axes.show = show;
+				if (write !== null) axes.write = write;
+				if (doMode !== null) axes.do = doMode;
+				return Object.keys(axes).length === 0 ? null : axes;
+			}
+			if (entry.customType === "prompt-mode") {
+				// v0.1 遗留单档条目的兜底（仅当没有 prompt-axes 时使用）
+				legacyShow = normalizeShowMode(entry.data?.show ?? entry.data?.mode);
+			}
+		}
+		return legacyShow !== null ? { show: legacyShow } : null;
+	}
+
+	/** 当前三轴是否等价于"全局关闭"（show normal + 其余 normal） */
+	private isGloballyOff(provider: string | undefined): boolean {
+		return (
+			this.effectiveShow(provider) === "normal" &&
+			this.effectiveWrite(provider) === "normal" &&
+			this.effectiveDo(provider) === "normal"
+		);
+	}
+
+	// ── 运行时解析（auto → 具体档） ──────────────────────────────────────
+
+	/**
+	 * auto 低频自动抽样：每 interval 轮 + 当日≤maxPerDay + 仅 show=auto + 不与手动探针重叠 →
+	 * 下一回合走 normal（不注入）采对照组样本，turn_end 重拟合。
+	 * 返回 true 当且仅当本轮应触发抽样（状态已更新，调用方直接返回 sample 决策）。
+	 */
+	private shouldSample(): boolean {
+		if (!this.config.isAutoSample()) return false;
+		if (this.probeTurnsLeft > 0) return false;
+		const provider = this.lastCtx?.model?.provider;
+		if (this.effectiveShow(provider) !== "auto") return false;
+		const now = new Date();
+		const day = beijingDate(now);
+		if (day !== this.todaySampleDay) { this.todaySampleDay = day; this.todaySampleCount = 0; }
+		this.turnsSinceSample += 1;
+		if (this.turnsSinceSample < this.config.autoSampleInterval()) return false;
+		if (this.todaySampleCount >= this.config.autoSampleMaxPerDay()) return false;
+		// 触发：重置计数，由 turn_end 负责 pendingRecalibrate
+		this.turnsSinceSample = 0;
+		this.todaySampleCount += 1;
+		return true;
+	}
+
+	/** 解析并缓存本回合三轴实际值（auto show 走选档器；探针/抽样回合强制不注入） */
+	private resolveAxes(provider: string | undefined, model: string | undefined): { show: RuntimeShowMode; write: WriteMode; do: DoMode; decision: string } {
+		if (this.probeTurnsLeft > 0) {
+			this.probeTurnsLeft -= 1;
+			if (this.probeTurnsLeft === 0) this.pendingRecalibrate = true;
+			return { show: "normal", write: "normal", do: "normal", decision: "probe" };
+		}
+		// auto 低频抽样（每 interval 轮采一次对照组；decision="sample"，turn_end 触发重拟合）
+		if (this.shouldSample()) {
+			this.pendingRecalibrate = true;
+			return { show: "normal", write: "normal", do: "normal", decision: "sample" };
+		}
+		const write = this.effectiveWrite(provider);
+		const doMode = this.effectiveDo(provider);
+		const preferred = this.effectiveShow(provider);
+		if (preferred !== "auto") {
+			return { show: preferred, write, do: doMode, decision: "manual" };
+		}
+		const bin = taskBinForInput(this.lastUserTokens);
+		const estMu = this.calibration.muFor(provider ?? "unknown", bin) ?? estimateMuFromInput(this.lastUserTokens);
+		// 峰谷不再由这里硬编码推算：由价格源（pi-pricer / 兜底）随价格返回 isPeak；
+		// peakUpgrade:false 时传 false，关闭"高峰升档"这层优化（仅影响升档定价）
+		const peakUpgrade = this.config.isPeakUpgrade();
+		const now = Date.now();
+		const modelId = model ?? "unknown";
+		const chosen = this.chooser.choose(provider ?? "unknown", modelId, bin, estMu, this.cacheState, now, peakUpgrade);
+		const isPeak = peakUpgrade && pricingFor(provider ?? "unknown", modelId, now).isPeak;
+		return {
+			show: chosen,
+			write,
+			do: doMode,
+			decision: `auto: µ=${estMu},${this.cacheState ? "cached" : "cold"}${isPeak ? ",peak" : ""}→${chosen}`,
+		};
+	}
+
+	// ── 状态栏 ───────────────────────────────────────────────────────────
+
+	/**
+	 * 渲染状态栏文本（v0.2.2 footer 风格）：三轴全显、纯文字、去掉 ●/○ 与档位图标。
+	 * show=auto 时显示本轮实际解析档；尚无解析的首帧回退显示 auto。
+	 * 恒常显示（不做"全局关停即隐藏"）——用户拍板"一直显示"。
+	 */
+	private statusText(provider: string | undefined): string {
+		const preferred = this.effectiveShow(provider);
+		const show = preferred === "auto" ? (this.lastResolved?.show ?? "auto") : preferred;
+		return `PROMPT ${show} · ${this.effectiveWrite(provider)} · ${this.effectiveDo(provider)}`;
+	}
+
+	/** 同步状态栏（hideStatus 配置可隐藏；文本永远是三轴全显，灰化显示） */
+	private syncStatus(ctx: AnyContext | undefined): void {
+		if (this.hideStatus || !ctx) return;
+		try {
+			ctx.ui.setStatus("pi-prompt", `${DIM_ON}${this.statusText(ctx.model?.provider)}${DIM_OFF}`);
+		} catch {
+			// 主题/状态栏异常一律静默
+		}
+	}
+
+	// ── 会话档位更新与持久化 ─────────────────────────────────────────────
+
+	/** 设置某轴会话档位：合并持久化 + 同步状态栏 + 提示 */
+	private applyAxis(axis: AxisName, value: ShowMode | WriteMode | DoMode, ctx: AnyContext): void {
+		const current = this.sessionAxes ?? {};
+		if (axis === "show") current.show = value as ShowMode;
+		if (axis === "write") current.write = value as WriteMode;
+		if (axis === "do") current.do = value as DoMode;
+		this.sessionAxes = current;
+		this.pi?.appendEntry("prompt-axes", { show: current.show, write: current.write, do: current.do });
+		this.syncStatus(ctx);
+		ctx.ui.notify(`pi-prompt: ${axis}=${String(value)}`, "info");
+	}
+
+	/** 全局回到三轴默认：清空会话覆盖并持久化清除标记 */
+	private resetToDefaults(ctx: AnyContext): void {
+		this.sessionAxes = null;
+		this.pi?.appendEntry("prompt-axes", { cleared: true });
+		this.syncStatus(ctx);
+		const defaults = this.config.getDefaults();
+		ctx.ui.notify(`pi-prompt 已回到默认：show=${String(defaults.show)}`, "info");
+	}
+
+	// ── 展示 ─────────────────────────────────────────────────────────────
+
+	/** /prompt status：三轴现状/默认/厂商映射/台账估算 */
+	private showStatus(ctx: AnyContext): void {
+		const provider = ctx.model?.provider;
+		const showCfg = this.effectiveShow(provider);
+		const lines: string[] = ["pi-prompt 状态"];
+		lines.push(
+			`  show: ${showCfg === "auto" ? "🔄 AUTO" : showLabel(showCfg)}${this.sessionAxes?.show !== undefined ? "（会话显式）" : "（自动）"}${this.lastResolved ? ` ·本轮→${showLabel(this.lastResolved.show)}` : ""}`,
+		);
+		lines.push(`  write: ${String(this.effectiveWrite(provider))}${this.sessionAxes?.write !== undefined ? "（会话显式）" : "（自动）"}`);
+		lines.push(`  do: ${String(this.effectiveDo(provider))}${this.sessionAxes?.do !== undefined ? "（会话显式）" : "（自动）"}`);
+		const defaults = this.config.getDefaults();
+		lines.push(`  默认: show=${String(defaults.show)} / write=${String(defaults.write)} / do=${String(defaults.do)}`);
+		const perProvider = this.config.perProviderConfig();
+		const mapped = Object.entries(perProvider);
+		lines.push(
+			mapped.length === 0
+				? "  厂商映射: 无"
+				: `  厂商映射: ${mapped.map(([providerId, axes]) => `${providerId}→show:${axes.show ?? "-"} write:${axes.write ?? "-"} do:${axes.do ?? "-"}`).join(" | ")}`,
+		);
+		const records = this.ledger.readAll();
+		if (records.length > 0) {
+			const est = estimateSaved(records);
+			lines.push(`  台账估算: 输出 ${formatTokens(est.outputTokens)}，估省 ${formatTokens(est.savedOutputTokens)} ≈ ¥${est.savedCNY.toFixed(4)}（保守假设）`);
+		} else {
+			lines.push("  台账: 暂无记录");
+		}
+		ctx.ui.notify(lines.join("\n"), "info");
+	}
+
+	/** /prompt usage：DeepSeek 风格的 token/金额台账表 */
+	private showUsage(ctx: AnyContext): void {
+		const records = this.ledger.readAll();
+		if (records.length === 0) {
+			ctx.ui.notify("pi-prompt 台账为空（还没有 turn_end 用量记录）", "info");
+			return;
+		}
+		const summary = summarizeUsage(records);
+		const lines: string[] = ["pi-prompt 台账（估算口径，权威计价在 pi-usager）"];
+		lines.push(`价格来源: ${this.describePricingSource()}`);
+		lines.push(`总览: ${summary.total.turns} 回合 · 输入 ${formatTokens(summary.total.input)} · 缓存命中 ${formatTokens(summary.total.cacheRead)} · 输出 ${formatTokens(summary.total.output)} · 估算 ¥${summary.total.costCNY.toFixed(4)}`);
+		for (const row of summary.rows) {
+			lines.push(`  ${row.day} ${row.model} — ${row.turns}回合 入${formatTokens(row.input)} 缓存${formatTokens(row.cacheRead)} 出${formatTokens(row.output)} ≈¥${row.costCNY.toFixed(4)} 估省¥${row.savedCNY.toFixed(4)}`);
+		}
+		if (summary.sessions.length > 0) {
+			lines.push("按会话:");
+			for (const sess of summary.sessions.slice(-8)) {
+				lines.push(`  ${sess.session} — ${sess.turns}回合 入${formatTokens(sess.input)} 出${formatTokens(sess.output)} ≈¥${sess.costCNY.toFixed(4)} 估省¥${sess.savedCNY.toFixed(4)}`);
+			}
+		}
+		ctx.ui.notify(lines.join("\n"), "info");
+	}
+
+	/**
+	 * 价格来源提醒（每种情况每会话只提一次）。
+	 * - 未装 pi-pricer：建议安装以获得用户自配的精准价格
+	 * - 装了但解析失败：暴露原因（否则用户会以为算的是自己配的价）
+	 */
+	private notifyPricingFallbackOnce(ctx: AnyContext): void {
+		if (this.pricingHintShown) return;
+		const { source, reason } = getPricingSource();
+		switch (source) {
+			case "pi-pricer":
+				return; // 权威价表，无需提醒
+			case "failed":
+				this.pricingHintShown = true;
+				ctx.ui.notify(`pi-pricer 价格解析失败（${reason ?? "未知原因"}），本次按内置兜底价估算。请检查 ~/.pi/model-pricing.json。`, "warning");
+				return;
+			case "builtin":
+				this.pricingHintShown = true;
+				ctx.ui.notify("当前用内置兜底近似价估算成本。安装 pi-pricer 并维护 ~/.pi/model-pricing.json，即可让成本与 auto 选档按你自己配置的真实价格（含峰谷）计算。", "info");
+				return;
+		}
+	}
+
+	/**
+	 * 价格来源人读文案：让用户知道成本/auto 按什么价算的。
+	 * pi-pricer 已装但加载失败时给出原因（不再完全静默）。
+	 */
+	private describePricingSource(): string {
+		const { source, reason } = getPricingSource();
+		switch (source) {
+			case "pi-pricer":
+				return "pi-pricer JSON 价表（~/.pi/model-pricing.json，含自定义峰谷）";
+			case "failed":
+				return `内置兜底价（pi-pricer 解析失败：${reason ?? "未知原因"}）`;
+			case "builtin":
+				return "内置兜底近似价（未安装 pi-pricer，建议安装以获得你自配的精准价格）";
+		}
+	}
+
+	/** /prompt check：台账完整性 + 校准状态；--calibrate 触发探针 */
+	private showCheck(ctx: AnyContext, calibrate: boolean): void {
+		const integrity = this.ledger.integrity();
+		const calFile = this.calibration.refresh();
+		const fitted: string[] = [];
+		for (const [provider, providerFit] of Object.entries(calFile.byProvider)) {
+			for (const [bin, binFit] of Object.entries(providerFit.byBin)) {
+				if (binFit.mu !== undefined) fitted.push(`${provider}#${bin}(µ${binFit.mu}, ctl${binFit.normal?.n ?? binFit.off?.n ?? 0})`);
+			}
+		}
+		const lines: string[] = ["pi-prompt 自检"];
+		lines.push(`  台账: ${integrity.validLines}/${integrity.totalLines} 合法行${integrity.damagedLines > 0 ? `，损坏 ${integrity.damagedLines} 行（将跳过）` : ""} @ ${integrity.filePath}`);
+		lines.push(`  价格来源: ${this.describePricingSource()}`);
+		lines.push(`  校准: ${calFile.updatedAt === 0 ? "无拟合数据（auto 用先验）" : `已拟合 ${fitted.join(", ") || "(空)"}（更新于 ${new Date(calFile.updatedAt).toISOString().slice(0, 10)}）`}`);
+		lines.push("  --calibrate 将跑 3 轮对照组探针（本轮不注入地采集基线）并重拟合");
+		if (calibrate) {
+			lines.push("  已排队 3 轮探针…");
+			this.queueProbes(ctx);
+		}
+		ctx.ui.notify(lines.join("\n"), "info");
+	}
+
+	/** 排队校准探针：剩余探针回合 + 依次发送固定题（仅 idle 才发，否则 followUp） */
+	private queueProbes(ctx: AnyContext): void {
+		if (!this.pi) return;
+		this.probeTurnsLeft = PROBE_TURNS;
+		const probePrompts: string[] = [
+			"pi-prompt 校准探针 1/3：请用约 3 句话解释什么是回调函数。",
+			"pi-prompt 校准探针 2/3：请用约 3 句话说明 git rebase 与 merge 的区别。",
+			"pi-prompt 校准探针 3/3：请用约 3 句话介绍 HOF 与装饰器。",
+		];
+		for (const prompt of probePrompts) {
+			if (ctx.isIdle?.() === false) {
+				this.pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+			} else {
+				this.pi.sendUserMessage(prompt);
+			}
+		}
+	}
+
+	// ── 台账 ─────────────────────────────────────────────────────────────
+
+	/** turn_end：采集用量追加台账；探针采集完触发重拟合 */
+	private recordUsage(raw: RawUsage | undefined, provider: string | undefined, model: string | undefined, ctx: AnyContext): void {
+		const resolved = this.lastResolved;
+		if (raw && resolved) {
+			this.ledger.append({
+				ts: Date.now(),
+				provider: provider ?? "unknown",
+				model: model ?? "unknown",
+				show: resolved.show,
+				write: resolved.write,
+				do: resolved.do,
+				taskBin: resolved.taskBin,
+				decision: resolved.decision,
+				session: this.runId,
+				input: raw.input ?? 0,
+				output: raw.output ?? 0,
+				cacheRead: raw.cacheRead ?? 0,
+				cacheWrite: raw.cacheWrite ?? 0,
+			});
+			// 缓存状态滚动更新（auto 的成本项输入）
+			this.cacheState = (raw.cacheRead ?? 0) > 0;
+		}
+		if (this.pendingRecalibrate) {
+			this.pendingRecalibrate = false;
+			const records = this.ledger.readAll();
+			const result = this.calibration.recalibrate(records);
+			ctx.ui.notify(
+				result.changed ? "校准完成：已按台账重拟合缩减率" : "校准完成：样本不足未改动系数（需 ≥5 对照组 / ≥3 各档）",
+				"info",
+			);
+		}
+	}
+
+	// ── 装配 ─────────────────────────────────────────────────────────────
+
+	/** 装配所有命令与事件（pi 生命周期入口） */
+	mount(pi: ExtensionAPI): void {
+		this.pi = pi;
+		// 后台预热 JSON 价表（pi-pricer 可选集成；失败静默保持内置近似价）
+		void ensurePricingResolver();
+
+		pi.registerCommand("prompt", {
+			description: "三轴输出控制：config/status/usage/check",
+			getArgumentCompletions: () => [
+				{ value: "config", label: "config", description: "打开三轴设置抽屉（会话档 + 默认档）" },
+				{ value: "status", label: "status", description: "显示三轴现状与台账估算" },
+				{ value: "usage", label: "usage", description: "token/金额台账表" },
+				{ value: "check", label: "check", description: "自检（--calibrate 触发探针校准）" },
+			],
+			handler: async (args, ctx) => {
+				this.lastCtx = ctx;
+				const cmd = parsePromptCommand(args);
+				switch (cmd.type) {
+					case "toggle": {
+						if (this.isGloballyOff(ctx.model?.provider)) {
+							this.resetToDefaults(ctx);
+							return;
+						}
+						// 全局关闭 = 三轴全部不注入（show normal + write/do normal）
+						this.applyAxis("show", "normal", ctx);
+						this.applyAxis("write", "normal", ctx);
+						this.applyAxis("do", "normal", ctx);
+						return;
+					}
+					case "status":
+						this.showStatus(ctx);
+						return;
+					case "usage":
+						// 先用 JSON 价表（pi-pricer）解析价格，失败自动兜底内置近似价
+						await ensurePricingResolver();
+						this.notifyPricingFallbackOnce(ctx);
+						this.showUsage(ctx);
+						return;
+					case "check":
+						this.showCheck(ctx, cmd.calibrate);
+						return;
+					case "config":
+						await this.drawer.open(ctx);
+						return;
+					case "invalid":
+						ctx.ui.notify(`未知参数 "${cmd.arg}"\n用法: /prompt [config | status | usage | check [--calibrate]]（无参=全局开关）`, "warning");
+						return;
+				}
+			},
+		});
+
+		pi.registerCommand("prompt-review", {
+			description: "运行 /skill:prompt-review 审计上一条回复的冗余",
+			handler: async (_args, ctx) => {
+				this.lastCtx = ctx;
+				if (ctx.isIdle?.() === false) {
+					pi.sendUserMessage("/skill:prompt-review", { deliverAs: "followUp" });
+					ctx.ui.notify("prompt-review 已排队为下一条", "info");
+					return;
+				}
+				pi.sendUserMessage("/skill:prompt-review");
+			},
+		});
+
+		// 全词关停："stop pi-prompt" / "normal mode" → 三轴回默认
+		pi.on("input", (event) => {
+			if (event?.source === "extension") return;
+			if (typeof event?.text === "string") {
+				const raw = event.text;
+				this.lastUserTokens = Math.max(1, Math.round(raw.length / 2.2));
+			}
+			if (!isDeactivationCommand(event?.text)) return;
+			const ctx = this.lastCtx;
+			if (ctx) this.resetToDefaults(ctx);
+			else this.sessionAxes = null;
+		});
+
+		// 会话启动/恢复：读会话三轴 + 隐藏开关
+		pi.on("session_start", (_event, ctx) => {
+			this.lastCtx = ctx;
+			this.hideStatus = this.config.isHideStatus();
+			this.sessionAxes = this.readSessionAxes(ctx);
+			this.syncStatus(ctx);
+			if (!this.config.isQuietStartup()) {
+				const show = this.effectiveShow(ctx.model?.provider);
+				ctx.ui.notify(`pi-prompt loaded: show=${show === "auto" ? "🔄 AUTO" : showLabel(show)}, write=${String(this.effectiveWrite(ctx.model?.provider))}, do=${String(this.effectiveDo(ctx.model?.provider))}`, "info");
+			}
+		});
+
+		// 切换模型：状态栏即时刷新
+		pi.on("model_select", (_event, ctx) => {
+			this.syncStatus(ctx);
+		});
+
+		// max_tokens 上限钳制（默认关；config maxTokensCap 或 env PI_PROMPT_MAX_TOKENS）
+		pi.on("before_provider_request", (event) => {
+			const cap = this.config.maxTokensCap();
+			if (cap === null) return;
+			const payload = event?.payload;
+			if (payload === undefined || payload === null) return;
+			return { payload: clampMaxTokens(payload, cap) };
+		});
+
+		// 核心注入：解析三轴（auto→选档）→ 固定顺序拼接恒定文案追加到系统提示末尾
+		pi.on("before_agent_start", (event, ctx) => {
+			const provider = ctx.model?.provider;
+			const model = ctx.model?.id;
+			const resolved = this.resolveAxes(provider, model);
+			this.lastResolved = { ...resolved, taskBin: taskBinForInput(this.lastUserTokens) };
+			// footer 状态同步为"本轮实际档"（show=auto 时）
+			this.syncStatus(ctx);
+			const text = this.registry.compose(resolved.show, resolved.write, resolved.do);
+			if (!text) return;
+			const base = event?.systemPrompt ? `${event.systemPrompt}\n\n` : "";
+			return { systemPrompt: `${base}${text}` };
+		});
+
+		// turn_end：采集真实 token 用量 → 台账 + 探针后重拟合
+		pi.on("turn_end", (event, ctx) => {
+			const raw = (event.message as { usage?: RawUsage }).usage;
+			this.recordUsage(raw, ctx.model?.provider, ctx.model?.id, ctx);
+		});
+	}
+}