dsh-vscode-mode 0.1.45 → 0.1.47

package/lib/index.js

@@ -3,7 +3,7 @@ import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/p
 import { basename, dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { inflateRawSync } from "node:zlib";
@@ -5760,6 +5760,7 @@ function createLspClient(transport, events = {}) {
 	const pending = /* @__PURE__ */ new Map();
 	let serverCapabilities = {
 		definition: false,
+		declaration: false,
 		references: false,
 		documentSymbol: false,
 		workspaceSymbol: false,
@@ -5894,6 +5895,7 @@ function createLspClient(transport, events = {}) {
 							didSave: true
 						},
 						definition: { dynamicRegistration: false },
+						declaration: { dynamicRegistration: false },
 						references: { dynamicRegistration: false },
 						documentSymbol: { dynamicRegistration: false },
 						hover: { dynamicRegistration: false },
@@ -5913,6 +5915,7 @@ function createLspClient(transport, events = {}) {
 			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),
@@ -5966,6 +5969,73 @@ function pathToFileUri(absPath) {
 	return pathToFileURL(normalized).toString();
 }
 //#endregion
+//#region src/lsp/derive.ts
+/** file:// URI（或裸路径）→ 归一化绝对路径（小写、/ 分隔）。 */
+function normAbs(uri) {
+	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, range) {
+	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, range) {
+	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, b) {
+	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) {
+	return (r.end.line - r.start.line) * 1e6 + (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
+*/
+function deriveDefinitionFromLocations(queryPos, locations, docText, docAbsPath) {
+	if (!locations.length) return null;
+	const docAbs = normAbs(docAbsPath);
+	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;
+	const first = candidates[0];
+	return sameRange(first.range, containing.range) ? containing : first;
+}
+//#endregion
 //#region src/lsp/server.ts
 /**
 * dsh-vscode-mode host — 单语言服务器会话（绑定 工作区根 + 语言）。
@@ -5990,6 +6060,7 @@ function createLspServer(spec, root, languageId, logger) {
 	let client = null;
 	let capabilities = {
 		definition: false,
+		declaration: false,
 		references: false,
 		documentSymbol: false,
 		workspaceSymbol: false,
@@ -6095,7 +6166,8 @@ function createLspServer(spec, root, languageId, logger) {
 			try {
 				transport = spawnServer({
 					argv: spec.argv,
-					cwd: spec.cwd ?? root
+					cwd: spec.cwd ?? root,
+					env: spec.env
 				}, (message) => {}, (line) => log("stderr: " + line));
 				client = createLspClient(transport, {
 					onReady: (caps) => {
@@ -6123,7 +6195,9 @@ function createLspServer(spec, root, languageId, logger) {
 					},
 					onLog: (line) => log("lsp: " + line)
 				});
-				capabilities = await client.initialize(rootUri, [rootUri]);
+				const caps = await client.initialize(rootUri, [rootUri]);
+				if (languageId === "csharp") client.notify("workspace/didChangeConfiguration", { settings: { dotrush: { roslyn: {} } } });
+				capabilities = caps;
 				return true;
 			} catch (error) {
 				log("start failed: " + String(error));
@@ -6173,13 +6247,42 @@ function createLspServer(spec, root, languageId, logger) {
 		async definition(path, line, character) {
 			const doc = docs.get(path);
 			if (!doc || !await readyWait) return [];
-			return normalizeLocations(await ensureClient().request("textDocument/definition", {
+			const client = ensureClient();
+			const position = {
+				line,
+				character
+			};
+			const direct = normalizeLocations(await client.request("textDocument/definition", {
 				textDocument: { uri: doc.uri },
-				position: {
-					line,
-					character
-				}
+				position
 			}));
+			if (direct.length) return direct;
+			if (capabilities.declaration) try {
+				const decl = normalizeLocations(await client.request("textDocument/declaration", {
+					textDocument: { uri: doc.uri },
+					position
+				}));
+				if (decl.length) {
+					log("definition fallback → declaration (" + path + ":" + line + ":" + character + ")");
+					return decl;
+				}
+			} catch (error) {
+				log("declaration request failed: " + String(error));
+			}
+			try {
+				const derived = deriveDefinitionFromLocations(position, normalizeLocations(await client.request("textDocument/references", {
+					textDocument: { uri: doc.uri },
+					position,
+					context: { includeDeclaration: true }
+				})), doc.text, doc.uri);
+				if (derived) {
+					log("definition fallback → references-derived (" + path + ":" + line + ":" + character + ")");
+					return [derived];
+				}
+			} catch (error) {
+				log("references fallback failed: " + String(error));
+			}
+			return [];
 		},
 		async references(path, line, character, includeDeclaration) {
 			const doc = docs.get(path);
@@ -6700,8 +6803,9 @@ async function updateExtension(id) {
 /**
 * dsh-vscode-mode host — 语言服务器 provider 解析。
 * 优先级：手动配置 > extmgr 扩展源(Phase 2 挂载) > 自动发现(~/.vscode/extensions、
-* ~/.dsh/dsh-vscode-mode/extensions、PATH)。产物 LspProviderSpec：{ ready, argv, cwd, reason }，
-* 供 manager 启动服务器。
+* ~/.dsh/dsh-vscode-mode/extensions、PATH)。C# 自动发现覆盖 ms-dotnettools.csharp
+* （Roslyn/OmniSharp）与 DotRush（自带 DotRush.dll 服务器，需对应 .NET 运行时）。
+* 产物 LspProviderSpec：{ ready, argv, cwd, reason }，供 manager 启动服务器。
 * 作者 ddj 2026-08-27
 */
 /** 平台目录名（LuaLS/OmniSharp 的 server/bin/<平台>）。 */
@@ -6725,8 +6829,14 @@ function listMatchingDirs(dir, prefix) {
 	}
 	return entries.filter((e) => e.isDirectory() && e.name.startsWith(prefix)).map((e) => join(dir, e.name));
 }
-/** VSCode 扩展目录（~/.vscode/extensions、~/.vscode-server/extensions + extmgr 目录；无则空数组）。 */
+/**
+* VSCode 扩展目录（~/.vscode/extensions、~/.vscode-server/extensions + extmgr 目录；无则空数组）。
+* 测试可用 DSH_LSP_EXT_DIRS（平台路径分隔符分隔）完全覆盖扫描列表，避免受真实机器扩展影响。
+* @author ddj 2026年09月03号
+*/
 function vscodeExtensionsDirs(home = dshHome()) {
+	const override = process.env.DSH_LSP_EXT_DIRS;
+	if (override) return override.split(sep === "\\" ? ";" : ":").map((dir) => dir.trim()).filter((dir) => dir && existsSync(dir));
 	const userHome = homedir();
 	return [
 		join(userHome, ".vscode", "extensions"),
@@ -6747,7 +6857,7 @@ function extensionProviderFor(languageId) {
 		cwd: p.cwd,
 		ready: true,
 		version: p.version,
-		providerName: p.version ? "EmmyLua" : "语言服务器扩展"
+		providerName: "语言服务器扩展"
 	};
 }
 /** PATH 中查找可执行文件（不含扩展名校验，交由 spawn 报错）。 */
@@ -6768,27 +6878,104 @@ function findInPath(name) {
 	}
 	return null;
 }
+/** dotnet 候选（PATH 命中 + 常见安装路径 + 用户级安装位置），仅保留真实存在者。 */
+function dotnetCandidates() {
+	const localAppData = process.env.LOCALAPPDATA;
+	return [
+		findInPath("dotnet"),
+		"C:/Program Files/dotnet/dotnet.exe",
+		"C:/Program Files (x86)/dotnet/dotnet.exe",
+		localAppData ? join(localAppData, "Microsoft", "dotnet", "dotnet.exe") : null
+	].filter((p) => !!p && existsSync(p));
+}
 /** 查找 dotnet（PATH + 常见安装路径）。 */
 function findDotnet() {
-	const inPath = findInPath("dotnet");
-	if (inPath) return inPath;
-	for (const c of ["C:/Program Files/dotnet/dotnet.exe", "C:/Program Files (x86)/dotnet/dotnet.exe"]) if (existsSync(c)) return c;
+	return dotnetCandidates()[0] ?? null;
+}
+/**
+* 查找具备指定 .NET 运行时大版本的 dotnet（按 dotnetCandidates 顺序探测）。
+* @author ddj 2026年09月03号
+* @param minMajor 运行时最低大版本（如 10）
+* @param candidates dotnet 候选路径（缺省 dotnetCandidates()；测试可注入）
+* @returns 满足条件的 dotnet 路径；无满足者返回 null
+*/
+function dotnetWithRuntime(minMajor, candidates = dotnetCandidates()) {
+	for (const dotnet of candidates) {
+		const sharedDir = join(dirname(dotnet), "shared", "Microsoft.NETCore.App");
+		let versions = [];
+		try {
+			versions = readdirSync(sharedDir);
+		} catch (error) {
+			continue;
+		}
+		if (versions.some((name) => {
+			const major = Number.parseInt(name.split(".")[0] ?? "", 10);
+			return Number.isInteger(major) && major >= minMajor;
+		})) return dotnet;
+	}
+	return null;
+}
+/**
+* 探测含 .NET SDK 的 dotnet 根目录（MSBuild 工程求值与 restore 需要，runtime-only 不够）。
+* @author ddj 2026年09月03号
+* @param candidates dotnet 候选路径（缺省 dotnetCandidates()；测试可注入）
+* @returns 含 SDK 的 dotnet 根目录；无则 null
+*/
+function findSdkRoot(candidates = dotnetCandidates()) {
+	for (const dotnet of candidates) {
+		const root = dirname(dotnet);
+		if (sdkVersionOf(root)) return root;
+	}
 	return null;
 }
+/**
+* dotnet 根目录下最新 SDK 版本号（无 SDK 返回 null）。
+* @author ddj 2026年09月03号
+* @param root dotnet 根目录
+* @returns SDK 版本号
+*/
+function sdkVersionOf(root) {
+	try {
+		const versions = readdirSync(join(root, "sdk")).filter((name) => /^\d+\.\d+/.test(name));
+		if (!versions.length) return null;
+		return versions.sort((a, b) => b.localeCompare(a, void 0, { numeric: true }))[0] ?? null;
+	} catch (error) {
+		return null;
+	}
+}
+/**
+* C# 服务器所需的 MSBuild 环境变量（SDK 解析 + restore 的 muxer 定位）。
+* @author ddj 2026年09月03号
+* @param sdkRoot 含 SDK 的 dotnet 根目录
+* @returns 环境变量表
+*/
+function sdkEnvOf(sdkRoot) {
+	const version = sdkVersionOf(sdkRoot);
+	const env = {
+		DOTNET_ROOT: sdkRoot,
+		DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR: sdkRoot
+	};
+	if (version) env.DOTNET_SDK_PATH = join(sdkRoot, "sdk", version);
+	return env;
+}
+/** 读扩展目录 package.json 的 version（读取失败不影响入口使用，返回 undefined）。 */
+function manifestVersionOf(extDir) {
+	try {
+		const manifest = JSON.parse(readFileSync(join(extDir, "package.json"), "utf8"));
+		return typeof manifest.version === "string" ? manifest.version : void 0;
+	} catch (error) {
+		return;
+	}
+}
 /** EmmyLua 自动发现候选（tangzx.emmylua-* / server/emmylua_ls）。 */
 function candidateEmmyLua(home = dshHome()) {
 	const candidates = [];
 	for (const dir of vscodeExtensionsDirs(home)) for (const extDir of listMatchingDirs(dir, "tangzx.emmylua-")) {
 		const server = join(extDir, "server", "emmylua_ls" + exeSuffix());
 		if (!existsSync(server)) continue;
-		let version;
-		try {
-			const manifest = JSON.parse(readFileSync(join(extDir, "package.json"), "utf8"));
-			if (typeof manifest.version === "string") version = manifest.version;
-		} catch (error) {}
 		candidates.push({
 			path: server,
-			version
+			version: manifestVersionOf(extDir)
 		});
 	}
 	candidates.sort((a, b) => (b.version ?? "").localeCompare(a.version ?? "", void 0, { numeric: true }) || a.path.localeCompare(b.path));
@@ -6807,20 +6994,73 @@ function candidateLuaServers(home = dshHome()) {
 	}
 	return out;
 }
-/** C# 自动发现候选：Roslyn dll（需 dotnet）或 OmniSharp 可执行。 */
+/**
+* C# 自动发现候选：ms-dotnettools.csharp 的 Roslyn dll（需 dotnet）/ OmniSharp 可执行，
+* 以及 DotRush 扩展自带服务器（extension/bin/LanguageServer/DotRush.dll，需对应 .NET 运行时）。
+* @author ddj 2026年09月03号
+* @param home DSH home（缺省真实；测试可注入临时目录）
+* @returns 发现结果
+*/
 function candidateCSharpServers(home = dshHome()) {
 	const out = {};
-	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 dotrushHits = [];
+	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;
+		}
+		for (const extDir of listMatchingDirs(dir, "nromanov.dotrush-")) {
+			const dll = join(extDir, "extension", "bin", "LanguageServer", "DotRush.dll");
+			if (!existsSync(dll)) continue;
+			dotrushHits.push({
+				dll,
+				version: manifestVersionOf(extDir)
+			});
+		}
+	}
+	const best = dotrushHits.sort((a, b) => (b.version ?? "").localeCompare(a.version ?? "", void 0, { numeric: true }) || a.dll.localeCompare(b.dll))[0];
+	if (best) {
+		out.dotrushDll = best.dll;
+		out.dotrushVersion = best.version;
 	}
 	const dotnet = findDotnet();
 	if (dotnet) out.dotnet = dotnet;
 	return out;
 }
 /**
+* 从服务器 dll 同目录的 *.runtimeconfig.json 解析所需 .NET 运行时大版本。
+* @author ddj 2026年09月03号
+* @param dllDir 服务器 dll 所在目录
+* @returns 运行时大版本；无清单或解析失败返回 null
+*/
+function runtimeMajorOf(dllDir) {
+	try {
+		for (const name of readdirSync(dllDir)) {
+			if (!name.endsWith(".runtimeconfig.json")) continue;
+			const version = JSON.parse(readFileSync(join(dllDir, name), "utf8")).runtimeOptions?.framework?.version;
+			if (typeof version !== "string") continue;
+			const major = Number.parseInt(version.split(".")[0] ?? "", 10);
+			if (Number.isInteger(major)) return major;
+		}
+	} catch (error) {}
+	return null;
+}
+/**
+* 解析 DotRush 启动参数：优先扩展内置 SDK dotnet，否则找满足其运行时大版本的 dotnet。
+* @author ddj 2026年09月03号
+* @param dll DotRush.dll 绝对路径
+* @returns argv 可直接启动；reason 为不可启动的原因
+*/
+function dotrushLaunch(dll) {
+	const sdkDotnet = join(dirname(dirname(dll)), "Sdk", "dotnet" + exeSuffix());
+	const major = runtimeMajorOf(dirname(dll));
+	const dotnet = existsSync(sdkDotnet) ? sdkDotnet : major !== null ? dotnetWithRuntime(major) : findDotnet();
+	if (dotnet) return { argv: [dotnet, dll] };
+	return { reason: "DotRush 需 .NET " + (major ?? "") + " 运行时，未找到满足的 dotnet" };
+}
+/**
 * 手动配置归一化：path 指向可执行文件/目录，command 为可执行名（PATH 解析）。
 * 未配置时返回空 reason（由各 resolve 兜底输出语言相关安装指引文案）。
 * @author ddj 2026年08月27号
@@ -6912,7 +7152,8 @@ function resolveLuaProvider(manual, home = dshHome()) {
 	});
 }
 /**
-* 解析 C# provider（优先级：手动 > 扩展源 > 自动发现；需 dotnet + Roslyn dll；或 OmniSharp）。
+* 解析 C# provider（优先级：手动 > 扩展源 > 自动发现；Roslyn dll 需 dotnet；
+* DotRush 需满足其运行时的 dotnet；或 OmniSharp）。
 * @author ddj 2026年08月27号
 * @param manual 手动配置
 * @param home DSH home（缺省真实；测试可注入临时目录）
@@ -6932,6 +7173,8 @@ function resolveCSharpProvider(manual, home = dshHome()) {
 		const ext = extensionProviderFor("csharp");
 		if (ext) return ext;
 		const discovered = candidateCSharpServers(h);
+		const sdkRoot = findSdkRoot();
+		const msbuildEnv = sdkRoot ? sdkEnvOf(sdkRoot) : void 0;
 		if (discovered.roslynDll && discovered.dotnet) return {
 			...base,
 			kind: "discover",
@@ -6940,8 +7183,26 @@ function resolveCSharpProvider(manual, home = dshHome()) {
 				discovered.roslynDll,
 				"--stdio"
 			],
+			env: msbuildEnv,
 			ready: true
 		};
+		let dotrushReason = null;
+		let provisionMajor;
+		if (discovered.dotrushDll) {
+			const major = runtimeMajorOf(dirname(discovered.dotrushDll));
+			const launch = dotrushLaunch(discovered.dotrushDll);
+			if ("argv" in launch) return {
+				...base,
+				kind: "discover",
+				argv: launch.argv,
+				env: msbuildEnv,
+				ready: true,
+				version: discovered.dotrushVersion,
+				providerName: "DotRush"
+			};
+			dotrushReason = launch.reason;
+			provisionMajor = major ?? void 0;
+		}
 		if (discovered.omnisharpExe) return {
 			...base,
 			kind: "discover",
@@ -6949,13 +7210,17 @@ function resolveCSharpProvider(manual, home = dshHome()) {
 			ready: true
 		};
 		const reasons = [];
-		if (!discovered.dotnet) reasons.push("未找到 dotnet");
-		if (!discovered.roslynDll && !discovered.omnisharpExe) reasons.push("未发现 ms-dotnettools.csharp 扩展");
+		if (dotrushReason) reasons.push(dotrushReason);
+		else {
+			if (!discovered.dotnet) reasons.push("未找到 dotnet");
+			reasons.push("未发现 ms-dotnettools.csharp / DotRush 扩展");
+		}
 		return {
 			...base,
 			kind: "none",
 			argv: [],
 			ready: false,
+			provisionRuntime: provisionMajor,
 			reason: reasons.join("；") + "（可手动指定 Roslyn/OmniSharp 入口）"
 		};
 	});
@@ -7003,7 +7268,7 @@ function fingerprintOf(home) {
 			return "?";
 		}
 	});
-	return process.platform + "|" + marks.join("|");
+	return process.platform + "|" + (findSdkRoot() ?? "no-sdk") + "|" + marks.join("|");
 }
 /**
 * 读取磁盘缓存（幂等：每进程只载一次；schema 文件名已隔离版本）。
@@ -7086,6 +7351,196 @@ function clearProviderCache(home = dshHome()) {
 	} catch (error) {}
 }
 //#endregion
+//#region src/lsp/dotnetProvision.ts
+/**
+* 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号
+*/
+const RETRY_MS = 6e5;
+/** 同 major 去重（in-flight）。 */
+const inFlight = /* @__PURE__ */ new Map();
+/** 失败时间戳（退避重试）。 */
+const failedAt = /* @__PURE__ */ new Map();
+/** 配置成功监听者（重载 provider 缓存与服务器）。 */
+const listeners = /* @__PURE__ */ new Set();
+/** 安装进行态（major → phase/message），供设置页轮询展示。 */
+const installStates = /* @__PURE__ */ new Map();
+/** 需求 id（与 envRequirements 的 id 一致）。 */
+function runtimeRequirementId(major) {
+	return "dotnet-runtime:" + major;
+}
+/** 当前安装进行态快照（edrv.lsp.envState 载荷）。 */
+function envInstallStates() {
+	return [...installStates.entries()].map(([major, state]) => ({
+		id: runtimeRequirementId(major),
+		phase: state.phase,
+		message: state.message
+	}));
+}
+/** 注册配置成功监听（成功后由 rpc 侧清缓存并重置服务器）。 */
+function onRuntimeProvisioned(listener) {
+	listeners.add(listener);
+}
+/** 平台 → 官方运行时资产文件名。 */
+function assetNameFor(platform, arch) {
+	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 的发现候选位置一致）。 */
+function userDotnetDir() {
+	if (process.platform === "win32") return join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "Microsoft", "dotnet");
+	return join(homedir(), ".dotnet");
+}
+/** 从 release 元数据 files 里挑当前平台资产（纯函数，测试可注入平台）。 */
+function pickRuntimeAsset(files, platform = process.platform, arch = process.arch) {
+	const name = assetNameFor(platform, arch);
+	return files.find((f) => f.name === name) ?? null;
+}
+/** 是否允许自动配置（测试隔离 + 显式开关）。 */
+function allowed() {
+	if (process.env.DSH_LSP_AUTO_RUNTIME === "0") return false;
+	if (process.env.DSH_LSP_EXT_DIRS) return false;
+	return true;
+}
+function setState(major, phase, message) {
+	installStates.set(major, {
+		phase,
+		message
+	});
+}
+function notifyListeners() {
+	for (const listener of listeners) try {
+		listener();
+	} catch {}
+}
+/**
+* 触发运行时自动配置（幂等：同 major 去重；失败 10 分钟退避；已满足则直接成功回调）。
+* 静默自动路径与设置页一键安装共用；进度经 envInstallStates 暴露。
+* @author ddj 2026年09月03号
+* @param major 运行时大版本
+*/
+function provisionRuntime(major) {
+	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）
+*/
+function startEnvInstall(major) {
+	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) {
+	if (dotnetWithRuntime(major)) return true;
+	setState(major, "downloading");
+	const files = ((await fetchJson("https://builds.dotnet.microsoft.com/dotnet/release-metadata/" + major + ".0/releases.json"))?.releases?.[0])?.runtime?.files;
+	if (!Array.isArray(files)) return false;
+	const asset = pickRuntimeAsset(files);
+	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 {
+		if (!await extractTo(buf, dir)) 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) {
+	try {
+		const res = await fetch(url, { signal: AbortSignal.timeout(3e4) });
+		if (!res.ok) return null;
+		return await res.json();
+	} catch {
+		return null;
+	}
+}
+/** 下载并按官方 sha512 校验（5 分钟超时，不匹配返回 null）。 */
+async function downloadVerified(url, sha512) {
+	try {
+		const res = await fetch(url, { signal: AbortSignal.timeout(3e5) });
+		if (!res.ok) return null;
+		const buf = Buffer.from(await res.arrayBuffer());
+		return createHash("sha512").update(buf).digest("hex").toLowerCase() === sha512.toLowerCase() ? buf : null;
+	} catch {
+		return null;
+	}
+}
+/** 解压到目录：win 走 zip（PK 头），unix 落临时包交系统 tar。 */
+async function extractTo(buf, dir) {
+	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((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 });
+	}
+}
+//#endregion
 //#region src/lsp/config.ts
 const LSP_SETTINGS_NS = "dsh-vscode-mode.languageServers";
 const LSP_LANGUAGES = ["lua", "csharp"];
@@ -7163,10 +7618,12 @@ function resolveProviderSpec(ctx, pluginConfig, languageId) {
 		ready: false,
 		reason: "已在设置中禁用"
 	};
-	return resolver({
+	const spec = resolver({
 		command: lang?.command,
 		path: lang?.path
 	});
+	if (spec.provisionRuntime) provisionRuntime(spec.provisionRuntime);
+	return spec;
 }
 /** 语言 → 扩展名（供客户端判断是否触发 LSP）。 */
 function langOfPath(path) {
@@ -7181,6 +7638,82 @@ function langOfPath(path) {
 	return null;
 }
 //#endregion
+//#region src/lsp/envRequirements.ts
+/**
+* dsh-vscode-mode host — LSP 环境需求检测注册表。
+* 每个语言注册一个检测器：扫描当前环境，返回未满足的需求清单（含一键安装与官网链接信息）。
+* 新接入 LSP：在 CHECKERS 加一个检测器条目；需要内置安装器时在 INSTALLERS 注册同前缀安装函数。
+* 检测在 status/redetect/configUpdate 时执行（不缓存），保证安装完成后状态即时刷新。
+* 作者 ddj 2026年09月03号
+*/
+/** dotnet 运行时需求构造（DotRush / ms-Roslyn 共用）。 */
+function dotnetRuntimeRequirement(major, detail) {
+	return {
+		id: "dotnet-runtime:" + major,
+		label: ".NET 运行时 " + major + ".0",
+		detail,
+		installable: true,
+		manualUrl: "https://dotnet.microsoft.com/download/dotnet/" + major + ".0",
+		manualLabel: "官网下载"
+	};
+}
+/** csharp 检测器：DotRush 缺运行时 / ms-Roslyn 缺 dotnet。 */
+function checkCSharp(home) {
+	const found = candidateCSharpServers(home);
+	const missing = [];
+	if (found.dotrushDll) {
+		const major = runtimeMajorOf(dirname(found.dotrushDll));
+		if (major !== null && dotnetWithRuntime(major) === null) missing.push(dotnetRuntimeRequirement(major, "DotRush 语言服务器运行所需"));
+		return missing;
+	}
+	if (found.roslynDll && !found.dotnet) missing.push(dotnetRuntimeRequirement(8, "Roslyn 语言服务器运行所需"));
+	return missing;
+}
+/** lua 检测器：EmmyLua/LuaLS 自带运行时，无外部依赖。 */
+function checkLua() {
+	return [];
+}
+/** 检测器注册表（按 languageId；新 LSP 在此加条目即可）。 */
+const CHECKERS = {
+	lua: checkLua,
+	csharp: checkCSharp
+};
+/** 安装器注册表（按需求 id 前缀匹配；新依赖类型在此加条目）。 */
+const INSTALLERS = [{
+	prefix: "dotnet-runtime:",
+	run: (id) => {
+		const major = Number.parseInt(id.slice(15), 10);
+		return Number.isInteger(major) ? startEnvInstall(major) : false;
+	}
+}];
+/**
+* 检测某语言未满足的环境需求（仅返回缺失项；检测器异常按无需求处理）。
+* @author ddj 2026年09月03号
+* @param languageId 语言 id
+* @param home DSH home（测试可注入临时目录）
+* @returns 缺失需求清单
+*/
+function envRequirementsFor(languageId, home) {
+	const checker = CHECKERS[languageId];
+	if (!checker) return [];
+	try {
+		return checker(home);
+	} catch {
+		return [];
+	}
+}
+/**
+* 尝试一键安装某条需求（存在内置安装器时启动，进行中/已满足返回 false）。
+* @author ddj 2026年09月03号
+* @param id 需求标识（如 dotnet-runtime:10）
+* @returns 是否成功启动安装
+*/
+function installRequirement(id) {
+	const installer = INSTALLERS.find((it) => id.startsWith(it.prefix));
+	if (!installer) return false;
+	return installer.run(id);
+}
+//#endregion
 //#region src/lsp/rpc.ts
 /**
 * 打开文档跟踪：openDocs(docKey→sessionId) + rootLangRefs 计数 + sessionAcquired 归属。
@@ -7275,6 +7808,10 @@ function createDocTracker() {
 function createLspRpc(deps) {
 	const { ctx, pluginConfig, manager } = deps;
 	const tracker = createDocTracker();
+	onRuntimeProvisioned(() => {
+		clearProviderCache();
+		manager.resetLanguage("csharp");
+	});
 	/** 解析会话与工作区根（失败 → null + error）。 */
 	const rootOf = async (sessionId) => {
 		const session = sessionOf(ctx, sessionId);
@@ -7295,9 +7832,10 @@ function createLspRpc(deps) {
 		...location,
 		root
 	}));
-	/** 当前 provider 检测结论 → 设置页 idle 状态（不启动 server）。 */
+	/** 当前 provider 检测结论 → 设置页 idle 状态（不启动 server）；附带未满足的环境需求。 */
 	const detectedStatus = (languageId, root) => {
 		const spec = resolveProviderSpec(ctx, pluginConfig, languageId);
+		const missingEnv = envRequirementsFor(languageId, dshHome());
 		return {
 			languageId,
 			source: spec.kind,
@@ -7305,7 +7843,8 @@ function createLspRpc(deps) {
 			reason: spec.ready ? void 0 : spec.reason,
 			version: spec.version,
 			providerName: spec.providerName,
-			root
+			root,
+			missingEnv: missingEnv.length ? missingEnv : void 0
 		};
 	};
 	/**
@@ -7613,6 +8152,23 @@ function createLspRpc(deps) {
 					};
 				}
 			},
+			"edrv.lsp.envInstall": async (args) => {
+				if (!installRequirement(args.id)) return {
+					ok: false,
+					started: false,
+					error: "该需求不支持一键安装：" + args.id
+				};
+				return {
+					ok: true,
+					started: true
+				};
+			},
+			"edrv.lsp.envState": async () => {
+				return {
+					ok: true,
+					states: envInstallStates()
+				};
+			},
 			"edrv.lsp.ext.list": async () => ({
 				ok: true,
 				extensions: listInstalled()