dsh-vscode-mode 0.1.45 → 0.1.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 dsh-better-sidebar 侧边栏与对话同屏）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚）+ 语言服务器（LSP）智能（跳转定义/引用/hover/大纲 + VSIX 扩展市场安装），状态持久化到工作区旁车",
   "keywords": [
     "dsh",

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

@@ -197,7 +197,16 @@ export async function gotoRefsAt(ed, position) {
   if (!path || !position) return
   const all = await findReferences(path, model.getValue(), position, false)
   const others = filterOtherRefs(all, path, position)
-  if (!others.length) return
+  if (!others.length) {
+    // 0 条「其它」引用：降级查定义（参数/局部变量只被声明时引用为空，定义可经 host 降级链推导）
+    const defs = await findDefinition(path, model.getValue(), position)
+    const first = defs[0]
+    if (!first) return
+    const lspPos = monoToLsp(position.lineNumber, position.column)
+    if (sameFile(targetOpenPath(first), path) && posInRange(lspPos, first.lspRange)) return // 定义即自身：无其它可跳，保持静默
+    jumpToLocation(first)
+    return
+  }
   if (others.length === 1) {
     jumpToLocation(others[0])
     return

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

@@ -0,0 +1,101 @@
+// @ts-nocheck
+/**
+ * dsh-vscode-mode client — Ctrl+hover 可导航标识符下划线提示。
+ * 背景：内嵌 Monaco 构建（0.42.0-dev）无 linkDetection contrib，原生不产生 ctrl+hover 下划线，
+ * 插件自绘：Ctrl/Meta 按住悬停在"语义 token 标识符"上时给词加下划线装饰，移出/松开即清除。
+ * 数据来源于语义 token（每 model+version 缓存 60s），不做逐词 LSP 查询。
+ * 作者 ddj 2026-09-02
+ */
+import { pathOfModel, fetchSemanticTokens } from './lspClient.js'
+import { decodeSemanticTokens, isNavigableTokenType } from '../../../shared/lsp.js'
+
+const CACHE_TTL_MS = 60_000
+
+/**
+ * 给一个 Monaco 编辑器绑定 Ctrl+hover 下划线提示（幂等）。
+ * @author ddj 2026年09月02号
+ * @param ed Monaco 编辑器
+ * @param monaco Monaco 实例
+ */
+export function bindLspUnderline(ed, monaco) {
+  if (!ed || !monaco || ed.__edrvUnderline) return
+  ed.__edrvUnderline = true
+  let decoIds = []
+  let lastKey = null
+  let hoverSeq = 0
+  let cache = { path: null, version: -1, ranges: null, at: 0 }
+
+  const clear = () => {
+    if (decoIds.length) {
+      ed.deltaDecorations(decoIds, [])
+      decoIds = []
+    }
+    lastKey = null
+  }
+
+  /** 取当前文档语义 token 范围（模型版本 + TTL 缓存）。 */
+  const rangesOf = async (model) => {
+    const path = pathOfModel(model)
+    const version = model.getVersionId?.() ?? 0
+    if (cache.path === path && cache.version === version && cache.ranges && Date.now() - cache.at < CACHE_TTL_MS) {
+      return cache.ranges
+    }
+    const res = await fetchSemanticTokens(path, model.getValue()).catch(() => null)
+    const ranges = res && Array.isArray(res.data) ? decodeSemanticTokens(res.data) : []
+    cache = { path, version, ranges, at: Date.now() }
+    return ranges
+  }
+
+  ed.onMouseMove((event) => {
+    const native = event?.event
+    const ctrl = native?.ctrlKey ?? false
+    const meta = native?.metaKey ?? false
+    if (!ctrl && !meta) {
+      clear()
+      hoverSeq++
+      return
+    }
+    const pos = event?.target?.position
+    const model = ed.getModel()
+    if (!pos || !model) {
+      clear()
+      hoverSeq++
+      return
+    }
+    const word = model.getWordAtPosition(pos)
+    if (!word) {
+      clear()
+      hoverSeq++
+      return
+    }
+    const seq = ++hoverSeq
+    const path = pathOfModel(model)
+    void rangesOf(model).then((ranges) => {
+      if (seq !== hoverSeq) return // 鼠标已移走，忽略过期结果
+      const lineIndex = Math.max(0, word.startLineNumber - 1)
+      const startCol = Math.max(0, word.startColumn - 1)
+      const endCol = Math.max(startCol, word.endColumn - 1)
+      const hit = ranges.some((r) => {
+        if (r.start.line !== lineIndex) return false
+        return isNavigableTokenType(r.type) && r.start.character <= startCol && r.end.character >= endCol
+      })
+      if (!hit) {
+        if (lastKey !== null) clear()
+        return
+      }
+      const key = String(path) + ':' + word.startColumn + ':' + word.endColumn
+      if (key === lastKey) return
+      lastKey = key
+      decoIds = ed.deltaDecorations(decoIds, [{
+        range: new monaco.Range(word.startLineNumber, word.startColumn, word.endLineNumber, word.endColumn),
+        options: { inlineClassName: 'edrv-nav-underline' },
+      }])
+    })
+  })
+
+  ed.onMouseLeave(() => clear())
+  ed.onDidBlurEditorText?.(() => clear())
+}
+
+/** 兼容占位（与 providers 的 hideReferencesOverlay 对称，无需真正释放）。 */
+export function disposeLspUnderline() {}

package/src/client/styles/editor.css

@@ -40,6 +40,8 @@
 [data-edrv-view] .edrv-lsp-status-dot.ready { background: var(--dsw-alias-state-success-primary, #0f9d58); }
 [data-edrv-view] .edrv-lsp-status-dot.busy { background: var(--dsw-alias-state-warn-primary, #d97706); animation: edrv-lsp-pulse 1.2s ease-in-out infinite; }
 @keyframes edrv-lsp-pulse { 50% { opacity: .45; } }
+/* Ctrl+hover 可导航标识符下划线提示（绑定 Monaco inlineClassName 装饰） */
+[data-edrv-view] .edrv-nav-underline { text-decoration: underline; text-decoration-color: var(--dsw-alias-interactive-primary, #4fc1ff); text-underline-offset: 1px; cursor: pointer; }
 [data-edrv-view] .edrv-diffchip { font-size: 11px; padding: 2px 10px; border: 1px solid var(--dsw-alias-border-l1, #333); border-radius: 999px; background: var(--dsw-alias-bg-layer-2, transparent); color: var(--dsw-alias-state-warn-primary, #b7791f); cursor: pointer; white-space: nowrap; flex-shrink: 0; }
 [data-edrv-view] .edrv-chip-btn { font-size: 12px; padding: 2px 6px; border: none; background: transparent; color: var(--dsw-alias-label-secondary, #aaa); cursor: pointer; border-radius: 4px; flex-shrink: 0; }
 [data-edrv-view] .edrv-chip-btn:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.06)); }

package/src/client/ui/EditorView.ts

@@ -26,6 +26,7 @@ import { bindingsOf, chordOf, matchEvent, useKeybindingsVersion } from '../keybi
 import { createNavHistory } from '../navHistory.js'
 import { CACHE_KEY } from '../paths.js'
 import { bindLspEditor, runGoToDefinition, runFindReferences, hideReferencesOverlay } from '../monaco/lsp/providers.js'
+import { bindLspUnderline } from '../monaco/lsp/underline.js'
 import { onLspProgress, refreshStatus } from '../monaco/lsp/index.js'
 
 /**
@@ -841,6 +842,7 @@ export function EditorView(props) {
     })
     ed.addCommand(m.KeyCode.F12, () => { void runGoToDefinition(ed) })
     bindLspEditor(ed)
+    bindLspUnderline(ed, m)
     // hover 差异块 → 浮出 Keep/Undo（req：鼠标移到编辑区差异块时显示）
     // 防闪烁：① 区域不变不 setState（浮窗锚定差异块起始行，不跟随鼠标）；② 延迟隐藏；
     // ③ 浮窗自身 onMouseEnter 取消隐藏计时（鼠标在浮窗与编辑器间移动不闪）。

package/src/client/ui/LspSettings.ts

@@ -11,7 +11,7 @@ import '../styles/mcp.css'
 
 const LANGUAGES = [
   { id: 'lua', label: 'Lua（EmmyLua / LuaLS）', hint: '优先使用已安装 EmmyLua；未安装时回退 LuaLS 或 PATH 中的 lua-language-server' },
-  { id: 'csharp', label: 'C#（Roslyn / OmniSharp）', hint: '需 dotnet + ms-dotnettools.csharp 的 .roslyn 服务器，或手动指定' },
+  { id: 'csharp', label: 'C#（Roslyn / DotRush / OmniSharp）', hint: '优先自动发现 ms-dotnettools.csharp / DotRush 扩展（DotRush 需 .NET 10 运行时）；也可手动指定' },
 ]
 
 const PHASE_LABEL = {
@@ -25,8 +25,18 @@ const TABS = [
   { id: 'updates', label: '更新' },
 ]
 
-/** 语言卡片：状态 + 启用开关 + 命令/路径配置 + 重新检测。 */
-function LangCard({ lang, config, status, busy, onToggle, onSave, onRedetect }) {
+/** 环境安装按钮文案（按安装进行态）。 */
+function envButtonLabel(req, envStates) {
+  const state = (envStates ?? []).find((s) => s.id === req.id)
+  if (state?.phase === 'downloading') return '下载中…'
+  if (state?.phase === 'extracting') return '安装中…'
+  if (state?.phase === 'done') return '已完成'
+  if (state?.phase === 'failed') return '重试'
+  return '一键安装'
+}
+
+/** 语言卡片：状态 + 缺失环境提示（一键安装/官网下载） + 启用开关 + 命令/路径配置 + 重新检测。 */
+function LangCard({ lang, config, status, busy, envStates, onInstallEnv, onToggle, onSave, onRedetect }) {
   const [pathDraft, setPathDraft] = React.useState(config?.path ?? '')
   const [commandDraft, setCommandDraft] = React.useState(config?.command ?? '')
   React.useEffect(() => { setPathDraft(config?.path ?? ''); setCommandDraft(config?.command ?? '') }, [config?.path, config?.command])
@@ -44,6 +54,21 @@ function LangCard({ lang, config, status, busy, onToggle, onSave, onRedetect })
       status?.version ? ' · v' + status.version : '',
       (phase === 'ready' && status?.root) ? ' · ' + String(status.root).split(/[\\/]/).pop() : ''),
     status?.reason ? React.createElement('div', { className: 'vsm-mcp-error' }, status.reason) : null,
+    Array.isArray(status?.missingEnv) && status.missingEnv.length
+      ? React.createElement('div', { className: 'vsm-lsp-hint' },
+        '缺少运行环境（一键安装后自动生效）：',
+        status.missingEnv.map((req) => React.createElement('div', { key: req.id, className: 'vsm-mcp-actions' },
+          React.createElement('span', null, req.label, req.detail ? '（' + req.detail + '）' : ''),
+          req.installable ? React.createElement('button', {
+            className: 'vsm-primary vsm-small',
+            disabled: busy === 'env:' + req.id,
+            onClick: () => onInstallEnv(lang.id, req),
+          }, envButtonLabel(req, envStates)) : null,
+          req.manualUrl ? React.createElement('a', {
+            href: req.manualUrl, target: '_blank', rel: 'noreferrer',
+            style: { color: 'inherit', textDecoration: 'underline', alignSelf: 'center' },
+          }, req.manualLabel ?? '官网下载') : null)))
+      : null,
     React.createElement('div', { className: 'vsm-lsp-form' },
       React.createElement('label', null, React.createElement('span', null, '可执行文件路径（绝对路径，优先）'), React.createElement('input', { value: pathDraft, placeholder: '如 C:/.../lua-language-server.exe', onChange: (e) => setPathDraft(e.target.value) })),
       React.createElement('label', null, React.createElement('span', null, '命令名（PATH 内查找）'), React.createElement('input', { value: commandDraft, placeholder: '如 lua-language-server', onChange: (e) => setCommandDraft(e.target.value) })),
@@ -96,6 +121,8 @@ export function LspSettings() {
   const [busy, setBusy] = React.useState('')
   const [error, setError] = React.useState('')
   const [loading, setLoading] = React.useState(true)
+  const [envStates, setEnvStates] = React.useState([])
+  const [envLang, setEnvLang] = React.useState('')
 
   const refreshServers = React.useCallback(() => {
     Promise.all([rpc('edrv.lsp.configGet', {}), rpc('edrv.lsp.status', {})])
@@ -117,6 +144,15 @@ export function LspSettings() {
       .catch((e) => setError(String(e)))
   }, [])
 
+  const refreshEnvStates = React.useCallback(() => {
+    return rpc('edrv.lsp.envState', {})
+      .then((res) => {
+        if (res?.ok) setEnvStates(res.states ?? [])
+        return res?.states ?? []
+      })
+      .catch(() => [])
+  }, [])
+
   const refresh = React.useCallback(() => {
     setLoading(true)
     Promise.all([refreshServers(), refreshExt()]).finally(() => setLoading(false))
@@ -140,10 +176,52 @@ export function LspSettings() {
   }
 
   /** 重检测后通知编辑器：与 host 重新同步已打开的模型（触发重新 acquire）。 */
-  const notifyResync = (languageId) => {
+  const notifyResync = React.useCallback((languageId) => {
     window.dispatchEvent(new CustomEvent('edrv:lsp-redetect', { detail: { languageId } }))
+  }, [])
+
+  /** 一键安装缺失环境：启动内置安装器（成功后进入轮询，完成自动重同步）。 */
+  const installEnv = (languageId, req) => {
+    const key = 'env:' + req.id
+    setBusy(key)
+    setError('')
+    setEnvLang(languageId)
+    rpc('edrv.lsp.envInstall', { languageId, id: req.id })
+      .then((res) => {
+        if (!res?.ok) { setError(res?.error ?? '无法启动安装'); return }
+        void refreshEnvStates()
+        void refreshServers()
+      })
+      .catch((e) => setError(String(e)))
+      .finally(() => setBusy(''))
   }
 
+  // 环境安装进行中：2s 轮询进度并刷新状态；某项转入 done 时由下方过渡检测重同步
+  React.useEffect(() => {
+    const states = envStates ?? []
+    const installing = states.some((s) => s.phase === 'downloading' || s.phase === 'extracting')
+    if (!installing) return
+    const timer = setInterval(() => {
+      void refreshEnvStates()
+      void refreshServers()
+    }, 2000)
+    return () => clearInterval(timer)
+  }, [envStates, refreshEnvStates, refreshServers])
+
+  // 环境安装完成过渡检测：刷新状态并通知编辑器重新同步对应语言
+  const prevEnvPhases = React.useRef({})
+  React.useEffect(() => {
+    const states = envStates ?? []
+    for (const s of states) {
+      const prev = prevEnvPhases.current[s.id]
+      if (prev && prev !== 'done' && s.phase === 'done' && envLang) {
+        void refreshServers()
+        notifyResync(envLang)
+      }
+      prevEnvPhases.current[s.id] = s.phase
+    }
+  }, [envStates, envLang, refreshServers, notifyResync])
+
   const saveLang = (languageId, path, command) => {
     setBusy(languageId)
     setError('')
@@ -271,7 +349,7 @@ export function LspSettings() {
         key: lang.id, lang,
         config: config[lang.id] ?? {},
         status: servers.find((s) => s.languageId === lang.id),
-        busy, onToggle: toggleLang, onSave: saveLang, onRedetect: redetectLang,
+        busy, envStates, onInstallEnv: installEnv, onToggle: toggleLang, onSave: saveLang, onRedetect: redetectLang,
       })),
       React.createElement('div', { className: 'vsm-lsp-hint' }, '提示：打开 Lua/C# 文件即自动（惰性）启动对应语言服务器；未配置时编辑器功能不受影响，大纲回退内置解析。')))
   } else if (tab === 'installed') {

package/src/lsp/client.ts

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

package/src/lsp/config.ts

@@ -5,6 +5,7 @@
  */
 import type { Ctx } from '../store.js'
 import { PROVIDER_RESOLVERS, type LspProviderSpec } from './providers.js'
+import { provisionRuntime } from './dotnetProvision.js'
 
 /** 单语言配置。 */
 export interface LspLangConfig {
@@ -91,7 +92,10 @@ export function resolveProviderSpec(ctx: Ctx, pluginConfig: unknown, languageId:
   if (lang && lang.enabled === false) {
     return { languageId, kind: 'none', argv: [], ready: false, reason: '已在设置中禁用' }
   }
-  return resolver({ command: lang?.command, path: lang?.path })
+  const spec = resolver({ command: lang?.command, path: lang?.path })
+  // DotRush 缺运行时：后台自动下载官方 .NET runtime（用户零操作），完成后经监听者重载
+  if (spec.provisionRuntime) provisionRuntime(spec.provisionRuntime)
+  return spec
 }
 
 /** 语言 → 扩展名（供客户端判断是否触发 LSP）。 */

package/src/lsp/derive.ts

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

package/src/lsp/dotnetProvision.ts

@@ -0,0 +1,224 @@
+/**
+ * dsh-vscode-mode host — C# 服务器 .NET 运行时自动配置。
+ * DotRush 等服务器需要 .NET 运行时；缺失时从官方 release 元数据解析下载地址，
+ * sha512 校验后解压到用户级 dotnet 目录（win: %LOCALAPPDATA%\Microsoft\dotnet，
+ * unix: ~/.dotnet），成功后通知监听者重载 provider——用户零手动操作。
+ * 失败静默降级（保留原 reason 文案），10 分钟退避重试。
+ * 安装全程有状态机（envInstallStates）供设置页一键安装与进度轮询使用。
+ * 作者 ddj 2026年09月03号
+ */
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { dotnetWithRuntime } from './providers.js'
+import type { LspEnvInstallState } from '../shared/lsp.js'
+import { unzip } from './zip.js'
+
+/** release 元数据 files 元素子集（官方 releases.json）。 */
+export interface RuntimeAsset {
+  name: string
+  url: string
+  hash: string
+}
+
+const META_BASE = 'https://builds.dotnet.microsoft.com/dotnet/release-metadata'
+const RETRY_MS = 10 * 60 * 1000
+
+/** 同 major 去重（in-flight）。 */
+const inFlight = new Map<number, Promise<boolean>>()
+/** 失败时间戳（退避重试）。 */
+const failedAt = new Map<number, number>()
+/** 配置成功监听者（重载 provider 缓存与服务器）。 */
+const listeners = new Set<() => void>()
+/** 安装进行态（major → phase/message），供设置页轮询展示。 */
+const installStates = new Map<number, { phase: LspEnvInstallState['phase']; message?: string }>()
+
+/** 需求 id（与 envRequirements 的 id 一致）。 */
+export function runtimeRequirementId(major: number): string {
+  return 'dotnet-runtime:' + major
+}
+
+/** 当前安装进行态快照（edrv.lsp.envState 载荷）。 */
+export function envInstallStates(): LspEnvInstallState[] {
+  return [...installStates.entries()].map(([major, state]) => ({
+    id: runtimeRequirementId(major),
+    phase: state.phase,
+    message: state.message,
+  }))
+}
+
+/** 注册配置成功监听（成功后由 rpc 侧清缓存并重置服务器）。 */
+export function onRuntimeProvisioned(listener: () => void): void {
+  listeners.add(listener)
+}
+
+/** 平台 → 官方运行时资产文件名。 */
+function assetNameFor(platform: string, arch: string): string {
+  const archPart = arch === 'arm64' ? 'arm64' : 'x64'
+  if (platform === 'win32') return 'dotnet-runtime-win-' + archPart + '.zip'
+  if (platform === 'darwin') return 'dotnet-runtime-osx-' + archPart + '.tar.gz'
+  return 'dotnet-runtime-linux-' + archPart + '.tar.gz'
+}
+
+/** 用户级 dotnet 安装目录（与 providers 的发现候选位置一致）。 */
+export function userDotnetDir(): string {
+  if (process.platform === 'win32') {
+    return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'Microsoft', 'dotnet')
+  }
+  return join(homedir(), '.dotnet')
+}
+
+/** 从 release 元数据 files 里挑当前平台资产（纯函数，测试可注入平台）。 */
+export function pickRuntimeAsset(files: RuntimeAsset[], platform = process.platform, arch = process.arch): RuntimeAsset | null {
+  const name = assetNameFor(platform, arch)
+  return files.find((f) => f.name === name) ?? null
+}
+
+/** 是否允许自动配置（测试隔离 + 显式开关）。 */
+function allowed(): boolean {
+  if (process.env.DSH_LSP_AUTO_RUNTIME === '0') return false
+  if (process.env.DSH_LSP_EXT_DIRS) return false // 测试环境不下载
+  return true
+}
+
+function setState(major: number, phase: LspEnvInstallState['phase'], message?: string): void {
+  installStates.set(major, { phase, message })
+}
+
+function notifyListeners(): void {
+  for (const listener of listeners) {
+    try {
+      listener()
+    } catch { /* 单个监听失败不影响其它 */ }
+  }
+}
+
+/**
+ * 触发运行时自动配置（幂等：同 major 去重；失败 10 分钟退避；已满足则直接成功回调）。
+ * 静默自动路径与设置页一键安装共用；进度经 envInstallStates 暴露。
+ * @author ddj 2026年09月03号
+ * @param major 运行时大版本
+ */
+export function provisionRuntime(major: number): void {
+  if (inFlight.has(major)) return
+  const failed = failedAt.get(major)
+  if (failed && Date.now() - failed < RETRY_MS) return
+  const task = runProvision(major)
+    .catch(() => false)
+    .then((ok) => {
+      inFlight.delete(major)
+      if (ok) {
+        failedAt.delete(major)
+        setState(major, 'done')
+        notifyListeners()
+      } else {
+        failedAt.set(major, Date.now())
+        setState(major, 'failed')
+      }
+      return ok
+    })
+  inFlight.set(major, task)
+}
+
+/**
+ * 一键安装入口（设置页按钮）：校验允许后触发 provisionRuntime。
+ * @author ddj 2026年09月03号
+ * @param major 运行时大版本
+ * @returns 是否成功启动（已满足/进行中/被禁用时返回 false）
+ */
+export function startEnvInstall(major: number): boolean {
+  if (dotnetWithRuntime(major)) {
+    setState(major, 'done')
+    return false
+  }
+  if (!allowed() || inFlight.has(major)) return false
+  const failed = failedAt.get(major)
+  if (failed && Date.now() - failed < RETRY_MS && installStates.get(major)?.phase === 'failed') {
+    // 退避期内失败态：允许用户手动重试（清除退避标记）
+    failedAt.delete(major)
+  }
+  provisionRuntime(major)
+  return inFlight.has(major)
+}
+
+async function runProvision(major: number): Promise<boolean> {
+  if (dotnetWithRuntime(major)) return true
+  setState(major, 'downloading')
+  const meta = await fetchJson(META_BASE + '/' + major + '.0/releases.json')
+  const release = meta?.releases?.[0]
+  const files = release?.runtime?.files
+  if (!Array.isArray(files)) return false
+  const asset = pickRuntimeAsset(files as RuntimeAsset[])
+  if (!asset?.url || !asset.hash) return false
+  const buf = await downloadVerified(asset.url, asset.hash)
+  if (!buf) return false
+  setState(major, 'extracting')
+  const dir = userDotnetDir()
+  const created = !existsSync(dir)
+  try {
+    const ok = await extractTo(buf, dir)
+    if (!ok) throw new Error('解压失败')
+  } catch (error) {
+    if (created) rmSync(dir, { recursive: true, force: true })
+    return false
+  }
+  return dotnetWithRuntime(major) !== null
+}
+
+/** 拉取 JSON（30s 超时，失败返回 null）。 */
+async function fetchJson(url: string): Promise<{ releases?: { runtime?: { files?: unknown } }[] } | null> {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(30000) })
+    if (!res.ok) return null
+    return await res.json()
+  } catch {
+    return null
+  }
+}
+
+/** 下载并按官方 sha512 校验（5 分钟超时，不匹配返回 null）。 */
+async function downloadVerified(url: string, sha512: string): Promise<Buffer | null> {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(300000) })
+    if (!res.ok) return null
+    const buf = Buffer.from(await res.arrayBuffer())
+    const actual = createHash('sha512').update(buf).digest('hex').toLowerCase()
+    return actual === sha512.toLowerCase() ? buf : null
+  } catch {
+    return null
+  }
+}
+
+/** 解压到目录：win 走 zip（PK 头），unix 落临时包交系统 tar。 */
+async function extractTo(buf: Buffer, dir: string): Promise<boolean> {
+  mkdirSync(dir, { recursive: true })
+  if (buf.subarray(0, 2).toString('ascii') === 'PK') {
+    for (const entry of unzip(buf)) {
+      if (!entry.path || entry.path.startsWith('..')) continue
+      const parts = entry.path.split(/[\\/]/).filter((p) => p && p !== '..' && p !== '.')
+      if (!parts.length) continue
+      const target = join(dir, ...parts)
+      if (entry.isDirectory) {
+        mkdirSync(target, { recursive: true })
+        continue
+      }
+      mkdirSync(dirname(target), { recursive: true })
+      writeFileSync(target, entry.data)
+    }
+    return true
+  }
+  const tmp = join(tmpdir(), 'dsh-dotnet-' + Date.now() + '.tar.gz')
+  try {
+    writeFileSync(tmp, buf)
+    return await new Promise<boolean>((resolve) => {
+      const child = spawn('tar', ['-xzf', tmp, '-C', dir], { stdio: 'ignore' })
+      child.on('exit', (code) => resolve(code === 0))
+      child.on('error', () => resolve(false))
+    })
+  } finally {
+    rmSync(tmp, { force: true })
+  }
+}