dsh-vscode-mode 0.13.0 → 0.14.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.13.0",
-  "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 DSH 0.1.5+ 官方右侧 Sidebar 与对话同屏）+ 命令栏（Ctrl+Shift+P）与可扩展指令系统 + VS Code 兼容代码片段（.code-snippets 全局/项目，IntelliSense 展开）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚）+ SVN 集成（侧栏变更面板/日志弹窗/并排差异）+ 语言服务器（LSP）智能（跳转定义/引用/hover/大纲 + VSIX 扩展市场安装），状态持久化到工作区旁车",
+  "version": "0.14.0",
+  "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 DSH 0.1.5+ 官方右侧 Sidebar 与对话同屏）+ 命令栏（Ctrl+Shift+P）与可扩展指令系统 + VS Code 兼容代码片段（.code-snippets 全局/项目，IntelliSense 展开）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚）+ SVN 集成（侧栏变更面板/日志弹窗/并排差异）+ 语言服务器（LSP）智能（跳转定义/引用/hover/大纲 + VSIX 扩展市场安装），状态持久化到工作区旁车，界面状态（页签/光标/侧栏/编辑 Tab/导航历史）镜像到 DSH home 跨重启恢复",
   "icon": "assets/icon.svg",
   "keywords": [
     "dsh",

package/src/client/index.ts

@@ -33,7 +33,7 @@ import { setupExtOpen } from './externalOpen.js'
 import { SettingsContext } from './settingsContext.js'
 import { SIDEBAR_PLUGIN, registerSlotSafely, settingsBridge } from './compat.js'
 import { detectSidebarService, hasSideRoute, installSideEditor, routeSideEditor, setEnsureSideEditor, SIDEBAR_INSTALL_CMD } from './sidebarBridge.js'
-import { detectOfficial, installOfficial, registerOfficialFileClaim, OFFICIAL_TAB_KIND, OFFICIAL_TAB_TITLE, isEditorTabActive, restoreEditorTab, buildFileAddress } from './officialSidebar.js'
+import { detectOfficial, installOfficial, registerOfficialFileClaim, OFFICIAL_TAB_KIND, OFFICIAL_TAB_TITLE, isEditorTabActive, markEditorActive, restoreEditorTab, buildFileAddress, readSavedTab, setEditorTabScope } from './officialSidebar.js'
 import { setNativeCsv, setNativeOpenHandler, resetNativeOpen } from './nativeOpenStore.js'
 import { SideEditorTab } from './ui/SideEditorTab.js'
 import { OfficialSideTab } from './ui/OfficialSideTab.js'
@@ -56,7 +56,6 @@ import type { CommandBridge } from './commandBridge.js'
 import { REGISTRY_GLOBAL } from './commandGlobals.js'
 import { awaitShortcutsService, bindCatalogChords, detectShortcuts, installLegacyKeys, migrateLegacyKeybindings, registerOfficialShortcuts } from './shortcutsOfficial.js'
 import { SHORTCUT_PROFILES, defaultKeybindings, normalizeKeybindings } from '../shared/keybindings.js'
-import { ShortcutSettings } from './ui/ShortcutSettings.js'
 import { sidebarMinApply } from './sidebarMin.js'
 import { editorLimitApply } from './editorLimit.js'
 import { log } from './log.js'
@@ -65,6 +64,8 @@ import { disposeSnippets } from './snippets/provider.js'
 import { disposeLaunchJson } from './dap/launchSnippetProvider.js'
 import { disposeAiInline } from './ai/inlineProvider.js'
 import { readSessionScope, subscribeScope } from './sessionScope.js'
+import { flushUiState, hydrateUiState, installUiStatePersist, onUiStateReady, reportUiStateEvent, uiStateSettled } from './state/uiStatePersist.js'
+import { workspaceScopeOf } from './state/scopeStore.js'
 import { dapStore } from './dap/store.js'
 import type { CompatAdapter } from '../shared/compat.js'
 
@@ -115,8 +116,48 @@ function setupCommands(ctx: any): CommandBridge {
  * @param ctx 客户端根上下文（slots + timer 服务）
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function apply(ctx: any): void {
+export async function apply(ctx: any): Promise<void> {
   const schedule = (fn: () => void, ms: number) => ctx.timeout(fn, ms)
+
+  /**
+   * 无门控上报界面状态镜像事件（绕过客户端 edrv.debug 开关，直接落 host 诊断日志）。
+   * 开关关闭时 dbg 直接 return，「重启后没恢复」这类问题会在客户端侧彻底无痕，故另开一条通路。
+   * @author ddj 2026年09月29号
+   * @param text 事件文本
+   * @param level 日志级别（缺省 'debug'）
+   */
+  const reportMirror = (text: string, level?: string): void => {
+    // 只认 host 侧已知级别，其余落 'debug'（镜像内部只发 'debug'/'warn'）
+    const lv = level === 'info' || level === 'warn' || level === 'error' ? level : 'debug'
+    try {
+      void rpc('edrv.debug', { sessionId: readSessionScope(ctx).sessionId, text: 'ui-state: ' + text, level: lv })
+        .catch(() => { /* 诊断上报失败忽略 */ })
+    } catch (error) { /* 会话未就绪等异常忽略 */ }
+  }
+
+  // 界面状态镜像：把 `edrv.*` 的 localStorage 状态写穿到 host，换 origin（重启换端口）后回填。
+  // 必须早于任何界面首次读写 localStorage（编辑器页签/侧栏/预览态的恢复逻辑都读它）。
+  if (installUiStatePersist(ctx, schedule, reportMirror)) {
+    reportMirror('镜像装配成功（origin=' + (typeof location === 'undefined' ? '?' : location.origin) + '）')
+    log.info('界面状态镜像已装配：界面状态随 host 持久化（重启/换端口可恢复）')
+  } else {
+    reportMirror('镜像装配失败：localStorage 不可用', 'warn')
+    log.warn('界面状态镜像不可用（无 localStorage）：界面状态仅存当前 origin')
+  }
+
+  // 争取「回填先于任何界面组件挂载」：面板/编辑器的恢复逻辑都在挂载时读 localStorage，
+  // 挂载后再回填只能靠 `edrv:ui-state-ready` 事件补跑（目前编辑器页签/侧栏已支持）。
+  // 已知会话时这次 RPC 是本地往返（通常几十毫秒），故短超时即可；会话未就绪则不在此等待，
+  // 交给镜像内部重试与迟到回填事件，避免拖慢启动。
+  if (readSessionScope(ctx).sessionId) {
+    try {
+      await Promise.race([
+        hydrateUiState(),
+        new Promise<void>((resolve) => { schedule(() => resolve(), 600) }),
+      ])
+    } catch (error) { /* 水合失败已在镜像内降级 */ }
+  }
+  ctx.effect(() => () => { void flushUiState() }, 'vscode-mode: ui state flush')
   ctx.effect(() => {
     let disposed = false
     let attempts = 0
@@ -483,6 +524,22 @@ export function apply(ctx: any): void {
       return
     }
     officialDisposer = ctx.effect(() => outcome, 'vscode-mode: official sidebar editor tab')
+    // 编辑 Tab 展开/激活态按工作区落 localStorage（镜像层写穿 host，重启/换端口后仍在）：
+    // 冷启动据此自动回到上次的编辑 Tab；官方 openTab 幂等，已激活时不重复调用。
+    setEditorTabScope(() => {
+      const scope = readSessionScope(ctx)
+      return workspaceScopeOf(scope.cwd, scope.sessionId)
+    })
+    const restoreActiveTab = (): void => {
+      const saved = readSavedTab()
+      const active = isEditorTabActive()
+      reportUiStateEvent('编辑 Tab 恢复：本地存档=' + String(saved) + '、当前激活=' + String(active))
+      if (!active && saved) markEditorActive(true)
+      restoreEditorTab(official.service, schedule)
+    }
+    restoreActiveTab()
+    // 换 origin 时本地 localStorage 为空：镜像回填完成后重判一次，迟到的回填同样能恢复编辑 Tab
+    ctx.effect(() => onUiStateReady(restoreActiveTab), 'vscode-mode: editor tab state hydration')
     // 官方打开器（下拉「官方侧边栏」选项，动态出现；openResource 能力缺失时跳过）+ 按当前设置同步 file 地址认领
     if (typeof official.service.openResource === 'function') {
       ctx.effect(() => registry.register(officialSidebarOpener(official.service)), 'vscode-mode: official sidebar opener')
@@ -575,16 +632,13 @@ export function apply(ctx: any): void {
     id: 'vscode-mode',
     order: 30,
     label: 'VSCodeMode',
-  }, () => React.createElement(SettingsContext.Provider, { value: bridge.scope() }, React.createElement(McpSettings, { openerRegistry: registry, compatSummary })))
-
-  // 独立「快捷键」设置区（与 VSCodeMode 平级）：官方快捷键子页 + 插件快捷键子页。
-  // 服务经 getShortcuts 运行时探测（自愈），组件内部自带就绪重试。
-  registerSlotSafely(ctx, {
-    name: 'settings.section',
-    id: 'vscode-mode-shortcuts',
-    order: 31,
-    label: '快捷键',
-  }, () => React.createElement(ShortcutSettings, { getShortcuts: () => detectShortcuts(ctx) }))
+  }, () => React.createElement(SettingsContext.Provider, { value: bridge.scope() }, React.createElement(McpSettings, {
+    openerRegistry: registry,
+    compatSummary,
+    // 快捷键统一走 DSH 官方配置：通用页只提供「打开官方快捷键配置」入口。
+    // 服务运行时探测（自愈）：旧版 DSH 无该服务时按钮给出手动打开方式。
+    getShortcuts: () => detectShortcuts(ctx),
+  })))
 
   // 卸载收尾（G4，DSH 0.1.6-alpha.2 起支持运行时卸载/重载）：
   // 注销挂在存活的 window.monaco 上的全部 Monaco provider 并复位模块状态。
@@ -597,4 +651,20 @@ export function apply(ctx: any): void {
     // 原生打开范围复位回默认集（handler 解绑已由其自身 ctx.effect disposer 承担）
     try { resetNativeOpen() } catch { /* 同上 */ }
   }, 'vscode-mode: monaco providers teardown')
+
+  // 会话晚到补试：冷启动早期 `sessions` 未就绪时 host 答「会话不存在」，首次水合会失败重试；
+  // 作用域变化（sid→ws）后同样补一次，保证界面状态尽早回填。
+  ctx.effect(() => subscribeScope(ctx, () => {
+    if (!uiStateSettled()) void hydrateUiState()
+  }), 'vscode-mode: ui state rehydrate')
+
+  // 争取「回填先于界面首次读 localStorage」：宿主若 await 本 apply，此处等到水合结束（或 1.2s 超时兜底）。
+  // 失败/超时不抛：镜像内部自带重试与结束事件，界面侧还有迟到回填重跑。
+  try {
+    await Promise.race([
+      hydrateUiState(),
+      new Promise<void>((resolve) => { schedule(() => resolve(), 1200) }),
+    ])
+  } catch (error) { /* 水合失败已在镜像内降级 */ }
+  reportUiStateEvent('客户端装配完成：水合' + (uiStateSettled() ? '已结束' : '仍在进行（界面稍后重跑恢复）'))
 }

package/src/client/navHistory.ts

@@ -36,6 +36,10 @@ export interface NavHistory {
   peekBack(): NavEntry | null
   /** 前进目标条目（不改变状态；不可进 → null）。 */
   peekForward(): NavEntry | null
+  /** 导出双栈快照（浅拷贝；持久化用）。 */
+  snapshot(): NavState
+  /** 用存档恢复双栈（调用方仅在实例为空时调用；非法项丢弃、超限截断）。 */
+  restore(state: NavState | null | undefined): void
 }
 
 /** 后退栈默认容量上限（超出逐出最旧）。 */
@@ -44,6 +48,37 @@ export const NAV_HISTORY_CAP = 200
 /** 工作区历史实例缓存上限（FIFO 逐出最久未用作用域，防长期驻留泄漏）。 */
 export const NAV_SCOPE_CAP = 6
 
+/** 持久化单栈容量上限（存档只留最近若干条，防 localStorage 膨胀）。 */
+export const NAV_PERSIST_CAP = 30
+
+/** 导航历史双栈快照（持久化/恢复用；viewState 由 viewStateCache 按路径另行恢复）。 */
+export interface NavState {
+  past: NavEntry[]
+  future: NavEntry[]
+}
+
+/**
+ * 归一化条目数组：丢弃无路径项；line/column 仅保留正整数，剥掉 viewState（体积大且另有存档）；
+ * 超限时保留末尾（最近的）cap 条。
+ * @author ddj 2026年09月28号
+ * @param entries 待归一化的原始数组（非数组 → 空表）
+ * @param cap 单栈上限（默认 NAV_PERSIST_CAP）
+ * @returns 归一化条目数组
+ */
+export function cleanNavEntries(entries: unknown, cap = NAV_PERSIST_CAP): NavEntry[] {
+  if (!Array.isArray(entries)) return []
+  const out: NavEntry[] = []
+  for (const raw of entries) {
+    const entry = raw as NavEntry
+    if (!entry || typeof entry.path !== 'string' || !entry.path) continue
+    const item: NavEntry = { path: entry.path }
+    if (typeof entry.line === 'number' && Number.isInteger(entry.line) && entry.line > 0) item.line = entry.line
+    if (typeof entry.column === 'number' && Number.isInteger(entry.column) && entry.column > 0) item.column = entry.column
+    out.push(item)
+  }
+  return out.length > cap ? out.slice(out.length - cap) : out
+}
+
 /** scope → 导航历史实例（同工作区跨会话复用同一份历史）。 */
 const scopeHistories = new Map<string, NavHistory>()
 
@@ -106,6 +141,16 @@ export function createNavHistory(cap = NAV_HISTORY_CAP): NavHistory {
     peekForward(): NavEntry | null {
       return future.length ? future[future.length - 1] : null
     },
+    snapshot(): NavState {
+      return { past: past.map((entry) => ({ ...entry })), future: future.map((entry) => ({ ...entry })) }
+    },
+    restore(state: NavState | null | undefined): void {
+      if (!state) return
+      past.length = 0
+      future.length = 0
+      past.push(...cleanNavEntries(state.past, cap))
+      future.push(...cleanNavEntries(state.future, cap))
+    },
   }
 }
 

package/src/client/officialSidebar.ts

@@ -11,6 +11,7 @@
 
 import { log } from './log.js'
 import { setEnsureSideEditor } from './sidebarBridge.js'
+import { CACHE_KEY } from './paths.js'
 import { OFFICE_EXT, BLIND_EXT, suffixOf } from '../shared/nativeOpen.js'
 import { inNativePath } from './nativeOpenStore.js'
 
@@ -365,6 +366,61 @@ export function registerOfficialFileClaim(options: {
 let editorTabActive = false
 /** 正文挂载纪元（每次挂载自增；延迟判定期间有新挂载则放弃清除）。 */
 let mountEpoch = 0
+/** 作用域解析器（index.ts 装配时注入；未注入则不落盘，退回纯内存标记）。 */
+let tabScopeOf: (() => string) | null = null
+
+/**
+ * 注入编辑 Tab 状态的作用域解析器（index.ts 装配一次；键跟随会话/工作区切换）。
+ * @author ddj 2026年09月28号
+ * @param resolve 返回工作区作用域键（scopeStore.workspaceScopeOf 产物）
+ */
+export function setEditorTabScope(resolve: () => string): void {
+  tabScopeOf = resolve
+}
+
+/**
+ * 编辑 Tab 状态的作用域键（未注入/解析失败 → 空串，调用方跳过持久化）。
+ * @author ddj 2026年09月28号
+ * @returns localStorage 键
+ */
+function editorTabKey(): string {
+  if (!tabScopeOf) return ''
+  try {
+    const scope = tabScopeOf()
+    return scope ? CACHE_KEY.editorTab + scope : ''
+  } catch (error) {
+    return ''
+  }
+}
+
+/**
+ * 读回「上次退出时编辑 Tab 是否处于激活态」（供冷启动自动展开编辑 Tab）。
+ * @author ddj 2026年09月28号
+ * @returns 是否曾被激活（存储不可用/未注入 → false）
+ */
+export function readSavedTab(): boolean {
+  const key = editorTabKey()
+  if (!key) return false
+  try {
+    return localStorage.getItem(key) === '1'
+  } catch (error) {
+    return false
+  }
+}
+
+/**
+ * 持久化编辑 Tab 激活态（存储不可用静默；镜像层会把它写穿到 host 跨重启保留）。
+ * @author ddj 2026年09月28号
+ * @param active 是否激活
+ */
+export function saveTabActive(active: boolean): void {
+  const key = editorTabKey()
+  if (!key) return
+  try {
+    if (active) localStorage.setItem(key, '1')
+    else localStorage.removeItem(key)
+  } catch (error) { /* 存储不可用：仅内存标记生效 */ }
+}
 
 /**
  * 标记编辑 Tab 激活并推进挂载纪元（正文挂载时调用）。
@@ -377,11 +433,13 @@ export function markEditorMounted(): void {
 
 /**
  * 直接设置激活标记（正文卸载延迟判定用；测试 also 用作状态编排入口）。
- * @author ddj 2026年09月09号
+ * 同时写穿到 localStorage（镜像层负责跨重启保留），供下次冷启动恢复。
+ * @author ddj 2026年09月09号 / 2026年09月28号
  * @param active 是否激活
  */
 export function markEditorActive(active: boolean): void {
   editorTabActive = active
+  saveTabActive(active)
 }
 
 /**

package/src/client/paths.ts

@@ -30,6 +30,12 @@ export const CACHE_KEY = {
   rules: 'edrv.rules.v1.',
   /** SVN 变更面板 UI 状态（SvnPanel v1：未版本控制/忽略项显示开关，按作用域隔离）。 */
   svn: 'edrv.svn.v1.',
+  /** Markdown 预览态（EditorView v1：处于预览态的 Markdown 路径集合，按作用域隔离）。 */
+  mdPreview: 'edrv.md-preview.v1.',
+  /** 官方侧边栏「文件编辑」Tab 展开/激活态（officialSidebar v1：重启后自动回到编辑 Tab）。 */
+  editorTab: 'edrv.editor-tab.v1.',
+  /** 编辑器导航历史双栈（navStateCache v1：重启后前进/后退与当前位置仍在，按作用域隔离）。 */
+  navHistory: 'edrv.nav-history.v1.',
 } as const
 
 /** 按前缀拼作用域键（scopeStore 产出作用域；侧边栏/编辑器等需要布局段时自行拼接后传入）。 */

package/src/client/shortcutsOfficial.ts

@@ -308,6 +308,32 @@ export function bindCatalogChords(service: ShortcutsServiceLike, onChange: (chor
   return service.catalog.subscribe(sync)
 }
 
+/**
+ * 唤起官方快捷键弹窗（VSCodeMode 通用页的跳转入口用；插件不再自建录键界面）。
+ * 官方入口不可用（旧版 DSH / registry 缺失）或唤起失败时返回可读说明，
+ * 供设置页原样展示：不抛错、不阻断设置渲染。
+ * @author ddj 2026年09月28号
+ * @param service 官方 shortcuts 服务（可为 null：运行时探测未就绪）
+ * @returns 空串 = 已成功唤起；否则为给用户看的失败说明
+ */
+export function openOfficialShortcuts(service: ShortcutsServiceLike | null): string {
+  const manual = '可按 Ctrl+/ 或到 DSH 设置 → 通用 → 快捷键 打开'
+  if (!service || !service.registry || typeof service.registry.invoke !== 'function') {
+    return '官方快捷键弹窗入口不可用（当前 DSH 版本或外壳未提供）：' + manual
+  }
+  try {
+    service.registry.invoke('shortcuts.open', {
+      region: 'page',
+      modal: null,
+      target: typeof document === 'undefined' ? null : document.activeElement,
+    })
+    return ''
+  } catch (error) {
+    bridgeLog.warn('打开官方快捷键弹窗失败：' + String(error))
+    return '打开官方快捷键弹窗失败：' + String(error) + '；' + manual
+  }
+}
+
 //#region 旧设置迁移
 
 /** 旧设置 scope 最小形状（compat settingsBridge 绑定产物的最小面，结构与 SettingsScopeLike 兼容）。 */

package/src/client/state/mdPreviewCache.ts

@@ -0,0 +1,74 @@
+/**
+ * dsh-vscode-mode client — Markdown 预览态缓存（localStorage，按工作区作用域）。
+ * 语义对齐编辑器布局记忆：切换页签/刷新/重启后，处于预览态的 Markdown 仍以预览打开。
+ * 键 = CACHE_KEY.mdPreview + scope；值为路径数组。解析/归一化纯函数可单测，IO 收在 load/save 两端。
+ * 作者 ddj 2026-09-28
+ */
+import { CACHE_KEY } from '../paths.js'
+
+/** 单作用域记忆的预览态路径上限（超出按顺序丢弃最早，防 localStorage 膨胀）。 */
+export const MD_PREVIEW_CAP = 50
+
+/**
+ * 归一化预览态路径表：丢弃非字符串/空串、去重（保留首次出现顺序），超限截断。
+ * @author ddj 2026年09月28号
+ * @param value 待归一化的解析产物（任意输入，非数组 → 空表）
+ * @returns 路径数组
+ */
+export function normalizeMdPreview(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  const out: string[] = []
+  for (const item of value) {
+    if (typeof item !== 'string' || !item) continue
+    if (out.includes(item)) continue
+    out.push(item)
+    if (out.length >= MD_PREVIEW_CAP) break
+  }
+  return out
+}
+
+/**
+ * 解析存档文本（空/损坏/非数组 → 空表）。
+ * @author ddj 2026年09月28号
+ * @param text localStorage 原文
+ * @returns 路径数组
+ */
+export function parseMdPreview(text: string | null): string[] {
+  if (!text) return []
+  try {
+    return normalizeMdPreview(JSON.parse(text))
+  } catch (error) {
+    return []
+  }
+}
+
+/**
+ * 读某作用域处于预览态的 Markdown 路径集合。
+ * @author ddj 2026年09月28号
+ * @param scope 作用域键（scopeStore.workspaceScopeOf 产物）
+ * @returns 预览态路径集合（存储不可用/无存档 → 空集）
+ */
+export function mdPreviewLoad(scope: string): Set<string> {
+  try {
+    return new Set(parseMdPreview(localStorage.getItem(CACHE_KEY.mdPreview + scope)))
+  } catch (error) {
+    return new Set()
+  }
+}
+
+/**
+ * 写某作用域的预览态集合（空集删除键，避免残留空数组）。
+ * @author ddj 2026年09月28号
+ * @param scope 作用域键
+ * @param paths 预览态路径集合
+ */
+export function mdPreviewSave(scope: string, paths: Set<string>): void {
+  try {
+    const list = normalizeMdPreview(Array.from(paths))
+    if (!list.length) {
+      localStorage.removeItem(CACHE_KEY.mdPreview + scope)
+      return
+    }
+    localStorage.setItem(CACHE_KEY.mdPreview + scope, JSON.stringify(list))
+  } catch (error) { /* 存储不可用：预览态仅存活本次会话 */ }
+}

package/src/client/state/navStateCache.ts

@@ -0,0 +1,83 @@
+/**
+ * dsh-vscode-mode client — 编辑器导航历史存档（localStorage，按工作区作用域）。
+ * 语义：刷新/重启后「后退/前进」双栈与当前位置仍在（对齐 VSCode navigation history 的体感，
+ * 只是延长到跨会话/跨 origin）。条目不含 viewState——它体积大且已由 viewStateCache 按路径存档。
+ * 键 = CACHE_KEY.navHistory + scope；序列化/解析为纯函数，IO 收在 load/save 两端。
+ * 作者 ddj 2026-09-28
+ */
+import { CACHE_KEY } from '../paths.js'
+import { cleanNavEntries, NAV_PERSIST_CAP, type NavState } from '../navHistory.js'
+
+/** 存档格式版本（结构不兼容时递增，旧档自动作废）。 */
+export const NAV_STATE_VERSION = 1
+
+/**
+ * 序列化双栈（空栈 → 空串，调用方据此删键）。
+ * @author ddj 2026年09月28号
+ * @param state 双栈快照（null/undefined → 空串）
+ * @returns 存档文本
+ */
+export function serializeNavState(state: NavState | null | undefined): string {
+  if (!state) return ''
+  const past = cleanNavEntries(state.past, NAV_PERSIST_CAP)
+  const future = cleanNavEntries(state.future, NAV_PERSIST_CAP)
+  if (!past.length && !future.length) return ''
+  return JSON.stringify({ v: NAV_STATE_VERSION, past, future })
+}
+
+/**
+ * 解析存档文本（空/损坏/版本不符/无可恢复条目 → null）。
+ * @author ddj 2026年09月28号
+ * @param text localStorage 原文
+ * @returns 双栈快照
+ */
+export function parseNavState(text: string | null): NavState | null {
+  if (!text) return null
+  try {
+    const value = JSON.parse(text) as { v?: unknown; past?: unknown; future?: unknown }
+    if (!value || typeof value !== 'object' || value.v !== NAV_STATE_VERSION) return null
+    const past = cleanNavEntries(value.past, NAV_PERSIST_CAP)
+    const future = cleanNavEntries(value.future, NAV_PERSIST_CAP)
+    if (!past.length && !future.length) return null
+    return { past, future }
+  } catch (error) {
+    return null
+  }
+}
+
+/** scope → 最近写入的原文（去重写：光标移动触发的快照大多与上次相同）。 */
+const lastWritten = new Map<string, string>()
+
+/**
+ * 读某作用域的导航历史存档。
+ * @author ddj 2026年09月28号
+ * @param scope 作用域键（scopeStore.workspaceScopeOf 产物）
+ * @returns 双栈快照（无存档/存储不可用 → null）
+ */
+export function navStateLoad(scope: string): NavState | null {
+  try {
+    return parseNavState(localStorage.getItem(CACHE_KEY.navHistory + scope))
+  } catch (error) {
+    return null
+  }
+}
+
+/**
+ * 写某作用域的导航历史存档（空存档删键；原文未变跳过写入）。
+ * @author ddj 2026年09月28号
+ * @param scope 作用域键
+ * @param state 双栈快照（null → 删除存档）
+ */
+export function navStateSave(scope: string, state: NavState | null | undefined): void {
+  try {
+    const text = serializeNavState(state)
+    if (lastWritten.get(scope) === text) return
+    lastWritten.set(scope, text)
+    const key = CACHE_KEY.navHistory + scope
+    if (!text) {
+      localStorage.removeItem(key)
+      return
+    }
+    localStorage.setItem(key, text)
+  } catch (error) { /* 存储不可用：导航历史仅存活本次会话 */ }
+}