dsh-vscode-mode 0.1.15 → 0.1.16

package/lib/index.js

@@ -2,10 +2,335 @@ import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import { dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
-import z from "schemastery";
+//#region src/mcp.ts
+/**
+* dsh-vscode-mode host — MCP 运行时管理适配层。
+* 只操作已装配的 @deepseek-ai/dsh-mcp-client loader entry，不在浏览器侧连接 MCP。
+* 身份常量（包名/条目前缀/新旧格式判定）统一由 compat 层持有，本模块再导出保持既有 import 面。
+* 作者 ddj 2026年08月22号
+*/
+/** 列出当前 loader 中的 MCP entry。 */
+function entriesOf(ctx) {
+	const loader = ctx.get("loader");
+	if (!loader || typeof loader.entries !== "function") return [];
+	return [...loader.entries()].filter((entry) => entry?.options?.name === MCP_PACKAGE);
+}
+/** 脱敏配置并保留可编辑字段的存在性。 */
+function publicConfig(config) {
+	const out = { ...config };
+	if (out.env && typeof out.env === "object") out.env = Object.fromEntries(Object.keys(out.env).map((key) => [key, "••••••"]));
+	if (out.headers && typeof out.headers === "object") out.headers = Object.fromEntries(Object.keys(out.headers).map((key) => [key, "••••••"]));
+	return out;
+}
+/** 从工具注册表读取服务器命名空间下的工具摘要。 */
+function toolsOf(ctx, serverName) {
+	const visible = (ctx.get("tools")?.view?.(void 0))?.visible;
+	if (!(visible instanceof Map)) return [];
+	const prefix = `mcp__${serverName}__`;
+	return [...visible.entries()].filter(([name]) => String(name).startsWith(prefix)).map(([name, definition]) => ({
+		name: String(name).slice(prefix.length),
+		description: typeof definition?.description === "string" ? definition.description : void 0
+	}));
+}
+/** 将 loader entry 映射为设置页摘要。 */
+function serverOf(ctx, entry) {
+	const config = entry.options?.config ?? {};
+	const serverName = typeof config.serverName === "string" ? config.serverName : entry.options?.id ?? "unknown";
+	const tools = toolsOf(ctx, serverName);
+	const state = entry.fiber?.state;
+	return {
+		id: String(entry.id ?? entry.options?.id ?? serverName),
+		serverName,
+		enabled: entry.disabled !== true,
+		transport: config.transport === "streamable-http" ? "streamable-http" : "stdio",
+		config: publicConfig(config),
+		status: state === 2 ? "connected" : state === 1 ? "connecting" : "error",
+		toolCount: tools.length,
+		tools,
+		error: state === 3 ? "MCP 插件未正常运行" : void 0
+	};
+}
+/** 校验 MCP 配置。 */
+function validateConfig(config) {
+	if (!/^[A-Za-z0-9_-]{1,32}$/.test(config.serverName)) throw new Error("serverName 只能包含字母、数字、下划线和连字符（最多 32 位）");
+	if (config.transport === "stdio" && !config.command?.trim()) throw new Error("stdio MCP 必须填写 command");
+	if (config.transport === "streamable-http" && !/^https?:\/\//.test(config.url ?? "")) throw new Error("HTTP MCP 必须填写 http(s) URL");
+}
+/** 列出全局（profile）MCP 服务，过滤掉新旧格式的项目级条目。 */
+function listMcp(ctx) {
+	return { servers: entriesOf(ctx).filter((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? ""))).map((entry) => serverOf(ctx, entry)) };
+}
+/** 保存 MCP 服务配置并触发 loader 热更新。 */
+async function saveMcp(ctx, config) {
+	validateConfig(config);
+	const loader = ctx.get("loader");
+	if (!loader) throw new Error("缺少 loader 服务");
+	const existing = entriesOf(ctx).find((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? "")) && entry.options?.config?.serverName === config.serverName);
+	if (existing) {
+		await loader.update(existing.id, { config: { ...config } });
+		return serverOf(ctx, loader.resolve(existing.id));
+	}
+	const id = await loader.create({
+		name: MCP_PACKAGE,
+		config: { ...config }
+	});
+	return serverOf(ctx, loader.resolve(id));
+}
+/** 删除 MCP 服务。 */
+async function removeMcp(ctx, id) {
+	const loader = ctx.get("loader");
+	if (!loader) throw new Error("缺少 loader 服务");
+	const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id);
+	if (!entry) throw new Error("MCP 服务不存在");
+	await loader.remove(entry.id);
+}
+/** 切换 MCP 服务启用状态。 */
+async function toggleMcp(ctx, id, enabled) {
+	const loader = ctx.get("loader");
+	if (!loader) throw new Error("缺少 loader 服务");
+	const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id);
+	if (!entry) throw new Error("MCP 服务不存在");
+	await loader.update(entry.id, { disabled: !enabled });
+	return serverOf(ctx, loader.resolve(entry.id));
+}
+/** 重新加载 MCP 服务。 */
+async function refreshMcp(ctx, id) {
+	const loader = ctx.get("loader");
+	if (!loader) throw new Error("缺少 loader 服务");
+	const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id);
+	if (!entry) throw new Error("MCP 服务不存在");
+	await loader.update(entry.id, { config: { ...entry.options?.config ?? {} } });
+	return serverOf(ctx, loader.resolve(entry.id));
+}
+//#endregion
+//#region src/fileOpenSettings.ts
+const FILE_OPEN_SETTINGS_NS = "dsh-vscode-mode";
+const FILE_OPEN_DEFAULT = "auto";
+let depsPromise;
+/**
+* 动态加载设置依赖（模块级缓存；任一缺失返回 null 而非抛错）。
+* @author ddj 2026年08月24号
+* @returns 设置依赖或 null
+*/
+function loadSettingsDeps() {
+	if (!depsPromise) depsPromise = Promise.all([import("@deepseek-ai/dsh-settings"), import("schemastery")]).then(([dshSettings, schemastery]) => ({
+		installSettingsSection: dshSettings.installSettingsSection,
+		z: schemastery.default
+	})).catch(() => null);
+	return depsPromise;
+}
+function normalizeValue(value) {
+	if (typeof value !== "string" || value.trim() === "") return FILE_OPEN_DEFAULT;
+	return value.trim();
+}
+function configValue(config) {
+	return normalizeValue(config?.fileOpenTool);
+}
+/**
+* 安装设置 section（动态依赖；缺失返回 false 不抛错）。
+* @author ddj 2026年08月24号
+* @param ctx DSH host 上下文
+* @param ns 设置命名空间
+* @param entry 初始设置值
+* @param hooks 设置源绑定与变更回调
+* @param loader 依赖装载器（测试注入）
+* @returns 是否成功安装
+*/
+async function installOpenSettingsSection(ctx, ns, entry, hooks, loader = loadSettingsDeps) {
+	const deps = await loader();
+	if (!deps) return false;
+	const schema = deps.z.object({ fileOpenTool: deps.z.string().default(FILE_OPEN_DEFAULT) });
+	deps.installSettingsSection(ctx, ns, schema, entry, hooks);
+	return true;
+}
+/**
+* 注册设置命名空间，并提供 host 侧的读取与更新状态。
+* @author ddj 2026年08月24号
+* @param ctx DSH host 上下文
+* @param config 插件组合配置
+* @param onChange 设置变化回调
+* @returns 设置状态
+*/
+function setupOpenSettings(ctx, config, onChange) {
+	let current = configValue(config);
+	let revision;
+	let provider;
+	const notify = (value) => {
+		current = normalizeValue(value);
+		onChange(current);
+	};
+	const syncRevision = () => {
+		revision = (provider?.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.revision;
+	};
+	const setSource = (source) => notify(source().fileOpenTool);
+	const settingsChange = () => syncRevision();
+	installOpenSettingsSection(ctx, FILE_OPEN_SETTINGS_NS, { fileOpenTool: current }, {
+		setSource,
+		onChange: settingsChange
+	});
+	ctx.inject?.(["settings"], (settingsCtx) => {
+		provider = settingsCtx.get("settings");
+		syncRevision();
+	});
+	return {
+		get value() {
+			return current;
+		},
+		get revision() {
+			return revision;
+		},
+		update: async (value, expectedRevision) => {
+			const next = normalizeValue(value);
+			if (!provider?.update) {
+				notify(next);
+				return;
+			}
+			await provider.update(FILE_OPEN_SETTINGS_NS, { fileOpenTool: next }, expectedRevision);
+			const stored = (provider.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.value;
+			notify(stored?.fileOpenTool ?? next);
+			syncRevision();
+		}
+	};
+}
+function normalizeFileOpenTool(value) {
+	return normalizeValue(value);
+}
+//#endregion
+//#region src/compat.ts
+/**
+* dsh-vscode-mode host — 兼容层：与其他插件 / DSH 版本的统一探测、适配、护栏与自诊断。
+* 职责：身份常量（包名 / MCP 条目前缀 / 路由前缀）、外部插件探测、路由冲突与重复装配检测、
+*       兼容性报告构建（RPC edrv.compat 与启动日志共用）。
+* 注意：与 mcp.ts 存在模块环（compat 提供身份常量、mcp 提供 entriesOf），
+*       双方仅在函数体内交叉使用导出，模块求值期无依赖，ESM 安全。
+* 作者 ddj 2026-08-24
+*/
+const PLUGIN_NAME = "dsh-vscode-mode";
+const MCP_PACKAGE = "@deepseek-ai/dsh-mcp-client";
+/** 项目级 MCP 的 loader entry id 固定前缀（区分 profile 全局 MCP；loader id 不能用 ':'，故用 '.'）。 */
+const PROJECT_ENTRY_PREFIX = "vsm-mcp.";
+/** webServer 路由前缀（RPC 精确路由 + 静态资源前缀共用）。 */
+const ROUTE_PREFIX = "/edrv";
+/** 判断新旧格式项目 MCP 条目 id（旧残留不被视为全局 MCP）。 */
+function isProjectEntryId(id) {
+	return id.startsWith("vsm-mcp.") || id.startsWith("vsm-mcp:");
+}
+/** 从项目条目 id 解析 workspace hash（新旧格式通用）。 */
+function entryHash(id) {
+	if (id.startsWith("vsm-mcp.")) return id.slice(8).split(".")[0];
+	if (id.startsWith("vsm-mcp:")) return id.slice(8).split(":")[0];
+}
+/** 读取随包 package.json 版本号（缺失/解析失败降级为空串）。 */
+function pluginVersionOf() {
+	try {
+		const file = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+		const pkg = JSON.parse(readFileSync(file, "utf8"));
+		return typeof pkg.version === "string" ? pkg.version : "";
+	} catch {
+		return "";
+	}
+}
+/** 探测外部插件/服务适配状态（depsAvailable 由调用方注入，便于测试）。 */
+function detectExternal(ctx, depsAvailable) {
+	const mcpCount = entriesOf(ctx).length;
+	const settings = ctx.get("settings");
+	const hasSettings = Boolean(settings?.describe || settings?.update);
+	return [
+		{
+			name: MCP_PACKAGE,
+			active: mcpCount > 0,
+			note: mcpCount > 0 ? mcpCount + " 个 MCP 服务条目" : "未检测到 MCP 条目（MCP 管理页显示为空）"
+		},
+		{
+			name: "设置持久化（@deepseek-ai/dsh-settings）",
+			active: depsAvailable,
+			note: depsAvailable ? "设置 section 已安装" : "未安装：fileOpenTool 持久化降级为配置值"
+		},
+		{
+			name: "settings 服务",
+			active: hasSettings,
+			note: hasSettings ? "可读写设置" : "不可用（设置读写走配置回退）"
+		}
+	];
+}
+/** 本插件已注册的路由（kind → path 集合），冲突检测时排除自身，避免自误报。 */
+const ownRoutes = {
+	exact: /* @__PURE__ */ new Set(),
+	prefixes: /* @__PURE__ */ new Set()
+};
+/** 清空本插件路由记录（registerRoutes 装配开始时调用，热重载不残留）。 */
+function resetOwnRoutes() {
+	ownRoutes.exact.clear();
+	ownRoutes.prefixes.clear();
+}
+/** 记录本插件路由（routes.ts 注册成功时调用）。 */
+function noteOwnRoute(kind, path) {
+	(kind === "exact" ? ownRoutes.exact : ownRoutes.prefixes).add(path);
+}
+/** 检测路由前缀占用与重叠（排除本插件自有路由；内部表不可读视为无冲突）。 */
+function routeConflict(web, prefix) {
+	try {
+		const w = web;
+		const exact = w?.exact;
+		const prefixes = w?.prefixes;
+		if (exact instanceof Map) for (const path of exact.keys()) {
+			const other = String(path);
+			if (other.startsWith(prefix + "/") && !ownRoutes.exact.has(other)) return "精确路由 " + other + " 与 " + prefix + " 前缀重叠（可能来自热重载残留或其他插件）";
+		}
+		if (prefixes instanceof Map) for (const path of prefixes.keys()) {
+			const other = String(path);
+			if (other !== prefix && (other.startsWith(prefix + "/") || prefix.startsWith(other + "/")) && !ownRoutes.prefixes.has(other)) return "路由前缀 " + prefix + " 与 " + other + " 重叠";
+		}
+	} catch {}
+	return null;
+}
+/** 检测本插件是否被重复装配（bundle 层 + 用户层重复 insert 的自诊断）。 */
+function duplicateEntries(ctx) {
+	const loader = ctx.get("loader");
+	if (!loader || typeof loader.entries !== "function") return [];
+	const own = [...loader.entries()].filter((entry) => String(entry.options?.name ?? entry.id ?? "") === PLUGIN_NAME);
+	if (own.length > 1) return ["检测到 " + own.length + " 个 dsh-vscode-mode loader 条目（重复装配）。请删除 profile 用户层 cordis.patch.yml 的重复 insert（或运行 dev_fix_patch 清理）"];
+	return [];
+}
+/** 护栏适配状态：路由前缀唯一性 + 插件装配唯一性。 */
+function detectGuards(ctx) {
+	const web = ctx.get("webServer");
+	const conflict = web ? routeConflict(web, ROUTE_PREFIX) : null;
+	const duplicates = duplicateEntries(ctx);
+	return [{
+		name: "路由前缀 /edrv",
+		active: !conflict,
+		note: conflict ?? "无冲突"
+	}, {
+		name: "插件装配唯一性",
+		active: duplicates.length === 0,
+		note: duplicates[0] ?? "唯一装配"
+	}];
+}
+/**
+* 构建完整兼容性报告（RPC 与启动日志共用）。
+* @author ddj 2026年08月24号
+* @param ctx DSH host 上下文
+* @param options 测试注入：depsAvailable 跳过动态导入、version 固定版本号
+* @returns 兼容性报告
+*/
+async function buildReport(ctx, options) {
+	const deps = options?.depsAvailable ?? await loadSettingsDeps() !== null;
+	const external = detectExternal(ctx, deps);
+	const guards = detectGuards(ctx);
+	const warnings = [];
+	if (!deps) warnings.push("未安装 @deepseek-ai/dsh-settings：文件打开工具设置持久化不可用（降级为配置值）");
+	for (const guard of guards) if (!guard.active && guard.note) warnings.push(guard.note);
+	return {
+		pluginVersion: options?.version ?? pluginVersionOf(),
+		external,
+		guards,
+		warnings
+	};
+}
+//#endregion
 //#region src/shared/rpc.ts
 /** webServer 精确路由。 */
 const RPC_PATH = "/edrv/rpc";
@@ -50,17 +375,32 @@ function imageDirOf(config) {
 /** Monaco AMD 静态目录（随包发布）。 */
 const vendorDir = join(dirname(fileURLToPath(import.meta.url)), "..", "assets", "vendor");
 /**
-* 注册全部 webServer 路由。
+* 注册全部 webServer 路由（带兼容护栏：前缀冲突预警 + 注册失败降级跳过）。
 * @author ddj 2026年08月20号
 * @param ctx DSH 上下文
 * @param config 插件配置（可选 imageDir 等）
 * @param handleRpc RPC 分发入口（method,args → RpcResult）
+* @param onWarning 兼容性警告收集（可选）
 */
-function registerRoutes(ctx, config, handleRpc) {
+function registerRoutes(ctx, config, handleRpc, onWarning) {
 	const imgDir = imageDirOf(config);
 	const web = ctx.get("webServer");
 	if (!web) return;
-	ctx.effect(() => web.register({
+	resetOwnRoutes();
+	const conflict = routeConflict(web, ROUTE_PREFIX);
+	if (conflict) onWarning?.("兼容性：" + conflict);
+	/** 护栏注册：重复路由抛错时降级为警告并跳过，不让单条路由拖垮装配。 */
+	const guarded = (route, label) => {
+		try {
+			const dispose = web.register(route);
+			noteOwnRoute(route.kind, route.path);
+			return dispose;
+		} catch (error) {
+			onWarning?.("兼容性：" + label + " 注册失败（" + String(error) + "）");
+			return;
+		}
+	};
+	ctx.effect(() => guarded({
 		kind: "exact",
 		path: RPC_PATH,
 		handler: async (req, res) => {
@@ -85,8 +425,8 @@ function registerRoutes(ctx, config, handleRpc) {
 				}));
 			}
 		}
-	}), "edrv: /edrv/rpc route");
-	for (const r of IMG_ROUTES) ctx.effect(() => web.register({
+	}, "/edrv/rpc 精确路由"), "edrv: routes");
+	for (const r of IMG_ROUTES) ctx.effect(() => guarded({
 		kind: "exact",
 		path: r.url,
 		handler: async (req, res) => {
@@ -101,8 +441,8 @@ function registerRoutes(ctx, config, handleRpc) {
 				res.end();
 			}
 		}
-	}), "edrv: static " + r.file);
-	ctx.effect(() => web.register({
+	}, "静态资源 " + r.file), "edrv: routes");
+	ctx.effect(() => guarded({
 		kind: "prefix",
 		path: VENDOR_PREFIX,
 		handler: async (req, res) => {
@@ -135,7 +475,7 @@ function registerRoutes(ctx, config, handleRpc) {
 				res.end();
 			}
 		}
-	}), "edrv: /edrv/vendor prefix");
+	}, "/edrv/vendor 前缀路由"), "edrv: routes");
 }
 //#endregion
 //#region src/shared/diff.ts
@@ -1646,109 +1986,6 @@ async function restoreFile(ctx, session, rec) {
 	}
 }
 //#endregion
