dsh-vscode-mode 0.1.36 → 0.1.43

package/src/lsp/providers.ts

@@ -5,12 +5,12 @@
  * 供 manager 启动服务器。
  * 作者 ddj 2026-08-27
  */
-import { existsSync, readdirSync, type Dirent } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync, type Dirent } from 'node:fs'
 import { homedir } from 'node:os'
-import { join, sep } from 'node:path'
+import { dirname, join, sep } from 'node:path'
 import { isAbsolute } from 'node:path'
 import { extensionsRoot } from './extmgr.js'
-import { dshHome } from '../paths.js'
+import { dshHome, lspSpecCacheFile } from '../paths.js'
 
 /** provider 来源标记（与 shared/lsp.ts 的 status.source 一致）。 */
 export type LspProviderKind = 'extension' | 'discover' | 'manual' | 'none'
@@ -22,6 +22,8 @@ export interface LspProviderSpec {
   cwd?: string
   ready: boolean
   reason?: string
+  version?: string
+  providerName?: string
 }
 
 /** 语言 → 扩展名（用于判断哪些文件触发该语言服务器）。 */
@@ -88,7 +90,7 @@ export function registerExtensionProvider(languageId: string, argv: string[], cw
 export function extensionProviderFor(languageId: string): LspProviderSpec | null {
   const p = extProviders.get(languageId)
   if (!p || !p.argv.length) return null
-  return { languageId, kind: 'extension', argv: p.argv, cwd: p.cwd, ready: true }
+  return { languageId, kind: 'extension', argv: p.argv, cwd: p.cwd, ready: true, version: p.version, providerName: p.version ? 'EmmyLua' : '语言服务器扩展' }
 }
 
 /** 清空全部扩展源注册（插件卸载/扩展目录重建时）。 */
@@ -123,6 +125,25 @@ export function findDotnet(): string | null {
   return null
 }
 
+/** EmmyLua 自动发现候选（tangzx.emmylua-* / server/emmylua_ls）。 */
+export function candidateEmmyLua(home = dshHome()): { path: string; version?: string } | null {
+  const candidates: { path: string; version?: string }[] = []
+  for (const dir of vscodeExtensionsDirs(home)) {
+    for (const extDir of listMatchingDirs(dir, 'tangzx.emmylua-')) {
+      const server = join(extDir, 'server', 'emmylua_ls' + exeSuffix())
+      if (!existsSync(server)) continue
+      let version: string | undefined
+      try {
+        const manifest = JSON.parse(readFileSync(join(extDir, 'package.json'), 'utf8')) as { version?: unknown }
+        if (typeof manifest.version === 'string') version = manifest.version
+      } catch (error) { /* 清单读取失败不影响入口使用 */ }
+      candidates.push({ path: server, version })
+    }
+  }
+  candidates.sort((a, b) => (b.version ?? '').localeCompare(a.version ?? '', undefined, { numeric: true }) || a.path.localeCompare(b.path))
+  return candidates[0] ?? null
+}
+
 /** LuaLS 自动发现候选（VSCode 扩展目录 + extmgr 目录下 sumneko.lua-* 的 server/bin 可执行）。 */
 export function candidateLuaServers(home = dshHome()): string[] {
   const plat = platformServerDir()
@@ -186,13 +207,17 @@ export function resolveLuaProvider(manual?: { command?: string; path?: string },
   const base = { languageId: 'lua' }
   const manualResolved = manualSpec(manual)
   if (manualResolved.ready) return { ...base, kind: 'manual', argv: manualResolved.argv, cwd: manualResolved.cwd, ready: true }
-  const ext = extensionProviderFor('lua')
-  if (ext) return ext
-  const candidates = candidateLuaServers(home)
-  if (candidates.length) return { ...base, kind: 'discover', argv: [candidates[0]], cwd: undefined, ready: true }
-  const inPath = findInPath('lua-language-server' + exeSuffix())
-  if (inPath) return { ...base, kind: 'discover', argv: [inPath], ready: true }
-  return { ...base, kind: 'none', argv: [], ready: false, reason: manualResolved.reason ?? '未发现 lua-language-server（可安装 LuaLS 或手动指定路径）' }
+  return resolveCached('lua', manual, home, (h) => {
+    const ext = extensionProviderFor('lua')
+    if (ext) return ext
+    const emmy = candidateEmmyLua(h)
+    if (emmy) return { ...base, kind: 'extension', argv: [emmy.path], ready: true, version: emmy.version, providerName: 'EmmyLua' }
+    const candidates = candidateLuaServers(h)
+    if (candidates.length) return { ...base, kind: 'discover', argv: [candidates[0]], cwd: undefined, ready: true }
+    const inPath = findInPath('lua-language-server' + exeSuffix())
+    if (inPath) return { ...base, kind: 'discover', argv: [inPath], ready: true }
+    return { ...base, kind: 'none', argv: [], ready: false, reason: manualResolved.reason ?? '未发现 lua-language-server（可安装 LuaLS 或手动指定路径）' }
+  })
 }
 
 /**
@@ -206,19 +231,21 @@ export function resolveCSharpProvider(manual?: { command?: string; path?: string
   const base = { languageId: 'csharp' }
   const manualResolved = manualSpec(manual)
   if (manualResolved.ready) return { ...base, kind: 'manual', argv: manualResolved.argv, cwd: manualResolved.cwd, ready: true }
-  const ext = extensionProviderFor('csharp')
-  if (ext) return ext
-  const discovered = candidateCSharpServers(home)
-  if (discovered.roslynDll && discovered.dotnet) {
-    return { ...base, kind: 'discover', argv: [discovered.dotnet, discovered.roslynDll, '--stdio'], ready: true }
-  }
-  if (discovered.omnisharpExe) {
-    return { ...base, kind: 'discover', argv: [discovered.omnisharpExe, '--stdio'], ready: true }
-  }
-  const reasons: string[] = []
-  if (!discovered.dotnet) reasons.push('未找到 dotnet')
-  if (!discovered.roslynDll && !discovered.omnisharpExe) reasons.push('未发现 ms-dotnettools.csharp 扩展')
-  return { ...base, kind: 'none', argv: [], ready: false, reason: reasons.join('；') + '（可手动指定 Roslyn/OmniSharp 入口）' }
+  return resolveCached('csharp', manual, home, (h) => {
+    const ext = extensionProviderFor('csharp')
+    if (ext) return ext
+    const discovered = candidateCSharpServers(h)
+    if (discovered.roslynDll && discovered.dotnet) {
+      return { ...base, kind: 'discover', argv: [discovered.dotnet, discovered.roslynDll, '--stdio'], ready: true }
+    }
+    if (discovered.omnisharpExe) {
+      return { ...base, kind: 'discover', argv: [discovered.omnisharpExe, '--stdio'], ready: true }
+    }
+    const reasons: string[] = []
+    if (!discovered.dotnet) reasons.push('未找到 dotnet')
+    if (!discovered.roslynDll && !discovered.omnisharpExe) reasons.push('未发现 ms-dotnettools.csharp 扩展')
+    return { ...base, kind: 'none', argv: [], ready: false, reason: reasons.join('；') + '（可手动指定 Roslyn/OmniSharp 入口）' }
+  })
 }
 
 /** 语言 → provider 解析器（可扩展；Phase 2 由 extmgr 注册扩展源 provider）。 */
@@ -233,3 +260,155 @@ export const PROVIDER_RESOLVERS: Record<string, ProviderResolver> = {
 export function looksAbsolute(value: string): boolean {
   return isAbsolute(value)
 }
+
+// --region provider 发现结果缓存（进程级 + 磁盘持久化）
+/**
+ * 发现结果缓存：只缓存"自动发现/扩展源"结论，不缓存 manual（用户改配置要立即生效）。
+ * 进程内 Map 命中优先；未命中读磁盘缓存（跨会话/跨重启共享）；仍无才真扫描。
+ * 缓存条目按"配置签名 + 扩展目录指纹"校验，任一变化即失效重扫。
+ * 作者 ddj 2026年08月28号
+ */
+
+/** 缓存条目：spec + 生成时的环境指纹。 */
+interface SpecCacheEntry {
+  spec: LspProviderSpec
+  fingerprint: string
+  at: number
+}
+
+/** 进程级缓存（home|languageId → 条目），同一 DSH home 的不同会话共享。 */
+const specCache = new Map<string, SpecCacheEntry>()
+/** 磁盘缓存是否已载入本进程（home → loaded），不同 profile 不串缓存。 */
+const diskLoaded = new Set<string>()
+/** 自动发现成功结果的复用时长；过期后才检查目录指纹。 */
+const SPEC_CACHE_TTL_MS = 30 * 60 * 1000
+/** 未发现结果的短缓存时长，避免缺失服务器时反复扫描 PATH。 */
+const SPEC_NEGATIVE_CACHE_MS = 60 * 1000
+
+/** 生成带 home 的缓存键，避免不同 profile 的 provider 结果串用。 */
+function cacheEntryKey(home: string, languageId: string): string {
+  return home + '|' + languageId
+}
+
+/**
+ * 构造缓存 key：语言 + 手动配置（manual 结果不缓存，故只参与"是否走缓存"判定）。
+ * @author ddj 2026年08月28号
+ * @param languageId 语言 id
+ * @param manual 手动配置
+ * @returns 缓存 key（manual 有效时返回空串表示跳过缓存）
+ */
+function cacheKeyOf(languageId: string, manual?: { command?: string; path?: string }): string {
+  const pathValue = manual?.path?.trim() ?? ''
+  const commandValue = manual?.command?.trim() ?? ''
+  if (pathValue || commandValue) return '' // 手动配置：不缓存，立即生效
+  return languageId
+}
+
+/**
+ * 环境指纹：扩展目录清单 + 平台。目录增删/换平台即失效（防缓存陈旧指向已删扩展）。
+ * @author ddj 2026年08月28号
+ * @param home DSH home
+ * @returns 指纹串
+ */
+function fingerprintOf(home: string): string {
+  const dirs = vscodeExtensionsDirs(home)
+  const marks = dirs.map((dir) => {
+    try {
+      return readdirSync(dir).sort().join(',')
+    } catch (error) {
+      return '?'
+    }
+  })
+  return process.platform + '|' + marks.join('|')
+}
+
+/**
+ * 读取磁盘缓存（幂等：每进程只载一次；schema 文件名已隔离版本）。
+ * @author ddj 2026年08月28号
+ * @param home DSH home
+ */
+function loadDiskCache(home: string): void {
+  if (diskLoaded.has(home)) return
+  diskLoaded.add(home)
+  const file = lspSpecCacheFile(home)
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf8')) as Record<string, SpecCacheEntry>
+    for (const [languageId, entry] of Object.entries(raw)) {
+      if (entry && typeof entry === 'object' && entry.spec && typeof entry.fingerprint === 'string') {
+        specCache.set(cacheEntryKey(home, languageId), entry)
+      }
+    }
+  } catch (error) { /* 首次运行/损坏：静默降级为真扫描 */ }
+}
+
+/**
+ * 写回磁盘缓存（best-effort；写失败不影响本次解析结果）。
+ * @author ddj 2026年08月28号
+ * @param home DSH home
+ */
+function saveDiskCache(home: string): void {
+  const file = lspSpecCacheFile(home)
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    const out: Record<string, SpecCacheEntry> = {}
+    const prefix = home + '|'
+    for (const [key, entry] of specCache) if (key.startsWith(prefix)) out[key.slice(prefix.length)] = entry
+    writeFileSync(file, JSON.stringify(out), 'utf8')
+  } catch (error) { /* 写入失败静默 */ }
+}
+
+/**
+ * 带缓存执行 provider 解析（自动发现路径专用）。
+ * @author ddj 2026年08月28号
+ * @param languageId 语言 id
+ * @param manual 手动配置
+ * @param home DSH home
+ * @param resolve 真解析函数（未命中时调用）
+ * @returns provider 规格
+ */
+function resolveCached(
+  languageId: string,
+  manual: { command?: string; path?: string } | undefined,
+  home: string,
+  resolve: (h: string) => LspProviderSpec,
+): LspProviderSpec {
+  const key = cacheKeyOf(languageId, manual)
+  if (!key) return resolve(home) // 手动配置：不走缓存
+  loadDiskCache(home)
+  const fullKey = cacheEntryKey(home, key)
+  const hit = specCache.get(fullKey)
+  if (hit && isCacheFresh(hit)) return hit.spec
+  const fingerprint = fingerprintOf(home)
+  if (hit && hit.fingerprint === fingerprint) {
+    hit.at = Date.now()
+    return hit.spec
+  }
+  const spec = resolve(home)
+  specCache.set(fullKey, { spec, fingerprint, at: Date.now() })
+  saveDiskCache(home)
+  return spec
+}
+
+/** 判断缓存条目是否仍可直接复用，不触发扩展目录扫描。 */
+function isCacheFresh(entry: SpecCacheEntry): boolean {
+  const age = Date.now() - entry.at
+  const ttl = entry.spec.kind === 'none' ? SPEC_NEGATIVE_CACHE_MS : SPEC_CACHE_TTL_MS
+  if (age < 0 || age >= ttl) return false
+  const executable = entry.spec.argv[0]
+  return !entry.spec.ready || !executable || existsSync(executable)
+}
+
+/**
+ * 清空 provider 发现缓存（扩展安装/卸载、配置变更后调用；进程级 + 删磁盘文件）。
+ * @author ddj 2026年08月28号
+ * @param home DSH home（缺省真实）
+ */
+export function clearProviderCache(home = dshHome()): void {
+  const prefix = home + '|'
+  for (const key of specCache.keys()) if (key.startsWith(prefix)) specCache.delete(key)
+  diskLoaded.delete(home)
+  try {
+    rmSync(lspSpecCacheFile(home), { force: true })
+  } catch (error) { /* 删除失败静默 */ }
+}
+// --endregion

package/src/lsp/rpc.ts

@@ -6,10 +6,11 @@
 import type { Ctx } from '../store.js'
 import { searchRoot } from '../search/ripgrep.js'
 import { sessionOf, cwdOf } from '../registry.js'
-import { resolveProviderSpec, langOfPath, configFromPlugin, configFromSettings, LSP_SETTINGS_NS, type LspConfig } from './config.js'
+import { resolveProviderSpec, langOfPath, configFromPlugin, configFromSettings, LSP_LANGUAGES, LSP_SETTINGS_NS, type LspConfig } from './config.js'
+import { clearProviderCache } from './providers.js'
 import type { LspManager } from './manager.js'
 import type { RpcHandlerMap } from '../shared/rpc.js'
-import type { LspLocation } from '../shared/lsp.js'
+import type { LspLocation, LspServerStatus } from '../shared/lsp.js'
 import { installFromMarket, installVsixFile, listInstalled, marketGet, marketSearch, uninstall, updateExtension, type ExtInfo } from './extmgr.js'
 
 export interface LspRpcDeps {
@@ -85,6 +86,21 @@ function createDocTracker() {
       sessionDocs.delete(sessionId)
       return [...toRelease]
     },
+    /** 清除指定语言的文档归属，让当前客户端重新同步时重新 acquire。 */
+    resetLanguage(languageId: string): void {
+      for (const [docKey, owners] of openDocs) {
+        if (!docKey.includes('|' + languageId + '|')) continue
+        for (const sessionId of owners) forgetDoc(sessionId, docKey)
+        openDocs.delete(docKey)
+      }
+      for (const key of [...rootLangRefs.keys()]) if (key.endsWith('|' + languageId)) rootLangRefs.delete(key)
+    },
+    /** 返回指定会话已打开的文档路径，用于重检测后恢复同步。 */
+    pathsFor(sessionId: string, languageId: string): string[] {
+      const docs = sessionDocs.get(sessionId)
+      if (!docs) return []
+      return [...docs].filter((key) => key.includes('|' + languageId + '|')).map((key) => key.slice(key.lastIndexOf('|') + 1))
+    },
   }
 }
 
