dsh-vscode-mode 0.1.44 → 0.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 dsh-better-sidebar 侧边栏与对话同屏）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚）+ 语言服务器（LSP）智能（跳转定义/引用/hover/大纲 + VSIX 扩展市场安装），状态持久化到工作区旁车",
   "keywords": [
     "dsh",

package/src/client/keybindings.ts

@@ -1,6 +1,6 @@
 /**
  * dsh-vscode-mode client — 快捷键配置模块（解析/匹配/状态同步）。
- * 纯逻辑（parseChord/formatChord/matchEvent/chordFromEvent/normalizeKey）不依赖 DOM，可单测；
+ * 纯逻辑（parseChord/parseChords/formatChord/matchEvent/chordFromEvent/normalizeKey）不依赖 DOM，可单测；
  * 模块状态由 settings 订阅驱动（client/index.ts 调 keybindingsApply）。
  * 键位语义：Ctrl 与 Cmd 互认（延续现有 Ctrl+P/Ctrl+B 捕获行为）。
  * 作者 ddj 2026年08月26号
@@ -23,6 +23,8 @@ export const COMMANDS: Array<{ id: string; label: string }> = [
   { id: 'edrv.quickOpen', label: '快速打开文件' },
   { id: 'edrv.toggleSidebar', label: '切换侧边栏' },
   { id: 'edrv.searchInFiles', label: '在工作区中搜索' },
+  { id: 'edrv.navigateBack', label: '后退（导航历史）' },
+  { id: 'edrv.navigateForward', label: '前进（导航历史）' },
 ]
 
 const MODIFIERS: Record<string, 'ctrl' | 'shift' | 'alt' | 'meta'> = {
@@ -30,18 +32,19 @@ const MODIFIERS: Record<string, 'ctrl' | 'shift' | 'alt' | 'meta'> = {
 }
 
 let current: Record<string, string> = { ...KEYBINDING_DEFAULTS }
-let parsed: Record<string, Binding | null> = {}
+let parsed: Record<string, Binding[]> = {}
 const listeners = new Set<() => void>()
 
 /**
  * 应用设置快照（与默认值合并；未知 id 丢弃；空对象 = 全部默认）。
+ * 每个命令可含多候选键位（`|` 分隔），任一命中即触发。
  * @author ddj 2026年08月26号
  * @param raw 设置 scope 的 keybindings 字段
  */
 export function keybindingsApply(raw: unknown): void {
   current = { ...KEYBINDING_DEFAULTS, ...normalizeKeybindings(raw) }
   parsed = {}
-  for (const id of Object.keys(current)) parsed[id] = parseChord(current[id])
+  for (const id of Object.keys(current)) parsed[id] = parseChords(current[id])
   for (const listener of listeners) {
     try { listener() } catch { /* 监听器异常不影响其他订阅 */ }
   }
@@ -70,13 +73,13 @@ export function chordOf(id: string): string | null {
 }
 
 /**
- * 当前命令的解析键位（未绑定/非法 → null）。
+ * 当前命令的解析键位集合（未绑定/非法 → 空数组；含多候选）。
  * @author ddj 2026年08月26号
  * @param id 命令 id
- * @returns 解析键位或 null
+ * @returns 解析键位数组（可能为空）
  */
-export function bindingOf(id: string): Binding | null {
-  return parsed[id] ?? null
+export function bindingsOf(id: string): Binding[] {
+  return parsed[id] ?? []
 }
 
 /**
@@ -114,6 +117,26 @@ export function parseChord(chord: string): Binding | null {
   return binding.key ? binding : null
 }
 
+/**
+ * 解析多候选键位弦（`|` 分隔）：逐段解析，丢弃非法段，去重。
+ * @author ddj 2026年08月26号
+ * @param chord 键位弦（如 `Alt+ArrowLeft|Ctrl+Alt+-`）
+ * @returns 解析键位数组（纯 `|`/空/非法 → 空数组）
+ */
+export function parseChords(chord: string): Binding[] {
+  const out: Binding[] = []
+  const seen = new Set<string>()
+  for (const part of String(chord ?? '').split('|')) {
+    const binding = parseChord(part)
+    if (!binding) continue
+    const key = formatChord(binding)
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(binding)
+  }
+  return out
+}
+
 /**
  * 格式化键位（Ctrl/Cmd/Shift/Alt + 主键；meta 显示 Cmd）。
  * @author ddj 2026年08月26号
@@ -131,18 +154,21 @@ export function formatChord(binding: Binding): string {
 }
 
 /**
- * 事件是否命中键位（Ctrl 与 Cmd 互认）。
+ * 事件是否命中键位（Ctrl 与 Cmd 互认；多候选任一命中即 true）。
  * @author ddj 2026年08月26号
  * @param e 键盘事件（鸭子类型，便于单测）
- * @param binding 解析键位（null = 未绑定，永不命中）
+ * @param bindings 解析键位或键位数组（null/空 = 未绑定，永不命中）
  * @returns 是否命中
  */
-export function matchEvent(e: { ctrlKey?: boolean; metaKey?: boolean; shiftKey?: boolean; altKey?: boolean; key?: string }, binding: Binding | null): boolean {
-  if (!binding) return false
-  if ((e.ctrlKey || e.metaKey) !== (binding.ctrl || binding.meta)) return false
-  if (Boolean(e.shiftKey) !== binding.shift) return false
-  if (Boolean(e.altKey) !== binding.alt) return false
-  return normalizeKey(e.key ?? '') === binding.key
+export function matchEvent(e: { ctrlKey?: boolean; metaKey?: boolean; shiftKey?: boolean; altKey?: boolean; key?: string }, bindings: Binding | Binding[] | null): boolean {
+  const list = Array.isArray(bindings) ? bindings : bindings ? [bindings] : []
+  for (const binding of list) {
+    if (Boolean(e.ctrlKey || e.metaKey) !== (binding.ctrl || binding.meta)) continue
+    if (Boolean(e.shiftKey) !== binding.shift) continue
+    if (Boolean(e.altKey) !== binding.alt) continue
+    if (normalizeKey(e.key ?? '') === binding.key) return true
+  }
+  return false
 }
 
 /**

package/src/client/navHistory.ts

@@ -0,0 +1,104 @@
+/**
+ * dsh-vscode-mode client — 编辑器导航历史（后退/前进）纯逻辑。
+ * 对齐 VSCode Go Back / Go Forward（navigation history）：记录「文件 + 焦点位置」访问轨迹，
+ * 后退回到上一处焦点，前进回到下一处，跨文件生效。
+ * 数据模型：past（末位 = 当前）+ future 两个栈；record 压栈并清空 future；
+ * 与栈顶同 path+line+column 视为同一位置：仅刷新 viewState 快照，不压栈、不清 future。
+ * 纯逻辑无 DOM 依赖，可单测。
+ * 作者 ddj 2026年09月04号
+ */
+
+/** 导航历史单条记录：文件 + 焦点位置（+ 可选的 viewState 快照用于恢复滚动/折叠）。 */
+export interface NavEntry {
+  /** 工作区相对路径 */
+  path: string
+  /** 焦点行（1-based） */
+  line?: number
+  /** 焦点列（1-based） */
+  column?: number
+  /** 该位置保存的 Monaco viewState（恢复滚动/折叠） */
+  viewState?: unknown
+}
+
+/** 导航历史接口。 */
+export interface NavHistory {
+  /** 记录当前位置（压栈 + 清空 future；与栈顶同位置时仅更新 viewState）。 */
+  record(entry: NavEntry): void
+  /** 后退：返回将要恢复的前一条目；历史不足 2 条 → null。 */
+  back(): NavEntry | null
+  /** 前进：返回将要恢复的条目；future 空 → null。 */
+  forward(): NavEntry | null
+  /** 是否可后退。 */
+  canBack(): boolean
+  /** 是否可前进。 */
+  canForward(): boolean
+  /** 后退目标条目（不改变状态；不可退 → null）。 */
+  peekBack(): NavEntry | null
+  /** 前进目标条目（不改变状态；不可进 → null）。 */
+  peekForward(): NavEntry | null
+}
+
+/** 后退栈默认容量上限（超出逐出最旧）。 */
+export const NAV_HISTORY_CAP = 200
+
+/** 路径一致（容忍相对路径大小写差异，对齐既有 sameFile 语义常用写法）。 */
+function samePath(a: string, b: string): boolean {
+  if (a === b) return true
+  return String(a).replace(/\\/g, '/').toLowerCase() === String(b).replace(/\\/g, '/').toLowerCase()
+}
+
+/** 位置一致（无焦点时按 null 归一，`undefined`/`null` 视为相等）。 */
+function samePos(a: NavEntry, b: NavEntry): boolean {
+  if (!samePath(a.path, b.path)) return false
+  return (a.line ?? null) === (b.line ?? null) && (a.column ?? null) === (b.column ?? null)
+}
+
+/**
+ * 创建导航历史实例（容量裁剪到 cap）。
+ * @author ddj 2026年09月04号
+ * @param cap 后退栈容量上限（默认 NAV_HISTORY_CAP）
+ * @returns 导航历史实例
+ */
+export function createNavHistory(cap = NAV_HISTORY_CAP): NavHistory {
+  const past: NavEntry[] = []
+  const future: NavEntry[] = []
+  return {
+    record(entry: NavEntry): void {
+      if (!entry || !entry.path) return
+      const top = past[past.length - 1]
+      if (top && samePos(top, entry)) {
+        // 同一位置：只更新 viewState 快照（滚动/折叠可能变化），栈与 future 不动
+        if (top.viewState !== undefined || entry.viewState !== undefined) top.viewState = entry.viewState
+        return
+      }
+      past.push({ path: entry.path, line: entry.line, column: entry.column, viewState: entry.viewState })
+      if (past.length > cap) past.splice(0, past.length - cap)
+      future.length = 0
+    },
+    back(): NavEntry | null {
+      if (past.length < 2) return null
+      const current = past.pop()
+      if (!current) return null
+      future.push(current)
+      return past[past.length - 1]
+    },
+    forward(): NavEntry | null {
+      const entry = future.pop()
+      if (!entry) return null
+      past.push(entry)
+      return entry
+    },
+    canBack(): boolean {
+      return past.length >= 2
+    },
+    canForward(): boolean {
+      return future.length > 0
+    },
+    peekBack(): NavEntry | null {
+      return past.length >= 2 ? past[past.length - 2] : null
+    },
+    peekForward(): NavEntry | null {
+      return future.length ? future[future.length - 1] : null
+    },
+  }
+}

package/src/client/styles/editor.css

@@ -43,6 +43,8 @@
 [data-edrv-view] .edrv-diffchip { font-size: 11px; padding: 2px 10px; border: 1px solid var(--dsw-alias-border-l1, #333); border-radius: 999px; background: var(--dsw-alias-bg-layer-2, transparent); color: var(--dsw-alias-state-warn-primary, #b7791f); cursor: pointer; white-space: nowrap; flex-shrink: 0; }
 [data-edrv-view] .edrv-chip-btn { font-size: 12px; padding: 2px 6px; border: none; background: transparent; color: var(--dsw-alias-label-secondary, #aaa); cursor: pointer; border-radius: 4px; flex-shrink: 0; }
 [data-edrv-view] .edrv-chip-btn:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.06)); }
+[data-edrv-view] .edrv-chip-btn:disabled { opacity: .35; cursor: default; }
+[data-edrv-view] .edrv-chip-btn:disabled:hover { background: transparent; }
 [data-edrv-view] .edrv-mn-add-line { background: rgba(15,157,88,.10); }
 [data-edrv-view] .edrv-mn-gutter-add { color: #0f9d58 !important; font-weight: 700; display: flex !important; align-items: center; justify-content: center; }
 [data-edrv-view] .edrv-mn-gutter-add::before { content: "+"; }

package/src/client/ui/EditorView.ts

@@ -22,7 +22,8 @@ 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 { bindingOf, chordOf, matchEvent, useKeybindingsVersion } from '../keybindings.js'
+import { bindingsOf, chordOf, matchEvent, useKeybindingsVersion } from '../keybindings.js'
+import { createNavHistory } from '../navHistory.js'
 import { CACHE_KEY } from '../paths.js'
 import { bindLspEditor, runGoToDefinition, runFindReferences, hideReferencesOverlay } from '../monaco/lsp/providers.js'
 import { onLspProgress, refreshStatus } from '../monaco/lsp/index.js'
@@ -82,6 +83,14 @@ export function EditorView(props) {
   const programmaticRef = React.useRef(false)
   const bootRef = React.useRef(false)
   const pendingFocusRef = React.useRef(null) // { path, region } 内容加载后跳转
+  // 导航历史（后退/前进）：跨文件焦点位置；按会话隔离，会话切换重置
+  const navRef = React.useRef(null)
+  if (!navRef.current) navRef.current = createNavHistory()
+  const navPendingRef = React.useRef(null) // { path,line,column,viewState } 待恢复条目（内容就绪后消费）
+  const navCursorTimerRef = React.useRef(null) // 光标位置防抖记录计时器
+  const navBackRef = React.useRef(null) // 后退动作最新闭包（窗口级键盘监听读取）
+  const navForwardRef = React.useRef(null) // 前进动作最新闭包（窗口级键盘监听读取）
+  const [navTick, setNavTick] = React.useState(0) // 历史可用性版本（按钮 disabled 重渲染）
   const hoverRegionsRef = React.useRef([]) // 当前 pending 区域镜像（稳定回调读取）
   const lineRegionMapRef = React.useRef(new Map()) // 行 → 区域 映射（hover 命中）
   const hoverKeyRef = React.useRef(null) // 当前 hover 区域 key（区域不变不重渲染）
@@ -164,9 +173,97 @@ export function EditorView(props) {
     try { ed.restoreViewState(saved) } catch (e) { /* 恢复失败忽略（行号越界自动兜底） */ }
   }
 
+  /**
+   * 采集当前焦点条目：路径从编辑器 model 实时读取（避免空依赖闭包读到过期 active），
+   * 位置/viewState 从编辑器读取；编辑器或模型未就绪 → null。
+   * @author ddj 2026年09月04号
+   * @returns 导航历史条目或 null
+   */
+  const captureNavEntry = () => {
+    const ed = editorRef.current
+    const model = ed?.getModel?.()
+    const uriPath = model?.uri?.path
+    if (!ed || !uriPath) return null
+    let line = null
+    let column = null
+    try {
+      const pos = ed.getPosition?.()
+      if (pos) { line = pos.lineNumber; column = pos.column }
+    } catch (e) { /* 位置读取失败降级为仅路径 */ }
+    let viewState = null
+    try { viewState = ed.saveViewState() } catch (e) { /* 快照失败忽略 */ }
+    return { path: decodeURIComponent(String(uriPath).replace(/^\//, '')), line, column, viewState }
+  }
+
+  /**
+   * 记录当前位置到导航历史（同位置去重由历史模块处理；可用性变化时刷新按钮）。
+   * @author ddj 2026年09月04号
+   */
+  const recordNav = () => {
+    const entry = captureNavEntry()
+    if (!entry) return
+    const wasBack = navRef.current.canBack()
+    const wasForward = navRef.current.canForward()
+    navRef.current.record(entry)
+    if (navRef.current.canBack() !== wasBack || navRef.current.canForward() !== wasForward) {
+      setNavTick((v) => v + 1)
+    }
+  }
+
+  /**
+   * 跳到历史条目：保存当前视图状态后打开目标文件，内容就绪后恢复焦点。
+   * @author ddj 2026年09月04号
+   * @param entry 目标历史条目
+   */
+  const navigateTo = (entry) => {
+    if (!entry || !entry.path) return
+    flushSave()
+    saveViewState(active)
+    navPendingRef.current = entry
+    addTab(entry.path, true)
+    setFocusRequest((value) => value + 1) // 目标已是活动文件时也触发恢复
+  }
+
+  /**
+   * 立即落盘待记录的光标位置（后退/前进前调用：<500ms 内刚移动的光标也算入历史）。
+   * @author ddj 2026年09月04号
+   */
+  const flushNavCursor = () => {
+    if (!navCursorTimerRef.current) return
+    clearTimeout(navCursorTimerRef.current)
+    navCursorTimerRef.current = null
+    recordNav()
+  }
+
+  /**
+   * 后退：恢复上一处焦点（跨文件）。
+   * @author ddj 2026年09月04号
+   */
+  const navBack = () => {
+    flushNavCursor()
+    const entry = navRef.current.back()
+    if (!entry) return
+    navigateTo(entry)
+    setNavTick((v) => v + 1)
+  }
+
+  /**
+   * 前进：恢复下一处焦点（跨文件）。
+   * @author ddj 2026年09月04号
+   */
+  const navForward = () => {
+    flushNavCursor()
+    const entry = navRef.current.forward()
+    if (!entry) return
+    navigateTo(entry)
+    setNavTick((v) => v + 1)
+  }
+  navBackRef.current = navBack
+  navForwardRef.current = navForward
+
   const closeTab = (path) => {
     flushSave()
-    if (path === active) saveViewState(path)
+    if (path === active) { saveViewState(path); recordNav() }
     setTabs((prev) => {
       const idx = prev.findIndex((t) => t.path === path)
       if (idx < 0) return prev
@@ -284,6 +381,7 @@ export function EditorView(props) {
       const p = e?.detail?.path
       if (!p) return
       if (e?.detail?.focusDiff === true) {
+        recordNav()
         pendingFocusRef.current = { path: p, region: null }
         setFocusRequest((value) => value + 1)
         addTab(p, true)
@@ -294,6 +392,7 @@ export function EditorView(props) {
         openFileAt(p, e?.detail?.line, e?.detail?.column)
         return
       }
+      recordNav()
       addTab(p, true)
     }
     const onShowLauncher = (event) => {
@@ -392,6 +491,14 @@ export function EditorView(props) {
     } catch (e) { /* 损坏忽略 */ }
   }, [sessionId])
 
+  // 导航历史会话隔离：切换会话时重置（历史仅会话内存，不跨会话串扰）
+  React.useEffect(() => {
+    navRef.current = createNavHistory()
+    navPendingRef.current = null
+    if (navCursorTimerRef.current) { clearTimeout(navCursorTimerRef.current); navCursorTimerRef.current = null }
+    setNavTick((v) => v + 1)
+  }, [sessionId])
+
   React.useEffect(() => {
     if (!sessionId) return
     try { localStorage.setItem(CACHE_KEY.editor + String(sessionId), JSON.stringify({ tabs: tabs.map((t) => t.path), active })) }
@@ -423,7 +530,7 @@ export function EditorView(props) {
   // 切换侧边栏（capture 抢占，避免与 DSH 全局冲突；键位随快捷键配置）
   React.useEffect(() => {
     const onKey = (e) => {
-      if (!matchEvent(e, bindingOf('edrv.toggleSidebar'))) return
+      if (!matchEvent(e, bindingsOf('edrv.toggleSidebar'))) return
       e.preventDefault(); e.stopPropagation()
       setSidebarOn((v) => !v)
     }
@@ -434,7 +541,7 @@ export function EditorView(props) {
   // 保存文件（窗口级）：编辑器有活动模型才拦截执行，无文件时放行（浏览器默认行为）
   React.useEffect(() => {
     const onKey = (e) => {
-      if (!matchEvent(e, bindingOf('edrv.save'))) return
+      if (!matchEvent(e, bindingsOf('edrv.save'))) return
       if (!editorRef.current?.getModel?.()) return
       e.preventDefault(); e.stopPropagation()
       flushSave()
@@ -447,7 +554,7 @@ export function EditorView(props) {
   // Ctrl+Shift+F 全局搜索：展开侧边栏 + 激活搜索页签，随后聚焦搜索输入框
   React.useEffect(() => {
     const onKey = (e) => {
-      if (!matchEvent(e, bindingOf('edrv.searchInFiles'))) return
+      if (!matchEvent(e, bindingsOf('edrv.searchInFiles'))) return
       e.preventDefault(); e.stopPropagation()
       setSidebarOn(true)
       setActivePanel('search')
@@ -457,6 +564,49 @@ export function EditorView(props) {
     return () => window.removeEventListener('keydown', onKey, true)
   }, [])
 
+  // 后退/前进：导航历史（跨文件焦点位置；经 ref 读最新闭包，避免空依赖过期）
+  React.useEffect(() => {
+    const onKey = (e) => {
+      if (!matchEvent(e, bindingsOf('edrv.navigateBack'))) return
+      e.preventDefault(); e.stopPropagation()
+      if (navBackRef.current) navBackRef.current()
+    }
+    window.addEventListener('keydown', onKey, true)
+    return () => window.removeEventListener('keydown', onKey, true)
+  }, [])
+  React.useEffect(() => {
+    const onKey = (e) => {
+      if (!matchEvent(e, bindingsOf('edrv.navigateForward'))) return
+      e.preventDefault(); e.stopPropagation()
+      if (navForwardRef.current) navForwardRef.current()
+    }
+    window.addEventListener('keydown', onKey, true)
+    return () => window.removeEventListener('keydown', onKey, true)
+  }, [])
+
+  // 鼠标侧键后退/前进：Logitech 官方默认「后退/前进」= XButton 鼠标事件（button 3/4），不产生键盘事件。
+  // pointerdown 触发导航（preventDefault 后兼容 mousedown 可能不再触发，避免双触发）；
+  // mousedown 兜底仅取消浏览器历史导航默认动作（MDN：preventDefault mousedown/pointerdown 可抑制）。
+  // @author ddj 2026年09月02号
+  React.useEffect(() => {
+    const onPointer = (e) => {
+      if (e?.button !== 3 && e?.button !== 4) return
+      e.preventDefault(); e.stopPropagation()
+      const ref = e.button === 3 ? navBackRef : navForwardRef
+      if (ref.current) ref.current()
+    }
+    const onMouse = (e) => {
+      if (e?.button !== 3 && e?.button !== 4) return
+      e.preventDefault(); e.stopPropagation()
+    }
+    window.addEventListener('pointerdown', onPointer, true)
+    window.addEventListener('mousedown', onMouse, true)
+    return () => {
+      window.removeEventListener('pointerdown', onPointer, true)
+      window.removeEventListener('mousedown', onMouse, true)
+    }
+  }, [])
+
   // 文件 → 待处理差异数 映射（侧边栏角标）
   const pendingByPath = React.useMemo(() => {
     const out = {}
@@ -629,6 +779,12 @@ export function EditorView(props) {
     })
     ed.onDidChangeCursorPosition((e) => {
       setCursor('Ln ' + e.position.lineNumber + ', Col ' + e.position.column)
+      // 导航历史：同文件内光标移动防抖记录（程序化恢复触发的位置与栈顶去重，无副作用）
+      if (navCursorTimerRef.current) clearTimeout(navCursorTimerRef.current)
+      navCursorTimerRef.current = setTimeout(() => {
+        navCursorTimerRef.current = null
+        recordNav()
+      }, 500)
     })
     // 编辑区右键 → 注入 Monaco 原生 context menu（与 Go to Definition 等同菜单，避免分离浮层）。
     // 有选区时额外显示「选中内容」项：context key edrvSelection 由光标选区变化驱动。
@@ -720,12 +876,26 @@ export function EditorView(props) {
     editorRef.current = ed
   }, [])
 
-  // 打开文件后的跳转（差异聚焦/搜索行列跳转，内容就绪后执行一次）
+  // 打开文件后的跳转（导航历史恢复/差异聚焦/搜索行列跳转，内容就绪后执行一次）
   React.useEffect(() => {
-    const pf = pendingFocusRef.current
-    if (!pf || pf.path !== active || content === null) return
     const ed = editorRef.current
-    if (!ed) return
+    if (!ed || content === null) return
+    // 导航历史恢复优先：viewState 快照恢复滚动/折叠，行列补定位
+    const nav = navPendingRef.current
+    if (nav && nav.path === active) {
+      navPendingRef.current = null
+      if (nav.viewState) {
+        try { ed.restoreViewState(nav.viewState) } catch (e) { /* 非法快照忽略（行号越界自动兜底） */ }
+      }
+      if (nav.line != null) {
+        ed.revealLineInCenter(Math.max(1, nav.line))
+        ed.setPosition({ lineNumber: Math.max(1, nav.line), column: Math.max(1, nav.column ?? 1) })
+      }
+      ed.focus()
+      return
+    }
+    const pf = pendingFocusRef.current
+    if (!pf || pf.path !== active) return
     if (pf.line != null) {
       // 搜索命中跳转：直接定位到行/列（不依赖差异区域）
       pendingFocusRef.current = null
@@ -982,6 +1152,7 @@ export function EditorView(props) {
 
   const openFile = (path, focusDiff) => {
     if (!path) return
+    recordNav()
     addTab(path, true)
     if (focusDiff) pendingFocusRef.current = { path, region: null }
   }
@@ -995,6 +1166,7 @@ export function EditorView(props) {
    */
   const openFileAt = (path, line, column) => {
     if (!path) return
+    recordNav()
     addTab(path, true)
     pendingFocusRef.current = { path, region: null, line: line ?? null, column: column ?? 1 }
     setFocusRequest((value) => value + 1)
@@ -1017,7 +1189,7 @@ export function EditorView(props) {
       key: t.path,
       className: 'edrv-tab' + (t.path === active ? ' edrv-tab-active' : ''),
       title: t.path,
-      onClick: () => { if (t.path !== active) { flushSave(); saveViewState(active); setActive(t.path) } },
+      onClick: () => { if (t.path !== active) { flushSave(); saveViewState(active); recordNav(); setActive(t.path) } },
       onContextMenu: (e) => {
         e.preventDefault()
         e.stopPropagation()
@@ -1054,11 +1226,29 @@ export function EditorView(props) {
         lspProgress !== null ? React.createElement('span', { className: 'edrv-sp-progress' }, lspProgress + '%') : null)
     : null
 
+  // 导航历史按钮：目标条目名（tooltip 提示下一步会回到哪个文件）
+  const navBackTarget = navRef.current.peekBack()
+  const navForwardTarget = navRef.current.peekForward()
+  const navNameOf = (entry) => (entry && entry.path ? String(entry.path).split(/[\\/]/).pop() : '')
   const tabRow = React.createElement('div', { style: { display: 'flex', alignItems: 'center', background: 'var(--dsw-alias-bg-layer-1,transparent)', flexShrink: 0 } },
     tabsEl,
     (sum.totalFiles > 0
       ? React.createElement('button', { className: 'edrv-diffchip', title: '打开差异总览/归档', onClick: () => setLauncherOpen((o) => !o) }, '⚠ 差异 ' + sum.totalFiles + ' 文件')
       : null),
+    React.createElement('button', {
+      className: 'edrv-chip-btn',
+      title: '后退（' + (chordOf('edrv.navigateBack') ?? '未绑定') + '）' + (navBackTarget ? ' · ' + navNameOf(navBackTarget) : ''),
+      disabled: !navRef.current.canBack(),
+      'aria-label': '后退',
+      onClick: navBack,
+    }, '←'),
+    React.createElement('button', {
+      className: 'edrv-chip-btn',
+      title: '前进（' + (chordOf('edrv.navigateForward') ?? '未绑定') + '）' + (navForwardTarget ? ' · ' + navNameOf(navForwardTarget) : ''),
+      disabled: !navRef.current.canForward(),
+      'aria-label': '前进',
+      onClick: navForward,
+    }, '→'),
     React.createElement('button', { className: 'edrv-chip-btn' + (sidebarOn ? ' edrv-chip-on' : ''), title: '切换侧边栏 (' + (chordOf('edrv.toggleSidebar') ?? 'Ctrl+B') + ')', onClick: () => setSidebarOn((v) => !v) }, '☰'),
     React.createElement('button', { className: 'edrv-chip-btn', title: '刷新', onClick: reloadFile }, '⟳'),
     React.createElement(QuickOpen, { sessionId, onOpen: (p) => openFile(p, false) }))

package/src/client/ui/KeybindingsPanel.ts

@@ -9,7 +9,7 @@
  */
 import React from 'react'
 import { SettingsContext } from '../settingsContext.js'
-import { COMMANDS, chordFromEvent, parseChord } from '../keybindings.js'
+import { COMMANDS, chordFromEvent, parseChords } from '../keybindings.js'
 import { defaultKeybindings, KEYBINDING_DEFAULTS, normalizeKeybindings } from '../../shared/keybindings.js'
 
 /**
@@ -148,7 +148,7 @@ export function KeybindingsPanel() {
   const rows = COMMANDS.map((command) => {
     const chord = draft[command.id] ?? null
     const conflict = chord !== null && conflicts.has(command.id)
-    const invalid = chord !== null && parseChord(chord) === null
+    const invalid = chord !== null && parseChords(chord).length === 0
     const recordingRow = recording === command.id
     let display
     if (recordingRow) {
@@ -174,7 +174,7 @@ export function KeybindingsPanel() {
 
   return React.createElement('section', { className: 'vsm-general-page' },
     React.createElement('h2', null, '快捷键'),
-    React.createElement('p', null, '配置编辑器视图的快捷键（保存 / 快速打开 / 侧边栏 / 搜索）。修改即时写入配置，重新聚焦编辑器后生效。'),
+    React.createElement('p', null, '配置编辑器视图的快捷键（保存 / 快速打开 / 侧边栏 / 搜索 / 后退 / 前进）。修改即时写入配置，重新聚焦编辑器后生效。'),
     unavailable && React.createElement('div', { className: 'vsm-mcp-error vsm-mcp-banner' }, '设置服务暂不可用，当前使用默认键位。'),
     error && React.createElement('div', { className: 'vsm-mcp-error vsm-mcp-banner' }, error),
     message && React.createElement('div', { className: 'vsm-kb-message' }, message),

package/src/client/ui/QuickOpen.ts

@@ -7,7 +7,7 @@
  */
 import React from 'react'
 import { rpc } from '../rpc.js'
-import { bindingOf, chordOf, matchEvent, useKeybindingsVersion } from '../keybindings.js'
+import { bindingsOf, chordOf, matchEvent, useKeybindingsVersion } from '../keybindings.js'
 
 /**
  * 快速打开搜索框：Ctrl+P 聚焦，输入 ≥2 字符经 edrv.searchFiles 搜索，
@@ -50,7 +50,7 @@ export function QuickOpen(props) {
 
   React.useEffect(() => {
     const onKey = (e) => {
-      if (matchEvent(e, bindingOf('edrv.quickOpen'))) {
+      if (matchEvent(e, bindingsOf('edrv.quickOpen'))) {
         e.preventDefault(); e.stopPropagation()
         inputRef.current?.focus?.()
         setOpen(true)

package/src/shared/keybindings.ts

@@ -1,16 +1,19 @@
 /**
  * dsh-vscode-mode shared — 快捷键命令目录与默认键位（双面契约）。
  * 纯数据模块：host（settings schema 默认值）与 client（执行匹配/设置页）共用。
- * 键位格式：修饰符 + 主键，`+` 连接，如 `Ctrl+Shift+F`；空串 = 未绑定。
+ * 键位格式：修饰符 + 主键，`+` 连接，如 `Ctrl+Shift+F`；空串 = 未绑定；
+ * `|` 连接多个候选（任一命中即触发），如 `Alt+ArrowLeft|Ctrl+Alt+-`。
  * 作者 ddj 2026年08月26号
  */
 
-/** 命令 id → 默认键位。命令目录以此为准，新增命令只需加一项。 */
+/** 命令 id → 默认键位（可为多候选）。命令目录以此为准，新增命令只需加一项。 */
 export const KEYBINDING_DEFAULTS: Record<string, string> = {
   'edrv.save': 'Ctrl+S',
   'edrv.quickOpen': 'Ctrl+P',
   'edrv.toggleSidebar': 'Ctrl+B',
   'edrv.searchInFiles': 'Ctrl+Shift+F',
+  'edrv.navigateBack': 'Alt+ArrowLeft|Ctrl+Alt+-',
+  'edrv.navigateForward': 'Alt+ArrowRight|Ctrl+Shift+-',
 }
 
 /**