dsh-vscode-mode 0.13.1 → 0.14.0

package/src/client/ui/EditorView.ts

@@ -50,12 +50,15 @@ import { editorHeight } from '../editorLayout.js'
 import { revealInExplorer as revealPathInExplorer } from '../fileReveal.js'
 import { setSidePending, SIDEBAR_INSTALL_CMD } from '../sidebarBridge.js'
 import { upsertViewState, viewStatesLoad, viewStatesSave } from '../state/viewStateCache.js'
+import { mdPreviewLoad, mdPreviewSave } from '../state/mdPreviewCache.js'
+import { onUiStateReady, reportUiStateEvent, uiStateSettled } from '../state/uiStatePersist.js'
 import { migrateScopedKeys, workspaceScopeOf } from '../state/scopeStore.js'
 import { modelsForScope, rememberModel } from '../state/modelCache.js'
 import { navFlashRangeOf } from '../navHighlight.js'
 import { chordOf, useKeybindingsVersion } from '../keybindings.js'
 import { getSidebarMinWidth } from '../sidebarMin.js'
 import { navHistoryFor } from '../navHistory.js'
+import { navStateLoad, navStateSave } from '../state/navStateCache.js'
 import { statusOfAdd } from '../addToConversation.js'
 import { setSearchScope, setSearchSeed } from '../searchSeed.js'
 import { CACHE_KEY } from '../paths.js'
@@ -324,6 +327,8 @@ export function EditorView(props) {
   const loadSeqRef = React.useRef(0)
   const programmaticRef = React.useRef(false)
   const restoredScopeRef = React.useRef(null) // 已恢复状态的作用域（cwd 晚到 sid→ws 时允许重恢复）
+  // 界面状态镜像迟到回填的触发器（重启换 origin：首帧 localStorage 为空，回填后需重跑恢复）
+  const [hydrateTick, setHydrateTick] = React.useState(0)
   const pendingFocusRef = React.useRef(null) // { path, region, line, column } 内容加载后跳转
   const navFlashRef = React.useRef([]) // 跳转目标高亮装饰 id（独立于 diff/下划线，随跳转替换）
   const navFlashTimerRef = React.useRef(null) // 跳转目标高亮自动清除计时器
@@ -1299,6 +1304,8 @@ export function EditorView(props) {
     // model 缓存跟随作用域（切工作区释放旧作用域模型；同工作区跨挂载复用）
     modelsRef.current = modelsForScope(scope)
     viewStatesRef.current = viewStatesLoad(scope)
+    // Markdown 预览态同样按作用域恢复（重启/换端口后由界面状态镜像回填，见 lateHydrateRef 分支）
+    mdPreviewRef.current = mdPreviewLoad(String(scope))
     try {
       // v3 优先；缺失时回读 v2（旧版纯路径数组）——normalizeTabs 兼容两种形状
       const raw = localStorage.getItem(CACHE_KEY.editor + String(scope))
@@ -1320,28 +1327,64 @@ export function EditorView(props) {
           const kept = plan.length ? restored.filter((tab) => !dropped.has(tab.path)) : restored
           setTabs(kept)
           setActive(kept.some((tab) => tab.path === activePath) ? activePath : (kept[0]?.path ?? null))
+          reportUiStateEvent(
+            '页签恢复（scope=' + String(scope) + '）：存档 ' + restored.length + ' 个、保留 ' + kept.length
+            + ' 个、活动 ' + String(activePath),
+          )
+        } else {
+          reportUiStateEvent('页签恢复（scope=' + String(scope) + '）：存档非空但归一化后为 0 个')
         }
+      } else {
+        reportUiStateEvent('页签恢复（scope=' + String(scope) + '）：localStorage 无存档')
       }
-    } catch (e) { /* 损坏忽略 */ }
-  }, [sessionId, scope])
+    } catch (e) {
+      reportUiStateEvent('页签恢复失败（scope=' + String(scope) + '）: ' + String(e), 'warn')
+    }
+  }, [sessionId, scope, hydrateTick])
+
+  // 镜像迟到回填：重启换 origin 时首帧读不到存档，host 回填完成后重跑一次恢复。
+  // 仅在本页签尚未恢复出任何内容时重跑（用户已打开/关闭过页签则不打扰）。
+  React.useEffect(() => onUiStateReady(() => {
+    if (tabsRef.current.length) return
+    restoredScopeRef.current = null
+    setHydrateTick((v) => v + 1)
+  }), [])
 
   // 导航历史按工作区作用域隔离：同工作区切换对话保留历史，跨工作区换实例
   React.useEffect(() => {
-    navRef.current = navHistoryFor(scope)
+    const history = navHistoryFor(scope)
+    // 空实例（首次创建/换作用域）才用存档恢复，避免覆盖本次会话已积累的历史；
+    // 换 origin 时存档由镜像迟到回填，hydrateTick 变化后再跑一次本效应
+    const current = history.snapshot()
+    if (!current.past.length && !current.future.length) {
+      const saved = navStateLoad(String(scope))
+      if (saved) history.restore(saved)
+      reportUiStateEvent(
+        '导航历史恢复（scope=' + String(scope) + '）：'
+        + (saved ? 'past=' + saved.past.length + ' future=' + saved.future.length : 'localStorage 无存档'),
+      )
+    }
+    navRef.current = history
     navPendingRef.current = null
     if (navCursorTimerRef.current) { clearTimeout(navCursorTimerRef.current); navCursorTimerRef.current = null }
     setNavTick((v) => v + 1)
-  }, [scope])
+  }, [scope, hydrateTick])
 
