dsh-vscode-mode 0.1.52 → 0.1.53

package/lib/index.js

@@ -1,10 +1,10 @@
 import { createRequire } from "node:module";
-import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, copyFile, cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir, tmpdir } from "node:os";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { Buffer as Buffer$1 } from "node:buffer";
 import { spawn } from "node:child_process";
 import { inflateRawSync } from "node:zlib";
@@ -127,6 +127,19 @@ const KEYBINDING_DEFAULTS = {
 	"edrv.navigateForward": "Alt+ArrowRight|Ctrl+Shift+-"
 };
 //#endregion
+//#region src/shared/integration.ts
+/**
+* dsh-vscode-mode shared — 系统集成载荷契约（Windows 右键菜单 + Unity 一键安装/更新）。
+* Purity rule: no node/react imports（platform 用 string 表示）。
+* 作者 ddj 2026-09-07
+*/
+/** Unity 内嵌包名（UPM 包名，同时是项目 Packages/ 下的目录名）。 */
+const UNITY_PACKAGE_NAME = "com.dsh.editor";
+/** 注册表菜单键叶子名（HKCU\Software\Classes\*\shell\<leaf>）。 */
+const SHELL_MENU_LEAF = "DSHEditor";
+/** 深链基址默认值（DSH Web GUI 默认端口，dsh-web.cmd 实证）。 */
+const INTEGRATION_BASE_DEFAULT = "http://127.0.0.1:3080";
+//#endregion
 //#region src/fileOpenSettings.ts
 const FILE_OPEN_SETTINGS_NS = "dsh-vscode-mode";
 const FILE_OPEN_DEFAULT = "auto";
