@bachi/pi-coder 1.0.0

package/extensions/working-indicator/spinner-frames.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Tests for spinner-frames.ts — working spinner 幻彩帧表的排布、去重与主题指纹。
+ *
+ * Run with:  node --test clients/pi/extensions/working-indicator/spinner-frames.test.ts
+ *
+ * 被测模块不 import pi / pi-tui，断言直接比对帧字符串的「颜色前缀 + 盲文字符」两段。
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+	DEFAULT_FRAMES_PER_COLOR,
+	SPINNER_COLOR_TOKENS,
+	SPINNER_FRAMES,
+	SPINNER_INTERVAL_MS,
+	buildSpinnerPalette,
+	type SpinnerColorize,
+} from "./spinner-frames.ts";
+
+/** 七个色槽各给一个可区分的「颜色」；`fg` 的形状就是「颜色前缀 + 原文」。 */
+const DISTINCT: Record<string, string> = Object.fromEntries(
+	SPINNER_COLOR_TOKENS.map((token, index) => [token, `<c${index}>`]),
+);
+
+/** 与模块内部同一口径的独立实现，用来交叉验证帧表周期（测公倍数性质，不是抄公式）。 */
+function gcd(a: number, b: number): number {
+	return b === 0 ? a : gcd(b, a % b);
+}
+
+/** 帧表周期的独立算法：lcm(盲文帧数, 每色帧数 × 颜色数)。 */
+function expectedPeriod(framesPerColor: number, colorCount: number): number {
+	const colorCycle = framesPerColor * colorCount;
+	return (10 * colorCycle) / gcd(10, colorCycle);
+}
+
+/** 假主题：`colorize(token, text)` → `颜色 + text`（与 `theme.fg` 同形，颜色靠前缀区分）。 */
+function fakeTheme(colors: Record<string, string>): SpinnerColorize {
+	return (token, text) => `${colors[token] ?? `<${token}>`}${text}`;
+}
+
+/** 从帧字符串里取回颜色前缀（盲文帧都在 BMP 内，各占 1 个 UTF-16 单元）。 */
+function colorOf(frame: string, colors: Record<string, string>): string {
+	for (const color of Object.values(colors)) {
+		if (frame.startsWith(color) && frame.length === color.length + 1) return color;
+	}
+	throw new Error(`帧里没有已知颜色前缀：${frame}`);
+}
+
+/** 从帧字符串里取回盲文字符。 */
+function frameOf(frame: string): string {
+	return frame.at(-1) as string;
+}
+
+/** 颜色段：连续同色帧合并成一段。 */
+function colorRuns(frames: string[], colors: Record<string, string>): Array<{ color: string; length: number }> {
+	const runs: Array<{ color: string; length: number }> = [];
+	for (const frame of frames) {
+		const color = colorOf(frame, colors);
+		const last = runs.at(-1);
+		if (last !== undefined && last.color === color) last.length += 1;
+		else runs.push({ color, length: 1 });
+	}
+	return runs;
+}
+
+/**
+ * 换色点在圈内的**相位**（帧号 % 10）：集合里只有一个元素 = 每圈都在盲文的同一位置换色，
+ * 多元素 = 换色点逐圈漂移（`framesPerColor` 不整除 10 时）。
+ */
+function changePhases(frames: string[], colors: Record<string, string>): Set<number> {
+	const phases = new Set<number>();
+	for (const [index, frame] of frames.entries()) {
+		if (index === 0) continue;
+		if (colorOf(frame, colors) !== colorOf(frames[index - 1] as string, colors)) {
+			phases.add(index % SPINNER_FRAMES.length);
+		}
+	}
+	return phases;
+}
+
+describe("buildSpinnerPalette 的帧表排布", () => {
+	it("没有配置时用七个色槽、每色 19 帧（默认值），周期 1330 帧", () => {
+		const palette = buildSpinnerPalette(fakeTheme(DISTINCT));
+		assert.deepEqual(palette.tokens, [...SPINNER_COLOR_TOKENS]);
+		assert.equal(DEFAULT_FRAMES_PER_COLOR, 19);
+		assert.equal(SPINNER_INTERVAL_MS, 80);
+		// 19 帧 × 80ms = 1520ms ≈ 1.5s 一换色；周期 = lcm(10, 19 × 7) = 1330 帧 ≈ 106s。
+		assert.equal(palette.frames?.length, 1330);
+		assert.equal(palette.frames?.length, expectedPeriod(19, 7));
+	});
+
+	it("旋转照旧：第 i 帧的盲文就是 pi 默认序列的第 i % 10 帧", () => {
+		const frames = buildSpinnerPalette(fakeTheme(DISTINCT)).frames as string[];
+		for (const [index, frame] of frames.entries()) {
+			assert.equal(frameOf(frame), SPINNER_FRAMES[index % SPINNER_FRAMES.length]);
+		}
+	});
+
+	it("颜色按帧数推进：每段恰好 framesPerColor 帧，顺序就是 tokens 顺序", () => {
+		const runs = colorRuns(buildSpinnerPalette(fakeTheme(DISTINCT)).frames as string[], DISTINCT);
+		assert.equal(runs.length, 70); // 1330 帧 / 每段 19 帧
+		assert.ok(runs.every((run) => run.length === DEFAULT_FRAMES_PER_COLOR));
+		for (const [index, run] of runs.entries()) {
+			assert.equal(run.color, DISTINCT[SPINNER_COLOR_TOKENS[index % SPINNER_COLOR_TOKENS.length] as string]);
+		}
+	});
+
+	it("默认帧表回绕无缝：末帧是本圈末帧 + 调色板末色，换色点相位遍历全部 10 个位置", () => {
+		const frames = buildSpinnerPalette(fakeTheme(DISTINCT)).frames as string[];
+		const last = frames[frames.length - 1] as string;
+		assert.equal(frameOf(last), SPINNER_FRAMES[9]);
+		assert.equal(colorOf(last, DISTINCT), DISTINCT["toolTitle"]);
+		assert.equal(frameOf(frames[0] as string), SPINNER_FRAMES[0]);
+		assert.equal(colorOf(frames[0] as string, DISTINCT), DISTINCT["accent"]);
+
+		// 19 与盲文圈长 10 互质：换色点每换一次就往圈内错一步，相位遍历全部 10 个位置
+		// （帧表周期 lcm(10, 19 × 7) = 1330 帧 ≈ 106s，比一轮调色板的 133 帧长得多）。
+		assert.equal(frames.length, DEFAULT_FRAMES_PER_COLOR * SPINNER_COLOR_TOKENS.length * 10);
+		assert.equal(changePhases(frames, DISTINCT).size, SPINNER_FRAMES.length);
+	});
+
+	it("framesPerColor 可调：1 = 每帧换色，3 = 周期 210 帧且换色点逐圈漂移", () => {
+		const perFrame = buildSpinnerPalette(fakeTheme(DISTINCT), { framesPerColor: 1 });
+		assert.equal(perFrame.frames?.length, expectedPeriod(1, 7));
+		assert.ok(colorRuns(perFrame.frames as string[], DISTINCT).every((run) => run.length === 1));
+
+		const holdThree = buildSpinnerPalette(fakeTheme(DISTINCT), { framesPerColor: 3 });
+		assert.equal(holdThree.frames?.length, expectedPeriod(3, 7));
+		assert.ok(colorRuns(holdThree.frames as string[], DISTINCT).every((run) => run.length === 3));
+		// 3 不整除 10：换色点不在盲文的同一个位置（相位多于一个 = 彩带在圈内漂）。
+		assert.ok(changePhases(holdThree.frames as string[], DISTINCT).size > 1);
+	});
+
+	it("非法 framesPerColor：0 / 负数 / NaN / Infinity 退回默认，小数取整", () => {
+		for (const [value, hold] of [
+			[0, DEFAULT_FRAMES_PER_COLOR],
+			[-3, DEFAULT_FRAMES_PER_COLOR],
+			[Number.NaN, DEFAULT_FRAMES_PER_COLOR],
+			[Number.POSITIVE_INFINITY, DEFAULT_FRAMES_PER_COLOR],
+			[2.9, 2],
+		] as const) {
+			const palette = buildSpinnerPalette(fakeTheme(DISTINCT), { framesPerColor: value });
+			assert.equal(colorRuns(palette.frames as string[], DISTINCT)[0]?.length, hold, `framesPerColor=${value}`);
+			assert.equal(palette.frames?.length, expectedPeriod(hold, 7), `framesPerColor=${value}`);
+		}
+	});
+
+	it("tokens 可换成子集：两个色槽、每色 5 帧 → 周期 lcm(10, 10) = 10 帧", () => {
+		const palette = buildSpinnerPalette(fakeTheme(DISTINCT), { framesPerColor: 5, tokens: ["accent", "warning"] });
+		assert.deepEqual(palette.tokens, ["accent", "warning"]);
+		assert.equal(palette.frames?.length, expectedPeriod(5, 2));
+		assert.deepEqual(
+			colorRuns(palette.frames as string[], DISTINCT).map((run) => run.color),
+			[DISTINCT["accent"], DISTINCT["warning"]],
+		);
+	});
+});
+
+describe("buildSpinnerPalette 的颜色去重与降级", () => {
+	it("当前主题里同色的两个槽位只留一个（不留连续两段同色）", () => {
+		// summer-night 实测撞车：success == toolDiffAdded、warning == toolTitle。
+		const theme = fakeTheme({
+			...DISTINCT,
+			toolDiffAdded: DISTINCT["success"] as string,
+			toolTitle: DISTINCT["warning"] as string,
+		});
+		const palette = buildSpinnerPalette(theme);
+		assert.deepEqual(palette.tokens, ["accent", "success", "warning", "syntaxKeyword", "toolDiffRemoved"]);
+		assert.equal(palette.frames?.length, expectedPeriod(19, 5));
+
+		const runs = colorRuns(palette.frames as string[], DISTINCT);
+		assert.ok(runs.every((run) => run.length === 19));
+		for (const [index, run] of runs.entries()) {
+			assert.notEqual(run.color, runs[index + 1]?.color, `第 ${index} 段与下一段同色`);
+		}
+		// 撞车的是后出现的那个槽位（去重保留首次出现者）。
+		assert.ok(!palette.tokens.includes("toolDiffAdded"));
+		assert.ok(!palette.tokens.includes("toolTitle"));
+	});
+
+	it("只剩一种颜色时不下发帧表（调用方保持 pi 默认 spinner）", () => {
+		const allSame = fakeTheme(Object.fromEntries(SPINNER_COLOR_TOKENS.map((token) => [token, "<all>"])));
+		const palette = buildSpinnerPalette(allSame);
+		assert.equal(palette.frames, null);
+		assert.deepEqual(palette.tokens, ["accent"]);
+	});
+
+	it("恒等主题（NO_COLOR / 非 TUI）也是单色 → frames 为 null", () => {
+		const identity: SpinnerColorize = (_token, text) => text;
+		assert.equal(buildSpinnerPalette(identity).frames, null);
+	});
+
+	it("指纹随主题变、同主题稳定（换肤后靠它决定重装）", () => {
+		const first = buildSpinnerPalette(fakeTheme(DISTINCT)).signature;
+		assert.equal(buildSpinnerPalette(fakeTheme(DISTINCT)).signature, first);
+		assert.notEqual(buildSpinnerPalette(fakeTheme({ ...DISTINCT, accent: "<other>" })).signature, first);
+
+		// 被去重丢掉的槽位（颜色与前一个槽位撞车）改了颜色也不影响指纹 —— 它不参与轮换。
+		const signatureWithDropped = (dropped: string): string =>
+			buildSpinnerPalette(
+				fakeTheme({ ...DISTINCT, toolDiffAdded: dropped, toolTitle: DISTINCT["warning"] as string }),
+			).signature;
+		assert.equal(
+			signatureWithDropped(DISTINCT["accent"] as string),
+			signatureWithDropped(DISTINCT["success"] as string),
+		);
+	});
+
+	it("取色探针是非空文本（空串取色分辨不出色槽）", () => {
+		const probes: string[] = [];
+		buildSpinnerPalette((token, text) => {
+			probes.push(text);
+			return `${token}${text}`;
+		});
+		assert.ok(probes.length >= SPINNER_COLOR_TOKENS.length);
+		assert.ok(probes.every((text) => text.length > 0));
+	});
+});

