dsh-vscode-mode 0.15.6 → 0.15.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.15.6",
+  "version": "0.15.7",
   "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": [

package/src/client/monaco/lsp/providers.ts

@@ -3,7 +3,7 @@
  * dsh-vscode-mode client — Monaco LSP provider 注册 + 跳转/引用命令。
  * 数据层：Definition/Reference/DocumentSymbol/Hover provider（同一文件内跳转 Monaco 原生可用）。
  * 交互层：edrv.goToDefinition（F12）/ edrv.findReferences（Shift+F12 / 右键）均走 Monaco 原生命令；
- * Ctrl+点击同样交给原生（多结果弹 Peek 让用户选、无定义时按 alternativeDefinitionCommand 降级），
+ * Ctrl+点击使用处交给原生；Lua 表枚举字段声明处改为打开引用 Peek，
  * 数据经 host 的 LSP RPC 提供（registerEditorOpener 接管 edrv:// 点击跳转）。
  * 作者 ddj 2026-08-27 / 2026-09-11
  */
@@ -324,6 +324,73 @@ function peekSupported(ed) {
   }
 }
 
+/**
+ * 判定 Ctrl+点击是否落在 Lua 表的字段声明键上（`TaskStateChange = 50000`）。
+ * 仅拦截表字面量内的键，不改动使用处的原生跳转行为。
+ * @author ddj 2026年10月16号
+ * @param model 当前 Monaco 文档
+ * @param position 鼠标命中位置
+ * @returns 是否为表字段声明键
+ */
+export function isLuaTableKey(model, position) {
+  if (model?.getLanguageId?.() !== 'lua' || !position) return false
+  const line = model.getLineContent(position.lineNumber)
+  const key = model.getWordAtPosition(position)
+  if (!key || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key.word)) return false
+  if (!/^\s*=\s*(?!=)/.test(line.slice(key.endColumn - 1))) return false
+  if (!/^\s*$/.test(line.slice(0, key.startColumn - 1))) return false
+
+  // 仅识别 `Name = {` 后连续的键值行；遇到其它语句或闭合括号即停止回溯。
+  for (let lineNumber = position.lineNumber - 1; lineNumber >= Math.max(1, position.lineNumber - 100); lineNumber--) {
+    const previous = model.getLineContent(lineNumber).trim()
+    if (!previous || previous.startsWith('--')) continue
+    if (/^(?:[A-Za-z_][A-Za-z0-9_]*\s*\.\s*)*[A-Za-z_][A-Za-z0-9_]*\s*=\s*\{\s*(?:--.*)?$/.test(previous)) return true
+    if (!/^[A-Za-z_][A-Za-z0-9_]*\s*=\s*[^{}]*,?\s*(?:--.*)?$/.test(previous)) return false
+  }
+  return false
+}
+
+/**
+ * 仅在 Lua 表字段声明处把 Ctrl+点击交给引用 Peek；其他点击留给 Monaco 原生导航。
+ * 使用 DOM capture 阶段阻止原生 gotoDefinitionAtPosition 同时触发，避免跳转和 Peek 竞态。
+ * @author ddj 2026年10月16号
+ * @param ed Monaco 编辑器
+ * @param monaco Monaco API
+ * @returns 解绑回调
+ */
+export function bindLuaKeyRefs(ed, monaco) {
+  const node = ed?.getDomNode?.()
+  if (!node) return () => {}
+  const keyAt = (event) => {
+    if (event.button !== 0 || (!event.ctrlKey && !event.metaKey) || event.altKey || event.shiftKey) return null
+    const target = ed.getTargetAtClientPoint?.(event.clientX, event.clientY)
+    const content = monaco.editor?.MouseTargetType?.CONTENT_TEXT ?? 6
+    return target?.type === content && isLuaTableKey(ed.getModel(), target.position) ? target.position : null
+  }
+  let suppressUp = false
+  const onDown = (event) => {
+    const position = keyAt(event)
+    if (!position) return
+    suppressUp = true
+    event.preventDefault()
+    event.stopPropagation()
+    ed.setPosition(position)
+    void triggerReferencePeek(ed)
+  }
+  const onUp = (event) => {
+    if (!suppressUp) return
+    suppressUp = false
+    event.preventDefault()
+    event.stopPropagation()
+  }
+  node.addEventListener('mousedown', onDown, true)
+  node.addEventListener('mouseup', onUp, true)
+  return () => {
+    node.removeEventListener('mousedown', onDown, true)
+    node.removeEventListener('mouseup', onUp, true)
+  }
+}
+
 /** Shift+F12 / 右键「查找所有引用」：走 Monaco 原生 References Peek（两栏引用视图）。 */
 export async function runFindReferences(ed) {
   const position = ed.getPosition()

package/src/client/ui/EditorView.ts

@@ -75,7 +75,7 @@ import { navStateLoad, navStateSave } from '../state/navStateCache.js'
 import { statusOfAdd } from '../addToConversation.js'
 import { setSearchScope, setSearchSeed } from '../searchSeed.js'
 import { CACHE_KEY } from '../paths.js'
-import { runGoToDefinition, runFindReferences, hideReferencesOverlay } from '../monaco/lsp/providers.js'
+import { runGoToDefinition, runFindReferences, hideReferencesOverlay, bindLuaKeyRefs } from '../monaco/lsp/providers.js'
 import { isLuaTypeSlot } from '../monaco/lsp/keywords.js'
 import { bindLspUnderline } from '../monaco/lsp/underline.js'
 import { onLspProgress, refreshStatus, setSession as setLspSession } from '../monaco/lsp/index.js'
@@ -2393,6 +2393,8 @@ export function EditorView(props) {
     // SVN 组按创建时的最新状态注册（此后由 [monaco, svnStatus] effect 随状态增减）
     syncSvnMenuActs(ed)
     bindLspUnderline(ed, m)
+    const unbindLuaKeyRefs = bindLuaKeyRefs(ed, m)
+    ed.onDidDispose(unbindLuaKeyRefs)
     // AI 补全：编辑器实例登记（差异静默判定用）+ Alt+\ 手动触发 ghost text
     trackAiEditor(ed)
     ed.addCommand(m.KeyMod.Alt | m.KeyCode.Backslash, () => {

package/src/lsp/derive.ts

@@ -94,3 +94,160 @@ export function deriveDefinitionFromLocations(
   const first = candidates[0]
   return sameRange(first.range, containing.range) ? containing : first
 }
+
+/** 文本读取回调（服务器提供：已打开文档走内存，其余读盘）。 */
+export interface CrossFileLookup {
+  readText: (uri: string) => Promise<string | null>
+  maxFiles?: number
+}
+
+/** 提取文本开头的标识符链（`EventId.ISTaskSystem = {` → ['EventId','ISTaskSystem']）。 */
+function chainOf(text: string): string[] {
+  const match = /^\s*([A-Za-z_][A-Za-z0-9_]*(?:\s*\.\s*[A-Za-z_][A-Za-z0-9_]*)*)/.exec(text)
+  if (!match) return []
+  return match[1].replace(/\s+/g, '').split('.')
+}
+
+/**
+ * 判定切片文本是否为查询链的声明形候选：链后紧跟单个 '='（name = ... 赋值，排除 '==' 比较），
+ * 且候选链是查询链的段级前缀（外层表声明 `EventId.ISTaskSystem = {`）或末段一致（叶字段声明
+ * `TaskStateChange = 50000,`）。
+ */
+function isDeclarationMatch(word: string, queryChain: string[]): boolean {
+  const match = /^\s*([A-Za-z_][A-Za-z0-9_]*(?:\s*\.\s*[A-Za-z_][A-Za-z0-9_]*)*)\s*(=)(?!=)/.exec(word)
+  if (!match) return false
+  const chain = match[1].replace(/\s+/g, '').split('.')
+  if (!chain.length || chain.length > queryChain.length) return false
+  // 候选是查询链的外层声明（EventId.ISTaskSystem = {）
+  const prefix = queryChain.slice(0, chain.length)
+  if (chain.every((seg, i) => seg === prefix[i])) return true
+  // 候选末段与查询链末段一致（TaskStateChange = 50000 是链叶字段声明）
+  if (chain[chain.length - 1] === queryChain[queryChain.length - 1]) return true
+  return false
+}
+
+/**
+ * 跨文件声明推导（definition/declaration 均空、同文件推导只给出"点击处自身"时的兜底）。
+ * 背景：EmmyLua 0.9.41 对成员链字段（EventId.ISTaskSystem.TaskStateChange）的 definition 恒返回空，
+ * 但 references(includeDeclaration) 在词中/尾位置包含字段声明位置（声明文件内的 `XXX = {...}` /
+ * `KEY = value,` 赋值行）。同文件推导把跨文件声明过滤掉 → 这里放宽到跨文件，
+ * 用"段级相等/前缀/后缀 + 赋值形（单个 '='）"识别声明，并读取目标文件文本做词级校验。
+ * 文件读取有上限（maxFiles），防止大工作区把跳转拖慢。
+ * @author ddj 2026年10月15号
+ * @param queryPos 查询位置（调用方已 nudge 到词尾）
+ * @param locations references(includeDeclaration) 结果
+ * @param docText 当前文档全文（取点击链）
+ * @param docAbsPath 当前文档绝对路径（file:// URI）
+ * @param lookup 文件文本读取器与读取上限
+ * @returns 跨文件声明位置；未识别到返回 null
+ */
+export async function deriveCrossFileDeclaration(
+  queryPos: LspPosition,
+  locations: LspLocation[],
+  docText: string,
+  docAbsPath: string,
+  lookup: CrossFileLookup,
+): Promise<LspLocation | null> {
+  if (!locations.length) return null
+  const docAbs = normAbs(docAbsPath)
+
+  // 点击位置落在的条目（多个时取最小包裹），取其词文本的标识符链作为查询链
+  const containing = locations
+    .filter((loc) => posInLspRange(queryPos, loc.range))
+    .sort((a, b) => rangeSize(a.range) - rangeSize(b.range))[0]
+  if (!containing) return null
+  const queryChain = chainOf(sliceRange(docText, containing.range))
+  if (!queryChain.length) return null
+
+  // 声明候选集中在低列（EventId = {} 在 col0、表字段 `TaskStateChange = 50000,` 在 col4），
+  // 使用点通常在 col10+。按列升序优先读取"声明形"文件，避免 3884 条引用按原序只读到使用文件
+  // 就耗尽 maxFiles。每个文件只读一次，但文件内每个位置都要判定。
+  const maxFiles = lookup.maxFiles ?? 8
+  const textByKey = new Map<string, string | null>()
+  let best: LspLocation | null = null
+  let bestChainLen = Number.POSITIVE_INFINITY
+  const ordered = [...locations].sort((a, b) => {
+    const ca = a.range.start.character - b.range.start.character
+    return ca !== 0 ? ca : a.range.start.line - b.range.start.line
+  })
+  for (const loc of ordered) {
+    const key = normAbs(loc.uri)
+    if (key === docAbs) continue
+    let text = textByKey.get(key)
+    if (text === undefined) {
+      if (textByKey.size >= maxFiles) break
+      text = await lookup.readText(loc.uri)
+      textByKey.set(key, text ?? null)
+    }
+    if (!text) continue
+    // 声明检测需看到标识符后的 `= value`，而引用条目 range 常只覆盖标识符本身
+    // （如 EventId = {} 的 range 是 0:0-0:7，'=' 在 8）。取从 range.start 到行末的文本。
+    const word = sliceToLineEnd(text, loc.range)
+    const chain = chainOf(word)
+    if (chain.length && chain.length <= bestChainLen && isDeclarationMatch(word, queryChain)) {
+      best = loc
+      bestChainLen = chain.length
+      if (bestChainLen === 1) break
+    }
+  }
+  return best
+}
+
+/** 从 range.start 到所在行末的切片（声明形判定需覆盖标识符后的 `= value`）。 */
+function sliceToLineEnd(text: string, range: LspRange): string {
+  const lines = text.split(/\r\n|\r|\n/)
+  const line = lines[Math.max(0, range.start.line)] ?? ''
+  return line.slice(Math.max(0, range.start.character))
+}
+
+/**
+ * 判定"直接 definition 结果是否为同文件误解析（把使用点当定义）"。
+ * 背景：EmmyLua 0.9.41 对跨文件全局（EventId = {} 定义在别的文件）的 textDocument/definition
+ * 常错误返回当前文件最后一个使用点（如 SubHandler:94 的 `{ EventId.NewActivity...`），而非声明文件。
+ * 特征：直接结果全部位于查询文档同文件，且首个结果的切片文本不是点击链的声明形
+ * （local/function 声明或 `链 = ...` 赋值）。命中即应降级走跨文件声明推导。
+ * @author ddj 2026年10月15号
+ * @param docAbsPath 当前文档绝对路径（file:// URI 或绝对路径）
+ * @param locations 直接 definition 结果
+ * @param docText 当前文档全文（取点击链）
+ * @param position 查询位置（调用方已 nudge 到词尾）
+ */
+export function isMisresolvedSameFileUsage(
+  docAbsPath: string,
+  locations: LspLocation[],
+  docText: string,
+  position: LspPosition,
+): boolean {
+  if (!locations.length) return false
+  const docAbs = normAbs(docAbsPath)
+  // 直接结果含跨文件条目 → 正常定义，不疑误
+  if (locations.some((loc) => normAbs(loc.uri) !== docAbs)) return false
+  const chainRange = chainRangeAt(docText, position)
+  if (!chainRange) return false
+  const queryChain = chainOf(sliceRange(docText, chainRange))
+  if (!queryChain.length) return false
+  // 取行末切片，覆盖 local/function 前缀与 `= value`（range 常只覆盖标识符本身）
+  return !isDeclarationForm(sliceToLineEnd(docText, locations[0].range), queryChain)
+}
+
+/** 取 position 处的标识符/成员链 range（0-based，取所在行内的链）。 */
+function chainRangeAt(text: string, pos: LspPosition): LspRange | null {
+  const line = text.split(/\r\n|\r|\n/)[pos.line] ?? ''
+  const re = /[A-Za-z_][A-Za-z0-9_]*(?:\s*\.\s*[A-Za-z_][A-Za-z0-9_]*)*/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(line))) {
+    const start = m.index
+    const end = start + m[0].length
+    if (pos.character >= start && pos.character < end) {
+      return { start: { line: pos.line, character: start }, end: { line: pos.line, character: end } }
+    }
+  }
+  return null
+}
+
+/** 切片文本是否为查询链的"声明形"（local/function 声明或 `链 = ...` 赋值）。 */
+function isDeclarationForm(word: string, queryChain: string[]): boolean {
+  const t = word.replace(/^\s+/, '')
+  if (/^(local\b|function\b)/.test(t)) return true
+  return isDeclarationMatch(word, queryChain)
+}

package/src/lsp/server.ts

@@ -6,8 +6,9 @@
  */
 import { spawnServer, type Transport } from './transport.js'
 import { createLspClient, type LspClient } from './client.js'
-import { pathToFileUri, toWorkspacePath, isAbsolutePath } from './uri.js'
-import { deriveDefinitionFromLocations } from './derive.js'
+import { pathToFileUri, toWorkspacePath, isAbsolutePath, fileUriToPath } from './uri.js'
+import { deriveDefinitionFromLocations, deriveCrossFileDeclaration, isMisresolvedSameFileUsage } from './derive.js'
+import { readFile } from 'node:fs/promises'
 import type { LspProviderSpec } from './providers.js'
 import { LSP_SEMANTIC_TOKEN_MODIFIERS, LSP_SEMANTIC_TOKEN_TYPES } from '../shared/lsp.js'
 import type {
@@ -16,6 +17,7 @@ import type {
   LspCompletionTextEdit,
   LspLocation,
   LspParameterInformation,
+  LspPosition,
   LspRange,
   LspSemanticTokens,
   LspServerCapabilities,
@@ -71,6 +73,73 @@ export function lspDocVersion(incoming: number, previous?: number): number {
   return Number.isInteger(incoming) && incoming >= next && incoming <= MAX_DOC_VERSION ? incoming : next
 }
 
+/**
+ * 把查询位置挪到光标所在 Lua 标识符词的末尾字符。
+ *
+ * 背景：EmmyLua 0.9.41 存在词边界怪癖——查询位置落在标识符 token 前半时，definition/hover/references
+ * 一律返回空 / "unknown" / []，落在 token 后半/末尾才正常解析（已对 EventId/ISTaskSystem/
+ * TaskStateChange 逐字符实测确认）。把位置挪到词尾即可让基标识符（如 `EventId`）正常解析。
+ * 仅当位置严格落在标识符词内时才挪；点号/空白/字符串/注释位置原样返回，不影响正常符号。
+ * @author ddj 2026年10月15号
+ * @param text 文档全文
+ * @param pos 查询位置（0-based）
+ * @returns 词末字符位置；不在词内则原样返回
+ */
+export function nudgeToWordEnd(text: string, pos: LspPosition): LspPosition {
+  const lines = text.split(/\r\n|\r|\n/)
+  const line = lines[pos.line]
+  if (line === undefined) return pos
+  const identifier = /[A-Za-z_][A-Za-z0-9_]*/g
+  let match: RegExpExecArray | null
+  while ((match = identifier.exec(line)) !== null) {
+    const start = match.index
+    const end = start + match[0].length
+    if (pos.character >= start && pos.character < end) {
+      return { line: pos.line, character: end - 1 }
+    }
+    if (pos.character < start) break
+  }
+  return pos
+}
+
+/** hover 内容是否"空/unknown"（EmmyLua 对未解析符号、成员链字段 hover 的原生输出）。 */
+function isEmptyHover(contents: string[]): boolean {
+  return contents.every((c) => {
+    const t = c.trim()
+    return !t || t === 'unknown'
+  })
+}
+
+/**
+ * 取光标所在成员链的基标识符范围（`EventId.ISTaskSystem.TaskStateChange` → `EventId`）。
+ * 链中无成员访问（无 '.'）时返回 null——基标识符回查无意义。
+ */
+function chainBaseRange(line: string, character: number): { start: number; end: number } | null {
+  const chain = /[A-Za-z_][A-Za-z0-9_]*(?:\s*\.\s*[A-Za-z_][A-Za-z0-9_]*)*/g
+  let match: RegExpExecArray | null
+  while ((match = chain.exec(line)) !== null) {
+    const start = match.index
+    const end = start + match[0].length
+    if (character >= start && character < end) {
+      const dot = match[0].indexOf('.')
+      if (dot === -1) return null
+      return { start, end: start + dot }
+    }
+    if (character < start) break
+  }
+  return null
+}
+
+/** LSP position 是否落在 range 内（start 包含、end 排除）。 */
+function rangeContains(pos: LspPosition, range: LspRange): boolean {
+  const start = range.start
+  const end = range.end ?? start
+  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
+}
+
 /**
  * 创建语言服务器会话。
  * @author ddj 2026年08月27号
@@ -98,6 +167,23 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
     const rel = toWorkspacePath(root, path)
     return isAbsolutePath(rel) ? pathToFileUri(rel) : pathToFileUri(root + '/' + rel.split('/').join('/'))
   }
+
+  /**
+   * 按 file:// URI 读取文件文本：已打开文档走内存（与语言服务器索引一致），其余读盘。
+   * @author ddj 2026年10月15号
+   * @param uri 目标文件 file:// URI
+   * @returns 文件文本；读取失败（文件不存在/非 UTF-8 等）返回 null
+   */
+  const readTextByUri = async (uri: string): Promise<string | null> => {
+    for (const doc of docs.values()) {
+      if (doc.uri === uri) return doc.text
+    }
+    try {
+      return await readFile(fileUriToPath(uri), 'utf8')
+    } catch {
+      return null
+    }
+  }
   let phase: LspServerPhase = 'idle'
   let transport: Transport | null = null
   let client: LspClient | null = null
@@ -283,7 +369,27 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
       const doc = docs.get(path)
       if (!doc || !(await readyWait)) return []
       const client = ensureClient()
-      const position = { line, character }
+      // EmmyLua 词边界怪癖：位置在标识符前半返回空，nudge 到词尾后基标识符可正常解析
+      const position = nudgeToWordEnd(doc.text, { line, character })
+      // 跨文件声明推导（references + 词级校验），两处复用
+      const crossFromRefs = async (): Promise<LspLocation | null> => {
+        try {
+          const refs = normalizeLocations(
+            await client.request<unknown>(
+              'textDocument/references',
+              {
+                textDocument: { uri: doc.uri },
+                position,
+                context: { includeDeclaration: true },
+              },
+            ),
+          )
+          return await deriveCrossFileDeclaration(position, refs, doc.text, doc.uri, { readText: readTextByUri })
+        } catch (error) {
+          log('references fallback failed: ' + String(error))
+          return null
+        }
+      }
       // ① 标准定义（方法/跨文件命名空间等）
       const direct = normalizeLocations(
         await client.request<unknown>(
@@ -291,7 +397,19 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
           { textDocument: { uri: doc.uri }, position },
         ),
       )
-      if (direct.length) return direct
+      if (direct.length) {
+        // EmmyLua 0.9.41 对跨文件全局（EventId = {} 定义在别的文件）的 definition 常错误返回
+        // 当前文件最后一个使用点（同文件非声明形）。识别到误解析时降级走跨文件声明推导。
+        const mis = isMisresolvedSameFileUsage(doc.uri, direct, doc.text, position)
+        if (mis) {
+          const cross = await crossFromRefs()
+          if (cross) {
+            log('definition direct was same-file misresolution → cross-file declaration (' + path + ':' + line + ':' + character + ')')
+            return [cross]
+          }
+        }
+        return direct
+      }
       // ② 声明（服务器能力支持时）：EmmyLua 对局部变量/参数/表字段 definition 常返回空，declaration 更准
       if (capabilities.declaration) {
         try {
@@ -323,10 +441,23 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
           ),
         )
         const derived = deriveDefinitionFromLocations(position, refs, doc.text, doc.uri)
-        if (derived) {
+        // derived 为"点击处自身"（字段定义缺失空转）或"同文件非声明形使用点"（把 EventId 用
+        // 点当定义）时都不直接信任 → 先找跨文件声明；二者皆非才直接用同文件推导结果。
+        const selfDerived = derived ? rangeContains(position, derived.range) : false
+        const misDerived = derived ? isMisresolvedSameFileUsage(doc.uri, [derived], doc.text, position) : false
+        if (derived && !selfDerived && !misDerived) {
           log('definition fallback → references-derived (' + path + ':' + line + ':' + character + ')')
           return [derived]
         }
+        const cross = await deriveCrossFileDeclaration(position, refs, doc.text, doc.uri, { readText: readTextByUri })
+        if (cross) {
+          log('definition fallback → cross-file declaration (' + path + ':' + line + ':' + character + ')')
+          return [cross]
+        }
+        if (derived) {
+          // 点中的正是声明自身，或引用里没有可识别的跨文件声明 → 返回自身/同文件结果（无更优目标）
+          return [derived]
+        }
       } catch (error) {
         log('references fallback failed: ' + String(error))
       }
@@ -336,11 +467,12 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
     async references(path: string, line: number, character: number, includeDeclaration: boolean): Promise<LspLocation[]> {
       const doc = docs.get(path)
       if (!doc || !(await readyWait)) return []
+      const position = nudgeToWordEnd(doc.text, { line, character })
       const result = await ensureClient().request<unknown>(
         'textDocument/references',
         {
           textDocument: { uri: doc.uri },
-          position: { line, character },
+          position,
           context: { includeDeclaration },
         },
       )
@@ -365,12 +497,29 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
     async hover(path: string, line: number, character: number): Promise<{ contents: string[] } | null> {
       const doc = docs.get(path)
       if (!doc || !(await readyWait)) return null
-      const result = await ensureClient().request<{ contents?: unknown; range?: unknown } | null>(
+      const client = ensureClient()
+      // EmmyLua 词边界怪癖：位置在标识符前半 hover 返回 "unknown"，nudge 到词尾可正常解析
+      const position = nudgeToWordEnd(doc.text, { line, character })
+      const result = await client.request<{ contents?: unknown; range?: unknown } | null>(
         'textDocument/hover',
-        { textDocument: { uri: doc.uri }, position: { line, character } },
+        { textDocument: { uri: doc.uri }, position },
       )
-      if (!result || !result.contents) return null
-      return { contents: stringifyHoverContents(result.contents) }
+      const contents = result?.contents ? stringifyHoverContents(result.contents) : []
+      // EmmyLua 对成员链字段（EventId.ISTaskSystem.TaskStateChange）hover 恒 "unknown"：
+      // 退回查询基标识符（EventId），显示其类型而非无信息文本
+      if (isEmptyHover(contents)) {
+        const lines = doc.text.split(/\r\n|\r|\n/)
+        const base = chainBaseRange(lines[position.line] ?? '', position.character)
+        if (base) {
+          const baseResult = await client.request<{ contents?: unknown } | null>(
+            'textDocument/hover',
+            { textDocument: { uri: doc.uri }, position: { line: position.line, character: base.end - 1 } },
+          )
+          const baseContents = baseResult?.contents ? stringifyHoverContents(baseResult.contents) : []
+          if (!isEmptyHover(baseContents)) return { contents: baseContents }
+        }
+      }
+      return contents.length ? { contents } : null
     },
 
     /**