pi-firecode 0.8.0

package/session/herdr-display.ts

@@ -0,0 +1,87 @@
+/**
+ * 把 pi 的会话身份投影到 herdr agent 副标题：`pi·模型/思考等级` + 会话名。
+ * 会话名同时以 `session` 自定义 token 上报，供 herdr 侧边栏 `$session` 行布局显示；
+ * 只写带 source 的 pane 显示元数据，不碰持久 pane/tab 名；失败静默，不影响会话。
+ * herdr 之外、非 TUI 模式或 Master Worker 内自我禁用。
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { formatModelName } from "../format.js";
+import { herdrPaneEnv, herdrRequest } from "../herdr-client.js";
+
+const SOURCE = "firecode";
+
+/** herdr 按 seq 丢弃过期上报，同一 pane 的元数据必须单调递增。 */
+let seq = Date.now() * 1000;
+const nextSeq = () => (seq += 1);
+
+type Identity = { title: string; agent: string };
+
+export function projectIdentity(
+	sessionName: string | undefined,
+	modelId: string | undefined,
+	thinking: string | undefined,
+): Identity {
+	const level = thinking && thinking !== "off" ? `/${thinking}` : "";
+	return {
+		title: sessionName ?? "",
+		agent: `pi·${formatModelName(modelId)}${level}`,
+	};
+}
+
+export function registerHerdrDisplay(pi: ExtensionAPI, subsession = false): void {
+	const env = herdrPaneEnv();
+	if (!env || subsession) return;
+	const paneId = env.paneId;
+
+	let chain = Promise.resolve();
+	let published: string | undefined;
+	/** 链尾意图：最近一次入队的身份。去重必须以它为准——拿已确认身份提前返回
+	 * 会让 A→B→A 快速切回把过时的 B 留在 pane 上；同时它挡住同身份密集事件的重发。
+	 * 失败且仍是链尾时清空，保持「失败静默并由下一事件重试」的既有语义。 */
+	let enqueued: string | undefined;
+
+	const publish = (identity: Identity): Promise<void> => {
+		const key = `${identity.title}\u0000${identity.agent}`;
+		if (key === (enqueued ?? published)) return chain;
+		enqueued = key;
+		chain = chain.then(async () => {
+			const delivered = await herdrRequest(SOURCE, "pane.report_metadata", {
+				pane_id: paneId,
+				source: SOURCE,
+				display_agent: identity.agent || null,
+				clear_display_agent: !identity.agent,
+				title: identity.title || null,
+				clear_title: !identity.title,
+				// 侧边栏行布局只能消费自定义 token（title 不在 token 集里）；null 即清除。
+				tokens: { session: identity.title || null },
+				seq: nextSeq(),
+			});
+			published = delivered ? key : undefined;
+			if (!delivered && enqueued === key) enqueued = undefined;
+		});
+		return chain;
+	};
+
+	const sync = (ctx: ExtensionContext): Promise<void> =>
+		ctx.mode === "tui"
+			? publish(
+					projectIdentity(
+						ctx.sessionManager.getSessionName(),
+						ctx.model?.id,
+						ctx.model?.reasoning ? pi.getThinkingLevel() : undefined,
+					),
+				)
+			: Promise.resolve();
+
+	pi.on("session_start", (_event, ctx) => sync(ctx));
+	// 覆盖 /rename、快捷键与 pi 自动命名：宿主已把改名收口到这一个事件。
+	pi.on("session_info_changed", (_event, ctx) => sync(ctx));
+	pi.on("model_select", (_event, ctx) => sync(ctx));
+	pi.on("thinking_level_select", (_event, ctx) => sync(ctx));
+	// quit 后 pane 退回 shell；其它 session 切换会立刻由新 session_start 覆盖。
+	pi.on("session_shutdown", (event, ctx) =>
+		event.reason === "quit" && ctx.mode === "tui"
+			? publish({ title: "", agent: "" })
+			: undefined,
+	);
+}

package/session/presets.ts