-//#region src/mcp.ts
-const MCP_PACKAGE = "@deepseek-ai/dsh-mcp-client";
-/** 项目级 MCP 的 loader entry id 固定前缀（区分 profile 全局 MCP；注意 loader id 不能用 ':' 分隔，故用 '.'）。 */
-const PROJECT_ENTRY_PREFIX = "vsm-mcp.";
-const LEGACY_PROJECT_PREFIX = "vsm-mcp:";
-/** 判断新旧格式项目 entry id，避免旧残留被显示为全局 MCP。 */
-function isProjectEntryId(id) {
-	return id.startsWith("vsm-mcp.") || id.startsWith(LEGACY_PROJECT_PREFIX);
-}
-/** 列出当前 loader 中的 MCP entry。 */
-function entriesOf(ctx) {
-	const loader = ctx.get("loader");
-	if (!loader || typeof loader.entries !== "function") return [];
-	return [...loader.entries()].filter((entry) => entry?.options?.name === MCP_PACKAGE);
-}
-/** 脱敏配置并保留可编辑字段的存在性。 */
-function publicConfig(config) {
-	const out = { ...config };
-	if (out.env && typeof out.env === "object") out.env = Object.fromEntries(Object.keys(out.env).map((key) => [key, "••••••"]));
-	if (out.headers && typeof out.headers === "object") out.headers = Object.fromEntries(Object.keys(out.headers).map((key) => [key, "••••••"]));
-	return out;
-}
-/** 从工具注册表读取服务器命名空间下的工具摘要。 */
-function toolsOf(ctx, serverName) {
-	const visible = (ctx.get("tools")?.view?.(void 0))?.visible;
-	if (!(visible instanceof Map)) return [];
-	const prefix = `mcp__${serverName}__`;
-	return [...visible.entries()].filter(([name]) => String(name).startsWith(prefix)).map(([name, definition]) => ({
-		name: String(name).slice(prefix.length),
-		description: typeof definition?.description === "string" ? definition.description : void 0
-	}));
-}
-/** 将 loader entry 映射为设置页摘要。 */
-function serverOf(ctx, entry) {
-	const config = entry.options?.config ?? {};
-	const serverName = typeof config.serverName === "string" ? config.serverName : entry.options?.id ?? "unknown";
-	const tools = toolsOf(ctx, serverName);
-	const state = entry.fiber?.state;
-	return {
-		id: String(entry.id ?? entry.options?.id ?? serverName),
-		serverName,
-		enabled: entry.disabled !== true,
-		transport: config.transport === "streamable-http" ? "streamable-http" : "stdio",
-		config: publicConfig(config),
-		status: state === 2 ? "connected" : state === 1 ? "connecting" : "error",
-		toolCount: tools.length,
-		tools,
-		error: state === 3 ? "MCP 插件未正常运行" : void 0
-	};
-}
-/** 校验 MCP 配置。 */
-function validateConfig(config) {
-	if (!/^[A-Za-z0-9_-]{1,32}$/.test(config.serverName)) throw new Error("serverName 只能包含字母、数字、下划线和连字符（最多 32 位）");
-	if (config.transport === "stdio" && !config.command?.trim()) throw new Error("stdio MCP 必须填写 command");
-	if (config.transport === "streamable-http" && !/^https?:\/\//.test(config.url ?? "")) throw new Error("HTTP MCP 必须填写 http(s) URL");
-}
-/** 列出全局（profile）MCP 服务，过滤掉新旧格式的项目级条目。 */
-function listMcp(ctx) {
-	return { servers: entriesOf(ctx).filter((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? ""))).map((entry) => serverOf(ctx, entry)) };
-}
-/** 保存 MCP 服务配置并触发 loader 热更新。 */
-async function saveMcp(ctx, config) {
-	validateConfig(config);
-	const loader = ctx.get("loader");
-	if (!loader) throw new Error("缺少 loader 服务");
-	const existing = entriesOf(ctx).find((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? "")) && entry.options?.config?.serverName === config.serverName);
-	if (existing) {
-		await loader.update(existing.id, { config: { ...config } });
-		return serverOf(ctx, loader.resolve(existing.id));
-	}
-	const id = await loader.create({
-		name: MCP_PACKAGE,
-		config: { ...config }
-	});
-	return serverOf(ctx, loader.resolve(id));
-}
-/** 删除 MCP 服务。 */
-async function removeMcp(ctx, id) {
-	const loader = ctx.get("loader");
-	if (!loader) throw new Error("缺少 loader 服务");
-	const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id);
-	if (!entry) throw new Error("MCP 服务不存在");
-	await loader.remove(entry.id);
-}
-/** 切换 MCP 服务启用状态。 */
-async function toggleMcp(ctx, id, enabled) {
-	const loader = ctx.get("loader");
-	if (!loader) throw new Error("缺少 loader 服务");
-	const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id);
-	if (!entry) throw new Error("MCP 服务不存在");
-	await loader.update(entry.id, { disabled: !enabled });
-	return serverOf(ctx, loader.resolve(entry.id));
-}
-/** 重新加载 MCP 服务。 */
-async function refreshMcp(ctx, id) {
-	const loader = ctx.get("loader");
-	if (!loader) throw new Error("缺少 loader 服务");
-	const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id);
-	if (!entry) throw new Error("MCP 服务不存在");
-	await loader.update(entry.id, { config: { ...entry.options?.config ?? {} } });
-	return serverOf(ctx, loader.resolve(entry.id));
-}
-//#endregion
 //#region src/mcpProject.ts
 /**
 * dsh-vscode-mode host — 项目级 MCP 管理。
@@ -2023,74 +2260,6 @@ async function projectRefresh(ctx, workspacePath, serverName) {
 	return projectOf(ctx, workspacePath, workspace.title ?? "");
 }
 //#endregion
-//#region src/fileOpenSettings.ts
-/**
-* dsh-vscode-mode host — 文件链接打开工具的持久化设置。
-* @author ddj 2026年08月24号
-*/
-const FILE_OPEN_SETTINGS_NS = settingsNamespace("dsh-vscode-mode");
-const FILE_OPEN_DEFAULT = "auto";
-const FILE_OPEN_SCHEMA = z.object({ fileOpenTool: z.string().default(FILE_OPEN_DEFAULT) });
-function normalizeValue(value) {
-	if (typeof value !== "string" || value.trim() === "") return FILE_OPEN_DEFAULT;
-	return value.trim();
-}
-function configValue(config) {
-	return normalizeValue(config?.fileOpenTool);
-}
-/**
-* 注册设置命名空间，并提供 host 侧的读取与更新状态。
-* @author ddj 2026年08月24号
-* @param ctx DSH host 上下文
-* @param config 插件组合配置
-* @param onChange 设置变化回调
-* @returns 设置状态
-*/
-function setupOpenSettings(ctx, config, onChange) {
-	let current = configValue(config);
-	let revision;
-	let provider;
-	const notify = (value) => {
-		current = normalizeValue(value);
-		onChange(current);
-	};
-	const syncRevision = () => {
-		revision = (provider?.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.revision;
-	};
-	const setSource = (source) => notify(source().fileOpenTool);
-	const settingsChange = () => syncRevision();
-	installSettingsSection(ctx, FILE_OPEN_SETTINGS_NS, FILE_OPEN_SCHEMA, { fileOpenTool: current }, {
-		setSource,
-		onChange: settingsChange
-	});
-	ctx.inject?.(["settings"], (settingsCtx) => {
-		provider = settingsCtx.get("settings");
-		syncRevision();
-	});
-	return {
-		get value() {
-			return current;
-		},
-		get revision() {
-			return revision;
-		},
-		update: async (value, expectedRevision) => {
-			const next = normalizeValue(value);
-			if (!provider?.update) {
-				notify(next);
-				return;
-			}
-			await provider.update(FILE_OPEN_SETTINGS_NS, { fileOpenTool: next }, expectedRevision);
-			const stored = (provider.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.value;
-			notify(stored?.fileOpenTool ?? next);
-			syncRevision();
-		}
-	};
-}
-function normalizeFileOpenTool(value) {
-	return normalizeValue(value);
-}
-//#endregion
 //#region src/rpc.ts
 /** cwd → Promise 链：串行化 debug 日志追加（fs read+write 非原子，避免并发丢行）。 */
 const debugWriteQueues = /* @__PURE__ */ new Map();
@@ -2617,7 +2786,11 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx)) {
 					error: String(error)
 				};
 			}
