dsh-vscode-mode 0.1.29 → 0.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.1.29",
+  "version": "0.1.32",
   "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 dsh-better-sidebar 侧边栏与对话同屏）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚），状态持久化到工作区旁车",
   "keywords": [
     "dsh",

package/src/capture.ts

@@ -10,6 +10,7 @@ import { loadBucket, saveBucket } from './store.js'
 import { fileMaxBatch, prune } from './model.js'
 import type { Registry } from './registry.js'
 import { cwdOf } from './registry.js'
+import { invalidateIndex } from './treeIndex.js'
 
 /** 校验并提取工具 result meta 中的文件 hunk。 */
 function validHunks(raw: unknown): Hunk[] {
@@ -97,6 +98,8 @@ export async function captureToolResult(ctx: Ctx, registry: Registry, exec: any,
     // 旧实现按文件 batch 自动归档 prior，会导致界面看起来每个文件只剩一条差异。
     prune(bucket)
     await saveBucket(ctx, cwd, bucket, session)
+    // agent 写盘后目录树可能变化（新建/删除文件/目录）：父目录+祖先进失效，后台自愈。
+    invalidateIndex(ctx, cwd, path)
   } catch (error) {
     console.error('edrv capture failed', error)
   }

package/src/client/index.ts

@@ -17,6 +17,7 @@ import React from 'react'
 import './styles/editor.css'
 import { EditorView } from './ui/EditorView.js'
 import { DiffBadge } from './ui/DiffBadge.js'
+import { PerfSizeBadge } from './ui/PerfSizeBadge.js'
 import { ConversationDiffDock } from './ui/ConversationDiffDock.js'
 import { McpSettings } from './ui/McpSettings.js'
 import { rpc } from './rpc.js'
@@ -230,6 +231,10 @@ export function apply(ctx: any): void {
   registerSlotSafely(ctx, { name: 'conversation.session.header.utilities', id: 'edrv-diff-badge', order: 90, label: '差异' },
     (props: unknown) => React.createElement(DiffBadge, Object.assign({}, props)))
 
+  // header 会话体积指示器：当前会话持久化体积，超阈值提示新开会话（性能优化）
+  registerSlotSafely(ctx, { name: 'conversation.session.header.utilities', id: 'edrv-perf-size', order: 89, label: '会话体积' },
+    (props: unknown) => React.createElement(PerfSizeBadge, Object.assign({}, props, { sessions })))
+
   // 设置页中的 VSCodeMode 专属页签，MCP 管理作为该页签的内部子 Tab。
   registerSlotSafely(ctx, {
     name: 'settings.section',

package/src/client/monaco/diffRender.ts

@@ -12,6 +12,8 @@
 export function createDiffRenderer(log) {
   let viewZoneIds = []
   let decorations = []
+  /** 上次已渲染的差异指纹（callId:idx@start-end:oldLen/newLen 串）：内容未变时跳过重建。 */
+  let lastKey = null
 
   /**
    * 渲染当前 pending 差异：绿底 decoration + 删除块 view zones + '-' 号 overlay（滚动同步）。
@@ -26,6 +28,11 @@ export function createDiffRenderer(log) {
     if (!pendingRegions.length && viewZoneIds.length === 0 && decorations.length === 0) return
     const renderT0 = Date.now()
     const callIdAttr = (callId, idx) => String(callId) + ':' + String(idx)
+    // 指纹相同 = 内容未变（轮询/引用空转/重复点击触发的重渲染）：残留 DOM 已在位，
+    // 直接跳过整轮重建（view zones 拆建 / overlay DOM / 50ms 校正），消除同区域重复渲染成本。
+    const key = pendingRegions.map((r) => callIdAttr(r.callId, r.idx) + '@' + (r.start ?? '?') + '-' + (r.end ?? '?') + ':' + (r.oldLines ? r.oldLines.length : 0) + '/' + (r.newLines ? r.newLines.length : 0)).join('|')
+    if (key === lastKey) return
+    lastKey = key
     log(sessionId, '[diff-render] begin regs=' + pendingRegions.length + ' ' + pendingRegions.map((r) => callIdAttr(r.callId, r.idx) + '@' + (r.start ?? '?') + '-' + (r.end ?? '?') + '(-' + (r.oldLines ? r.oldLines.length : 0) + '/+' + (r.newLines ? r.newLines.length : 0) + ')').join('|'))
 
     const decos = []

package/src/client/paths.ts

@@ -0,0 +1,36 @@
+/**
+ * dsh-vscode-mode client — 浏览器端缓存键/路径统一出口（PathConst）。
+ * 统一 localStorage 键前缀（各缓存模块/编辑区/搜索面板共用），避免内联散落；
+ * 键带 schema 版本号，未来版本递增时经 sweepLegacyKeys 自动清旧。
+ * 浏览器不涉 ~/.dsh 文件系统，这里只管键名 + shared 路由常量。
+ * 作者 ddj 2026-09-01
+ */
+
+/** localStorage 键前缀表（按功能隔离；均按会话拼接）。 */
+export const CACHE_KEY = {
+  /** 展开状态（explorerCache v1，当前使用）。 */
+  expanded: 'edrv.cache.explorer.v1.',
+  /** 目录条目 SWR 缓存（explorerEntriesCache v2，当前使用）。 */
+  entries: 'edrv.cache.entries.v2.',
+  /** 编辑区视图状态（viewStateCache v1）。 */
+  viewstate: 'edrv.cache.viewstate.v1.',
+  /** 编辑器页签/活动文件（EditorView v2）。 */
+  editor: 'edrv.editor.v2.',
+  /** 侧边栏状态（EditorView；按布局 side/central 追加段）。 */
+  sidebar: 'edrv.sidebar.',
+  /** 搜索面板条件（SearchPanel v1）。 */
+  search: 'edrv.search.v1.',
+  /** 侧边栏提示已关闭标记（全局，无会话）。 */
+  sideHint: 'edrv.side-hint-dismissed',
+} as const
+
+/** 按前缀拼会话键（侧边栏/编辑器等需要布局段时自行拼接后传入）。 */
+export function cacheKey(prefix: string, sessionId: string): string {
+  return prefix + sessionId
+}
+
+/** 旧版本键清理入口：未来前缀版本递增时在此登记旧前缀并清空（当前无实际旧键）。 */
+export function sweepLegacyKeys(): void {
+  // 例：entries v2 取代 v1 时 → localStorage.removeItem('edrv.cache.entries.v1.' + sid)
+  // 当前各功能均为现役版本，无待清旧键。
+}

package/src/client/rpc.ts

@@ -6,6 +6,16 @@
 import { RPC_PATH } from '../shared/rpc.js'
 import type { RpcMethod, RpcRequestMap, RpcResult } from '../shared/rpc.js'
 
+/**
+ * 诊断日志开关（默认关）：diff 渲染热路径每条日志 = 1 次 RPC 往返 +
+ * host 端 debug 文件全量读改写（上限 512KB），高频渲染下开销可观。
+ * 排查问题时在浏览器控制台执行 localStorage.setItem('edrv.debug','1') 后刷新开启。
+ * @author ddj 2026年08月26号
+ */
+const DEBUG = (() => {
+  try { return localStorage.getItem('edrv.debug') === '1' } catch (e) { return false }
+})()
+
 /** 同源 RPC 调用（host /edrv/rpc 精确路由）。 */
 export function rpc<M extends RpcMethod>(method: M, args: RpcRequestMap[M]): Promise<RpcResult<M>> {
   return fetch(RPC_PATH, {
@@ -16,12 +26,13 @@ export function rpc<M extends RpcMethod>(method: M, args: RpcRequestMap[M]): Pro
 }
 
 /**
- * 诊断日志：统一走 host edrv.debug 落盘，避免 console 刷屏。
- * @author ddj 2026年08月20号
+ * 诊断日志：开关关闭时直接返回（零 RPC 零落盘）；开启时走 host edrv.debug 落盘。
+ * @author ddj 2026年08月26号
  * @param sessionId 会话 id
  * @param text 日志文本
  */
 export function dbg(sessionId: string | undefined, text: string): void {
+  if (!DEBUG) return
   try {
     rpc('edrv.debug', { sessionId, text }).catch(() => {})
   } catch (e) { /* 日志失败忽略 */ }

package/src/client/sidebar/panels/FileExplorer.ts

@@ -1,11 +1,12 @@
 // @ts-nocheck
 /**
- * dsh-vscode-mode client — 侧边栏「文件管理」面板（懒加载目录树）。
- * 点目录展开/收起（首次经 edrv.listDir 拉取并缓存），点文件经 ctx.openFile 打开；
- * 差异角标取 pendingByPath，活动文件高亮；edrv:refresh 事件与手动刷新重载树。
- * 右键行/空白弹出菜单：项来自 ctx.fileMenuItems 注册表（可拓展），
- * 内置「在文件浏览器中打开」经 edrv.revealInExplorer 定位/打开。
- * 作者 ddj 2026-08-26 / 2026-08-27
+ * dsh-vscode-mode client — 侧边栏「文件管理」面板（懒加载目录树 + SWR 缓存）。
+ * 展开目录立即渲染（dirs 内存态 → 本地条目缓存兜底），后台刷新（edrv.listDir 走
+ * host 树索引，命中近乎零成本）；挂载/切会话从缓存即时恢复展开树；⟳/edrv:refresh
+ * 保留旧条目强制后台重列（force）；每次用户发起加载后预取 ≤4 个子目录（排除重型
+ * 目录、缓存新鲜跳过、不级联）；10s 轻量跟随已展开目录（命中索引，RPC 近零成本）。
+ * 差异角标/右键菜单/展开状态持久化行为不变。
+ * 作者 ddj 2026-08-26 / 2026-08-27 / 2026-08-31
  */
 import React from 'react'
 import { rpc } from '../../rpc.js'
@@ -13,13 +14,17 @@ import { ContextMenu } from '../../ui/ContextMenu.js'
 import { rowMenuPosition } from '../../ui/menuPosition.js'
 import { buildTreeMenu } from '../contextMenu.js'
 import { explorerLoad, explorerSave } from '../../state/explorerCache.js'
+import { entriesCacheGet, entriesCacheIsFresh, entriesCachePut } from '../../state/explorerEntriesCache.js'
 import type { SidebarCtx } from '../types.js'
 
 const DIR_CAP = 4000
 const SAVE_DEBOUNCE_MS = 300
+const FOLLOW_INTERVAL_MS = 10_000
+const PREFETCH_MAX = 4
+const PREFETCH_EXCLUDED = new Set(['node_modules', '.git', '.hg', '.svn', '.pnpm', '.pnpm-store'])
 
 /**
- * 目录树面板主体。
+ * 目录树面板主体（SWR：有缓存先渲染，无缓存才显示加载态；加载总在后台）。
  * @param props.ctx 面板共享上下文（sessionId/openFile/activePath/pendingByPath/fileMenuItems/notify）
  */
 export function FileExplorer(props) {
@@ -29,34 +34,76 @@ export function FileExplorer(props) {
   const activePath = ctx?.activePath ?? null
   const pendingByPath = ctx?.pendingByPath ?? {}
   const [root, setRoot] = React.useState(null)
-  const [dirs, setDirs] = React.useState({})
+  const [dirs, setDirs] = React.useState({}) // rel → 最新条目（本会话内存态）
   const [expanded, setExpanded] = React.useState({})
   const [loading, setLoading] = React.useState({})
-  const [error, setError] = React.useState(null)
+  const [errors, setErrors] = React.useState({}) // rel → 错误文案（仅无任何数据时展示）
   const [menu, setMenu] = React.useState(null) // 右键菜单 { x, y, target }
+  // 各状态 ref 镜像：定时器/监听用最新闭包
   const tokensRef = React.useRef({})
-  // expanded 的 ref 镜像：edrv:refresh 监听用首次渲染闭包，但需读到最新展开态
   const expandedRef = React.useRef({})
   expandedRef.current = expanded
-  // 展开状态防抖写回计时器
+  const loadingRef = React.useRef({})
+  loadingRef.current = loading
+  const dirsRef = React.useRef({})
+  dirsRef.current = dirs
   const saveTimerRef = React.useRef(null)
+  const loadDirRef = React.useRef(null)
+  const refreshRef = React.useRef(null)
 
-  const loadDir = (rel) => {
+  /** 渲染取数：内存态 → 本地条目缓存 → null（显示加载态）。 */
+  const entriesOf = (rel) => dirsRef.current[rel] ?? entriesCacheGet(sessionId, rel) ?? null
+
+  /** 预取子目录：≤4 个、排除重型目录、缓存新鲜跳过、已加载跳过、不级联。 */
+  const prefetchDirs = (rel, entries) => {
+    const want = []
+    for (const e of entries) {
+      if (e.type !== 'directory') continue
+      if (PREFETCH_EXCLUDED.has(e.name)) continue
+      if (entriesCacheIsFresh(sessionId, e.path)) continue
+      if (dirsRef.current[e.path] !== undefined) continue
+      want.push(e.path)
+      if (want.length >= PREFETCH_MAX) break
+    }
+    for (const sub of want) void loadDir(sub, {})
+  }
+
+  /**
+   * 后台加载目录：token 守卫防乱序；force 跳过索引命中强制实列；
+   * 非 force 且已在途时跳过（避免轮询打断用户展开的响应）。
+   */
+  const loadDir = (rel, opts) => {
+    const force = opts?.force === true
+    const doPrefetch = opts?.prefetch === true
+    if (!force && loadingRef.current[rel]) return
     const token = (tokensRef.current[rel] || 0) + 1
     tokensRef.current[rel] = token
     setLoading((prev) => Object.assign({}, prev, { [rel]: true }))
-    setError(null)
-    rpc('edrv.listDir', { sessionId, path: rel }).then((res) => {
+    setErrors((prev) => {
+      const next = Object.assign({}, prev)
+      delete next[rel]
+      return next
+    })
+    const args = { sessionId, path: rel }
+    if (force) args.force = true
+    rpc('edrv.listDir', args).then((res) => {
       if (tokensRef.current[rel] !== token) return
       if (res && res.ok && Array.isArray(res.entries)) {
         setDirs((prev) => Object.assign({}, prev, { [rel]: res.entries }))
-        if (res.root && !root) setRoot(res.root)
+        if (res.root) setRoot((prev) => prev || res.root)
+        entriesCachePut(sessionId, rel, res.entries)
+        if (doPrefetch) prefetchDirs(rel, res.entries)
       } else {
-        setError(res?.error ? String(res.error) : '读取目录失败')
+        // 有可渲染数据时静默（旧数据可能过期但可用）；全无数据才报错
+        if (!entriesOf(rel)) {
+          setErrors((prev) => Object.assign({}, prev, { [rel]: res?.error ? String(res.error) : '读取目录失败' }))
+        }
       }
     }).catch((e) => {
       if (tokensRef.current[rel] !== token) return
-      setError('读取目录异常:' + String(e))
+      if (!entriesOf(rel)) {
+        setErrors((prev) => Object.assign({}, prev, { [rel]: '读取目录异常:' + String(e) }))
+      }
     }).finally(() => {
       if (tokensRef.current[rel] !== token) return
       setLoading((prev) => {
@@ -66,43 +113,45 @@ export function FileExplorer(props) {
       })
     })
   }
+  loadDirRef.current = loadDir
 
   const toggle = (rel) => {
     if (expanded[rel] === true) {
       setExpanded((prev) => Object.assign({}, prev, { [rel]: false }))
       return
     }
-    if (!dirs[rel]) void loadDir(rel)
     setExpanded((prev) => Object.assign({}, prev, { [rel]: true }))
+    void loadDir(rel, { prefetch: true })
   }
 
   const refresh = () => {
     const keep = Object.keys(expandedRef.current).filter((k) => expandedRef.current[k] === true)
     tokensRef.current = {}
     setMenu(null)
-    setDirs({})
+    setErrors({})
+    // SWR：保留旧条目不清空，后台强制重列（force 跳过索引）
     setLoading({})
-    setError(null)
     if (keep.length) {
       const next = {}
       for (const rel of keep) next[rel] = true
       setExpanded(next)
-      for (const rel of keep) void loadDir(rel)
+      for (const rel of keep) void loadDir(rel, { force: true, prefetch: true })
     } else {
       setExpanded({})
     }
-    void loadDir('')
+    void loadDir('', { force: true, prefetch: true })
   }
+  refreshRef.current = refresh
 
   React.useEffect(() => {
     tokensRef.current = {}
     setDirs({})
     setExpanded({})
     setLoading({})
-    setError(null)
+    setErrors({})
     setMenu(null)
     setRoot(null)
-    // 恢复上次展开状态（对齐 VSCode：持久化展开路径，目录条目实时拉取）
+    // 恢复上次展开状态（对齐 VSCode：持久化展开路径，条目缓存即时渲染、后台刷新）
     const cached = sessionId ? explorerLoad(sessionId) : null
     const restored = cached?.expanded ?? []
     if (cached?.root) setRoot(cached.root)
@@ -111,9 +160,9 @@ export function FileExplorer(props) {
       for (const rel of restored) next[rel] = true
       setExpanded(next)
     }
-    void loadDir('')
+    void loadDir('', { prefetch: true })
     for (const rel of restored) {
-      if (rel) void loadDir(rel)
+      if (rel) void loadDir(rel, { prefetch: true })
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [sessionId])
@@ -132,13 +181,26 @@ export function FileExplorer(props) {
     }
   }, [expanded, root, sessionId])
 
+  // edrv:refresh（差异决策/回滚后）：保留旧条目，强制后台重列
   React.useEffect(() => {
-    const onRefresh = () => refresh()
+    const onRefresh = () => refreshRef.current?.()
     window.addEventListener('edrv:refresh', onRefresh)
     return () => window.removeEventListener('edrv:refresh', onRefresh)
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
+  // 10s 轻量跟随：已展开目录后台刷新（命中 host 索引，近零成本），树跟随 agent 写入
+  React.useEffect(() => {
+    if (!sessionId) return
+    const timer = setInterval(() => {
+      const open = Object.keys(expandedRef.current).filter((k) => expandedRef.current[k] === true)
+      if (!open.length) return
+      for (const rel of open) loadDirRef.current?.(rel, {})
+    }, FOLLOW_INTERVAL_MS)
+    return () => clearInterval(timer)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sessionId])
+
   const rootName = root ? String(root).split(/[\\/]/).pop() || root : ''
 
   const rowEl = (e, depth, isDir, isOpen) => {
@@ -172,7 +234,7 @@ export function FileExplorer(props) {
   }
 
   const rowsOf = (rel, depth) => {
-    const entries = dirs[rel]
+    const entries = entriesOf(rel)
     if (!entries) {
       return [React.createElement('div', { key: rel + ':loading', className: 'edrv-tree-loading', style: { paddingLeft: 6 + depth * 14 } },
         loading[rel] ? '加载中…' : '无法加载')]
@@ -212,6 +274,9 @@ export function FileExplorer(props) {
       }))
     : []
 
+  const errorList = Object.entries(errors)
+  const errorText = errorList.length ? errorList[0][1] : null
+
   return React.createElement('div', { className: 'edrv-side-panel', onContextMenu: onPanelContext },
     React.createElement('div', { className: 'edrv-side-head' },
       React.createElement('span', { className: 'edrv-side-title' }, '资源管理器'),
@@ -219,9 +284,9 @@ export function FileExplorer(props) {
       React.createElement('span', { style: { flex: 1 } }),
       React.createElement('button', { className: 'edrv-side-btn', title: '刷新目录树', onClick: refresh }, '⟳')),
     React.createElement('div', { className: 'edrv-tree' },
-      (error
+      (errorText
         ? React.createElement('div', { className: 'edrv-tree-error' },
-            React.createElement('span', null, String(error)),
+            React.createElement('span', null, String(errorText)),
             React.createElement('button', { className: 'edrv-side-btn', onClick: () => refresh() }, '重试'))
         : null),
       rowsOf('', 0)),

package/src/client/sidebar/panels/SearchPanel.ts

@@ -10,6 +10,7 @@
 import React from 'react'
 import { rpc } from '../../rpc.js'
 import type { SidebarCtx } from '../types.js'
+import { CACHE_KEY } from '../../paths.js'
 
 const DEBOUNCE_MS = 250
 const INCLUDE_PLACEHOLDER = '例如 *.ts, src/**/include'
@@ -56,6 +57,7 @@ export function SearchPanel(props) {
   const [sectionOpen, setSectionOpen] = React.useState(false)
   const [status, setStatus] = React.useState('idle') // idle | searching | done | error
   const [error, setError] = React.useState('')
+  const [warning, setWarning] = React.useState('') // rg 遍历错误时的部分结果提示（结果照常展示）
   const [matches, setMatches] = React.useState(null)
   const [truncated, setTruncated] = React.useState(false)
   const [collapsed, setCollapsed] = React.useState({})
@@ -78,7 +80,7 @@ export function SearchPanel(props) {
   React.useEffect(() => {
     if (!sessionId) return
     try {
-      const saved = JSON.parse(localStorage.getItem('edrv.search.v1.' + String(sessionId)) || 'null')
+      const saved = JSON.parse(localStorage.getItem(CACHE_KEY.search + String(sessionId)) || 'null')
       if (saved && typeof saved === 'object') {
         if (typeof saved.query === 'string') setQuery(saved.query)
         if (typeof saved.matchCase === 'boolean') setMatchCase(saved.matchCase)
@@ -97,7 +99,7 @@ export function SearchPanel(props) {
   React.useEffect(() => {
     if (!sessionId) return
     try {
-      localStorage.setItem('edrv.search.v1.' + String(sessionId), JSON.stringify({
+      localStorage.setItem(CACHE_KEY.search + String(sessionId), JSON.stringify({
         query, matchCase, wholeWord, regex, includeText, excludeText, onlyActive, excludeOn, sectionOpen,
       }))
     } catch (e) { /* 忽略 */ }
@@ -114,6 +116,7 @@ export function SearchPanel(props) {
     const req = requestRef.current
     setStatus('searching')
     setError('')
+    setWarning('')
     rpc('edrv.searchContent', {
       sessionId, query: clean,
       matchCase: req.matchCase, wholeWord: req.wholeWord, regex: req.regex,
@@ -123,6 +126,7 @@ export function SearchPanel(props) {
       if (res && res.ok) {
         setMatches(Array.isArray(res.matches) ? res.matches : [])
         setTruncated(res.truncated === true)
+        setWarning(res?.warning ? String(res.warning) : '')
         setStatus('done')
       } else {
         setError(res?.error ? String(res.error) : '搜索失败')
@@ -249,6 +253,10 @@ export function SearchPanel(props) {
           : '无匹配结果')
     : null
 
+  const warnBanner = warning
+    ? React.createElement('div', { className: 'edrv-search-warn', title: warning }, warning)
+    : null
+
   const body = (() => {
     if (status === 'searching') return React.createElement('div', { className: 'edrv-search-empty' }, '搜索中…')
     if (status === 'error') return React.createElement('div', { className: 'edrv-search-error' }, error)
@@ -290,5 +298,6 @@ export function SearchPanel(props) {
     optsBar,
     filterRows,
     summary,
+    warnBanner,
     body)
 }

package/src/client/state/explorerCache.ts

@@ -1,11 +1,13 @@
 /**
  * dsh-vscode-mode client — 资源管理栏展开状态持久化（纯函数，可单测）。
  * 对齐 VSCode：只持久化展开路径集合，不缓存目录条目数据（条目实时 listDir）。
+ * 键前缀统一走 paths.ts PathConst（CACHE_KEY.expanded）。
  * 作者 ddj 2026-08-28
  */
+import { CACHE_KEY } from '../paths.js'
 
 /** localStorage 键前缀（按会话隔离）。 */
-const KEY_PREFIX = 'edrv.cache.explorer.v1.'
+const KEY_PREFIX = CACHE_KEY.expanded
 
 /** 展开路径容量上限：超出丢弃最旧（按写入顺序近似 LRU）。 */
 export const EXPANDED_CAP = 500

package/src/client/state/explorerEntriesCache.ts

@@ -0,0 +1,172 @@
+/**
+ * dsh-vscode-mode client — 资源管理栏目录条目缓存（SWR：旧数据即时渲染 + 后台刷新）。
+ * 与 explorerCache（展开状态持久化）互补：本文件只缓存目录条目数据，键按会话隔离。
+ * 纯函数（序列化/解析/裁剪）导出可单测；内存镜像 Map 同步读避免每次渲染 parse
+ * localStorage，落盘 300ms 防抖；配额满/隐私模式 try/catch 降级纯内存。
+ * 作者 ddj 2026-08-31
+ */
+import type { TreeEntry } from '../../shared/rpc.js'
+import { CACHE_KEY } from '../paths.js'
+
+// --region 常量
+const KEY_PREFIX = CACHE_KEY.entries
+/** 缓存目录上限（超出按 ts 逐出最旧，保活热门目录）。 */
+export const CACHE_MAX_DIRS = 300
+/** 单目录条目缓存上限（即时渲染用，刷新补齐全量）。 */
+export const CACHE_DIR_ENTRIES = 500
+/** 新鲜度窗口：预取去重用（展示不受限，永远可用缓存渲染）。 */
+export const CACHE_FRESH_MS = 30_000
+/** 落盘防抖。 */
+export const CACHE_SAVE_DEBOUNCE_MS = 300
+// --endregion
+
+/** 单目录缓存条目。 */
+export interface CachedDir {
+  ts: number
+  entries: TreeEntry[]
+}
+
+/** 缓存数据（v2：与 v1 展开状态缓存分离）。 */
+export interface EntriesCacheData {
+  v: 2
+  root: string | null
+  dirs: Record<string, CachedDir>
+}
+
+/** 裁剪到上限（目录按 ts 逐出最旧；单目录条目截断）。 */
+export function entriesTrim(data: EntriesCacheData, maxDirs = CACHE_MAX_DIRS, maxEntries = CACHE_DIR_ENTRIES): EntriesCacheData {
+  const dirs: Record<string, CachedDir> = {}
+  const sorted = Object.entries(data.dirs).sort((a, b) => b[1].ts - a[1].ts)
+  for (const [rel, dir] of sorted) {
+    if (Object.keys(dirs).length >= maxDirs) break
+    dirs[rel] = { ts: dir.ts, entries: dir.entries.length > maxEntries ? dir.entries.slice(0, maxEntries) : dir.entries }
+  }
+  return { v: 2, root: data.root, dirs }
+}
+
+/** 序列化缓存数据。 */
+export function entriesSerialize(data: EntriesCacheData): string {
+  return JSON.stringify(data)
+}
+
+/** 解析缓存文本；损坏/格式不符 → null。 */
+export function entriesParse(text: string | null): EntriesCacheData | null {
+  if (!text) return null
+  try {
+    const raw = JSON.parse(text) as { v?: unknown; root?: unknown; dirs?: unknown }
+    if (!raw || raw.v !== 2 || !raw.dirs || typeof raw.dirs !== 'object') return null
+    const dirs: Record<string, CachedDir> = {}
+    for (const [rel, d] of Object.entries(raw.dirs)) {
+      if (!d || typeof d !== 'object') continue
+      const dir = d as { ts?: unknown; entries?: unknown }
+      if (!Array.isArray(dir.entries)) continue
+      const entries: TreeEntry[] = []
+      for (const e of dir.entries) {
+        if (!e || typeof e !== 'object') continue
+        const item = e as { name?: unknown; path?: unknown; type?: unknown }
+        if (typeof item.name !== 'string' || typeof item.path !== 'string') continue
+        const type = item.type === 'directory' ? 'directory' : item.type === 'file' ? 'file' : 'other'
+        entries.push({ name: item.name, path: item.path, type })
+      }
+      if (!entries.length) continue
+      dirs[rel] = { ts: typeof dir.ts === 'number' ? dir.ts : 0, entries }
+    }
+    return { v: 2, root: typeof raw.root === 'string' ? raw.root : null, dirs }
+  } catch (error) {
+    return null
+  }
+}
+
+// --region 内存镜像 + 防抖落盘
+/** sessionId → 缓存镜像（同步读，避免每次渲染 parse）。 */
+const mirrors = new Map<string, EntriesCacheData>()
+/** sessionId → 落盘防抖计时器。 */
+const saveTimers = new Map<string, ReturnType<typeof setTimeout>>()
+/** 单调时钟：连续 put 的 ts 严格递增（同毫秒不并列，逐出顺序可预期）。 */
+let clock = 0
+
+/** 取下一时间戳（不小于真实时间且严格递增）。 */
+function nextTs(): number {
+  clock = Math.max(Date.now(), clock + 1)
+  return clock
+}
+
+/** localStorage 读取（不可用 → null）。 */
+function readRaw(sessionId: string): string | null {
+  try {
+    return window.localStorage.getItem(KEY_PREFIX + sessionId)
+  } catch (error) {
+    return null
+  }
+}
+
+/** localStorage 写入（配额/隐私模式失败静默）。 */
+function writeRaw(sessionId: string, text: string): void {
+  try {
+    window.localStorage.setItem(KEY_PREFIX + sessionId, text)
+  } catch (error) { /* 配额满/隐私模式忽略 */ }
+}
+
+/** 取（或建）会话缓存镜像。 */
+function mirrorOf(sessionId: string): EntriesCacheData {
+  const existing = mirrors.get(sessionId)
+  if (existing) return existing
+  const data = entriesParse(readRaw(sessionId)) ?? { v: 2, root: null, dirs: {} }
+  mirrors.set(sessionId, data)
+  return data
+}
+
+/** 调度防抖落盘（重置已有计时器）。 */
+function scheduleSave(sessionId: string): void {
+  const prev = saveTimers.get(sessionId)
+  if (prev) clearTimeout(prev)
+  saveTimers.set(sessionId, setTimeout(() => {
+    saveTimers.delete(sessionId)
+    const data = mirrors.get(sessionId)
+    if (data) writeRaw(sessionId, entriesSerialize(entriesTrim(data)))
+  }, CACHE_SAVE_DEBOUNCE_MS))
+}
+// --endregion
+
+/**
+ * 读某目录缓存条目（无 → null；展示不受新鲜度限制）。
+ * @author ddj 2026年08月31号
+ * @param sessionId 会话 id
+ * @param rel 目录相对路径（'' = 根）
+ * @returns 缓存条目或 null
+ */
+export function entriesCacheGet(sessionId: string | undefined, rel: string): TreeEntry[] | null {
+  if (!sessionId) return null
+  const dir = mirrorOf(sessionId).dirs[rel]
+  if (!dir || !dir.entries.length) return null
+  return dir.entries
+}
+
+/**
+ * 某目录缓存是否新鲜（预取去重用）。
+ * @author ddj 2026年08月31号
+ * @param sessionId 会话 id
+ * @param rel 目录相对路径
+ * @returns 新鲜返回 true
+ */
+export function entriesCacheIsFresh(sessionId: string | undefined, rel: string): boolean {
+  if (!sessionId) return false
+  const dir = mirrorOf(sessionId).dirs[rel]
+  return Boolean(dir && Date.now() - dir.ts < CACHE_FRESH_MS)
+}
+
+/**
+ * 写入某目录缓存条目（内存镜像 + 防抖落盘；单目录条目截断）。
+ * @author ddj 2026年08月31号
+ * @param sessionId 会话 id
+ * @param rel 目录相对路径
+ * @param entries 目录条目
+ */
+export function entriesCachePut(sessionId: string | undefined, rel: string, entries: TreeEntry[]): void {
+  if (!sessionId) return
+  const data = mirrorOf(sessionId)
+  data.dirs[rel] = { ts: nextTs(), entries: entries.slice(0, CACHE_DIR_ENTRIES) }
+  const trimmed = entriesTrim(data)
+  data.dirs = trimmed.dirs
+  scheduleSave(sessionId)
+}

package/src/client/state/viewStateCache.ts

@@ -2,11 +2,13 @@
  * dsh-vscode-mode client — 编辑器视图状态持久化（纯函数，可单测）。
  * 对齐 VSCode workbench.editor.restoreViewState：恢复每个文件的光标/滚动/折叠位置。
  * 视图状态 = Monaco editor.saveViewState() 返回值（JSON 可序列化），按 path 存储。
+ * 键前缀统一走 paths.ts PathConst（CACHE_KEY.viewstate）。
  * 作者 ddj 2026-08-28
  */
+import { CACHE_KEY } from '../paths.js'
 
 /** localStorage 键前缀（按会话隔离）。 */
-const KEY_PREFIX = 'edrv.cache.viewstate.v1.'
+const KEY_PREFIX = CACHE_KEY.viewstate
 
 /** 视图状态条目容量上限。 */
 export const VIEWSTATE_CAP = 50

package/src/client/styles/editor.css

@@ -270,6 +270,7 @@
 [data-edrv-view] .edrv-search-hit { background: var(--dsw-alias-state-warn-primary, #e5b93f); color: #1f2933; border-radius: 2px; padding: 0 1px; }
 [data-edrv-view] .edrv-search-empty { padding: 8px 4px; font-size: 12px; color: var(--dsw-alias-label-tertiary, #9aa5b1); }
 [data-edrv-view] .edrv-search-error { padding: 6px 8px; border: 1px solid rgba(217,83,79,.4); border-radius: 6px; background: #fdeaea; color: var(--dsw-alias-state-error-primary, #d9534f); font-size: 11px; }
+[data-edrv-view] .edrv-search-warn { padding: 6px 8px; border: 1px solid rgba(240,173,78,.45); border-radius: 6px; background: #fdf6e3; color: #b8860b; font-size: 11px; word-break: break-all; }
 
 /* include/exclude filter rows (collapsible) */
 [data-edrv-view] .edrv-search-rows { display: flex; flex-direction: column; gap: 4px; padding: 2px 0 4px; }