dsh-vscode-mode 0.1.32 → 0.1.35

package/src/lsp/rpc.ts

@@ -0,0 +1,334 @@
+/**
+ * dsh-vscode-mode host — edrv.lsp.* RPC handlers。
+ * 文档跟踪（openDocs 集合 + root|lang 引用计数）→ 懒启动服务器、用完释放。
+ * 作者 ddj 2026-08-27
+ */
+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 type { LspManager } from './manager.js'
+import type { RpcHandlerMap } from '../shared/rpc.js'
+import type { LspLocation } from '../shared/lsp.js'
+import { installFromMarket, installVsixFile, listInstalled, marketGet, marketSearch, uninstall, updateExtension, type ExtInfo } from './extmgr.js'
+
+export interface LspRpcDeps {
+  ctx: Ctx
+  pluginConfig: unknown
+  manager: LspManager
+}
+
+/**
+ * 打开文档跟踪：openDocs(docKey→sessionId) + rootLangRefs 计数 + sessionAcquired 归属。
+ * 保证 manager 的 acquire/release 一一配对（多会话共享同一 root|lang 也平衡）。
+ */
+function createDocTracker() {
+  const openDocs = new Map<string, Set<string>>()
+  const rootLangRefs = new Map<string, number>()
+  const sessionDocs = new Map<string, Set<string>>()
+  const keyOf = (root: string, lang: string, path: string): string => root + '|' + lang + '|' + path
+  const rootLangOf = (docKey: string): string => docKey.slice(0, docKey.lastIndexOf('|'))
+  const rememberDoc = (sessionId: string, docKey: string): void => {
+    const docs = sessionDocs.get(sessionId) ?? new Set<string>()
+    docs.add(docKey)
+    sessionDocs.set(sessionId, docs)
+  }
+  const forgetDoc = (sessionId: string, docKey: string): void => {
+    const docs = sessionDocs.get(sessionId)
+    docs?.delete(docKey)
+    if (docs?.size === 0) sessionDocs.delete(sessionId)
+  }
+  const releaseRef = (rl: string): boolean => {
+    const next = (rootLangRefs.get(rl) ?? 1) - 1
+    if (next <= 0) {
+      rootLangRefs.delete(rl)
+      return true
+    }
+    rootLangRefs.set(rl, next)
+    return false
+  }
+  return {
+    /** 记录文档打开；同一文档可由多个会话打开，但每个会话只计一次。 */
+    open(root: string, lang: string, path: string, sessionId: string): boolean {
+      const docKey = keyOf(root, lang, path)
+      const owners = openDocs.get(docKey) ?? new Set<string>()
+      if (owners.has(sessionId)) return false
+      owners.add(sessionId)
+      openDocs.set(docKey, owners)
+      rememberDoc(sessionId, docKey)
+      const rl = root + '|' + lang
+      const count = rootLangRefs.get(rl) ?? 0
+      rootLangRefs.set(rl, count + 1)
+      return count === 0
+    },
+    /** 记录文档关闭；返回 true 表示 root|lang 已无文档（应 release）。 */
+    close(root: string, lang: string, path: string, sessionId: string): boolean {
+      const docKey = keyOf(root, lang, path)
+      const owners = openDocs.get(docKey)
+      if (!owners?.has(sessionId)) return false
+      owners.delete(sessionId)
+      if (owners.size === 0) openDocs.delete(docKey)
+      forgetDoc(sessionId, docKey)
+      return releaseRef(root + '|' + lang)
+    },
+    /** 关闭某会话全部文档；返回全局引用归零、需要 release 的 root|lang。 */
+    closeSession(sessionId: string): string[] {
+      const docs = sessionDocs.get(sessionId)
+      if (!docs) return []
+      const toRelease = new Set<string>()
+      for (const docKey of docs) {
+        const owners = openDocs.get(docKey)
+        owners?.delete(sessionId)
+        if (owners?.size === 0) openDocs.delete(docKey)
+        if (releaseRef(rootLangOf(docKey))) toRelease.add(rootLangOf(docKey))
+      }
+      sessionDocs.delete(sessionId)
+      return [...toRelease]
+    },
+  }
+}
+
+/**
+ * 构造 edrv.lsp.* handlers（一次性创建，tracker 状态跨请求保留）。
+ * @author ddj 2026年08月27号
+ * @param deps 依赖（ctx/pluginConfig/manager）
+ * @returns { handlers, disposeSession } handlers 为局部 map，disposeSession 供 session/disposed 清理
+ */
+export function createLspRpc(deps: LspRpcDeps): { handlers: Partial<RpcHandlerMap>; disposeSession: (sessionId: string) => void } {
+  const { ctx, pluginConfig, manager } = deps
+  const tracker = createDocTracker()
+
+  /** 解析会话与工作区根（失败 → null + error）。 */
+  const rootOf = async (sessionId: string | undefined): Promise<{ root: string; sessionId: string } | { err: string }> => {
+    const session = sessionOf(ctx, sessionId)
+    if (!session) return { err: '会话不存在' }
+    const cwd = cwdOf(session)
+    if (!cwd) return { err: '会话无工作区' }
+    try {
+      const root = await searchRoot(ctx, session)
+      const sid = typeof session.id === 'string' && session.id ? session.id : sessionId ?? ''
+      return { root, sessionId: sid }
+    } catch (error) {
+      return { err: String(error) }
+    }
+  }
+
+  const acquireServer = (root: string, lang: string) =>
+    manager.acquire(root, lang, (languageId: string) => resolveProviderSpec(ctx, pluginConfig, languageId))
+
+  const serverOf = (root: string, lang: string) =>
+    manager.peek(root, lang)
+
+  const rootLocations = (locations: LspLocation[], root: string): LspLocation[] =>
+    locations.map((location) => ({ ...location, root }))
+
+  const disposeSession = (sessionId: string): void => {
+    for (const rl of tracker.closeSession(sessionId)) {
+      const sep = rl.lastIndexOf('|')
+      manager.release(rl.slice(0, sep), rl.slice(sep + 1))
+    }
+  }
+
+  const handlers: Partial<RpcHandlerMap> = {
+    'edrv.lsp.status': async (args) => {
+      if (!args.sessionId) return { ok: true, servers: manager.statusAll() }
+      const sc = await rootOf(args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      return { ok: true, servers: manager.statusAll().filter((status) => status.root === sc.root) }
+    },
+
+    'edrv.lsp.configGet': async () => {
+      const settings = configFromSettings(ctx)
+      const plugin = configFromPlugin(pluginConfig)
+      const merged: LspConfig = { ...plugin }
+      for (const lang of Object.keys(settings)) merged[lang] = { ...plugin[lang], ...settings[lang] }
+      return { ok: true, config: merged as unknown as Record<string, unknown> }
+    },
+
+    'edrv.lsp.configUpdate': async (args) => {
+      const lang = args.languageId
+      if (!lang || !resolveProviderSpec(ctx, pluginConfig, lang).languageId) {
+        return { ok: false, error: '不支持的语言：' + lang }
+      }
+      const current = configFromSettings(ctx)
+      const next: LspConfig = { ...current, [lang]: { ...(current[lang] ?? {}) } }
+      const target = next[lang]!
+      if (args.enabled !== undefined) target.enabled = args.enabled
+      if (args.command !== undefined) target.command = args.command || undefined
+      if (args.path !== undefined) target.path = args.path || undefined
+      try {
+        const settings = ctx.get('settings')
+        if (!settings?.update) return { ok: false, error: '设置服务不可用' }
+        await settings.update(LSP_SETTINGS_NS, { [lang]: target })
+        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> }
+      } catch (error) {
+        return { ok: false, error: '配置保存失败：' + String(error) }
+      }
+    },
+
+    'edrv.lsp.sync': async (args) => {
+      const lang = langOfPath(args.path)
+      if (!lang) return { ok: true }
+      const sc = await rootOf(args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const first = tracker.open(sc.root, lang, args.path, sc.sessionId)
+      const server = first ? acquireServer(sc.root, lang) : serverOf(sc.root, lang)
+      if (!server) return { ok: false, error: '语言服务器未注册' }
+      server.sync(args.path, args.text, args.version)
+      return { ok: true }
+    },
+
+    'edrv.lsp.close': async (args) => {
+      const lang = langOfPath(args.path)
+      if (!lang) return { ok: true }
+      const sc = await rootOf(args.sessionId)
+      if ('err' in sc) return { ok: true }
+      if (tracker.close(sc.root, lang, args.path, sc.sessionId)) {
+        manager.release(sc.root, lang)
+      }
+      return { ok: true }
+    },
+
+    'edrv.lsp.definition': async (args) => {
+      const lang = langOfPath(args.path)
+      if (!lang) return { ok: true, locations: [] }
+      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, locations: [] }
+        const locations = await server.definition(args.path, args.position.line, args.position.character)
+        const rooted = rootLocations(locations, sc.root)
+        const truncated = rooted.length > 500
+        return { ok: true, locations: truncated ? rooted.slice(0, 500) : rooted, truncated: truncated || undefined }
+      } catch (error) {
+        return { ok: false, error: 'LSP 定义查询失败：' + String(error) }
+      }
+    },
+
+    'edrv.lsp.references': async (args) => {
+      const lang = langOfPath(args.path)
+      if (!lang) return { ok: true, locations: [] }
+      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, locations: [] }
+        const locations = await server.references(args.path, args.position.line, args.position.character, args.includeDeclaration !== false)
+        const rooted = rootLocations(locations, sc.root)
+        const truncated = rooted.length > 500
+        return { ok: true, locations: truncated ? rooted.slice(0, 500) : rooted, truncated: truncated || undefined }
+      } catch (error) {
+        return { ok: false, error: 'LSP 引用查询失败：' + String(error) }
+      }
+    },
+
+    'edrv.lsp.documentSymbol': async (args) => {
+      const lang = langOfPath(args.path)
+      if (!lang) return { ok: true, symbols: [] }
+      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, symbols: [] }
+        const symbols = await server.documentSymbol(args.path)
+        return { ok: true, symbols }
+      } catch (error) {
+        return { ok: false, error: 'LSP 大纲查询失败：' + String(error) }
+      }
+    },
+
+    'edrv.lsp.workspaceSymbol': async (args) => {
+      const sc = await rootOf(args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const out: { symbols: never[]; truncated?: boolean } = { symbols: [] }
+      for (const lang of ['lua', 'csharp']) {
+        const existing = serverOf(sc.root, lang)
+        if (!existing) continue
+        try {
+          const symbols = await existing.workspaceSymbol(args.query)
+          if (symbols.length) out.symbols.push(...(symbols as never[]))
+        } catch (error) {
+          /* 单语言失败忽略 */
+        }
+      }
+      const truncated = out.symbols.length > 500
+      return { ok: true, symbols: out.symbols.slice(0, 500), truncated: truncated || undefined }
+    },
+
+    'edrv.lsp.hover': async (args) => {
+      const lang = langOfPath(args.path)
+      if (!lang) return { ok: true, hover: 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, hover: undefined }
+        const hover = await server.hover(args.path, args.position.line, args.position.character)
+        return { ok: true, hover: hover ?? undefined }
+      } catch (error) {
+        return { ok: false, error: 'LSP hover 查询失败：' + String(error) }
+      }
+    },
+
+    // --region 扩展管理（edrv.lsp.ext.*：已装/市场/安装/卸载/更新）
+    'edrv.lsp.ext.list': async () => ({ ok: true, extensions: listInstalled() }),
+
+    'edrv.lsp.ext.market': async (args) => {
+      try {
+        const items = await marketSearch(args.query, args.size ?? 12)
+        return { ok: true, extensions: items }
+      } catch (error) {
+        return { ok: false, error: '市场搜索失败：' + String(error) }
+      }
+    },
+
+    'edrv.lsp.ext.install': async (args) => {
+      try {
+        let info: ExtInfo
+        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）' }
+        return { ok: true, extension: info }
+      } catch (error) {
+        return { ok: false, error: '安装失败：' + String(error) }
+      }
+    },
+
+    'edrv.lsp.ext.uninstall': async (args) => {
+      return uninstall(args.id) ? { ok: true } : { ok: false, error: '扩展未安装：' + args.id }
+    },
+
+    'edrv.lsp.ext.update': async (args) => {
+      try {
+        const updated = await updateExtension(args.id)
+        if (!updated) {
+          const current = listInstalled().find((e) => e.id === args.id)
+          return current ? { ok: true, extension: current, updated: false } : { ok: false, error: '扩展未安装：' + args.id }
+        }
+        return { ok: true, extension: updated, updated: true }
+      } catch (error) {
+        return { ok: false, error: '更新失败：' + String(error) }
+      }
+    },
+
+    'edrv.lsp.ext.updates': async () => {
+      try {
+        const updates = []
+        for (const ext of listInstalled()) {
+          const meta = await marketGet(ext.namespace, ext.name)
+          const latest = String(meta?.version ?? '')
+          if (latest && latest !== ext.version) updates.push({ id: ext.id, current: ext.version, latest, displayName: ext.displayName })
+        }
+        return { ok: true, updates }
+      } catch (error) {
+        return { ok: false, error: '检查更新失败：' + String(error) }
+      }
+    },
+    // --endregion
+  }
+  return { handlers, disposeSession }
+}

