dsh-vscode-mode 0.1.44 → 0.1.46

package/src/client/ui/EditorView.ts

@@ -22,9 +22,11 @@ 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 { bindLspUnderline } from '../monaco/lsp/underline.js'
 import { onLspProgress, refreshStatus } from '../monaco/lsp/index.js'
 
 /**
@@ -82,6 +84,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 +174,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 +382,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 +393,7 @@ export function EditorView(props) {
         openFileAt(p, e?.detail?.line, e?.detail?.column)
         return
       }
+      recordNav()
       addTab(p, true)
     }
     const onShowLauncher = (event) => {
@@ -392,6 +492,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 +531,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 +542,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 +555,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 +565,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 +780,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 由光标选区变化驱动。
@@ -685,6 +842,7 @@ export function EditorView(props) {
     })
     ed.addCommand(m.KeyCode.F12, () => { void runGoToDefinition(ed) })
     bindLspEditor(ed)
+    bindLspUnderline(ed, m)
     // hover 差异块 → 浮出 Keep/Undo（req：鼠标移到编辑区差异块时显示）
     // 防闪烁：① 区域不变不 setState（浮窗锚定差异块起始行，不跟随鼠标）；② 延迟隐藏；
     // ③ 浮窗自身 onMouseEnter 取消隐藏计时（鼠标在浮窗与编辑器间移动不闪）。
@@ -720,12 +878,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 +1154,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 +1168,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 +1191,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 +1228,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/lsp/client.ts

@@ -56,6 +56,7 @@ export function createLspClient(
   const pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>()
   let serverCapabilities: LspServerCapabilities = {
     definition: false,
+    declaration: false,
     references: false,
     documentSymbol: false,
     workspaceSymbol: false,
@@ -158,6 +159,7 @@ export function createLspClient(
       const init = await client.request<{
         capabilities?: {
           definitionProvider?: unknown
+          declarationProvider?: unknown
           referencesProvider?: unknown
           documentSymbolProvider?: unknown
           workspaceSymbolProvider?: unknown
@@ -179,6 +181,7 @@ export function createLspClient(
           textDocument: {
             synchronization: { dynamicRegistration: false, willSave: false, didSave: true },
             definition: { dynamicRegistration: false },
+            declaration: { dynamicRegistration: false },
             references: { dynamicRegistration: false },
             documentSymbol: { dynamicRegistration: false },
             hover: { dynamicRegistration: false },
@@ -196,6 +199,7 @@ export function createLspClient(
       const legend = caps.semanticTokensProvider?.legend
       serverCapabilities = {
         definition: Boolean(caps.definitionProvider),
+        declaration: Boolean(caps.declarationProvider),
         references: Boolean(caps.referencesProvider),
         documentSymbol: Boolean(caps.documentSymbolProvider),
         workspaceSymbol: Boolean(caps.workspaceSymbolProvider),

package/src/lsp/derive.ts

@@ -0,0 +1,96 @@
+/**
+ * dsh-vscode-mode host — 定义查找降级链的纯推导函数。
+ * 背景：EmmyLua 对局部变量/参数/表字段的 textDocument/definition 常返回空，
+ * 但 references(includeDeclaration) 能给出包含声明的条目。
+ * 本函数从引用列表推导"声明位置"：同文件、词文本与点击处一致，且点击位置落在某条目内时，
+ * 取列表首个（EmmyLua 对局部/参数把声明排在引用首位；点击处即首个时按"点击了声明"处理）。
+ * 词文本必须与点击词一致，否则拒绝（宁可空，不误跳）。
+ * 作者 ddj 2026-09-02
+ */
+import type { LspLocation, LspPosition, LspRange } from '../shared/lsp.js'
+
+/** file:// URI（或裸路径）→ 归一化绝对路径（小写、/ 分隔）。 */
+function normAbs(uri: string): string {
+  const path = String(uri ?? '').replace(/^file:\/\/\/?/, '')
+  return decodeURIComponent(path).replace(/\\/g, '/').replace(/^\/([A-Za-z]:)/, '$1').toLowerCase()
+}
+
+/** 取文档 text 在 LSP range（0-based）内的切片。 */
+function sliceRange(text: string, range: LspRange): string {
+  const lines = text.split(/\r\n|\r|\n/)
+  const start = range.start
+  const end = range.end
+  const startLine = Math.max(0, start.line)
+  const endLine = Math.max(startLine, end.line)
+  if (startLine >= lines.length || endLine >= lines.length) return ''
+  const startChar = Math.max(0, start.character)
+  if (startLine === endLine) {
+    return lines[startLine].slice(startChar, Math.max(startChar, end.character))
+  }
+  const first = lines[startLine].slice(startChar)
+  const middle = lines.slice(startLine + 1, endLine)
+  const last = lines[endLine].slice(0, Math.max(0, end.character))
+  return [first, ...middle, last].join('\n')
+}
+
+/** LSP position 是否落在 range 内（start 包含、end 排除；零宽按点匹配）。 */
+function posInLspRange(pos: LspPosition, range: LspRange): boolean {
+  const start = range.start
+  const end = range.end ?? start
+  if (start.line === end.line && start.character === end.character) {
+    return pos.line === start.line && pos.character === start.character
+  }
+  if (pos.line < start.line || pos.line > end.line) return false
+  if (pos.line === start.line && pos.character < start.character) return false
+  if (pos.line === end.line && pos.character >= end.character) return false
+  return true
+}
+
+/** 两个 range 是否完全一致。 */
+function sameRange(a: LspRange, b: LspRange): boolean {
+  return a.start.line === b.start.line && a.start.character === b.start.character &&
+    a.end.line === b.end.line && a.end.character === b.end.character
+}
+
+/** range 长度（行/列均按 0-based 差估算，仅用于取"最小包裹"排序）。 */
+function rangeSize(r: LspRange): number {
+  return (r.end.line - r.start.line) * 1_000_000 + (r.end.line === r.start.line ? r.end.character - r.start.character : r.end.character)
+}
+
+/**
+ * 从引用列表推导定义位置。
+ * @author ddj 2026年09月02号
+ * @param queryPos 查询位置（LSP 0-based）
+ * @param locations references(includeDeclaration) 结果
+ * @param docText 当前文档全文（词文本一致校验）
+ * @param docAbsPath 当前文档绝对路径（root+相对路径，与 loc.uri 归一化后比较）
+ * @returns 推导出的定义位置；无法确定返回 null
+ */
+export function deriveDefinitionFromLocations(
+  queryPos: LspPosition,
+  locations: LspLocation[],
+  docText: string,
+  docAbsPath: string,
+): LspLocation | null {
+  if (!locations.length) return null
+  const docAbs = normAbs(docAbsPath)
+
+  // 点击位置落在的条目（多个时取最小包裹 = 最贴近词的 range）
+  const containing = locations
+    .filter((loc) => posInLspRange(queryPos, loc.range))
+    .sort((a, b) => rangeSize(a.range) - rangeSize(b.range))[0]
+  if (!containing) return null
+  const queryWord = sliceRange(docText, containing.range)
+  if (!queryWord) return null
+
+  // 同文件 + 词文本一致的候选（按服务器返回顺序）
+  const candidates = locations.filter((loc) => {
+    return normAbs(loc.uri) === docAbs && sliceRange(docText, loc.range) === queryWord
+  })
+  if (!candidates.length) return null
+
+  // 点击处即候选首个（且与查询词重合）→ 点击的就是声明，返回自身
+  // 否则取首个（EmmyLua 对局部/参数把声明排在引用首位）
+  const first = candidates[0]
+  return sameRange(first.range, containing.range) ? containing : first
+}