+  // 导航双栈落 localStorage（同原文去重写；镜像层负责跨重启）：刷新/重启后前进后退与当前位置仍在
   React.useEffect(() => {
-    if (!sessionId) return
+    if (!sessionId || !uiStateSettled()) return
+    navStateSave(String(scope), navRef.current?.snapshot?.() ?? null)
+  }, [navTick, cursor, active, sessionId, scope, hydrateTick])
+
+  React.useEffect(() => {
+    if (!sessionId || !uiStateSettled()) return
     try {
       // v3 写入：页签带 pinned（只写有值字段，减小体积）；固定态随工作区作用域持久化
       const payload = { tabs: tabs.map((t) => (t.pinned ? { path: t.path, pinned: true } : { path: t.path })), active }
       localStorage.setItem(CACHE_KEY.editor + String(scope), JSON.stringify(payload))
     }
     catch (e) { /* 忽略 */ }
-  }, [tabs, active, sessionId, scope])
+  }, [tabs, active, sessionId, scope, hydrateTick])
 
   /**
    * 标记页签为「最近使用」（LRU 序号单调递增；编辑动作也算使用，见 onEdit）。
@@ -1394,9 +1437,17 @@ export function EditorView(props) {
         if (typeof saved.on === 'boolean') setSidebarOn(saved.on)
         if (typeof saved.width === 'number') setSidebarW(Math.max(getSidebarMinWidth(), Math.min(560, saved.width)))
         if (typeof saved.panel === 'string') setActivePanel(saved.panel)
+        reportUiStateEvent(
+          '侧栏恢复（键 ' + sidebarKey + '）：on=' + String(saved.on) + ' width=' + String(saved.width)
+          + ' panel=' + String(saved.panel),
+        )
+      } else {
+        reportUiStateEvent('侧栏恢复（键 ' + sidebarKey + '）：localStorage 无存档')
       }
-    } catch (e) { /* 损坏忽略 */ }
-  }, [sessionId, sidebarKey])
+    } catch (e) {
+      reportUiStateEvent('侧栏恢复失败（键 ' + sidebarKey + '）: ' + String(e), 'warn')
+    }
+  }, [sessionId, sidebarKey, hydrateTick])
 
   // 侧边栏最小宽度设置变更（edrv:sidebar-min-width）→ 更新 minW 并重夹当前宽度
   const [sidebarMinW, setSidebarMinW] = React.useState(() => getSidebarMinWidth())
