dsh-vscode-mode 0.5.3 → 0.6.0

package/lib/index.js

@@ -6,7 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir, tmpdir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { Buffer as Buffer$1 } from "node:buffer";
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { inflateRawSync } from "node:zlib";
 //#region src/mcp.ts
 /**
@@ -134,7 +134,13 @@ const KEYBINDING_DEFAULTS = {
 	"edrv.nextEditorRow": "Ctrl+Alt+ArrowDown",
 	"edrv.prevEditorRow": "Ctrl+Alt+ArrowUp",
 	"edrv.addSelectionRef": "Ctrl+U",
-	"edrv.closeTab": "Ctrl+F4"
+	"edrv.closeTab": "Ctrl+F4",
+	"edrv.debugToggleBreakpoint": "F9",
+	"edrv.debugStartContinue": "F5",
+	"edrv.debugStepOver": "F10",
+	"edrv.debugStepInto": "F11",
+	"edrv.debugStepOut": "Shift+F11",
+	"edrv.debugStop": "Shift+F5"
 };
 //#endregion
 //#region src/shared/integration.ts
@@ -183,6 +189,23 @@ function tortoiseLaunchArgv(exe, action, absPath) {
 		"/path:" + absPath
 	];
 }
+/** W2-6 内容护栏嗅探窗（字符数；NUL/U+FFFD 只看前 8K，全量扫描大文本得不偿失）。 */
+const GUARD_SNIFF_CHARS = 8192;
+/**
+* 文本级内容护栏（W2-6，纯函数）：对喂给差异视图/补丁的文本做低成本嗅探。
+* 二进制锚点取 NUL 字节（比 svn:mime-type 更兜底——mime 缺省的「伪文本」二进制也拦得住）；
+* 编码提示取 U+FFFD（host fs.readText 按 UTF-8 解码，无效序列会变成替换符）。
+* @author ddj 2026年09月20号
+* @param text 待嗅探文本（null/undefined 按空处理）
+* @returns 护栏标记（干净内容返回空对象）
+*/
+function contentGuardOf(text) {
+	if (typeof text !== "string" || !text) return {};
+	const window = text.slice(0, GUARD_SNIFF_CHARS);
+	if (window.includes("\0")) return { binary: true };
+	if (window.includes("�")) return { encodingHint: true };
+	return {};
+}
 //#endregion
 //#region src/shared/logger.ts
 /**
@@ -3347,7 +3370,12 @@ function pathMatch(value, query) {
 const STDOUT_CAP$1 = 4 << 20;
 const STDERR_CAP$2 = 65536;
 const GRACE_MS$1 = 2e4;
-/** 默认排除目录（文件/内容搜索共用，导出供 provider 复用）。 */
+/**
+* 默认排除目录（文件/内容搜索共用，导出供 provider 复用）。
+* 语义为**大小写敏感**的路径段匹配：`build` 只排除小写构建产物目录，
+* 不得用 `--glob-case-insensitive` 之类的全局开关，「Module/Build」这类
+* 源码目录（如 IslandSplash 的 Module/Build/Logic）必须保持可搜索。
+*/
 const EXCLUDES = [
 	"node_modules",
 	".git",
@@ -3375,13 +3403,31 @@ const FILE_EXCLUDES = [
 	"**/*.map"
 ];
 /**
-* 将 query 转成 rg 的字面 glob。
-* @author ddj 2026年08月24号
-* @param query 已规范化 query
+* 将查询文本转成大小写不敏感的 rg 正选 glob。
+* 逐字符把有大小写的字母展开成 `[aA]` 字符类，**不用**大小写不敏感开关：
+* ① 全局 `--glob-case-insensitive` 会把 `-g/--glob` 全部当成 `--iglob`，
+*    连带让 `!**\/build/**` 大小写不敏感，从而排除 `Module/Build/` 这类源码目录
+*    （Ctrl+P 搜 BuildLogic 恒「无匹配文件」）；
+* ② 把查询词改用 `--iglob` 也不行——rg 的正选 glob 会覆盖全部黑名单 glob，
+*    node_modules/.git 等排除项集体失效。
+* 字符类方案同时满足「查询不区分大小写」且「排除项保持大小写敏感」。
+* @author ddj 2026年08月24号 / 2026年09月20号
+* @param query 已规范化查询文本
 * @returns 安全 glob
 */
 function queryGlob(query) {
-	return "**/*" + pathText(query).replace(/[\*?\[\]{}!]/g, (char) => "\\" + char) + "*";
+	const value = pathText(query);
+	let body = "";
+	for (const char of value) {
+		const lower = char.toLowerCase();
+		const upper = char.toUpperCase();
+		if (lower !== upper && lower.length === 1 && upper.length === 1) {
+			body += "[" + lower + upper + "]";
+			continue;
+		}
+		body += /[\*?\[\]{}!]/.test(char) ? "\\" + char : char;
+	}
+	return "**/*" + body + "*";
 }
 /**
 * 返回当前平台的 rg 可执行文件路径，不让可选依赖影响模块加载。
@@ -3496,32 +3542,45 @@ function rgExitFailure(code, stderrText) {
 	};
 }
 /**
-* 使用打包 ripgrep 搜索工作区文件。
-* @author ddj 2026年08月24号
-* @param input provider 输入
-* @returns 有界搜索结果
+* 构造文件搜索 rg argv（查询 glob 大小写不敏感，排除 glob 大小写敏感）。
+* 大小写不敏感**只能**靠 queryGlob 的字符类实现：全局 `--glob-case-insensitive`
+* 会波及排除项（误排除 `Module/Build/`），查询词用 `--iglob` 又会覆盖全部黑名单 glob。
+* @author ddj 2026年09月20号
+* @param binary rg 可执行文件路径
+* @param root 搜索根目录
+* @param query 已规范化查询文本
+* @returns 完整 argv（末位为根目录）
 */
-async function searchRipgrep(input) {
-	const sub = input.ctx.get("subprocess");
-	if (!sub) throw new Error("缺少 subprocess");
-	const binary = ripgrepPath();
-	if (!binary) throw new Error("ripgrep 不可用");
-	const root = input.root ?? await searchRoot(input.ctx, input.session);
+function filesArgv(binary, root, query) {
 	const argv = [
 		binary,
 		"--no-config",
 		"--files",
 		"--hidden",
 		"--no-ignore",
-		"--glob-case-insensitive",
 		"--glob",
-		queryGlob(prepareQuery(input.query).text)
+		queryGlob(query)
 	];
 	for (const excluded of EXCLUDES) argv.push("--glob", "!**/" + excluded + "/**");
 	for (const excluded of FILE_EXCLUDES) argv.push("--glob", "!" + excluded);
 	argv.push("--", root);
+	return argv;
+}
+/**
+* 使用打包 ripgrep 搜索工作区文件。
+* @author ddj 2026年08月24号
+* @param input provider 输入
+* @returns 有界搜索结果
+*/
+async function searchRipgrep(input) {
+	const sub = input.ctx.get("subprocess");
+	if (!sub) throw new Error("缺少 subprocess");
+	const binary = ripgrepPath();
+	if (!binary) throw new Error("ripgrep 不可用");
+	const root = input.root ?? await searchRoot(input.ctx, input.session);
+	const query = prepareQuery(input.query);
 	const handle = sub.spawn({
-		argv,
+		argv: filesArgv(binary, root, query.text),
 		cwd: root,
 		stdio: {
 			stdin: "ignore",
@@ -3556,6 +3615,93 @@ async function searchRipgrep(input) {
 	};
 }
 /**
+* 构造 chunkname 定向查找的 rg argv。
+* 与 {@link filesArgv} 同源（同样的排除 glob 与大小写口径），差异只在查询 glob 由
+* chunkname 推导：chunkname 可能带 chunk 前缀（`@`）与无扩展名 stem，故先剥 `@`、
+* 取 basename、去掉扩展名后作为片段匹配，仍走 {@link queryGlob} 的字符类方案
+* ——避免 `--glob-case-insensitive` 波及排除项（见 queryGlob 注释）。
+* @author ddj 2026年09月21号
+* @param binary rg 可执行文件路径
+* @param root 搜索根目录
+* @param chunk 适配器上报的 chunkname
+* @returns 完整 argv（末位为根目录）；chunk 为空时返回 null
+*/
+function chunkFilesArgv(binary, root, chunk) {
+	const clean = normalizeChunk(chunk);
+	if (!clean) return null;
+	const argv = [
+		binary,
+		"--no-config",
+		"--files",
+		"--hidden",
+		"--no-ignore",
+		"--glob",
+		queryGlob(clean)
+	];
+	for (const excluded of EXCLUDES) argv.push("--glob", "!**/" + excluded + "/**");
+	for (const excluded of FILE_EXCLUDES) argv.push("--glob", "!" + excluded);
+	argv.push("--", root);
+	return argv;
+}
+/**
+* chunkname → 用于片段匹配的纯文件名片段。
+* 剥 `@` 前缀、统一分隔符、取 basename、去掉扩展名（xLua chunkname 惯例不含扩展名），
+* 使 `GuideSystemMgr` 能命中 `GuideSystemMgr.lua`。
+* @author ddj 2026年09月21号
+* @param chunk 适配器上报的 chunkname
+* @returns 纯片段（空输入返回空串）
+*/
+function normalizeChunk(chunk) {
+	const text = String(chunk ?? "").replace(/^@/, "").replaceAll("\\", "/").trim();
+	if (!text) return "";
+	return (text.split("/").pop() ?? "").replace(/\.[^.]+$/, "");
+}
+/**
+* 按 chunkname 定向查找工作区文件（DAP findFile 反向匹配专用）。
+*
+* 为什么不用工作区全量文件索引：22 万文件的 Unity 工程里，全量枚举按到达序截断，
+* `Assets/Scripts/Lua/**` 会被 `GameData`/`Entitas` 等目录挤出配额，导致断点命中后
+* 无法定位源文件（实测前 6000 条中 .lua 数为 0）。此处改为让 rg 在遍历时过滤，
+* 命中规模与工作区总规模无关（实测同一工作区 0.37s 返回正确结果）。
+* @author ddj 2026年09月21号
+* @param ctx DSH 上下文
+* @param root 工作区根（subprocess 可访问路径）
+* @param chunk 适配器上报的 chunkname
+* @param maxResults 候选上限
+* @returns 绝对路径候选（任何失败都返回空数组，不抛错）
+*/
+async function findFilesByChunk(ctx, root, chunk, maxResults = 50) {
+	const sub = ctx.get("subprocess");
+	const binary = ripgrepPath();
+	if (!sub || !binary || !root) return [];
+	const argv = chunkFilesArgv(binary, root, chunk);
+	if (!argv) return [];
+	let handle;
+	try {
+		handle = sub.spawn({
+			argv,
+			cwd: root,
+			stdio: {
+				stdin: "ignore",
+				stdout: { maxBytes: STDOUT_CAP$1 },
+				stderr: { maxBytes: STDERR_CAP$2 }
+			},
+			graceMs: GRACE_MS$1
+		});
+	} catch (error) {
+		return [];
+	}
+	let code;
+	try {
+		const outcome = await handle.done;
+		code = outcome.exitCode ?? outcome.code;
+	} catch (error) {
+		return [];
+	}
+	if (code !== 0 && code !== 1 && code !== 2) return [];
+	return parseOutput(handle, maxResults).files;
+}
+/**
 * 构造 ripgrep provider。
 * @author ddj 2026年08月24号
 * @returns provider 实例
@@ -6528,10 +6674,14 @@ function clientsAlive() {
 //#region src/reveal.ts
 /**
 * dsh-vscode-mode host — 在 OS 文件浏览器中打开/定位路径（reveal 能力）。
-* 纯函数 revealCommand 平台分发 + revealInExplorer 经 ctx.subprocess.spawn 发射
-* （argv 数组、无 shell 插值，沿 workspace/revert 的 subprocess 契约）。
+* 纯函数 revealCommand 平台分发 + revealSpawnOpts 启动选项 + revealInExplorer 发射。
 * 文件 → 资源管理器选中定位；目录 → 打开目录；Linux 无通用定位协议 → 打开所在目录。
-* 作者 ddj 2026-08-27
+*
+* 刻意**不经** ctx.subprocess.spawn：DSH 的 Windows Job runner 硬编码
+* `windowsHide: true`（dsh-subprocess-local 的 launchWindowsJob 与 runner 内部 spawn），
+* 连 explorer.exe 的 GUI 窗口一并隐藏——RPC 回 ok:true 但窗口根本不出现。
+* GUI 拉起属 fire-and-forget，用 node child_process + detached + unref 才贴合语义。
+* 作者 ddj 2026年08月27号 / 2026年09月20号
 */
 /**
 * 构造平台 opener 的 argv（纯函数，platform 可注入便于单测）。
@@ -6557,32 +6707,47 @@ function revealCommand(absPath, isDir, platform = process.platform) {
 	}
 }
 /**
-* 经 host subprocess 服务发射 opener（fire-and-forget 语义）。
-* Explorer 为 GUI 分离进程，非零退出码不视为失败；仅 spawn 级错误回失败。
-* @author ddj 2026年08月27号
-* @param ctx DSH host 上下文
+* 构造 opener 子进程启动选项。
+* `windowsHide` 必须为 **false**：置 true 会把 Explorer 等 GUI 窗口一起隐藏，
+* 症状即「RPC 回 ok:true 但窗口不出现」（本文件头注释记录的回归）。
+* @author ddj 2026年09月20号
+* @param cwd 子进程工作目录（打开文件时用其父目录）
+* @returns child_process.spawn 选项
+*/
+function revealSpawnOpts(cwd) {
+	return {
+		cwd,
+		stdio: "ignore",
+		windowsHide: false,
+		detached: true
+	};
+}
+/**
+* 发射 opener 拉起 OS 文件浏览器（fire-and-forget 语义）。
+* Explorer 为 GUI 分离进程，非零退出码不视为失败，故只等 spawn 事件即返回；
+* 子进程脱离父进程组并 unref，避免阻塞宿主退出。
+* @author ddj 2026年08月27号 / 2026年09月20号
 * @param absPath 绝对路径
 * @param isDir 是否为目录
 * @returns 成功或失败原因
 */
-async function revealInExplorer(ctx, absPath, isDir) {
-	const sub = ctx.get("subprocess");
-	if (!sub || typeof sub.spawn !== "function") return {
+async function revealInExplorer(absPath, isDir) {
+	const [program, ...args] = revealCommand(absPath, isDir).argv;
+	if (!program) return {
 		ok: false,
-		error: "打开文件浏览器不可用：缺少 subprocess 服务"
+		error: "打开失败：opener 命令为空"
 	};
-	const { argv } = revealCommand(absPath, isDir);
 	try {
-		await sub.spawn({
-			argv,
-			cwd: dirname(absPath),
-			stdio: {
-				stdout: { maxBytes: 65536 },
-				stderr: { maxBytes: 65536 },
-				stdin: "ignore"
-			},
-			graceMs: 1e4
-		}).done;
+		await new Promise((resolve, reject) => {
+			const child = spawn(program, args, revealSpawnOpts(dirname(absPath)));
+			child.once("spawn", () => {
+				child.unref();
+				resolve();
+			});
+			child.once("error", (error) => {
+				reject(error);
+			});
+		});
 		return { ok: true };
 	} catch (error) {
 		return {
@@ -7375,11 +7540,12 @@ async function integrationBaseUrlOf(ctx) {
 	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, aiHandlers, fileVersions, svnHandlers) {
+function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearcher = newContentSearcher(ctx), lspHandlers, aiHandlers, fileVersions, svnHandlers, dapHandlers) {
 	return {
 		...lspHandlers ?? {},
 		...aiHandlers ?? {},
 		...svnHandlers ?? {},
+		...dapHandlers ?? {},
 		"edrv.list": async (args) => {
 			const sc = await requireSession(ctx, args.sessionId);
 			if ("err" in sc) return {
@@ -7493,6 +7659,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			};
 			try {
 				const target = await resolveTarget(ctx, sc.session, args.path);
+				debugRecord(ctx, sc.cwd, "[DEBUG path.resolve] input=" + String(args.path ?? "") + " resolved=" + fs.processPath(target), "debug");
 				const info = await fs.stat(target);
 				if (!info || info.type !== "file") return {
 					ok: false,
@@ -7552,6 +7719,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			};
 			try {
 				const target = await resolveTarget(ctx, sc.session, args.path);
+				debugRecord(ctx, sc.cwd, "[DEBUG path.resolve] input=" + String(args.path ?? "") + " resolved=" + fs.processPath(target), "debug");
 				const info = await fs.stat(target);
 				if (!info || info.type !== "file") return {
 					ok: false,
@@ -7615,6 +7783,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			};
 			try {
 				const target = await resolveTarget(ctx, sc.session, args.path);
+				debugRecord(ctx, sc.cwd, "[DEBUG path.resolve] input=" + String(args.path ?? "") + " resolved=" + fs.processPath(target), "debug");
 				const rev = typeof args.rev === "string" && args.rev ? args.rev : null;
 				const intent = rev ? {
 					kind: "replaceIfVersion",
@@ -7655,6 +7824,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			};
 			try {
 				const target = await resolveTarget(ctx, sc.session, args.path);
+				debugRecord(ctx, sc.cwd, "[DEBUG path.resolve] input=" + String(args.path ?? "") + " resolved=" + fs.processPath(target), "debug");
 				const info = await fs.stat(target);
 				if (!info || info.type !== "file") return {
 					ok: false,
@@ -7850,7 +8020,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			};
 		},
 		"edrv.dlog.reveal": async () => {
-			const revealed = await revealInExplorer(ctx, pluginLogRoot(), true);
+			const revealed = await revealInExplorer(pluginLogRoot(), true);
 			if (!revealed.ok) return {
 				ok: false,
 				error: revealed.error
@@ -7954,7 +8124,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 					error: "路径不存在"
 				};
 				const abs = fs.processPath(target);
-				const outcome = await revealInExplorer(ctx, abs, info.type === "directory");
+				const outcome = await revealInExplorer(abs, info.type === "directory");
 				if (!outcome.ok) return {
 					ok: false,
 					error: outcome.error
@@ -8618,8 +8788,8 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 * 统一入口：按方法分发到 handler 表。
 * @author ddj 2026年08月20号 / 2026年08月26号
 */
-async function handleRpc(ctx, registry, method, args, searcher = newSearcher(ctx), contentSearcher = newContentSearcher(ctx), lspHandlers, aiHandlers, fileVersions, svnHandlers) {
-	const handler = buildHandlers(ctx, registry, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions, svnHandlers)[method];
+async function handleRpc(ctx, registry, method, args, searcher = newSearcher(ctx), contentSearcher = newContentSearcher(ctx), lspHandlers, aiHandlers, fileVersions, svnHandlers, dapHandlers) {
+	const handler = buildHandlers(ctx, registry, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions, svnHandlers, dapHandlers)[method];
 	if (!handler) return {
 		ok: false,
 		error: "未知方法: " + String(method)
@@ -8754,14 +8924,6 @@ function installIsolation(ctx) {
 	}, "vscode-mode:mcp-isolation");
 }
 //#endregion
-//#region src/workspace.ts
-/** cwd → { at, files }（随会话销毁清理）。 */
-const fileIndex = /* @__PURE__ */ new Map();
-/** 会话销毁时清理文件索引缓存。 */
-function dropFileIndex(cwd) {
-	fileIndex.delete(cwd);
-}
-//#endregion
 //#region src/lsp/jsonrpc.ts
 /**
 * dsh-vscode-mode host — LSP JSON-RPC 帧编解码（纯函数，node 可测）。
@@ -10247,6 +10409,11 @@ async function updateExtension(id) {
 * 产物 LspProviderSpec：{ ready, argv, cwd, reason }，供 manager 启动服务器。
 * 作者 ddj 2026-08-27
 */
+/** 语言 → 扩展名（用于判断哪些文件触发该语言服务器）。 */
+const LSP_LANG_EXT = {
+	lua: ["lua"],
+	csharp: ["cs", "csx"]
+};
 /** 平台目录名（LuaLS/OmniSharp 的 server/bin/<平台>）。 */
 function platformServerDir(platform = process.platform) {
 	if (platform === "win32") return "Windows";
@@ -10397,7 +10564,8 @@ function sdkEnvOf(sdkRoot) {
 	if (version) env.DOTNET_SDK_PATH = join(sdkRoot, "sdk", version);
 	return env;
 }
-/** 读扩展目录 package.json 的 version（读取失败不影响入口使用，返回 undefined）。 */
+/** 读扩展目录 package.json 的 version（读取失败不影响入口使用，返回 undefined）。
+* 导出供 dap/discovery 复用（扩展清单版本排序同口径，避免第二份实现）。 */
 function manifestVersionOf(extDir) {
 	try {
 		const manifest = JSON.parse(readFileSync(join(extDir, "package.json"), "utf8"));
@@ -12732,6 +12900,21 @@ const READ_GRACE_MS = 3e4;
 const MUTATE_GRACE_MS = 12e4;
 /** 文本读取上限（对齐 rpc.ts READ_CAP：>8MB 拒绝整文件读取/差异）。 */
 const READ_CAP = 8388608;
+/**
+* W2-1 补丁文本输出上限（16MB）。实测教训复用（PROGRESS §六.1）：DSH stdout 收集器
+* 超限**保留尾部**——补丁被截断时头部 `Index:` 会丢失，host 以「不以 Index: 开头」
+* 标记 truncated，客户端明示「不完整」而非让用户拿半份补丁去用。
+*/
+const PATCH_OUTPUT_CAP = 16777216;
+/** W2-2 目录对比 summarize 输出上限（8MB；大目录长区间的变更条目 XML）。 */
+const SUM_OUTPUT_CAP = 8388608;
+/**
+* W2-3 远端检查超时（15s）。M3 实测：无凭据/离线时 `status -u` 会长时间挂起
+* （受限沙箱内 120s 无输出），远端检查必须短超时 + 失败降级，绝不阻塞面板。
+*/
+const REMOTE_GRACE_MS = 15e3;
+/** W2-2 summarize 服务器往返预算（大目录长区间可能较慢）。 */
+const SUM_GRACE_MS = 6e4;
 /** 工作副本根向上查找（≤10 层，命中含 .svn 的最近祖先）。 */
 const SVN_ROOT_MAX_DEPTH = 10;
 /** 默认存在性探测（node fs；异常一律按不存在）。 */
@@ -12892,6 +13075,130 @@ function parseStatusXml(xml, cap = CHANGES_CAP) {
 		truncated
 	};
 }
+/**
+* 绝对路径 → 工作副本相对路径（W2-2/W2-3：M3/M5 实测 XML 中 path 为绝对路径）。
+* Windows 大小写不敏感文件系统：前缀匹配按小写比较，剥离后保留原大小写。
+* @author ddj 2026年09月20号
+* @param abs 绝对路径（`/` 或 `\` 分隔均可）
+* @param wcRoot 工作副本根绝对路径
+* @returns 相对路径（`/` 分隔）；不在根下返回 null
+*/
+function relPathOfAbs(abs, wcRoot) {
+	const norm = (p) => String(p ?? "").replace(/\\/g, "/").replace(/\/+$/, "");
+	const a = norm(abs);
+	const r = norm(wcRoot);
+	if (!r || !a.toLowerCase().startsWith(r.toLowerCase() + "/")) return null;
+	return a.slice(r.length + 1);
+}
+/**
+* W2-1 补丁的 `-x` 扩展选项组合（纯函数）。
+* 冒烟实测修正（2026-09-20）：本机 svn 内部 diff 的上下文行数只认 `-U<N>`，
+* `--unified=N` 报 E200016 erroneous argument（07 计划 §1 当年只核对了 help 文案，未实测）。
+* @author ddj 2026年09月20号
+* @param opts 空白语义 / EOL 忽略 / 上下文行数
+* @returns 空格连接的单个 `-x` 值；无选项时空串
+*/
+function patchExtOf(opts) {
+	const parts = [];
+	if (opts.whitespace === "b") parts.push("-b");
+	if (opts.whitespace === "w") parts.push("-w");
+	if (opts.ignoreEol === true) parts.push("--ignore-eol-style");
+	const unified = Math.floor(Number(opts.unified));
+	if (Number.isFinite(unified) && unified >= 0 && unified <= 100 && unified !== 3) parts.push("-U" + unified);
+	return parts.join(" ");
+}
+/**
+* 解析 `svn diff --summarize --xml` 输出（W2-2；M5 实测形态，svn 1.14.5）：
+* `<diff><paths><path item="modified" kind="file" props="none">ABS:\\PATH</path>...`
+* - path 的**文本内容**是绝对路径（非属性）→ relPathOfAbs 归一为工作副本相对；
+* - 属性输出顺序不稳定（与 M1 log 同款教训），只按字段名取值、不做字符串快照；
+* - 区间无变更时 `<paths>` 为空 → entries 为空数组（非错误）。
+* @author ddj 2026年09月20号
+* @param xml summarize --xml 的 stdout
+* @param wcRoot 工作副本根（路径归一锚点）
+* @param cap 条目上限（超出标记 truncated）
+* @returns 变更条目与是否截断
+*/
+function parseSummarizeXml(xml, wcRoot, cap = CHANGES_CAP) {
+	const entries = [];
+	let truncated = false;
+	if (typeof xml !== "string" || !xml) return {
+		entries,
+		truncated
+	};
+	const re = /<path\b([^>]*?)>([\s\S]*?)<\/path>/g;
+	let match;
+	while ((match = re.exec(xml)) !== null) {
+		const abs = unescapeXml(match[2].trim());
+		const rel = relPathOfAbs(abs, wcRoot) ?? changePathOf(abs);
+		if (!rel) continue;
+		if (entries.length >= cap) {
+			truncated = true;
+			break;
+		}
+		entries.push({
+			path: rel,
+			item: attrOf(match[1], "item") || "none",
+			kind: attrOf(match[1], "kind") || "none",
+			props: attrOf(match[1], "props") || "none"
+		});
+	}
+	return {
+		entries,
+		truncated
+	};
+}
+/**
+* 解析 `svn status -u --xml` 输出（W2-3；M3 实测形态，svn 1.14.5）：
+* `<entry path="ABS"><wc-status ...>...</wc-status><repos-status item="modified" props="none"/></entry>` + `<against revision="N"/>`
+* - 落后锚点 = 存在 `<repos-status>` 且 `item !== 'none'`（实测落后文件为 modified）；
+*   远端无变化的条目**没有** repos-status 元素（省略，非 'none' 值）；
+* - 离线/无凭据时会长时间挂起（M3 实测 120s+），调用方必须用 REMOTE_GRACE_MS 短超时。
+* @author ddj 2026年09月20号
+* @param xml status -u --xml 的 stdout
+* @param wcRoot 工作副本根（路径归一锚点）
+* @param cap 条目上限（超出标记 truncated）
+* @returns 落后清单 + against 修订
+*/
+function parseRemoteStatusXml(xml, wcRoot, cap = CHANGES_CAP) {
+	const outdated = [];
+	let againstRev = null;
+	let truncated = false;
+	if (typeof xml !== "string" || !xml) return {
+		outdated,
+		againstRev,
+		truncated
+	};
+	const against = /<against\b([^>]*?)\/?>/.exec(xml);
+	if (against) {
+		const rev = numAttrOf(against[1], "revision");
+		if (rev !== void 0) againstRev = rev;
+	}
+	const re = /<entry\b([^>]*?)>([\s\S]*?)<\/entry>/g;
+	let match;
+	while ((match = re.exec(xml)) !== null) {
+		const repos = /<repos-status\b([^>]*?)\/?>/.exec(match[2]);
+		if (!repos) continue;
+		const item = attrOf(repos[1], "item");
+		if (!item || item === "none") continue;
+		const rawPath = attrOf(match[1], "path");
+		const rel = relPathOfAbs(rawPath, wcRoot) ?? changePathOf(rawPath);
+		if (!rel) continue;
+		if (outdated.length >= cap) {
+			truncated = true;
+			break;
+		}
+		outdated.push({
+			path: rel,
+			item
+		});
+	}
+	return {
+		outdated,
+		againstRev,
+		truncated
+	};
+}
 /** 进程名（去路径去 .exe；前台助手用）。 */
 function processNameOf(exe) {
 	return (exe.split(/[\\/]/).pop() ?? exe).replace(/\.exe$/i, "");
@@ -13349,6 +13656,48 @@ function createSvnRpc(deps) {
 			error: sides[0].error ?? sides[1].error
 		};
 	};
+	/**
+	* 扫描冲突副本文件（W2-4；svn 冲突时的标准后缀 `.mine`/`.working`/`.rN`，纯本地 fs 只读）。
+	* @author ddj 2026年09月20号
+	* @param wcRoot 工作副本根
+	* @param rel 冲突文件的工作副本相对路径
+	* @returns 副本清单（rev 升序 → working → mine；默认对比对 = 首个 .rN ↔ .mine）
+	*/
+	const conflictArtifactsOf = async (wcRoot, rel) => {
+		const abs = join(wcRoot, rel);
+		const base = basename(abs);
+		const names = await readdir(dirname(abs));
+		const rankOf = (kind) => kind === "rev" ? 0 : kind === "working" ? 1 : 2;
+		const artifacts = [];
+		for (const name of names) {
+			let kind = null;
+			let rev;
+			if (name === base + ".mine") kind = "mine";
+			else if (name === base + ".working") kind = "working";
+			else if (name.startsWith(base + ".r") && /^\d+$/.test(name.slice(base.length + 2))) {
+				kind = "rev";
+				rev = Number.parseInt(name.slice(base.length + 2), 10);
+			}
+			if (kind === null) continue;
+			const artifactPath = relPathOfAbs(join(dirname(abs), name), wcRoot);
+			if (!artifactPath) continue;
+			artifacts.push({
+				path: artifactPath,
+				name,
+				kind,
+				...rev !== void 0 ? { rev } : {}
+			});
+		}
+		return artifacts.sort((a, b) => rankOf(a.kind) - rankOf(b.kind) || (a.rev ?? 0) - (b.rev ?? 0) || a.name.localeCompare(b.name));
+	};
+	/** W2-6：双侧内容护栏标记（干净时返回空对象，展开进载荷不添字段）。 */
+	const guardSides = (a, b) => {
+		const merged = {
+			...contentGuardOf(a ?? ""),
+			...contentGuardOf(b ?? "")
+		};
+		return merged.binary || merged.encodingHint ? merged : {};
+	};
 	return { handlers: {
 		"svn.status": async (args) => {
 			const sc = await requireSvnSession(ctx, args.sessionId);
@@ -13441,13 +13790,15 @@ function createSvnRpc(deps) {
 						base: null,
 						working,
 						reason: /pristine|E200009/i.test(text) ? "no-pristine" : "cat-failed",
-						error: tailOfText(text)
+						error: tailOfText(text),
+						...guardSides(null, working)
 					};
 				}
 				return {
 					ok: true,
 					base: outcome.stdout,
-					working
+					working,
+					...guardSides(outcome.stdout, working)
 				};
 			} catch (error) {
 				return {
@@ -13528,9 +13879,11 @@ function createSvnRpc(deps) {
 				error: "svn 命令不可用（可在设置页配置 svn 路径）"
 			};
 			try {
+				const result = await diffRevSides(status.wcRoot, rel, Math.floor(revision));
 				return {
 					ok: true,
-					...await diffRevSides(status.wcRoot, rel, Math.floor(revision))
+					...result,
+					...guardSides(result.left, result.right)
 				};
 			} catch (error) {
 				return {
@@ -13566,9 +13919,11 @@ function createSvnRpc(deps) {
 				error: "svn 命令不可用（可在设置页配置 svn 路径）"
 			};
 			try {
+				const result = await pairSides(status.wcRoot, rel, Math.floor(revA), Math.floor(revB));
 				return {
 					ok: true,
-					...await pairSides(status.wcRoot, rel, Math.floor(revA), Math.floor(revB))
+					...result,
+					...guardSides(result.left, result.right)
 				};
 			} catch (error) {
 				return {
@@ -13631,12 +13986,14 @@ function createSvnRpc(deps) {
 					left: null,
 					right: working,
 					reason: "not-exist",
-					error: tailOfText((leftOutcome.stderr || leftOutcome.stdout).trim())
+					error: tailOfText((leftOutcome.stderr || leftOutcome.stdout).trim()),
+					...guardSides(null, working)
 				};
 				return {
 					ok: true,
 					left: leftOutcome.stdout,
-					right: working
+					right: working,
+					...guardSides(leftOutcome.stdout, working)
 				};
 			} catch (error) {
 				return {
@@ -13645,7 +14002,7 @@ function createSvnRpc(deps) {
 				};
 			}
 		},
-		"svn.wcRev": async (args) => {
+		"svn.patchText": async (args) => {
 			const sc = await requireSvnSession(ctx, args.sessionId);
 			if ("err" in sc) return {
 				ok: false,
@@ -13653,8 +14010,8 @@ function createSvnRpc(deps) {
 			};
 			const rel = safeRel(args.path);
 			if (rel === null || rel === "") return {
-				ok: true,
-				revision: null
+				ok: false,
+				error: "路径不合法"
 			};
 			const status = await statusOf(sc.cwd);
 			if (!status.managed || !status.wcRoot) return {
@@ -13665,27 +14022,55 @@ function createSvnRpc(deps) {
 				ok: false,
 				error: "svn 命令不可用（可在设置页配置 svn 路径）"
 			};
-			const outcome = await runSvn(status.wcRoot, [
-				"info",
-				"--xml",
-				"--",
-				rel
-			], READ_GRACE_MS);
-			if (outcome.code !== 0) return {
-				ok: true,
-				revision: null
-			};
-			return {
-				ok: true,
-				revision: parseSvnInfoRevision(outcome.stdout)
-			};
+			try {
+				const ext = patchExtOf({
+					whitespace: args.whitespace,
+					ignoreEol: args.ignoreEol === true,
+					unified: args.unified
+				});
+				const argv = [
+					"diff",
+					...ext ? ["-x", ext] : [],
+					"--",
+					rel
+				];
+				const outcome = await runSvn(status.wcRoot, argv, READ_GRACE_MS, PATCH_OUTPUT_CAP);
+				if (outcome.code !== 0) return {
+					ok: false,
+					error: "生成补丁失败：" + tailOfText([outcome.stderr, outcome.stdout].filter(Boolean).join("\n"))
+				};
+				const text = outcome.stdout;
+				const head = text.slice(0, 200);
+				return {
+					ok: true,
+					text,
+					truncated: !head.startsWith("Index:") && !head.startsWith("Property changes on:"),
+					binary: text.includes("Cannot display:")
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "生成补丁失败：" + String(error)
+				};
+			}
 		},
-		"svn.cleanup": async (args) => {
+		"svn.diffSum": async (args) => {
 			const sc = await requireSvnSession(ctx, args.sessionId);
 			if ("err" in sc) return {
 				ok: false,
 				error: sc.err
 			};
+			const rel = safeRel(args.path);
+			if (rel === null) return {
+				ok: false,
+				error: "路径不合法"
+			};
+			const revA = Number(args.revA);
+			const revB = Number(args.revB);
+			if (!Number.isFinite(revA) || revA < 1 || !Number.isFinite(revB) || revB < 1) return {
+				ok: false,
+				error: "版本号不合法"
+			};
 			const status = await statusOf(sc.cwd);
 			if (!status.managed || !status.wcRoot) return {
 				ok: false,
@@ -13695,29 +14080,32 @@ function createSvnRpc(deps) {
 				ok: false,
 				error: "svn 命令不可用（可在设置页配置 svn 路径）"
 			};
-			const argv = ["cleanup"];
-			if (args.removeUnversioned === true) argv.push("--remove-unversioned");
-			if (args.removeIgnored === true) argv.push("--remove-ignored");
 			try {
-				const outcome = await runSvn(status.wcRoot, argv, MUTATE_GRACE_MS);
-				const result = batchResultOf(outcome.stdout, outcome.stderr, outcome.code, "清理");
+				const argv = [
+					"diff",
+					"--summarize",
+					"--xml",
+					"-r",
+					String(Math.floor(revA)) + ":" + String(Math.floor(revB))
+				];
+				if (rel) argv.push("--", rel);
+				const outcome = await runSvn(status.wcRoot, argv, SUM_GRACE_MS, SUM_OUTPUT_CAP);
 				if (outcome.code !== 0) return {
 					ok: false,
-					error: "清理失败：" + tailOfText(result.output)
+					error: "目录对比失败：" + tailOfText([outcome.stderr, outcome.stdout].filter(Boolean).join("\n"))
 				};
-				changesCache.delete(status.wcRoot);
 				return {
 					ok: true,
-					...result
+					...parseSummarizeXml(outcome.stdout, status.wcRoot)
 				};
 			} catch (error) {
 				return {
 					ok: false,
-					error: "清理失败：" + String(error)
+					error: "目录对比失败：" + String(error)
 				};
 			}
 		},
-		"svn.update": async (args) => {
+		"svn.remoteStatus": async (args) => {
 			const sc = await requireSvnSession(ctx, args.sessionId);
 			if ("err" in sc) return {
 				ok: false,
@@ -13729,7 +14117,7 @@ function createSvnRpc(deps) {
 				error: "路径不合法"
 			};
 			const status = await statusOf(sc.cwd);
-			if (!status.managed) return {
+			if (!status.managed || !status.wcRoot) return {
 				ok: false,
 				error: "当前工作区不受 SVN 管理"
 			};
@@ -13738,73 +14126,1912 @@ function createSvnRpc(deps) {
 				error: "svn 命令不可用（可在设置页配置 svn 路径）"
 			};
 			try {
-				const outcome = await runSvn(sc.cwd, ["update", rel || "."], UPDATE_GRACE_MS);
-				const result = updateResultOf(outcome.stdout, outcome.stderr, outcome.code);
+				const argv = [
+					"status",
+					"-u",
+					"--xml"
+				];
+				if (rel) argv.push("--", rel);
+				const outcome = await runSvn(status.wcRoot, argv, REMOTE_GRACE_MS, SUM_OUTPUT_CAP);
 				if (outcome.code !== 0) return {
 					ok: false,
-					error: "更新失败：" + tailOfText(result.output)
+					error: "远端检查失败：" + tailOfText([outcome.stderr, outcome.stdout].filter(Boolean).join("\n"))
 				};
 				return {
 					ok: true,
-					...result
+					...parseRemoteStatusXml(outcome.stdout, status.wcRoot)
 				};
 			} catch (error) {
 				return {
 					ok: false,
-					error: "更新失败：" + String(error)
+					error: "远端检查失败：" + String(error)
 				};
 			}
 		},
-		"svn.tortoise": async (args) => {
+		"svn.conflictArtifacts": async (args) => {
 			const sc = await requireSvnSession(ctx, args.sessionId);
 			if ("err" in sc) return {
 				ok: false,
 				error: sc.err
 			};
-			const action = args.action;
-			if (action !== "update" && action !== "commit" && action !== "log" && action !== "diff" && action !== "blame" && action !== "revert") return {
-				ok: false,
-				error: "未知动作: " + String(action)
-			};
 			const rel = safeRel(args.path);
-			if (rel === null) return {
+			if (rel === null || rel === "") return {
 				ok: false,
 				error: "路径不合法"
 			};
 			const status = await statusOf(sc.cwd);
-			if (!status.managed) return {
+			if (!status.managed || !status.wcRoot) return {
 				ok: false,
 				error: "当前工作区不受 SVN 管理"
 			};
-			if (!status.tortoise) return {
-				ok: false,
-				error: "TortoiseProc.exe 不可用（仅 Windows；可在设置页配置目录）"
-			};
-			const fs = ctx.get("fs");
-			if (!fs?.resolve || !fs?.stat || !fs?.processPath) return {
-				ok: false,
-				error: "缺少 fs"
-			};
 			try {
-				const target = await fs.resolve(rel || ".", { cwd: sc.cwd });
-				if (!await fs.stat(target)) return {
-					ok: false,
-					error: "路径不存在"
-				};
-				const abs = fs.processPath(target);
-				launchTortoise(status.tortoiseExe, action, abs);
 				return {
 					ok: true,
-					launched: abs
+					artifacts: await conflictArtifactsOf(status.wcRoot, rel)
 				};
 			} catch (error) {
 				return {
 					ok: false,
-					error: "启动 TortoiseSVN 失败：" + String(error)
+					error: "扫描冲突副本失败：" + String(error)
 				};
 			}
-		}
-	} };
+		},
+		"svn.diffLocalPair": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const left = safeRel(args.left);
+			const right = safeRel(args.right);
+			if (!left || !right) return {
+				ok: false,
+				error: "路径不合法（需工作副本内相对路径）"
+			};
+			const status = await statusOf(sc.cwd);
+			if (!status.managed || !status.wcRoot) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			const fs = ctx.get("fs");
+			if (!fs?.resolve || !fs?.stat || !fs?.readText) return {
+				ok: false,
+				error: "缺少 fs"
+			};
+			try {
+				const sides = [];
+				for (const rel of [left, right]) {
+					const resolved = await fs.resolve(rel, { cwd: sc.cwd });
+					const info = await fs.stat(resolved);
+					if (!info || info.type !== "file") return {
+						ok: false,
+						error: "文件不存在：" + rel
+					};
+					if ((info.size ?? 0) > READ_CAP) return {
+						ok: false,
+						error: "文件过大（>8MB）：" + rel
+					};
+					sides.push(await fs.readText(resolved));
+				}
+				return {
+					ok: true,
+					left: sides[0],
+					right: sides[1],
+					...guardSides(sides[0], sides[1])
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "读取冲突副本失败：" + String(error)
+				};
+			}
+		},
+		"svn.fileSizes": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const list = Array.isArray(args.paths) ? args.paths.slice(0, 200) : [];
+			if (!list.length) return {
+				ok: true,
+				sizes: []
+			};
+			const fs = ctx.get("fs");
+			if (!fs?.resolve || !fs?.stat) return {
+				ok: false,
+				error: "缺少 fs"
+			};
+			const sizes = [];
+			for (const raw of list) {
+				const rel = safeRel(raw);
+				if (rel === null || rel === "") {
+					sizes.push({
+						path: String(raw ?? ""),
+						size: null
+					});
+					continue;
+				}
+				try {
+					const resolved = await fs.resolve(rel, { cwd: sc.cwd });
+					const info = await fs.stat(resolved);
+					sizes.push({
+						path: rel,
+						size: info && info.type === "file" ? info.size ?? null : null
+					});
+				} catch {
+					sizes.push({
+						path: rel,
+						size: null
+					});
+				}
+			}
+			return {
+				ok: true,
+				sizes
+			};
+		},
+		"svn.wcRev": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const rel = safeRel(args.path);
+			if (rel === null || rel === "") return {
+				ok: true,
+				revision: null
+			};
+			const status = await statusOf(sc.cwd);
+			if (!status.managed || !status.wcRoot) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			if (!status.svnCli) return {
+				ok: false,
+				error: "svn 命令不可用（可在设置页配置 svn 路径）"
+			};
+			const outcome = await runSvn(status.wcRoot, [
+				"info",
+				"--xml",
+				"--",
+				rel
+			], READ_GRACE_MS);
+			if (outcome.code !== 0) return {
+				ok: true,
+				revision: null
+			};
+			return {
+				ok: true,
+				revision: parseSvnInfoRevision(outcome.stdout)
+			};
+		},
+		"svn.cleanup": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const status = await statusOf(sc.cwd);
+			if (!status.managed || !status.wcRoot) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			if (!status.svnCli) return {
+				ok: false,
+				error: "svn 命令不可用（可在设置页配置 svn 路径）"
+			};
+			const argv = ["cleanup"];
+			if (args.removeUnversioned === true) argv.push("--remove-unversioned");
+			if (args.removeIgnored === true) argv.push("--remove-ignored");
+			try {
+				const outcome = await runSvn(status.wcRoot, argv, MUTATE_GRACE_MS);
+				const result = batchResultOf(outcome.stdout, outcome.stderr, outcome.code, "清理");
+				if (outcome.code !== 0) return {
+					ok: false,
+					error: "清理失败：" + tailOfText(result.output)
+				};
+				changesCache.delete(status.wcRoot);
+				return {
+					ok: true,
+					...result
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "清理失败：" + String(error)
+				};
+			}
+		},
+		"svn.update": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const rel = safeRel(args.path);
+			if (rel === null) return {
+				ok: false,
+				error: "路径不合法"
+			};
+			const status = await statusOf(sc.cwd);
+			if (!status.managed) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			if (!status.svnCli) return {
+				ok: false,
+				error: "svn 命令不可用（可在设置页配置 svn 路径）"
+			};
+			try {
+				const outcome = await runSvn(sc.cwd, ["update", rel || "."], UPDATE_GRACE_MS);
+				const result = updateResultOf(outcome.stdout, outcome.stderr, outcome.code);
+				if (outcome.code !== 0) return {
+					ok: false,
+					error: "更新失败：" + tailOfText(result.output)
+				};
+				return {
+					ok: true,
+					...result
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "更新失败：" + String(error)
+				};
+			}
+		},
+		"svn.tortoise": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const action = args.action;
+			if (action !== "update" && action !== "commit" && action !== "log" && action !== "diff" && action !== "blame" && action !== "revert") return {
+				ok: false,
+				error: "未知动作: " + String(action)
+			};
+			const rel = safeRel(args.path);
+			if (rel === null) return {
+				ok: false,
+				error: "路径不合法"
+			};
+			const status = await statusOf(sc.cwd);
+			if (!status.managed) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			if (!status.tortoise) return {
+				ok: false,
+				error: "TortoiseProc.exe 不可用（仅 Windows；可在设置页配置目录）"
+			};
+			const fs = ctx.get("fs");
+			if (!fs?.resolve || !fs?.stat || !fs?.processPath) return {
+				ok: false,
+				error: "缺少 fs"
+			};
+			try {
+				const target = await fs.resolve(rel || ".", { cwd: sc.cwd });
+				if (!await fs.stat(target)) return {
+					ok: false,
+					error: "路径不存在"
+				};
+				const abs = fs.processPath(target);
+				launchTortoise(status.tortoiseExe, action, abs);
+				return {
+					ok: true,
+					launched: abs
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "启动 TortoiseSVN 失败：" + String(error)
+				};
+			}
+		}
+	} };
+}
+//#endregion
+//#region src/shared/dap.ts
+/** 全部合法动作（运行时校验用）。 */
+const DAP_ACTIONS = [
+	"continue",
+	"next",
+	"stepIn",
+	"stepOut",
+	"pause",
+	"disconnect"
+];
+/** 调试配置文件（工作区相对路径；插件专属，与 VS Code 的 .vscode/launch.json 互不干扰）。 */
+const DAP_LAUNCH_REL = ".dsh/launch.json";
+/** 旧共用配置路径（仅首读迁移源：复制到 DAP_LAUNCH_REL 后不再读取，永不回写）。 */
+const DAP_LEGACY_LAUNCH_REL = ".vscode/launch.json";
+/**
+* 配置 → DAP request 类型：显式 request 优先；emmylua_attach 旧配置缺 request 时按 attach 兼容。
+* @author ddj 2026年09月21号
+* @param config 调试配置（取 type/request 两字段）
+* @returns 'attach' | 'launch'
+*/
+function requestOfConfig(config) {
+	if (config.request === "attach" || config.request === "launch") return config.request;
+	return config.type === "emmylua_attach" ? "attach" : "launch";
+}
+/**
+* 是否应发送 configurationDone（DAP 标准握手收尾：断点下发完 → configurationDone → 目标开跑）。
+* 仅当适配器在 initialize 响应声明 supportsConfigurationDoneRequest 时发送；
+* emmylua 适配器未声明该能力（实测响应体仅 5 个 supports* 字段）→ 不发，Lua 行为不变。
+* @author ddj 2026年09月21号
+* @param caps initialize 响应 body（capabilities）
+*/
+function needsConfigurationDone(caps) {
+	return caps?.supportsConfigurationDoneRequest === true;
+}
+/**
+* stopped 事件 body → 当前线程 id：多线程适配器（coreclr 等）取真实 threadId，
+* 缺省/非法回退 1（单线程适配器 emmylua 语义不变）。
+* @author ddj 2026年09月21号
+* @param body stopped 事件 body
+*/
+function threadIdOfStopped(body) {
+	const id = body.threadId;
+	return typeof id === "number" && Number.isInteger(id) && id > 0 ? id : 1;
+}
+/**
+* setBreakpoints 响应 body → 断点回执（DAP 顺序与请求一致；缺行回退请求行）。
+* 适配器会把断点挪到最近可绑定行并给出 verified/message——必须消费而非造假回执。
+* @author ddj 2026年09月21号
+* @param body setBreakpoints 响应 body（breakpoints 数组）
+* @param items 本次请求的断点（回退基准）
+*/
+function bpAcksOfResponse(body, items) {
+	const list = body?.breakpoints;
+	if (!Array.isArray(list)) return items.map((it) => ({
+		line: it.line,
+		verified: true
+	}));
+	return list.map((item, i) => {
+		const b = item ?? {};
+		const ack = {
+			line: typeof b.line === "number" && b.line >= 1 ? b.line : items[i]?.line ?? 0,
+			verified: b.verified === true
+		};
+		if (typeof b.message === "string" && b.message) ack.message = b.message;
+		return ack;
+	});
+}
+//#endregion
+//#region src/dap/sourcePath.ts
+/**
+* dsh-vscode-mode host — DAP source 路径归一化与候选排序。
+* 适配器可能上报绝对路径、工作区相对路径、file:// URI 或 Lua chunkname；
+* 这里统一转换，避免调用栈只显示 rawFile 但无法跳转。
+* 作者 ddj 2026年09月29号
+*/
+/** 统一路径分隔符并去掉 chunkname 的 @ 前缀。 */
+function normalizeSourcePath(value) {
+	let text = String(value ?? "").trim();
+	if (!text) return "";
+	if (/^file:\/\//i.test(text)) text = fileUriPath(text);
+	return text.replace(/^@/, "").replace(/\\/g, "/");
+}
+/** 将 file:// URI 转成本地路径（兼容 Windows 盘符与 UNC）。 */
+function fileUriPath(value) {
+	try {
+		const url = new URL(value);
+		let path = decodeURIComponent(url.pathname);
+		if (url.hostname && url.hostname !== "localhost") path = "//" + url.hostname + path;
+		if (/^\/[A-Za-z]:/.test(path)) path = path.slice(1);
+		return path;
+	} catch {
+		return value.replace(/^file:\/\//i, "");
+	}
+}
+/** 取路径 basename（大小写保持原样）。 */
+function sourceBaseOf(value) {
+	return normalizeSourcePath(value).split("/").pop() ?? "";
+}
+/** 规范化路径键（大小写不敏感，供候选缓存使用）。 */
+function sourceKeyOf(value) {
+	return normalizeSourcePath(value).toLowerCase();
+}
+/**
+* 把 source 路径转换为工作区相对路径；工作区外路径保留规范化绝对路径，
+* 不再返回空串，调用方仍可交给现有 tabPathOf/absoluteOf 继续处理。
+*/
+function sourcePathOf(value, workspacePath) {
+	const source = normalizeSourcePath(value);
+	if (!source) return "";
+	const root = normalizeSourcePath(workspacePath).replace(/\/+$/, "");
+	if (root && source.toLowerCase().startsWith((root + "/").toLowerCase())) return source.slice(root.length + 1);
+	return source;
+}
+/**
+* 对 findFile 候选按 chunkname 相关度排序：完整路径后缀 > 路径片段 > basename/stem，
+* 同分时保持确定性字典序，避免同名 Lua 文件随机取第一项。
+*/
+function rankSourceCandidates(chunk, files, workspacePath) {
+	const needle = normalizeSourcePath(chunk).toLowerCase();
+	const needleParts = needle.split("/").filter(Boolean);
+	const needleBase = sourceBaseOf(needle).toLowerCase();
+	const needleStem = needleBase.replace(/\.[^.]+$/, "");
+	return [...files].sort((a, b) => scoreSource(b, needle, needleParts, needleBase, needleStem, workspacePath) - scoreSource(a, needle, needleParts, needleBase, needleStem, workspacePath) || a.localeCompare(b));
+}
+/** 计算单个候选相关度。 */
+function scoreSource(file, needle, parts, base, stem, workspacePath) {
+	const rel = sourcePathOf(file, workspacePath).toLowerCase();
+	const fileBase = sourceBaseOf(rel).toLowerCase();
+	const fileStem = fileBase.replace(/\.[^.]+$/, "");
+	let score = 0;
+	if (needle && (rel === needle || rel.endsWith("/" + needle) || needle.endsWith("/" + rel))) score += 1e5;
+	if (base && fileBase === base) score += 1e4;
+	if (stem && fileStem === stem) score += 5e3;
+	const relParts = rel.split("/").filter(Boolean);
+	let suffix = 0;
+	for (let i = 1; i <= Math.min(parts.length, relParts.length); i++) {
+		if (parts[parts.length - i] !== relParts[relParts.length - i]) break;
+		suffix += 1;
+	}
+	return score + suffix * 100;
+}
+//#endregion
+//#region src/dap/launchConfig.ts
+/**
+* 清洗 JSONC 为可 JSON.parse 文本：去 // 与 /* *\/ 注释、去尾逗号（字符串字面量感知）。
+* @author ddj 2026年09月29号
+* @param text 原始 launch.json 文本
+* @returns 清洗后文本
+*/
+function stripJsonc(text) {
+	let out = "";
+	let i = 0;
+	const n = text.length;
+	let state = "code";
+	while (i < n) {
+		const ch = text[i];
+		const next = i + 1 < n ? text[i + 1] : "";
+		if (state === "string") {
+			out += ch;
+			if (ch === "\\") {
+				out += next;
+				i += 2;
+				continue;
+			}
+			if (ch === "\"") state = "code";
+			i += 1;
+			continue;
+		}
+		if (ch === "\"") {
+			state = "string";
+			out += ch;
+			i += 1;
+			continue;
+		}
+		if (ch === "/" && next === "/") {
+			while (i < n && text[i] !== "\n") i += 1;
+			continue;
+		}
+		if (ch === "/" && next === "*") {
+			i += 2;
+			while (i + 1 < n && !(text[i] === "*" && text[i + 1] === "/")) i += 1;
+			i += 2;
+			continue;
+		}
+		out += ch;
+		i += 1;
+	}
+	return out.replace(/,(\s*[}\]])/g, "$1");
+}
+/**
+* 解析 launch.json 文本为全量调试配置列表（非法/缺 name/type 的条目跳过）。
+* @author ddj 2026年09月29号 / 2026年09月21号
+* @param text launch.json 文本（JSONC）
+* @param workspacePath 工作区根（${workspaceFolder}/${cwd} 替换基准；空 = 不替换）
+* @returns 全量配置（raw 原样透传）
+*/
+function parseLaunchConfigs(text, workspacePath = "") {
+	let data;
+	try {
+		data = JSON.parse(stripJsonc(text));
+	} catch {
+		return [];
+	}
+	const list = data?.configurations;
+	if (!Array.isArray(list)) return [];
+	const out = [];
+	for (const item of list) {
+		if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+		const cfg = item;
+		const type = asString(cfg.type);
+		const name = asString(cfg.name);
+		if (!type || !name) continue;
+		out.push({
+			name,
+			type,
+			request: asString(cfg.request),
+			processName: asString(cfg.processName),
+			pid: asPositive(cfg.pid),
+			processId: asPositive(cfg.processId),
+			host: asString(cfg.host),
+			port: asPositive(cfg.port),
+			sourcePaths: stringListOf(cfg.sourcePaths),
+			ext: stringListOf(cfg.ext),
+			captureLog: typeof cfg.captureLog === "boolean" ? cfg.captureLog : void 0,
+			raw: expandRaw(cfg, workspacePath)
+		});
+	}
+	return out;
+}
+/**
+* 配置是否含 ${command:...} 占位（VS Code 命令，本插件无法解析，需用户改为具体值）。
+* @author ddj 2026年09月21号
+* @param config 调试配置
+*/
+function hasCmdPlaceholder(config) {
+	return JSON.stringify(config.raw ?? {}).includes("${command:");
+}
+/** ${workspaceFolder}/${cwd} → 工作区根（大小写不敏感；其余占位保持原样交适配器）。 */
+function expandLaunchVars(text, workspacePath) {
+	if (!workspacePath) return text;
+	return text.replace(/\$\{workspaceFolder\}/gi, workspacePath).replace(/\$\{cwd\}/gi, workspacePath);
+}
+/** raw 逐字段递归展开（字符串内占位替换；数组/嵌套对象同口径）。 */
+function expandRaw(raw, workspacePath) {
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) out[key] = expandValue(value, workspacePath);
+	return out;
+}
+/** 单值展开。 */
+function expandValue(value, workspacePath) {
+	if (typeof value === "string") return expandLaunchVars(value, workspacePath);
+	if (Array.isArray(value)) return value.map((v) => expandValue(v, workspacePath));
+	if (value && typeof value === "object") return expandRaw(value, workspacePath);
+	return value;
+}
+/** unknown → 字符串（非字符串返回 undefined）。 */
+function asString(value) {
+	return typeof value === "string" && value ? value : void 0;
+}
+/** unknown → 正数（number 且 >0；其余 undefined）。 */
+function asPositive(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+/** 字符串数组字段清洗（非字符串元素剔除；空数组返回 undefined）。 */
+function stringListOf(raw) {
+	if (!Array.isArray(raw)) return void 0;
+	const items = raw.filter((v) => typeof v === "string" && v.length > 0);
+	return items.length ? items : void 0;
+}
+//#endregion
+//#region src/dap/configSnippets.ts
+/**
+* dsh-vscode-mode host — launch.json「添加配置」片段提取。
+* 扫描 VSCode 扩展清单 contributes.debuggers[]：
+* - configurationSnippets[]（label/description/body）优先；缺失时 initialConfigurations[] 兜底
+*   （条目本身就是配置体，label 取 body.name → debugger.label → type）；
+* - %key% 占位符按 package.nls.json → package.nls.zh-cn.json 合并表解析（zh 覆盖 base），
+*   解析失败剥 %…% 外壳（避免裸占位符上屏）；
+* - body 缺 type/name 时补齐（parseLaunchConfigs 要求两者，缺了插进去也不可见）。
+* 与 discovery 各自独立缓存（片段随扩展安装变化；force 重扫，测试隔离）。
+* 作者 ddj 2026年09月22号
+*/
+/** 发现缓存（null = 未加载；按 home 隔离，测试用 force/clear 复位）。 */
+let cache$1 = null;
+let cacheHome$1 = "";
+/**
+* 全部可添加调试配置片段（按 label 字典序稳定输出，type+label 去重）。
+* @author ddj 2026年09月22号
+* @param force 强制重扫（扩展安装后 / 测试隔离用）
+* @param home DSH home（缺省真实；测试可注入）
+* @returns 片段列表
+*/
+function dapConfigSnippets(force = false, home = dshHome()) {
+	if (!force && cache$1 !== null && home === cacheHome$1) return cache$1;
+	cache$1 = scanSnippets(home);
+	cacheHome$1 = home;
+	return cache$1;
+}
+/**
+* 按适配器可用性标注片段（与调试工具条同源裁决 debuggerDecls）：
+* type 命中 decl → 透传 available/reason；未命中（清单无该 type 的可用适配器声明）
+* → available=false +「未发现该类型适配器」。下拉据此过滤「选得进、跑不了」的条目。
+* @author ddj 2026年09月22号
+* @param snippets 片段列表（dapConfigSnippets 产物）
+* @param decls 适配器声明表（debuggerDecls()）
+* @returns 带可用性标注的片段列表（新数组，不改入参）
+*/
+function annotateSnippets(snippets, decls) {
+	const byType = new Map(decls.map((decl) => [decl.type, decl]));
+	return snippets.map((snip) => {
+		const decl = byType.get(snip.type);
+		if (!decl) return {
+			...snip,
+			available: false,
+			reason: "未发现该类型适配器"
+		};
+		const annotated = {
+			...snip,
+			available: decl.available
+		};
+		if (!decl.available && decl.reason) annotated.reason = decl.reason;
+		return annotated;
+	});
+}
+/** 扫描全部扩展根收集片段（先到先得去重，输出按 label 排序）。 */
+function scanSnippets(home) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const root of vscodeExtensionsDirs(home)) for (const extDir of subDirsOf$1(root)) collectExt(extDir, out, seen);
+	return out.sort((a, b) => a.label.localeCompare(b.label));
+}
+/** 单扩展处理：有产出原料才读 nls（多数扩展无调试片段，不白读两个小文件）。 */
+function collectExt(extDir, out, seen) {
+	const plans = debuggersOf$1(extDir).map((entry) => ({
+		entry,
+		type: strOf(entry.type),
+		items: rawItemsOf(entry)
+	})).filter((plan) => Boolean(plan.type) && plan.items.length > 0);
+	if (!plans.length) return;
+	const nls = readNlsTable(extDir);
+	for (const plan of plans) for (const item of plan.items) {
+		const snippet = projectSnippet(plan.entry, plan.type, item, nls);
+		const key = plan.type + "\0" + snippet.label;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(snippet);
+	}
+}
+/** 清单条目 → 片段投影（nls 解析 + type/name 补齐）。 */
+function projectSnippet(entry, type, item, nls) {
+	const body = resolveNlsDeep(item.body, nls);
+	if (!strOf(body.type)) body.type = type;
+	const label = resolveNlsText(item.label ?? "", nls) || strOf(body.name) || resolveNlsText(strOf(entry.label), nls) || type;
+	if (!strOf(body.name)) body.name = label;
+	const snippet = {
+		label,
+		type: strOf(body.type) || type,
+		bodyText: JSON.stringify(body, null, 2)
+	};
+	const description = resolveNlsText(item.description ?? "", nls);
+	if (description) snippet.description = description;
+	return snippet;
+}
+/** 读扩展根下的扩展子目录（根不存在返回空；与 discovery 同口径）。 */
+function subDirsOf$1(root) {
+	let entries;
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return entries.filter((e) => e.isDirectory()).map((e) => join(root, e.name));
+}
+/** 读某扩展的 contributes.debuggers（无清单/无声明/解析失败返回空）。 */
+function debuggersOf$1(extDir) {
+	try {
+		const text = readFileSync(join(extDir, "package.json"), "utf8").replace(/^/, "");
+		const list = JSON.parse(text).contributes?.debuggers;
+		return Array.isArray(list) ? list : [];
+	} catch {
+		return [];
+	}
+}
+/** 条目 → 原料列表：configurationSnippets 优先，initialConfigurations 兜底（条目即配置体）。 */
+function rawItemsOf(entry) {
+	const out = [];
+	const snippets = asArray(entry.configurationSnippets);
+	for (const raw of snippets) {
+		const snippet = asRecord(raw);
+		if (!snippet) continue;
+		const body = asRecord(snippet.body);
+		if (!body) continue;
+		out.push({
+			label: strOf(snippet.label),
+			description: strOf(snippet.description),
+			body
+		});
+	}
+	if (out.length) return out;
+	for (const raw of asArray(entry.initialConfigurations)) {
+		const body = asRecord(raw);
+		if (body) out.push({ body });
+	}
+	return out;
+}
+/**
+* 读扩展 nls 表（base 先入，zh-cn 后入覆盖；文件缺失/解析失败按空跳过）。
+* @author ddj 2026年09月22号
+* @param extDir 扩展根目录
+* @returns %key% → 文本 表
+*/
+function readNlsTable(extDir) {
+	const table = {};
+	for (const file of ["package.nls.json", "package.nls.zh-cn.json"]) try {
+		const path = join(extDir, file);
+		if (!existsSync(path)) continue;
+		const data = JSON.parse(readFileSync(path, "utf8").replace(/^/, ""));
+		for (const [key, value] of Object.entries(data)) if (typeof value === "string") table[key] = value;
+	} catch {}
+	return table;
+}
+/**
+* 解析单串 %key% 占位（最多 3 轮：nls 值可再含占位；未命中剥 %…% 外壳）。
+* @author ddj 2026年09月22号
+* @param value 原文
+* @param table nls 表
+* @returns 解析后文本（无占位原样返回）
+*/
+function resolveNlsText(value, table) {
+	if (!value.includes("%")) return value;
+	let out = value;
+	for (let round = 0; round < 3; round += 1) {
+		const next = out.replace(/%([A-Za-z0-9_.-]+)%/g, (_match, key) => table[key] ?? key);
+		if (next === out) break;
+		out = next;
+	}
+	return out;
+}
+/** 深度解析任意值内的 %key%（字符串逐个过 resolveNlsText，对象/数组递归）。 */
+function resolveNlsDeep(value, table) {
+	if (typeof value === "string") return resolveNlsText(value, table);
+	if (Array.isArray(value)) return value.map((item) => resolveNlsDeep(item, table));
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [key, item] of Object.entries(value)) out[key] = resolveNlsDeep(item, table);
+		return out;
+	}
+	return value;
+}
+/** unknown → 非空字符串（其余空串）。 */
+function strOf(value) {
+	return typeof value === "string" && value ? value : "";
+}
+/** unknown → 普通对象（数组/原始值返回 null）。 */
+function asRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+/** unknown → 数组（单对象包一层，兼容 initialConfigurations 单对象写法）。 */
+function asArray(value) {
+	if (Array.isArray(value)) return value;
+	return value && typeof value === "object" ? [value] : [];
+}
+//#endregion
+//#region src/dap/processList.ts
+/**
+* dsh-vscode-mode host — 调试目标进程枚举（Windows）。
+* 用 PowerShell Get-Process 取 窗口标题/进程名/路径（完整 Unicode，无 GBK 乱码），
+* 等价替代 VS Code 扩展的 emmy_tool.exe list_processes（扩展侧 QuickPick 的数据源），
+* 匹配语义一致：processName 对 窗口标题 或 进程文件名 做**包含**匹配。
+* emmylua_attach 仅支持 Windows（适配器原生限制），非 Windows 返回空表。
+* 作者 ddj 2026年09月29号
+*/
+/** PowerShell 单行命令：仅带主窗口的进程，JSON 输出（UTF-8）。 */
+const PROCESS_LIST_CMD = "$OutputEncoding=[Text.Encoding]::UTF8;[Console]::OutputEncoding=[Text.Encoding]::UTF8;Get-Process | Where-Object { $_.MainWindowHandle -ne 0 } | Select-Object Id,ProcessName,MainWindowTitle,Path | ConvertTo-Json -Compress -Depth 2";
+/**
+* 解析 ConvertTo-Json 输出为进程列表（纯函数，可单测）。
+* 单条时 PowerShell 输出对象而非数组，两种形状都接受。
+* @author ddj 2026年09月29号
+* @param text PowerShell stdout
+* @returns 进程列表（无效行剔除）
+*/
+function parseProcessListJson(text) {
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		return [];
+	}
+	const rows = Array.isArray(data) ? data : [data];
+	const out = [];
+	for (const row of rows) {
+		if (!row || typeof row !== "object") continue;
+		const item = row;
+		const pid = typeof item.Id === "number" ? item.Id : NaN;
+		if (!Number.isFinite(pid) || pid <= 0) continue;
+		const path = typeof item.Path === "string" ? item.Path : "";
+		const name = path ? path.split(/[\\/]/).pop() ?? item.ProcessName ?? "" : (item.ProcessName ?? "") + ".exe";
+		out.push({
+			pid,
+			title: typeof item.MainWindowTitle === "string" ? item.MainWindowTitle : "",
+			path,
+			name
+		});
+	}
+	return out;
+}
+/**
+* 按 processName 过滤进程（与 VS Code 扩展口径一致：标题或文件名包含匹配；空串全量）。
+* @author ddj 2026年09月29号
+* @param items 全量进程
+* @param processName 过滤词
+*/
+function filterProcesses(items, processName) {
+	const needle = (processName ?? "").trim();
+	if (!needle) return items;
+	return items.filter((it) => it.title.includes(needle) || it.name.includes(needle));
+}
+/**
+* 枚举带主窗口的进程（Windows；spawn 失败/非 Windows 返回空表不抛错）。
+* @author ddj 2026年09月29号
+*/
+function listProcesses() {
+	if (process.platform !== "win32") return Promise.resolve([]);
+	return new Promise((resolve) => {
+		execFile("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			PROCESS_LIST_CMD
+		], {
+			encoding: "utf8",
+			windowsHide: true,
+			timeout: 15e3,
+			maxBuffer: 8 << 20
+		}, (error, stdout) => {
+			if (error && !stdout) {
+				resolve([]);
+				return;
+			}
+			resolve(parseProcessListJson(String(stdout ?? "")));
+		});
+	});
+}
+//#endregion
+//#region src/dap/discovery.ts
+/**
+* dsh-vscode-mode host — 调试适配器发现（清单驱动，VSCode contributes.debuggers 同源语义）。
+* 扫描全部扩展根（复用 lsp 侧 vscodeExtensionsDirs：~/.vscode/extensions、
+* ~/.vscode-server/extensions、插件扩展目录），读各扩展 package.json 的
+* contributes.debuggers[] 声明，解析为 DapAdapterDecl：
+* - program 按平台取 windows/linux/osx 覆盖，相对扩展根解析；
+* - runtime='node' → 由 node 跑 js 入口；无 runtime → program 即可执行（args 为清单声明）；
+* - 同 type 多扩展并存 → 按「清单版本降序(numeric) → 路径升序」取唯一（与 LSP 候选口径一致）；
+* - 入口不存在 / runtime 不支持 → available=false + reason（如 DotRush 按需下载的 clrdbg，
+*   诚实标注不假成功，调用方据此在下拉置灰并提示原因）。
+* 作者 ddj 2026年09月21号
+*/
+/** 发现缓存（扩展清单会话内基本不变；测试用 force 重扫）。 */
+let cacheReady = false;
+let cacheHome = "";
+let cache = [];
+/**
+* 发现全部调试适配器声明（按 type 去重、type 字典序稳定输出）。
+* @author ddj 2026年09月21号
+* @param force 强制重扫（扩展安装后 / 测试隔离用）
+* @param home DSH home（缺省真实；测试可注入）
+*/
+function debuggerDecls(force = false, home = dshHome()) {
+	if (cacheReady && !force && home === cacheHome) return cache;
+	cache = scanDecls(home);
+	cacheHome = home;
+	cacheReady = true;
+	return cache;
+}
+/** 扫描全部扩展根并收集声明（同 type 去重后返回）。 */
+function scanDecls(home) {
+	const hits = [];
+	for (const root of vscodeExtensionsDirs(home)) for (const extDir of subDirsOf(root)) for (const entry of debuggersOf(extDir)) {
+		const decl = declOf(extDir, entry);
+		if (decl) hits.push({
+			decl,
+			version: manifestVersionOf(extDir) ?? ""
+		});
+	}
+	return pickPerType(hits);
+}
+/** 同 type 去重：清单版本降序（numeric）→ 路径升序；输出按 type 字典序。 */
+function pickPerType(hits) {
+	const byType = /* @__PURE__ */ new Map();
+	for (const hit of hits) {
+		if (!betterOf(hit, byType.get(hit.decl.type))) continue;
+		byType.set(hit.decl.type, hit);
+	}
+	return [...byType.values()].map((h) => h.decl).sort((a, b) => a.type.localeCompare(b.type));
+}
+/** 候选比较：版本降序优先，平版本路径升序（无前任直接胜出）。 */
+function betterOf(hit, prev) {
+	if (!prev) return true;
+	const byVersion = compareVersion(hit.version, prev.version);
+	if (byVersion !== 0) return byVersion > 0;
+	return hit.decl.extensionPath.localeCompare(prev.decl.extensionPath) < 0;
+}
+/** 清单版本比较（numeric 感知，与 LSP 候选排序同口径）：>0 表示 a 更新。 */
+function compareVersion(a, b) {
+	return String(a || "").localeCompare(String(b || ""), void 0, { numeric: true });
+}
+/** 枚举扩展根下的扩展子目录（根不存在返回空）。 */
+function subDirsOf(root) {
+	let entries;
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return entries.filter((e) => e.isDirectory()).map((e) => join(root, e.name));
+}
+/** 读某扩展的 contributes.debuggers 声明（无清单/无声明/解析失败返回空）。 */
+function debuggersOf(extDir) {
+	try {
+		const text = readFileSync(join(extDir, "package.json"), "utf8").replace(/^\uFEFF/, "");
+		const list = JSON.parse(text).contributes?.debuggers;
+		return Array.isArray(list) ? list : [];
+	} catch {
+		return [];
+	}
+}
+/** 清单条目 → 声明（缺 type/program 视为无效条目跳过）。 */
+function declOf(extDir, entry) {
+	const type = typeof entry.type === "string" ? entry.type : "";
+	if (!type || typeof entry.program !== "string" || !entry.program) return null;
+	const languages = stringsOf(entry.languages);
+	const resolved = resolveProgram(extDir, entry);
+	const runtime = typeof entry.runtime === "string" && entry.runtime ? entry.runtime : void 0;
+	const runtimeBad = runtime !== void 0 && runtime !== "node";
+	const available = resolved.available && !runtimeBad;
+	const reason = !resolved.available ? resolved.reason : runtimeBad ? "暂不支持运行时 \"" + runtime + "\"（仅支持 node 与原生可执行）" : void 0;
+	return {
+		type,
+		label: typeof entry.label === "string" && entry.label ? entry.label : type,
+		extensionId: extensionIdOf(extDir),
+		extensionPath: extDir,
+		program: resolved.program,
+		args: stringsOf(entry.args),
+		runtime,
+		languages,
+		exts: extsOf(entry, languages),
+		available,
+		reason
+	};
+}
+/** 平台 program 解析：windows/linux/osx(darwin) 覆盖优先，相对扩展根（剥 ./）。 */
+function resolveProgram(extDir, entry) {
+	const plat = process.platform;
+	const override = plat === "win32" ? entry.windows?.program : plat === "darwin" ? entry.osx?.program ?? entry.darwin?.program : entry.linux?.program;
+	const rel = typeof override === "string" && override ? override : entry.program;
+	if (typeof rel !== "string" || !rel) return {
+		program: "",
+		available: false,
+		reason: "清单未声明本平台 program"
+	};
+	const program = join(extDir, ...rel.replace(/^\.\//, "").split(/[\\/]/));
+	if (!existsSync(program)) return {
+		program,
+		available: false,
+		reason: "适配器入口不存在（扩展可能需按需下载）：" + rel
+	};
+	return {
+		program,
+		available: true
+	};
+}
+/** 来源扩展 id（目录名 publisher.name-version 取 version 前段；解析失败回退目录名）。 */
+function extensionIdOf(extDir) {
+	const base = extDir.split(/[\\/]/).pop() ?? "";
+	const dot = base.lastIndexOf("-");
+	return dot > 0 ? base.slice(0, dot) : base;
+}
+/** 可下断点扩展名：优先清单 configurationAttributes 的 ext 缺省（emmylua 的 .lua 家族），
+* 否则按声明 languages 映射（LSP 侧同源）；两者皆空 = 不限（不过滤断点）。 */
+function extsOf(entry, languages) {
+	const attrs = entry.configurationAttributes;
+	const fromManifest = stringsOf(attrs?.attach?.properties?.ext?.default ?? attrs?.launch?.properties?.ext?.default);
+	if (fromManifest.length) return fromManifest;
+	const out = [];
+	for (const lang of languages) for (const ext of LSP_LANG_EXT[lang] ?? []) {
+		const dotted = "." + ext.replace(/^\./, "");
+		if (!out.includes(dotted)) out.push(dotted);
+	}
+	return out;
+}
+/** unknown → 字符串数组（非字符串元素剔除）。 */
+function stringsOf(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((v) => typeof v === "string" && v.length > 0);
+}
+//#endregion
+//#region src/dap/provider.ts
+/**
+* dsh-vscode-mode host — 调试适配器规格解析：按调试类型从扩展清单声明（discovery）
+* 解析 spawn 规格，通用不限定语言：
+* - runtime='node' → node 跑 js 入口（emmylua 形态，等价旧 process.execPath 硬编码）；
+* - 无 runtime → program 即原生可执行（clrdbg/monodbg 形态，args 为清单声明如 --interpreter=vscode）；
+* - 其它 runtime 明确不支持（decl.available=false 带原因，不做假启动）。
+* 旧版仅探测 tangzx.emmylua 两型（attach/new），由清单驱动后自然覆盖并扩展到任意适配器。
+* 作者 ddj 2026年09月29号 / 2026年09月21号
+*/
+/**
+* 解析某调试类型的适配器启动规格。
+* @author ddj 2026年09月29号 / 2026年09月21号
+* @param type 调试类型（launch.json type = 清单 contributes.debuggers.type）
+* @param force 强制重扫扩展清单（测试隔离用）
+* @param home DSH home（缺省真实；测试可注入）
+* @returns 启动规格；类型未发现 / 不可用 / runtime 不支持返回 null（原因见 discovery 声明）
+*/
+function resolveAdapterSpec(type, force = false, home) {
+	const decl = debuggerDecls(force, home).find((d) => d.type === type);
+	if (!decl || !decl.available) return null;
+	const base = {
+		type,
+		extensionPath: decl.extensionPath,
+		extensionId: decl.extensionId,
+		exts: decl.exts,
+		detail: decl.extensionPath
+	};
+	if (decl.runtime === "node") return {
+		...base,
+		command: process.execPath,
+		args: [decl.program, ...decl.args]
+	};
+	if (!decl.runtime) return {
+		...base,
+		command: decl.program,
+		args: [...decl.args]
+	};
+	return null;
+}
+//#endregion
+//#region src/dap/protocol.ts
+/** 客户端 → 适配器请求帧构造。 */
+function dapRequest(seq, command, args) {
+	return args === void 0 ? {
+		seq,
+		type: "request",
+		command
+	} : {
+		seq,
+		type: "request",
+		command,
+		arguments: args
+	};
+}
+/** 响应守卫。 */
+function isDapResponse(msg) {
+	return msg.type === "response" && typeof msg.request_seq === "number";
+}
+/** 事件守卫。 */
+function isDapEvent(msg) {
+	return msg.type === "event" && typeof msg.event === "string";
+}
+/** 事件体安全取值。 */
+function eventBody(event) {
+	return event.body && typeof event.body === "object" ? event.body : {};
+}
+/** 响应体安全取值。 */
+function responseBody(response) {
+	return response.body && typeof response.body === "object" ? response.body : {};
+}
+/**
+* initialize 请求参数（适配器协商口径：path 格式、行列 1 基）。
+* @author ddj 2026年09月29号
+* @param adapterId 适配器 id
+*/
+function initializeArgs(adapterId) {
+	return {
+		adapterID: adapterId,
+		locale: "zh-cn",
+		linesStartAt1: true,
+		columnsStartAt1: true,
+		pathFormat: "path",
+		supportsVariableType: true,
+		supportsVariablePaging: false,
+		supportsRunInTerminalRequest: false
+	};
+}
+//#endregion
+//#region src/dap/manager.ts
+/**
+* dsh-vscode-mode host — 调试会话管理器（DAP 桥核心，适配器通用）。
+* 单例调试会话：spawn 扩展清单声明的 DAP 适配器（node js 或原生 exe）↔ 本管理器翻译成
+* edrv.dap.* 视图。要点（emmylua 源自适配器源码逆向，探针验证；通用语义对齐 DAP 3.x）：
+* - 帧协议与 LSP 相同（Content-Length）→ 复用 lsp/jsonrpc.ts；
+* - initialize → attach/launch 响应后适配器异步连目标，连上才发 initialized 事件，
+*   此时需把已存断点全量重发；随后按能力位发 configurationDone（emmylua 未声明该能力
+*   不发，行为不变；clrdbg 等声明了必须发，否则目标挂起等待）；
+* - 停帧后 stackTrace/scopes/variables/evaluate 才有效（适配器未连接时 evaluate 永不回包，
+*   必须守卫 + 请求级超时）；
+* - stackTrace 期间 emmylua 适配器可能发 findFileReq **反向请求**等 findFileRsp
+*   （chunkname→文件由 IDE 侧解析），本管理器经注入的文件索引回调应答；
+*   其它适配器直接上报可打开的源码路径，不走该扩展事件；
+* - 线程：emmylua 固定 threadId=1；通用适配器取 stopped 事件的真实 threadId，
+*   栈/单步/暂停均携带；
+* - emmylua 的 scopes frameId 是 stacks 数组下标（私有语义），标准适配器用原生 frame id；
+* - 适配器对无效 pid 会未捕获异常崩溃 → attach 前必须先经进程枚举校验 pid。
+* 作者 ddj 2026年09月29号 / 2026年09月21号
+*/
+const EVENT_CAP = 500;
+const REQUEST_TIMEOUT_MS = 8e3;
+/** emmylua 兼容 shim 的来源扩展 id（extensionPath/pid 等缺省注入仅对其生效）。 */
+const EMMYLUA_EXT_ID = "tangzx.emmylua";
+/** 判断 source 是否已经是可定位的源码路径（exts 由调用方按当前适配器给出）。 */
+function hasSourceExtension(value, exts) {
+	const path = normalizeSourcePath(value).toLowerCase();
+	if (!path) return false;
+	return exts.some((ext) => path.endsWith(String(ext).toLowerCase()));
+}
+/**
+* 是否为「裸 chunkname」：无目录分隔符且非盘符/UNC 前缀。
+*
+* 这类值（如 xLua 上报的 `GuideSystemMgr`）被 {@link sourcePathOf} 处理后仍是原串，
+* 客户端会按工作区根拼接（`<cwd>/GuideSystemMgr`）——该路径必然不存在，
+* 于是断点命中后页签打不开、报「文件加载失败」。故反查失败时须判定为未解析，
+* 而不是把它当成文件路径下发。
+* @author ddj 2026年09月21号
+* @param value 适配器上报的 source 值
+* @returns 是否裸 chunkname
+*/
+function isBareChunk(value) {
+	const text = normalizeSourcePath(value);
+	if (!text) return false;
+	if (text.includes("/")) return false;
+	return !/^[a-z]:/i.test(text);
+}
+/**
+* 单例调试会话。生命周期：start → starting →（initialized）running →（stopped）paused
+* →（terminated/disconnect）terminated → dispose 回 idle。
+* @author ddj 2026年09月29号
+*/
+var DapSession = class {
+	deps;
+	child = null;
+	phase = "idle";
+	config = null;
+	workspacePath = "";
+	pid;
+	error;
+	/** spawn 的扩展根目录（emmylua 兼容 shim 注入 extensionPath）。 */
+	extPath = "";
+	/** 来源扩展 id（emmylua 兼容 shim 与 frameId 语义判定）。 */
+	extId = "";
+	/** 当前适配器可下断点扩展名（断点语言过滤；空 = 不限）。 */
+	exts = [];
+	/** initialize 响应 capabilities（configurationDone 门控）。 */
+	caps = null;
+	/** 当前停帧线程（多线程适配器取 stopped 事件真实 threadId；emmylua 恒 1）。 */
+	threadId = 1;
+	/** 断点（绝对路径），initialized 与每次 setBreakpoints 时全量下发。 */
+	breakpoints = [];
+	/** findFileReq chunkname → 已排序候选首路径（frame source.path 缺失时回退）。 */
+	sourceFiles = /* @__PURE__ */ new Map();
+	/** 停帧调用栈缓存（paused 期间供 stackTrace/topFrame）。 */
+	frames = [];
+	stateTop = null;
+	events = [];
+	eventSeq = 0;
+	msgSeq = 1;
+	/** 适配器 stderr 尾部缓冲（保留末尾 STDERR_TAIL_CAP 字符，退出 fail 消息附带用）。 */
+	stderrTail = "";
+	pending = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** 当前状态视图。 */
+	stateOf() {
+		return {
+			phase: this.phase,
+			configName: this.config?.name,
+			configType: this.config?.type,
+			pid: this.pid,
+			error: this.error,
+			topFrame: this.phase === "paused" ? this.stateTop : null
+		};
+	}
+	/**
+	* 启动调试会话（异步推进：spawn → initialize → attach/launch）。
+	* @author ddj 2026年09月29号
+	* @param spec 适配器启动规格
+	* @param config 调试配置
+	* @param workspacePath 工作区绝对路径（断点/findFile 基准）
+	* @param pid 附加目标 pid（attach 型必填且必须已校验存在）
+	*/
+	start(spec, config, workspacePath, pid) {
+		if (this.child) this.killChild();
+		this.config = config;
+		this.workspacePath = workspacePath;
+		this.extPath = spec.extensionPath;
+		this.extId = spec.extensionId;
+		this.exts = spec.exts;
+		this.caps = null;
+		this.threadId = 1;
+		this.pid = pid;
+		this.error = void 0;
+		this.stderrTail = "";
+		this.frames = [];
+		this.sourceFiles.clear();
+		this.stateTop = null;
+		this.setPhase("starting");
+		try {
+			this.spawnAdapter(spec);
+			this.handshake(spec, config);
+		} catch (error) {
+			this.fail("启动适配器失败：" + String(error));
+		}
+	}
+	/** 停止会话（disconnect 尽力发送 + 杀进程树）。 */
+	stop() {
+		if (!this.child) {
+			this.setPhase("idle");
+			return;
+		}
+		this.request("disconnect").catch(() => {});
+		this.killChild();
+		this.pushEvent({ kind: "terminated" });
+		this.setPhase("terminated");
+	}
+	/** 释放会话（插件卸载/进程退出）：杀进程树并复位。 */
+	dispose() {
+		this.killChild();
+		this.setPhase("idle");
+	}
+	/**
+	* poll：状态 + since 之后的增量事件（纯读，无副作用）。
+	* @author ddj 2026年09月29号
+	* @param since 客户端已有游标
+	*/
+	poll(since) {
+		const events = this.events.filter((e) => e.seq > since);
+		const nextSeq = this.eventSeq;
+		return {
+			state: this.stateOf(),
+			events,
+			nextSeq
+		};
+	}
+	/**
+	* 设置某文件断点（DAP per-source replace-all 语义）。
+	* 不属于当前适配器语言的文件不入适配器（防跨语言串发），回执 verified=false 带原因；
+	* 适配器在线时消费真实回执（可能挪行/判不可验证），离线时按旧口径乐观回执（start 后 flush 重发）。
+	* @author ddj 2026年09月29号 / 2026年09月21号
+	* @param absFile 目标文件绝对路径
+	* @param items 该文件断点行列表
+	*/
+	async setBreakpoints(absFile, items) {
+		const allowed = this.bpAllowed(absFile);
+		this.breakpoints = this.breakpoints.filter((bp) => bp.file !== absFile);
+		if (allowed) for (const p of items) this.breakpoints.push({
+			file: absFile,
+			line: p.line,
+			condition: p.condition,
+			hitCondition: p.hitCondition,
+			logMessage: p.logMessage
+		});
+		const res = allowed ? await this.request("setBreakpoints", {
+			source: {
+				name: absFile.split(/[\\/]/).pop() ?? "",
+				path: absFile
+			},
+			breakpoints: items.map((p) => ({
+				line: p.line,
+				condition: p.condition,
+				hitCondition: p.hitCondition,
+				logMessage: p.logMessage
+			}))
+		}) : null;
+		if (!res || !isDapResponse(res) || !res.success) return items.map((p) => ({
+			line: p.line,
+			verified: allowed,
+			...allowed ? {} : { message: "当前调试器不处理该文件类型" }
+		}));
+		return bpAcksOfResponse(responseBody(res), items);
+	}
+	/** 调用栈（paused 限定；threadId 取当前停帧线程）。 */
+	async stackTrace() {
+		if (this.phase !== "paused") return this.frames;
+		const res = await this.request("stackTrace", { threadId: this.threadId });
+		if (!res || !isDapResponse(res) || !res.success) return this.frames;
+		const raw = responseBody(res).stackFrames;
+		if (!Array.isArray(raw)) return this.frames;
+		this.frames = await Promise.all(raw.map((item, index) => this.frameViewOf(item, index)));
+		this.stateTop = this.frames[0] ? {
+			file: this.frames[0].file,
+			rawFile: this.frames[0].rawFile,
+			line: this.frames[0].line,
+			name: this.frames[0].name
+		} : null;
+		return this.frames;
+	}
+	/** 作用域列表（paused 限定；frameId 语义随适配器：emmylua=栈下标，标准=原生 frame id）。 */
+	async scopes(frameId) {
+		if (this.phase !== "paused") return [];
+		const res = await this.request("scopes", { frameId });
+		if (!res || !isDapResponse(res) || !res.success) return [];
+		const raw = responseBody(res).scopes;
+		if (!Array.isArray(raw)) return [];
+		return raw.map((item) => {
+			const s = item;
+			return {
+				name: String(s.name ?? ""),
+				ref: typeof s.variablesReference === "number" ? s.variablesReference : 0,
+				hint: typeof s.presentationHint === "string" ? s.presentationHint : void 0
+			};
+		});
+	}
+	/** 变量子级（paused 限定）。 */
+	async variables(ref) {
+		if (this.phase !== "paused") return [];
+		const res = await this.request("variables", { variablesReference: ref });
+		if (!res || !isDapResponse(res) || !res.success) return [];
+		const raw = responseBody(res).variables;
+		if (!Array.isArray(raw)) return [];
+		return raw.map((item) => {
+			const v = item;
+			return {
+				name: String(v.name ?? ""),
+				value: String(v.value ?? ""),
+				type: typeof v.type === "string" ? v.type : void 0,
+				ref: typeof v.variablesReference === "number" ? v.variablesReference : 0
+			};
+		});
+	}
+	/** 表达式求值（REPL/监视；paused 限定，避免适配器挂起）。 */
+	async evaluate(expression, frameId) {
+		if (this.phase !== "paused") return {
+			result: "未暂停：仅在断点暂停时可求值",
+			ref: 0
+		};
+		const res = await this.request("evaluate", {
+			expression,
+			frameId: frameId ?? 0,
+			context: "repl"
+		});
+		if (!res || !isDapResponse(res) || !res.success) return {
+			result: "求值失败",
+			ref: 0
+		};
+		const body = responseBody(res);
+		return {
+			result: String(body.result ?? ""),
+			type: typeof body.type === "string" ? body.type : void 0,
+			ref: typeof body.variablesReference === "number" ? body.variablesReference : 0
+		};
+	}
+	/** 调试控制动作（线程型命令携带当前停帧线程；emmylua 单线程 threadId 恒 1 不受影响）。 */
+	action(action) {
+		if (!DAP_ACTIONS.includes(action)) return;
+		const command = action === "disconnect" ? "disconnect" : action;
+		this.request(command, action === "disconnect" ? void 0 : { threadId: this.threadId }).catch(() => {});
+		if (action === "continue" || action === "next" || action === "stepIn" || action === "stepOut") this.setPhase("running");
+	}
+	/** spawn 适配器进程并接好帧解析。 */
+	spawnAdapter(spec) {
+		const child = spawn(spec.command, spec.args, {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			windowsHide: true
+		});
+		this.child = child;
+		const parser = createFrameParser();
+		child.stdout?.on("data", (chunk) => {
+			for (const message of parser.push(chunk)) this.handleMessage(message);
+		});
+		child.stderr?.on("data", (chunk) => {
+			log.debug("[dap-adapter] " + chunk.toString("utf8").trim());
+			this.stderrTail = (this.stderrTail + chunk.toString("utf8")).slice(-2e3);
+		});
+		child.on("error", (error) => this.fail("适配器进程错误：" + String(error)));
+		child.on("exit", (code) => {
+			if (this.child === child && this.phase !== "idle" && this.phase !== "terminated") this.fail("适配器退出（code=" + code + "）" + this.stderrSuffix());
+		});
+	}
+	/**
+	* stderr 尾部摘要（供 fail 消息附带）：取末尾若干非空行、以 | 折叠单行化。
+	* 无 stderr 内容时返回空串（不改变既有消息文案）。
+	* @author ddj 2026年09月22号
+	* @returns 形如「；stderr: xxx | yyy」的摘要，或空串
+	*/
+	stderrSuffix() {
+		const text = this.stderrTail.trim();
+		if (!text) return "";
+		const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+		if (!lines.length) return "";
+		return "；stderr: " + lines.slice(-6).join(" | ");
+	}
+	/** initialize → attach/launch 握手（initialized 事件后重发断点 + 按能力位收尾）。 */
+	async handshake(spec, config) {
+		const init = await this.request("initialize", initializeArgs(spec.type));
+		if (!init || !isDapResponse(init) || !init.success) {
+			this.fail("initialize 失败：" + (init && isDapResponse(init) ? init.message ?? "" : "超时"));
+			return;
+		}
+		this.caps = responseBody(init);
+		const request = requestOfConfig(config);
+		const res = await this.request(request, this.requestArgs(config));
+		if (!res || !isDapResponse(res) || !res.success) this.fail((request === "attach" ? "attach 失败：" : "launch 失败：") + (res && isDapResponse(res) ? res.message ?? "" : "超时"));
+	}
+	/**
+	* attach/launch 请求参数：launch.json 原样透传（含未识别字段，对齐 VS Code 语义），
+	* emmylua 兼容缺省注入（对齐扩展自身 resolveDebugConfiguration：extensionPath/pid 等）。
+	* @author ddj 2026年09月21号
+	* @param config 调试配置
+	*/
+	requestArgs(config) {
+		const args = { ...config.raw ?? {} };
+		if (args.cwd === void 0 && this.workspacePath) args.cwd = this.workspacePath;
+		if (this.extId !== EMMYLUA_EXT_ID) {
+			if (!(config.type === "unity") && this.pid && requestOfConfig(config) === "attach" && args.processId === void 0) args.processId = this.pid;
+			return args;
+		}
+		if (args.extensionPath === void 0) args.extensionPath = this.extPath;
+		if (requestOfConfig(config) === "attach") {
+			args.pid = this.pid ?? (typeof args.pid === "number" && args.pid > 0 ? args.pid : 0);
+			if (!Array.isArray(args.sourcePaths)) args.sourcePaths = [this.workspacePath];
+			if (!Array.isArray(args.ext)) args.ext = [".lua"];
+			if (args.captureLog === void 0) args.captureLog = false;
+			return args;
+		}
+		if (args.host === void 0) args.host = "localhost";
+		if (args.port === void 0) args.port = 9966;
+		if (args.ideConnectDebugger === void 0) args.ideConnectDebugger = true;
+		if (!Array.isArray(args.sourcePaths)) args.sourcePaths = [this.workspacePath];
+		if (!Array.isArray(args.ext)) args.ext = [".lua"];
+		return args;
+	}
+	/** DAP 消息分流：响应 → pending；事件 → handleEvent。 */
+	handleMessage(message) {
+		if (isDapResponse(message)) {
+			const entry = this.pending.get(message.request_seq);
+			if (entry) {
+				this.pending.delete(message.request_seq);
+				entry.resolve(message);
+			}
+			return;
+		}
+		if (isDapEvent(message)) this.handleEvent(message);
+	}
+	/** 事件处理：initialized/stopped/terminated/output/log/findFileReq。 */
+	handleEvent(event) {
+		const body = eventBody(event);
+		if (event.event === "initialized") {
+			this.setPhase("running");
+			this.flushBreakpoints();
+			if (needsConfigurationDone(this.caps)) this.request("configurationDone").catch(() => {});
+			return;
+		}
+		if (event.event === "stopped") {
+			this.threadId = threadIdOfStopped(body);
+			this.handleStopped(String(body.reason ?? "breakpoint"));
+			return;
+		}
+		if (event.event === "terminated") {
+			if (this.phase === "starting") {
+				const hint = this.earlyTermHint();
+				this.pushEvent({
+					kind: "output",
+					text: hint + "\n"
+				});
+				this.deps.trace?.(this.workspacePath, "[DEBUG terminated] " + hint);
+			}
+			this.pushEvent({ kind: "terminated" });
+			this.setPhase("terminated");
+			return;
+		}
+		if (event.event === "continued") {
+			this.setPhase("running");
+			this.pushEvent({ kind: "continued" });
+			return;
+		}
+		if (event.event === "findFileReq") {
+			this.respondFindFile(body);
+			return;
+		}
+		if (event.event === "output" || event.event === "log") this.pushEvent({
+			kind: "output",
+			text: String(body.output ?? body.message ?? "")
+		});
+	}
+	/** 停帧：置 paused + 预拉调用栈（首帧进 state.topFrame 驱动跳转高亮）。 */
+	async handleStopped(reason) {
+		this.pushEvent({
+			kind: "stopped",
+			reason
+		});
+		this.setPhase("paused");
+		try {
+			await this.stackTrace();
+		} catch {}
+	}
+	/**
+	* 初始化前终止的控制台提示：指明失败阶段并给出适配器日志位置（根因常在适配器自家日志）。
+	* DotRush 扩展的 monodbg 日志固定在扩展根 bin/DebuggerMono/logs，直接给绝对路径；
+	* 其它适配器回退到通用指引（宿主日志 [dap-adapter] 段有 stderr 镜像）。
+	* @author ddj 2026年09月22号
+	* @returns 提示文本（不含换行）
+	*/
+	earlyTermHint() {
+		return "会话在初始化完成前终止（attach/连接目标失败）" + (this.extId === "nromanov.dotrush" && this.extPath ? "；适配器日志：" + join(this.extPath, "bin", "DebuggerMono", "logs", "Error.log") : "；请查看适配器自身日志与宿主日志 [dap-adapter] 段");
+	}
+	/** findFileReq 反向应答：按完整 chunkname 排序工作区候选并缓存首命中。 */
+	async respondFindFile(body) {
+		const seq = typeof body.seq === "number" ? body.seq : -1;
+		const chunk = String(body.file ?? "");
+		const files = await this.deps.findFiles(this.workspacePath, chunk);
+		log.debug("[dap-trace] findFileReq seq=" + seq + " chunk=" + chunk + " candidates=" + files.length + " first=" + (files[0] ?? ""));
+		this.deps.trace?.(this.workspacePath, "[DEBUG findFileReq] seq=" + seq + " chunk=" + chunk + " candidates=" + files.length + " first=" + (files[0] ?? ""));
+		const first = files[0];
+		if (first) {
+			this.sourceFiles.set(sourceKeyOf(chunk), first);
+			this.sourceFiles.set(sourceKeyOf(sourceBaseOf(chunk)), first);
+		}
+		this.send({
+			seq: this.msgSeq++,
+			type: "request",
+			command: "findFileRsp",
+			arguments: {
+				seq,
+				files
+			}
+		});
+	}
+	/** 发送已存断点（initialized 后调用一次；只发属于当前适配器语言的文件）。 */
+	flushBreakpoints() {
+		if (!this.breakpoints.length) return;
+		const byFile = /* @__PURE__ */ new Map();
+		for (const bp of this.breakpoints) {
+			if (!this.bpAllowed(bp.file)) continue;
+			const list = byFile.get(bp.file) ?? [];
+			list.push(bp);
+			byFile.set(bp.file, list);
+		}
+		for (const [file, list] of byFile) this.request("setBreakpoints", {
+			source: {
+				name: file.split(/[\\/]/).pop() ?? "",
+				path: file
+			},
+			breakpoints: list.map((bp) => ({
+				line: bp.line,
+				condition: bp.condition,
+				hitCondition: bp.hitCondition,
+				logMessage: bp.logMessage
+			}))
+		}).catch(() => {});
+	}
+	/** 断点文件是否属于当前适配器（按声明扩展名过滤；未知语言不过滤，兼容旧链路）。 */
+	bpAllowed(file) {
+		if (!this.exts.length) return true;
+		const lower = file.toLowerCase();
+		return this.exts.some((ext) => lower.endsWith(ext));
+	}
+	/** 栈帧源码扩展名判定集：emmylua 沿用旧口径（.lua 家族 + 配置 ext），通用适配器用声明 exts。 */
+	frameExts() {
+		if (this.extId !== EMMYLUA_EXT_ID) return this.exts;
+		return [.../* @__PURE__ */ new Set([
+			...this.config?.ext ?? [],
+			".lua",
+			".lua.bytes"
+		])];
+	}
+	/** 栈帧 id：emmylua 的 scopes 以 stacks 下标为 frameId（私有语义）；标准适配器用原生 id。 */
+	frameIdOf(raw, index) {
+		if (this.extId === EMMYLUA_EXT_ID) return index;
+		return typeof raw.id === "number" ? raw.id : index;
+	}
+	/** 发送请求（seq 自增 + 超时守卫；适配器不回包时拒绝而非悬挂）。 */
+	request(command, args) {
+		if (!this.child?.stdin?.writable) return Promise.resolve(null);
+		const seq = this.msgSeq++;
+		const frame = dapRequest(seq, command, args);
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(seq);
+				resolve(null);
+			}, REQUEST_TIMEOUT_MS);
+			this.pending.set(seq, {
+				resolve,
+				timer
+			});
+			this.child.stdin.write(encodeMessage(frame));
+		});
+	}
+	/** 直发原始帧（反向请求应答等无需等待响应的场景）。 */
+	send(frame) {
+		if (!this.child?.stdin?.writable) return;
+		this.child.stdin.write(encodeMessage(frame));
+	}
+	/** 追加事件（环形截断）。 */
+	pushEvent(partial) {
+		this.eventSeq += 1;
+		this.events.push({
+			seq: this.eventSeq,
+			...partial
+		});
+		if (this.events.length > EVENT_CAP) this.events.splice(0, this.events.length - EVENT_CAP);
+	}
+	/** 记录错误并终止会话。 */
+	fail(message) {
+		this.error = message;
+		log.warn("[dap] " + message);
+		this.pushEvent({
+			kind: "output",
+			text: message + "\n"
+		});
+		this.pushEvent({ kind: "terminated" });
+		this.killChild();
+		this.setPhase("terminated");
+	}
+	/** 杀适配器进程树（Windows taskkill /T /F，同 LSP transport 口径）。 */
+	killChild() {
+		const child = this.child;
+		this.child = null;
+		for (const entry of this.pending.values()) {
+			clearTimeout(entry.timer);
+			entry.resolve(null);
+		}
+		this.pending.clear();
+		if (!child) return;
+		try {
+			child.kill();
+		} catch {}
+		if (process.platform === "win32" && child.pid) try {
+			spawn("taskkill", [
+				"/PID",
+				String(child.pid),
+				"/T",
+				"/F"
+			], {
+				windowsHide: true,
+				stdio: "ignore"
+			});
+		} catch {}
+		setTimeout(() => {
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+		}, 1500).unref?.();
+	}
+	/** 相位切换（running→running 等幂等跳过）。 */
+	setPhase(phase) {
+		if (this.phase === phase) return;
+		this.phase = phase;
+		if (phase === "idle") {
+			this.events = [];
+			this.config = null;
+			this.pid = void 0;
+			this.error = void 0;
+		}
+	}
+	/** 适配器上报路径 → 帧视图（file 始终保留可打开的规范路径）。 */
+	async frameViewOf(item, index) {
+		const raw = item;
+		const source = raw.source ?? {};
+		const sourcePath = typeof source.path === "string" ? source.path : "";
+		const sourceName = typeof source.name === "string" ? source.name : "";
+		const cached = this.sourceFiles.get(sourceKeyOf(sourcePath)) ?? this.sourceFiles.get(sourceKeyOf(sourceName));
+		let selected = cached || sourcePath || sourceName;
+		const needsLookup = !selected || !hasSourceExtension(selected, this.frameExts());
+		log.debug("[dap-trace] frame rawPath=" + sourcePath + " name=" + sourceName + " cached=" + (cached ?? "") + " needsLookup=" + needsLookup + " selected=" + selected);
+		this.deps.trace?.(this.workspacePath, "[DEBUG frame] rawPath=" + sourcePath + " name=" + sourceName + " cached=" + (cached ?? "") + " needsLookup=" + needsLookup + " selected=" + selected);
+		if (!cached && needsLookup) {
+			const candidates = await this.deps.findFiles(this.workspacePath, sourceName || sourcePath);
+			log.debug("[dap-trace] frameLookup source=" + (sourceName || sourcePath) + " candidates=" + candidates.length + " first=" + (candidates[0] ?? ""));
+			this.deps.trace?.(this.workspacePath, "[DEBUG frameLookup] source=" + (sourceName || sourcePath) + " candidates=" + candidates.length + " first=" + (candidates[0] ?? ""));
+			if (candidates[0]) {
+				selected = candidates[0];
+				this.sourceFiles.set(sourceKeyOf(sourceName || sourcePath), candidates[0]);
+			} else if (isBareChunk(sourceName || sourcePath)) selected = "";
+		}
+		const finalFile = selected ? sourcePathOf(selected, this.workspacePath) : "";
+		log.debug("[dap-trace] frameFinal name=" + sourceName + " file=" + finalFile + " line=" + String(raw.line ?? 0));
+		this.deps.trace?.(this.workspacePath, "[DEBUG frameFinal] name=" + sourceName + " file=" + finalFile + " line=" + String(raw.line ?? 0));
+		return {
+			id: this.frameIdOf(raw, index),
+			name: String(raw.name ?? ""),
+			file: finalFile,
+			rawFile: sourceName || sourcePath || selected,
+			line: typeof raw.line === "number" ? raw.line : 0
+		};
+	}
+};
+//#endregion
+//#region src/dap/rpc.ts
+/**
+* dsh-vscode-mode host — 调试 RPC（edrv.dap.*）装配。
+* 单例 DapSession + 适配器发现（扩展清单驱动，通用不限定语言）+ 进程枚举 +
+* launch.json 读取（全量透传）+ findFile 反向匹配（chunkname → ripgrep 定向查找源文件）。
+* 作者 ddj 2026年09月29号 / 2026年09月21号
+*/
+/**
+* 解析工作区根为 subprocess 执行世界可见的真实路径。
+* DAP 会话无 DSH Session 对象，不能让 fs.resolve('.') 落回 host 进程目录，
+* 因此显式以 cwd 为基准解析 `.`（= cwd 本身）。
+* @author ddj 2026年09月21号
+* @param ctx DSH 上下文
+* @param workspacePath 工作区绝对路径
+* @returns 可交给 rg 的根路径；fs 不可用或解析失败返回空串
+*/
+async function rootPathOf(ctx, workspacePath) {
+	const fs = ctx.get("fs");
+	if (!fs || !workspacePath) return "";
+	try {
+		const target = await fs.resolve(".", { cwd: workspacePath });
+		return fs.processPath(target) || "";
+	} catch (error) {
+		return "";
+	}
+}
+/**
+* 创建调试 RPC（单例会话随插件装配创建，ctx.effect 里调 disposeDap 清理）。
+* @author ddj 2026年09月29号
+* @param ctx DSH 上下文
+*/
+function createDapRpc(ctx) {
+	const session = new DapSession({
+		findFiles: async (workspacePath, chunk) => {
+			const clean = normalizeSourcePath(chunk);
+			if (!clean) return [];
+			const root = await rootPathOf(ctx, workspacePath);
+			if (!root) {
+				debugRecord(ctx, workspacePath, "[DEBUG findFiles] chunk=" + clean + " root=(无法解析) candidates=0", "debug");
+				return [];
+			}
+			const ranked = rankSourceCandidates(clean, await findFilesByChunk(ctx, root, clean), workspacePath);
+			log.debug("[dap-trace] findFiles chunk=" + clean + " cwd=" + workspacePath + " root=" + root + " candidates=" + ranked.length + " first=" + (ranked[0] ?? ""));
+			debugRecord(ctx, workspacePath, "[DEBUG findFiles] chunk=" + clean + " root=" + root + " candidates=" + ranked.length + " first=" + (ranked[0] ?? ""), "debug");
+			return ranked;
+		},
+		trace: (workspacePath, message) => debugRecord(ctx, workspacePath, message, "debug")
+	});
+	return {
+		handlers: {
+			"edrv.dap.configs": async (args) => {
+				const configs = await readLaunchConfigs(ctx, args.workspacePath);
+				return {
+					ok: true,
+					configs,
+					adapters: debuggerDecls().map((d) => ({
+						type: d.type,
+						label: d.label,
+						available: d.available,
+						reason: d.reason
+					})),
+					source: configs.length ? "launchjson" : "none"
+				};
+			},
+			"edrv.dap.snippets": async () => ({
+				ok: true,
+				snippets: annotateSnippets(dapConfigSnippets(), debuggerDecls())
+			}),
+			"edrv.dap.processes": async (args) => {
+				return {
+					ok: true,
+					items: filterProcesses(await listProcesses(), args.processName)
+				};
+			},
+			"edrv.dap.start": async (args) => {
+				const config = args.config;
+				if (hasCmdPlaceholder(config)) return {
+					ok: false,
+					error: "配置含 ${command:...} 占位（VS Code 命令），本插件无法解析，请在 launch.json 中改为具体值"
+				};
+				const spec = resolveAdapterSpec(config.type);
+				if (!spec) return {
+					ok: false,
+					error: unknownTypeMessage(config.type)
+				};
+				let pid = args.pid && args.pid > 0 ? args.pid : void 0;
+				if (requestOfConfig(config) === "attach" && !pid && !config.processId) {
+					const resolved = await resolvePid(config.processName);
+					if (typeof resolved === "string") return {
+						ok: false,
+						error: resolved
+					};
+					pid = resolved;
+				}
+				session.start(spec, config, args.workspacePath, pid);
+				return {
+					ok: true,
+					phase: "starting"
+				};
+			},
+			"edrv.dap.stop": async () => {
+				session.stop();
+				return { ok: true };
+			},
+			"edrv.dap.poll": async (args) => ({
+				ok: true,
+				...session.poll(args.since)
+			}),
+			"edrv.dap.setBreakpoints": async (args) => {
+				const abs = join(args.workspacePath, args.file.replace(/\\/g, "/"));
+				return {
+					ok: true,
+					breakpoints: await session.setBreakpoints(abs, args.points)
+				};
+			},
+			"edrv.dap.stackTrace": async () => ({
+				ok: true,
+				frames: await session.stackTrace()
+			}),
+			"edrv.dap.scopes": async (args) => ({
+				ok: true,
+				scopes: await session.scopes(args.frameId)
+			}),
+			"edrv.dap.variables": async (args) => ({
+				ok: true,
+				variables: await session.variables(args.ref)
+			}),
+			"edrv.dap.evaluate": async (args) => ({
+				ok: true,
+				...await session.evaluate(args.expression, args.frameId)
+			}),
+			"edrv.dap.command": async (args) => {
+				if (!DAP_ACTIONS.includes(args.action)) return {
+					ok: false,
+					error: "未知动作：" + args.action
+				};
+				if (args.action === "disconnect") session.stop();
+				else session.action(args.action);
+				return { ok: true };
+			}
+		},
+		dispose: () => session.dispose()
+	};
+}
+/**
+* processName → pid：唯一命中直用；0 命中或多命中返回错误文案（客户端引导用 processes 列表选择）。
+* @author ddj 2026年09月29号
+* @param processName 进程名（标题/文件名包含匹配）
+*/
+async function resolvePid(processName) {
+	const items = filterProcesses(await listProcesses(), processName);
+	if (items.length === 1) return items[0].pid;
+	if (items.length === 0) return "未找到匹配进程：" + (processName || "(空)");
+	return "匹配到 " + items.length + " 个进程，请先在进程列表中选择（edrv.dap.processes）";
+}
+/**
+* 读工作区调试配置：优先 `.dsh/launch.json`（插件专属）；缺失时从旧共用
+* `.vscode/launch.json` 一次性迁移（只读 legacy 源、永不回写；复制失败当次
+* 仍用 legacy 内容响应不丢配置，下次读重试）；都缺失 → 空表。
+* @author ddj 2026年09月22号
+* @param ctx DSH 上下文
+* @param workspacePath 工作区绝对路径
+* @returns 解析后的配置列表
+*/
+async function readLaunchConfigs(ctx, workspacePath) {
+	const fs = ctx.get("fs");
+	if (!fs || !workspacePath) return [];
+	try {
+		const target = await fs.resolve(DAP_LAUNCH_REL, { cwd: workspacePath });
+		let text = "";
+		let exists = true;
+		try {
+			text = String(await fs.readText(target) ?? "");
+		} catch {
+			exists = false;
+		}
+		if (exists) return parseLaunchConfigs(text, workspacePath);
+		let legacy = "";
+		let legacyExists = true;
+		try {
+			const source = await fs.resolve(DAP_LEGACY_LAUNCH_REL, { cwd: workspacePath });
+			legacy = String(await fs.readText(source) ?? "");
+		} catch {
+			legacyExists = false;
+		}
+		if (!legacyExists) return [];
+		try {
+			const realPath = fs.processPath(target);
+			await mkdir(join(realPath, ".."), { recursive: true });
+			await writeFile(realPath, legacy, "utf8");
+			log.debug("[dap] 已迁移 .vscode/launch.json → .dsh/launch.json（" + workspacePath + "）");
+		} catch (error) {
+			log.debug("[dap] launch.json 迁移失败（下次读重试，本次以旧源响应）：" + String(error));
+		}
+		return parseLaunchConfigs(legacy, workspacePath);
+	} catch (error) {
+		log.debug("[dap] launch.json 读取失败（视为无配置）：" + String(error));
+		return [];
+	}
+}
+/**
+* 未知调试类型的错误文案：列出已识别类型（含不可用原因），引导用户安装/排查。
+* @author ddj 2026年09月21号
+* @param type launch.json 中的调试类型
+*/
+function unknownTypeMessage(type) {
+	const known = debuggerDecls().map((d) => d.type + (d.available ? "" : "（" + (d.reason ?? "不可用") + "）")).join(" / ");
+	return "未发现调试类型「" + type + "」的适配器（已识别：" + (known || "无，请安装带调试器的扩展") + "）";
 }
 //#endregion
 //#region src/index.ts
@@ -13866,6 +16093,9 @@ function apply(ctx, config) {
 		ctx,
 		settings: openSettings
 	}).handlers;
+	/** 调试 RPC（DAP 桥单例：spawn 扩展适配器 + 事件缓冲 + findFile 反向匹配）。 */
+	const dapRpc = createDapRpc(ctx);
+	const dapHandlers = dapRpc.handlers;
 	/** 文件磁盘新鲜度观察器（客户端轮询 edrv.versions；变化时顺带失效目录树缓存）。 */
 	const fileVersions = createFileVersions(ctx);
 	ctx.on("tools/result", (exec, result) => {
@@ -13875,7 +16105,6 @@ function apply(ctx, config) {
 		const cwd = cwdOf(session);
 		if (cwd) {
 			registry.delete(cwd);
-			dropFileIndex(cwd);
 			searcher.dispose(cwd);
 			contentSearcher.dispose(cwd);
 			disposeIndex(cwd);
@@ -13883,7 +16112,7 @@ function apply(ctx, config) {
 		const sid = session?.id;
 		if (typeof sid === "string") lspRpc.disposeSession(sid);
 	});
-	registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions, svnHandlers), (warning) => warnings.push(warning));
+	registerRoutes(ctx, config, (method, args) => handleRpc(ctx, registry, method, args, searcher, contentSearcher, lspHandlers, aiHandlers, fileVersions, svnHandlers, dapHandlers), (warning) => warnings.push(warning));
 	installIsolation(ctx);
 	ctx.effect(() => shellMenuLifecycle(ctx));
 	sweepTreeCache();
@@ -13893,6 +16122,7 @@ function apply(ctx, config) {
 		disposeAllServers();
 	});
 	ctx.effect(() => () => fileVersions.dispose());
+	ctx.effect(() => () => dapRpc.dispose());
 	hookExitReclaim();
 	log.info("编辑差异审查已装配（/edrv/rpc 路由就绪，项目 MCP 隔离已启用，语言服务器 LSP 已接入，规则注入" + (rulesInstalled ? "已接入" : "未接入") + "，技能组" + (skillsDispatched ? "装配中" : "未装配") + "）");
 }