-		}
+		},
+		"compat": async () => ({
+			ok: true,
+			report: await buildReport(ctx)
+		})
 	};
 }
 /**
@@ -2640,7 +2813,6 @@ async function handleRpc(ctx, registry, method, args, searcher = newSearcher(ctx
 * tools.restrict() 负责模型可见性，tools.guard() 负责执行层兜底拒绝。
 * 作者 ddj 2026年08月22号
 */
-const LEGACY_PREFIX = "vsm-mcp:";
 const UNKNOWN_PROJECT = "__unknown_project__";
 /** 统一 workspace 路径，供 cwd 父路径匹配。 */
 function normalizePath(path) {
@@ -2657,15 +2829,8 @@ function matchWorkspace(cwd, paths) {
 	matches.sort((a, b) => normalizePath(b).length - normalizePath(a).length);
 	return matches[0];
 }
-/** 根据 entry id 判断是否为新旧格式项目 MCP。 */
-function isProjectEntry(id) {
-	return id.startsWith("vsm-mcp.") || id.startsWith(LEGACY_PREFIX);
-}
-/** 从项目 entry id 解析 workspace hash。 */
-function entryHash(id) {
-	if (id.startsWith("vsm-mcp.")) return id.slice(8).split(".")[0];
-	if (id.startsWith(LEGACY_PREFIX)) return id.slice(8).split(":")[0];
-}
+/** 根据 entry id 判断是否为新旧格式项目 MCP（兼容层统一判定）。 */
+const isProjectEntry = isProjectEntryId;
 /** 返回一个 agent 不应继承的项目工具名。 */
 function denyTools(toolProjects, currentPath) {
 	return [...toolProjects.entries()].filter(([, owner]) => owner !== currentPath).map(([name]) => name).sort();
@@ -2779,9 +2944,10 @@ function dropFileIndex(cwd) {
 //#region src/index.ts
 /**
 * @dsh-external 生态 → dsh-vscode-mode：DSH 上的类 VSCode 编码体验（Host 半入口）。
-* 职责：装配 capture（tools/result 捕获 edit/write 差异）、RPC 分发（11 个 edrv.* 方法）、
-*       webServer 路由（/edrv/rpc、/edrv/assets/*、/edrv/vendor/*）、工作区旁车持久化。
-* 结构：shared/（双面契约） + model/store/capture/workspace/revert/registry/rpc/routes（host 模块）。
+* 职责：装配 capture（tools/result 捕获 edit/write 差异）、RPC 分发（edrv.* / mcp.* / vscode.* / compat）、
+*       webServer 路由（/edrv/rpc、/edrv/assets/*、/edrv/vendor/*）、工作区旁车持久化、
+*       兼容层装配（依赖守卫 + 重复装配自诊断 + 启动日志兼容性报告）。
+* 结构：shared/（双面契约） + model/store/capture/workspace/revert/registry/rpc/routes/compat（host 模块）。
 * 作者 ddj 2026-08-20
 */
 const name = "dsh-vscode-mode";
@@ -2795,7 +2961,7 @@ const inject = [
 	"agents"
 ];
 /**
-* 装配插件：挂事件监听、注册路由。
+* 装配插件：挂事件监听、注册路由、安装兼容层。
 * @author ddj 2026年08月20号
 * @param ctx DSH 上下文（sessions/fs/webServer 由 inject 提供；sandboxPolicy/subprocess 惰性获取）
 * @param config 插件配置（可选 imageDir 覆盖图标目录）
@@ -2803,6 +2969,8 @@ const inject = [
 function apply(ctx, config) {
 	const registry = /* @__PURE__ */ new Map();
 	const searcher = newSearcher(ctx);
+	/** 兼容性警告收集（route 护栏等写入，启动日志一并输出）。 */
+	const warnings = [];
 	setupOpenSettings(ctx, config, () => {});
 	ctx.on("tools/result", (exec, result) => {
 		captureToolResult(ctx, registry, exec, result);
@@ -2815,10 +2983,30 @@ function apply(ctx, config) {
 			searcher.dispose(cwd);
 		}
 	});
-	registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher));
+	registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher), (warning) => warnings.push(warning));
 	installIsolation(ctx);
+	logCompatSummary(ctx, warnings);
 	ctx.logger?.info?.("[dsh-vscode-mode] 编辑差异审查已装配（/edrv/rpc 路由就绪，项目 MCP 隔离已启用）");
 }
+/**
+* 异步输出兼容性报告摘要（含重复装配/路由冲突自诊断）。
+* @author ddj 2026年08月24号
+* @param ctx DSH host 上下文
+* @param warnings 装配期收集的兼容性警告
+*/
+async function logCompatSummary(ctx, warnings) {
+	try {
+		const report = await buildReport(ctx);
+		for (const warning of warnings) report.warnings.push(warning);
+		const logger = ctx.logger;
+		if (!logger?.info) return;
+		const head = "[dsh-vscode-mode] 兼容性：" + report.external.length + " 项外部适配 / " + report.guards.length + " 项护栏";
+		if (report.warnings.length) logger.warn?.(head + "，警告 " + report.warnings.length + " 条：" + report.warnings.join("；"));
+		else logger.info?.(head + "，无警告");
+	} catch (error) {
+		ctx.logger?.warn?.("[dsh-vscode-mode] 兼容性报告生成失败：" + String(error));
+	}
+}
 //#endregion
 export { apply, inject, name };