dsh-vscode-mode 0.1.32 → 0.1.36

package/src/lsp/extmgr.ts

@@ -0,0 +1,208 @@
+/**
+ * dsh-vscode-mode host — VSIX 扩展管理器（extmgr）。
+ * 管理 DSH 专属扩展目录（~/.dsh/dsh-vscode-mode/extensions/），支持：
+ * 本地 .vsix 安装、Open VSX 市场搜索/下载安装、卸载、更新检测与安装。
+ * 已装扩展作为 LSP provider 的"扩展源"（kind=extension），见 providers.ts。
+ * 作者 ddj 2026-08-27
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { unzip } from './zip.js'
+import { dshHome, PLUGIN_ID } from '../paths.js'
+
+/** 单个已装扩展信息（edrv.lsp.ext.list 载荷元素）。 */
+export interface ExtInfo {
+  id: string        // publisher.name
+  namespace: string
+  name: string
+  version: string
+  displayName?: string
+  description?: string
+  dirName: string   // 目录名 publisher.name-version
+  dir: string       // 绝对路径
+}
+
+/** Open VSX 市场搜索结果（edrv.lsp.ext.market 载荷元素）。 */
+export interface MarketItem {
+  namespace: string
+  name: string
+  id: string
+  version: string
+  displayName?: string
+  description?: string
+  download?: string
+}
+
+const OPEN_VSX = 'https://open-vsx.org'
+const META_FILE = 'package.json'
+/** 当前平台（与 VSCode platform 命名对齐：win32-x64/darwin-arm64/linux-x64）。 */
+const PLATFORM = (() => {
+  if (process.platform === 'win32') return process.arch === 'arm64' ? 'win32-arm64' : 'win32-x64'
+  if (process.platform === 'darwin') return process.arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64'
+  return process.arch === 'arm64' ? 'linux-arm64' : 'linux-x64'
+})()
+
+/** DSH 专属扩展目录。 */
+export function extensionsRoot(home = dshHome()): string {
+  return join(home, PLUGIN_ID, 'extensions')
+}
+
+/** 从 VSIX 字节里读 extension/package.json 清单。 */
+export function vsixManifest(vsix: Buffer): Record<string, unknown> {
+  for (const entry of unzip(vsix)) {
+    if (entry.path === 'extension/package.json' || entry.path === 'extension\\package.json') {
+      return JSON.parse(entry.data.toString('utf8')) as Record<string, unknown>
+    }
+  }
+  throw new Error('VSIX 缺少 extension/package.json')
+}
+
+/**
+ * 解包 VSIX 到目录（仅取 extension/ 子树，剥前缀；返回清单）。
+ * @author ddj 2026年08月27号
+ * @param vsix vsix 字节
+ * @param dest 目标目录（已存在则先清空）
+ * @returns 清单对象
+ */
+export function unpackVsix(vsix: Buffer, dest: string): Record<string, unknown> {
+  rmSync(dest, { recursive: true, force: true })
+  mkdirSync(dest, { recursive: true })
+  let manifest: Record<string, unknown> | null = null
+  for (const entry of unzip(vsix)) {
+    const rel = entry.path.replace(/^extension[\\/]/, '')
+    if (!rel || entry.path.startsWith('..')) continue
+    const safe = rel.split(/[\\/]/).filter((part) => part && part !== '..' && part !== '.').join('/')
+    if (!safe) continue
+    const target = join(dest, ...safe.split('/'))
+    if (entry.isDirectory) {
+      mkdirSync(target, { recursive: true })
+      continue
+    }
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, entry.data)
+    if (rel === 'package.json') manifest = JSON.parse(entry.data.toString('utf8')) as Record<string, unknown>
+  }
+  if (!manifest) throw new Error('VSIX 解包后缺少 package.json')
+  return manifest
+}
+
+/** 扩展信息（清单 + 目录）。 */
+export function extInfoOf(manifest: Record<string, unknown>, dir: string): ExtInfo {
+  const namespace = String(manifest.publisher ?? 'unknown')
+  const name = String(manifest.name ?? 'unknown')
+  const version = String(manifest.version ?? '0.0.0')
+  return {
+    id: namespace + '.' + name,
+    namespace,
+    name,
+    version,
+    displayName: typeof manifest.displayName === 'string' ? manifest.displayName : undefined,
+    description: typeof manifest.description === 'string' ? manifest.description : undefined,
+    dirName: basename(dir),
+    dir,
+  }
+}
+
+/** 安装本地 .vsix 文件（已存在同 id 则升级替换）。 */
+export async function installVsixFile(vsixPath: string, home = dshHome()): Promise<ExtInfo> {
+  const vsix = readFileSync(vsixPath)
+  return installVsixBuffer(vsix, home)
+}
+
+/** 安装 VSIX 字节（解包进 extensionsRoot；同名旧版本先清）。 */
+export function installVsixBuffer(vsix: Buffer, home = dshHome()): ExtInfo {
+  const manifest = vsixManifest(vsix)
+  const info = extInfoOf(manifest, '')
+  const target = join(extensionsRoot(home), info.id + '-' + info.version)
+  const unpacked = unpackVsix(vsix, target)
+  return extInfoOf(unpacked, target)
+}
+/** 扫描已装扩展目录。 */
+export function listInstalled(home = dshHome()): ExtInfo[] {
+  const root = extensionsRoot(home)
+  if (!existsSync(root)) return []
+  const out: ExtInfo[] = []
+  for (const dir of readdirSync(root)) {
+    const full = join(root, dir)
+    const meta = join(full, META_FILE)
+    if (!existsSync(meta)) continue
+    try {
+      const manifest = JSON.parse(readFileSync(meta, 'utf8')) as Record<string, unknown>
+      out.push(extInfoOf(manifest, full))
+    } catch (error) {
+      /* 坏清单目录跳过 */
+    }
+  }
+  return out
+}
+
+/** 卸载扩展（按 id）。 */
+export function uninstall(id: string, home = dshHome()): boolean {
+  const target = listInstalled(home).find((e) => e.id === id)?.dir
+  if (!target) return false
+  rmSync(target, { recursive: true, force: true })
+  return true
+}
+
+/** Open VSX 单扩展元数据（latest + 下载 URL）。 */
+export async function marketGet(namespace: string, name: string, version?: string): Promise<Record<string, unknown> | null> {
+  const path = version ? namespace + '/' + name + '/' + version : namespace + '/' + name
+  const res = await fetch(OPEN_VSX + '/api/' + path, { headers: { accept: 'application/json' } })
+  if (!res.ok) return null
+  return (await res.json()) as Record<string, unknown>
+}
+
+/** Open VSX 搜索。 */
+export async function marketSearch(query: string, size = 12): Promise<MarketItem[]> {
+  const url = OPEN_VSX + '/api/-/search?query=' + encodeURIComponent(query) + '&size=' + size
+  const res = await fetch(url, { headers: { accept: 'application/json' } })
+  if (!res.ok) throw new Error('市场搜索失败：HTTP ' + res.status)
+  const data = (await res.json()) as { extensions?: unknown[] }
+  return ((data.extensions ?? []) as Record<string, unknown>[]).map((item) => ({
+    namespace: String(item.namespace ?? ''),
+    name: String(item.name ?? ''),
+    id: String(item.namespace ?? '') + '.' + String(item.name ?? ''),
+    version: String(item.version ?? ''),
+    displayName: typeof item.displayName === 'string' ? item.displayName : undefined,
+    description: typeof item.description === 'string' ? item.description : undefined,
+    download: typeof (item.files as { download?: unknown } | undefined)?.download === 'string' ? (item.files as { download: string }).download : undefined,
+  }))
+}
+
+/** 平台匹配的 VSIX 下载 URL（探测平台变体，失败回退 API 默认）。 */
+export async function resolveDownload(namespace: string, name: string, version: string): Promise<string> {
+  const candidate = OPEN_VSX + '/api/' + namespace + '/' + name + '/' + PLATFORM + '/' + version +
+    '/file/' + namespace + '.' + name + '-' + version + '@' + PLATFORM + '.vsix'
+  try {
+    const head = await fetch(candidate, { method: 'HEAD' })
+    if (head.ok) return candidate
+  } catch (error) {
+    /* 探测失败走默认 */
+  }
+  const meta = await marketGet(namespace, name, version)
+  const download = (meta?.files as { download?: unknown } | undefined)?.download
+  if (typeof download === 'string') return download
+  throw new Error('市场未提供 ' + namespace + '.' + name + '@' + version + ' 的下载地址')
+}
+
+/** 从 Open VSX 安装/更新扩展。 */
+export async function installFromMarket(namespace: string, name: string, version?: string): Promise<ExtInfo> {
+  const meta = await marketGet(namespace, name, version)
+  if (!meta) throw new Error('市场找不到 ' + namespace + '.' + name + (version ? '@' + version : ''))
+  const ver = version ?? String(meta.version ?? '')
+  const url = await resolveDownload(namespace, name, ver)
+  const res = await fetch(url)
+  if (!res.ok) throw new Error('下载失败：HTTP ' + res.status)
+  const vsix = Buffer.from(await res.arrayBuffer())
+  return installVsixBuffer(vsix)
+}
+
+/** 更新已装扩展（对比市场最新版；返回 null 表示已最新）。 */
+export async function updateExtension(id: string): Promise<ExtInfo | null> {
+  const installed = listInstalled().find((e) => e.id === id)
+  if (!installed) throw new Error('扩展未安装：' + id)
+  const meta = await marketGet(installed.namespace, installed.name)
+  const latest = String(meta?.version ?? '')
+  if (!latest || latest === installed.version) return null
+  return installFromMarket(installed.namespace, installed.name, latest)
+}