package/src/lsp/server.ts

@@ -7,6 +7,7 @@
 import { spawnServer, type Transport } from './transport.js'
 import { createLspClient, type LspClient } from './client.js'
 import { pathToFileUri } from './uri.js'
+import { deriveDefinitionFromLocations } from './derive.js'
 import type { LspProviderSpec } from './providers.js'
 import { LSP_SEMANTIC_TOKEN_MODIFIERS, LSP_SEMANTIC_TOKEN_TYPES } from '../shared/lsp.js'
 import type {
@@ -64,6 +65,7 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
   let client: LspClient | null = null
   let capabilities: LspServerCapabilities = {
     definition: false,
+    declaration: false,
     references: false,
     documentSymbol: false,
     workspaceSymbol: false,
@@ -231,11 +233,55 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
     async definition(path: string, line: number, character: number): Promise<LspLocation[]> {
       const doc = docs.get(path)
       if (!doc || !(await readyWait)) return []
-      const result = await ensureClient().request<unknown>(
-        'textDocument/definition',
-        { textDocument: { uri: doc.uri }, position: { line, character } },
+      const client = ensureClient()
+      const position = { line, character }
+      // ① 标准定义（方法/跨文件命名空间等）
+      const direct = normalizeLocations(
+        await client.request<unknown>(
+          'textDocument/definition',
+          { textDocument: { uri: doc.uri }, position },
+        ),
       )
-      return normalizeLocations(result)
+      if (direct.length) return direct
+      // ② 声明（服务器能力支持时）：EmmyLua 对局部变量/参数/表字段 definition 常返回空，declaration 更准
+      if (capabilities.declaration) {
+        try {
+          const decl = normalizeLocations(
+            await client.request<unknown>(
+              'textDocument/declaration',
+              { textDocument: { uri: doc.uri }, position },
+            ),
+          )
+          if (decl.length) {
+            log('definition fallback → declaration (' + path + ':' + line + ':' + character + ')')
+            return decl
+          }
+        } catch (error) {
+          log('declaration request failed: ' + String(error))
+        }
+      }
+      // ③ 引用推导：definition/declaration 均空时，从 references(includeDeclaration) 推导声明
+      // （EmmyLua 局部/参数把声明排在引用首位；词文本不一致则拒绝，宁可空不误跳）
+      try {
+        const refs = normalizeLocations(
+          await client.request<unknown>(
+            'textDocument/references',
+            {
+              textDocument: { uri: doc.uri },
+              position,
+              context: { includeDeclaration: true },
+            },
+          ),
+        )
+        const derived = deriveDefinitionFromLocations(position, refs, doc.text, doc.uri)
+        if (derived) {
+          log('definition fallback → references-derived (' + path + ':' + line + ':' + character + ')')
+          return [derived]
+        }
+      } catch (error) {
+        log('references fallback failed: ' + String(error))
+      }
+      return []
     },
 
     async references(path: string, line: number, character: number, includeDeclaration: boolean): Promise<LspLocation[]> {

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+-',
 }
 
 /**

package/src/shared/lsp.ts

@@ -69,9 +69,66 @@ export interface LspSemanticTokens {
   resultId?: string
 }
 
+/** 语义 token 解码后的绝对范围（LSP 0-based；type 为插件固定 legend 与 type 名）。 */
+export interface LspSemanticTokenRange {
+  start: LspPosition
+  end: LspPosition
+  type: string
+  modifiers: number
+}
+
+/** 语义 token 中可作为"可导航标识符"的类型（ctrl+hover 下划线判定用）。 */
+export const LSP_NAVIGABLE_TOKEN_TYPES: ReadonlySet<string> = new Set([
+  'variable', 'parameter', 'property', 'function', 'method', 'class', 'enum',
+  'struct', 'interface', 'namespace', 'typeParameter', 'enumMember', 'event', 'type',
+])
+
+/**
+ * 语义 token 是否属于可导航标识符。
+ * @author ddj 2026年09月02号
+ * @param type 语义 token 类型名（插件固定 legend）
+ * @returns 是否可导航
+ */
+export function isNavigableTokenType(type: string): boolean {
+  return LSP_NAVIGABLE_TOKEN_TYPES.has(type)
+}
+
+/**
+ * 解码 LSP delta 编码的语义 token 流为绝对范围数组。
+ * @author ddj 2026年09月02号
+ * @param data 5 元组 delta 流（host normalizeSemanticData 产物，类型索引对应固定 legend）
+ * @param types 固定 legend 类型表（缺省 LSP_SEMANTIC_TOKEN_TYPES）
+ * @returns 绝对范围列表（保持文档顺序）
+ */
+export function decodeSemanticTokens(
+  data: number[],
+  types: readonly string[] = LSP_SEMANTIC_TOKEN_TYPES,
+): LspSemanticTokenRange[] {
+  const out: LspSemanticTokenRange[] = []
+  let line = 0
+  let character = 0
+  for (let i = 0; i + 4 < data.length; i += 5) {
+    const deltaLine = data[i] ?? 0
+    const deltaCharacter = data[i + 1] ?? 0
+    const length = Math.max(0, data[i + 2] ?? 0)
+    const typeIndex = data[i + 3] ?? 0
+    const modifiers = data[i + 4] ?? 0
+    line += deltaLine
+    character = deltaLine === 0 ? character + deltaCharacter : deltaCharacter
+    out.push({
+      start: { line, character },
+      end: { line, character: character + length },
+      type: types[typeIndex] ?? 'variable',
+      modifiers,
+    })
+  }
+  return out
+}
+
 /** LSP 服务器能力子集：本插件会用到的方法。 */
 export interface LspServerCapabilities {
   definition: boolean
+  declaration: boolean
   references: boolean
   documentSymbol: boolean
   workspaceSymbol: boolean