pi-cc-extensions 0.9.12 → 1.0.1

package/README.en.md

@@ -63,6 +63,7 @@ Renderer snapshots for `on` / `compact` modes: [default](./docs/tool-render-exam
   "expandedCardBackground": "userMessageBg", // expanded card background slot: userMessageBg (same as user prompts) / toolPendingBg (neutral) etc.
   "toolLabelClip": 0, // tool summary path/command clip length; 0 = fit width
   "showStartupHeader": true, // startup header (logo + tips) toggle
+  "stickyUserMessage": true, // fullscreen: pin a user message's first line once it scrolls off the top edge, until the next one takes over
 
   // diff
   "diffViewMode": "auto", // layout: auto / split / unified
@@ -80,6 +81,8 @@ Renderer snapshots for `on` / `compact` modes: [default](./docs/tool-render-exam
 
   // footer
   "enableCustomFooter": true, // custom status bar
+  "footerTokenRate": true, // output rate chip; false hides it
+  "footerTokenRateMode": "average", // average: whole-prompt avg; live: trailing 1s rate
   "footerCurrency": "USD", // display currency for the footer cost
   "footerCurrencyRate": null, // display units per 1 cost unit; null changes the symbol only
   "footerNerdIcons": true, // Nerd Font glyphs for git/cache; false = plain text
@@ -92,7 +95,7 @@ Renderer snapshots for `on` / `compact` modes: [default](./docs/tool-render-exam
 ```
 
 > [!TIP]
-> **Fullscreen**: click `click to show more` to expand tool cards, thinking, Skill, and compact summaries. An expanded diff always shows every line; when expanded Input/Output exceeds the line cap, the footer `… +N more lines · click to show more` opens a full preview. Click to collapse (dragging inside the card selects text).
+> **Fullscreen**: click `click to show more` to expand tool cards, thinking, Skill, and compact summaries. An expanded diff always shows every line; when expanded Input/Output exceeds the line cap, the footer `… +N more lines · click to show more` opens a full preview. Click to collapse.
 
 > [!NOTE]
 > **Mermaid rendering**: set `markdown.mermaid` to `final` via `~/.pi/agent/settings.json` or the Mermaid diagrams option in `/settings`. Default `streaming` redraws per frame; `final` renders once at completion.

package/README.md

@@ -63,6 +63,7 @@ pi install git:github.com/minuque/pi-cc-extensions
   "expandedCardBackground": "userMessageBg", // 展开卡背景槽位；userMessageBg 与用户消息同色，toolPendingBg 为中性灰
   "toolLabelClip": 0,                      // 工具摘要 path/command 折叠字符数；0 = 按可用宽度
   "showStartupHeader": true,               // 启动头（logo + tips）开关
+  "stickyUserMessage": true,               // fullscreen：userMessage 正文首行滚出视口上沿后钉住，直到下一条指令接手
 
   // diff
   "diffViewMode": "auto",                  // 布局：auto / split / unified
@@ -80,6 +81,8 @@ pi install git:github.com/minuque/pi-cc-extensions
 
   // footer
   "enableCustomFooter": true,              // 自定义状态栏
+  "footerTokenRate": true,                  // 输出速率芯片；false 隐藏
+  "footerTokenRateMode": "average",         // average：整段指令平均（avg）；live：最近 1 秒瞬时（live）
   "footerCurrency": "USD",                 // 底栏费用的显示币种
   "footerCurrencyRate": null,              // 1 单位费用换成多少显示币种；null 只换符号、不乘倍率
   "footerNerdIcons": true,                 // git/缓存用 Nerd Font 图标；false 为纯文本
@@ -92,7 +95,7 @@ pi install git:github.com/minuque/pi-cc-extensions
 ```
 
 > [!TIP]
-> **全屏模式**：单击 `click to show more` 展开工具卡、思考、Skill 和 compact 摘要；工具卡展开态 diff 全量显示，Input/Output 超行时末行 `… +N more lines · click to show more` 打开全量预览，单击收起（卡内拖动为选中文本）。
+> **全屏模式**：单击 `click to show more` 展开工具卡、思考、Skill 和 compact 摘要；工具卡展开态 diff 全量显示，Input/Output 超行时末行 `… +N more lines · click to show more` 打开全量预览，单击收起。
 
 > [!NOTE]
 > **Mermaid 渲染**：建议把 `markdown.mermaid` 设为 `final`（`~/.pi/agent/settings.json` 或 `/settings` 面板的 Mermaid diagrams 选项）。默认 `streaming` 逐帧重绘，`final` 渲染最终版更稳定。

package/extensions/config/config.ts

@@ -14,6 +14,7 @@ export type CompactStyleMode = "on" | "compact" | "off";
 export type DiffViewMode = "auto" | "split" | "unified";
 export type DiffIndicatorMode = "bars" | "classic" | "none";
 export type FooterGitStatsMode = "working" | "branch";
+export type FooterTokenRateMode = "average" | "live";
 
 export interface ToolDisplayConfig {
 	diffViewMode: DiffViewMode;
@@ -65,6 +66,8 @@ export type Config = {
 	animationIntervalMs: number;
 	dimThinkingText: boolean;
 	showStartupHeader: boolean;
+	/** fullscreen：userMessage 正文首行滚出视口上沿后钉住，直到下一条指令接手。 */
+	stickyUserMessage: boolean;
 	enableSessionReference: boolean;
 	enableSubagentAutocomplete: boolean;
 	enableContextCommand: boolean;
@@ -72,6 +75,10 @@ export type Config = {
 	enableWorkingMessage: boolean;
 	enableAliases: boolean;
 	enableCustomFooter: boolean;
+	/** footer 输出速率芯片。关则不显示。 */
+	footerTokenRate: boolean;
+	/** average：整段指令墙钟平均；live：最近 1 秒瞬时速率，空档回退平均。 */
+	footerTokenRateMode: FooterTokenRateMode;
 	/** ISO 4217 显示币种。USD 时不换算。 */
 	footerCurrency: string;
 	/** 1 单位费用对应的显示币种数量。null 只换符号、不乘倍率。 */
@@ -91,6 +98,7 @@ const LEGACY_CONFIG_PATH = join(AGENT_DIR, "claude-code-style.json");
 export const DIFF_VIEW_MODES: DiffViewMode[] = ["auto", "split", "unified"];
 export const DIFF_INDICATOR_MODES: DiffIndicatorMode[] = ["bars", "classic", "none"];
 export const FOOTER_GIT_STATS_MODES: FooterGitStatsMode[] = ["working", "branch"];
+export const FOOTER_TOKEN_RATE_MODES: FooterTokenRateMode[] = ["average", "live"];
 export const DIFF_SPLIT_MIN_WIDTH_VALUES = ["80", "100", "120", "140", "160", "180"];
 export const DIFF_COLLAPSED_LINES_VALUES = ["0", "12", "24", "36", "48", "80", "120"];
 /** Write collapsed presets. 0 = stats only (`+N -0` + expand hint). */
@@ -153,6 +161,7 @@ export const DEFAULT_CONFIG: Config = {
 	animationIntervalMs: 90,
 	dimThinkingText: false,
 	showStartupHeader: true,
+	stickyUserMessage: true,
 	enableSessionReference: true,
 	enableSubagentAutocomplete: true,
 	enableContextCommand: true,
@@ -160,6 +169,8 @@ export const DEFAULT_CONFIG: Config = {
 	enableWorkingMessage: true,
 	enableAliases: true,
 	enableCustomFooter: true,
+	footerTokenRate: true,
+	footerTokenRateMode: "average",
 	footerCurrency: "USD",
 	footerCurrencyRate: null,
 	footerNerdIcons: true,
@@ -282,6 +293,7 @@ export function normalizeConfig(input: unknown): Config {
 		),
 		dimThinkingText: source.dimThinkingText === true,
 		showStartupHeader: source.showStartupHeader !== false,
+		stickyUserMessage: source.stickyUserMessage !== false,
 		enableSessionReference: source.enableSessionReference !== false,
 		enableSubagentAutocomplete: source.enableSubagentAutocomplete !== false,
 		enableContextCommand: source.enableContextCommand !== false,
@@ -289,6 +301,12 @@ export function normalizeConfig(input: unknown): Config {
 		enableWorkingMessage: source.enableWorkingMessage !== false,
 		enableAliases: source.enableAliases !== false,
 		enableCustomFooter: source.enableCustomFooter !== false,
+		footerTokenRate: source.footerTokenRate !== false,
+		footerTokenRateMode: pickEnum(
+			source.footerTokenRateMode,
+			FOOTER_TOKEN_RATE_MODES,
+			DEFAULT_CONFIG.footerTokenRateMode,
+		),
 		footerCurrency: normalizeCurrency(source.footerCurrency),
 		footerCurrencyRate: normalizeFooterCurrencyRate(source.footerCurrencyRate),
 		footerNerdIcons: source.footerNerdIcons !== false,
@@ -344,6 +362,7 @@ export function formatConfigStatus(source: Config = config): string {
 		`thinkingAnimation=${source.animationIntervalMs}ms`,
 		`thinkingDim=${source.dimThinkingText ? "on" : "off"}`,
 		`startupHeader=${source.showStartupHeader ? "on" : "off"}`,
+		`stickyUserMessage=${source.stickyUserMessage ? "on" : "off"}`,
 		`sessionRef=${source.enableSessionReference ? "on" : "off"}`,
 		`subagentAuto=${source.enableSubagentAutocomplete ? "on" : "off"}`,
 		`context=${source.enableContextCommand ? "on" : "off"}`,
@@ -351,6 +370,8 @@ export function formatConfigStatus(source: Config = config): string {
 		`workingMsg=${source.enableWorkingMessage ? "on" : "off"}`,
 		`aliases=${source.enableAliases ? "on" : "off"}`,
 		`footer=${source.enableCustomFooter ? "on" : "off"}`,
+		`footerTokenRate=${source.footerTokenRate ? "on" : "off"}`,
+		`footerTokenRateMode=${source.footerTokenRateMode}`,
 		`footerCurrency=${source.footerCurrency}`,
 		`footerRate=${source.footerCurrencyRate ?? "-"}`,
 		`footerIcons=${source.footerNerdIcons ? "nerd" : "plain"}`,

package/extensions/config/panel.ts

@@ -43,6 +43,7 @@ import {
 	EXPANDED_OUTPUT_MAX_LINES_VALUES,
 	EXPANDED_PREVIEW_MAX_LINES_VALUES,
 	FOOTER_GIT_STATS_MODES,
+	FOOTER_TOKEN_RATE_MODES,
 	formatExcludeRenderers,
 	getCompactThinkingConfig,
 	pickPositiveInt,
@@ -58,6 +59,7 @@ import {
 	type DiffIndicatorMode,
 	type DiffViewMode,
 	type FooterGitStatsMode,
+	type FooterTokenRateMode,
 } from "./config.ts";
 
 /** renderer 注入的渲染副作用，面板自身不触碰渲染状态。 */
@@ -68,7 +70,7 @@ export type CcstylePanelHooks = {
 
 function modeSettingDescription(mode: CompactStyleMode): string {
 	if (mode === "compact") {
-		return "(Experimental) One summary line per assistant round; edit/write reuse the same Diff preview settings as on.";
+		return "One summary line per assistant round; edit/write reuse the same Diff preview settings as on.";
 	}
 	if (mode === "off") {
 		return "Pi native tool rendering. Diff options below still apply independently.";
@@ -87,6 +89,18 @@ function customFooterDescription(enabled: boolean): string {
 	return "Custom status bar with model, context, cache, cost, git, and plugin chips.";
 }
 
+function footerTokenRateDescription(enabled: boolean): string {
+	return enabled
+		? "Output rate chip after the cache hit rate. Turn off to hide it."
+		: "Output rate chip hidden.";
+}
+
+function footerTokenRateModeDescription(mode: FooterTokenRateMode): string {
+	return mode === "live"
+		? "Sliding 1s rate while generating (live). Tool waits are excluded. Falls back to the run average between chunks and after the prompt."
+		: "Average over the whole user prompt (avg), including tool waits. Stays until the next prompt.";
+}
+
 function footerGitStatsDescription(mode: FooterGitStatsMode): string {
 	return mode === "branch"
 		? "Net changes since the merge base, including uncommitted edits. Base: origin/HEAD, then local main/master. Untracked files excluded; unavailable stats hidden."
@@ -422,8 +436,8 @@ export async function showCcstylePanel(
 			id: "mode",
 			label: "Mode",
 			description: modeSettingDescription(config.mode),
-			currentValue: config.mode === "compact" ? "compact (Experimental)" : config.mode,
-			values: ["on", "compact (Experimental)", "off"],
+			currentValue: config.mode,
+			values: ["on", "compact", "off"],
 		};
 		// Tracks whether a nested submenu is open so Tab switches sections
 		// only at the top level (mirrors Zentui settings: Tab = switch sections).
@@ -595,6 +609,15 @@ export async function showCcstylePanel(
 			currentValue: config.showStartupHeader ? "on" : "off",
 			values: ["on", "off"],
 		};
+		const stickyUserMessageSetting = {
+			id: "stickyUserMessage",
+			label: "Sticky user message",
+			description: config.stickyUserMessage
+				? "Fullscreen: pin a user message's first line once it scrolls off the top edge, until the next one takes over."
+				: "User messages scroll normally.",
+			currentValue: config.stickyUserMessage ? "on" : "off",
+			values: ["on", "off"],
+		};
 
 		// 额外功能开关：注册于扩展加载期，切换后需重启（/reload）生效。
 		const sessionReferenceToggle = featureToggleSetting(
@@ -721,6 +744,20 @@ export async function showCcstylePanel(
 			currentValue: config.footerGitStatsMode,
 			values: FOOTER_GIT_STATS_MODES,
 		};
+		const footerTokenRateSetting = {
+			id: "footerTokenRate",
+			label: "Token rate",
+			description: footerTokenRateDescription(config.footerTokenRate),
+			currentValue: config.footerTokenRate ? "on" : "off",
+			values: ["on", "off"],
+		};
+		const footerTokenRateModeSetting = {
+			id: "footerTokenRateMode",
+			label: "Token rate mode",
+			description: footerTokenRateModeDescription(config.footerTokenRateMode),
+			currentValue: config.footerTokenRateMode,
+			values: FOOTER_TOKEN_RATE_MODES,
+		};
 		const pluginChipsSetting = {
 			id: "footerPluginChips",
 			label: "Plugin chips",
@@ -793,6 +830,23 @@ export async function showCcstylePanel(
 				ctx.ui.notify(`Updated ${id}: ${value}`, "info");
 				return;
 			}
+			if (id === "footerTokenRate") {
+				const enabled = value === "on";
+				updateConfig({ footerTokenRate: enabled });
+				footerTokenRateSetting.currentValue = enabled ? "on" : "off";
+				footerTokenRateSetting.description = footerTokenRateDescription(enabled);
+				ctx.ui.notify(`Updated ${id}: ${value}`, "info");
+				return;
+			}
+			if (id === "footerTokenRateMode") {
+				updateConfig({ footerTokenRateMode: value as FooterTokenRateMode });
+				footerTokenRateModeSetting.currentValue = config.footerTokenRateMode;
+				footerTokenRateModeSetting.description = footerTokenRateModeDescription(
+					config.footerTokenRateMode,
+				);
+				ctx.ui.notify(`Updated ${id}: ${value}`, "info");
+				return;
+			}
 			if (id === "footerNerdIcons") {
 				const enabled = value === "on";
 				updateConfig({ footerNerdIcons: enabled });
@@ -819,9 +873,7 @@ export async function showCcstylePanel(
 					toolLabelClipSetting.currentValue = String(config.toolLabelClip);
 					break;
 				case "mode": {
-					// 选项值带 Experimental 标记，选择后还原为真实 mode 值。
-					const mode: CompactStyleMode =
-						value === "compact (Experimental)" ? "compact" : (value as CompactStyleMode);
+					const mode = value as CompactStyleMode;
 					modeSetting.description = modeSettingDescription(mode);
 					hooks.applyStyleMode(mode, ctx, toolGrouping);
 					return;
@@ -930,6 +982,13 @@ export async function showCcstylePanel(
 						? "Thinking text uses the theme's dim color."
 						: "Keep the default thinking text color.";
 					break;
+				case "stickyUserMessage": {
+					updateConfig({ stickyUserMessage: value === "on" });
+					stickyUserMessageSetting.description = config.stickyUserMessage
+						? "Fullscreen: pin a user message's first line once it scrolls off the top edge, until the next one takes over."
+						: "User messages scroll normally.";
+					break;
+				}
 				case "showStartupHeader": {
 					const enabled = value === "on";
 					updateConfig({ showStartupHeader: enabled });
@@ -975,6 +1034,7 @@ export async function showCcstylePanel(
 					expandedMaxSetting,
 					expandedCardBgSetting,
 					toolLabelClipSetting,
+					stickyUserMessageSetting,
 					startupHeaderSetting,
 				],
 			},
@@ -1005,6 +1065,8 @@ export async function showCcstylePanel(
 				label: "Footer",
 				items: [
 					customFooterSetting,
+					footerTokenRateSetting,
+					footerTokenRateModeSetting,
 					footerCurrencySetting,
 					footerCurrencyRateSetting,
 					footerNerdIconsSetting,

package/extensions/feature/shell/footer.ts

@@ -21,6 +21,7 @@ import { pathToFileURL } from "node:url";
 import { config } from "../../config/config.ts";
 import { stripAnsi } from "../../utils/ansi-text.ts";
 import { formatFooterCost } from "./footer-currency.ts";
+import { formatTokenCount } from "../../utils/format.ts";
 import {
 	PI_USAGE_KEY,
 	isSkippedFooterStatusKey,
@@ -30,6 +31,7 @@ import {
 } from "./footer-layout.ts";
 import { createGitStatsRefresher, readGitStats, type GitStats } from "./git-stats.ts";
 import { MCP_STATUS_KEY, buildMcpChip } from "./mcp-chip.ts";
+import { currentTtftMs, displayTokenRate, formatTokenRate } from "./token-rate.ts";
 
 export { parseGitStats } from "./git-stats.ts";
 
@@ -51,6 +53,46 @@ export function footerGlyphs(nerdIcons: boolean): { git: string; cache: string;
 		: { git: "", cache: "", mcp: "" };
 }
 
+/** 思考等级的填充圆标：等级越高填得越满。 */
+const EFFORT_SYMBOL: Record<string, string> = {
+	minimal: "\u25cc",
+	low: "\u25cb",
+	medium: "\u25d4",
+	high: "\u25d1",
+	xhigh: "\u25d5",
+	max: "\u25cf",
+};
+
+/** 模型名后直接接圆标和等级，中间不用分隔点。 */
+export function modelChip(
+	theme: { fg: (color: string, text: string) => string },
+	modelLabel: string,
+	level: string,
+	thinkingColor: (text: string) => string,
+): string {
+	const symbol = EFFORT_SYMBOL[level];
+	if (!symbol) return theme.fg("accent", modelLabel);
+	return `${theme.fg("accent", modelLabel)} ${thinkingColor(symbol)} ${theme.fg("dim", level)}`;
+}
+
+/** git 状态符号按职能分色：冲突/落后 error，修改 warning，未跟踪 muted，领先 success。 */
+export function colorGitStatus(
+	theme: { fg: (color: string, text: string) => string },
+	status: string,
+): string {
+	let out = "";
+	let color = "dim";
+	for (const ch of status) {
+		if (ch === "=" || ch === "\u21e3") color = "error";
+		else if (ch === "!") color = "warning";
+		else if (ch === "?") color = "muted";
+		else if (ch === "\u21e1") color = "success";
+		else if (!/[0-9]/.test(ch)) color = "dim";
+		out += theme.fg(color, ch);
+	}
+	return out;
+}
+
 type XaiFooterReport = {
 	buckets?: Array<{
 		id?: string;
@@ -303,13 +345,7 @@ const createCustomFooterFactory =
 			tui.requestRender();
 		});
 
-		const fmt = (n: number): string => {
-			if (n < 1000) return `${n}`;
-			if (n < 10000) return `${(n / 1000).toFixed(1)}k`;
-			if (n < 1000000) return `${Math.round(n / 1000)}k`;
-			if (n < 10000000) return `${(n / 1000000).toFixed(1)}M`;
-			return `${Math.round(n / 1000000)}M`;
-		};
+		const fmt = formatTokenCount;
 
 		// ---- pi-cc-status 风格：上下文条形图 ----
 		const BAR_WIDTH = 10;
@@ -400,6 +436,14 @@ const createCustomFooterFactory =
 			const glyphs = footerGlyphs(config.footerNerdIcons);
 			const cacheLabel =
 				cachePct > 0 ? `${glyphs.cache ? `${glyphs.cache} ` : ""}${Math.floor(cachePct)}%` : "";
+			const rateLabel = config.footerTokenRate
+				? formatTokenRate(
+						displayTokenRate(config.footerTokenRateMode),
+						currentTtftMs(),
+						config.footerTokenRateMode,
+					)
+				: "";
+			const rateChip = rateLabel ? theme.fg("dim", rateLabel) : "";
 			const costChip =
 				cost || usingSubscription
 					? theme.fg(
@@ -408,10 +452,10 @@ const createCustomFooterFactory =
 						) + (usingSubscription ? theme.fg("warning", " sub") : "")
 					: "";
 			const line1 = joinChips([
-				theme.fg("accent", modelLabel),
-				model?.reasoning ? thinkingColor(thinkingLevelStr) : "",
+				modelChip(theme, modelLabel, model?.reasoning ? thinkingLevelStr : "", thinkingColor),
 				barGauge(percent ?? 0) + theme.fg("dim", ` ${pctLabel}/${fmt(contextWindow)}`),
 				cacheLabel ? theme.fg("dim", cacheLabel) : "",
+				rateChip,
 				costChip,
 				...line1Plugins,
 			]);
@@ -427,7 +471,7 @@ const createCustomFooterFactory =
 				const s = gitStats;
 				let stats = "";
 				if (s && s.status)
-					stats = theme.fg("dim", " [") + gitColor(s.status) + theme.fg("dim", "]");
+					stats = theme.fg("dim", " [") + colorGitStatus(theme, s.status) + theme.fg("dim", "]");
 				if (s && (s.add || s.del))
 					stats +=
 						theme.fg("dim", "(") +

package/extensions/feature/shell/token-rate.ts

@@ -0,0 +1,192 @@
+/**
+ * footer 输出速率的共享状态：working-message 负责采集，footer 负责显示。
+ *
+ * average：一次用户指令的墙钟平均（工具等待计入分母），显示 `avg`。
+ * live：最近 1 秒的瞬时速率，生成期暂停时钟，显示 `live`；指令结束定格为整段平均。
+ * token 与 working-message 同源：优先 provider `usage.output`，否则按 delta 增量估算
+ * （CJK 1 token，其余 chars/4）。provider 值回填到本段消息窗口。
+ * Pi 的 turn 是单次 assistant 消息，工具调用结束会开新 turn。token 跨 turn 累加，
+ * 计时与 TTFT 直到下一条用户指令才重置。
+ * TTFT：用户指令开始到第一个内容块（text/thinking/toolcall）开始的毫秒数，
+ * 同一指令内只记第一次，定格后保留到下一条指令覆盖。
+ */
+
+export type TokenRateMode = "average" | "live";
+
+const LIVE_WINDOW_MS = 1_000;
+const MIN_SPAN_MS = 250;
+const CJK_CHARS =
+	/[\u3000-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uac00-\ud7af\uf900-\ufaff\uff00-\uffef]/g;
+
+interface TokenSample {
+	t: number;
+	cum: number;
+}
+
+let runStartTime = 0;
+let carriedTokens = 0;
+let currentTokens = 0;
+let pauseStartedAt = 0;
+/** 并行工具调用数；>0 时瞬时采样暂停。 */
+let activeTools = 0;
+let lastRate = 0;
+let lastLiveRate = 0;
+let firstTokenAt = 0;
+let samples: TokenSample[] = [];
+let usageAnchorTime = 0;
+let usageAnchorTokens = 0;
+let countedUsage = 0;
+
+/** 新的用户指令：重置计时、累计 token、定格值与 TTFT。 */
+export function resetTokenRate(startAt = 0): void {
+	runStartTime = startAt;
+	carriedTokens = 0;
+	currentTokens = 0;
+	pauseStartedAt = 0;
+	activeTools = 0;
+	lastRate = 0;
+	lastLiveRate = 0;
+	firstTokenAt = 0;
+	samples = [];
+	usageAnchorTime = 0;
+	usageAnchorTokens = 0;
+	countedUsage = 0;
+}
+
+/**
+ * 一段 assistant 回复结束：保留计时与 TTFT，把本段已计 token 结算进累计。
+ * 下一段的 token 从 0 重计，采样时加回来。
+ */
+export function carryTokenRate(): void {
+	if (currentTokens > 0) carriedTokens += currentTokens;
+	currentTokens = 0;
+	countedUsage = 0;
+}
+
+/** 工具开始执行：计数 +1，第一个工具才真正暂停瞬时采样。 */
+export function pauseTokenRate(now = Date.now()): void {
+	if (!runStartTime) return;
+	activeTools += 1;
+	if (activeTools === 1 && !pauseStartedAt) pauseStartedAt = now;
+}
+
+/** 工具执行结束：计数 -1，最后一个工具结束才恢复采样。 */
+export function resumeTokenRate(): void {
+	activeTools = Math.max(0, activeTools - 1);
+	if (activeTools === 0 && pauseStartedAt) {
+		pauseStartedAt = 0;
+	}
+}
+
+/** 本指令第一个内容块开始时调用；同一指令后续消息不覆盖。 */
+export function markFirstToken(now = Date.now()): void {
+	if (runStartTime && !firstTokenAt) firstTokenAt = now;
+}
+
+function estimateTokens(text: string): number {
+	if (!text) return 0;
+	const cjk = text.match(CJK_CHARS)?.length ?? 0;
+	return Math.ceil(cjk + (text.length - cjk) / 4);
+}
+
+function pushSample(time: number, cum: number): void {
+	samples.push({ t: time, cum });
+	const cutoff = time - LIVE_WINDOW_MS;
+	while (samples.length > 1 && samples[0]!.t < cutoff) samples.shift();
+}
+
+function updateRates(now: number): void {
+	const total = carriedTokens + currentTokens;
+	const elapsed = (now - runStartTime) / 1000;
+	if (elapsed > 0) lastRate = total / elapsed;
+	if (samples.length < 2) return;
+	const first = samples[0]!;
+	const last = samples[samples.length - 1]!;
+	const span = last.t - first.t;
+	if (span >= MIN_SPAN_MS) {
+		lastLiveRate = ((last.cum - first.cum) * 1000) / span;
+	}
+}
+
+/** 每个文本增量采样一次。工具暂停期的增量只累计 token，不进窗口。 */
+export function sampleTokenDelta(delta: string, now = Date.now()): void {
+	if (!runStartTime) return;
+	const added = estimateTokens(delta);
+	if (added <= 0) return;
+	currentTokens += added;
+	if (pauseStartedAt) return;
+	pushSample(now, carriedTokens + currentTokens);
+	updateRates(now);
+}
+
+/**
+ * 记录本段 provider `usage.output`。usage 按锚点摊回窗口：
+ * 首次报告从消息起点铺到现在，之后每次把增量摊在上次报告之后。
+ */
+export function recordProviderUsage(output: number, now = Date.now()): void {
+	if (!runStartTime || output <= 0) return;
+	const firstReport = countedUsage === 0;
+	const jump = output - countedUsage;
+	countedUsage = output;
+	// provider 是权威计数；首次报告以它为准，之后增量接管。
+	currentTokens = output;
+	if (firstReport) {
+		samples = samples.filter((sample) => sample.t < usageAnchorTime);
+		pushSample(usageAnchorTime, carriedTokens + usageAnchorTokens);
+	}
+	const span = Math.max(now - usageAnchorTime, 1);
+	const count = Math.min(Math.max(Math.ceil(jump / 16), 1), 32);
+	const base = firstReport
+		? carriedTokens + usageAnchorTokens
+		: carriedTokens + currentTokens - jump;
+	for (let i = 1; i <= count; i++) {
+		pushSample(usageAnchorTime + (span * i) / count, base + (jump * i) / count);
+	}
+	usageAnchorTime = now;
+	usageAnchorTokens = currentTokens;
+	updateRates(now);
+}
+
+/** 本段消息开始：重置 provider 锚点。 */
+export function startMessageSegment(now = Date.now()): void {
+	if (!runStartTime) return;
+	usageAnchorTime = now;
+	usageAnchorTokens = currentTokens;
+	countedUsage = 0;
+}
+
+/** 整段指令的累计 token 数：已结转段 + 当前段。 */
+export function totalTokens(): number {
+	return carriedTokens + currentTokens;
+}
+
+/** average 的当前值：指令中为实时平均，指令外为上一段定格值。 */
+export function currentTokenRate(): number {
+	return lastRate;
+}
+
+/**
+ * 按显示模式取值。live 在生成中取窗口速率，窗口数据不足或指令结束后回到整段平均。
+ * 工具暂停期间时钟不动，显示上一条窗口值。
+ */
+export function displayTokenRate(mode: TokenRateMode): number {
+	if (mode === "live" && samples.length >= 2 && lastLiveRate > 0) {
+		return lastLiveRate;
+	}
+	return lastRate;
+}
+
+/** 本指令 TTFT（毫秒）；未出首 token 或无活动指令返回 0。定格后保留。 */
+export function currentTtftMs(): number {
+	if (!runStartTime || !firstTokenAt) return 0;
+	return Math.max(0, firstTokenAt - runStartTime);
+}
+
+/** `avg 1.2k tok/s (TTFT: 812ms)`；无数据显示空串，未出首 token 时无括号段。 */
+export function formatTokenRate(rate: number, ttftMs = 0, mode: TokenRateMode = "average"): string {
+	if (!Number.isFinite(rate) || rate <= 0) return "";
+	const value = rate >= 1000 ? `${(rate / 1000).toFixed(1)}k` : `${Math.round(rate)}`;
+	const ttft = Number.isFinite(ttftMs) && ttftMs > 0 ? ` (TTFT: ${Math.round(ttftMs)}ms)` : "";
+	const label = mode === "live" ? "live" : "avg";
+	return `${label} ${value} tok/s${ttft}`;
+}