dsh-vscode-mode 0.1.46 → 0.1.48

package/package.json

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

package/src/client/addToConversation.ts

@@ -15,6 +15,21 @@ export interface RefRange {
 /** 引用动作的返回状态。 */
 export type AddOutcome = 'ok' | 'busy' | 'unavailable'
 
+/** 引用外观类型：文件/文件夹（DSH reference source 均支持）。 */
+export type RefAppearance = 'file' | 'folder'
+
+/** 把追加引用结果映射为可读文案（ok 用 okText；busy 提示已降级纯文本；unavailable 提示不可用）。
+ * @author ddj 2026年09月03号
+ * @param outcome 追加结果状态
+ * @param okText 成功文案（如「已添加文件引用」/「已添加文件夹引用」）
+ * @returns 状态栏/通知用文案
+ */
+export function statusOfAdd(outcome: AddOutcome, okText: string): string {
+  if (outcome === 'ok') return okText
+  if (outcome === 'busy') return okText + '（输入框忙，已降级纯文本）'
+  return '无法添加到对话（无会话或输入框不可用）'
+}
+
 /** DSH reference source 名（dsh-client-ui-reference 注册的 @file/@session 统一源）。 */
 const REF_SOURCE = 'reference'
 
@@ -61,11 +76,17 @@ export function refOf(mention: string, range: RefRange | undefined): string {
     : `${mention} L${range.startLine}-${range.endLine}`
 }
 
-/** 构造 DSH 文件引用插入载荷（source=reference，发送序列化为 mention(+range) 文本）。 */
+/** 构造 DSH 文件引用插入载荷（source=reference，发送序列化为 mention(+range) 文本）。
+ * @param path 目标路径（相对 cwd 或绝对）
+ * @param cwd 会话工作区目录（可选）
+ * @param range 行区间（可选）
+ * @param appearance 引用外观：'file'（默认）| 'folder'
+ */
 export function buildFileRef(
   path: string,
   cwd: string | undefined,
   range?: RefRange,
+  appearance: RefAppearance = 'file',
 ): { reference: ReferenceInsertLike; mention: string } {
   const mention = mentionOf(path, cwd)
   return {
@@ -74,7 +95,7 @@ export function buildFileRef(
       source: REF_SOURCE,
       ref: refOf(mention, range),
       label: labelOf(path, range),
-      appearance: 'file',
+      appearance,
       clipboardText: mention,
     },
   }
@@ -85,7 +106,6 @@ export interface InputLike {
   state: { getSnapshot: () => { draft: string; draftRev: number } }
   insertReference: (ref: ReferenceInsertLike, span: TokenSpanLike) => boolean
   setDraft: (text: string) => void
-  notify: (level: 'info' | 'error', text: string) => void
 }
 
 /** ReferenceInsert 结构形状（与 dsh-client-ui-input-trigger 类型一致）。 */
@@ -111,8 +131,13 @@ export interface CtxLike {
 
 /** 注入器产物：给 EditorView 用的动作集合。 */
 export interface AddToConversation {
-  /** 追加文件引用 chip（@path [Lstart-end]）；忙态自动降级纯文本。 */
-  appendReference(sessionId: string | undefined, path: string, range?: RefRange): Promise<AddOutcome>
+  /** 追加文件/文件夹引用 chip（@path [Lstart-end]）；忙态自动降级纯文本。 */
+  appendReference(
+    sessionId: string | undefined,
+    path: string,
+    range?: RefRange,
+    appearance?: RefAppearance,
+  ): Promise<AddOutcome>
 }
 
 /**
@@ -161,16 +186,6 @@ function cwdOf(ctx: CtxLike, sessionId: string | undefined): string | undefined
   }
 }
 
-/** 写入成功后的 composer 内联提示（门面可用时；失败静默）。
- * @author ddj 2026年08月25号 */
-function notify(input: InputLike, text: string): void {
-  try {
-    input.notify?.('info', text)
-  } catch {
-    /* 提示失败忽略 */
-  }
-}
-
 /** 输入门面插入引用（拦截异常视作未应用，走降级）。
  * @author ddj 2026年08月25号 */
 function safeInsert(input: InputLike, reference: ReferenceInsertLike, span: TokenSpanLike): boolean {
@@ -188,22 +203,20 @@ function safeInsert(input: InputLike, reference: ReferenceInsertLike, span: Toke
  * @returns 动作集
  */
 export function createAddToConversation(ctx: CtxLike): AddToConversation {
-  const appendReference: AddToConversation['appendReference'] = async (sessionId, path, range) => {
+  const appendReference: AddToConversation['appendReference'] = async (sessionId, path, range, appearance) => {
     const input = inputFor(ctx, sessionId)
     if (!input) return 'unavailable'
     const cur = draftCursor(input)
     if (!cur) return 'unavailable'
-    const { reference, mention } = buildFileRef(path, cwdOf(ctx, sessionId), range)
+    const { reference, mention } = buildFileRef(path, cwdOf(ctx, sessionId), range, appearance)
     const span: TokenSpanLike = { start: cur.draft.length, end: cur.draft.length, draftRev: cur.draftRev }
     const ok = safeInsert(input, reference, span)
     if (!ok) {
       // 忙态（adjudicating/submitting）或 CAS 失败：降级纯文本追加，保证动作有落点。
       const gap = cur.draft.length > 0 && !/\s$/.test(cur.draft) ? ' ' : ''
       input.setDraft(cur.draft + gap + mention + ' ')
-      notify(input, '已添加文件引用 ' + mention)
       return 'busy'
     }
-    notify(input, '已添加文件引用 ' + mention)
     return 'ok'
   }
 

package/src/client/sidebar/menuItems.ts

@@ -1,10 +1,12 @@
 /**
  * dsh-vscode-mode client — 文件管理右键菜单内置项。
- * 首个内置项：「在文件浏览器中打开」（文件→OS Explorer 定位选中、目录→打开目录）。
+ * 内置项：「在文件浏览器中打开」（文件→OS Explorer 定位选中、目录→打开目录）；
+ * 「添加引用到对话」（文件/文件夹引用注入当前会话对话输入框）。
  * 反馈统一走 ctx.notify（由 EditorView 提供，落到编辑区路径栏状态）。
- * 作者 ddj 2026-08-27
+ * 作者 ddj 2026-08-27 / 2026-09-03
  */
 import { revealInExplorer } from '../fileReveal.js'
+import { statusOfAdd } from '../addToConversation.js'
 import type { TreeMenuItem } from './contextMenu.js'
 
 /**
@@ -24,5 +26,24 @@ export function createDefaultFileMenuItems(): TreeMenuItem[] {
         })
       },
     },
+    {
+      id: 'add-to-conversation',
+      label: '添加引用到对话',
+      order: 1,
+      // 排除根目录空白区（path==='' 无意义）、无会话、动作集缺失时隐藏
+      visible: (target, ctx) => Boolean(target.path && ctx.sessionId && ctx.addToConversation),
+      run: (target, ctx) => {
+        const isDir = target.type === 'directory'
+        const add = ctx.addToConversation
+        if (!add) {
+          ctx.notify?.('添加到对话不可用')
+          return
+        }
+        const okText = isDir ? '已添加文件夹引用' : '已添加文件引用'
+        void add.appendReference(ctx.sessionId, target.path, undefined, isDir ? 'folder' : 'file').then((outcome) => {
+          ctx.notify?.(statusOfAdd(outcome, okText))
+        })
+      },
+    },
   ]
 }

package/src/client/sidebar/panels/FileExplorer.ts

@@ -11,7 +11,6 @@
 import React from 'react'
 import { rpc } from '../../rpc.js'
 import { ContextMenu } from '../../ui/ContextMenu.js'
-import { rowMenuPosition } from '../../ui/menuPosition.js'
 import { buildTreeMenu } from '../contextMenu.js'
 import { explorerLoad, explorerSave } from '../../state/explorerCache.js'
 import { entriesCacheGet, entriesCacheIsFresh, entriesCachePut } from '../../state/explorerEntriesCache.js'
@@ -219,9 +218,8 @@ export function FileExplorer(props) {
       onContextMenu: (ev) => {
         ev.preventDefault()
         ev.stopPropagation()
-        const rect = ev.currentTarget?.getBoundingClientRect?.()
-        const position = rowMenuPosition(rect, ev.clientX, ev.clientY)
-        setMenu({ x: position.left, y: position.top, target: { path: e.path, type: e.type } })
+        // 菜单左上角对齐鼠标点击位置（视口坐标，ContextMenu 内再做 viewport clamp）
+        setMenu({ x: ev.clientX, y: ev.clientY, target: { path: e.path, type: e.type } })
       },
     },
       React.createElement('span', { className: 'edrv-tree-chev' },

package/src/client/sidebar/types.ts

@@ -4,6 +4,7 @@
  * 作者 ddj 2026-08-26
  */
 import type { OutlineSourceRegistry } from '../outline/types.js'
+import type { AddToConversation } from '../addToConversation.js'
 import type { TreeMenuRegistry } from './contextMenu.js'
 
 /** 面板可用的共享上下文（由 SidebarView 从 EditorView 注入，面板不直碰其内部）。 */
@@ -25,6 +26,8 @@ export interface SidebarCtx {
   outlineSources?: OutlineSourceRegistry
   /** 文件右键菜单项注册表（公开 provide 为 edrvFileContextMenuItems；文件管理面板构建菜单用）。 */
   fileMenuItems?: TreeMenuRegistry
+  /** 「添加到对话」动作集（文件/文件夹引用注入对话输入框；缺省时菜单项降级提示）。 */
+  addToConversation?: AddToConversation
   /** 面板动作反馈（如右键菜单操作结果 → 编辑区路径栏状态）。 */
   notify?: (message: string) => void
 }

package/src/client/ui/EditorView.ts

@@ -24,6 +24,7 @@ import { setSidePending, SIDEBAR_INSTALL_CMD } from '../sidebarBridge.js'
 import { upsertViewState, viewStatesLoad, viewStatesSave } from '../state/viewStateCache.js'
 import { bindingsOf, chordOf, matchEvent, useKeybindingsVersion } from '../keybindings.js'
 import { createNavHistory } from '../navHistory.js'
+import { statusOfAdd } from '../addToConversation.js'
 import { CACHE_KEY } from '../paths.js'
 import { bindLspEditor, runGoToDefinition, runFindReferences, hideReferencesOverlay } from '../monaco/lsp/providers.js'
 import { bindLspUnderline } from '../monaco/lsp/underline.js'
@@ -1119,15 +1120,7 @@ export function EditorView(props) {
     setTabMenu(null)
   }
 
-  /** 把「添加到对话」返回状态映射为状态栏文案。
-   * @author ddj 2026年08月25号 */
-  const statusOfAdd = (outcome, okText) => {
-    if (outcome === 'ok') return okText
-    if (outcome === 'busy') return okText + '（输入框忙，已降级纯文本）'
-    return '无法添加到对话（无会话或输入框不可用）'
-  }
-
-  /** 添加文件/选中区引用到对话（异步，状态栏反馈）。 */
+  /** 添加文件/选中区引用到对话（异步，状态栏反馈；状态文案走共享 statusOfAdd）。 */
   const addRefToChat = (path, range) => {
     if (!path) { setStatus('无活动文件'); return }
     if (!addToConversation) { setStatus('添加到对话不可用'); return }
@@ -1406,6 +1399,7 @@ export function EditorView(props) {
     editor: () => editorRef.current,
     outlineSources: props.outlineSources,
     fileMenuItems: props.fileMenuItems,
+    addToConversation,
     notify: (message) => setStatus(message),
   }
 

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/client/ui/menuPosition.ts

@@ -1,7 +1,7 @@
 /**
  * dsh-vscode-mode client — 右键菜单 viewport 定位纯函数。
- * 将目标行锚点与视口边界计算从 React 渲染层拆出，便于复用和单测。
- * 作者 ddj 2026-08-28
+ * 将视口边界 clamp 从 React 渲染层拆出，便于复用和单测。
+ * 作者 ddj 2026-08-28 / 2026-09-03
  */
 
 export interface MenuPosition {
@@ -9,13 +9,6 @@ export interface MenuPosition {
   top: number
 }
 
-export interface MenuAnchorRect {
-  top: number
-  right: number
-  width: number
-  height: number
-}
-
 /**
  * 将菜单坐标限制在 viewport 内。
  * @author ddj 2026年08月28号
@@ -42,22 +35,3 @@ export function clampMenuPosition(
     top: Math.max(4, Math.min(y, maxTop)),
   }
 }
-
-/**
- * 将文件树行右键菜单锚定到目标行右侧；无法测量时回退到鼠标坐标。
- * @author ddj 2026年08月28号
- * @param rect 目标行的布局矩形
- * @param fallbackX 鼠标 viewport x 坐标
- * @param fallbackY 鼠标 viewport y 坐标
- * @returns 菜单初始位置
- */
-export function rowMenuPosition(
-  rect: MenuAnchorRect | null | undefined,
-  fallbackX: number,
-  fallbackY: number,
-): MenuPosition {
-  if (!rect || rect.width <= 0 || rect.height <= 0) {
-    return { left: fallbackX, top: fallbackY }
-  }
-  return { left: rect.right + 4, top: rect.top }
-}

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/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 })
+  }
+}