@@ -1411,10 +1462,10 @@ export function EditorView(props) {
 
   // 侧边栏状态持久化
   React.useEffect(() => {
-    if (!sessionId) return
+    if (!sessionId || !uiStateSettled()) return
     try { localStorage.setItem(sidebarKey, JSON.stringify({ on: sidebarOn, width: sidebarW, panel: activePanel })) }
     catch (e) { /* 忽略 */ }
-  }, [sidebarOn, sidebarW, activePanel, sessionId, sidebarKey])
+  }, [sidebarOn, sidebarW, activePanel, sessionId, sidebarKey, hydrateTick])
   // 编辑器键位（侧栏/保存/搜索/Markdown 预览/导航/页签循环）已归官方 shortcuts 机制派发：
   // 官方 resolve → 指令注册表 run → `edrv.command.*` 事件 → 下方「指令系统接线」表执行。
   // 历史 capture 监听移除（与官方派发并存会双执行）；Markdown 预览的「非 .md 不吞键」
@@ -2014,6 +2065,8 @@ export function EditorView(props) {
     // 卸载即切作用域/重挂载：先把待记录光标落进历史，再存当前文件视图状态
     //（经 ref 取最新闭包，修正旧实现捕获挂载时 active 的问题）
     flushNavCursor()
+    // 关页面/切作用域前把双栈落到 localStorage（镜像层 flush 负责写穿 host）
+    navStateSave(String(scope), navRef.current?.snapshot?.() ?? null)
     saveViewStateRef.current?.()
     diffRendererRef.current?.dispose?.()
     hideReferencesOverlay()
@@ -2536,6 +2589,8 @@ export function EditorView(props) {
       next.delete(path)
     }
     mdPreviewRef.current = next
+    // 预览态按作用域落 localStorage（镜像层写穿 host）：刷新/重启后仍以预览打开
+    mdPreviewSave(String(scope), next)
     setStatus(entering ? '已切换为 Markdown 预览' : '已切换为源码编辑')
   }
   toggleMdPreviewRef.current = toggleMdPreview

package/src/paths.ts

@@ -25,6 +25,8 @@ export const DSH_DIR_NAME = '.dsh'
 export const DSH_HOME_ENV = 'DSH_HOME'
 /** 树缓存 schema 版本（文件名携带；版本递增即触发旧版清理）。 */
 export const TREE_CACHE_SCHEMA = 1
+/** UI 状态镜像 schema 版本（文件名携带；版本递增即触发旧版清理）。 */
+export const UI_STATE_SCHEMA = 1
 /** LSP provider 发现缓存 schema 版本（格式变更即递增，旧文件自动失效）。 */
 export const LSP_SPEC_CACHE_SCHEMA = 4
 /** 树缓存保留期：超期文件视为废弃（工作区搬迁/废弃残留）。 */
@@ -161,6 +163,31 @@ export function treeCacheFile(cwd: string, home = dshHome(), schema = TREE_CACHE
   return join(workspaceCacheDir(hashOf(cwd), home), 'tree.v' + schema + '.json')
 }
 