package/src/lsp/server.ts

@@ -0,0 +1,346 @@
+/**
+ * dsh-vscode-mode host — 单语言服务器会话（绑定 工作区根 + 语言）。
+ * 负责：启动传输 + LSP 客户端握手、文档同步（didOpen/didChange/didSave/didClose）、
+ * 请求封装（definition/references/documentSymbol/workspaceSymbol/hover）、状态上报。
+ * 作者 ddj 2026-08-27
+ */
+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 type {
+  LspLocation,
+  LspServerCapabilities,
+  LspServerPhase,
+  LspServerStatus,
+  LspSymbol,
+} from '../shared/lsp.js'
+
+export interface LspServer {
+  readonly languageId: string
+  readonly root: string
+  readonly phase: LspServerPhase
+  readonly capabilities: LspServerCapabilities
+  onStateChange: ((status: LspServerStatus) => void) | null
+  status(): LspServerStatus
+  start(): Promise<boolean>
+  sync(path: string, text: string, version: number): void
+  close(path: string): void
+  definition(path: string, line: number, character: number): Promise<LspLocation[]>
+  references(path: string, line: number, character: number, includeDeclaration: boolean): Promise<LspLocation[]>
+  documentSymbol(path: string): Promise<LspSymbol[]>
+  workspaceSymbol(query: string): Promise<LspSymbol[]>
+  hover(path: string, line: number, character: number): Promise<{ contents: string[] } | null>
+  dispose(): Promise<void>
+}
+
+/** 文档注册表：path(工作区相对) → { version, text, uri }。 */
+interface OpenDoc {
+  path: string
+  uri: string
+  version: number
+  text: string
+}
+
+const RESTARTABLE = true
+
+/**
+ * 创建语言服务器会话。
+ * @author ddj 2026年08月27号
+ * @param spec provider 规格（argv/cwd）
+ * @param root 工作区根（绝对路径）
+ * @param languageId 语言 id
+ * @param logger 诊断日志
+ * @returns 会话句柄
+ */
+export function createLspServer(spec: LspProviderSpec, root: string, languageId: string, logger?: (line: string) => void): LspServer {
+  const rootUri = pathToFileUri(root)
+  const docs = new Map<string, OpenDoc>()
+  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 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 }
+
+  const log = (line: string): void => logger?.('[' + languageId + '@' + root + '] ' + line)
+
+  const setPhase = (next: LspServerPhase, reason?: string): void => {
+    phase = next
+    lastStatus = { languageId, source: spec.kind, phase: next, reason, root, ...progressFields() }
+    server.onStateChange?.(lastStatus)
+  }
+
+  /** 返回当前进度字段，避免空进度污染状态载荷。 */
+  const progressFields = (): Pick<LspServerStatus, 'progress' | 'progressMessage'> => ({
+    progress: lastProgress.value,
+    progressMessage: lastProgress.message,
+  })
+
+  /** 处理 LSP $/progress 通知并映射为编辑器状态。 */
+  const applyProgress = (params: unknown): void => {
+    const value = params as { value?: unknown }
+    const report = value?.value as { kind?: unknown; percentage?: unknown; message?: unknown } | undefined
+    if (report?.kind === 'begin') {
+      lastProgress = { value: 0, message: typeof report.message === 'string' ? report.message : '正在解析工作区' }
+      if (phase === 'ready') phase = 'indexing'
+    } else if (report?.kind === 'end') {
+      lastProgress = { value: 100, message: typeof report.message === 'string' ? report.message : '解析完成' }
+      if (phase === 'indexing') phase = 'ready'
+    } else if (typeof report?.percentage === 'number') {
+      lastProgress = { value: Math.max(0, Math.min(100, report.percentage)), message: typeof report.message === 'string' ? report.message : lastProgress.message }
+      if (phase === 'ready') phase = 'indexing'
+    } else if (typeof report?.message === 'string') {
+      lastProgress = { ...lastProgress, message: report.message }
+    }
+    lastStatus = { ...lastStatus, phase, ...progressFields() }
+    server.onStateChange?.(lastStatus)
+  }
+
+  const ensureClient = (): LspClient => {
+    if (!client) throw new Error('LSP 服务器未启动')
+    return client
+  }
+
+  const server: LspServer = {
+    languageId,
+    root,
+    get phase() {
+      return phase
+    },
+    get capabilities() {
+      return capabilities
+    },
+    status(): LspServerStatus {
+      return lastStatus
+    },
+    onStateChange: null,
+
+    async start(): Promise<boolean> {
+      if (disposed) return false
+      if (phase === 'starting') return readyWait
+      if (phase === 'ready' || phase === 'indexing') return true
+      readyWait = new Promise((resolve) => { resolveReady = resolve })
+      lastProgress = {}
+      setPhase('starting')
+      try {
+        transport = spawnServer(
+          { argv: spec.argv, cwd: spec.cwd ?? root },
+          (message) => { /* 由 client 接管 */ },
+          (line) => log('stderr: ' + line),
+        )
+        client = createLspClient(transport, {
+          onReady: (caps) => {
+            capabilities = caps
+            // 重放已打开文档（崩溃重启后恢复服务器侧状态）
+            for (const doc of docs.values()) {
+              client?.notify('textDocument/didOpen', {
+                textDocument: { uri: doc.uri, languageId, version: doc.version, text: doc.text },
+              })
+            }
+            setPhase('ready')
+            resolveReady?.(true)
+            resolveReady = null
+            log('ready: definition=' + caps.definition + ' references=' + caps.references + ' symbols=' + caps.documentSymbol)
+          },
+          onProgress: (params) => applyProgress(params),
+          onExit: (code, signal) => {
+            if (disposed) return
+            resolveReady?.(false)
+            resolveReady = null
+            log('server exited (' + String(code) + '/' + String(signal) + ')')
+            client = null
+            transport = null
+            if (RESTARTABLE) setPhase('idle', '服务器已退出（' + String(code) + '/' + String(signal) + '），等待重启')
+            else setPhase('stopped', '服务器已退出')
+          },
+          onLog: (line) => log('lsp: ' + line),
+        })
+        // 让 client 接管 stdout 消息
+        const caps = await client.initialize(rootUri, [rootUri])
+        capabilities = caps
+        return true
+      } catch (error) {
+        log('start failed: ' + String(error))
+        setPhase('unavailable', '启动失败：' + String(error))
+        resolveReady?.(false)
+        resolveReady = null
+        try { await server.dispose() } catch { /* 忽略 */ }
+        return false
+      }
+    },
+
+    sync(path: string, text: string, version: number): void {
+      const existing = docs.get(path)
+      const uri = existing?.uri ?? pathToFileUri(root + '/' + path.split('/').join('/'))
+      if (existing) {
+        existing.version = version
+        existing.text = text
+        if (phase === 'ready' || phase === 'indexing') {
+          client?.notify('textDocument/didChange', {
+            textDocument: { uri, version },
+            contentChanges: [{ text }],
+          })
+        }
+        return
+      }
+      docs.set(path, { path, uri, version, text })
+      if (phase === 'ready' || phase === 'indexing') {
+        client?.notify('textDocument/didOpen', {
+          textDocument: { uri, languageId, version, text },
+        })
+      }
+    },
+
+    close(path: string): void {
+      const doc = docs.get(path)
+      if (!doc) return
+      docs.delete(path)
+      if (phase === 'ready' || phase === 'indexing') {
+        client?.notify('textDocument/didClose', { textDocument: { uri: doc.uri } })
+      }
+    },
+
+    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 } },
+      )
+      return normalizeLocations(result)
+    },
+
+    async references(path: string, line: number, character: number, includeDeclaration: boolean): Promise<LspLocation[]> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait)) return []
+      const result = await ensureClient().request<unknown>(
+        'textDocument/references',
+        {
+          textDocument: { uri: doc.uri },
+          position: { line, character },
+          context: { includeDeclaration },
+        },
+      )
+      return normalizeLocations(result)
+    },
+
+    async documentSymbol(path: string): Promise<LspSymbol[]> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait)) return []
+      const result = await ensureClient().request<unknown>('textDocument/documentSymbol', { textDocument: { uri: doc.uri } })
+      if (!Array.isArray(result)) return []
+      return (result as unknown[]).map(normalizeSymbol).filter((s): s is LspSymbol => s !== null)
+    },
+
+    async workspaceSymbol(query: string): Promise<LspSymbol[]> {
+      if (!(await readyWait)) return []
+      const result = await ensureClient().request<unknown>('workspace/symbol', { query })
+      if (!Array.isArray(result)) return []
+      return (result as unknown[]).map(normalizeSymbol).filter((s): s is LspSymbol => s !== null)
+    },
+
+    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>(
+        'textDocument/hover',
+        { textDocument: { uri: doc.uri }, position: { line, character } },
+      )
+      if (!result || !result.contents) return null
+      return { contents: stringifyHoverContents(result.contents) }
+    },
+
+    async dispose(): Promise<void> {
+      disposed = true
+      resolveReady?.(false)
+      resolveReady = null
+      if (client) {
+        await client.shutdown().catch(() => {})
+        client = null
+      }
+      if (transport) {
+        transport.dispose()
+        transport = null
+      }
+      setPhase('stopped')
+    },
+  }
+  return server
+}
+
+/** 归一化 definition/references 结果（Location | Location[] | LocationLink[]）。 */
+function normalizeLocations(result: unknown): LspLocation[] {
+  if (!Array.isArray(result)) return []
+  const out: LspLocation[] = []
+  for (const item of result) {
+    if (!item || typeof item !== 'object') continue
+    const obj = item as { uri?: unknown; range?: unknown; targetUri?: unknown; targetRange?: unknown; targetSelectionRange?: unknown }
+    const uri = typeof obj.targetUri === 'string' ? obj.targetUri : typeof obj.uri === 'string' ? obj.uri : ''
+    const range = (obj.targetRange ?? obj.range) as { start?: { line?: unknown; character?: unknown }; end?: { line?: unknown; character?: unknown } } | undefined
+    if (!uri || !range || !range.start || !range.end) continue
+    out.push({
+      uri,
+      range: {
+        start: { line: toInt(range.start.line), character: toInt(range.start.character) },
+        end: { line: toInt(range.end.line), character: toInt(range.end.character) },
+      },
+    })
+  }
+  return out
+}
+
+/** 归一化 documentSymbol/workspaceSymbol 结果（DocumentSymbol | SymbolInformation）。 */
+function normalizeSymbol(item: unknown): LspSymbol | null {
+  if (!item || typeof item !== 'object') return null
+  const obj = item as {
+    name?: unknown
+    kind?: unknown
+    detail?: unknown
+    containerName?: unknown
+    range?: { start?: unknown; end?: unknown }
+    selectionRange?: { start?: unknown; end?: unknown }
+    children?: unknown
+    location?: { uri?: unknown; range?: unknown }
+  }
+  if (typeof obj.name !== 'string') return null
+  const selection = obj.selectionRange ?? (obj.location && (obj.location as { range?: unknown }).range)
+  const range = obj.range ?? selection
+  if (!range || typeof range !== 'object') return null
+  const r = range as { start?: { line?: unknown; character?: unknown }; end?: { line?: unknown; character?: unknown } }
+  if (!r.start || !r.end) return null
+  const symbol: LspSymbol = {
+    name: obj.name,
+    kind: toInt(obj.kind),
+    range: { start: { line: toInt((r.start as { line?: unknown }).line), character: toInt((r.start as { character?: unknown }).character) }, end: { line: toInt((r.end as { line?: unknown }).line), character: toInt((r.end as { character?: unknown }).character) } },
+    selectionRange: selection
+      ? { start: { line: toInt(((selection as { start?: { line?: unknown } }).start as { line?: unknown } | undefined)?.line ?? toInt((r.start as { line?: unknown }).line)), character: toInt(((selection as { start?: { character?: unknown } }).start as { character?: unknown } | undefined)?.character ?? toInt((r.start as { character?: unknown }).character)) }, end: { line: toInt(((selection as { end?: { line?: unknown } }).end as { line?: unknown } | undefined)?.line ?? toInt((r.end as { line?: unknown }).line)), character: toInt(((selection as { end?: { character?: unknown } }).end as { character?: unknown } | undefined)?.character ?? toInt((r.end as { character?: unknown }).character)) } }
+      : { start: { line: toInt((r.start as { line?: unknown }).line), character: toInt((r.start as { character?: unknown }).character) }, end: { line: toInt((r.end as { line?: unknown }).line), character: toInt((r.end as { character?: unknown }).character) } },
+  }
+  if (typeof obj.detail === 'string' && obj.detail) symbol.detail = obj.detail
+  if (typeof obj.containerName === 'string' && obj.containerName) symbol.containerName = obj.containerName
+  if (Array.isArray(obj.children)) {
+    const kids = obj.children.map(normalizeSymbol).filter((s): s is LspSymbol => s !== null)
+    if (kids.length) symbol.children = kids
+  }
+  return symbol
+}
+
+/** hover contents → 文本行（MarkupContent | MarkedString | MarkedString[]）。 */
+function stringifyHoverContents(contents: unknown): string[] {
+  if (typeof contents === 'string') return [contents]
+  if (Array.isArray(contents)) return contents.map(stringifyHoverContents).flat().filter(Boolean)
+  if (contents && typeof contents === 'object') {
+    const value = (contents as { value?: unknown }).value
+    if (typeof value === 'string') return [value]
+  }
+  return []
+}
+
+function toInt(value: unknown): number {
+  const n = Number(value)
+  return Number.isFinite(n) ? Math.max(0, Math.floor(n)) : 0
+}