@@ -122,6 +138,41 @@ export function createLspRpc(deps: LspRpcDeps): { handlers: Partial<RpcHandlerMa
   const rootLocations = (locations: LspLocation[], root: string): LspLocation[] =>
     locations.map((location) => ({ ...location, root }))
 
+  /** 当前 provider 检测结论 → 设置页 idle 状态（不启动 server）。 */
+  const detectedStatus = (languageId: string, root?: string): LspServerStatus => {
+    const spec = resolveProviderSpec(ctx, pluginConfig, languageId)
+    return {
+      languageId,
+      source: spec.kind,
+      phase: 'idle',
+      reason: spec.ready ? undefined : spec.reason,
+      version: spec.version,
+      providerName: spec.providerName,
+      root,
+    }
+  }
+
+  /**
+   * 清发现缓存并重置旧 server（保留 tracker 文档记录）；
+   * 下一次模型同步会按最新配置重新 acquire，已打开文档无需重开。
+   * 作者 ddj 2026年09月02号
+   * @param languageId 语言 id
+   * @param sessionId 会话语境（缺省重置全部工作区该语言）
+   * @returns 检测后的 idle 状态列表
+   */
+  const redetectLanguage = async (languageId: string, sessionId?: string): Promise<LspServerStatus[]> => {
+    clearProviderCache()
+    if (sessionId) {
+      const sc = await rootOf(sessionId)
+      if ('err' in sc) return []
+      manager.reset(sc.root, languageId)
+      return [detectedStatus(languageId, sc.root)]
+    }
+    const roots = [...new Set(manager.statusAll().filter((s) => s.languageId === languageId).map((s) => s.root))]
+    manager.resetLanguage(languageId)
+    return roots.length ? roots.map((root) => detectedStatus(languageId, root)) : [detectedStatus(languageId)]
+  }
+
   const disposeSession = (sessionId: string): void => {
     for (const rl of tracker.closeSession(sessionId)) {
       const sep = rl.lastIndexOf('|')
@@ -160,10 +211,12 @@ export function createLspRpc(deps: LspRpcDeps): { handlers: Partial<RpcHandlerMa
         const settings = ctx.get('settings')
         if (!settings?.update) return { ok: false, error: '设置服务不可用' }
         await settings.update(LSP_SETTINGS_NS, { [lang]: target })
+        // 保存/切换后立即重新检测：清缓存 + 重置旧 server，旧状态不残留
+        const servers = await redetectLanguage(lang)
         const descriptor = settings.describe?.({ redactSecrets: true })?.find((item: { ns?: string }) => item.ns === LSP_SETTINGS_NS)
         const stored = descriptor?.value as Record<string, unknown> | undefined
         const merged: LspConfig = { ...configFromPlugin(pluginConfig), ...(stored as LspConfig) }
-        return { ok: true, config: merged as unknown as Record<string, unknown> }
+        return { ok: true, config: merged as unknown as Record<string, unknown>, servers }
       } catch (error) {
         return { ok: false, error: '配置保存失败：' + String(error) }
       }
@@ -274,6 +327,31 @@ export function createLspRpc(deps: LspRpcDeps): { handlers: Partial<RpcHandlerMa
       }
     },
 
+    'edrv.lsp.semanticTokens': async (args) => {
+      const lang = langOfPath(args.path)
+      if (!lang) return { ok: true, tokens: undefined }
+      const sc = await rootOf(args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      try {
+        const server = serverOf(sc.root, lang)
+        if (!server) return { ok: true, tokens: undefined }
+        return { ok: true, tokens: (await server.semanticTokens(args.path)) ?? undefined }
+      } catch (error) {
+        return { ok: false, error: 'LSP 语义分色查询失败：' + String(error) }
+      }
+    },
+
+    'edrv.lsp.redetect': async (args) => {
+      if (!(LSP_LANGUAGES as readonly string[]).includes(args.languageId)) {
+        return { ok: false, error: '不支持的语言：' + args.languageId }
+      }
+      try {
+        return { ok: true, servers: await redetectLanguage(args.languageId) }
+      } catch (error) {
+        return { ok: false, error: '重新检测失败：' + String(error) }
+      }
+    },
+
     // --region 扩展管理（edrv.lsp.ext.*：已装/市场/安装/卸载/更新）
     'edrv.lsp.ext.list': async () => ({ ok: true, extensions: listInstalled() }),
 
@@ -292,6 +370,7 @@ export function createLspRpc(deps: LspRpcDeps): { handlers: Partial<RpcHandlerMa
         if (args.vsixPath) info = await installVsixFile(args.vsixPath)
         else if (args.namespace && args.name) info = await installFromMarket(args.namespace, args.name, args.version)
         else return { ok: false, error: '缺少安装源（vsixPath 或 namespace+name）' }
+        clearProviderCache() // 新扩展可能成为 Lua provider，立即丢弃旧发现结果
         return { ok: true, extension: info }
       } catch (error) {
         return { ok: false, error: '安装失败：' + String(error) }
@@ -299,7 +378,9 @@ export function createLspRpc(deps: LspRpcDeps): { handlers: Partial<RpcHandlerMa
     },
 
     'edrv.lsp.ext.uninstall': async (args) => {
-      return uninstall(args.id) ? { ok: true } : { ok: false, error: '扩展未安装：' + args.id }
+      const ok = uninstall(args.id)
+      if (ok) clearProviderCache()
+      return ok ? { ok: true } : { ok: false, error: '扩展未安装：' + args.id }
     },
 
     'edrv.lsp.ext.update': async (args) => {
@@ -309,6 +390,7 @@ export function createLspRpc(deps: LspRpcDeps): { handlers: Partial<RpcHandlerMa
           const current = listInstalled().find((e) => e.id === args.id)
           return current ? { ok: true, extension: current, updated: false } : { ok: false, error: '扩展未安装：' + args.id }
         }
+        clearProviderCache()
         return { ok: true, extension: updated, updated: true }
       } catch (error) {
         return { ok: false, error: '更新失败：' + String(error) }

package/src/lsp/server.ts

@@ -8,8 +8,10 @@ import { spawnServer, type Transport } from './transport.js'
 import { createLspClient, type LspClient } from './client.js'
 import { pathToFileUri } from './uri.js'
 import type { LspProviderSpec } from './providers.js'
+import { LSP_SEMANTIC_TOKEN_MODIFIERS, LSP_SEMANTIC_TOKEN_TYPES } from '../shared/lsp.js'
 import type {
   LspLocation,
+  LspSemanticTokens,
   LspServerCapabilities,
   LspServerPhase,
   LspServerStatus,
@@ -31,6 +33,7 @@ export interface LspServer {
   documentSymbol(path: string): Promise<LspSymbol[]>
   workspaceSymbol(query: string): Promise<LspSymbol[]>
   hover(path: string, line: number, character: number): Promise<{ contents: string[] } | null>
+  semanticTokens(path: string): Promise<LspSemanticTokens | null>
   dispose(): Promise<void>
 }
 
@@ -59,18 +62,39 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
   let phase: LspServerPhase = 'idle'
   let transport: Transport | null = null
   let client: LspClient | null = null
-  let capabilities: LspServerCapabilities = { definition: false, references: false, documentSymbol: false, workspaceSymbol: false, hover: false }
+  let capabilities: LspServerCapabilities = {
+    definition: false,
+    references: false,
+    documentSymbol: false,
+    workspaceSymbol: false,
+    hover: false,
+    semanticTokens: false,
+    semanticTokenTypes: [...LSP_SEMANTIC_TOKEN_TYPES],
+    semanticTokenModifiers: [...LSP_SEMANTIC_TOKEN_MODIFIERS],
+  }
   let disposed = false
   let readyWait: Promise<boolean> = Promise.resolve(false)
   let resolveReady: ((ready: boolean) => void) | null = null
   let lastProgress: { value?: number; message?: string } = {}
-  let lastStatus: LspServerStatus = { languageId, source: spec.kind, phase: 'idle', reason: spec.ready ? undefined : spec.reason, root }
+  let lastStatus: LspServerStatus = {
+    languageId,
+    source: spec.kind,
+    phase: 'idle',
+    reason: spec.ready ? undefined : spec.reason,
+    root,
+    version: spec.version,
+    providerName: spec.providerName ?? (spec.version ? '语言服务器扩展' : undefined),
+  }
 
   const log = (line: string): void => logger?.('[' + languageId + '@' + root + '] ' + line)
+  const providerInfo = {
+    version: spec.version,
+    providerName: spec.providerName ?? (spec.version ? 'EmmyLua' : undefined),
+  }
 
   const setPhase = (next: LspServerPhase, reason?: string): void => {
     phase = next
-    lastStatus = { languageId, source: spec.kind, phase: next, reason, root, ...progressFields() }
+    lastStatus = { languageId, source: spec.kind, phase: next, reason, root, ...providerInfo, ...progressFields() }
     server.onStateChange?.(lastStatus)
   }
 
@@ -254,6 +278,25 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
       return { contents: stringifyHoverContents(result.contents) }
     },
 
+    /** 查询全文 semantic tokens，并将服务器 legend 归一到插件固定 legend。 */
+    async semanticTokens(path: string): Promise<LspSemanticTokens | null> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait) || !capabilities.semanticTokens) return null
+      const result = await ensureClient().request<{ data?: unknown; resultId?: unknown } | null>(
+        'textDocument/semanticTokens/full',
+        { textDocument: { uri: doc.uri } },
+      )
+      if (!result || !Array.isArray(result.data)) return null
+      return {
+        data: normalizeSemanticData(
+          result.data,
+          capabilities.semanticTokenTypes ?? [],
+          capabilities.semanticTokenModifiers ?? [],
+        ),
+        resultId: typeof result.resultId === 'string' ? result.resultId : undefined,
+      }
+    },
+
     async dispose(): Promise<void> {
       disposed = true
       resolveReady?.(false)
@@ -344,3 +387,37 @@ function toInt(value: unknown): number {
   const n = Number(value)
   return Number.isFinite(n) ? Math.max(0, Math.floor(n)) : 0
 }
+
+/** 把服务器 legend 下的 5 元组流转换为插件固定 legend 下的 5 元组流。 */
+function normalizeSemanticData(data: unknown[], types: string[], modifiers: string[]): number[] {
+  const out: number[] = []
+  let previousLine = 0
+  let previousCharacter = 0
+  let outputLine = 0
+  let outputCharacter = 0
+  for (let i = 0; i + 4 < data.length; i += 5) {
+    const deltaLine = toInt(data[i])
+    const deltaCharacter = toInt(data[i + 1])
+    const length = toInt(data[i + 2])
+    const sourceType = types[toInt(data[i + 3])] ?? 'variable'
+    const sourceModifiers = toInt(data[i + 4])
+    const line = previousLine + deltaLine
+    const character = deltaLine === 0 ? previousCharacter + deltaCharacter : deltaCharacter
+    const typeIndex = Math.max(0, LSP_SEMANTIC_TOKEN_TYPES.indexOf(sourceType as never))
+    let modifierBits = 0
+    for (let bit = 0; bit < modifiers.length; bit++) {
+      if ((sourceModifiers & (1 << bit)) === 0) continue
+      const modifier = modifiers[bit]
+      const targetBit = LSP_SEMANTIC_TOKEN_MODIFIERS.indexOf(modifier as never)
+      if (targetBit >= 0) modifierBits |= 1 << targetBit
+    }
+    const outputDeltaLine = line - outputLine
+    const outputDeltaCharacter = outputDeltaLine === 0 ? character - outputCharacter : character
+    out.push(outputDeltaLine, outputDeltaCharacter, length, typeIndex, modifierBits)
+    previousLine = line
+    previousCharacter = character
+    outputLine = line
+    outputCharacter = character
+  }
+  return out
+}

package/src/lsp/settings.ts

@@ -1,11 +1,12 @@
 /**
- * dsh-vscode-mode host — LSP 配置设置 section 安装（动态依赖，缺失不抛错）。
+ * dsh-vscode-mode host — LSP 配置设置 section 安装（版本自适应；缺失/失败不抛错）。
  * ns：dsh-vscode-mode.languageServers；每语言 { enabled, command, path }。
- * 作者 ddj 2026-08-27
+ * 安装策略分派见 fileOpenSettings.runSettingsInstall（rc 线 legacy / alpha 线服务方法）。
+ * 作者 ddj 2026-08-27 / 2026-09-02
  */
 import type { Ctx } from '../store.js'
 import { LSP_LANGUAGES, LSP_SETTINGS_NS, type LspConfig } from './config.js'
-import { loadSettingsDeps, type SettingsDeps } from '../fileOpenSettings.js'
+import { loadSettingsDeps, runSettingsInstall, type SettingsDeps } from '../fileOpenSettings.js'
 
 /**
  * 安装 LSP 设置 section。
@@ -15,7 +16,12 @@ import { loadSettingsDeps, type SettingsDeps } from '../fileOpenSettings.js'
  * @returns 是否成功安装
  */
 export async function installLspSettingsSection(ctx: Ctx, entry: LspConfig): Promise<boolean> {
-  const deps = await loadSettingsDeps()
+  let deps: SettingsDeps | null = null
+  try {
+    deps = await loadSettingsDeps()
+  } catch {
+    /* 装载失败按缺失处理 */
+  }
   if (!deps) return false
   try {
     // schemastery 无 .optional()，对象字段默认即可选；.default 必给避免 undefined 覆盖
@@ -29,11 +35,11 @@ export async function installLspSettingsSection(ctx: Ctx, entry: LspConfig): Pro
       }).default({})
     }
     const schema = z.object(langShape).default({})
-    deps.installSettingsSection(ctx, LSP_SETTINGS_NS, schema, entry, {
+    const strategy = await runSettingsInstall(ctx, LSP_SETTINGS_NS, schema, entry, {
       setSource: () => {},
       onChange: () => {},
     })
-    return true
+    return strategy === 'legacy' || strategy === 'service'
   } catch (error) {
     // 设置 section 安装失败不致命：降级为无设置 UI，LSP 核心功能不受影响
     console.error('[dsh-vscode-mode] LSP 设置 section 安装失败：' + String(error))

package/src/paths.ts

@@ -25,6 +25,8 @@ export const DSH_DIR_NAME = '.dsh'
 export const DSH_HOME_ENV = 'DSH_HOME'
 /** 树缓存 schema 版本（文件名携带；版本递增即触发旧版清理）。 */
 export const TREE_CACHE_SCHEMA = 1
+/** LSP provider 发现缓存 schema 版本（格式变更即递增，旧文件自动失效）。 */
+export const LSP_SPEC_CACHE_SCHEMA = 4
 /** 树缓存保留期：超期文件视为废弃（工作区搬迁/废弃残留）。 */
 export const TREE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
 /** 插件缓存目录总预算：超限按 mtime 从旧到新删文件，防任意增长撑爆磁盘（最后兜底）。 */
@@ -141,6 +143,11 @@ export function userCacheDir(home = dshHome()): string {
   return join(pluginCacheRoot(home), 'user')
 }
 
+/** LSP provider 发现结果缓存文件（用户级：user/lsp-specs.v<schema>.json，跨会话/跨重启共享）。 */
+export function lspSpecCacheFile(home = dshHome(), schema = LSP_SPEC_CACHE_SCHEMA): string {
+  return join(userCacheDir(home), 'lsp-specs.v' + schema + '.json')
+}
+
 /** 插件日志根（~/.dsh/dsh-vscode-mode/logs，用户级）。 */
 export function pluginLogRoot(home = dshHome()): string {
   return join(home, PLUGIN_ID, 'logs')

package/src/rpc.ts

@@ -284,7 +284,10 @@ export function buildHandlers(
       try {
         const target = await resolveTarget(ctx, sc.session, args.path)
         const info = await fs.stat(target)
-        if (!info || info.type !== 'file') return { ok: false, error: '文件不存在' }
+        if (!info || info.type !== 'file') {
+          // 带上解析后的真实路径：跳转失败时可直接看出是路径解析错还是目标本身不存在
+          return { ok: false, error: '文件不存在', resolvedPath: fs.processPath(target) }
+        }
         if ((info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览' }
         const content = await fs.readText(target)
         return { ok: true, content, size: content.length }

package/src/shared/compat.ts

@@ -1,10 +1,10 @@
 /**
  * dsh-vscode-mode 兼容层双面契约 — 与其他插件 / DSH 版本的探测与自诊断报告。
  * Purity rule: no node/react imports (same as types.ts / rpc.ts)。
- * 作者 ddj 2026-08-24
+ * 作者 ddj 2026-08-24 / 2026-09-02
  */
 
-/** 单项适配状态：外部插件/服务或护栏项，active 表示健康/生效。 */
+/** 单项适配状态：外部插件/服务、护栏或版本适配项，active 表示健康/生效。 */
 export interface CompatAdapter {
   name: string
   active: boolean
@@ -17,11 +17,17 @@ export interface DevFormInfo {
   path?: string
 }
 
-/** 兼容性报告：host 侧构建（RPC edrv.compat 返回），client 侧补充本地适配项后展示。 */
+/**
+ * 兼容性报告：host 侧构建（RPC edrv.compat 返回），client 侧补充本地适配项后展示。
+ * dshVersion = 运行中 DSH 核心版本（未探测到为空串）；adapters = 版本适配机制状态行
+ * （旧客户端忽略未知字段，安全前向兼容）。
+ */
 export interface CompatReport {
   pluginVersion: string
   external: CompatAdapter[]
   guards: CompatAdapter[]
   warnings: string[]
   devForm?: DevFormInfo
+  dshVersion?: string
+  adapters?: CompatAdapter[]
 }