@@ -247,6 +260,11 @@ function normalizeValue(value) {
 function configValue(config) {
 	return normalizeValue(config?.fileOpenTool);
 }
+/** 配置/设置里的深链基址（缺省/非法回退默认值）。 */
+function baseValueOf(config) {
+	const raw = config?.integrationBaseUrl;
+	return typeof raw === "string" && raw.trim() ? raw.trim() : INTEGRATION_BASE_DEFAULT;
+}
 /**
 * 安装设置 section（版本自适应；任一策略不可用返回 false 不抛错）。
 * @author ddj 2026年08月24号 / 2026年09月02号
@@ -266,7 +284,8 @@ async function installOpenSettingsSection(ctx, ns, entry, hooks, loader = loadSe
 	const strategy = await runSettingsInstall(ctx, ns, deps.z.object({
 		fileOpenTool: deps.z.string().default(FILE_OPEN_DEFAULT),
 		keybindings: deps.z.object(keybindingsShape(deps.z)).default({ ...KEYBINDING_DEFAULTS }),
-		sidebarMinWidth: deps.z.number().default(300)
+		sidebarMinWidth: deps.z.number().default(300),
+		integrationBaseUrl: deps.z.string().default(INTEGRATION_BASE_DEFAULT)
 	}), entry, {
 		setSource: (source) => hooks.setSource(source),
 		onChange: hooks.onChange
@@ -294,7 +313,10 @@ function setupOpenSettings(ctx, config, onChange) {
 	};
 	const setSource = (source) => notify(source().fileOpenTool);
 	const settingsChange = () => syncRevision();
-	installOpenSettingsSection(ctx, FILE_OPEN_SETTINGS_NS, { fileOpenTool: current }, {
+	installOpenSettingsSection(ctx, FILE_OPEN_SETTINGS_NS, {
+		fileOpenTool: current,
+		integrationBaseUrl: baseValueOf(config)
+	}, {
 		setSource,
 		onChange: settingsChange
 	});
@@ -4309,6 +4331,926 @@ async function projectRefresh(ctx, workspacePath, serverName) {
 	return projectOf(ctx, workspacePath, workspace.title ?? "");
 }
 //#endregion
+//#region src/unityBridge.ts
+/**
+* dsh-vscode-mode host — Unity 内嵌包一键安装/更新。
+* 机制：把包源目录 unity/com.dsh.editor 复制为 <Unity项目根>/Packages/com.dsh.editor
+* （Unity 内嵌包自动发现，无需改 manifest.json）；安装/更新同入口（整目录替换）；
+* 卸载 = 删除目标目录。登记清单存 ~/.dsh/dsh-vscode-mode/unity-projects.json。
+* 安全：只触碰固定目标目录；项目根须含 Assets + ProjectSettings；目标已存在且
+* package.json name 不是本包 → 拒绝覆盖。纯路径构造与项目特征判定可单测。
+* 作者 ddj 2026-09-07
+*/
+/** Unity 项目特征目录。 */
+const UNITY_MARKERS = ["Assets", "ProjectSettings"];
+/** 登记清单文件名。 */
+const PROJECTS_FILE = "unity-projects.json";
+/** 包源目录相对插件包根的位置。 */
+const UNITY_DIR_NAME = "unity";
+/**
+* 包源目录（随插件包分发的 unity/com.dsh.editor 绝对路径）。
+* @author ddj 2026年09月07号
+* @param moduleUrl 模块 URL（缺省 import.meta.url；测试注入）
+* @returns 包源目录绝对路径
+*/
+function unitySourceDir(moduleUrl = import.meta.url) {
+	return join(dirname(fileURLToPath(moduleUrl)), "..", UNITY_DIR_NAME, UNITY_PACKAGE_NAME);
+}
+/**
+* 项目登记清单文件（~/.dsh/dsh-vscode-mode/unity-projects.json）。
+* @author ddj 2026年09月07号
+* @param home DSH home（测试可注入）
+* @returns 清单文件绝对路径
+*/
+function unityProjectsFile(home = dshHome()) {
+	return join(home, PLUGIN_ID, PROJECTS_FILE);
+}
+/**
+* 归一化用户输入的项目根：去首尾空白/引号/尾部分隔符。
+* @author ddj 2026年09月07号
+* @param raw 原始输入
+* @returns 归一化绝对路径
+*/
+function normalizeUnityRoot(raw) {
+	return String(raw ?? "").trim().replace(/^["']|["']$/g, "").replace(/[\\/]+$/, "");
+}
+/**
+* 目录名清单是否满足 Unity 项目特征（Assets + ProjectSettings 同时存在）。
+* @author ddj 2026年09月07号
+* @param entries 项目根下的目录名清单
+* @returns 是否 Unity 项目根
+*/
+function isUnityProject(entries) {
+	return UNITY_MARKERS.every((marker) => entries.includes(marker));
+}
+/**
+* 内嵌包目标目录（固定：<root>/Packages/com.dsh.editor）。
+* @author ddj 2026年09月07号
+* @param root Unity 项目根
+* @returns 目标目录绝对路径
+*/
+function unityTargetOf(root) {
+	return join(root, "Packages", UNITY_PACKAGE_NAME);
+}
+/**
+* 读 package.json 的 version（缺失/非法 → null）。
+* @author ddj 2026年09月07号
+* @param pkgFile package.json 绝对路径
+* @returns 版本号或 null
+*/
+async function readPackageVersion(pkgFile) {
+	try {
+		const data = JSON.parse(await readFile(pkgFile, "utf8"));
+		return typeof data?.version === "string" && data.version ? data.version : null;
+	} catch {
+		return null;
+	}
+}
+/** 读登记清单（缺失/非法 → 空数组）。 */
+async function readProjects(home = dshHome()) {
+	try {
+		const data = JSON.parse(await readFile(unityProjectsFile(home), "utf8"));
+		if (!Array.isArray(data)) return [];
+		return data.filter((item) => !!item && typeof item.path === "string").map((item) => ({
+			path: String(item.path),
+			addedAt: String(item.addedAt ?? "")
+		}));
+	} catch {
+		return [];
+	}
+}
+/** 写登记清单（父目录按需创建）。 */
+async function writeProjects(records, home = dshHome()) {
+	const file = unityProjectsFile(home);
+	await mkdir(dirname(file), { recursive: true });
+	await writeFile(file, JSON.stringify(records, null, 2) + "\n", "utf8");
+}
+/**
+* 单个项目的安装状态视图（版本对比 + 合法性）。
+* @author ddj 2026年09月07号
+* @param rawPath 项目路径（原始输入）
+* @param moduleUrl 模块 URL（测试注入）
+* @returns 项目状态
+*/
+async function unityEntryOf(rawPath, moduleUrl = import.meta.url) {
+	const root = normalizeUnityRoot(rawPath);
+	const entry = {
+		path: root,
+		title: basename(root) || root,
+		installedVersion: null,
+		upToDate: false,
+		missingDir: false
+	};
+	let names = [];
+	try {
+		names = await readdir(root);
+	} catch {
+		entry.missingDir = true;
+		return entry;
+	}
+	if (!isUnityProject(names)) {
+		entry.error = "不是 Unity 项目根（缺少 Assets 或 ProjectSettings 目录）";
+		return entry;
+	}
+	const installed = await readPackageVersion(join(unityTargetOf(root), "package.json"));
+	entry.installedVersion = installed;
+	const sourceVersion = await readPackageVersion(join(unitySourceDir(moduleUrl), "package.json"));
+	entry.upToDate = installed !== null && installed === sourceVersion;
+	return entry;
+}
+/**
+* 列出登记项目与包源版本。
+* @author ddj 2026年09月07号
+* @param moduleUrl 模块 URL（测试注入）
+* @param home DSH home（测试注入）
+* @returns 列表载荷
+*/
+async function unityList(moduleUrl = import.meta.url, home = dshHome()) {
+	const source = unitySourceDir(moduleUrl);
+	const records = await readProjects(home);
+	const projects = [];
+	for (const record of records) projects.push(await unityEntryOf(record.path, moduleUrl));
+	return {
+		sourceVersion: await readPackageVersion(join(source, "package.json")),
+		sourcePath: source,
+		projects
+	};
+}
+/**
+* 登记一个 Unity 项目（校验通过才入清单，重复登记幂等）。
+* @author ddj 2026年09月07号
+* @param rawPath 项目路径（原始输入）
+* @param moduleUrl 模块 URL（测试注入）
+* @param home DSH home（测试注入）
+* @returns 项目状态
+*/
+async function unityAdd(rawPath, moduleUrl = import.meta.url, home = dshHome()) {
+	const root = normalizeUnityRoot(rawPath);
+	const entry = await unityEntryOf(root, moduleUrl);
+	if (entry.missingDir) throw new Error("目录不存在：" + root);
+	if (entry.error) throw new Error(entry.error);
+	const records = await readProjects(home);
+	if (!records.some((record) => normalizeUnityRoot(record.path) === root)) {
+		records.push({
+			path: root,
+			addedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		await writeProjects(records, home);
+	}
+	return entry;
+}
+/**
+* 移除一个项目的登记（不删除已安装的包目录）。
+* @author ddj 2026年09月07号
+* @param rawPath 项目路径（原始输入）
+* @param home DSH home（测试注入）
+*/
+async function unityRemove(rawPath, home = dshHome()) {
+	const root = normalizeUnityRoot(rawPath);
+	await writeProjects((await readProjects(home)).filter((record) => normalizeUnityRoot(record.path) !== root), home);
+}
+/**
+* 一键安装/更新：整目录替换 <root>/Packages/com.dsh.editor 为包源内容。
+* @author ddj 2026年09月07号
+* @param rawPath 项目路径（原始输入）
+* @param moduleUrl 模块 URL（测试注入）
+* @returns 安装后项目状态
+*/
+async function unityInstall(rawPath, moduleUrl = import.meta.url) {
+	const root = normalizeUnityRoot(rawPath);
+	const source = unitySourceDir(moduleUrl);
+	const target = unityTargetOf(root);
+	await validateInstallTarget(root, source, target);
+	await rm(target, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(join(target, ".."), { recursive: true });
+	await cp(source, target, { recursive: true });
+	return unityEntryOf(root, moduleUrl);
+}
+/**
+* 安装前校验：Unity 项目根 + 目标不与包源重叠 + 已存在目标必须是本包。
+* @author ddj 2026年09月07号
+* @param root 项目根
+* @param source 包源目录
+* @param target 目标目录
+*/
+async function validateInstallTarget(root, source, target) {
+	let names = [];
+	try {
+		names = await readdir(root);
+	} catch {
+		throw new Error("目录不存在：" + root);
+	}
+	if (!isUnityProject(names)) throw new Error("不是 Unity 项目根（缺少 Assets 或 ProjectSettings 目录）");
+	if (target === source || target.startsWith(source + sep) || source.startsWith(target + sep)) throw new Error("目标目录与包源重叠，拒绝安装");
+	const text = await readFile(join(target, "package.json"), "utf8").catch((error) => {
+		if (error?.code === "ENOENT") return null;
+		throw error;
+	});
+	if (text === null) return;
+	let name = null;
+	try {
+		name = JSON.parse(text).name;
+	} catch {}
+	if (name !== "com.dsh.editor") throw new Error("目标目录已存在且不是 DSH 包，拒绝覆盖：" + target);
+}
+//#endregion
+//#region src/integrate.ts
+/**
+* dsh-vscode-mode host — 资源管理器右键菜单「在 DSH 文件编辑中打开」（跨平台）。
+* - Windows：launcher（assets/shell/dsh-open.cs 经 csc 编译 WinExe，csc 缺失降级 ps1）安装到
+*   ~/.dsh/dsh-vscode-mode/shell/，HKCU\Software\Classes 三类菜单键（`*`/Directory/Directory\Background）。
+* - Linux：dsh-open.sh + GNOME Files（Nautilus）右键脚本 + KDE Dolphin 服务菜单（纯文件写入）。
+* - macOS：dsh-open.sh（Finder 快速操作由用户按配方手动创建，自动检测/移除）。
+* 生命周期：注册成功写 marker（shell/registered.json）→ 插件卸载/reload 清理注册痕迹，
+* 启动时 marker 存在则自动恢复（更新插件不丢注册）；用户显式「移除注册」删 marker 永不自动恢复。
+* 所有 reg/csc 调用经 subprocess 服务 argv 数组（卸载清理用 child_process 直调，teardown 可靠）。
+* 纯函数（键路径/命令行/ini/脚本内容）可单测。
+* 作者 ddj 2026-09-07
+*/
+/** 菜单显示名（Windows 键默认值 / Linux 菜单项名 / macOS workflow 名）。 */
+const MENU_LABEL = "在 DSH 文件编辑中打开";
+/** 编译 launcher 文件名（Windows）。 */
+const LAUNCHER_EXE = "dsh-open.exe";
+/** launcher C# 源文件名。 */
+const LAUNCHER_CS = "dsh-open.cs";
+/** 降级 launcher 脚本名（Windows）。 */
+const LAUNCHER_PS1 = "dsh-open.ps1";
+/** POSIX launcher 脚本名（Linux/macOS 通用）。 */
+const LAUNCHER_SH = "dsh-open.sh";
+/** 深链基址配置文件名。 */
+const INI_NAME = "dsh-open.ini";
+/** 注册 marker 文件名（存在 = 用户注册过且未显式移除）。 */
+const MARKER_NAME = "registered.json";
+/** Icon 值名。 */
+const REG_VALUE_NAME_ICON = "Icon";
+/** Nautilus 右键脚本文件名。 */
+const NAUTILUS_NAME = MENU_LABEL;
+/** Dolphin 服务菜单文件名。 */
+const DOLPHIN_NAME = "dsh-editor.desktop";
+/** Finder 快速操作（workflow 包）目录名。 */
+const FINDER_NAME = MENU_LABEL + ".workflow";
+/** DSH 小鲸鱼图标文件名（右键菜单 Icon，注册时复制到安装目录）。 */
+const WHALE_ICO = "dsh-whale.ico";
+/**
+* reg.exe 路径（SystemRoot 派生；env 可注入便于测试）。
+* @author ddj 2026年09月07号
+* @param env 环境映射（缺省 process.env）
+* @returns reg.exe 绝对路径
+*/
+function regExe(env = process.env) {
+	return join(systemRoot(env), "System32", "reg.exe");
+}
+/**
+* csc.exe 候选列表（.NET Framework 4.x 常驻路径，按存在性取首个）。
+* @author ddj 2026年09月07号
+* @param env 环境映射（缺省 process.env）
+* @returns 候选绝对路径列表
+*/
+function cscCandidates(env = process.env) {
+	const root = systemRoot(env);
+	return [join(root, "Microsoft.NET", "Framework64", "v4.0.30319", "csc.exe"), join(root, "Microsoft.NET", "Framework", "v4.0.30319", "csc.exe")];
+}
+/**
+* Windows 三类菜单键完整路径。
+* @author ddj 2026年09月07号
+* @param leaf 菜单键叶子名（缺省 DSHEditor）
+* @returns files/dir/background 三个键路径
+*/
+function menuKeyPaths(leaf = SHELL_MENU_LEAF) {
+	const root = "HKCU\\Software\\Classes";
+	return {
+		files: root + "\\*\\shell\\" + leaf,
+		dir: root + "\\Directory\\shell\\" + leaf,
+		background: root + "\\Directory\\Background\\shell\\" + leaf
+	};
+}
+/**
+* launcher 安装目录（~/.dsh/dsh-vscode-mode/shell）。
+* @author ddj 2026年09月07号
+* @param home DSH home（测试可注入）
+* @returns 安装目录绝对路径
+*/
+function shellInstallDir(home = dshHome()) {
+	return join(home, PLUGIN_ID, "shell");
+}
+/**
+* Nautilus 右键脚本路径（~/.local/share/nautilus/scripts/）。
+* @author ddj 2026年09月07号
+* @param home 用户 home（测试可注入）
+*/
+function nautilusPath(home = homedir()) {
+	return join(home, ".local", "share", "nautilus", "scripts", NAUTILUS_NAME);
+}
+/**
+* Dolphin 服务菜单路径（新 kio/servicemenus + 旧 kservices5，两个都写）。
+* @author ddj 2026年09月07号
+* @param home 用户 home（测试可注入）
+*/
+function dolphinMenuPaths(home = homedir()) {
+	return [join(home, ".local", "share", "kio", "servicemenus", DOLPHIN_NAME), join(home, ".local", "share", "kservices5", "ServiceMenus", DOLPHIN_NAME)];
+}
+/**
+* Finder 快速操作 workflow 包路径（~/Library/Services/）。
+* @author ddj 2026年09月07号
+* @param home 用户 home（测试可注入）
+*/
+function finderWorkflowPath(home = homedir()) {
+	return join(home, "Library", "Services", FINDER_NAME);
+}
+/**
+* 注册 marker 文件路径（shell/registered.json）。
+* @author ddj 2026年09月07号
+* @param home DSH home（测试可注入）
+*/
+function markerFile(home = dshHome()) {
+	return join(shellInstallDir(home), MARKER_NAME);
+}
+/**
+* command 默认值（Windows 编译 exe 版）。
+* @author ddj 2026年09月07号
+* @param exePath launcher 绝对路径
+* @param token 路径占位符
+* @returns 注册表 command 值
+*/
+function commandValue(exePath, token = "%1") {
+	return "\"" + exePath + "\" \"" + token + "\"";
+}
+/**
+* command 默认值（Windows 降级 ps1 版：隐藏窗口运行脚本）。
+* @author ddj 2026年09月07号
+* @param ps1Path launcher 脚本绝对路径
+* @param token 路径占位符
+* @param powerShell powershell.exe 路径（测试可注入）
+* @returns 注册表 command 值
+*/
+function ps1CommandValue(ps1Path, token = "%1", powerShell = powerShellExe()) {
+	return "\"" + powerShell + "\" -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File \"" + ps1Path + "\" \"" + token + "\"";
+}
+/**
+* dsh-open.ini 内容（base 行驱动 launcher 深链基址，三平台共用）。
+* @author ddj 2026年09月07号
+* @param baseUrl 深链基址
+* @returns ini 文件全文
+*/
+function iniContent(baseUrl) {
+	return "[dsh]\nbase=" + (baseUrl.trim() || "http://127.0.0.1:3080") + "\n";
+}
+/**
+* Nautilus 右键脚本内容（多选经 NAUTILUS_SCRIPT_SELECTED_FILE_PATHS 一次传给 launcher）。
+* @author ddj 2026年09月07号
+* @param launcherPath dsh-open.sh 绝对路径
+* @returns 脚本全文（#!/usr/bin/env bash）
+*/
+function nautilusScript(launcherPath) {
+	return [
+		"#!/usr/bin/env bash",
+		"# 由 dsh-vscode-mode 生成：GNOME Files（Nautilus）右键脚本 → DSH 文件编辑",
+		"launcher=\"$HOME/.dsh/dsh-vscode-mode/shell/dsh-open.sh\"",
+		"args=()",
+		"while IFS= read -r line; do",
+		"  [ -n \"$line\" ] && args+=(\"$line\")",
+		"done <<< \"${NAUTILUS_SCRIPT_SELECTED_FILE_PATHS:-}\"",
+		"exec \"$launcher\" \"${args[@]}\"",
+		""
+	].join("\n");
+}
+/**
+* Dolphin 服务菜单内容（%F 多选传参）。
+* @author ddj 2026年09月07号
+* @param launcherPath dsh-open.sh 绝对路径
+* @returns .desktop 全文
+*/
+function dolphinMenu(launcherPath) {
+	return [
+		"[Desktop Entry]",
+		"Type=Service",
+		"X-KDE-ServiceTypes=KonqPopupMenu/Plugin",
+		"MimeType=all/allfiles;inode/directory;",
+		"Actions=openInDshEditor",
+		"[Desktop Action openInDshEditor]",
+		"Name=" + MENU_LABEL,
+		"Icon=utilities-terminal",
+		"Exec=\"" + launcherPath + "\" %F",
+		""
+	].join("\n");
+}
+/** SystemRoot 解析（env 可注入）。 */
+function systemRoot(env) {
+	return env.SystemRoot || "C:\\Windows";
+}
+/** powershell.exe 路径（Windows 降级注册用）。 */
+function powerShellExe(env = process.env) {
+	return join(systemRoot(env), "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+/** POSIX launcher 脚本安装路径。 */
+function shLauncherPath(home = dshHome()) {
+	return join(shellInstallDir(home), LAUNCHER_SH);
+}
+/**
+* 经 subprocess 服务运行一个命令（argv 数组，无 shell 插值）。
+* ⚠️ stdio 必须 'inherit'：受管 host 环境禁止管道 stdio（node spawn pipe → EPERM），
+* inherit 直写宿主控制台且不建管道；本模块只需退出码（reg query 缺键 = 退出码 1）。
+* done 契约宽松归一化：{exitCode,signal} / {code} / undefined / 抛错（spawn 失败）。
+* @author ddj 2026年09月07号
+* @param ctx DSH 上下文
+* @param argv 命令与参数
+* @param cwd 工作目录（须已存在）
+* @returns 退出码（0=成功）
+*/
+async function runArgv(ctx, argv, cwd = dshHome()) {
+	const sub = ctx.get("subprocess");
+	if (!sub || typeof sub.spawn !== "function") throw new Error("缺少 subprocess 服务");
+	let handle;
+	try {
+		handle = sub.spawn({
+			argv,
+			cwd,
+			stdio: {
+				stdout: "inherit",
+				stderr: "inherit",
+				stdin: "ignore"
+			},
+			graceMs: 1e4
+		});
+	} catch (error) {
+		return {
+			code: 1,
+			output: String(error)
+		};
+	}
+	try {
+		return normalizeOutcome(await handle.done);
+	} catch (error) {
+		return {
+			code: 1,
+			output: String(error)
+		};
+	}
+}
+/** 归一化 done 结果（契约宽松：{exitCode,signal} / {code} / 字符串 / undefined）。 */
+function normalizeOutcome(result) {
+	if (result == null) return {
+		code: 0,
+		output: ""
+	};
+	if (typeof result === "string") return {
+		code: 0,
+		output: result
+	};
+	const record = result;
+	if (typeof record.exitCode === "number") return {
+		code: record.exitCode,
+		output: ""
+	};
+	if (typeof record.code === "number") return {
+		code: record.code,
+		output: ""
+	};
+	return {
+		code: 0,
+		output: ""
+	};
+}
+/** 文件存在性探测（best-effort）。 */
+async function fileExists(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+/** Windows：探测一个注册表键是否存在（reg query 缺键 = 退出码 1，无需读输出）。 */
+async function keyExists(ctx, key) {
+	return (await runArgv(ctx, [
+		regExe(),
+		"query",
+		key,
+		"/ve"
+	])).code === 0;
+}
+/** 读注册 marker（缺失/非法 → null）。 */
+async function readMarker(home = dshHome()) {
+	try {
+		const data = JSON.parse(await readFile(markerFile(home), "utf8"));
+		if (typeof data?.baseUrl !== "string" || !data.baseUrl) return null;
+		return {
+			baseUrl: data.baseUrl,
+			at: typeof data.at === "string" ? data.at : ""
+		};
+	} catch {
+		return null;
+	}
+}
+/** 写注册 marker（父目录已存在）。 */
+async function saveMarker(baseUrl, home = dshHome()) {
+	const data = {
+		baseUrl,
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await writeFile(markerFile(home), JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+/** 复制 POSIX launcher 并加执行位（三平台 ini 同写）。 */
+async function installPosix(dir, baseUrl) {
+	await copyFile(join(assetsDirOf(import.meta.url), "shell", LAUNCHER_SH), join(dir, LAUNCHER_SH));
+	await chmod(join(dir, LAUNCHER_SH), 493);
+	await writeFile(join(dir, INI_NAME), iniContent(baseUrl), "utf8");
+}
+/** 写 Nautilus 右键脚本（父目录按需创建 + 执行位）。 */
+async function writeNautilus(home, launcherPath) {
+	const script = nautilusPath(home);
+	await mkdir(join(script, ".."), { recursive: true });
+	await writeFile(script, nautilusScript(launcherPath), "utf8");
+	await chmod(script, 493);
+}
+/** 写 Dolphin 服务菜单（新/旧两个路径，父目录按需创建）。 */
+async function writeDolphinMenus(home, launcherPath) {
+	for (const menu of dolphinMenuPaths(home)) {
+		await mkdir(join(menu, ".."), { recursive: true });
+		await writeFile(menu, dolphinMenu(launcherPath), "utf8");
+	}
+}
+/** Linux：移除 Nautilus 脚本与 Dolphin 服务菜单（仅本插件自有文件）。 */
+async function removePosixFiles(home) {
+	await rm(nautilusPath(home), { force: true });
+	for (const menu of dolphinMenuPaths(home)) await rm(menu, { force: true });
+}
+/** macOS：移除 Finder 快速操作（仅当其内容引用本插件 launcher，防误删用户手工产物）。 */
+async function dropFinderMenu(home) {
+	const dir = finderWorkflowPath(home);
+	let text = "";
+	try {
+		text = await readFile(join(dir, "Contents", "document.wflow"), "utf8");
+	} catch {
+		return;
+	}
+	if (!text.includes("dsh-open")) return;
+	await rm(dir, {
+		recursive: true,
+		force: true
+	});
+}
+/** 卸载清理专用：直调 reg delete（subprocess 服务在 teardown 可能已卸载）。⚠️ stdio 'ignore'：受管环境禁管道。 */
+function regDeleteDirect(key) {
+	return new Promise((resolve) => {
+		try {
+			const child = spawn(regExe(), [
+				"delete",
+				key,
+				"/f"
+			], {
+				windowsHide: true,
+				timeout: 5e3,
+				stdio: "ignore"
+			});
+			child.once("close", () => resolve());
+			child.once("error", () => resolve());
+		} catch {
+			resolve();
+		}
+	});
+}
+/**
+* 查询系统集成状态（按平台探测条目注册状态 + launcher 安装态）。
+* @author ddj 2026年09月07号
+* @param ctx DSH 上下文
+* @param baseUrl 深链基址（设置 integrationBaseUrl）
+* @returns 集成状态
+*/
+async function shellMenuStatus(ctx, baseUrl) {
+	const dir = shellInstallDir();
+	const platform = process.platform;
+	let launcher;
+	let entries = [];
+	if (platform === "win32") {
+		const exe = join(dir, LAUNCHER_EXE);
+		const ps1 = join(dir, LAUNCHER_PS1);
+		const compiled = await fileExists(exe);
+		const ps1Present = await fileExists(ps1);
+		launcher = {
+			present: compiled || ps1Present,
+			compiled,
+			path: compiled ? exe : ps1
+		};
+		entries = [
+			{
+				id: "files",
+				label: "文件",
+				registered: await keyExists(ctx, menuKeyPaths().files)
+			},
+			{
+				id: "dir",
+				label: "文件夹",
+				registered: await keyExists(ctx, menuKeyPaths().dir)
+			},
+			{
+				id: "dirBackground",
+				label: "文件夹空白处",
+				registered: await keyExists(ctx, menuKeyPaths().background)
+			}
+		];
+	} else {
+		const sh = shLauncherPath();
+		launcher = {
+			present: await fileExists(sh),
+			compiled: false,
+			path: sh
+		};
+		if (platform === "linux") {
+			const menus = dolphinMenuPaths();
+			entries = [{
+				id: "nautilus",
+				label: "GNOME Files（Nautilus）",
+				registered: await fileExists(nautilusPath())
+			}, {
+				id: "dolphin",
+				label: "KDE Dolphin",
+				registered: await fileExists(menus[0]) || await fileExists(menus[1])
+			}];
+		} else if (platform === "darwin") entries = [{
+			id: "finder",
+			label: "Finder 快速操作",
+			registered: await fileExists(finderWorkflowPath()),
+			manual: true
+		}];
+	}
+	return {
+		platform,
+		launcher,
+		entries,
+		baseUrl,
+		unityPackagePath: unitySourceDir()
+	};
+}
+/**
+* 注册右键菜单（平台分发）：写 ini → 安装 launcher → 首次备份（Windows）→ 写菜单；
+* 成功后写 marker（驱动卸载清理与重启自动恢复）。
+* @author ddj 2026年09月07号
+* @param ctx DSH 上下文
+* @param baseUrl 深链基址
+* @returns 注册后状态
+*/
+async function shellMenuRegister(ctx, baseUrl) {
+	const dir = shellInstallDir();
+	await mkdir(dir, { recursive: true });
+	if (process.platform === "win32") {
+		await writeFile(join(dir, INI_NAME), iniContent(baseUrl), "utf8");
+		await installIcon(dir);
+		const compiled = await installLauncher(ctx, dir, true);
+		if (!await readMarker()) await backupKeys(ctx, dir);
+		await writeMenuKeys(ctx, dir, compiled);
+	} else if (process.platform === "linux") {
+		await installPosix(dir, baseUrl);
+		const launcherPath = join(dir, LAUNCHER_SH);
+		await writeNautilus(homedir(), launcherPath);
+		await writeDolphinMenus(homedir(), launcherPath);
+	} else if (process.platform === "darwin") await installPosix(dir, baseUrl);
+	await saveMarker(baseUrl);
+	return shellMenuStatus(ctx, baseUrl);
+}
+/**
+* 移除右键菜单注册（平台分发）+ 删除 marker（显式移除后重启不再自动恢复）。
+* @author ddj 2026年09月07号
+* @param ctx DSH 上下文
+* @param baseUrl 深链基址
+* @returns 移除后状态
+*/
+async function shellMenuRemove(ctx, baseUrl) {
+	if (process.platform === "win32") {
+		const paths = menuKeyPaths();
+		for (const key of [
+			paths.files,
+			paths.dir,
+			paths.background
+		]) await runArgv(ctx, [
+			regExe(),
+			"delete",
+			key,
+			"/f"
+		]);
+	} else if (process.platform === "linux") await removePosixFiles(homedir());
+	else if (process.platform === "darwin") await dropFinderMenu(homedir());
+	await rm(markerFile(), { force: true });
+	return shellMenuStatus(ctx, baseUrl);
+}
+/**
+* 系统集成生命周期（index.ts 经 ctx.effect 挂载）：
+* 启动时 marker 存在 → 幂等自动恢复注册（插件更新/reload 不丢注册）；
+* 返回的 disposer 在插件卸载/reload 时清理注册痕迹（marker 保留供下次恢复）。
+* @author ddj 2026年09月07号
+* @param ctx DSH 上下文
+* @returns 卸载清理 disposer
+*/
+function shellMenuLifecycle(ctx) {
+	restoreOnLoad(ctx).catch(() => {});
+	return () => {
+		cleanupOnUnload().catch(() => {});
+	};
+}
+/** 启动自动恢复：marker 存在才执行（幂等；exe 已存在跳过编译）。 */
+async function restoreOnLoad(ctx) {
+	const marker = await readMarker();
+	if (!marker) return;
+	await shellMenuRegister(ctx, marker.baseUrl);
+}
+/** 卸载清理：marker 存在 → 按平台移除注册痕迹（launcher 文件与 marker 保留）。 */
+async function cleanupOnUnload() {
+	if (!await readMarker()) return;
+	if (process.platform === "win32") {
+		const paths = menuKeyPaths();
+		for (const key of [
+			paths.files,
+			paths.dir,
+			paths.background
+		]) await regDeleteDirect(key);
+	} else if (process.platform === "linux") await removePosixFiles(homedir());
+	else if (process.platform === "darwin") await dropFinderMenu(homedir());
+}
+/**
+* 安装 Windows launcher：优先 csc 编译 exe（无控制台闪窗），任一候选失败降级复制 ps1。
+* @author ddj 2026年09月07号
+* @param ctx DSH 上下文
+* @param dir 安装目录（已存在）
+* @param force 是否强制重编译（自动恢复时 false：exe 已存在直接复用）
+* @returns 是否编译成功（false=降级 ps1）
+*/
+async function installLauncher(ctx, dir, force) {
+	const exe = join(dir, LAUNCHER_EXE);
+	if (!force && await fileExists(exe)) return true;
+	const shellAssets = join(assetsDirOf(import.meta.url), "shell");
+	for (const candidate of cscCandidates()) {
+		if (!await fileExists(candidate)) continue;
+		try {
+			await copyFile(join(shellAssets, LAUNCHER_CS), join(dir, LAUNCHER_CS));
+			if ((await runArgv(ctx, [
+				candidate,
+				"/nologo",
+				"/target:winexe",
+				"/r:System.Windows.Forms.dll",
+				"/r:System.Web.Extensions.dll",
+				"/out:" + exe,
+				join(dir, "dsh-open.cs")
+			], dir)).code === 0 && await fileExists(exe)) return true;
+		} catch {}
+	}
+	await copyFile(join(shellAssets, LAUNCHER_PS1), join(dir, LAUNCHER_PS1));
+	return false;
+}
+/**
+* 首次注册前备份 Windows 三类既有键（best-effort，键不存在时导出失败忽略）。
+* @author ddj 2026年09月07号
+* @param ctx DSH 上下文
+* @param dir 备份文件落盘目录
+*/
+async function backupKeys(ctx, dir) {
+	const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+	const paths = menuKeyPaths();
+	const targets = [
+		[paths.files, "files"],
+		[paths.dir, "dir"],
+		[paths.background, "background"]
+	];
+	for (const [key, name] of targets) await runArgv(ctx, [
+		regExe(),
+		"export",
+		key,
+		join(dir, "backup-" + name + "-" + stamp + ".reg"),
+		"/y"
+	], dir);
+}
+/** 复制 DSH 小鲸鱼 ico 到安装目录（右键菜单 Icon 用；缺失不阻塞注册）。 */
+async function installIcon(dir) {
+	try {
+		await copyFile(join(assetsDirOf(import.meta.url), "shell", WHALE_ICO), join(dir, WHALE_ICO));
+	} catch {}
+}
+/**
+* 写 Windows 三类菜单键（显示名 + Icon + command 子键）。
+* @author ddj 2026年09月07号
+* @param ctx DSH 上下文
+* @param dir launcher 安装目录
+* @param compiled 是否为编译 exe（否则 ps1 command）
+*/
+async function writeMenuKeys(ctx, dir, compiled) {
+	const launcherPath = compiled ? join(dir, LAUNCHER_EXE) : join(dir, LAUNCHER_PS1);
+	const iconPath = await fileExists(join(dir, "dsh-whale.ico")) ? join(dir, WHALE_ICO) : launcherPath;
+	const keys = [
+		[menuKeyPaths().files, "%1"],
+		[menuKeyPaths().dir, "%1"],
+		[menuKeyPaths().background, "%V"]
+	];
+	for (const [key, token] of keys) await addMenuKey(ctx, key, iconPath, compiled ? commandValue(launcherPath, token) : ps1CommandValue(launcherPath, token));
+}
+/** 写一个 Windows 菜单键：默认值（显示名）+ Icon + command 子键。 */
+async function addMenuKey(ctx, key, iconPath, command) {
+	const reg = regExe();
+	await runArgv(ctx, [
+		reg,
+		"add",
+		key,
+		"/ve",
+		"/t",
+		"REG_SZ",
+		"/d",
+		MENU_LABEL,
+		"/f"
+	]);
+	await runArgv(ctx, [
+		reg,
+		"add",
+		key,
+		"/v",
+		REG_VALUE_NAME_ICON,
+		"/t",
+		"REG_SZ",
+		"/d",
+		iconPath,
+		"/f"
+	]);
+	await runArgv(ctx, [
+		reg,
+		"add",
+		key + "\\command",
+		"/ve",
+		"/t",
+		"REG_SZ",
+		"/d",
+		command,
+		"/f"
+	]);
+}
+//#endregion
+//#region src/externalHandoff.ts
+/**
+* dsh-vscode-mode host — 深链移交（避免重复打开 DSH 页面）。
+* launcher 投递待打开请求（edrv.external.handoff）→ 已打开页面 3s 轮询领取（edrv.external.pending）
+* 并就地执行打开规则；15s 内无页面轮询过 = 无活跃页面 → launcher 回退打开新页。
+* token 防多实例串扰；TTL 兜底防陈旧悬挂。模块级状态（host 单进程单例）。
+* 作者 ddj 2026-09-08
+*/
+/** 待打开 TTL：超时未领取即丢弃（launcher 回退已自行处理）。 */
+const PENDING_TTL_MS = 6e4;
+/** 活跃页面判定窗口：窗口内有过 pending 轮询 = 有页面在。 */
+const PRESENCE_WINDOW_MS = 15e3;
+let pending = null;
+let lastPollAt = 0;
+/**
+* 投递一次外部打开请求；返回活跃页面数（0 = launcher 应回退开新页）与移交 token。
+* @author ddj 2026年09月08号
+* @param req 打开请求
+* @returns 活跃页面数与 token
+*/
+function handoffOpen(req) {
+	const token = randomUUID();
+	pending = {
+		...req,
+		token,
+		at: Date.now()
+	};
+	return {
+		token,
+		clients: clientsAlive() ? 1 : 0
+	};
+}
+/**
+* 页面轮询：刷新活跃态并领取待打开请求（取走即清，多页面仅一方执行）。
+* @author ddj 2026年09月08号
+* @returns 待打开请求或 null
+*/
+function pollPending() {
+	lastPollAt = Date.now();
+	if (!pending) return null;
+	if (Date.now() - pending.at > PENDING_TTL_MS) {
+		pending = null;
+		return null;
+	}
+	const taken = {
+		paths: pending.paths,
+		line: pending.line,
+		column: pending.column
+	};
+	pending = null;
+	return taken;
+}
+/**
+* 查询移交是否已被页面领取（take=true 时未领取则取走清除，供 launcher 回退开新页）。
+* @author ddj 2026年09月08号
+* @param token 移交 token
+* @param take 未领取时是否取走清除
+* @returns delivered=true = 已有页面领取（或已被更新的请求取代）
+*/
+function pendingState(token, take) {
+	const delivered = pending === null || pending.token !== token;
+	if (take && !delivered) pending = null;
+	return { delivered };
+}
+/** 活跃页面判定。 */
+function clientsAlive() {
+	return Date.now() - lastPollAt <= PRESENCE_WINDOW_MS;
+}
+//#endregion
 //#region src/reveal.ts
 /**
 * dsh-vscode-mode host — 在 OS 文件浏览器中打开/定位路径（reveal 能力）。
@@ -5002,6 +5944,11 @@ async function latestPatchBackup(patchPath) {
 	const base = basename(patchPath);
 	return (await readdir(dir).catch(() => [])).filter((n) => n.startsWith(base + ".bak-")).sort().reverse()[0];
 }
+/** 读取设置中的深链基址（缺省/非法回退默认 3080）。 */
+async function integrationBaseUrlOf(ctx) {
+	const value = (ctx.get("settings")?.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.value;
+	return (typeof value?.integrationBaseUrl === "string" ? value.integrationBaseUrl.trim() : "") || "http://127.0.0.1:3080";
+}
 /** 各方法 handler 表（类型由 shared/rpc 的 RpcHandlerMap 约束）。 */
 function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearcher = newContentSearcher(ctx), lspHandlers) {
 	return {
@@ -5568,6 +6515,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			return {
 				ok: true,
 				fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool ?? "auto"),
+				integrationBaseUrl: await integrationBaseUrlOf(ctx),
 				revision: descriptor?.revision
 			};
 		},
@@ -5578,12 +6526,15 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				error: "设置服务不可用"
 			};
 			try {
-				await settings.update(FILE_OPEN_SETTINGS_NS, { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) }, args.expectedRevision);
+				const patch = { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) };
+				if (typeof args.integrationBaseUrl === "string" && args.integrationBaseUrl.trim()) patch.integrationBaseUrl = args.integrationBaseUrl.trim();
+				await settings.update(FILE_OPEN_SETTINGS_NS, patch, args.expectedRevision);
 				const descriptor = settings.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS);
 				const value = descriptor?.value;
 				return {
 					ok: true,
 					fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool),
+					integrationBaseUrl: await integrationBaseUrlOf(ctx),
 					revision: descriptor?.revision
 				};
 			} catch (error) {
@@ -5620,6 +6571,135 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				};
 			}
 		},
+		"edrv.integration.status": async () => {
+			try {
+				return {
+					ok: true,
+					...await shellMenuStatus(ctx, await integrationBaseUrlOf(ctx))
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.integration.register": async () => {
+			try {
+				return {
+					ok: true,
+					...await shellMenuRegister(ctx, await integrationBaseUrlOf(ctx))
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.integration.unregister": async () => {
+			try {
+				return {
+					ok: true,
+					...await shellMenuRemove(ctx, await integrationBaseUrlOf(ctx))
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.unity.list": async () => {
+			try {
+				return {
+					ok: true,
+					...await unityList()
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.unity.add": async (args) => {
+			try {
+				return {
+					ok: true,
+					project: await unityAdd(args.path)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.unity.remove": async (args) => {
+			try {
+				await unityRemove(args.path);
+				return { ok: true };
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.unity.install": async (args) => {
+			try {
+				return {
+					ok: true,
+					project: await unityInstall(args.path)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.externalStat": async (args) => {
+			const fs = ctx.get("fs");
+			if (!fs) return {
+				ok: false,
+				error: "缺少 fs"
+			};
+			try {
+				const target = await fs.resolve(args.path);
+				const info = await fs.stat(target);
+				if (!info || info.type === "other") return {
+					ok: true,
+					kind: "missing"
+				};
+				return {
+					ok: true,
+					kind: info.type === "directory" ? "directory" : "file"
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.external.handoff": async (args) => ({
+			ok: true,
+			...handoffOpen({
+				paths: args.paths,
+				line: args.line,
+				column: args.column
+			})
+		}),
+		"edrv.external.pending": async () => ({
+			ok: true,
+			open: pollPending()
+		}),
+		"edrv.external.pendingState": async (args) => ({
+			ok: true,
+			delivered: pendingState(args.token, args.take === true).delivered
+		}),
 		"edrv.perf.inventory": async () => {
 			try {
 				const home = dshHome();
@@ -8963,6 +10043,7 @@ function apply(ctx, config) {
 	});
 	registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher, contentSearcher, lspHandlers), (warning) => warnings.push(warning));
 	installIsolation(ctx);
+	ctx.effect(() => shellMenuLifecycle(ctx));
 	sweepTreeCache();
 	logCompatSummary(ctx, warnings);
 	ctx.effect(() => () => {