@yinan_chen/pi-claude-code-ui 0.8.9 → 0.9.0

package/README.md

@@ -32,10 +32,26 @@ pi -e npm:@yinan_chen/pi-claude-code-ui
 - **子代理面板** — 后台 agent 状态一目了然
 - **工作状态提示** — working message / running effect
 - **只读工具美化** — read/bash/grep/find/ls 结果渲染
+- **设置面板** — `/skin-setting` 即改即存调整全部皮肤配置，`/skin-setting default` 一键恢复默认（v0.9.0）
 
 ## 配置
 
-配置文件：`~/.pi/agent/lean-tidy.json`（不存在时全部使用默认值）：
+### 推荐方式：`/skin-setting` 设置面板
+
+在 pi 会话里输入 `/skin-setting` 打开居中 overlay 设置面板，即改即存——每次改动校验后立即写入配置文件并刷新面板行，没有"保存/放弃"负担：
+
+- 内置搜索过滤，25 个配置键快速定位；每行附中文说明与默认值
+- 枚举/布尔键回车在合法值间循环切换，不会选错；数字/字符串键回车进入输入框，带范围校验（如 0–100、0–4）
+- 大多数键是热键，改动关闭面板后整屏重绘即刻可见；加载期固化的冷键常驻 `⟳ 需 /reload 生效` 标注，改动时会再提醒一次
+- `foreignCardSkip` 黑名单只读展示，看得见状态又不会误编辑
+- `/skin-setting default`：经确认对话框一键恢复全部默认（只清除本皮肤的配置键，文件里手写的其他内容保留）
+- 非 TUI 模式（RPC / JSON / print）下运行会提示配置文件路径，请改用文件方式
+
+任何时刻可用 **F5** 整屏重绘（排残影的习惯操作）。
+
+### 手改配置文件
+
+也可以直接编辑 `~/.pi/agent/lean-tidy.json`（不存在时全部使用默认值）。手改后需 `/reload` 生效；设置面板的改动则是热键即时生效、冷键（下表标 `⟳` 者）需 `/reload`：
 
 ```json
 {
@@ -71,20 +87,20 @@ pi -e npm:@yinan_chen/pi-claude-code-ui
 
 | 键 | 默认 | 说明 |
 |---|---|---|
-| `profile` | `"claude"` | 整体风格：`claude` / `native`（pi 原生） |
+| `profile` ⟳ | `"claude"` | 整体风格：`claude` / `native`（pi 原生） |
 | `skillRendering` | `"native"` | skill 块样式：pi 原生折叠行 / `claude` 两行风格 |
-| `subagentRendering` | `"claude"` | 子代理完成通知：`claude` 分支风格 / `native` 保留包内面板 |
+| `subagentRendering` ⟳ | `"claude"` | 子代理完成通知：`claude` 分支风格 / `native` 保留包内面板 |
 | `detailsBackground` | `"selectedBg"` | 详情背景色（主题色键名，可选 `customMessageBg`/`toolPendingBg`/`toolSuccessBg`/`toolErrorBg`/`""`） |
 | `bash/code/errorPreviewLines` | `0`/`0`/`0` | 三类工具结果的预览行数（0–100；0 = 默认折叠） |
 | `liveThinking` | `true` | 思考过程流式展示 |
 | `thinkingTailLines` | `5` | 思考尾行数 |
 | `foldAnimMs` | `240` | 折叠动画时长（ms，0 关闭） |
-| `stickyIncludeCustom` | `false` | 吸附泡是否包含扩展注入/跨会话转发的旁路消息 |
-| `skillResumePreview` | `true` | `/resume` 列表预览是否折回 `[skill] 名` 单行 |
+| `stickyIncludeCustom` ⟳ | `false` | 吸附泡是否包含扩展注入/跨会话转发的旁路消息 |
+| `skillResumePreview` ⟳ | `true` | `/resume` 列表预览是否折回 `[skill] 名` 单行 |
 | `resultPrefix` | `"└"` | 工具结果行拐角前缀（制表符族，等宽字体最稳；可换 `↳` 或 Claude Code 官方的 `⎿`，后两者在部分字体下会变宽） |
 | `resultPrefixGap` | `1` | 前缀符号与内容之间的空格数（0–4） |
 | `normalizeForeignRenderers` | `true` | 第三方扩展卡片输出里行首 `⎿` 自动规范化为 `resultPrefix`（任何未适配扩展的渲染都能统一风格；关闭可看第三方原版） |
-| `workflowRendering` | `"claude"` | workflow 完成卡片样式：`● Workflow(name)` 风格 / `native` 保留包内卡片。分发层拦截实现，不受包加载顺序影响 |
+| `workflowRendering` ⟳ | `"claude"` | workflow 完成卡片样式：`● Workflow(name)` 风格 / `native` 保留包内卡片。分发层拦截实现，不受包加载顺序影响 |
 | `foreignCardStyle` | `"generic"` | 未适配扩展的卡片：自动接管为通用 `● 卡片`（零配置）；`symbols` = 仅统一符号不接管布局 |
 | `foreignCardSkip` | `[]` | 不接管的 customType 黑名单（交互型第三方卡片异常时按类型跳过） |
 | `diff.diffViewMode` | `"auto"` | diff 视图：`auto`/`split`/`unified` |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yinan_chen/pi-claude-code-ui",
-	"version": "0.8.9",
+	"version": "0.9.0",
 	"description": "Claude Code-style UI for Pi: transcript view, rich diffs, subagent panels and working-message status.",
 	"type": "module",
 	"license": "MIT",

package/src/index.ts

@@ -36,6 +36,8 @@ import registerWorkingMessage from "./working-message.ts";
 // Vendored rich diff (MIT; see vendor/diff/ATTRIBUTION.md).
 import { renderRichToolResult, WriteExecutionMetadataStore } from "./vendor/diff/index.ts";
 import { DEFAULT_TOOL_DISPLAY_CONFIG, type ToolDisplayConfig } from "./vendor/diff-config.ts";
+import { SETTING_BY_ID, applyRuntimeDefaults, resetConfigFile, topLevelDefaults } from "./settings.ts";
+import { handleSkinSettingCommand } from "./skin-setting-panel.ts";
 
 const LOG = "/tmp/lean-tidy.log";
 const DEBUG = (process.env.PI_LEAN_TIDY_DEBUG || "").trim() === "1";
@@ -98,26 +100,8 @@ interface Config {
 }
 
 function loadConfig(): Config {
-	const config: Config = {
-		profile: "claude",
-		skillRendering: "native",
-		subagentRendering: "claude",
-		detailsBackground: "selectedBg",
-		bashPreviewLines: 0,
-		codePreviewLines: 0,
-		errorPreviewLines: 0,
-		liveThinking: true,
-		thinkingTailLines: 5,
-		foldAnimMs: 240,
-		stickyIncludeCustom: false,
-		skillResumePreview: true,
-		resultPrefix: "└",
-		resultPrefixGap: 1,
-		normalizeForeignRenderers: true,
-		workflowRendering: "claude",
-		foreignCardStyle: "generic",
-		foreignCardSkip: [],
-	};
+	// 默认值单一来源：18 个顶层键的初始值取自 settings.ts 的元数据（与面板/恢复默认共用同一份）。
+	const config: Config = topLevelDefaults() as Config;
 	diffDisplayConfig = { ...DEFAULT_TOOL_DISPLAY_CONFIG };
 	try {
 		const data = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
@@ -147,17 +131,10 @@ function loadConfig(): Config {
 			diffDisplayConfig = { ...DEFAULT_TOOL_DISPLAY_CONFIG, ...data.diff };
 		}
 	} catch {}
-	const profile = (process.env.PI_LEAN_TIDY_PROFILE || "").trim();
-	if (profile === "claude" || profile === "native") config.profile = profile;
-	const skill = (process.env.PI_LEAN_TIDY_SKILL || "").trim();
-	if (skill === "claude" || skill === "native") config.skillRendering = skill;
-	const subagent = (process.env.PI_LEAN_TIDY_SUBAGENT || "").trim();
-	if (subagent === "claude" || subagent === "native") config.subagentRendering = subagent;
-	const live = (process.env.PI_LEAN_TIDY_LIVE_THINKING || "").trim().toLowerCase();
-	if (live === "on" || live === "off") config.liveThinking = live === "on";
-	if ((process.env.PI_TIDY_STATIC_THINKING || "").trim() === "1") config.liveThinking = false;
-	const tail = (process.env.PI_LEAN_TIDY_THINKING_TAIL || "").trim();
-	if (/^\d+$/.test(tail)) config.thinkingTailLines = Number(tail);
+	// 配置收敛为单一来源：lean-tidy.json 是唯一配置入口，配置型环境变量
+	// （PI_LEAN_TIDY_PROFILE/_SKILL/_SUBAGENT/_LIVE_THINKING、PI_TIDY_STATIC_THINKING、
+	// PI_LEAN_TIDY_THINKING_TAIL）已全部移除，设了也不生效（一南 2026-10-06）；
+	// PI_LEAN_TIDY_DEBUG 与 PI_PATCH_VERSION_WARN 是诊断开关，不属于配置，仍然保留。
 	return config;
 }
 
@@ -448,6 +425,8 @@ export default async function leanTidy(pi: ExtensionAPI): Promise<void> {
 	const impl = {
 		loadId: loadCounter,
 		config,
+		/** diff 显示配置的运行时引用（热键 apply 时被整体替换，getter 保证读到最新值）。 */
+		get diffDisplayConfig() { return diffDisplayConfig; },
 		hookMode,
 		containerRender: (container: any, width: number, chat: boolean): string[] =>
 			claude && chat ? claude.renderChat(container, width) : Container.prototype.render.call(container, width),
@@ -585,12 +564,78 @@ export default async function leanTidy(pi: ExtensionAPI): Promise<void> {
 			return true;
 		} catch { return false; }
 	}
-	pi.registerCommand("tidy-redraw", {
-		description: "lean-tidy: 强制整屏重绘（清掉终端/pane 层留下的残影行）",
-		handler: async (_args: string, ctx: any) => {
-			if (!forceRedraw()) ctx.ui?.notify?.("lean-tidy: 拿不到 TUI，无法重绘", "warning");
+	// /tidy-redraw 命令已从命令面移除（内部工具不再占用命令列表）；
+	// 整屏重绘能力由下方 F5 快捷键保留。
+
+	/** 热键运行时通道：原地改 config（闭包共享引用直达渲染层）并同步 SYMBOLS / diffDisplayConfig。
+	 *  冷键在加载期固化（视图与面板注册），运行时 apply 无意义，直接跳过。 */
+	function applySetting(id: string, value: unknown): void {
+		const def = SETTING_BY_ID.get(id);
+		if (!def || def.cold) return;
+		if (id.startsWith("diff.")) {
+			diffDisplayConfig = { ...diffDisplayConfig, [id.slice("diff.".length)]: value };
+			return;
+		}
+		(config as Record<string, unknown>)[id] = value;
+		if (id === "resultPrefix") SYMBOLS.resultPrefix = value as string;
+		if (id === "resultPrefixGap") SYMBOLS.resultPrefixGap = value as number;
+	}
+
+	/** /skin-setting default 全链路：确认 → 文件重置（保留未知键）→ 热键运行时重置 → 整屏重绘 → 冷键提醒 /reload。 */
+	async function resetDefaultFlow(ctx: any): Promise<void> {
+		let confirmed = false;
+		try {
+			confirmed = await ctx?.ui?.confirm?.(
+				"恢复默认设置",
+				"将删除 lean-tidy.json 中的全部已知皮肤配置键（未知键保留），热键立即恢复默认。确定继续？",
+			);
+		} catch { confirmed = false; }
+		if (!confirmed) return; // Esc / 取消：文件与运行时零改动。
+		const { coldReset } = resetConfigFile(CONFIG_PATH);
+		// diff 显示配置先整体回出厂拷贝（文件 diff 里的未知键不留在运行时），
+		// 再走统一的热键 apply 通道逐键重置（幂等，值相同）。
+		diffDisplayConfig = { ...DEFAULT_TOOL_DISPLAY_CONFIG };
+		applyRuntimeDefaults(applySetting);
+		forceRedraw();
+		if (coldReset.length > 0) ctx?.ui?.notify?.(`已恢复默认，${coldReset.length} 项需 /reload 生效`, "info");
+	}
+
+	/** 设置面板（工单 03）：当前值读取统一走 currentValueOf——顶层键读共享 config，diff.* 读 diffDisplayConfig（闭包每次读模块变量，apply 整体替换后仍取最新值）。 */
+	const skinSettingDeps = {
+		currentValueOf: (id: string) => id.startsWith("diff.")
+			? diffDisplayConfig[id.slice("diff.".length) as keyof ToolDisplayConfig]
+			: (config as Record<string, unknown>)[id],
+		applySetting,
+		configPath: CONFIG_PATH,
+		forceRedraw,
+	};
+
+	// /skin-setting：无参 = 打开设置面板（仅 TUI；守卫与非 TUI 提示在面板模块内），
+	// default = 确认后一键恢复默认。命令补全只提示 default。
+	pi.registerCommand("skin-setting", {
+		description: "lean-tidy 皮肤设置（default = 恢复默认）",
+		getArgumentCompletions(prefix: string) {
+			const items = [{ value: "default", label: "default", description: "恢复全部默认（未知键保留）" }];
+			return items.filter((item) => item.value.startsWith(prefix));
+		},
+		handler: async (args: string, ctx: any) => {
+			const arg = (args ?? "").trim();
+			if (arg === "default") {
+				// confirm 在有 UI 的模式（含 RPC）可用；无 UI 时拿回 false 即零改动，天然安全，不做模式限制。
+				await resetDefaultFlow(ctx);
+				return;
+			}
+			if (arg === "") {
+				await handleSkinSettingCommand(skinSettingDeps, ctx);
+				return;
+			}
+			ctx?.ui?.notify?.(
+				`未知参数「${arg}」。用法：/skin-setting 打开设置面板（仅 TUI 模式）；/skin-setting default 恢复默认。配置文件：${CONFIG_PATH}`,
+				"info",
+			);
 		},
 	});
+
 	pi.registerShortcut("f5" as any, {
 		description: "lean-tidy: 强制整屏重绘",
 		handler: () => { forceRedraw(); },

package/src/settings.ts

@@ -0,0 +1,327 @@
+/**
+ * 皮肤设置纯逻辑模块（零 TUI 依赖）。
+ *
+ * 职责：25 个配置键的元数据（规范 id / label / 中文描述 / 类型 / 合法值或范围 /
+ * 冷热分类 / 默认值）、编辑侧校验、编辑形态派生判定（循环域 / 输入子菜单——
+ * def.type 的装配侧分派单点收敛于此，validateSetting 的 switch 是校验唯一实现点）、
+ * lean-tidy.json 的 read-modify-write 原子写、恢复默认的文件语义，以及热键默认值的
+ * 运行时 apply 通道（回调注入——本模块不 import 渲染层，避免与 index.ts 循环依赖）。
+ *
+ * 键全集：18 个顶层键（与 index.ts 的 Config 接口对应）+ 7 个 "diff.*" 点路径键
+ * （与 vendor/diff-config.ts 的 DEFAULT_TOOL_DISPLAY_CONFIG 同源）。
+ * 冷键（5 个）在加载期固化（视图与面板注册），改动只落文件、/reload 后生效；
+ * 其余为热键，渲染期读取，运行时原地变更即生效。
+ *
+ * 校验语义与 loadConfig 的读取语义刻意不同：这里（编辑/写入侧）严格拒绝非法值；
+ * loadConfig（读取侧）宽容——文件里的非法值被忽略、回落默认。写严读宽，文件
+ * 里只会有干净值。
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { DEFAULT_TOOL_DISPLAY_CONFIG } from "./vendor/diff-config.ts";
+
+export type SettingType = "enum" | "boolean" | "number" | "string" | "readonly-array";
+
+export interface SettingDef {
+	/** 规范 id：顶层键用 camelCase，diff 段用 "diff.xxx" 点路径（与 lean-tidy.json 键名一致）。 */
+	id: string;
+	/** 面板展示用的简短标签。 */
+	label: string;
+	/** 中文描述（含默认值），面板行与文档共用。 */
+	description: string;
+	type: SettingType;
+	defaultValue: unknown;
+	/** enum 类型的合法值集。 */
+	values?: readonly unknown[];
+	/** number 类型的范围（min 必填）。 */
+	min?: number;
+	max?: number;
+	/** true = 严格整数（0–100 / 0–4 类）；false = 非负且向下取整（≥0 类）。 */
+	integer?: boolean;
+	/** 冷键：加载期固化，改动只落文件，需 /reload 生效。 */
+	cold: boolean;
+}
+
+/** 25 键元数据。默认值是唯一事实来源：loadConfig 经 topLevelDefaults() 消费，消除双源。 */
+export const SETTING_DEFS: readonly SettingDef[] = [
+	// ---- 顶层 18 键 ----
+	{
+		id: "profile", label: "界面配置档案", type: "enum", values: ["claude", "native"], defaultValue: "claude", cold: true,
+		description: "整体呈现：claude = Claude Code 风格视图（默认）；native = pi 原生回退。",
+	},
+	{
+		id: "skillRendering", label: "Skill 渲染", type: "enum", values: ["native", "claude"], defaultValue: "native", cold: false,
+		description: "Skill 调用块样式：native = pi 原生 [skill] 折叠行（默认）；claude = ● Skill(name) 两行风格。",
+	},
+	{
+		id: "subagentRendering", label: "Subagent 渲染", type: "enum", values: ["native", "claude"], defaultValue: "claude", cold: true,
+		description: "Subagent 完成通知样式：claude = ● Subagent(desc) + 分支（默认）；native = 保留包内面板。",
+	},
+	{
+		id: "detailsBackground", label: "详情背景色", type: "enum",
+		values: ["selectedBg", "customMessageBg", "toolPendingBg", "toolSuccessBg", "toolErrorBg", ""],
+		defaultValue: "selectedBg", cold: false,
+		description: "工具详情展开区的背景色（默认 selectedBg；空字符串 = 无背景）。",
+	},
+	{
+		id: "bashPreviewLines", label: "Bash 预览行数", type: "number", min: 0, max: 100, integer: true, defaultValue: 0, cold: false,
+		description: "bash 工具折叠态的输出预览行数，0–100（默认 0）。",
+	},
+	{
+		id: "codePreviewLines", label: "代码工具预览行数", type: "number", min: 0, max: 100, integer: true, defaultValue: 0, cold: false,
+		description: "read / write / edit / find 等折叠态预览行数，0–100（默认 0）。",
+	},
+	{
+		id: "errorPreviewLines", label: "错误预览行数", type: "number", min: 0, max: 100, integer: true, defaultValue: 0, cold: false,
+		description: "失败工具结果折叠态的预览行数，0–100（默认 0）。",
+	},
+	{
+		id: "liveThinking", label: "实时思考流", type: "boolean", defaultValue: true, cold: false,
+		description: "是否流式显示 thinking 块（默认 true）。",
+	},
+	{
+		id: "thinkingTailLines", label: "思考尾部行数", type: "number", min: 0, defaultValue: 5, cold: false,
+		description: "折叠 thinking 时尾部保留的行数，≥0（默认 5）。",
+	},
+	{
+		id: "foldAnimMs", label: "折叠动画时长", type: "number", min: 0, defaultValue: 240, cold: false,
+		description: "代码块折叠动画时长，毫秒，≥0（默认 240）。",
+	},
+	{
+		id: "stickyIncludeCustom", label: "sticky 含扩展消息", type: "boolean", defaultValue: false, cold: true,
+		description: "sticky 吸附池是否包含扩展注入的 CustomMessage（默认 false）。",
+	},
+	{
+		id: "skillResumePreview", label: "resume 预览折回", type: "boolean", defaultValue: true, cold: true,
+		description: "/resume 会话列表预览是否折回 [skill] 名（默认 true）。",
+	},
+	{
+		id: "resultPrefix", label: "结果行前缀", type: "string", defaultValue: "└", cold: false,
+		description: "工具结果行的拐角前缀符号（默认 └；可换 ↳ 或 ⎿）。",
+	},
+	{
+		id: "resultPrefixGap", label: "前缀后空格", type: "number", min: 0, max: 4, integer: true, defaultValue: 1, cold: false,
+		description: "前缀符号与内容之间的空格数，0–4（默认 1）。",
+	},
+	{
+		id: "normalizeForeignRenderers", label: "第三方输出规范化", type: "boolean", defaultValue: true, cold: false,
+		description: "第三方扩展渲染输出的行首 ⎿ 是否统一为 resultPrefix（默认 true）。",
+	},
+	{
+		id: "workflowRendering", label: "Workflow 渲染", type: "enum", values: ["claude", "native"], defaultValue: "claude", cold: true,
+		description: "workflow 完成卡片样式：claude = ● Workflow(name)（默认）；native = 保留包内卡片。",
+	},
+	{
+		id: "foreignCardStyle", label: "未适配卡片样式", type: "enum", values: ["generic", "symbols"], defaultValue: "generic", cold: false,
+		description: "未适配 customType 的卡片：generic = 自动接管为通用卡片（默认）；symbols = 仅统一符号不接管布局。",
+	},
+	{
+		id: "foreignCardSkip", label: "卡片接管黑名单", type: "readonly-array", defaultValue: [], cold: false,
+		description: "不接管的 customType 黑名单（只读；默认 []）。",
+	},
+	// ---- diff.* 7 键（默认值直接引用 vendored DEFAULT_TOOL_DISPLAY_CONFIG，保持同源）----
+	{
+		id: "diff.diffViewMode", label: "diff 视图模式", type: "enum", values: ["auto", "split", "unified"],
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.diffViewMode, cold: false,
+		description: "diff 展示模式：auto / split / unified（默认 auto）。",
+	},
+	{
+		id: "diff.diffIndicatorMode", label: "diff 指示器", type: "enum", values: ["bars", "classic", "none"],
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.diffIndicatorMode, cold: false,
+		description: "diff 变更指示器：bars / classic / none（默认 bars）。",
+	},
+	{
+		id: "diff.diffSplitMinWidth", label: "split 最小宽度", type: "number", min: 0,
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.diffSplitMinWidth, cold: false,
+		description: "split 视图的最小总宽度，低于则回落 unified（默认 120）。",
+	},
+	{
+		id: "diff.editDiffCollapsedLines", label: "edit 折叠行数", type: "number", min: 0,
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.editDiffCollapsedLines, cold: false,
+		description: "edit diff 折叠时显示的上下文行数（默认 0）。",
+	},
+	{
+		id: "diff.writeDiffCollapsedLines", label: "write 折叠行数", type: "number", min: 0,
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.writeDiffCollapsedLines, cold: false,
+		description: "write diff 折叠时显示的上下文行数（默认 0）。",
+	},
+	{
+		id: "diff.diffWordWrap", label: "diff 自动换行", type: "boolean",
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.diffWordWrap, cold: false,
+		description: "diff 行超宽时是否自动换行（默认 true）。",
+	},
+	{
+		id: "diff.expandedPreviewMaxLines", label: "展开预览行上限", type: "number", min: 0,
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.expandedPreviewMaxLines, cold: false,
+		description: "diff 展开态预览的最大行数（默认 40）。",
+	},
+];
+
+export const SETTING_BY_ID: ReadonlyMap<string, SettingDef> = new Map(SETTING_DEFS.map((def) => [def.id, def]));
+
+/** 冷键 id 清单（派生自元数据）：加载期固化，运行时不可 apply。 */
+export const COLD_SETTING_IDS: readonly string[] = SETTING_DEFS.filter((def) => def.cold).map((def) => def.id);
+
+/** 18 个顶层键的默认值对象——loadConfig 的初始值由此构造（默认值单一事实来源）。 */
+export function topLevelDefaults(): Record<string, unknown> {
+	const defaults: Record<string, unknown> = {};
+	for (const def of SETTING_DEFS) {
+		if (!def.id.includes(".")) defaults[def.id] = def.defaultValue;
+	}
+	return defaults;
+}
+
+/* ---------- 值词汇与编辑形态派生（装配侧共用） ---------- */
+
+/** 值显示词汇：面板与文件一致，统一用 JSON 字面量（true / 240 / "└" / ["a","b"]）。 */
+export function toJsonLiteral(value: unknown): string {
+	return JSON.stringify(value) ?? "null";
+}
+
+/** 该键的回车循环域：enum 给合法值集、boolean 给 true/false（JSON 字面量词汇）；无循环编辑的键返回 undefined。 */
+export function cycleValuesOf(def: SettingDef): string[] | undefined {
+	if (def.type === "enum") return (def.values ?? []).map((value) => toJsonLiteral(value));
+	if (def.type === "boolean") return ["true", "false"];
+	return undefined;
+}
+
+/** 该键是否提供输入子菜单编辑：number / string 走子菜单输入框；enum/boolean 走列表循环，readonly-array 只读。 */
+export function hasInputEditor(def: SettingDef): boolean {
+	return def.type === "number" || def.type === "string";
+}
+
+/* ---------- 校验（编辑侧，严格） ---------- */
+
+export type ValidateResult = { ok: true; value: unknown } | { ok: false; error: string };
+
+/** 校验单键取值：非法值拒绝并给出中文错误；通过时返回归一化后的值（≥0 键取整）。 */
+export function validateSetting(id: string, value: unknown): ValidateResult {
+	const def = SETTING_BY_ID.get(id);
+	if (!def) return { ok: false, error: `未知配置键：${id}` };
+	switch (def.type) {
+		case "enum": {
+			if (def.values?.includes(value)) return { ok: true, value };
+			const legal = def.values?.map((v) => JSON.stringify(v)).join(" / ") ?? "";
+			return { ok: false, error: `${def.label} 只接受 ${legal} 之一` };
+		}
+		case "boolean":
+			return typeof value === "boolean"
+				? { ok: true, value }
+				: { ok: false, error: `${def.label} 只接受 true / false` };
+		case "number": {
+			if (typeof value !== "number" || !Number.isFinite(value)) {
+				return { ok: false, error: `${def.label} 需要是数字` };
+			}
+			if (def.integer && !Number.isInteger(value)) {
+				return { ok: false, error: `${def.label} 需要是整数（${def.min}–${def.max}）` };
+			}
+			if (value < (def.min ?? -Infinity) || value > (def.max ?? Infinity)) {
+				const upper = def.max === undefined ? "∞" : def.max;
+				return { ok: false, error: `${def.label} 超出范围 ${def.min}–${upper}` };
+			}
+			return { ok: true, value: def.integer ? value : Math.floor(value) };
+		}
+		case "string":
+			return typeof value === "string" && value.trim()
+				? { ok: true, value }
+				: { ok: false, error: `${def.label} 不能为空白字符串` };
+		case "readonly-array":
+			return { ok: false, error: `${def.label} 为只读黑名单，不支持在此编辑（请手改配置文件）` };
+	}
+}
+
+/* ---------- lean-tidy.json 读写 ---------- */
+
+/** 读现有配置对象：文件不存在或 JSON 损坏按 {} 处理（写回时覆盖损坏内容）。 */
+export function readConfigObject(path: string): Record<string, unknown> {
+	if (!existsSync(path)) return {};
+	try {
+		const data = JSON.parse(readFileSync(path, "utf8"));
+		if (data && typeof data === "object" && !Array.isArray(data)) return data;
+		return {};
+	} catch {
+		return {};
+	}
+}
+
+/** 序列化格式：2 空格缩进 + 末尾换行（与手写习惯一致、diff 友好）。 */
+export function serializeConfig(obj: Record<string, unknown>): string {
+	return `${JSON.stringify(obj, null, 2)}\n`;
+}
+
+/** 同目录临时文件 + rename 原子替换：中断不留半个文件。 */
+export function writeConfigAtomic(path: string, obj: Record<string, unknown>): void {
+	const tmp = join(dirname(path), `${basename(path)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`);
+	writeFileSync(tmp, serializeConfig(obj));
+	renameSync(tmp, path);
+}
+
+/** 在嵌套对象上按点路径取/建容器（"diff.xxx" → obj.diff）。 */
+function nestedContainer(obj: Record<string, unknown>, prefix: string): Record<string, unknown> {
+	const existing = obj[prefix];
+	if (existing && typeof existing === "object" && !Array.isArray(existing)) return existing;
+	const created: Record<string, unknown> = {};
+	obj[prefix] = created;
+	return created;
+}
+
+/** 单键 RMW：校验 → 读现有文件 → 只改目标键路径（含 diff.* 嵌套）→ 保留未知键 → 原子写回。 */
+export function setSettingInFile(path: string, id: string, value: unknown): Record<string, unknown> {
+	const check = validateSetting(id, value);
+	if (!check.ok) throw new Error(check.error);
+	const obj = readConfigObject(path);
+	const dot = id.indexOf(".");
+	if (dot > 0) {
+		nestedContainer(obj, id.slice(0, dot))[id.slice(dot + 1)] = check.value;
+	} else {
+		obj[id] = check.value;
+	}
+	writeConfigAtomic(path, obj);
+	return obj;
+}
+
+/* ---------- 恢复默认的文件语义 ---------- */
+
+export interface ResetFileResult {
+	/** 文件中原本非默认、被本次删除的冷键 id（调用方据此提醒「N 项需 /reload 生效」）。 */
+	coldReset: string[];
+}
+
+/**
+ * 恢复默认：从文件删除全部已知键（顶层 18 + diff 对象内 7 个），未知键保留；
+ * diff 清空后整个移除。文件不存在则不创建（无事可删）。
+ * 冷键默认值均为原始类型（enum/boolean），用严格相等判断「原本非默认」。
+ */
+export function resetConfigFile(path: string): ResetFileResult {
+	if (!existsSync(path)) return { coldReset: [] };
+	const obj = readConfigObject(path);
+	const coldReset: string[] = [];
+	for (const def of SETTING_DEFS) {
+		if (def.id.includes(".")) continue;
+		if (!(def.id in obj)) continue;
+		if (def.cold && obj[def.id] !== def.defaultValue) coldReset.push(def.id);
+		delete obj[def.id];
+	}
+	const diff = obj.diff;
+	if (diff && typeof diff === "object" && !Array.isArray(diff)) {
+		for (const def of SETTING_DEFS) {
+			if (!def.id.startsWith("diff.")) continue;
+			delete (diff as Record<string, unknown>)[def.id.slice("diff.".length)];
+		}
+		if (Object.keys(diff).length === 0) delete obj.diff;
+	}
+	writeConfigAtomic(path, obj);
+	return { coldReset };
+}
+
+/* ---------- 运行时重置（回调注入） ---------- */
+
+/** 运行时 apply 回调：由 index.ts 注入（改 config 对象 / SYMBOLS / diffDisplayConfig）。 */
+export type ApplyFn = (id: string, value: unknown) => void;
+
+/** 热键逐键 apply 默认值；冷键加载期固化、不 apply（/reload 后生效）。 */
+export function applyRuntimeDefaults(apply: ApplyFn): void {
+	for (const def of SETTING_DEFS) {
+		if (!def.cold) apply(def.id, def.defaultValue);
+	}
+}

package/src/skin-setting-panel.ts

@@ -0,0 +1,347 @@
+/**
+ * /skin-setting 设置面板模块（工单 03）。
+ *
+ * 职责：25 键面板行装配（SettingsList 的 SettingItem[]——冷键常驻 ⟳ 标注、
+ * 值用 JSON 字面量、enum/boolean 提供回车循环域）与 TUI overlay 面板的
+ * 挂载/编辑链路。编辑链路（校验 → 写文件 → 运行时原地生效 → 面板行刷新）
+ * 的纯逻辑都在 settings.ts，本模块只做装配；当前值读取与热键 apply 通道
+ * 由 index.ts 注入（避免本模块 import 渲染层，与 settings.ts 同一约束）。
+ *
+ * 数字 / 字符串键的回车输入编辑（子菜单输入框 + 原地错误提示）在工单 04 加入；
+ * readonly-array 键（foreignCardSkip）保持只读展示，不提供 submenu。
+ */
+import { Container, Input, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
+import type { Component, SettingItem } from "@earendil-works/pi-tui";
+import {
+	cycleValuesOf,
+	hasInputEditor,
+	SETTING_BY_ID,
+	SETTING_DEFS,
+	setSettingInFile,
+	toJsonLiteral,
+	validateSetting,
+} from "./settings.ts";
+import type { SettingDef } from "./settings.ts";
+
+/** 面板宽度（列）：60–80 区间取 76——description 换行少、窄终端仍居中可容。 */
+const PANEL_WIDTH = 76;
+/** 可视行数：SettingsList maxVisible ≈ 12。 */
+const MAX_VISIBLE = 12;
+
+export type NotifyLevel = "info" | "warning" | "error";
+type NotifyFn = (message: string, level: NotifyLevel) => void;
+
+export interface SkinSettingPanelDeps {
+	/** 当前值读取通道（index.ts 注入：顶层键 → 共享 config，diff.* → diffDisplayConfig）。 */
+	currentValueOf(id: string): unknown;
+	/** 热键原地生效通道（index.ts 注入；冷键在注入方 no-op——write-only）。 */
+	applySetting(id: string, value: unknown): void;
+	/** lean-tidy.json 路径（即改即存 RMW 的写入目标）。 */
+	configPath: string;
+	/** 整屏重绘（面板关闭时调一次，热键改动的效果即刻可见）。 */
+	forceRedraw(): void;
+}
+
+/**
+ * 值显示词汇：实现已据至 settings.ts（与 cycleValuesOf 同源），此处 re-export 维持原导出面。
+ */
+export { toJsonLiteral };
+
+/**
+ * 主题 fg 单点装配：theme.fg 存在则透传着色，否则原样返回文本。
+ * 列表主题 / 边框 / 输入子菜单三处共用，消除同形状闭包的多处重复。
+ */
+function themeFg(theme: any): (color: string, text: string) => string {
+	return (color, text) => (typeof theme?.fg === "function" ? theme.fg(color, text) : text);
+}
+
+/* ---------- 子菜单输入编辑（工单 04：number / string 键） ---------- */
+
+/** SettingsList 的子菜单 done 契约（settings-list.d.ts）：带值提交 → 行刷新 + onChange；无值 → 仅关闭回原行。 */
+type SubmenuDone = (selectedValue?: string, options?: { navigateTo?: string }) => void;
+
+/** 即改即存提交链路结果：失败时携带中文错误（由调用方决定 notify 还是子菜单原地展示）。 */
+export type CommitResult = { ok: true; value: unknown } | { ok: false; error: string };
+export type CommitFn = (id: string, value: unknown) => CommitResult;
+
+/** 输入约束说明（提示行）：数字键给范围与取整语义，字符串键给非空约束。 */
+function inputConstraintHint(def: SettingDef): string {
+	if (def.type === "number") {
+		const upper = def.max === undefined ? "∞" : String(def.max);
+		return def.integer ? `范围 ${def.min}–${upper}（整数）` : `范围 ≥ ${def.min}（小数自动向下取整）`;
+	}
+	return "trim 后非空";
+}
+
+/** 文本 → 待校验值：数字键 Number() 解析（空输入按 NaN，交给 validateSetting 出中文错误）；字符串键原样。 */
+function parseInputValue(def: SettingDef, text: string): unknown {
+	if (def.type !== "number") return text;
+	const trimmed = text.trim();
+	return trimmed === "" ? Number.NaN : Number(trimmed);
+}
+
+/** 原地错误行：无错误时零行，有错误时一行红色中文提示（非法输入不落盘的呈现位）。 */
+class SubmenuErrorLine implements Component {
+	error: string | null = null;
+	private readonly fg: (color: string, text: string) => string;
+	constructor(fg: (color: string, text: string) => string) {
+		this.fg = fg;
+	}
+	invalidate(): void {}
+	render(_width: number): string[] {
+		return this.error === null ? [] : [this.fg("error", `  ✗ ${this.error}`)];
+	}
+}
+
+/**
+ * 数字 / 字符串键的输入编辑子菜单：标题行（键标签）+ 约束行（范围 / 非空 + 当前值）
+ * + pi-tui Input（placeholder = 当前值）+ 原地错误行 + 操作提示。
+ * 提交流：解析 → 即改即存链路（校验 → 落盘 → 热键原地生效 → 面板行刷新）→
+ * done(新 JSON 字面量) 关子菜单；非法：原地错误行、输入保留、不落盘不关。
+ * Esc：done() 无值关闭，回到列表原行。
+ *
+ * 注意：done 用无 options 的 done(字面量)，不用 { navigateTo: id }——pi-tui 的
+ * closeSubmenu 对 navigateTo 会 selectItem(id) 后 activateItem() 自动重开目标键的
+ * 子菜单，与「提交后关子菜单回原行」矛盾；无 options 的 done 已由 SettingsList
+ * 完成 行刷新（item.currentValue = 值）+ 回原行（submenuItemIndex 恢复）。
+ * 经真实 SettingsList 提交时，本组件先 commit 一次，done → onChange 会再 commit
+ * 一次（幂等：同值重写 + 同值 apply，无副作用）。
+ */
+export class SettingInputSubmenu extends Container {
+	private readonly def: SettingDef;
+	private readonly input: Input;
+	private readonly errorLine: SubmenuErrorLine;
+
+	constructor(
+		def: SettingDef,
+		currentValueJson: string,
+		done: SubmenuDone,
+		commit: CommitFn,
+		fg: (color: string, text: string) => string,
+	) {
+		super();
+		this.def = def;
+		let current: unknown;
+		try {
+			current = JSON.parse(currentValueJson);
+		} catch {
+			current = def.defaultValue;
+		}
+		const placeholder = def.type === "number" ? String(current) : String(current ?? "");
+		this.addChild(new Text(fg("accent", def.label), 1, 0));
+		this.addChild(new Text(fg("muted", `${inputConstraintHint(def)} · 当前 ${currentValueJson}`), 1, 0));
+		this.addChild(new Spacer(1));
+		this.input = new Input({ placeholder, placeholderStyle: (text: string) => fg("dim", text) });
+		this.errorLine = new SubmenuErrorLine(fg);
+		this.input.onSubmit = (text: string) => {
+			const result = commit(def.id, parseInputValue(def, text));
+			if (!result.ok) {
+				// 原地提示不落盘：子菜单里显示中文错误行，输入框保留用户输入供改正，不关子菜单。
+				this.errorLine.error = result.error;
+				return;
+			}
+			this.errorLine.error = null;
+			done(toJsonLiteral(result.value));
+		};
+		this.input.onEscape = () => {
+			done(); // 无值关闭：不触发 onChange，回到列表原行。
+		};
+		this.addChild(this.input);
+		this.addChild(this.errorLine);
+		this.addChild(new Text(fg("dim", "Enter 保存 · Esc 取消"), 1, 0));
+	}
+
+	handleInput(data: string): void {
+		// 新输入作废旧错误（提交时会重新校验给出新结果）；按键全部交给输入框。
+		this.errorLine.error = null;
+		this.input.handleInput(data);
+	}
+}
+
+/**
+ * 面板行装配：25 键 → SettingItem[]。
+ * 冷键标注双保险：label 尾部 ⟳（SettingsList 的 description 只在选中行显示，
+ * 要「常驻可见」必须落在 label 上）+ description 尾部（⟳ 需 /reload 生效）。
+ */
+export function buildSettingItems(currentValueOf: (id: string) => unknown): SettingItem[] {
+	return SETTING_DEFS.map((def) => {
+		const item: SettingItem = {
+			id: def.id,
+			label: def.cold ? `${def.label} ⟳` : def.label,
+			description: def.cold ? `${def.description}（⟳ 需 /reload 生效）` : def.description,
+			currentValue: toJsonLiteral(currentValueOf(def.id)),
+		};
+		// 循环域（enum/boolean）由 settings.ts 的 cycleValuesOf 单点派生；number/string 的输入
+		// submenu 需要提交链路与主题，在 handleSkinSettingCommand 的装配处注入（见 buildPanel）；
+		// 此处保持纯装配不接。readonly-array 保持只读。
+		const values = cycleValuesOf(def);
+		if (values) item.values = values;
+		return item;
+	});
+}
+
+/** 全宽字符（CJK / 全角）按 2 列计——边框行自适应渲染宽度用。 */
+function displayWidth(text: string): number {
+	let width = 0;
+	for (const ch of text) {
+		const code = ch.codePointAt(0) ?? 0;
+		const wide =
+			(code >= 0x1100 && code <= 0x115f) || // 谚文
+			(code >= 0x2e80 && code <= 0x303e) || (code >= 0x3041 && code <= 0x33ff) ||
+			(code >= 0x3400 && code <= 0x4dbf) || (code >= 0x4e00 && code <= 0x9fff) ||
+			(code >= 0xa960 && code <= 0xa97f) || (code >= 0xac00 && code <= 0xd7a3) ||
+			(code >= 0xf900 && code <= 0xfaff) || (code >= 0xfe30 && code <= 0xfe6f) ||
+			(code >= 0xff00 && code <= 0xff60) || (code >= 0xffe0 && code <= 0xffe6);
+		width += wide ? 2 : 1;
+	}
+	return width;
+}
+
+/** 自绘边框行（pi-tui 的 Box 只有 padding+bg 无边框，上/下边框用 ─ 拼）。 */
+class BorderLine implements Component {
+	private readonly makeLine: (width: number) => string;
+	constructor(makeLine: (width: number) => string) {
+		this.makeLine = makeLine;
+	}
+	invalidate(): void {}
+	render(width: number): string[] {
+		return [this.makeLine(Math.max(width, 8))];
+	}
+}
+
+/** 标题边框行：── 皮肤设置（…） ──，标题居中、随渲染宽度自适应。 */
+function titleBorder(fg: (color: string, text: string) => string): BorderLine {
+	return new BorderLine((width) => {
+		const title = " 皮肤设置（回车即改即存 · 输入即搜索） ";
+		const fill = width - displayWidth(title) - 2;
+		const left = Math.max(1, Math.floor(fill / 2));
+		const right = Math.max(1, fill - left);
+		return fg("borderAccent", `─${"─".repeat(left)}${title}${"─".repeat(right)}─`);
+	});
+}
+
+/** 底部边框行：纯 ─ 收尾。 */
+function bottomBorder(fg: (color: string, text: string) => string): BorderLine {
+	return new BorderLine((width) => fg("border", "─".repeat(width)));
+}
+
+/** SettingsList 配色：照 pi 自家 getSettingsListTheme 的口径（选中 accent、未选中 muted、描述 dim）。 */
+function makeListTheme(theme: any) {
+	const fg = themeFg(theme);
+	return {
+		label: (text: string, selected: boolean) => (selected ? fg("accent", text) : text),
+		value: (text: string, selected: boolean) => (selected ? fg("accent", text) : fg("muted", text)),
+		description: (text: string) => fg("dim", text),
+		cursor: fg("accent", "→ "),
+		hint: (text: string) => fg("dim", text),
+	};
+}
+
+/**
+ * 面板组件：标题边框 + SettingsList（搜索 + 25 键 + 选中行描述）+ 底部边框。
+ * 键盘焦点由 overlay 的 setFocus 落在本容器上，handleInput 转发给列表
+ * （搜索输入框与列表按键都由 SettingsList 自己分发）。
+ */
+class SkinSettingPanelComponent extends Container {
+	readonly list: SettingsList;
+	constructor(theme: any, items: SettingItem[], onChange: (id: string, newValue: string) => void, onCancel: () => void) {
+		super();
+		const fg = themeFg(theme);
+		this.list = new SettingsList(items, MAX_VISIBLE, makeListTheme(theme), onChange, onCancel, { enableSearch: true });
+		this.addChild(titleBorder(fg));
+		this.addChild(this.list);
+		this.addChild(bottomBorder(fg));
+	}
+
+	handleInput(data: string): void {
+		this.list.handleInput(data);
+	}
+
+	invalidate(): void {
+		super.invalidate();
+		this.list.invalidate();
+	}
+}
+
+/**
+ * /skin-setting 无参命令处理：TUI 开面板，非 TUI 提示「面板仅 TUI + 文件路径」（守卫自 index.ts 挪入）。
+ * 直接以 (deps, ctx) 函数导出，由 index.ts 接线——原先 createSkinSettingPanel 返回单方法
+ * 对象属 Middle Man；deps 参数本身即注入面，测试走 index.ts 注册的命令面，不受影响。
+ */
+export async function handleSkinSettingCommand(deps: SkinSettingPanelDeps, ctx: any): Promise<void> {
+	function buildPanel(theme: any, done: () => void, notify: NotifyFn): SkinSettingPanelComponent {
+		// 冷键 notify 去抖：同一键同一次面板会话只在首次改动时提醒。
+		// 理由：回车循环极易连按（切过头再切回），每按一次弹一条会刷屏遮挡面板；
+		// 首次提醒已传达「此键需 /reload」，同键后续改动无新信息。重开面板重置（新意图）。
+		const coldNotified = new Set<string>();
+		let panel: SkinSettingPanelComponent;
+		// 即改即存提交链路（enum 循环与子菜单输入共用）：校验 → RMW 落盘 → 热键原地
+		// 生效 → 面板行刷新 → 冷键首次 notify。失败返回中文错误，由调用方决定呈现
+		// （列表循环路径 notify + 行回滚；子菜单路径原地错误行，不关子菜单）。
+		const commit: CommitFn = (id, value) => {
+			// 「未知配置键」错误文案由 validateSetting 单点产出（原先此处的预查是其重复）；
+			// check.ok ⇒ SETTING_BY_ID 必含 id（冷键 notify 还需要 def 元数据，故再取一次）。
+			const check = validateSetting(id, value);
+			if (!check.ok) return { ok: false, error: check.error };
+			const def = SETTING_BY_ID.get(id)!;
+			try {
+				setSettingInFile(deps.configPath, id, check.value);
+			} catch (error: any) {
+				return { ok: false, error: `写入 ${deps.configPath} 失败：${error?.message ?? error}` };
+			}
+			deps.applySetting(id, check.value); // 热键原地生效；冷键 write-only（注入方 no-op）
+			panel.list.updateValue(id, toJsonLiteral(check.value));
+			if (def.cold && !coldNotified.has(id)) {
+				coldNotified.add(id);
+				notify(`⟳ ${def.label} 已写入，/reload 后生效`, "info");
+			}
+			return { ok: true, value: check.value };
+		};
+		const onChange = (id: string, newValueJson: string) => {
+			if (!SETTING_BY_ID.has(id)) return;
+			// SettingsList 循环时已先把行值改掉，回滚基准用运行时真值（apply 还没发生）。
+			const previousJson = toJsonLiteral(deps.currentValueOf(id));
+			let value: unknown;
+			try {
+				value = JSON.parse(newValueJson);
+			} catch {
+				return;
+			}
+			const result = commit(id, value);
+			if (!result.ok) {
+				panel.list.updateValue(id, previousJson);
+				notify(result.error, "error");
+			}
+		};
+		const onCancel = () => {
+			done();
+			deps.forceRedraw();
+		};
+		// number / string 键接上输入子菜单（在面板装配处接：需要 commit 链与主题；
+		// 裸 buildSettingItems 不接，保持纯装配）。diff.* 数字键与顶层数字键同一条路径，
+		// 类型判定由 settings.ts 的 hasInputEditor 单点提供。
+		const fg = themeFg(theme);
+		const items = buildSettingItems(deps.currentValueOf).map((item) => {
+			const def = SETTING_BY_ID.get(item.id);
+			if (def && hasInputEditor(def)) {
+				item.submenu = (currentValue: string, doneSubmenu: SubmenuDone) =>
+					new SettingInputSubmenu(def, currentValue, doneSubmenu, commit, fg);
+			}
+			return item;
+		});
+		panel = new SkinSettingPanelComponent(theme, items, onChange, onCancel);
+		return panel;
+	}
+
+	const notify: NotifyFn = (message, level) => {
+		ctx?.ui?.notify?.(message, level);
+	};
+	if (ctx?.mode !== "tui" || typeof ctx?.ui?.custom !== "function") {
+		notify(`用法：/skin-setting 打开设置面板（仅 TUI 模式）；/skin-setting default 恢复默认。配置文件：${deps.configPath}`, "info");
+		return;
+	}
+	await ctx.ui.custom(
+		(_tui: any, theme: any, _keybindings: any, done: () => void) => buildPanel(theme, done, notify),
+		{ overlay: true, overlayOptions: { anchor: "center" as const, width: PANEL_WIDTH } },
+	);
+}