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

package/README.md

@@ -1,41 +1,59 @@
 # @yinan_chen/pi-claude-code-ui
 
+English | [简体中文](README.zh-CN.md)
+
 ![preview](assets/preview.png)
 
-### 演示
+### Demo
 
 ![demo](https://github.com/user-attachments/assets/d264935a-79fc-434e-be97-05c8210144fe)
 
-动图预览（不渲染视频的平台，如 npm）： ![gif](assets/demo.gif)
+Animated GIF preview (for platforms that don't render video, such as npm): ![gif](assets/demo.gif)
 
-> 原名 lean-tidy —— Claude Code 风格的 Pi 界面增强扩展：Claude 式对话转录视图、富文本 diff 渲染、子代理面板与工作状态提示。
+> Formerly lean-tidy — a Claude Code-style UI enhancement extension for Pi: Claude-style conversation transcript views, rich diff rendering, subagent panels, and working-state hints.
 
-## 安装
+## Install
 
 ```bash
 pi install npm:@yinan_chen/pi-claude-code-ui
 ```
 
-试运行（不写入配置）：
+Trial run (doesn't write to your config):
 
 ```bash
 pi -e npm:@yinan_chen/pi-claude-code-ui
 ```
 
-## 功能
+## Features
+
+- **Claude-style views** — conversation transcript adapter, with Pi native fallback
+- **Sticky message bubble** — pins the user message currently being answered at the top while scrolling; click to jump back (built in since v0.2.0; formerly the sticky-first-message extension)
+- **Skill recollapse** — expanded skill invocations automatically fold back to `/skill:name args`, covering four blind spots such as /tree and /fork backfill (built in since v0.2.0; formerly the skill-block-recollapse extension)
+- **Full third-party renderer takeover** — cards from any extension (including future unmatched ones) render automatically in a unified `● card` style, covering tools / messages / entries at all three layers, zero config and zero adaptation; dispatch-layer interception is unaffected by load order (v0.7.0)
+- **Rich diff rendering** — syntax-highlighted diffs for edit/write tools (vendored, MIT)
+- **Subagent panel** — background agent status at a glance
+- **Working-state hints** — working message / running effect
+- **Polished read-only tools** — rendering for read / bash / grep / find / ls results
+- **Skin Settings panel** — `/skin-setting` adjusts every skin setting with save-as-you-edit; `/skin-setting default` resets to defaults in one shot (v0.9.0)
+
+## Configuration
+
+### Recommended: the `/skin-setting` panel
+
+Type `/skin-setting` in a pi session to open the centered overlay Skin Settings panel, where changes save as you make them — every edit is validated, written to the config file immediately, and reflected in the panel row, with no save/discard burden:
+
+- Built-in search filtering to quickly locate any of the 25 config keys; each row shows its description and default value
+- Enum / boolean keys cycle through legal values on Enter, so you can't pick an invalid one; number / string keys open an input box on Enter with range validation (e.g. 0–100, 0–4)
+- Most keys are live settings — once you change them and close the panel, a full redraw makes them visible at once; reload-required settings are fixed at load time, carry a persistent `⟳ needs /reload` annotation, and get one extra reminder when changed
+- The `foreignCardSkip` blocklist is shown read-only — its state stays visible without risk of accidental edits
+- `/skin-setting default`: one-shot reset to defaults after a confirmation dialog (only this skin's config keys are removed; anything else you wrote in the file is kept)
+- In non-TUI modes (RPC / JSON / print) it prints the config file path instead — use the file-based approach below
 
-- **Claude 式视图** — 对话转录适配器，Pi 原生回退
-- **吸附消息泡（sticky）** — 滚动时顶部吸附显示当前正在回答的用户消息原文，点击回位（v0.2.0 内置，原 sticky-first-message 扩展）
-- **Skill 折叠（recollapse）** — 展开的 skill 全文自动折回 `/skill:名 参数`，覆盖 /tree、/fork 回填等四处盲区（v0.2.0 内置，原 skill-block-recollapse 扩展）
-- **第三方渲染全接管** — 任何扩展的卡片（含未来未适配的）自动渲染为统一的 `● 卡片` 风格，工具/消息/条目三层全覆盖，零配置零适配；分发层拦截不受加载顺序影响（v0.7.0）
-- **富 diff 渲染** — edit/write 工具的语法高亮 diff（vendored, MIT）
-- **子代理面板** — 后台 agent 状态一目了然
-- **工作状态提示** — working message / running effect
-- **只读工具美化** — read/bash/grep/find/ls 结果渲染
+**F5** forces a full-screen redraw at any time (the habitual fix for leftover artifacts).
 
-## 配置
+### Editing the config file directly
 
-配置文件：`~/.pi/agent/lean-tidy.json`（不存在时全部使用默认值）：
+You can also edit `~/.pi/agent/lean-tidy.json` directly (when the file doesn't exist, all defaults apply). Manual edits take effect after `/reload`; panel edits apply instantly for live settings, while reload-required settings (those marked `⟳` in the table below) need `/reload`:
 
 ```json
 {
@@ -69,36 +87,36 @@ pi -e npm:@yinan_chen/pi-claude-code-ui
 }
 ```
 
-| 键 | 默认 | 说明 |
+| Key | Default | Description |
 |---|---|---|
-| `profile` | `"claude"` | 整体风格：`claude` / `native`（pi 原生） |
-| `skillRendering` | `"native"` | skill 块样式：pi 原生折叠行 / `claude` 两行风格 |
-| `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] 名` 单行 |
-| `resultPrefix` | `"└"` | 工具结果行拐角前缀（制表符族，等宽字体最稳；可换 `↳` 或 Claude Code 官方的 `⎿`，后两者在部分字体下会变宽） |
-| `resultPrefixGap` | `1` | 前缀符号与内容之间的空格数（0–4） |
-| `normalizeForeignRenderers` | `true` | 第三方扩展卡片输出里行首 `⎿` 自动规范化为 `resultPrefix`（任何未适配扩展的渲染都能统一风格；关闭可看第三方原版） |
-| `workflowRendering` | `"claude"` | workflow 完成卡片样式：`● Workflow(name)` 风格 / `native` 保留包内卡片。分发层拦截实现，不受包加载顺序影响 |
-| `foreignCardStyle` | `"generic"` | 未适配扩展的卡片：自动接管为通用 `● 卡片`（零配置）；`symbols` = 仅统一符号不接管布局 |
-| `foreignCardSkip` | `[]` | 不接管的 customType 黑名单（交互型第三方卡片异常时按类型跳过） |
-| `diff.diffViewMode` | `"auto"` | diff 视图：`auto`/`split`/`unified` |
-| `diff.diffIndicatorMode` | `"bars"` | 变更指示条：`bars`/`classic`/`none` |
-| `diff.diffSplitMinWidth` | `120` | 宽于此才用 split 视图 |
-| `diff.edit/writeDiffCollapsedLines` | `0`/`0` | edit/write 默认折叠行数（0 = 默认展开） |
-| `diff.diffWordWrap` | `true` | diff 自动换行 |
-| `diff.expandedPreviewMaxLines` | `40` | 展开后最多显示行数 |
-
-## 兼容性
-
-按 `VERIFIED_PI_VERSION = 1.0.2` 验收；版本不一致时扩展会在 session 启动时提示一次。
-
-## 从源码安装
+| `profile` ⟳ | `"claude"` | Overall look: claude = Claude Code-style views (default); native = pi native fallback. |
+| `skillRendering` | `"native"` | Skill invocation block style: native = pi native [skill] collapsed line (default); claude = ● Skill(name) two-line style. |
+| `subagentRendering` ⟳ | `"claude"` | Subagent completion notice style: claude = ● Subagent(desc) + branches (default); native = keep the bundled panel. |
+| `detailsBackground` | `"selectedBg"` | Background color of the expanded tool details area; theme color key — `customMessageBg`/`toolPendingBg`/`toolSuccessBg`/`toolErrorBg` also work, `""` = none. |
+| `bash/code/errorPreviewLines` | `0`/`0`/`0` | Preview lines for the three tool-result classes, 0–100 (0 = collapsed by default): bash output / read-write-edit-find tools / failed results. |
+| `liveThinking` | `true` | Stream thinking blocks as they arrive. |
+| `thinkingTailLines` | `5` | Lines kept at the tail when thinking is collapsed, ≥0. |
+| `foldAnimMs` | `240` | Code block fold animation duration in milliseconds, ≥0 (0 disables it). |
+| `stickyIncludeCustom` ⟳ | `false` | Whether the sticky bubble includes side-channel messages: CustomMessages injected by extensions or forwarded across sessions. |
+| `skillResumePreview` ⟳ | `true` | Whether the /resume session list preview folds back to [skill] names. |
+| `resultPrefix` | `"└"` | Corner prefix symbol for tool result lines (tab-drawing glyphs are the most reliable in monospace fonts; `↳` or Claude Code's official `⎿` also work, though both may widen in some fonts). |
+| `resultPrefixGap` | `1` | Spaces between the prefix symbol and content, 0–4. |
+| `normalizeForeignRenderers` | `true` | Rewrite the leading ⎿ of third-party extension output to resultPrefix (unifies the style of any unmatched extension's rendering; turn it off to see the third-party original). |
+| `workflowRendering` ⟳ | `"claude"` | Workflow completion card style: claude = ● Workflow(name) (default); native = keep the bundled card. Dispatch-layer interception, unaffected by package load order. |
+| `foreignCardStyle` | `"generic"` | Cards for unmatched customTypes: generic = take over as a unified `● card` (zero config); symbols = unify symbols only, keep layout. |
+| `foreignCardSkip` | `[]` | customType blocklist never taken over (skip by type when an interactive third-party card misbehaves). |
+| `diff.diffViewMode` | `"auto"` | Diff display mode: auto / split / unified. |
+| `diff.diffIndicatorMode` | `"bars"` | Diff change indicator: bars / classic / none. |
+| `diff.diffSplitMinWidth` | `120` | Minimum total width for split view; falls back to unified below it. |
+| `diff.edit/writeDiffCollapsedLines` | `0`/`0` | Context lines kept when edit / write diffs are collapsed (0 = expanded by default). |
+| `diff.diffWordWrap` | `true` | Wrap overly wide diff lines. |
+| `diff.expandedPreviewMaxLines` | `40` | Maximum lines for expanded diff previews. |
+
+## Compatibility
+
+Verified against `VERIFIED_PI_VERSION = 1.0.2`; on a version mismatch the extension shows a single notice at session startup.
+
+## Install from source
 
 ```bash
 pi install git:github.com/chenyn273/pi-claude-code-ui@v0.2.0

package/README.zh-CN.md

@@ -0,0 +1,123 @@
+# @yinan_chen/pi-claude-code-ui
+
+[English](README.md) | 简体中文
+
+![preview](assets/preview.png)
+
+### 演示
+
+![demo](https://github.com/user-attachments/assets/d264935a-79fc-434e-be97-05c8210144fe)
+
+动图预览（不渲染视频的平台，如 npm）： ![gif](assets/demo.gif)
+
+> 原名 lean-tidy —— Claude Code 风格的 Pi 界面增强扩展：Claude 式对话转录视图、富文本 diff 渲染、子代理面板与工作状态提示。
+
+## 安装
+
+```bash
+pi install npm:@yinan_chen/pi-claude-code-ui
+```
+
+试运行（不写入配置）：
+
+```bash
+pi -e npm:@yinan_chen/pi-claude-code-ui
+```
+
+## 功能
+
+- **Claude 式视图** — 对话转录适配器，Pi 原生回退
+- **吸附消息泡（sticky）** — 滚动时顶部吸附显示当前正在回答的用户消息原文，点击回位（v0.2.0 内置，原 sticky-first-message 扩展）
+- **Skill 折叠（recollapse）** — 展开的 skill 全文自动折回 `/skill:名 参数`，覆盖 /tree、/fork 回填等四处盲区（v0.2.0 内置，原 skill-block-recollapse 扩展）
+- **第三方渲染全接管** — 任何扩展的卡片（含未来未适配的）自动渲染为统一的 `● 卡片` 风格，工具/消息/条目三层全覆盖，零配置零适配；分发层拦截不受加载顺序影响（v0.7.0）
+- **富 diff 渲染** — edit/write 工具的语法高亮 diff（vendored, MIT）
+- **子代理面板** — 后台 agent 状态一目了然
+- **工作状态提示** — working message / running effect
+- **只读工具美化** — read/bash/grep/find/ls 结果渲染
+- **设置面板** — `/skin-setting` 即改即存调整全部皮肤配置，`/skin-setting default` 一键恢复默认（v0.9.0）
+
+## 配置
+
+### 推荐方式：`/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
+{
+  "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": [],
+  "diff": {
+    "diffViewMode": "auto",
+    "diffIndicatorMode": "bars",
+    "diffSplitMinWidth": 120,
+    "editDiffCollapsedLines": 0,
+    "writeDiffCollapsedLines": 0,
+    "diffWordWrap": true,
+    "expandedPreviewMaxLines": 40
+  }
+}
+```
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `profile` ⟳ | `"claude"` | 整体风格：`claude` / `native`（pi 原生） |
+| `skillRendering` | `"native"` | skill 块样式：pi 原生折叠行 / `claude` 两行风格 |
+| `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] 名` 单行 |
+| `resultPrefix` | `"└"` | 工具结果行拐角前缀（制表符族，等宽字体最稳；可换 `↳` 或 Claude Code 官方的 `⎿`，后两者在部分字体下会变宽） |
+| `resultPrefixGap` | `1` | 前缀符号与内容之间的空格数（0–4） |
+| `normalizeForeignRenderers` | `true` | 第三方扩展卡片输出里行首 `⎿` 自动规范化为 `resultPrefix`（任何未适配扩展的渲染都能统一风格；关闭可看第三方原版） |
+| `workflowRendering` ⟳ | `"claude"` | workflow 完成卡片样式：`● Workflow(name)` 风格 / `native` 保留包内卡片。分发层拦截实现，不受包加载顺序影响 |
+| `foreignCardStyle` | `"generic"` | 未适配扩展的卡片：自动接管为通用 `● 卡片`（零配置）；`symbols` = 仅统一符号不接管布局 |
+| `foreignCardSkip` | `[]` | 不接管的 customType 黑名单（交互型第三方卡片异常时按类型跳过） |
+| `diff.diffViewMode` | `"auto"` | diff 视图：`auto`/`split`/`unified` |
+| `diff.diffIndicatorMode` | `"bars"` | 变更指示条：`bars`/`classic`/`none` |
+| `diff.diffSplitMinWidth` | `120` | 宽于此才用 split 视图 |
+| `diff.edit/writeDiffCollapsedLines` | `0`/`0` | edit/write 默认折叠行数（0 = 默认展开） |
+| `diff.diffWordWrap` | `true` | diff 自动换行 |
+| `diff.expandedPreviewMaxLines` | `40` | 展开后最多显示行数 |
+
+## 兼容性
+
+按 `VERIFIED_PI_VERSION = 1.0.2` 验收；版本不一致时扩展会在 session 启动时提示一次。
+
+## 从源码安装
+
+```bash
+pi install git:github.com/chenyn273/pi-claude-code-ui@v0.2.0
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yinan_chen/pi-claude-code-ui",
-	"version": "0.8.9",
+	"version": "0.9.1",
 	"description": "Claude Code-style UI for Pi: transcript view, rich diffs, subagent panels and working-message status.",
 	"type": "module",
 	"license": "MIT",
@@ -20,7 +20,8 @@
 	],
 	"files": [
 		"src",
-		"README.md"
+		"README.md",
+		"README.zh-CN.md"
 	],
 	"pi": {
 		"extensions": [

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,14 +564,80 @@ 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.reloadRequired) 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?.(
+				"Restore default settings",
+				"This will delete all known skin config keys from lean-tidy.json (unknown keys are kept); live settings revert immediately. Continue?",
+			);
+		} catch { confirmed = false; }
+		if (!confirmed) return; // Esc / 取消：文件与运行时零改动。
+		const { reloadRequiredReset } = resetConfigFile(CONFIG_PATH);
+		// diff 显示配置先整体回出厂拷贝（文件 diff 里的未知键不留在运行时），
+		// 再走统一的热键 apply 通道逐键重置（幂等，值相同）。
+		diffDisplayConfig = { ...DEFAULT_TOOL_DISPLAY_CONFIG };
+		applyRuntimeDefaults(applySetting);
+		forceRedraw();
+		if (reloadRequiredReset.length > 0) ctx?.ui?.notify?.(`Defaults restored — ${reloadRequiredReset.length} setting(s) need /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: skin settings (default = reset to defaults)",
+		getArgumentCompletions(prefix: string) {
+			const items = [{ value: "default", label: "default", description: "Reset all settings to defaults (unknown keys are kept)" }];
+			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?.(
+				`Unknown argument "${arg}". Usage: /skin-setting opens the settings panel (TUI only); /skin-setting default restores defaults. Config file: ${CONFIG_PATH}`,
+				"info",
+			);
 		},
 	});
+
 	pi.registerShortcut("f5" as any, {
-		description: "lean-tidy: 强制整屏重绘",
+		description: "lean-tidy: force full redraw",
 		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 生效。 */
+	reloadRequired: boolean;
+}
+
+/** 25 键元数据。默认值是唯一事实来源：loadConfig 经 topLevelDefaults() 消费，消除双源。 */
+export const SETTING_DEFS: readonly SettingDef[] = [
+	// ---- 顶层 18 键 ----
+	{
+		id: "profile", label: "Profile", type: "enum", values: ["claude", "native"], defaultValue: "claude", reloadRequired: true,
+		description: "Overall look: claude = Claude Code-style views (default); native = pi native fallback.",
+	},
+	{
+		id: "skillRendering", label: "Skill rendering", type: "enum", values: ["native", "claude"], defaultValue: "native", reloadRequired: false,
+		description: "Skill invocation block style: native = pi native [skill] collapsed line (default); claude = ● Skill(name) two-line style.",
+	},
+	{
+		id: "subagentRendering", label: "Subagent rendering", type: "enum", values: ["native", "claude"], defaultValue: "claude", reloadRequired: true,
+		description: "Subagent completion notice style: claude = ● Subagent(desc) + branches (default); native = keep the bundled panel.",
+	},
+	{
+		id: "detailsBackground", label: "Details background", type: "enum",
+		values: ["selectedBg", "customMessageBg", "toolPendingBg", "toolSuccessBg", "toolErrorBg", ""],
+		defaultValue: "selectedBg", reloadRequired: false,
+		description: "Background color of the expanded tool details area (default selectedBg; empty string = no background).",
+	},
+	{
+		id: "bashPreviewLines", label: "Bash preview lines", type: "number", min: 0, max: 100, integer: true, defaultValue: 0, reloadRequired: false,
+		description: "Output preview lines for collapsed bash tool results, 0–100 (default 0).",
+	},
+	{
+		id: "codePreviewLines", label: "Code preview lines", type: "number", min: 0, max: 100, integer: true, defaultValue: 0, reloadRequired: false,
+		description: "Preview lines for collapsed read / write / edit / find tools, 0–100 (default 0).",
+	},
+	{
+		id: "errorPreviewLines", label: "Error preview lines", type: "number", min: 0, max: 100, integer: true, defaultValue: 0, reloadRequired: false,
+		description: "Preview lines for collapsed failed tool results, 0–100 (default 0).",
+	},
+	{
+		id: "liveThinking", label: "Live thinking stream", type: "boolean", defaultValue: true, reloadRequired: false,
+		description: "Stream thinking blocks as they arrive (default true).",
+	},
+	{
+		id: "thinkingTailLines", label: "Thinking tail lines", type: "number", min: 0, defaultValue: 5, reloadRequired: false,
+		description: "Lines kept at the tail when thinking is collapsed, ≥0 (default 5).",
+	},
+	{
+		id: "foldAnimMs", label: "Fold animation duration", type: "number", min: 0, defaultValue: 240, reloadRequired: false,
+		description: "Code block fold animation duration in milliseconds, ≥0 (default 240).",
+	},
+	{
+		id: "stickyIncludeCustom", label: "Sticky includes custom messages", type: "boolean", defaultValue: false, reloadRequired: true,
+		description: "Whether the sticky pool includes CustomMessages injected by extensions (default false).",
+	},
+	{
+		id: "skillResumePreview", label: "Resume preview fold-back", type: "boolean", defaultValue: true, reloadRequired: true,
+		description: "Whether the /resume session list preview folds back to [skill] names (default true).",
+	},
+	{
+		id: "resultPrefix", label: "Result line prefix", type: "string", defaultValue: "└", reloadRequired: false,
+		description: "Corner prefix symbol for tool result lines (default └; can be ↳ or ⎿).",
+	},
+	{
+		id: "resultPrefixGap", label: "Prefix gap", type: "number", min: 0, max: 4, integer: true, defaultValue: 1, reloadRequired: false,
+		description: "Spaces between the prefix symbol and content, 0–4 (default 1).",
+	},
+	{
+		id: "normalizeForeignRenderers", label: "Normalize foreign renderers", type: "boolean", defaultValue: true, reloadRequired: false,
+		description: "Rewrite the leading ⎿ of third-party extension output to resultPrefix (default true).",
+	},
+	{
+		id: "workflowRendering", label: "Workflow rendering", type: "enum", values: ["claude", "native"], defaultValue: "claude", reloadRequired: true,
+		description: "Workflow completion card style: claude = ● Workflow(name) (default); native = keep the bundled card.",
+	},
+	{
+		id: "foreignCardStyle", label: "Foreign card style", type: "enum", values: ["generic", "symbols"], defaultValue: "generic", reloadRequired: false,
+		description: "Cards for unmatched customTypes: generic = take over as a generic card (default); symbols = unify symbols only, keep layout.",
+	},
+	{
+		id: "foreignCardSkip", label: "Card takeover blocklist", type: "readonly-array", defaultValue: [], reloadRequired: false,
+		description: "customType blocklist never taken over (read-only; default []).",
+	},
+	// ---- diff.* 7 键（默认值直接引用 vendored DEFAULT_TOOL_DISPLAY_CONFIG，保持同源）----
+	{
+		id: "diff.diffViewMode", label: "Diff view mode", type: "enum", values: ["auto", "split", "unified"],
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.diffViewMode, reloadRequired: false,
+		description: "Diff display mode: auto / split / unified (default auto).",
+	},
+	{
+		id: "diff.diffIndicatorMode", label: "Diff indicator", type: "enum", values: ["bars", "classic", "none"],
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.diffIndicatorMode, reloadRequired: false,
+		description: "Diff change indicator: bars / classic / none (default bars).",
+	},
+	{
+		id: "diff.diffSplitMinWidth", label: "Split min width", type: "number", min: 0,
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.diffSplitMinWidth, reloadRequired: false,
+		description: "Minimum total width for split view; falls back to unified below it (default 120).",
+	},
+	{
+		id: "diff.editDiffCollapsedLines", label: "Edit collapsed lines", type: "number", min: 0,
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.editDiffCollapsedLines, reloadRequired: false,
+		description: "Context lines shown when an edit diff is collapsed (default 0).",
+	},
+	{
+		id: "diff.writeDiffCollapsedLines", label: "Write collapsed lines", type: "number", min: 0,
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.writeDiffCollapsedLines, reloadRequired: false,
+		description: "Context lines shown when a write diff is collapsed (default 0).",
+	},
+	{
+		id: "diff.diffWordWrap", label: "Diff word wrap", type: "boolean",
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.diffWordWrap, reloadRequired: false,
+		description: "Wrap overly wide diff lines (default true).",
+	},
+	{
+		id: "diff.expandedPreviewMaxLines", label: "Expanded preview max lines", type: "number", min: 0,
+		defaultValue: DEFAULT_TOOL_DISPLAY_CONFIG.expandedPreviewMaxLines, reloadRequired: false,
+		description: "Maximum lines for expanded diff previews (default 40).",
+	},
+];
+
+export const SETTING_BY_ID: ReadonlyMap<string, SettingDef> = new Map(SETTING_DEFS.map((def) => [def.id, def]));
+
+/** 冷键 id 清单（派生自元数据）：加载期固化，运行时不可 apply。 */
+export const RELOAD_REQUIRED_SETTING_IDS: readonly string[] = SETTING_DEFS.filter((def) => def.reloadRequired).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: `Unknown setting key: ${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} only accepts one of ${legal}` };
+		}
+		case "boolean":
+			return typeof value === "boolean"
+				? { ok: true, value }
+				: { ok: false, error: `${def.label} only accepts true / false` };
+		case "number": {
+			if (typeof value !== "number" || !Number.isFinite(value)) {
+				return { ok: false, error: `${def.label} must be a number` };
+			}
+			if (def.integer && !Number.isInteger(value)) {
+				return { ok: false, error: `${def.label} must be an integer (${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} is out of range ${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} cannot be a blank string` };
+		case "readonly-array":
+			return { ok: false, error: `${def.label} is a read-only blocklist; edit the config file manually` };
+	}
+}
+
+/* ---------- 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 生效」）。 */
+	reloadRequiredReset: string[];
+}
+
+/**
+ * 恢复默认：从文件删除全部已知键（顶层 18 + diff 对象内 7 个），未知键保留；
+ * diff 清空后整个移除。文件不存在则不创建（无事可删）。
+ * 冷键默认值均为原始类型（enum/boolean），用严格相等判断「原本非默认」。
+ */
+export function resetConfigFile(path: string): ResetFileResult {
+	if (!existsSync(path)) return { reloadRequiredReset: [] };
+	const obj = readConfigObject(path);
+	const reloadRequiredReset: string[] = [];
+	for (const def of SETTING_DEFS) {
+		if (def.id.includes(".")) continue;
+		if (!(def.id in obj)) continue;
+		if (def.reloadRequired && obj[def.id] !== def.defaultValue) reloadRequiredReset.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 { reloadRequiredReset };
+}
+
+/* ---------- 运行时重置（回调注入） ---------- */
+
+/** 运行时 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.reloadRequired) 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 ? `Range ${def.min}–${upper} (integer)` : `Range ≥ ${def.min} (fractional values are floored)`;
+	}
+	return "non-blank after 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)} · current ${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 to save · Esc to cancel"), 1, 0));
+	}
+
+	handleInput(data: string): void {
+		// 新输入作废旧错误（提交时会重新校验给出新结果）；按键全部交给输入框。
+		this.errorLine.error = null;
+		this.input.handleInput(data);
+	}
+}
+
+/**
+ * 面板行装配：25 键 → SettingItem[]。
+ * 冷键标注双保险：label 尾部 ⟳（SettingsList 的 description 只在选中行显示，
+ * 要「常驻可见」必须落在 label 上）+ description 尾部 (⟳ needs /reload)。
+ */
+export function buildSettingItems(currentValueOf: (id: string) => unknown): SettingItem[] {
+	return SETTING_DEFS.map((def) => {
+		const item: SettingItem = {
+			id: def.id,
+			label: def.reloadRequired ? `${def.label} ⟳` : def.label,
+			description: def.reloadRequired ? `${def.description} (⟳ needs /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))];
+	}
+}
+
+/** 标题边框行：── Skin Settings（…） ──，标题居中、随渲染宽度自适应（副句表达即改即存与输入即搜索）。 */
+function titleBorder(fg: (color: string, text: string) => string): BorderLine {
+	return new BorderLine((width) => {
+		const title = " Skin Settings (auto-save on change · type to search) ";
+		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 reloadRequiredNotified = 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: `Failed to write ${deps.configPath}: ${error?.message ?? error}` };
+			}
+			deps.applySetting(id, check.value); // 热键原地生效；冷键 write-only（注入方 no-op）
+			panel.list.updateValue(id, toJsonLiteral(check.value));
+			if (def.reloadRequired && !reloadRequiredNotified.has(id)) {
+				reloadRequiredNotified.add(id);
+				notify(`⟳ ${def.label} saved — takes effect after /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(`Usage: /skin-setting opens the settings panel (TUI only); /skin-setting default restores defaults. Config file: ${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 } },
+	);
+}