@@ -0,0 +1,257 @@
+/**
+ * 预设：一键切换模型、思考等级、工具集与附加指令。
+ * 入口有 `--preset`、`/preset [名字]`、Option+1-9、Ctrl+Shift+U 循环。
+ * 预设定义见 firecode/config.jsonc 的 presets 节。
+ */
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+import { type Preset, loadConfig } from "../config.js";
+
+const CLEAR_ITEM = "（无）";
+const INSTRUCTIONS_PREVIEW_CHARS = 30;
+const SELECTOR_MAX_ROWS = 10;
+
+/** 会话可用的等级比预设可配置的多（含 max），快照要按前者存。 */
+type OriginalState = {
+	model: Model<Api> | undefined;
+	thinkingLevel: ReturnType<ExtensionAPI["getThinkingLevel"]>;
+	tools: string[];
+};
+
+const title = (text: string): string =>
+	text ? `${text[0].toUpperCase()}${text.slice(1)}` : text;
+
+function describe(preset: Preset): string {
+	const parts: string[] = [];
+	if (preset.provider && preset.model) parts.push(`${preset.provider}/${preset.model}`);
+	if (preset.thinkingLevel) parts.push(`thinking:${preset.thinkingLevel}`);
+	if (preset.tools) parts.push(`tools:${preset.tools.join(",")}`);
+	if (preset.instructions) {
+		const preview =
+			preset.instructions.length > INSTRUCTIONS_PREVIEW_CHARS
+				? `${preset.instructions.slice(0, INSTRUCTIONS_PREVIEW_CHARS - 3)}...`
+				: preset.instructions;
+		parts.push(`"${preview}"`);
+	}
+	return parts.join(" | ");
+}
+
+export function registerPresets(pi: ExtensionAPI): void {
+	let presets: Record<string, Preset> = {};
+	let activeName: string | undefined;
+	let activePreset: Preset | undefined;
+	let originalState: OriginalState | undefined;
+
+	pi.registerFlag("preset", {
+		description: "要启用的预设名",
+		type: "string",
+	});
+
+	const updateStatus = (ctx: ExtensionContext) =>
+		ctx.ui.setStatus(
+			"preset",
+			activeName ? ctx.ui.theme.fg("accent", `🧩 ${title(activeName)}`) : undefined,
+		);
+
+	const noPresetsHint = (ctx: ExtensionContext) =>
+		ctx.ui.notify("未定义任何预设。在 firecode/config.jsonc 的 presets 里添加。", "warning");
+
+	async function applyPreset(name: string, preset: Preset, ctx: ExtensionContext): Promise<void> {
+		// 首次应用前留一份快照，用于恢复默认。
+		if (activeName === undefined) {
+			originalState = {
+				model: ctx.model,
+				thinkingLevel: pi.getThinkingLevel(),
+				tools: pi.getActiveTools(),
+			};
+		}
+
+		if (preset.provider && preset.model) {
+			const model = ctx.modelRegistry.find(preset.provider, preset.model);
+			if (!model) {
+				ctx.ui.notify(
+					`Preset "${name}": Model ${preset.provider}/${preset.model} not found`,
+					"warning",
+				);
+			} else if (!(await pi.setModel(model))) {
+				ctx.ui.notify(
+					`Preset "${name}": No API key for ${preset.provider}/${preset.model}`,
+					"warning",
+				);
+			}
+		}
+
+		if (preset.thinkingLevel) pi.setThinkingLevel(preset.thinkingLevel);
+
+		if (preset.tools?.length) {
+			const known = new Set(pi.getAllTools().map((tool) => tool.name));
+			const valid = preset.tools.filter((tool) => known.has(tool));
+			const unknown = preset.tools.filter((tool) => !known.has(tool));
+			if (unknown.length)
+				ctx.ui.notify(`预设「${name}」含未知工具：${unknown.join("、")}`, "warning");
+			if (valid.length) pi.setActiveTools(valid);
+		}
+
+		activeName = name;
+		activePreset = preset;
+	}
+
+	async function activate(name: string, ctx: ExtensionContext): Promise<void> {
+		const preset = presets[name];
+		if (!preset) return;
+		await applyPreset(name, preset, ctx);
+		ctx.ui.notify(`已切换预设「${name}」`, "info");
+		updateStatus(ctx);
+	}
+
+	async function clearPreset(ctx: ExtensionContext): Promise<void> {
+		activeName = undefined;
+		activePreset = undefined;
+		if (originalState) {
+			if (originalState.model) await pi.setModel(originalState.model);
+			pi.setThinkingLevel(originalState.thinkingLevel);
+			pi.setActiveTools(originalState.tools);
+		}
+		ctx.ui.notify("预设已清除，恢复默认", "info");
+		updateStatus(ctx);
+	}
+
+	async function showSelector(ctx: ExtensionContext): Promise<void> {
+		const names = Object.keys(presets);
+		if (names.length === 0) {
+			noPresetsHint(ctx);
+			return;
+		}
+
+		const items: SelectItem[] = names.map((name) => ({
+			value: name,
+			label: name === activeName ? `${name}（当前）` : name,
+			description: describe(presets[name]),
+		}));
+		items.push({
+			value: CLEAR_ITEM,
+			label: CLEAR_ITEM,
+			description: "清除当前预设，恢复默认",
+		});
+
+		const choice = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
+			container.addChild(new Text(theme.fg("accent", theme.bold("选择预设"))));
+
+			const selectList = new SelectList(items, Math.min(items.length, SELECTOR_MAX_ROWS), {
+				selectedPrefix: (text) => theme.fg("accent", text),
+				selectedText: (text) => theme.fg("accent", text),
+				description: (text) => theme.fg("muted", text),
+				scrollInfo: (text) => theme.fg("dim", text),
+				noMatch: (text) => theme.fg("warning", text),
+			});
+			selectList.onSelect = (item) => done(item.value);
+			selectList.onCancel = () => done(null);
+			container.addChild(selectList);
+			container.addChild(new Text(theme.fg("dim", "↑↓ 选择 • enter 确认 • esc 取消")));
+			container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
+
+			return {
+				render: (width: number) => container.render(width),
+				invalidate: () => container.invalidate(),
+				handleInput(data: string) {
+					selectList.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		});
+
+		if (!choice) return;
+		if (choice === CLEAR_ITEM) await clearPreset(ctx);
+		else await activate(choice, ctx);
+	}
+
+	async function cyclePreset(ctx: ExtensionContext): Promise<void> {
+		const names = Object.keys(presets);
+		if (names.length === 0) {
+			noPresetsHint(ctx);
+			return;
+		}
+		const cycle = [CLEAR_ITEM, ...names];
+		const current = cycle.indexOf(activeName ?? CLEAR_ITEM);
+		const next = cycle[current === -1 ? 0 : (current + 1) % cycle.length];
+		if (next === CLEAR_ITEM) await clearPreset(ctx);
+		else await activate(next, ctx);
+	}
+
+	const { keys, presets: configured } = loadConfig().config;
+
+	pi.registerShortcut(keys.cyclePreset as never, {
+		description: "轮切预设",
+		handler: (ctx) => cyclePreset(ctx),
+	});
+
+	for (const [name, preset] of Object.entries(configured)) {
+		if (!preset.key) continue;
+		pi.registerShortcut(preset.key as never, {
+			description: `启用预设「${name}」`,
+			handler: (ctx) => activate(name, ctx),
+		});
+	}
+
+	pi.registerCommand("preset", {
+		description: "切换预设",
+		handler: async (args, ctx) => {
+			const name = args?.trim();
+			if (!name) {
+				await showSelector(ctx);
+				return;
+			}
+			if (!presets[name]) {
+				const available = Object.keys(presets).join(", ") || "(none defined)";
+				ctx.ui.notify(`未知预设「${name}」，可用：${available}`, "error");
+				return;
+			}
+			await activate(name, ctx);
+		},
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (!activePreset?.instructions) return;
+		return { systemPrompt: `${event.systemPrompt}\n\n${activePreset.instructions}` };
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		// 配置问题由 index.ts 统一提示，这里只取预设。
+		presets = loadConfig().config.presets;
+
+		const flag = pi.getFlag("preset");
+		if (typeof flag === "string" && flag) {
+			if (presets[flag]) {
+				await applyPreset(flag, presets[flag], ctx);
+				ctx.ui.notify(`已切换预设「${flag}」`, "info");
+			} else {
+				const available = Object.keys(presets).join(", ") || "(none defined)";
+				ctx.ui.notify(`未知预设「${flag}」，可用：${available}`, "warning");
+			}
+		} else {
+			// 恢复上次会话的预设：只认名字，不重放模型与工具切换。
+			const restored = ctx.sessionManager
+				.getEntries()
+				.filter(
+					(entry: { type: string; customType?: string }) =>
+						entry.type === "custom" && entry.customType === "preset-state",
+				)
+				.pop() as { data?: { name: string } } | undefined;
+			const name = restored?.data?.name;
+			if (name && presets[name]) {
+				activeName = name;
+				activePreset = presets[name];
+			}
+		}
+
+		updateStatus(ctx);
+	});
+
+	pi.on("turn_start", async () => {
+		if (activeName) pi.appendEntry("preset-state", { name: activeName });
+	});
+}