+/**
+ * 每工作区 UI 状态镜像文件（工作区级：workspace/<id>/ui.v<schema>.json）。
+ * 存编辑器页签/侧栏/预览态等界面状态的 localStorage 原值副本，供换 origin 后回填。
+ * @author ddj 2026年09月28号
+ * @param cwd 工作区绝对路径
+ * @param home DSH home（测试可注入）
+ * @param schema schema 版本（缺省 UI_STATE_SCHEMA）
+ * @returns UI 状态镜像文件绝对路径
+ */
+export function uiStateFile(cwd: string, home = dshHome(), schema = UI_STATE_SCHEMA): string {
+  return join(workspaceCacheDir(hashOf(cwd), home), 'ui.v' + schema + '.json')
+}
+
+/**
+ * 用户级 UI 状态镜像文件（跨工作区共享：user/ui-globals.v<schema>.json）。
+ * 存与工作区无关的全局键（侧栏提示已忽略、工作区折叠态等）。
+ * @author ddj 2026年09月28号
+ * @param home DSH home（测试可注入）
+ * @param schema schema 版本（缺省 UI_STATE_SCHEMA）
+ * @returns 全局 UI 状态镜像文件绝对路径
+ */
+export function uiGlobalsFile(home = dshHome(), schema = UI_STATE_SCHEMA): string {
+  return join(userCacheDir(home), 'ui-globals.v' + schema + '.json')
+}
+
 /** 每工作区 debug 日志文件（用户级日志根下，按 cwd hash 隔离）。 */
 export function debugLogFile(cwd: string, home = dshHome()): string {
   return join(pluginLogRoot(home), 'debug.' + hashOf(cwd) + '.log')
@@ -201,6 +228,37 @@ export function treeSchemaOf(filename: string): number | null {
   return m ? Number(m[1]) : null
 }
 
+/**
+ * 已知缓存文件种类 → 当前 schema 版本（sweep 判旧依据）。
+ * 新增缓存文件必须登记在此，否则被当作未知残留清理。
+ */
+const CACHE_SCHEMAS: Record<string, number> = {
+  tree: TREE_CACHE_SCHEMA,
+  'lsp-specs': LSP_SPEC_CACHE_SCHEMA,
+  ui: UI_STATE_SCHEMA,
+  'ui-globals': UI_STATE_SCHEMA,
+}
+
+/** 缓存文件名 → 种类与 schema 版本（`<kind>.v<schema>.json`；未登记种类/命名不合规 → null）。 */
+function parseCacheName(filename: string): { kind: string; schema: number } | null {
+  const m = /^([a-z-]+)\.v(\d+)\.json$/.exec(filename)
+  if (!m) return null
+  const kind = m[1]
+  if (CACHE_SCHEMAS[kind] === undefined) return null
+  return { kind, schema: Number(m[2]) }
+}
+
+/**
+ * 该缓存文件名是否为已登记种类的当前 schema 版本（sweep 判旧/判残留依据）。
+ * @author ddj 2026年09月28号
+ * @param filename 缓存文件名（不含目录）
+ * @returns 已登记种类且版本为当前版本
+ */
+export function isCurrentCacheFile(filename: string): boolean {
+  const parsed = parseCacheName(filename)
+  return parsed !== null && parsed.schema === CACHE_SCHEMAS[parsed.kind]
+}
+
 /** 按「schema 版本 + 保留期」清扫某目录内文件（目录级，返回相对路径清单）。 */
 async function sweepDirFiles(dir: string, removed: string[], now: number, dropAll: boolean): Promise<void> {
   const names = await readdir(dir).catch(() => [])
@@ -208,9 +266,7 @@ async function sweepDirFiles(dir: string, removed: string[], now: number, dropAl
     const full = join(dir, name)
     let drop = dropAll
     if (!drop) {
-      const schema = treeSchemaOf(name)
-      if (schema === null) drop = true // 未知残留
-      else if (schema !== TREE_CACHE_SCHEMA) drop = true // 旧版本
+      if (!isCurrentCacheFile(name)) drop = true // 未知残留 / 旧版本
       else {
         try {
           const info = await stat(full)

package/src/rpc.ts

@@ -46,7 +46,8 @@ import { baseNameOf, checkNewName, checkRenameName, isSubPath, joinRelPath, pare
 import { invalidateIndex, listDirCached } from './treeIndex.js'
 import { findRemoteWs, remoteDisplayOf, type RemoteWs } from './remoteWorkspace.js'
 import { revealInExplorer } from './reveal.js'
-import { dshHome, debugLogFile, pluginLogRoot } from './paths.js'
+import { dshHome, debugLogFile, pluginLogRoot, uiGlobalsFile, uiStateFile } from './paths.js'
+import { readUiState, writeUiState } from './uiState.js'
 import { clearDebugLog, debugRecord, isDebugLogName, listDebugLogs, readDebugLog } from './debugLog.js'
 import { markActiveSessions, markOfficialFlags, moveOutSessions, planMoveOut, purgeArchive, restoreSession, scanSessionInventory, sessionsArchiveRoot, sessionSizeOf, sidecarSummaryOf, unarchiveOfficial } from './perf.js'
 import { patchHasPerfConfig, patchInsertPerfConfig, patchRemovePerfConfig, perfConfigBlock } from './perfPatch.js'
@@ -57,6 +58,12 @@ import { settingsDocPath } from './settingsDocPath.js'
 const staleCheckedAt = new Map<string, number>()
 /** stale 自动清理最小间隔。 */
 const STALE_CHECK_MIN_MS = 10_000
+/**
+ * 无会话期诊断的伪 cwd：冷启动早期本插件客户端就会上报界面状态镜像事件
+ * （此时 `sessions` 可能尚未就绪，`requireSession` 会失败），退回本固定值落盘
+ * `logs/debug.<hashOf(该值)>.log`，保证「换 origin 后没恢复」这类问题的诊断不丢。
+ */
+const UI_AUDIT_CWD = 'ui-state'
 
 /** 记录 → 客户端视图（不含 before 全文，仅长度）；远程工作区附远端展示路径（issue #7）。 */
 function recView(record: DiffRecord, ws: RemoteWs | null = null): RecordView {
@@ -465,6 +472,40 @@ export function buildHandlers(
       out.sort((a, b) => (a.at < b.at ? -1 : 1))
       return { ok: true, records: out }
     },
+    /**
+     * 界面状态镜像读取：回填换 origin（Web GUI 重启换端口）后丢失的 localStorage 界面状态。
+     * 文件缺失/损坏 → 空表（客户端自然不动作）。
+     * @author ddj 2026年09月28号
+     */
+    'edrv.uiState.get': async (args) => {
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const keys = await readUiState(uiStateFile(sc.cwd))
+      const globals = await readUiState(uiGlobalsFile())
+      return { ok: true, keys, globals }
+    },
+    /**
+     * 界面状态镜像写入：把客户端改动过的 `edrv.*` 键增量同步到 host 文件（空补丁不落盘）。
+     * 失败时写一条诊断日志（默认静默的客户端 dbg 之外的可查证据），并如实回错误由客户端逐键回退。
+     * @author ddj 2026年09月28号 / 2026年09月29号
+     */
+    'edrv.uiState.set': async (args) => {
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const tasks: Array<Promise<{ ok: true } | { ok: false; error: string }>> = []
+      if (args.keys && Object.keys(args.keys).length) tasks.push(writeUiState(uiStateFile(sc.cwd), args.keys))
+      if (args.globals && Object.keys(args.globals).length) tasks.push(writeUiState(uiGlobalsFile(), args.globals))
+      const results = await Promise.all(tasks)
+      const failed = results.find((item) => !item.ok)
+      if (failed && !failed.ok) {
+        const keyCount = Object.keys(args.keys ?? {}).length
+        const globalCount = Object.keys(args.globals ?? {}).length
+        debugRecord(ctx, sc.cwd, '界面状态镜像写入失败: ' + failed.error
+          + '（keys=' + keyCount + ' 键, globals=' + globalCount + ' 键）', 'warn')
+        return { ok: false, error: failed.error }
+      }
+      return { ok: true }
+    },
     'edrv.accept': async (args) => {
       const sc = await requireSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false, error: sc.err }
@@ -749,9 +790,15 @@ export function buildHandlers(
     'edrv.debug': async (args) => {
       // 诊断日志：client 上报 → debugLog 模块缓冲批量落盘 ~/.dsh/dsh-vscode-mode/logs/
       // （console 不一定落盘，文件可靠）。只出现在调试开关开启时（client dbg 默认关）。
+      const text = String(args.text ?? '')
       const sc = await requireSession(ctx, args.sessionId)
-      if ('err' in sc) return { ok: false, error: sc.err }
-      debugRecord(ctx, sc.cwd, String(args.text ?? ''), args.level)
+      if ('err' in sc) {
+        // 会话未就绪（冷启动早期、界面状态镜像水合期）也必须能落盘：否则换 origin 后的
+        // 「水合失败/放弃」诊断全部丢失，只剩「界面没恢复」这个不可观测的现象。
+        debugRecord(ctx, UI_AUDIT_CWD, text, args.level)
+        return { ok: true }
+      }
+      debugRecord(ctx, sc.cwd, text, args.level)
       return { ok: true }
     },
     'edrv.dlog.list': async (args) => {

package/src/shared/rpc.ts

@@ -331,6 +331,24 @@ export interface DebugLogRead {
   truncated: boolean
 }
 
+/** 界面状态镜像快照（edrv.uiState.get）：界面状态键值表 + 跨工作区全局键值表。 */
+export interface UiStateSnapshot {
+  /** 工作区级键值表（localStorage 键 → 字符串原值）。 */
+  keys: Record<string, string>
+  /** 全局键值表（与工作区无关，跨工作区共享）。 */
+  globals: Record<string, string>
+}
+
+/** 界面状态镜像写入补丁（edrv.uiState.set）：值 null 表示删除该键。 */
+export interface UiStatePatchInput {
+  /** 会话 id（缺省取唯一活跃会话）。 */
+  sessionId?: string
+  /** 工作区级增量补丁。 */
+  keys?: Record<string, string | null>
+  /** 全局增量补丁。 */
+  globals?: Record<string, string | null>
+}
+
 /** 每个方法的请求参数（sessionId 为公共可选字段）。 */
 export interface RpcRequestMap {
   'edrv.list': { sessionId?: string; callIds?: string[]; skipStale?: boolean }
@@ -481,6 +499,10 @@ export interface RpcRequestMap {
   'edrv.dap.variables': { ref: number }
   'edrv.dap.evaluate': { expression: string; frameId?: number }
   'edrv.dap.command': { action: DapAction }
+  /** 界面状态镜像读取：回填换 origin（重启换端口）后丢失的 localStorage 界面状态。 */
+  'edrv.uiState.get': { sessionId?: string }
+  /** 界面状态镜像写入：把客户端改动过的 `edrv.*` 键增量同步到 host 文件。 */
+  'edrv.uiState.set': UiStatePatchInput
 }
 
 export type RpcMethod = keyof RpcRequestMap
@@ -632,6 +654,8 @@ export interface RpcOkMap {
   'edrv.dap.variables': { variables: DapVariableView[] }
   'edrv.dap.evaluate': { result: string; type?: string; ref: number }
   'edrv.dap.command': object
+  'edrv.uiState.get': UiStateSnapshot
+  'edrv.uiState.set': object
 }
 
 /** 统一响应：{ok:true, ...payload} 或 {ok:false, error}。 */

package/src/uiState.ts

@@ -0,0 +1,165 @@
+/**
+ * dsh-vscode-mode host — UI 状态镜像存储（界面状态的跨重启记忆）。
+ * 背景：Web GUI 的 origin（含端口）可能每次启动变化，而 localStorage 按 origin 分区，
+ * 于是页签/侧栏/预览态等状态随重启一并丢失。这里把客户端 `edrv.*` 键的字符串原值
+ * 按工作区镜像到 host 文件（workspace/<hash>/ui.v<schema>.json；全局键走 user/），
+ * 启动时原样回填本地缺失的键。
+ * 值不解析、不校验业务格式（客户端自会解析并丢弃损坏值），只保证键值对可靠落盘：
+ * - 原子写：先写临时文件再 rename，避免半截文件
+ * - 串行化：同一文件的写操作链式排队，避免并发丢更新
+ * - 容量上限：序列化超过 UI_STATE_BYTES_CAP 即拒写（客户端保留 localStorage，不丢数据）
+ * 纯函数（parse/serialize/merge）与文件读写均参数注入，可单测。
+ * 作者 ddj 2026-09-28
+ */
+import { Buffer } from 'node:buffer'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+// --region 常量与类型
+/** UI 状态镜像文档版本（与文件名 schema 解耦：文件名管失效，字段管结构）。 */
+export const UI_STATE_VERSION = 1
+/** UI 状态镜像容量上限：序列化后超出即拒写（客户端回退纯 localStorage）。 */
+export const UI_STATE_BYTES_CAP = 512 * 1024
+
+/** UI 状态镜像文档。 */
+export interface UiStateDoc {
+  /** 文档版本（不匹配即视为损坏）。 */
+  version: number
+  /** 最后写入时间（ISO 字符串，仅供排查）。 */
+  updatedAt: string
+  /** 界面状态键值表（localStorage 键 → 字符串原值）。 */
+  keys: Record<string, string>
+}
+
+/** 增量补丁：值 null/undefined 表示删除该键（localStorage 值恒为字符串，语义无歧义）。 */
+export type UiStatePatch = Record<string, string | null | undefined>
+// --endregion
+
+// --region 纯函数
+/**
+ * 合并增量补丁到键值表（不改入参）。
+ * @author ddj 2026年09月28号
+ * @param base 已有键值表
+ * @param patch 增量补丁（null/undefined 值删除该键；空键跳过）
+ * @returns 合并后的新键值表
+ */
+export function mergeUiStateKeys(base: Record<string, string>, patch: UiStatePatch): Record<string, string> {
+  const merged: Record<string, string> = { ...base }
+  for (const [key, value] of Object.entries(patch)) {
+    if (!key) continue
+    if (value === null || value === undefined) delete merged[key]
+    else merged[key] = String(value)
+  }
+  return merged
+}
+
+/**
+ * 解析镜像文件文本；损坏/版本不符 → null（调用方视为空）。
+ * @author ddj 2026年09月28号
+ * @param text 文件文本（可为空）
+ * @returns 解析后的文档；不可用时 null
+ */
+export function parseUiState(text: string | null | undefined): UiStateDoc | null {
+  if (!text) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch (error) {
+    return null
+  }
+  if (!raw || typeof raw !== 'object') return null
+  const doc = raw as { version?: unknown; updatedAt?: unknown; keys?: unknown }
+  if (doc.version !== UI_STATE_VERSION) return null
+  if (!doc.keys || typeof doc.keys !== 'object') return null
+  const keys: Record<string, string> = {}
+  for (const [key, value] of Object.entries(doc.keys as Record<string, unknown>)) {
+    if (!key || typeof value !== 'string') continue
+    keys[key] = value
+  }
+  return {
+    version: UI_STATE_VERSION,
+    updatedAt: typeof doc.updatedAt === 'string' ? doc.updatedAt : '',
+    keys,
+  }
+}
+
+/**
+ * 序列化为镜像文件文本。
+ * @author ddj 2026年09月28号
+ * @param keys 键值表
+ * @param updatedAt 更新时间（缺省当前时间）
+ * @returns 文件文本
+ */
+export function serializeUiState(keys: Record<string, string>, updatedAt = new Date().toISOString()): string {
+  const doc: UiStateDoc = { version: UI_STATE_VERSION, updatedAt, keys }
+  return JSON.stringify(doc)
+}
+// --endregion
+
+// --region 文件读写
+/** 同文件写队列尾（串行化并发写入；队列清空即移除条目）。 */
+const writeChains = new Map<string, Promise<unknown>>()
+
+/**
+ * 把写任务挂到该文件的队尾串行执行（前序失败不影响后续）。
+ * @author ddj 2026年09月28号
+ * @param file 目标文件绝对路径
+ * @param run 实际写操作
+ * @returns 本次写操作结果
+ */
+function chainWrite<T>(file: string, run: () => Promise<T>): Promise<T> {
+  const prev = writeChains.get(file) ?? Promise.resolve()
+  const next = prev.then(run, run)
+  const tail = next.then(() => undefined, () => undefined)
+  writeChains.set(file, tail)
+  void tail.then(() => {
+    if (writeChains.get(file) === tail) writeChains.delete(file)
+  })
+  return next
+}
+
+/**
+ * 读取镜像文件的键值表（文件缺失/损坏/不可读 → 空表，静默）。
+ * @author ddj 2026年09月28号
+ * @param file 镜像文件绝对路径
+ * @returns 键值表（localStorage 键 → 字符串原值）
+ */
+export async function readUiState(file: string): Promise<Record<string, string>> {
+  try {
+    const doc = parseUiState(await readFile(file, 'utf8'))
+    return doc ? doc.keys : {}
+  } catch (error) {
+    return {}
+  }
+}
+
+/**
+ * 合并写入镜像文件（读旧 → 合并补丁 → 容量校验 → 原子替换），同文件写操作串行。
+ * @author ddj 2026年09月28号
+ * @param file 镜像文件绝对路径
+ * @param patch 增量补丁（null/undefined 值删除该键）
+ * @returns ok；超限或写入失败时 ok:false + 中文错误文案
+ */
+export async function writeUiState(
+  file: string,
+  patch: UiStatePatch,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  return chainWrite(file, async () => {
+    try {
+      const merged = mergeUiStateKeys(await readUiState(file), patch)
+      const json = serializeUiState(merged)
+      if (Buffer.byteLength(json, 'utf8') > UI_STATE_BYTES_CAP) {
+        return { ok: false as const, error: '界面状态镜像超出容量上限（' + UI_STATE_BYTES_CAP + ' 字节）' }
+      }
+      await mkdir(dirname(file), { recursive: true })
+      const tmp = file + '.tmp'
+      await writeFile(tmp, json, 'utf8')
+      await rename(tmp, file)
+      return { ok: true as const }
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+      return { ok: false as const, error: '界面状态写入失败: ' + reason }
+    }
+  })
+}
+// --endregion