package/src/lsp/jsonrpc.ts

@@ -0,0 +1,86 @@
+/**
+ * dsh-vscode-mode host — LSP JSON-RPC 帧编解码（纯函数，node 可测）。
+ * LSP over stdio 用 Content-Length 帧：
+ *   Content-Length: <n>\r\n\r\n<恰好 n 字节 JSON>
+ * 导出：encodeMessage（对象→帧 Buffer）、createFrameParser（流式粘包/拆包）、parseFrame（单帧）。
+ * 作者 ddj 2026-08-27
+ */
+
+const HEADER_END = '\r\n\r\n'
+
+/** 消息头正则（仅取 Content-Length；其它头忽略）。 */
+const HEADER_RE = /^Content-Length:\s*(\d+)\s*$/im
+
+/** 将对象编码为带 Content-Length 头的帧。 */
+export function encodeMessage(message: unknown): Buffer {
+  const body = JSON.stringify(message)
+  const head = 'Content-Length: ' + Buffer.byteLength(body, 'utf8') + '\r\n\r\n'
+  return Buffer.from(head + body, 'utf8')
+}
+
+/**
+ * 尝试从 buffer 解析单个帧；成功返回 { body, rest }，数据不足返回 null。
+ * @author ddj 2026年08月27号
+ * @param buffer 已累积的字节
+ * @returns 解析结果（rest 为剩余未消费字节）
+ */
+export function parseFrame(buffer: Buffer): { body: string; rest: Buffer } | null {
+  const headEnd = buffer.indexOf(HEADER_END)
+  if (headEnd < 0) return null
+  const header = buffer.subarray(0, headEnd).toString('utf8')
+  const m = HEADER_RE.exec(header)
+  if (!m) {
+    // 非法头：丢弃直到下一个帧头，避免死循环
+    const next = buffer.indexOf('Content-Length:')
+    return next >= 0 ? parseFrame(buffer.subarray(next)) : null
+  }
+  const length = Number(m[1])
+  const bodyStart = headEnd + HEADER_END.length
+  if (buffer.length < bodyStart + length) return null
+  const body = buffer.subarray(bodyStart, bodyStart + length).toString('utf8')
+  return { body, rest: buffer.subarray(bodyStart + length) }
+}
+
+/** 帧解析器：push 数据块，吐出完整消息（可能拆包后重组、也可能一包多帧）。 */
+export function createFrameParser(): {
+  push(chunk: Buffer): unknown[]
+  clear(): void
+} {
+  let buffer: Buffer = Buffer.alloc(0)
+  return {
+    push(chunk: Buffer): unknown[] {
+      if (chunk.length) buffer = Buffer.concat([buffer, chunk]) as Buffer
+      const out: unknown[] = []
+      for (;;) {
+        const parsed = parseFrame(buffer)
+        if (!parsed) break
+        buffer = parsed.rest
+        try {
+          out.push(JSON.parse(parsed.body))
+        } catch (error) {
+          out.push({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error: ' + String(error) }, id: null })
+        }
+      }
+      return out
+    },
+    clear(): void {
+      buffer = Buffer.alloc(0)
+    },
+  }
+}
+
+/** 构造标准 JSON-RPC 请求消息。 */
+export function requestMessage(id: number, method: string, params: unknown): Record<string, unknown> {
+  return { jsonrpc: '2.0', id, method, params }
+}
+
+/** 构造标准 JSON-RPC 通知消息（无 id，fire-and-forget）。 */
+export function notifyMessage(method: string, params: unknown): Record<string, unknown> {
+  return { jsonrpc: '2.0', method, params }
+}
+
+/** 构造标准 JSON-RPC 响应消息。 */
+export function responseMessage(id: number | string | null, result: unknown, error?: unknown): Record<string, unknown> {
+  if (error !== undefined) return { jsonrpc: '2.0', id, error }
+  return { jsonrpc: '2.0', id, result }
+}

package/src/lsp/manager.ts

@@ -0,0 +1,133 @@
+/**
+ * dsh-vscode-mode host — LSP 服务器管理器。
+ * 实例注册表（key=root|languageId，refcount 共享），崩溃退避重启，session/disposed 清理。
+ * 作者 ddj 2026-08-27
+ */
+import { createLspServer, type LspServer } from './server.js'
+import type { LspProviderSpec } from './providers.js'
+import type { LspServerStatus } from '../shared/lsp.js'
+
+interface Entry {
+  key: string
+  server: LspServer
+  refs: number
+  failures: number
+  restartTimer: ReturnType<typeof setTimeout> | null
+}
+
+const BACKOFF_MS = [1000, 5000, 30000]
+const MAX_FAILURES = 3
+
+export interface LspManager {
+  /** 获取（或惰性创建）某工作区+语言的服务器；refs+1。 */
+  acquire(root: string, languageId: string, resolveSpec: (languageId: string) => LspProviderSpec): LspServer
+  /** 释放引用；refs 归零时停止服务器。 */
+  release(root: string, languageId: string): void
+  /** 释放工作区下全部语言（session/disposed 用）。 */
+  releaseRoot(root: string): void
+  /** 状态快照。 */
+  statusAll(): LspServerStatus[]
+  /** 查询已注册的工作区+语言服务器，不增加引用计数。 */
+  peek(root: string, languageId: string): LspServer | undefined
+  /** 停止并清空全部（卸载/退出）。 */
+  disposeAll(): Promise<void>
+  /** 监听状态变化（用于 UI）。 */
+  onStatusChange: ((status: LspServerStatus) => void) | null
+}
+
+/**
+ * 创建 LSP 管理器。
+ * @author ddj 2026年08月27号
+ * @param logger 诊断日志
+ * @returns 管理器
+ */
+export function createLspManager(logger?: (line: string) => void): LspManager {
+  const entries = new Map<string, Entry>()
+  const keyOf = (root: string, languageId: string): string => root + '|' + languageId
+
+  const log = (line: string): void => logger?.('[lsp-manager] ' + line)
+
+  /** 同步摘除注册表项并后台回收（refs 归零/工作区清理用；statusAll 立即可见归零）。 */
+  const dropEntry = (entry: Entry): void => {
+    if (entry.restartTimer) {
+      clearTimeout(entry.restartTimer)
+      entry.restartTimer = null
+    }
+    entries.delete(entry.key)
+    void entry.server.dispose().catch(() => {})
+  }
+
+  const scheduleRestart = (entry: Entry): void => {
+    if (entry.restartTimer) return
+    if (entry.failures >= MAX_FAILURES) {
+      log('unavailable after ' + entry.failures + ' failures: ' + entry.key)
+      return
+    }
+    const delay = BACKOFF_MS[Math.min(entry.failures, BACKOFF_MS.length - 1)]
+    entry.restartTimer = setTimeout(() => {
+      entry.restartTimer = null
+      if (!entries.has(entry.key)) return
+      void (async () => {
+        const ok = await entry.server.start()
+        if (!ok) entry.failures++
+        else entry.failures = 0
+        if (!ok && entries.has(entry.key)) scheduleRestart(entry)
+      })()
+    }, delay)
+  }
+
+  const manager: LspManager = {
+    acquire(root: string, languageId: string, resolveSpec: (languageId: string) => LspProviderSpec): LspServer {
+      const key = keyOf(root, languageId)
+      let entry = entries.get(key)
+      if (!entry) {
+        const spec = resolveSpec(languageId)
+        const server = createLspServer(spec, root, languageId, log)
+        server.onStateChange = (status) => manager.onStatusChange?.(status)
+        entry = { key, server, refs: 0, failures: 0, restartTimer: null }
+        entries.set(key, entry)
+        // 惰性启动：若 spec ready 才启动，否则保持 idle（供 status 展示 reason）
+        if (spec.ready) {
+          void server.start().then((ok) => {
+            if (!ok && entries.has(key)) entry!.failures++
+          })
+        }
+      }
+      entry.refs++
+      return entry.server
+    },
+
+    release(root: string, languageId: string): void {
+      const entry = entries.get(keyOf(root, languageId))
+      if (!entry) return
+      entry.refs = Math.max(0, entry.refs - 1)
+      if (entry.refs === 0) dropEntry(entry)
+    },
+
+    releaseRoot(root: string): void {
+      for (const entry of [...entries.values()]) {
+        if (entry.server.root === root) dropEntry(entry)
+      }
+    },
+
+    statusAll(): LspServerStatus[] {
+      return [...entries.values()].map((entry) => entry.server.status())
+    },
+
+    peek(root: string, languageId: string): LspServer | undefined {
+      return entries.get(keyOf(root, languageId))?.server
+    },
+
+    async disposeAll(): Promise<void> {
+      const list = [...entries.values()]
+      entries.clear()
+      for (const entry of list) {
+        if (entry.restartTimer) clearTimeout(entry.restartTimer)
+        await entry.server.dispose()
+      }
+    },
+
+    onStatusChange: null,
+  }
+  return manager
+}

package/src/lsp/providers.ts

@@ -0,0 +1,235 @@
+/**
+ * dsh-vscode-mode host — 语言服务器 provider 解析。
+ * 优先级：手动配置 > extmgr 扩展源(Phase 2 挂载) > 自动发现(~/.vscode/extensions、
+ * ~/.dsh/dsh-vscode-mode/extensions、PATH)。产物 LspProviderSpec：{ ready, argv, cwd, reason }，
+ * 供 manager 启动服务器。
+ * 作者 ddj 2026-08-27
+ */
+import { existsSync, readdirSync, type Dirent } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, sep } from 'node:path'
+import { isAbsolute } from 'node:path'
+import { extensionsRoot } from './extmgr.js'
+import { dshHome } from '../paths.js'
+
+/** provider 来源标记（与 shared/lsp.ts 的 status.source 一致）。 */
+export type LspProviderKind = 'extension' | 'discover' | 'manual' | 'none'
+
+export interface LspProviderSpec {
+  languageId: string
+  kind: LspProviderKind
+  argv: string[]
+  cwd?: string
+  ready: boolean
+  reason?: string
+}
+
+/** 语言 → 扩展名（用于判断哪些文件触发该语言服务器）。 */
+export const LSP_LANG_EXT: Record<string, string[]> = {
+  lua: ['lua'],
+  csharp: ['cs', 'csx'],
+}
+
+/** 平台目录名（LuaLS/OmniSharp 的 server/bin/<平台>）。 */
+export function platformServerDir(platform = process.platform): string {
+  if (platform === 'win32') return 'Windows'
+  if (platform === 'darwin') return 'macOS'
+  return 'Linux'
+}
+
+/** exe 后缀（Windows 为 .exe）。 */
+export function exeSuffix(platform = process.platform): string {
+  return platform === 'win32' ? '.exe' : ''
+}
+
+/** 列出目录下匹配前缀的子目录（如 ~/.vscode/extensions/sumneko.lua-*）。 */
+export function listMatchingDirs(dir: string, prefix: string): string[] {
+  if (!existsSync(dir)) return []
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch (error) {
+    return []
+  }
+  return entries.filter((e) => e.isDirectory() && e.name.startsWith(prefix)).map((e) => join(dir, e.name))
+}
+
+/** VSCode 扩展目录（~/.vscode/extensions、~/.vscode-server/extensions + extmgr 目录；无则空数组）。 */
+export function vscodeExtensionsDirs(home = dshHome()): string[] {
+  const userHome = homedir()
+  return [
+    join(userHome, '.vscode', 'extensions'),
+    join(userHome, '.vscode-server', 'extensions'),
+    extensionsRoot(home),
+  ].filter((dir) => existsSync(dir))
+}
+
+// --region 扩展源 provider 挂载点（extmgr 安装扩展后注册；kind=extension）
+/** 扩展源 provider 注册表：languageId → 启动参数。 */
+const extProviders = new Map<string, { argv: string[]; cwd?: string; version?: string }>()
+
+/**
+ * 注册扩展源 provider（extmgr 安装的 VSIX 扩展调用；覆盖/清除传空 argv 可注销）。
+ * @author ddj 2026年08月27号
+ * @param languageId 语言 id
+ * @param argv 启动参数（argv[0] 为可执行）
+ * @param cwd 工作目录
+ * @param version 扩展版本（诊断展示）
+ */
+export function registerExtensionProvider(languageId: string, argv: string[], cwd?: string, version?: string): void {
+  if (!argv.length) {
+    extProviders.delete(languageId)
+    return
+  }
+  extProviders.set(languageId, { argv, cwd, version })
+}
+
+/** 取扩展源 provider spec（未注册返回 null）。 */
+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 }
+}
+
+/** 清空全部扩展源注册（插件卸载/扩展目录重建时）。 */
+export function clearExtensionProviders(): void {
+  extProviders.clear()
+}
+// --endregion
+
+/** PATH 中查找可执行文件（不含扩展名校验，交由 spawn 报错）。 */
+export function findInPath(name: string): string | null {
+  const pathEnv = process.env.PATH ?? ''
+  const exts = process.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : ['']
+  for (const dir of pathEnv.split(sep === '\\' ? ';' : ':')) {
+    if (!dir) continue
+    for (const ext of exts) {
+      const candidate = join(dir, name + ext)
+      if (existsSync(candidate)) return candidate
+    }
+  }
+  return null
+}
+
+/** 查找 dotnet（PATH + 常见安装路径）。 */
+export function findDotnet(): string | null {
+  const inPath = findInPath('dotnet')
+  if (inPath) return inPath
+  const candidates = [
+    'C:/Program Files/dotnet/dotnet.exe',
+    'C:/Program Files (x86)/dotnet/dotnet.exe',
+  ]
+  for (const c of candidates) if (existsSync(c)) return c
+  return null
+}
+
+/** LuaLS 自动发现候选（VSCode 扩展目录 + extmgr 目录下 sumneko.lua-* 的 server/bin 可执行）。 */
+export function candidateLuaServers(home = dshHome()): string[] {
+  const plat = platformServerDir()
+  const suffix = exeSuffix()
+  const out: string[] = []
+  for (const dir of vscodeExtensionsDirs(home)) {
+    for (const extDir of listMatchingDirs(dir, 'sumneko.lua-')) {
+      const binDir = join(extDir, 'server', 'bin')
+      const binName = 'lua-language-server' + suffix
+      // 新布局（3.x 平台变体 vsix）：server/bin/xxx.exe；旧布局：server/bin/<平台>/xxx.exe
+      const bin = existsSync(join(binDir, binName)) ? join(binDir, binName) : join(binDir, plat, binName)
+      if (existsSync(bin) && !out.includes(bin)) out.push(bin)
+    }
+  }
+  return out
+}
+
+/** C# 自动发现候选：Roslyn dll（需 dotnet）或 OmniSharp 可执行。 */
+export function candidateCSharpServers(home = dshHome()): { roslynDll?: string; omnisharpExe?: string; dotnet?: string } {
+  const out: { roslynDll?: string; omnisharpExe?: string; dotnet?: string } = {}
+  for (const dir of vscodeExtensionsDirs(home)) {
+    for (const extDir of listMatchingDirs(dir, 'ms-dotnettools.csharp-')) {
+      const roslyn = join(extDir, '.roslyn', 'Microsoft.CodeAnalysis.LanguageServer.dll')
+      if (!out.roslynDll && existsSync(roslyn)) out.roslynDll = roslyn
+      const omni = join(extDir, '.omnisharp', 'OmniSharp' + exeSuffix())
+      if (!out.omnisharpExe && existsSync(omni)) out.omnisharpExe = omni
+    }
+  }
+  const dotnet = findDotnet()
+  if (dotnet) out.dotnet = dotnet
+  return out
+}
+
+/**
+ * 手动配置归一化：path 指向可执行文件/目录，command 为可执行名（PATH 解析）。
+ * 未配置时返回空 reason（由各 resolve 兜底输出语言相关安装指引文案）。
+ * @author ddj 2026年08月27号
+ */
+export function manualSpec(manual: { command?: string; path?: string } | undefined): { argv: string[]; cwd?: string; ready: boolean; reason?: string } {
+  if (!manual) return { argv: [], ready: false }
+  const pathValue = typeof manual.path === 'string' && manual.path.trim() ? manual.path.trim() : ''
+  const commandValue = typeof manual.command === 'string' && manual.command.trim() ? manual.command.trim() : ''
+  if (!pathValue && !commandValue) return { argv: [], ready: false }
+  if (pathValue) {
+    if (!existsSync(pathValue)) return { argv: [], ready: false, reason: '路径不存在：' + pathValue }
+    return { argv: [pathValue], ready: true }
+  }
+  const found = findInPath(commandValue)
+  if (!found) return { argv: [], ready: false, reason: 'PATH 中找不到命令：' + commandValue }
+  return { argv: [found], ready: true }
+}
+
+/**
+ * 解析 Lua provider（优先级：手动 > 扩展源 > 自动发现）。
+ * @author ddj 2026年08月27号
+ * @param manual 手动配置
+ * @param home DSH home（缺省真实；测试可注入临时目录）
+ * @returns provider 规格
+ */
+export function resolveLuaProvider(manual?: { command?: string; path?: string }, home = dshHome()): LspProviderSpec {
+  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 或手动指定路径）' }
+}
+
+/**
+ * 解析 C# provider（优先级：手动 > 扩展源 > 自动发现；需 dotnet + Roslyn dll；或 OmniSharp）。
+ * @author ddj 2026年08月27号
+ * @param manual 手动配置
+ * @param home DSH home（缺省真实；测试可注入临时目录）
+ * @returns provider 规格
+ */
+export function resolveCSharpProvider(manual?: { command?: string; path?: string }, home = dshHome()): LspProviderSpec {
+  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 入口）' }
+}
+
+/** 语言 → provider 解析器（可扩展；Phase 2 由 extmgr 注册扩展源 provider）。 */
+export type ProviderResolver = (manual?: { command?: string; path?: string }) => LspProviderSpec
+
+export const PROVIDER_RESOLVERS: Record<string, ProviderResolver> = {
+  lua: resolveLuaProvider,
+  csharp: resolveCSharpProvider,
+}
+
+/** 手动配置是否为绝对路径可执行（供设置页判断输入类型）。 */
+export function looksAbsolute(value: string): boolean {
+  return isAbsolute(value)
+}