package/extensions/working-indicator/spinner-frames.ts

@@ -0,0 +1,156 @@
+/**
+ * spinner-frames.ts — working spinner 的「幻彩」帧表：同一族盲文帧按调色板轮换颜色。
+ *
+ * 抽出来的理由与 `working-summary.ts` / `bash-spinner.ts` 相同：帧表怎么排（周期长度、
+ * 第 i 帧配哪个颜色）、调色板怎么去重、主题指纹是什么，全是纯计算，不该活在 `index.ts`
+ * 的 ctx 与定时器之间。本模块**不 import pi / pi-tui**，`node --test` 直接跑每个分支
+ * （用例见 `spinner-frames.test.ts`）；装着帧表的那半边（什么时候装、什么时候重装）在扩展里。
+ *
+ * ## 为什么只能预烘颜色
+ *
+ * pi 的 `Loader` 只有一条上色路径：默认十帧盲文交给 `spinnerColorFn`（非嵌入态就是
+ * `theme.fg("accent", frame)`），所以整条 spinner 永远一个颜色 —— 这正是本扩展要改的。
+ * 扩展的入口 `ctx.ui.setWorkingIndicator({ frames, intervalMs })` 里**自定义帧是 verbatim
+ * 渲染的**（pi 0.85.1 的 Loader：`renderIndicatorVerbatim = indicator !== undefined`，
+ * 为真时 `getRenderedIndicator()` 直接返回帧字符串、不套 `spinnerColorFn`），也就是颜色
+ * 必须由帧字符串自己带。于是「一帧一个颜色」只能把 ANSI 序列预烘进帧表；代价是换主题后
+ * 帧表不会自己更新，得重装一次（重装 = 再调一次 `setWorkingIndicator`，要不要重装由
+ * `signature` 判断）。
+ *
+ * ## 帧表怎么排
+ *
+ * Loader 每 `intervalMs`（默认 80）把帧表索引 +1 再取模回绕，**帧表顺序就是动画顺序**。
+ * 把「十帧盲文 × 若干颜色」摊平成一维数组，索引 i 的真身是
+ *
+ *     盲文 = SPINNER_FRAMES[i % 10]                        （旋转照旧，速度与 pi 默认一致）
+ *     颜色 = colors[floor(i / framesPerColor) % colors.length]
+ *
+ * 颜色是**按帧数**推进而不是每帧一换：默认 `framesPerColor = 19`。1500ms 不是 80ms 的
+ * 整数倍，19 帧 = 1520ms 是离需求（1.5s 一换色）最近的取值（差 1.3%）；演变轨迹：初版
+ * 5 帧 / 400ms 偏快 → 10 帧 / 800ms（减半）→ 19 帧 / 1520ms。每帧一换
+ * （`framesPerColor = 1`，80ms）在终端里是频闪不是幻彩；再往上就是「半天不动」——
+ * `PI_SPINNER_COLOR_HOLD` 按帧数调。
+ *
+ * 一维表必须有周期，否则回绕处会跳色：周期 = lcm(10, framesPerColor × 颜色数)，这样
+ * i 与 i+周期 的 (盲文, 颜色) 都对齐。默认 19 帧 × 7 色：一轮调色板 133 帧（10.6s，
+ * 盲文转 13.3 圈），帧表周期 lcm(10, 133) = 1330 帧（约 106s）。
+ * 19 与盲文圈长 10 互质，所以换色点每换一次就往圈内错一步、相位遍历全部 10 个位置 ——
+ * 观感是颜色在漂移的彩带，换色点不会总落在同一个盲文帧上。想让换色点固定在盲文同一
+ * 位置（每圈/每两圈换一次色）就把 `framesPerColor` 设成 10 的倍数（如 10 / 20），代价是
+ * 调色板周期与旋转周期锁相。
+ *
+ * ## 调色板
+ *
+ * 七个色槽按需求取：accent / success / warning / syntaxKeyword / toolDiffAdded /
+ * toolDiffRemoved / toolTitle（需求里的「keyword / added / removed / tool」在主题
+ * token 目录里的正式名字）。顺序就照需求这一串排列。换主题后**实际颜色可能撞车**
+ * （实测 summer-night：success 与 toolDiffAdded 同为 #8cd6a7、warning 与 toolTitle
+ * 同为 #e9c16f），撞车的槽位按 `fg` 的渲染结果去重丢掉 —— 留着会连续两段同一个颜色，
+ * 看着像动画卡住了。去重后只剩一种颜色（单色主题 / NO_COLOR）时 `frames = null`：
+ * 调用方保持 pi 默认 spinner，不要装一张每帧长得都一样的「动画」表。
+ */
+
+/** 只用到 `fg` 的主题接口 —— 沿用 `index.ts` 的 `WorkingMessageTheme` 形状，但不反向 import。 */
+export type SpinnerColorize = (token: string, text: string) => string;
+
+/** pi 默认的十帧盲文（顺序即旋转方向）。帧表沿用它：动画读起来与改动前是同一族。 */
+export const SPINNER_FRAMES: readonly string[] = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * pi 默认帧间隔（毫秒）。自定义帧必须自己给间隔（不给就退回 pi 的默认值，数值一样但
+ * 依赖 pi 的实现细节），所以这里写死一份并与 pi 的 `DEFAULT_INTERVAL_MS` 对齐 —— 它同时
+ * 是「颜色持续多久」的换算基准（`framesPerColor × SPINNER_INTERVAL_MS`）。
+ */
+export const SPINNER_INTERVAL_MS = 80;
+
+/** 参与轮换的主题色槽，按需求顺序（「幻彩」的色序）。 */
+export const SPINNER_COLOR_TOKENS: readonly string[] = [
+	"accent",
+	"success",
+	"warning",
+	"syntaxKeyword",
+	"toolDiffAdded",
+	"toolDiffRemoved",
+	"toolTitle",
+];
+
+/**
+ * 每种颜色持续的帧数（默认 19 帧 × 80ms = 1520ms ≈ 1.5s 一换色）。
+ * 1500ms 不是 80ms 的整数倍，19 是最近的帧数（1520ms，差 1.3%）。
+ */
+export const DEFAULT_FRAMES_PER_COLOR = 19;
+
+/**
+ * 取色探针字符：给 `fg` 一个非空文本，拿到的就是「该色槽的染色结果」，用来比对两个
+ * 色槽在当前主题下是否同色（`fg` 的返回值带上 ANSI 前缀，不能只看槽位名字）。
+ */
+const COLOR_PROBE = "x";
+
+export interface SpinnerPalette {
+	/** 去重后真正参与轮换的色槽（保持原顺序）。 */
+	tokens: string[];
+	/** 主题指纹：同一主题同一配色下稳定，换主题 / 换配色后必变。 */
+	signature: string;
+	/** 帧表（已上色，逐帧字符串）；`null` = 当前主题挑不出两种可区分的颜色。 */
+	frames: string[] | null;
+}
+
+function gcd(a: number, b: number): number {
+	let left = Math.abs(a);
+	let right = Math.abs(b);
+	while (right > 0) {
+		const next = left % right;
+		left = right;
+		right = next;
+	}
+	return left;
+}
+
+/** 帧表周期（帧数）：盲文圈（10）与颜色周期（每色帧数 × 颜色数）的最小公倍数。 */
+function spinnerFramePeriod(framesPerColor: number, colorCount: number): number {
+	const colorCycle = framesPerColor * colorCount;
+	return (colorCycle / gcd(SPINNER_FRAMES.length, colorCycle)) * SPINNER_FRAMES.length;
+}
+
+/** 非整数 / <1 / 非有限值一律退回默认（环境变量解析出来的数还可能是 NaN）。 */
+function normalizeFramesPerColor(value: number | undefined): number {
+	return value !== undefined && Number.isFinite(value) && value >= 1
+		? Math.floor(value)
+		: DEFAULT_FRAMES_PER_COLOR;
+}
+
+/**
+ * 按当前主题算出幻彩帧表。
+ *
+ * 颜色去重按**渲染结果**（`colorize(token, COLOR_PROBE)`）而不是槽位名字：两个槽位在当前
+ * 主题里可能是同一个颜色（见文件头）。去重后不足两种颜色就返回 `frames: null`。
+ */
+export function buildSpinnerPalette(
+	colorize: SpinnerColorize,
+	options: { framesPerColor?: number; tokens?: readonly string[] } = {},
+): SpinnerPalette {
+	const tokens = options.tokens ?? SPINNER_COLOR_TOKENS;
+	const framesPerColor = normalizeFramesPerColor(options.framesPerColor);
+
+	const seen = new Set<string>();
+	const kept: string[] = [];
+	const probes: string[] = [];
+	for (const token of tokens) {
+		const probe = colorize(token, COLOR_PROBE);
+		if (seen.has(probe)) continue;
+		seen.add(probe);
+		kept.push(token);
+		probes.push(probe);
+	}
+	const signature = probes.join("\n");
+	if (kept.length < 2) return { tokens: kept, signature, frames: null };
+
+	const frames: string[] = [];
+	const period = spinnerFramePeriod(framesPerColor, kept.length);
+	for (let index = 0; index < period; index += 1) {
+		const token = kept[Math.floor(index / framesPerColor) % kept.length] as string;
+		const frame = SPINNER_FRAMES[index % SPINNER_FRAMES.length] as string;
+		frames.push(colorize(token, frame));
+	}
+	return { tokens: kept, signature, frames };
+}

