@foolsecret/pi-prompt 0.4.0 → 0.4.8

package/src/ui.ts

@@ -1,113 +1,398 @@
 /**
- * 三轴设置抽屉（复刻 pi /settings 的交互效果）：上下 DynamicBorder 彩色边框 +
- * 中间 SettingsList，选中行时说明栏随键盘上下切换（description 即"帮助栏/说明栏"）。
+ * 分级设置抽屉（对齐姊妹项目 pi-pricer 的 submenu 钻取范式）：
+ * 根层 = 4 个分类（提示词 / 工具 / 上下文 / 其他），Enter 钻入子层，Esc 逐级返回。
+ * 上下 DynamicBorder 边框 + 动态面包屑标题 + 中间 SettingsList（说明栏随光标切换）。
  *
- * 设计规范见仓库根 DESIGN.md（design-md 格式）：本模块是可复用部件，
- * 只负责"渲染 + 把变更转发给回调"，不接触配置/台账（由调用方接线）。
+ * 三层切分（见仓库根 DESIGN.md）：
+ *   纯函数层 buildRootItems / buildGroupItems / resolveSettingId —— 不依赖 TUI，可单测
+ *   表现层 PromptConfigDrawer —— 只组装组件 + 转发 (id,value) 给回调
+ *   接线层 PromptExtension —— 注入 readState / callbacks，负责写盘与持久化
  */
 
 import { DynamicBorder, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
-import { Container, SettingsList, Text, type SettingItem } from "@earendil-works/pi-tui";
+import { Container, getKeybindings, matchesKey, SettingsList, Text, type SettingItem } from "@earendil-works/pi-tui";
 import type { DoMode, ShowMode, WriteMode } from "./modes.ts";
 import type { AxisName } from "./command.ts";
 
-/** 抽屉展示所需的当前状态：会话轴 + 默认轴（各三档） */
+/** 抽屉展示所需的当前状态：三轴 + 开关 + 数值 */
 export interface PromptConfigDrawerState {
 	session: { show: ShowMode; write: WriteMode; do: DoMode };
 	defaults: { show: ShowMode; write: WriteMode; do: DoMode };
+	/** 布尔开关当前值 */
+	flags: {
+		peakUpgrade: boolean;
+		quietStartup: boolean;
+		hideStatus: boolean;
+		autoSample: boolean;
+		autoCompact: boolean;
+	};
+	/** 数值参数当前值 */
+	numbers: {
+		maxTokensCap: number;
+		/** 0 = 关 */
+		hysteresis: number;
+		autoCompactMaxTokens: number;
+		autoCompactPercent: number;
+		autoCompactMinTurns: number;
+		autoSampleInterval: number;
+		autoSampleMaxPerDay: number;
+	};
+	/** 工具输出上限（0 = 该工具不截） */
+	toolCaps: { grep: number; read: number; bash: number; default: number };
+	/** 工具输出截断总开关 */
+	toolOutputEnabled: boolean;
 }
 
 /** 抽屉各行的值域（show 含 auto 元档位，放第一项便于循环命中"自动"） */
 const SHOW_VALUES: readonly string[] = ["auto", "normal", "lite", "full", "ultra"];
 const WRITE_VALUES: readonly string[] = ["minimal", "normal", "complete"];
 const DO_VALUES: readonly string[] = ["direct", "normal", "deep"];
+/** 布尔开关：off 在前，循环先关后开 */
+const BOOL_VALUES: readonly string[] = ["off", "on"];
 
-/** 设置项 id 的取值：会话轴 show|write|do；默认档 default-<轴> */
+/** 设置项 id 的取值：会话轴 show|write|do；默认档 default-<轴>；开关 flag-<名>；数值 num-<名>；工具上限 cap-<工具> */
 const SESSION_IDS: readonly AxisName[] = ["show", "write", "do"];
 const DEFAULT_PREFIX = "default-";
+const FLAG_PREFIX = "flag-";
+const NUM_PREFIX = "num-";
+const CAP_PREFIX = "cap-";
+
+/** 分类 id（根层的 4 个钻取入口） */
+export const GROUP_IDS = ["prompt", "tool", "context", "other"] as const;
+export type GroupId = (typeof GROUP_IDS)[number];
+
+/** 分类显示名（面包屑用同一份） */
+const GROUP_LABELS: Record<GroupId, string> = {
+	prompt: "提示词",
+	tool: "工具",
+	context: "上下文",
+	other: "其他",
+};
+
+/** 把秒/数值格式化成人类可读（用于行尾 currentValue） */
+function fmtNum(n: number): string {
+	if (n === 0) return "关";
+	if (n >= 1000 && n % 1000 === 0) return `${n / 1000}K`;
+	return String(n);
+}
+
+function fmtBool(b: boolean): string {
+	return b ? "on" : "off";
+}
+
+/** 工具上限的预设档（含"关"=0） */
+const CAP_CHOICES: readonly number[] = [0, 4096, 8192, 16384, 32768, 65536];
+
+/** 数值参数的预设档选项（值 → 显示名） */
+export interface NumChoice {
+	value: number;
+	label: string;
+}
+
+/** 各数值参数的档位表（子菜单用） */
+export const NUM_CHOICES: Record<string, readonly NumChoice[]> = {
+	hysteresis: [
+		{ value: 0, label: "0（关迟滞，退回无状态 argmax）" },
+		{ value: 0.25, label: "0.25（易换档）" },
+		{ value: 0.5, label: "0.5（默认）" },
+		{ value: 1, label: "1（最难换档，最保缓存）" },
+	],
+	autoCompactMaxTokens: [
+		{ value: 100000, label: "100K" },
+		{ value: 200000, label: "200K" },
+		{ value: 400000, label: "400K（默认）" },
+		{ value: 800000, label: "800K" },
+	],
+	autoCompactPercent: [
+		{ value: 0.4, label: "40% 窗口" },
+		{ value: 0.6, label: "60% 窗口（默认）" },
+		{ value: 0.8, label: "80% 窗口" },
+	],
+	autoCompactMinTurns: [
+		{ value: 20, label: "20 轮" },
+		{ value: 50, label: "50 轮（默认）" },
+		{ value: 100, label: "100 轮" },
+	],
+	maxTokensCap: [
+		{ value: 0, label: "关（默认）" },
+		{ value: 4096, label: "4096" },
+		{ value: 8192, label: "8192" },
+		{ value: 16384, label: "16384" },
+	],
+	autoSampleInterval: [
+		{ value: 20, label: "20 轮" },
+		{ value: 50, label: "50 轮（默认）" },
+		{ value: 100, label: "100 轮" },
+	],
+	autoSampleMaxPerDay: [
+		{ value: 1, label: "1 次/天" },
+		{ value: 3, label: "3 次/天（默认）" },
+		{ value: 10, label: "10 次/天" },
+	],
+};
+
+/** 数值行的中文名（根层摘要与子层 label 共用） */
+const NUM_LABELS: Record<string, string> = {
+	hysteresis: "换档迟滞（hysteresis）",
+	autoCompactMaxTokens: "压缩绝对上限 token",
+	autoCompactPercent: "压缩窗口百分比",
+	autoCompactMinTurns: "压缩最少轮数",
+	maxTokensCap: "max_tokens 上限",
+	autoSampleInterval: "抽样间隔（轮）",
+	autoSampleMaxPerDay: "当日抽样上限",
+};
+
+/** 开关行的中文名与说明 */
+const FLAG_META: Record<string, { label: string; desc: string }> = {
+	peakUpgrade: {
+		label: "高峰升档（peakUpgrade）",
+		desc: "DeepSeek 高峰时段自动升档，用更省的注入换输出成本。",
+	},
+	autoCompact: {
+		label: "自动上下文压缩（autoCompact）",
+		desc: "上下文超过阈值且会话够长时自动压缩。默认关：压缩是投资，短会话压缩反而亏（缓存读很便宜）。",
+	},
+	autoSample: {
+		label: "auto 低频抽样（autoSample）",
+		desc: "定期采对照组样本用于校准节省估算。默认关。",
+	},
+	quietStartup: { label: "安静启动（quietStartup）", desc: "启动时不打印提示信息。" },
+	hideStatus: { label: "隐藏状态栏（hideStatus）", desc: "不在底部状态栏显示 pi-prompt 档位。" },
+};
+
+/** 分类说明（根层 description） */
+const GROUP_DESC: Record<GroupId, string> = {
+	prompt: "注入系统提示词的三轴：控制模型回话的风格、代码量、行为力度（会话档 + 新会话默认档）。",
+	tool: "请求形状与工具结果：高峰升档、max_tokens 上限、工具输出截断上限。",
+	context: "上下文长度与缓存稳定性：自动压缩开关与阈值、换档迟滞。",
+	other: "观测与界面偏好：auto 抽样校准、启动与状态栏显示。",
+};
+
+/** 分类 → 该组包含的行 id（纯数据，buildGroupItems 与测试共用） */
+export const GROUP_MEMBERS: Record<GroupId, readonly string[]> = {
+	prompt: ["show", "write", "do", "default-show", "default-write", "default-do"],
+	tool: ["flag-peakUpgrade", "num-maxTokensCap", "flag-toolOutput", "cap-grep", "cap-read", "cap-bash", "cap-default"],
+	context: ["flag-autoCompact", "num-autoCompactMaxTokens", "num-autoCompactPercent", "num-autoCompactMinTurns", "num-hysteresis"],
+	other: ["flag-autoSample", "num-autoSampleInterval", "num-autoSampleMaxPerDay", "flag-quietStartup", "flag-hideStatus"],
+};
+
+/** 构造单个三轴行 */
+function axisItem(axis: AxisName, prefix: string, state: PromptConfigDrawerState): SettingItem {
+	const isDefault = prefix === DEFAULT_PREFIX;
+	const current = isDefault ? state.defaults[axis] : state.session[axis];
+	const values = axis === "show" ? SHOW_VALUES : axis === "write" ? WRITE_VALUES : DO_VALUES;
+	const scope = isDefault ? "默认" : "会话";
+	const base = axis === "show" ? "风格" : axis === "write" ? "代码" : "行动";
+	const detail =
+		axis === "show"
+			? "auto 按成本函数每轮自动选档；ultra 电报式最省、full 常规精炼、lite 轻柔、normal 不注入。"
+			: axis === "write"
+				? "minimal 只交付最小可跑实现、normal 常规、complete 富注释带文档。"
+				: "direct 收敛最小步骤、normal 常规、deep 主动查证根因与边界。";
+	return {
+		id: `${prefix}${axis}`,
+		label: `${scope} · ${base}（${axis}）`,
+		currentValue: current,
+		values: [...values],
+		description: `${detail}${isDefault ? "（仅影响后续会话）" : ""}`,
+	};
+}
+
+/** 构造单个开关行 */
+function flagItem(name: string, state: PromptConfigDrawerState): SettingItem {
+	const meta = FLAG_META[name]!;
+	const current = name === "toolOutput" ? state.toolOutputEnabled : Boolean(state.flags[name as keyof typeof state.flags]);
+	return {
+		id: `${FLAG_PREFIX}${name}`,
+		label: name === "toolOutput" ? "工具输出截断（toolOutput）" : meta.label,
+		currentValue: fmtBool(current),
+		values: [...BOOL_VALUES],
+		description:
+			name === "toolOutput"
+				? "在工具结果创建时截断到各工具上限（缓存友好）。默认关：pi 已自带 50KB 上限，再收紧会改变模型看到的内容。"
+				: meta.desc,
+	};
+}
+
+/** 构造单个数值行（Enter 打开预设档子菜单） */
+function numItem(name: string, state: PromptConfigDrawerState, onPick: (name: string, value: number) => void): SettingItem {
+	const current = state.numbers[name as keyof typeof state.numbers];
+	const choices = NUM_CHOICES[name] ?? [];
+	return {
+		id: `${NUM_PREFIX}${name}`,
+		label: NUM_LABELS[name] ?? name,
+		currentValue: fmtNum(current),
+		description: "Enter 选择预设档位。",
+		submenu: (_v, done) => {
+			const sub: SettingItem[] = choices.map((c) => ({
+				id: `${NUM_PREFIX}${name}#${c.value}`,
+				label: c.label,
+				currentValue: c.value === current ? "← 当前" : "",
+			}));
+			return new SettingsList(
+				sub,
+				Math.min(sub.length + 4, 12),
+				getSettingsListTheme(),
+				(id) => {
+					const picked = Number(String(id).split("#")[1]);
+					if (!Number.isFinite(picked)) return;
+					onPick(name, picked);
+					done(String(picked));
+				},
+				() => done(undefined),
+				{ enableSearch: true },
+			);
+		},
+	};
+}
+
+/** 构造单个工具上限行 */
+function capItem(tool: "grep" | "read" | "bash" | "default", state: PromptConfigDrawerState): SettingItem {
+	const current = state.toolCaps[tool];
+	return {
+		id: `${CAP_PREFIX}${tool}`,
+		label: `工具输出上限 · ${tool}`,
+		currentValue: fmtNum(current),
+		values: CAP_CHOICES.map((n) => String(n)),
+		description:
+			tool === "read"
+				? "read 是模型主动要看的内容，砍太狠会引发重读 → 反而增加输出成本，建议 ≥16K。"
+				: tool === "grep"
+					? "grep 匹配行冗余度高，收紧收益最大。"
+					: "0 = 不截该工具（仍受 pi 自带 50KB 上限约束）。",
+	};
+}
 
 /**
- * 依据当前状态生成设置项列表（纯函数，不依赖 TUI，可单测）。
- * 每项都有 description —— SettingsList 会把选中项的 description 渲染在
- * 提示行上方，这就是"说明栏随光标切换"的机制。
+ * 根层 4 个分类项（每项 Enter 钻入子层）。
+ * currentValue 为分类摘要（如 "show=auto"），便于不钻入也能看到关键状态。
  */
-export function buildSettingItems(state: PromptConfigDrawerState): SettingItem[] {
-	const session: SettingItem[] = [
-		{
-			id: "show",
-			label: "会话输出风格（show）",
-			currentValue: state.session.show,
-			values: [...SHOW_VALUES],
-			description:
-				"输出风格：auto 按成本函数每轮自动选档；ultra 电报式最省、full 常规精炼、lite 轻柔、normal 不注入（基础行为）。",
-		},
-		{
-			id: "write",
-			label: "会话代码量（write）",
-			currentValue: state.session.write,
-			values: [...WRITE_VALUES],
-			description: "代码写量：minimal 只交付最小可跑实现、normal 常规、complete 富注释带文档。",
-		},
-		{
-			id: "do",
-			label: "会话行为力度（do）",
-			currentValue: state.session.do,
-			values: [...DO_VALUES],
-			description: "行为力度：direct 收敛最小步骤、normal 常规、deep 主动查证根因与边界。",
-		},
-	];
-	const defaults: SettingItem[] = [
-		{
-			id: `${DEFAULT_PREFIX}show`,
-			label: "默认输出风格（show）",
-			currentValue: state.defaults.show,
-			values: [...SHOW_VALUES],
-			description: "新会话默认的输出风格（后续会话生效，不影响当前会话）。",
-		},
-		{
-			id: `${DEFAULT_PREFIX}write`,
-			label: "默认代码量（write）",
-			currentValue: state.defaults.write,
-			values: [...WRITE_VALUES],
-			description: "新会话默认的代码写量。",
-		},
-		{
-			id: `${DEFAULT_PREFIX}do`,
-			label: "默认行为力度（do）",
-			currentValue: state.defaults.do,
-			values: [...DO_VALUES],
-			description: "新会话默认的行为力度。",
-		},
-	];
-	return [...session, ...defaults];
+export function buildRootItems(state: PromptConfigDrawerState): SettingItem[] {
+	const promptSummary = `风格=${state.session.show}`;
+	const toolSummary = `工具截断=${fmtBool(state.toolOutputEnabled)}`;
+	const ctxSummary = `压缩=${fmtBool(state.flags.autoCompact)}`;
+	const otherSummary = `抽样=${fmtBool(state.flags.autoSample)}`;
+	const summary: Record<GroupId, string> = {
+		prompt: promptSummary,
+		tool: toolSummary,
+		context: ctxSummary,
+		other: otherSummary,
+	};
+	return GROUP_IDS.map((id) => ({
+		id: `group-${id}`,
+		label: GROUP_LABELS[id],
+		currentValue: summary[id],
+		description: GROUP_DESC[id],
+	}));
+}
+
+/** 子层：某分类下的所有设置行（纯函数，可单测） */
+export function buildGroupItems(
+	group: GroupId,
+	state: PromptConfigDrawerState,
+	onNumPick: (name: string, value: number) => void = () => {},
+): SettingItem[] {
+	return GROUP_MEMBERS[group].map((id) => {
+		if (id === "show" || id === "write" || id === "do") return axisItem(id, "", state);
+		if (id.startsWith(DEFAULT_PREFIX)) return axisItem(id.slice(DEFAULT_PREFIX.length) as AxisName, DEFAULT_PREFIX, state);
+		if (id.startsWith(FLAG_PREFIX)) return flagItem(id.slice(FLAG_PREFIX.length), state);
+		if (id.startsWith(NUM_PREFIX)) return numItem(id.slice(NUM_PREFIX.length), state, onNumPick);
+		if (id.startsWith(CAP_PREFIX)) return capItem(id.slice(CAP_PREFIX.length) as "grep" | "read" | "bash" | "default", state);
+		throw new Error(`未知行 id: ${id}`);
+	});
 }
 
-/** 设置项 id → 是否为默认档行，以及对应的轴 */
-export function resolveSettingId(id: string): { axis: AxisName; isDefault: boolean } | null {
-	if (SESSION_IDS.includes(id as AxisName)) return { axis: id as AxisName, isDefault: false };
+/** 分类显示名（接线层拼面包屑标题用） */
+export function groupLabel(group: GroupId): string {
+	return GROUP_LABELS[group];
+}
+
+/** 设置项 id → 分发目标（唯一分发点；未知 id 返回 null 即丢弃） */
+export type SettingTarget =
+	| { kind: "session-axis"; axis: AxisName }
+	| { kind: "default-axis"; axis: AxisName }
+	| { kind: "flag"; name: string }
+	| { kind: "number"; name: string }
+	| { kind: "cap"; tool: "grep" | "read" | "bash" | "default" };
+
+export function resolveSettingId(id: string): SettingTarget | null {
+	if (SESSION_IDS.includes(id as AxisName)) return { kind: "session-axis", axis: id as AxisName };
 	if (id.startsWith(DEFAULT_PREFIX)) {
 		const axis = id.slice(DEFAULT_PREFIX.length) as AxisName;
-		if (SESSION_IDS.includes(axis)) return { axis, isDefault: true };
+		if (SESSION_IDS.includes(axis)) return { kind: "default-axis", axis };
+	}
+	if (id.startsWith(FLAG_PREFIX)) return { kind: "flag", name: id.slice(FLAG_PREFIX.length) };
+	if (id.startsWith(NUM_PREFIX)) return { kind: "number", name: id.slice(NUM_PREFIX.length) };
+	if (id.startsWith(CAP_PREFIX)) {
+		const tool = id.slice(CAP_PREFIX.length);
+		if (tool === "grep" || tool === "read" || tool === "bash" || tool === "default") return { kind: "cap", tool };
 	}
 	return null;
 }
 
-/** 抽屉所需的回调接线（由 PromptExtension 提供，注入以便单测） */
+/**
+ * 抽屉所需的回调接线（由 PromptExtension 提供，注入以便单测）。
+ * 返回值 = 是否变更成功（写入草稿），供抽屉刷新与状态栏显示。
+ * ⚠ `编辑只改草稿`——落盘只由 onSave 触发（Ctrl+S）。
+ */
 export interface PromptConfigDrawerCallbacks {
-	onSessionAxisChange: (axis: AxisName, value: string) => void;
-	onDefaultAxisChange: (axis: AxisName, value: string) => void;
+	onSessionAxisChange: (axis: AxisName, value: string) => boolean;
+	onDefaultAxisChange: (axis: AxisName, value: string) => boolean;
+	onFlagChange: (name: string, value: boolean) => boolean;
+	onNumberChange: (name: string, value: number) => boolean;
+	onCapChange: (tool: "grep" | "read" | "bash" | "default", value: number) => boolean;
+	/** Ctrl+S：把草稿落盘 */
+	onSave: () => { ok: boolean; reason: string };
+	/** Ctrl+R：丢弃未保存改动 */
+	onReset: () => void;
+}
+
+/** 抽屉主题形参（与 pi-pricer 对齐） */
+interface DrawerTheme {
+	fg: (color: string, text: string) => string;
+	bold: (text: string) => string;
 }
 
 /**
- * 三轴设置抽屉：open 时在 ctx.ui 上开一个 /settings 同款抽屉；
+ * 分级设置抽屉：open 时在 ctx.ui 上开一个 pi-pricer 同款抽屉。
  * 无 TUI（非交互模式）时交给 onUnavailable 回退。
+ *
+ * 保存模型（**草稿 + Ctrl+S**，对齐 pi-pricer）：
+ *   抽屉内所有编辑只改**内存草稿**（由接线层的 PromptDraft 持有），
+ *   状态栏常驻显示 `● 未保存改动（面）`；Ctrl+S 落盘后转 `✓ 已保存`。
+ *   根层 Esc 且有未保存改动时**拦截退出**：第一次只提示，第二次才放弃退出。
+ *
+ * 刷新模型：readState() 与 SettingsList.items 都是构造时**快照**，
+ *   故变更后必须重建当前层与根层列表（否则根层摘要 stale——曾出现
+ *   "改了值但返回上层看到的还是旧值"）；重建后用 selectItem() 保住光标。
+ *
+ * 键盘拦截必须用 matchesKey 而非裸字节：pi-tui 在增强键盘协议下把 Ctrl+S
+ *   编码为 CSI-u / modifyOtherKeys 序列，裸比较 \x13 永远不命中（保存静默失效）。
  */
 export class PromptConfigDrawer {
+	/** 当前所在分类（null = 根层） */
+	private activeGroup: GroupId | null = null;
+	/** 当前层列表引用（重建时替换） */
+	private activeList: SettingsList | null = null;
+	/** 是否已有未保存改动（由接线层草稿状态同步；决定 Esc 是否拦截） */
+	private readonly draftView: DrawerDraftView;
+
 	constructor(
 		private readonly readState: () => PromptConfigDrawerState,
 		private readonly callbacks: PromptConfigDrawerCallbacks,
 		private readonly onUnavailable: (context: unknown) => void,
-	) {}
+		draftView?: DrawerDraftView,
+	) {
+		this.draftView = draftView ?? { isDirty: () => false, changedAreas: () => [] };
+	}
+
+	private isDirty(): boolean {
+		return this.draftView.isDirty();
+	}
+
+	private changedAreas(): string[] {
+		return this.draftView.changedAreas();
+	}
 
 	/** 打开抽屉；无 custom UI 时走回退分支 */
 	async open(context: unknown): Promise<void> {
@@ -116,41 +401,200 @@ export class PromptConfigDrawer {
 			this.onUnavailable(context);
 			return;
 		}
-		const items = buildSettingItems(this.readState());
 		await (ui.custom as (factory: unknown) => Promise<unknown>)(
-			(tui: unknown, theme: { fg: (color: string, text: string) => string; bold: (text: string) => string }, _kb: unknown, done: (result?: undefined) => void) => {
-				const container = new Container();
-				container.addChild(new DynamicBorder((s: string) => theme.fg("borderAccent", s)));
-				container.addChild(
-					new Text(theme.fg("accent", theme.bold("pi-prompt 设置")), 1, 1),
-				);
-				const settingsList = new SettingsList(
-					items,
-					Math.min(items.length + 4, 12),
-					getSettingsListTheme(),
-					(id, newValue) => this.handleChange(String(id), String(newValue)),
-					() => done(undefined),
-					{ enableSearch: true },
-				);
-				container.addChild(settingsList);
-				container.addChild(new DynamicBorder((s: string) => theme.fg("borderAccent", s)));
+			(tui: unknown, theme: DrawerTheme, _kb: unknown, done: (result?: undefined) => void) =>
+				this.buildScene(theme, () => done(undefined)),
+		);
+	}
+
+	/**
+	 * 组装抽屉场景：边框 + 面包屑标题 + 当前层列表 + 状态栏 + 下边框。
+	 * Esc 归属用**显式深度计数器**（不靠标题反推：标题是展示层状态，
+	 * 用它决定 Esc 归属会把展示与逻辑耦合）。
+	 */
+	private buildScene(theme: DrawerTheme, close: () => void): unknown {
+		const ROOT_TITLE = "pi-prompt 设置";
+		const container = new Container();
+		const title = new Text(theme.fg("accent", theme.bold(ROOT_TITLE)), 1, 1);
+		const statusText = new Text("", 1, 0);
+
+		/** 深度：根层 0，每进一级 +1（决定 Esc 是"返回上级"还是"退出"） */
+		let depth = 0;
+		/** Esc 已提示过"放弃退出"？有未保存改动时第一次 Esc 只提示，第二次才退 */
+		let escHintShown = false;
+
+		const refreshStatus = (message?: string): void => {
+			const left = this.isDirty()
+				? theme.fg("warning", `● 未保存改动（${this.changedAreas().join("、")}）`)
+				: theme.fg("success", "✓ 已保存");
+			const detail = message ? `   ${message}` : "";
+			const keys = theme.fg("dim", "  Ctrl+S 保存 · Ctrl+R 重置 · Esc 返回");
+			statusText.setText(`${left}${detail}${keys}`);
+			container.invalidate();
+		};
+
+		const setTitle = (text: string): void => {
+			title.setText(theme.fg("accent", theme.bold(text)));
+			container.invalidate();
+		};
+
+		/** 用新列表替换 container 里的旧列表（原地换，保持边框/标题/状态栏顺序） */
+		const swapList = (next: SettingsList, prev: SettingsList | null): void => {
+			if (prev) container.removeChild(prev);
+			container.removeChild(statusText);
+			container.addChild(next);
+			container.addChild(statusText);
+			this.activeList = next;
+			container.invalidate();
+		};
+
+		const sceneCtx: SceneCtx = { theme, setTitle, rootTitle: ROOT_TITLE, refreshStatus, swapList, close, enterLevel: () => { depth += 1; }, leaveLevel: () => { depth = Math.max(0, depth - 1); } };
+
+		this.activeList = this.buildLevel(sceneCtx);
+		container.addChild(new DynamicBorder((s: string) => theme.fg("borderAccent", s)));
+		container.addChild(title);
+		container.addChild(this.activeList);
+		container.addChild(statusText);
+		container.addChild(new DynamicBorder((s: string) => theme.fg("borderAccent", s)));
+		refreshStatus();
+
+		return {
+			render: (w: number) => container.render(w),
+			invalidate: () => container.invalidate(),
+			handleInput: (data: unknown) => {
+				const key = data as string;
+				// Ctrl+S / Ctrl+R 任意层级可用，优先于列表导航
+				if (matchesKey(key, "ctrl+s")) {
+					const result = this.callbacks.onSave();
+					escHintShown = false;
+					refreshStatus(result.ok ? "已保存到 ~/.pi/pi-prompt.json" : `保存失败：${result.reason}`);
+					return;
+				}
+				if (matchesKey(key, "ctrl+r")) {
+					this.callbacks.onReset();
+					escHintShown = false;
+					// 重置后当前层列表要按新状态重建
+					swapList(this.buildLevel(sceneCtx), this.activeList);
+					refreshStatus("已丢弃未保存改动");
+					return;
+				}
+				// 根层 Esc + 有未保存改动：第一次提示，第二次放弃退出
+				if (getKeybindings().matches(key, "tui.select.cancel") && this.isDirty() && depth === 0) {
+					if (!escHintShown) {
+						escHintShown = true;
+						refreshStatus(theme.fg("warning", "有未保存改动：Ctrl+S 保存 / Ctrl+R 重置 / 再按 Esc 放弃退出"));
+						return;
+					}
+					close();
+					return;
+				}
+				this.activeList?.handleInput?.(key);
+			},
+		};
+	}
+
+	/** 构建当前层（根层或某个分类子层）的 SettingsList */
+	private buildLevel(ctx: SceneCtx): SettingsList {
+		if (this.activeGroup === null) {
+			const items: SettingItem[] = buildRootItems(this.readState()).map((item) => {
+				const group = item.id.replace(/^group-/, "") as GroupId;
 				return {
-					render: (w: number) => container.render(w),
-					invalidate: () => container.invalidate(),
-					handleInput: (data: unknown) => settingsList.handleInput?.(data as string),
+					...item,
+					submenu: (_currentValue, done) => {
+						this.activeGroup = group;
+						ctx.enterLevel();
+						ctx.setTitle(`${ctx.rootTitle} · ${groupLabel(group)}`);
+						const child = this.buildLevel(ctx);
+						ctx.swapList(child, this.activeList);
+						ctx.refreshStatus(`${groupLabel(group)}组`);
+						return child;
+					},
 				};
-			},
+			});
+			return new SettingsList(
+				items,
+				Math.min(items.length + 4, 12),
+				getSettingsListTheme(),
+				() => {},
+				ctx.close,
+				{ enableSearch: true },
+			);
+		}
+		const group = this.activeGroup;
+		const items = buildGroupItems(group, this.readState());
+		return new SettingsList(
+			items,
+			Math.min(items.length + 4, 16),
+			getSettingsListTheme(),
+			(id, newValue) => this.handleChange(String(id), String(newValue), ctx),
+			// 子层 Esc：回根层（而不是关抽屉）
+			() => this.goRoot(ctx),
+			{ enableSearch: true },
 		);
 	}
 
-	/** 行变更分发：会话行 vs 默认档行，分别走对应回调 */
-	private handleChange(id: string, value: string): void {
-		const resolved = resolveSettingId(id);
-		if (!resolved) return;
-		if (resolved.isDefault) {
-			this.callbacks.onDefaultAxisChange(resolved.axis, value);
-		} else {
-			this.callbacks.onSessionAxisChange(resolved.axis, value);
+	/** 回到根层：重置层级、标题、列表 */
+	private goRoot(ctx: SceneCtx): void {
+		this.activeGroup = null;
+		ctx.leaveLevel();
+		ctx.setTitle(ctx.rootTitle);
+		const root = this.buildLevel(ctx);
+		ctx.swapList(root, this.activeList);
+		ctx.refreshStatus();
+	}
+
+	/** 行变更分发：只改草稿（Ctrl+S 才落盘），随后重建当前层让值可见 */
+	private handleChange(id: string, value: string, ctx: SceneCtx): void {
+		const target = resolveSettingId(id);
+		if (!target) return;
+		let ok = false;
+		switch (target.kind) {
+			case "session-axis":
+				ok = this.callbacks.onSessionAxisChange(target.axis, value);
+				break;
+			case "default-axis":
+				ok = this.callbacks.onDefaultAxisChange(target.axis, value);
+				break;
+			case "flag":
+				ok = this.callbacks.onFlagChange(target.name, value === "on");
+				break;
+			case "number": {
+				const n = Number(value);
+				if (!Number.isFinite(n)) return;
+				ok = this.callbacks.onNumberChange(target.name, n);
+				break;
+			}
+			case "cap": {
+				const n = Number(value);
+				if (!Number.isFinite(n)) return;
+				ok = this.callbacks.onCapChange(target.tool, n);
+				break;
+			}
 		}
+		if (!ok) return;
+		const rebuilt = this.buildLevel(ctx);
+		rebuilt.selectItem(id);
+		ctx.swapList(rebuilt, this.activeList);
+		ctx.refreshStatus();
 	}
-}
+}
+
+/** 场景闭包上下文（标题/状态栏/列表替换/层级/关闭） */
+interface SceneCtx {
+	theme: DrawerTheme;
+	setTitle: (t: string) => void;
+	rootTitle: string;
+	refreshStatus: (msg?: string) => void;
+	swapList: (next: SettingsList, prev: SettingsList | null) => void;
+	/** 进入子层：深度 +1（决定 Esc 归属） */
+	enterLevel: () => void;
+	/** 回到上级：深度 -1 */
+	leaveLevel: () => void;
+	close: () => void;
+}
+
+/** 抽屉可注入的草稿状态读取（供接线层同步 dirty / changedAreas） */
+export interface DrawerDraftView {
+	isDirty: () => boolean;
+	changedAreas: () => string[];
+}