package/session/rename.ts

@@ -0,0 +1,46 @@
+/** 会话重命名：`/rename <name>` 与 config.keys.rename，只改 pi 会话名。 */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config.js";
+
+const MAX_TITLE_CHARS = 160;
+const CONTROL_CHARS = /[\x00-\x1f\x7f-\x9f]/g;
+const INVISIBLE_CHARS = /[\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g;
+
+function cleanTitle(raw: string): string {
+	const title = raw
+		.replace(CONTROL_CHARS, " ")
+		.replace(INVISIBLE_CHARS, "")
+		.replace(/\s+/g, " ")
+		.trim();
+	return Array.from(title).slice(0, MAX_TITLE_CHARS).join("");
+}
+
+export function registerSessionName(pi: ExtensionAPI): void {
+	const rename = (ctx: ExtensionContext, name: string) => {
+		pi.setSessionName(name);
+		ctx.ui.notify(`会话已改名：${name}`, "info");
+	};
+
+	pi.registerShortcut(loadConfig().config.keys.rename as never, {
+		description: "重命名当前会话",
+		handler: async (ctx) => {
+			if (!ctx.hasUI) return;
+			const current = pi.getSessionName() ?? "";
+			const next = await ctx.ui.input("重命名会话", current || "新名字");
+			const name = cleanTitle(next ?? "");
+			if (name) rename(ctx, name);
+		},
+	});
+
+	pi.registerCommand("rename", {
+		description: "重命名当前会话",
+		handler: async (args, ctx) => {
+			const name = cleanTitle(args);
+			if (!name) {
+				ctx.ui.notify("用法：/rename <新名字>", "error");
+				return;
+			}
+			rename(ctx, name);
+		},
+	});
+}

package/session/stats.ts

@@ -0,0 +1,310 @@
+/**
+ * 会话 token / 成本统计：扫描 sessions 下的 jsonl，按模型汇总后用 Markdown 展示。
+ * 源自 pi-token-stats (MIT, https://github.com/reaishijie/pi-token-stats)，已精简。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder, getAgentDir, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { type AutocompleteItem, Container, Markdown, Text, matchesKey } from "@earendil-works/pi-tui";
+
+const DEFAULT_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+type Usage = {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	totalTokens?: number;
+	cost?: { total?: number };
+};
+
+export type SessionLine = {
+	type?: string;
+	timestamp?: string;
+	usage?: Usage;
+	message?: { role?: string; provider?: string; model?: string; usage?: Usage; timestamp?: number };
+};
+
+export type UsageAttribution = {
+	provider: string;
+	model: string;
+	usage: Usage;
+	timestamp?: number;
+	countRequest: boolean;
+};
+
+/** 与 pi 的 usage-totals 对齐：assistant 归模型，工具与压缩归 tools/summaries。 */
+export function usageAttribution(entry: SessionLine): UsageAttribution | undefined {
+	const at = (fallback?: number) => fallback ?? (entry.timestamp ? Date.parse(entry.timestamp) : undefined);
+
+	if (entry.type === "message" && entry.message?.usage) {
+		const { role, provider, model, usage, timestamp } = entry.message;
+		if (role === "assistant") {
+			return {
+				provider: provider ?? "unknown",
+				model: model ?? "unknown",
+				usage,
+				timestamp: at(timestamp),
+				countRequest: true,
+			};
+		}
+		if (role === "toolResult") {
+			return { provider: "tools", model: "summaries", usage, timestamp: at(timestamp), countRequest: false };
+		}
+		return undefined;
+	}
+
+	if ((entry.type === "compaction" || entry.type === "branch_summary") && entry.usage) {
+		return { provider: "tools", model: "summaries", usage: entry.usage, timestamp: at(), countRequest: false };
+	}
+	return undefined;
+}
+
+type Totals = {
+	requests: number;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	tokens: number;
+	cost: number;
+};
+
+const emptyTotals = (): Totals => ({
+	requests: 0,
+	input: 0,
+	output: 0,
+	cacheRead: 0,
+	cacheWrite: 0,
+	tokens: 0,
+	cost: 0,
+});
+
+function add(target: Totals, usage: Usage, countRequest: boolean): void {
+	const input = usage.input ?? 0;
+	const output = usage.output ?? 0;
+	const cacheRead = usage.cacheRead ?? 0;
+	const cacheWrite = usage.cacheWrite ?? 0;
+
+	if (countRequest) target.requests += 1;
+	target.input += input;
+	target.output += output;
+	target.cacheRead += cacheRead;
+	target.cacheWrite += cacheWrite;
+	target.tokens += usage.totalTokens ?? input + output + cacheRead + cacheWrite;
+	target.cost += usage.cost?.total ?? 0;
+}
+
+function sessionFiles(dir: string): string[] {
+	if (!existsSync(dir)) return [];
+
+	const found: string[] = [];
+	const pending = [dir];
+	while (pending.length > 0) {
+		const current = pending.pop() as string;
+		let entries: string[];
+		try {
+			entries = readdirSync(current);
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const path = join(current, entry);
+			try {
+				if (statSync(path).isDirectory()) pending.push(path);
+				else if (entry.endsWith(".jsonl")) found.push(path);
+			} catch {
+				// 会话文件可能在扫描过程中被轮转掉。
+			}
+		}
+	}
+	return found;
+}
+
+type Report = {
+	days: number;
+	from?: number;
+	to: number;
+	dir: string;
+	scanned: number;
+	matched: number;
+	overall: Totals;
+	byModel: Map<string, Totals>;
+};
+
+function collect(days: number): Report {
+	const to = Date.now();
+	const from = days === 0 ? undefined : to - days * DAY_MS;
+	const dir = join(getAgentDir(), "sessions");
+	const files = sessionFiles(dir);
+	const report: Report = {
+		days,
+		from,
+		to,
+		dir,
+		scanned: files.length,
+		matched: 0,
+		overall: emptyTotals(),
+		byModel: new Map(),
+	};
+
+	for (const file of files) {
+		let content: string;
+		try {
+			content = readFileSync(file, "utf8");
+		} catch {
+			continue;
+		}
+
+		let matched = false;
+		for (const line of content.split("\n")) {
+			if (!line.trim()) continue;
+
+			let attributed: UsageAttribution | undefined;
+			try {
+				attributed = usageAttribution(JSON.parse(line) as SessionLine);
+			} catch {
+				continue;
+			}
+			if (!attributed) continue;
+			if (from !== undefined && attributed.timestamp !== undefined && attributed.timestamp < from) continue;
+
+			const key = `${attributed.provider}/${attributed.model}`;
+			let model = report.byModel.get(key);
+			if (!model) {
+				model = emptyTotals();
+				report.byModel.set(key, model);
+			}
+			add(report.overall, attributed.usage, attributed.countRequest);
+			add(model, attributed.usage, attributed.countRequest);
+			matched = true;
+		}
+
+		if (matched) report.matched += 1;
+	}
+
+	return report;
+}
+
+const number = (value: number): string => new Intl.NumberFormat("en-US").format(Math.round(value));
+
+const compactTokens = (value: number): string => {
+	const rounded = Math.round(value);
+	if (rounded >= 100_000_000) return `${(rounded / 100_000_000).toFixed(1)}亿`;
+	if (rounded >= 10_000) return `${(rounded / 10_000).toFixed(1)}万`;
+	return number(rounded);
+};
+
+const cost = (value: number): string => `$${value.toFixed(value >= 1 ? 2 : 4)}`;
+
+const dateTime = (value: number): string => {
+	const date = new Date(value);
+	const pad = (part: number) => part.toString().padStart(2, "0");
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+};
+
+const row = (cells: Array<string | number>): string => `| ${cells.join(" | ")} |`;
+
+const totalsCells = (totals: Totals): string[] => [
+	number(totals.input),
+	number(totals.output),
+	number(totals.cacheRead),
+	number(totals.cacheWrite),
+	compactTokens(totals.tokens),
+	cost(totals.cost),
+];
+
+function buildMarkdown(report: Report): string {
+	const range =
+		report.days === 0
+			? "全部"
+			: `最近 ${report.days} 天（${dateTime(report.from as number)} ~ ${dateTime(report.to)}）`;
+	const headers = ["输入", "输出", "缓存读", "缓存写", "总 Token", "成本"];
+	const aligns = headers.map(() => "---:");
+	const lines = [
+		"# Token 用量",
+		"",
+		`- 范围：${range}`,
+		`- 会话：命中 ${number(report.matched)} / 扫描 ${number(report.scanned)} 个文件`,
+		`- 请求：${number(report.overall.requests)} 次，合计 ${cost(report.overall.cost)}`,
+		"",
+		row(headers),
+		row(aligns),
+		row(totalsCells(report.overall)),
+		"",
+		"## 按模型",
+		"",
+	];
+
+	const models = [...report.byModel.entries()].sort((left, right) => right[1].tokens - left[1].tokens);
+	if (models.length === 0) {
+		lines.push("该范围内没有用量记录。");
+		return lines.join("\n");
+	}
+
+	lines.push(row(["模型", "请求", ...headers]));
+	lines.push(row(["---", "---:", ...aligns]));
+	for (const [key, totals] of models) {
+		lines.push(row([`\`${key}\``, number(totals.requests), ...totalsCells(totals)]));
+	}
+	return lines.join("\n");
+}
+
+async function show(markdown: string, ctx: ExtensionCommandContext): Promise<void> {
+	if (ctx.mode !== "tui") {
+		console.log(markdown);
+		return;
+	}
+
+	await ctx.ui.custom((_tui, theme, _keybindings, done) => {
+		const container = new Container();
+		const border = new DynamicBorder((text: string) => theme.fg("accent", text));
+		container.addChild(border);
+		container.addChild(new Markdown(markdown, 1, 1, getMarkdownTheme()));
+		container.addChild(new Text(theme.fg("dim", "Enter / Esc 关闭"), 1, 0));
+		container.addChild(border);
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				if (matchesKey(data, "enter") || matchesKey(data, "escape")) done(undefined);
+			},
+		};
+	});
+}
+
+/** 支持 `/tokens 7`、`/tokens --days 7`、`/tokens 0`（全部）。 */
+export function parseDays(args: string | undefined): number {
+	const text = (args ?? "").trim();
+	if (!text) return DEFAULT_DAYS;
+
+	const matched = text.match(/(?:^|\s)(?:--days|-d)\s+(\d+)(?:\s|$)/i) ?? text.match(/^(\d+)\s*d?$/i);
+	const value = Number.parseInt(matched?.[1] ?? "", 10);
+	return Number.isFinite(value) ? value : DEFAULT_DAYS;
+}
+
+const dayCompletions: AutocompleteItem[] = [
+	{ value: "7", label: "7", description: "最近 7 天" },
+	{ value: "30", label: "30", description: "最近 30 天（默认）" },
+	{ value: "0", label: "0", description: "全部历史" },
+];
+
+export function registerStats(pi: ExtensionAPI): void {
+	pi.registerCommand("tokens", {
+		description: "统计会话 token 与成本，参数为天数：默认 30，0 表示全部",
+		getArgumentCompletions: (prefix: string) => {
+			const matches = dayCompletions.filter((item) => item.value.startsWith(prefix.trim()));
+			return matches.length > 0 ? matches : null;
+		},
+		handler: async (args: string | undefined, ctx: ExtensionCommandContext) => {
+			const days = parseDays(args);
+			if (ctx.hasUI) {
+				ctx.ui.notify(`统计中（${days === 0 ? "全部历史" : `最近 ${days} 天`}）…`, "info");
+			}
+			await show(buildMarkdown(collect(days)), ctx);
+		},
+	});
+}