package/extensions/working-indicator/summary-request.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Tests for summary-request.ts — 「提示词太长时请模型压成一句话」的纯逻辑。
+ *
+ * Run with:  node --test clients/pi/extensions/working-indicator/summary-request.test.ts
+ *
+ * 被测模块不 import pi / pi-tui（宽度是调用方量好的列数），所以这里也喂假宽度概念：
+ * 参数直接就是列数，不需要任何测量函数。
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+	DEFAULT_TRIGGER_RATIO,
+	MAX_REQUEST_INPUT_CHARS,
+	MAX_SUMMARY_TEXT_CHARS,
+	MIN_REQUEST_BUDGET,
+	TARGET_WIDTH_RATIO,
+	buildSummaryRequestPrompt,
+	cleanSummaryText,
+	planSummaryRequest,
+} from "./summary-request.ts";
+
+describe("planSummaryRequest: trigger", () => {
+	it("does not request when the prompt fits the available width", () => {
+		assert.equal(planSummaryRequest({ promptWidth: 30, budgetWidth: 40 }).needed, false);
+		assert.equal(planSummaryRequest({ promptWidth: 40, budgetWidth: 40 }).needed, false);
+	});
+
+	it("does not request for a mild overflow (pure truncation is good enough)", () => {
+		// 显式倍数 2：截断后仍能显示一半原文，不值得请求。
+		assert.equal(planSummaryRequest({ promptWidth: 41, budgetWidth: 40, triggerRatio: 2 }).needed, false);
+		assert.equal(planSummaryRequest({ promptWidth: 79, budgetWidth: 40, triggerRatio: 2 }).needed, false);
+	});
+
+	it("requests once the prompt exceeds the budget by the trigger ratio", () => {
+		// 默认倍数 1.2：40 列的格子放下 48 列以上就请求。
+		assert.equal(planSummaryRequest({ promptWidth: 49, budgetWidth: 40 }).needed, true);
+		assert.equal(planSummaryRequest({ promptWidth: 4000, budgetWidth: 40 }).needed, true);
+	});
+
+	it("is strict about the boundary (equal to budget * ratio does not request)", () => {
+		const threshold = 40 * DEFAULT_TRIGGER_RATIO;
+		assert.equal(planSummaryRequest({ promptWidth: threshold, budgetWidth: 40 }).needed, false);
+		assert.equal(planSummaryRequest({ promptWidth: threshold + 1, budgetWidth: 40 }).needed, true);
+	});
+
+	it("honours a custom trigger ratio", () => {
+		assert.equal(planSummaryRequest({ promptWidth: 60, budgetWidth: 40, triggerRatio: 1.5 }).needed, false);
+		assert.equal(planSummaryRequest({ promptWidth: 61, budgetWidth: 40, triggerRatio: 1.5 }).needed, true);
+		// ratio 1 = 只要放不下就请求。
+		assert.equal(planSummaryRequest({ promptWidth: 41, budgetWidth: 40, triggerRatio: 1 }).needed, true);
+	});
+
+	it("never requests when the available width is too narrow to hold a useful summary", () => {
+		const plan = planSummaryRequest({ promptWidth: 10_000, budgetWidth: MIN_REQUEST_BUDGET - 1 });
+		assert.equal(plan.needed, false);
+		// 恰好到下限就允许（只要原文够长）。
+		assert.equal(planSummaryRequest({ promptWidth: 1000, budgetWidth: MIN_REQUEST_BUDGET }).needed, true);
+	});
+
+	it("honours a custom minBudget", () => {
+		assert.equal(planSummaryRequest({ promptWidth: 10_000, budgetWidth: 20, minBudget: 30 }).needed, false);
+	});
+
+	it("defaults the trigger ratio to 1.2", () => {
+		assert.equal(DEFAULT_TRIGGER_RATIO, 1.2);
+	});
+});
+
+describe("planSummaryRequest: target width", () => {
+	it("leaves headroom below the available width", () => {
+		const plan = planSummaryRequest({ promptWidth: 1000, budgetWidth: 40 });
+		assert.equal(plan.targetWidth, Math.floor(40 * TARGET_WIDTH_RATIO));
+		assert.ok(plan.targetWidth < 40, "目标必须小于可用宽度，否则模型略超一点就被截");
+	});
+
+	it("floors fractional budgets and keeps a tenth of the width as headroom", () => {
+		assert.equal(planSummaryRequest({ promptWidth: 1000, budgetWidth: 40.9 }).targetWidth, 36);
+		// 最窄的可请求格子：10 列预算 → 目标 9 列。
+		assert.equal(planSummaryRequest({ promptWidth: 1000, budgetWidth: MIN_REQUEST_BUDGET }).targetWidth, 9);
+	});
+});
+
+describe("buildSummaryRequestPrompt", () => {
+	it("states the target width and the display-column unit", () => {
+		const prompt = buildSummaryRequestPrompt("把 working 摘要改成模型压缩", 48);
+		assert.match(prompt, /48 display columns/);
+		assert.match(prompt, /CJK\/full-width character counts as 2 columns/);
+	});
+
+	it("asks for a single line without decoration and mirrors the input language", () => {
+		const prompt = buildSummaryRequestPrompt("hello", 30);
+		assert.match(prompt, /Output a single line/);
+		assert.match(prompt, /No line breaks, no quotes, no markdown/);
+		assert.match(prompt, /same language as the input/);
+	});
+
+	it("embeds the input prompt verbatim", () => {
+		const input = "优化 summary 截断逻辑\n第二行说明";
+		const prompt = buildSummaryRequestPrompt(input, 30);
+		assert.ok(prompt.includes(input), "原文应原样带上（压平等加工由调用方负责）");
+		assert.ok(prompt.trimEnd().endsWith(input));
+	});
+
+	it("clips a very long prompt to the request cap", () => {
+		const prompt = buildSummaryRequestPrompt("x".repeat(MAX_REQUEST_INPUT_CHARS + 500), 30);
+		assert.ok(prompt.includes("x".repeat(MAX_REQUEST_INPUT_CHARS)));
+		assert.ok(!prompt.includes("x".repeat(MAX_REQUEST_INPUT_CHARS + 1)), "超过上限的部分应被截掉");
+		assert.ok(prompt.includes("…"), "截断处应有省略号");
+	});
+
+	it("does not split a surrogate pair when clipping", () => {
+		const prompt = buildSummaryRequestPrompt("😀".repeat(MAX_REQUEST_INPUT_CHARS + 20), 30);
+		const clipped = prompt.slice(prompt.lastIndexOf("Input:") + "Input:".length + 1);
+		assert.ok(clipped.endsWith("😀…"), `截断点不能落在半个代理对上（实际结尾 ${JSON.stringify(clipped.slice(-3))}）`);
+	});
+});
+
+describe("cleanSummaryText", () => {
+	it("passes a plain one-liner through", () => {
+		assert.equal(cleanSummaryText("优化提示词摘要的截断逻辑"), "优化提示词摘要的截断逻辑");
+	});
+
+	it("strips a label prefix in ASCII and Chinese", () => {
+		assert.equal(cleanSummaryText("摘要：优化摘要逻辑"), "优化摘要逻辑");
+		assert.equal(cleanSummaryText("Summary: refactor the loader"), "refactor the loader");
+		assert.equal(cleanSummaryText("概括 : 修 bug"), "修 bug");
+	});
+
+	it("strips a bold-wrapped label and its closing markers", () => {
+		assert.equal(cleanSummaryText("**摘要：** 优化摘要逻辑"), "优化摘要逻辑");
+		assert.equal(cleanSummaryText("**摘要**：优化摘要逻辑"), "优化摘要逻辑");
+	});
+
+	it("skips a label-only first line and uses the next line", () => {
+		assert.equal(cleanSummaryText("摘要：\n优化提示词摘要逻辑"), "优化提示词摘要逻辑");
+		assert.equal(cleanSummaryText("**Summary**\nrefactor the loader"), "refactor the loader");
+	});
+
+	it("takes only the first meaningful line", () => {
+		const reply = "优化摘要逻辑\n\n这段代码做的事情是把很长的提示词交给模型压缩，具体来说……";
+		assert.equal(cleanSummaryText(reply), "优化摘要逻辑");
+	});
+
+	it("strips wrapping quotes and book-title marks", () => {
+		assert.equal(cleanSummaryText('"优化摘要逻辑"'), "优化摘要逻辑");
+		assert.equal(cleanSummaryText("「优化摘要逻辑」"), "优化摘要逻辑");
+		assert.equal(cleanSummaryText("《优化摘要逻辑》"), "优化摘要逻辑");
+		assert.equal(cleanSummaryText("`优化摘要逻辑`"), "优化摘要逻辑");
+	});
+
+	it("strips whole-text bold wrapping", () => {
+		assert.equal(cleanSummaryText("**优化摘要逻辑**"), "优化摘要逻辑");
+		assert.equal(cleanSummaryText("__refactor the loader__"), "refactor the loader");
+	});
+
+	it("unwraps stacked decoration (label + quotes + bold)", () => {
+		assert.equal(cleanSummaryText('**"摘要：优化摘要逻辑"**'), "优化摘要逻辑");
+	});
+
+	it("strips list bullets and markdown chrome via flattenPrompt", () => {
+		assert.equal(cleanSummaryText("- 优化摘要逻辑"), "优化摘要逻辑");
+		assert.equal(cleanSummaryText("# 优化摘要逻辑"), "优化摘要逻辑");
+	});
+
+	it("keeps the fenced content when the reply is a code fence", () => {
+		assert.equal(cleanSummaryText("```\n优化摘要逻辑\n```"), "优化摘要逻辑");
+	});
+
+	it("removes ANSI escapes, zero-width characters and control chars", () => {
+		assert.equal(cleanSummaryText("\u001b[31m优化摘要逻辑\u001b[0m"), "优化摘要逻辑");
+		assert.equal(cleanSummaryText("优化\u200b摘要逻辑"), "优化摘要逻辑");
+	});
+
+	it("returns empty for empty / decorative-only replies", () => {
+		assert.equal(cleanSummaryText(""), "");
+		assert.equal(cleanSummaryText("   \n\t\n "), "");
+		assert.equal(cleanSummaryText("摘要："), "");
+		assert.equal(cleanSummaryText("```\n```"), "");
+	});
+
+	it("caps runaway replies at MAX_SUMMARY_TEXT_CHARS without splitting a surrogate pair", () => {
+		const reply = "😀".repeat(MAX_SUMMARY_TEXT_CHARS + 50);
+		const cleaned = cleanSummaryText(reply);
+		// 上限 + 表示被截的 `…`，按码点算恰好一个。
+		assert.equal([...cleaned].length, MAX_SUMMARY_TEXT_CHARS + 1);
+		assert.ok(cleaned.endsWith("😀…"));
+	});
+
+	it("keeps CJK text intact", () => {
+		const text = "把右侧摘要换成模型压缩后的一句话";
+		assert.equal(cleanSummaryText(text), text);
+	});
+});