dsh-vscode-mode 0.21.0 → 0.21.2

package/lib/index.js

@@ -464,1434 +464,1467 @@ var McpBridge = class McpBridge {
 	}
 };
 //#endregion
-//#region src/mcpPool.ts
-/** Connection ownership, bounded cold starts and workspace leases. @author ddj 2026年10月20号 */
-/** @private @author ddj 2026年10月20号 @param input Plain effective configuration. @returns Stable secret-bearing identity used only as digest input. */
-function stableConfig(input) {
-	if (Array.isArray(input)) return "[" + input.map(stableConfig).join(",") + "]";
-	if (input && typeof input === "object") {
-		const config = input;
-		return "{" + Object.keys(config).sort().map((key) => JSON.stringify(key) + ":" + stableConfig(config[key])).join(",") + "}";
-	}
-	return JSON.stringify(input) ?? "null";
-}
-/** @public @author ddj 2026年10月20号 @param task Shared work that must remain alive for other waiters. @param signal One waiter's cancellation. @returns Caller-local wait without abandoning owned pool work. */
-function waitMcp(task, signal) {
-	if (!signal) return task;
-	return new Promise((resolve, reject) => {
-		/** @author ddj 2026年10月20号 Rejects only this waiter. */
-		const abort = () => {
-			reject(/* @__PURE__ */ new Error("MCP 等待已取消"));
-		};
-		if (signal.aborted) {
-			abort();
-			return;
-		}
-		signal.addEventListener("abort", abort, { once: true });
-		task.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
-	});
-}
-/** The pool owns private scopes independently from any first subscriber. */
-var McpPool = class {
-	ctx;
-	load;
-	make;
-	entries = /* @__PURE__ */ new Map();
-	owners = /* @__PURE__ */ new WeakMap();
-	ownerSeq = 0;
-	running = 0;
-	queue = [];
-	jobs = /* @__PURE__ */ new Set();
-	stopped = false;
-	/** @public @author ddj 2026年10月20号 @param ctx Host lifecycle owner. @param load Official plugin loader. @param make Private scope factory. */
-	constructor(ctx, load, make = () => McpBridge.create(ctx)) {
-		this.ctx = ctx;
-		this.load = load;
-		this.make = make;
-	}
-	/** @private @author ddj 2026年10月20号 @param spec Effective request. @returns Private digest; never emit configuration or secrets. */
-	keyOf(spec) {
-		let owner = 0;
-		if (spec.policy.sharing === "agent") {
-			if (!this.owners.has(spec.owner)) this.owners.set(spec.owner, ++this.ownerSeq);
-			owner = this.owners.get(spec.owner);
-		}
-		const workspace = process.platform === "win32" ? spec.workspace.replace(/\\/g, "/").toLowerCase() : spec.workspace;
-		return createHash("sha256").update(stableConfig([
-			workspace,
-			owner,
-			spec.config,
-			spec.policy
-		])).digest("hex");
-	}
-	/** @public @author ddj 2026年10月20号 @param spec Authorized connection request. @returns Reference-counted single-flight lease. */
-	acquire(spec) {
-		if (this.stopped) throw new Error("MCP runtime is disposed");
-		const key = this.keyOf(spec);
-		let entry = this.entries.get(key);
-		if (entry?.phase === "error" && entry.retryAt !== void 0 && Date.now() >= entry.retryAt && !entry.close) {
-			this.entries.delete(key);
-			entry = void 0;
-		}
-		if (entry && !entry.live) throw new Error(entry.error ?? "MCP 旧连接仍在释放，暂不能创建替代实例");
-		if (!entry) {
-			entry = {
-				key,
-				spec,
-				refs: 0,
-				phase: "queued",
-				queuedAt: Date.now(),
-				phaseAt: Date.now(),
-				ready: Promise.resolve(),
-				live: true,
-				calls: Promise.resolve()
-			};
-			this.entries.set(key, entry);
-			entry.ready = this.schedule(entry);
-			entry.ready.catch(() => void 0);
-		}
-		if (entry.idle) clearTimeout(entry.idle);
-		entry.idle = void 0;
-		entry.refs += 1;
-		let released = false;
-		return {
-			entry,
-			release: () => {
-				if (released) return;
-				released = true;
-				this.release(entry);
-			}
-		};
-	}
-	/** @private @author ddj 2026年10月20号 @param entry New entry. @returns Queued initialization, bounded to two concurrent starts. */
-	schedule(entry) {
-		return new Promise((resolve, reject) => {
-			/** @author ddj 2026年10月20号 Initializes a still-owned queue item. */
-			const run = async () => {
-				try {
-					await this.start(entry);
-					resolve();
-				} catch (error) {
-					reject(error);
-				}
-			};
-			this.queue.push(run);
-			this.pump();
-		});
-	}
-	/** @private @author ddj 2026年10月20号 Advances FIFO work; each task holds its slot until startup or cleanup quiesces. */
-	pump() {
-		while (this.running < 2 && this.queue.length) {
-			const run = this.queue.shift();
-			this.running += 1;
-			const job = run().finally(() => {
-				this.running -= 1;
-				this.jobs.delete(job);
-				this.pump();
-			});
-			this.jobs.add(job);
-		}
-	}
-	/** @private @author ddj 2026年10月20号 @param entry Connection to initialize. @returns Initialization completion, or failure after owned cleanup. */
-	async start(entry) {
-		if (!entry.live || this.stopped) throw new Error("MCP 启动已取消");
-		entry.phase = "loading";
-		entry.phaseAt = Date.now();
-		entry.startAt = entry.phaseAt;
-		let timer;
-		const work = this.mount(entry);
-		const deadline = new Promise((_resolve, reject) => {
-			timer = setTimeout(() => reject(/* @__PURE__ */ new Error("MCP 初始化超时")), entry.spec.policy.startupTimeoutMs);
-			timer.unref?.();
-		});
-		try {
-			await Promise.race([work, deadline]);
-			if (!entry.live) throw new Error("MCP 启动已取消");
-			entry.phase = "ready";
-			entry.finishedAt = Date.now();
-			entry.connectedAt = entry.finishedAt;
-		} catch (error) {
-			entry.error = "MCP 初始化失败或超时，请查看 Host 日志";
-			this.ctx.logger?.warn?.("MCP initialization failed: " + String(error));
-			entry.live = false;
-			entry.phase = "stopping";
-			const closing = this.closeBridge(entry);
-			await Promise.allSettled([closing, work]);
-			entry.phase = "error";
-			entry.finishedAt = Date.now();
-			entry.retryAt = Date.now() + 5e3;
-			throw new Error(entry.error);
-		} finally {
-			if (timer) clearTimeout(timer);
-		}
-	}
-	/** @private @author ddj 2026年10月20号 @param entry Owned generation. @returns Official initial sync; never publishes after invalidation. */
-	async mount(entry) {
-		const official = await this.load();
-		if (!entry.live || this.stopped) return;
-		const bridge = await this.make();
-		if (!entry.live || this.stopped) {
-			await bridge.dispose();
-			return;
-		}
-		entry.bridge = bridge;
-		entry.phase = "starting";
-		entry.phaseAt = Date.now();
-		entry.fiber = bridge.scope.ctx.plugin(official, entry.spec.config);
-		await entry.fiber;
-		if (entry.fiber?.state !== void 0 && entry.fiber.state !== 2) throw new Error("MCP 插件未完成激活");
-	}
-	/** @private @author ddj 2026年10月20号 @param entry Connection to close. @returns Shared closure barrier; rejection retains a fenced entry. */
-	async closeBridge(entry) {
-		if (entry.close) return entry.close;
-		const close = entry.bridge?.dispose() ?? Promise.resolve();
-		entry.close = close;
-		try {
-			await close;
-			entry.bridge = void 0;
-			entry.fiber = void 0;
-			entry.close = void 0;
-		} catch (error) {
-			entry.error = "MCP 释放未确认，禁止重建，请查看 Host 日志";
-			this.ctx.logger?.warn?.("MCP cleanup failed: " + String(error));
-			throw error;
-		}
-	}
-	/** @private @author ddj 2026年10月20号 @param entry One lease's owner. Arms workspace-only warm retention. */
-	release(entry) {
-		entry.refs = Math.max(0, entry.refs - 1);
-		if (entry.refs || !entry.live) return;
-		if (entry.spec.policy.sharing === "agent") {
-			this.retire(entry).catch(() => void 0);
-			return;
-		}
-		entry.idle = setTimeout(() => {
-			this.retire(entry).catch(() => void 0);
-		}, 6e4);
-		entry.idle.unref?.();
-	}
-	/** @public @author ddj 2026年10月20号 @param entry Invalid generation. @returns Quiescent close; callers may await before starting a replacement. */
-	async retire(entry) {
-		entry.live = false;
-		entry.phase = "stopping";
-		if (entry.idle) clearTimeout(entry.idle);
-		await this.closeBridge(entry);
-		await entry.ready.catch(() => void 0);
-		await entry.calls.catch(() => void 0);
-		if (this.entries.get(entry.key) === entry) this.entries.delete(entry.key);
-	}
-	/** @public @author ddj 2026年10月20号 @param entry Authorized connection. @param action Per-call work retaining original execution identity. @param signal Caller cancellation. @returns Serialized shared result; no direct registry bypass is introduced here. */
-	run(entry, action, signal) {
-		/** @author ddj 2026年10月20号 Checks cancellation and generation again at actual dispatch. */
-		const invoke = async () => {
-			await waitMcp(entry.ready, signal);
-			if (signal?.aborted || !entry.live || entry.phase !== "ready") throw new Error("MCP 连接不可用或调用已取消");
-			return action();
-		};
-		const result = entry.calls.then(invoke);
-		entry.calls = result.catch(() => void 0);
-		return result;
-	}
-	/** @public @author ddj 2026年10月20号 @returns Full disposal of entries, queue, timers and owned work. */
-	async dispose() {
-		this.stopped = true;
-		await Promise.all([...this.entries.values()].map((entry) => this.retire(entry)));
-		await Promise.all([...this.jobs]);
-	}
-};
-//#endregion
-//#region src/mcpDiscover.ts
-/** @public @author ddj 2026年10月20号 @param runtime Authorized runtime. @param ctx Host registration context. @returns Global discovery cleanup; normal capability filters remain authoritative. */
-function installDiscover(runtime, ctx) {
-	const tools = ctx.get("tools");
-	/** @author ddj 2026年10月20号 @param args Validated operation. @param execution Registry-owned caller identity. @returns Safe capability catalogue or real connected schemas. */
-	const execute = async (args, execution) => {
-		const agent = execution.agent;
-		if (!agent || !runtime.agents.has(agent)) throw new Error("会话未激活，不能使用项目 MCP 发现入口");
-		if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some((key) => !["action", "serverName"].includes(key))) throw new Error("发现入口仅接受 action 和 serverName");
-		if (!["list", "connect"].includes(args.action)) throw new Error("action 必须为 list 或 connect");
-		if (args.action === "list") return runtime.catalogue(agent);
-		if (typeof args.serverName !== "string") throw new Error("请指定已配置的 serverName");
-		return runtime.connect(agent, args.serverName, execution.signal);
-	};
-	/** @author ddj 2026年10月20号 @param _args Unused. @param result Safe canonical JSON. @returns Native content without bypassing output validation. */
-	const render = (_args, result) => [{
-		type: "text",
-		text: JSON.stringify(result)
-	}];
-	return tools.register({
-		name: "discover_project_mcp",
-		description: "List this workspace’s configured project MCP services without starting them, or connect one to discover its real tools. After connecting, call discovered tools in the NEXT request/program; never guess schemas. Global/preset MCPs are not included.",
-		parameters: {
-			type: "object",
-			properties: {
-				action: {
-					type: "string",
-					enum: ["list", "connect"]
-				},
-				serverName: { type: "string" }
-			},
-			required: ["action"],
-			additionalProperties: false
-		},
-		output: {
-			schema: {},
-			render
-		},
-		execute
-	});
-}
-/** @public @author ddj 2026年10月20号 @param runtime Active owners. @param agent Scoped catalogue owner. @returns Scoped instruction cleanup; does not register a tool override. */
-function discoverPrompt(runtime, agent) {
-	const prompt = agent.ctx.get("systemPrompt");
-	/** @author ddj 2026年10月20号 @returns Current enabled names only; no credential-bearing configuration. */
-	const text = () => {
-		const names = runtime.catalogue(agent).map((server) => server.serverName);
-		if (!names.length) return "";
-		return "Project MCP capabilities (may not be started): " + JSON.stringify(names) + ". Use discover_project_mcp action=list, then action=connect with serverName when needed. Only use returned real tool schemas. Native tools appear on the next model request; PTC must finish the current program and start a new program to refresh its SDK. Do not eval or bypass tool approval.";
-	};
-	return prompt.section({
-		name: "vscode-mode:project-mcp",
-		order: 3090,
-		text,
-		interpolate: false
-	});
-}
-//#endregion
-//#region src/shared/diff.ts
-/** 统一取对应 hunk；callHunk 只用于旧记录缺失 hunks 时兼容。 */
-function preciseHunk(record, idx) {
-	return hunkOf(record, idx);
-}
-/** 轻量、确定性的字符串指纹；不引入 Node crypto。 */
-function fingerprint(text) {
-	if (typeof text !== "string") return null;
-	let hash = 2166136261;
-	for (let i = 0; i < text.length; i++) {
-		hash ^= text.charCodeAt(i);
-		hash = Math.imul(hash, 16777619);
-	}
-	return "fnv1a:" + (hash >>> 0).toString(16) + ":" + text.length;
-}
-/** 取记录第 idx 个有效 hunk；只有记录缺 hunk 时才回退 callHunk。 */
-function hunkOf(record, idx) {
-	const hunk = Array.isArray(record.hunks) ? record.hunks[idx] : void 0;
-	if (hunk && typeof hunk.newText === "string") return hunk;
-	if (idx === 0 && record.callHunk && typeof record.callHunk.newText === "string") return record.callHunk;
-	return null;
-}
-/** hunk 是否表示没有实际内容变化。 */
-function isNoopHunk(hunk) {
-	return !!hunk && hunk.oldText !== null && hunk.oldText === hunk.newText;
-}
-/**
-* 差异比较口径归一化：剥离 UTF-8 BOM、统一 CRLF 为 LF。
-* 背景：外部工具（pwsh/编辑器）可能改变 BOM/行尾，导致 after 指纹与 hunk
-* 定位在内容语义未变的情况下误报 conflict，把待确认修改从 UI 排除。
-* @author ddj 2026年09月09号
-*/
-function normalizeForCompare(text) {
-	return text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
-}
-/** 归一化一个 hunk 的两侧文本（与 normalizeForCompare 同口径）。 */
-function normalizeHunk(hunk) {
-	return {
-		oldText: hunk.oldText === null ? null : normalizeForCompare(hunk.oldText),
-		newText: normalizeForCompare(hunk.newText)
-	};
-}
-/** 按文件顺序为多 hunk 写入不重复的 after 坐标。 */
-function annotateHunks(hunks, before, after) {
-	if (typeof after !== "string") return hunks;
-	let cursor = 0;
-	return hunks.map((hunk) => {
-		if (hunk.newText.length > 0) {
-			const start = after.indexOf(hunk.newText, cursor);
-			if (start >= 0) {
-				cursor = start + hunk.newText.length;
-				return {
-					...hunk,
-					afterStart: start,
-					afterEnd: cursor
-				};
-			}
-			return hunk;
-		}
-		if (hunks.length !== 1 || typeof before !== "string" || before === after || hunk.oldText === null) return hunk;
-		const prefix = commonPrefix(before, after);
-		const suffix = commonSuffix(before, after, prefix);
-		const removedStart = prefix;
-		const removedEnd = Math.max(removedStart, before.length - suffix);
-		return {
-			...hunk,
-			afterStart: removedStart,
-			afterEnd: removedStart,
-			beforeStart: removedStart,
-			beforeEnd: removedEnd
-		};
-	});
-}
-/** 计算两个文本的最长公共前缀长度。 */
-function commonPrefix(left, right) {
-	const limit = Math.min(left.length, right.length);
-	let i = 0;
-	while (i < limit && left.charCodeAt(i) === right.charCodeAt(i)) i++;
-	return i;
-}
-/** 计算不与 prefix 重叠的最长公共后缀长度。 */
-function commonSuffix(left, right, prefix) {
-	const limit = Math.min(left.length, right.length) - prefix;
-	let i = 0;
-	while (i < limit && left.charCodeAt(left.length - 1 - i) === right.charCodeAt(right.length - 1 - i)) i++;
-	return i;
-}
+//#region src/shared/rpc.ts
+/** webServer 精确路由。 */
+const RPC_PATH = "/edrv/rpc";
 /**
-* 懒扫描候选：先找 cursor 后未占用项，找不到再回退至首个未占用项。
-* @author ddj 2026年09月29号
-* @param content 当前内容
-* @param needle 搜索串
-* @param cursor 前一块的结束位置
-* @param occupied 已选区间
-* @param state 此搜索串已扫描的候选
-* @returns 与完整候选列表双轮查找相同的匹配
+* 图片扩展名（小写、无点）→ MIME。edrv.read base64 响应与 client 图片预览共用，
+* 收敛在此避免 host/client 两处漂移。
+* @author ddj 2026年09月08号
 */
-function findCandidate(content, needle, cursor, occupied, state) {
-	if (!needle.length) return void 0;
-	let fallback;
-	for (let i = 0; i < state.ranges.length; i++) {
-		const range = state.ranges[i];
-		if (occupied.some((used) => overlaps(range, used))) continue;
-		if (range.start >= cursor) return range;
-		if (!fallback) fallback = range;
-	}
-	while (!state.done) {
-		const at = content.indexOf(needle, state.next);
-		if (at < 0) {
-			state.done = true;
-			break;
-		}
-		const range = {
-			start: at,
-			end: at + needle.length
-		};
-		state.ranges.push(range);
-		state.next = range.end;
-		if (occupied.some((used) => overlaps(range, used))) continue;
-		if (range.start >= cursor) return range;
-		if (!fallback) fallback = range;
-	}
-	return fallback;
-}
+const IMAGE_MIME = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	bmp: "image/bmp",
+	ico: "image/x-icon",
+	avif: "image/avif",
+	svg: "image/svg+xml"
+};
 /**
-* 从 after 快照定位所有 hunk，按 hunk 顺序优先选未占用且靠近前一块的候选。
-* 若 hunk 带 afterStart/afterEnd，则优先验证快照坐标，避免重复文本错配。
-* @author ddj 2026年08月24号
-* @param content 当前文件内容
-* @param hunks 待定位 hunk
-* @returns 每个 hunk 一个结果，matched=false 表示冲突/stale
+* 路径 → 图片 MIME：按 basename 扩展名小写查 {@link IMAGE_MIME}，未命中回退 application/octet-stream。
+* @author ddj 2026年09月08号
+* @param path 文件路径（`/` 或 `\` 分隔均可）
+* @returns MIME 字符串
 */
-function locateHunks(content, hunks) {
-	const locations = [];
-	let cursor = 0;
-	const occupied = [];
-	const matches = /* @__PURE__ */ new Map();
-	for (let idx = 0; idx < hunks.length; idx++) {
-		const hunk = hunks[idx];
-		const newText = hunk.newText;
-		const snapshot = Number.isInteger(hunk.afterStart) && Number.isInteger(hunk.afterEnd) ? {
-			start: hunk.afterStart,
-			end: hunk.afterEnd
-		} : null;
-		const snapshotMatches = snapshot && snapshot.start >= 0 && snapshot.end >= snapshot.start && (newText.length === 0 || content.slice(snapshot.start, snapshot.end) === newText) ? snapshot : null;
-		let candidate;
-		if (snapshotMatches) {
-			if (!occupied.some((used) => overlaps(snapshotMatches, used))) candidate = snapshotMatches;
-		} else if (newText.length) {
-			let state = matches.get(newText);
-			if (!state) {
-				state = {
-					ranges: [],
-					next: 0,
-					done: false
-				};
-				matches.set(newText, state);
-			}
-			candidate = findCandidate(content, newText, cursor, occupied, state);
-		}
-		if (candidate) {
-			locations.push({
-				idx,
-				hunk,
-				...candidate,
-				matched: true
-			});
-			occupied.push(candidate);
-			cursor = Math.max(cursor, candidate.end);
-			continue;
-		}
-		if (newText.length === 0 && hunk.afterStart === void 0 && hunk.afterEnd === void 0 && content.length === 0) {
-			locations.push({
-				idx,
-				hunk,
-				start: 0,
-				end: 0,
-				matched: true
-			});
-			continue;
-		}
-		if (newText.length === 0 && hunk.afterStart !== void 0 && hunk.afterEnd !== void 0 && hunk.afterStart === hunk.afterEnd && hunk.afterStart >= 0 && hunk.afterStart <= content.length) {
-			const point = {
-				start: hunk.afterStart,
-				end: hunk.afterEnd
-			};
-			if (!occupied.some((used) => overlaps(point, used))) {
-				locations.push({
-					idx,
-					hunk,
-					...point,
-					matched: true
-				});
-				occupied.push(point);
-				cursor = Math.max(cursor, point.end);
-				continue;
-			}
-		}
-		locations.push({
-			idx,
-			hunk,
-			start: -1,
-			end: -1,
-			matched: false
-		});
-	}
-	return locations;
-}
-/** 判断两个半开区间是否重叠。零长度区间只与同一位置的零长度区间重叠。 */
-function overlaps(left, right) {
-	if (left.start === left.end || right.start === right.end) return left.start === right.start && left.end === right.end;
-	return left.start < right.end && right.start < left.end;
+function imageMimeOf(path) {
+	const base = String(path || "").split(/[\\/]/).pop() || "";
+	const dot = base.lastIndexOf(".");
+	const ext = dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+	return IMAGE_MIME[ext] ?? "application/octet-stream";
 }
-/** 在可定位区间上执行一次 hunk 反向替换。 */
-function replaceRange(content, location, reverse = false) {
-	if (!location.matched || location.start < 0) return null;
-	const replacement = reverse ? location.hunk.oldText ?? "" : location.hunk.newText;
-	return content.slice(0, location.start) + replacement + content.slice(location.end);
+/** PDF 统一 MIME（host base64 响应与 client PDF 面板同源，避免两处漂移）。 */
+const PDF_MIME = "application/pdf";
+/**
+* 会话级前置错误的规范文案：host requireSession 系与 client 错误识别共用同一常量，
+* 避免文案漂移导致 client 端分类失效。跨端场景（桌面端/Web 端各自运行独立 DSH 实例、
+* 会话列表互通但会话仅在一端激活）下，本端 host 取不到会话即返回「会话不存在」。
+* @author ddj 2026年10月16号
+*/
+const SESSION_MISSING_ERROR = "会话不存在";
+/** 会话存在但无工作区 cwd 时的规范文案（与 SESSION_MISSING_ERROR 同源共用）。 */
+const SESSION_NO_WORKSPACE_ERROR = "会话无工作区";
+/**
+* 路径 → 二进制预览 MIME：PDF 特判 {@link PDF_MIME}，其余走图片表回退 octet-stream。
+* @author ddj 2026年09月22号
+* @param path 文件路径（`/` 或 `\` 分隔均可）
+* @returns MIME 字符串
+*/
+function binaryMimeOf(path) {
+	const base = String(path || "").split(/[\\/]/).pop() || "";
+	const dot = base.lastIndexOf(".");
+	if (dot > 0 && base.slice(dot + 1).toLowerCase() === "pdf") return PDF_MIME;
+	return imageMimeOf(path);
 }
+//#endregion
+//#region src/paths.ts
 /**
-* 按位置倒序收集片段，最后一次拼接；非互斥区间退回原替换语义。
-* @author ddj 2026年09月29号
-* @param content 当前文件内容
-* @param locations 已定位区间
-* @param reverse 是否反向应用
-* @returns 合成内容及失效块索引
+* dsh-vscode-mode host — 路径常量与动态路径统一出口（PathConst）。
+* 所有 host 侧文件路径/缓存键/路由前缀从这里取，避免散落内联：
+* - 静态：插件缓存根（~/.dsh/dsh-vscode-mode/cache，下分 workspace/ 工作区级与
+*   user/ 用户级）、日志根、工作区侧车名、路由前缀、静态资源目录（import.meta.url 派生）
+* - 动态：每工作区树缓存文件（workspace/<id>/tree.v<schema>.json）、home 解析
+*   （DSH_HOME → ~/.dsh）
+* - 清理：缓存 sweep（分级：工作区级按版本/TTL/空目录、用户级按版本/保留期、根级残留）
+* 纯函数可单测；raw fs 写入与引擎自身插件（settings-file 用 node:fs + DSH_HOME）一致。
+* 作者 ddj 2026-09-01
 */
-function applyLocations(content, locations, reverse = false) {
-	const stale = locations.filter((location) => !location.matched).map((location) => location.idx);
-	const matched = locations.filter((location) => location.matched).sort((a, b) => b.start - a.start);
-	const parts = [];
-	let end = content.length;
-	for (const location of matched) {
-		if (location.start < 0 || location.end > end) {
-			let out = content;
-			for (const item of matched) {
-				const next = replaceRange(out, item, reverse);
-				if (next === null) stale.push(item.idx);
-				else out = next;
-			}
-			return {
-				content: out,
-				stale: stale.sort((a, b) => a - b)
-			};
-		}
-		parts.push(content.slice(location.end, end), reverse ? location.hunk.oldText ?? "" : location.hunk.newText);
-		end = location.start;
-	}
-	parts.push(content.slice(0, end));
-	parts.reverse();
-	return {
-		content: parts.join(""),
-		stale: stale.sort((a, b) => a - b)
-	};
+/** 插件 id（也是 .dsh 下插件工作区目录名）。 */
+const PLUGIN_ID = "dsh-vscode-mode";
+/** DSH 工作区目录名（默认 home 下）。 */
+const DSH_DIR_NAME = ".dsh";
+/** home 覆盖环境变量（与引擎 resolveDshHome 一致）。 */
+const DSH_HOME_ENV = "DSH_HOME";
+/** 插件缓存目录总预算：超限按 mtime 从旧到新删文件，防任意增长撑爆磁盘（最后兜底）。 */
+const CACHE_TOTAL_CAP = 209715200;
+/** 工作区根侧车：审查记录（用户数据，随项目走，不迁移）。 */
+const SIDECAR = ".dsh-edit-review.json";
+/** 旧 debug 日志文件名（工作区，迁移后由插件清理）。 */
+const DEBUG_LOG = ".dsh-edit-review-debug.log";
+/** 旧树缓存 sidecar 名（工作区，迁移后由插件清理；缓存可重建，删除无损）。 */
+const LEGACY_TREE_SIDECARS = [".dsh-edit-review-tree.json", ".dsh-vscode-mode-tree.json"];
+/** 路由前缀（兼容性检查用）。 */
+const ROUTE_PREFIX = "/edrv";
+/** Monaco 静态资源前缀。 */
+const VENDOR_PREFIX = "/edrv/vendor";
+/** 稳定短哈希（cwd → 缓存文件名段；sha1 截断，跨运行稳定）。 */
+function hashOf(text) {
+	return createHash("sha1").update(String(text)).digest("hex").slice(0, 16);
 }
 /**
-* 写决策到记录（scope=call 整体 / hunk 单个块）。
-* @author ddj 2026年08月20号
-* @param record 记录
-* @param scope 作用域
-* @param idx hunk 下标（仅 scope=hunk 时生效）
-* @param value 决策值
-* @returns 更新后的记录（原对象就地修改）
+* 可读安全路径段编码：非安全码位 → ~XXXX 大写十六进制（`~` 本身也转义）。
+* 与 DSH 引擎 dsh-session-persistence-jsonl 的 encodeSegment 逐字节一致，
+* 用于从 cwd/id 反推 `~/.dsh/sessions` 下的会话目录，纯函数可单测。
+* @author ddj 2026年09月02号
+* @param raw 原始路径段（非空）
+* @returns 路径安全段（`.`/`..` 特判为 ~002E / ~002E~002E）
 */
-function markDecision(record, scope, idx, value) {
-	const dec = record.decisions;
-	if (scope === "hunk" && Array.isArray(dec.perHunk) && Number.isInteger(idx)) {
-		const i = idx;
-		if (i >= 0 && i < dec.perHunk.length) dec.perHunk[i] = value;
-	} else {
-		dec.call = value;
-		if (Array.isArray(dec.perHunk)) dec.perHunk = dec.perHunk.map(() => value);
-	}
-	record.at = (/* @__PURE__ */ new Date()).toISOString();
-	return record;
-}
-/** 记录是否已无任何待决策差异（superseded 或全部已决策）。 */
-function recordResolved(record) {
-	if (record.superseded === true) return true;
-	const hunks = Array.isArray(record.hunks) ? record.hunks : [];
-	const perHunk = Array.isArray(record.decisions.perHunk) ? record.decisions.perHunk : [];
-	const count = Math.max(hunks.length, perHunk.length);
-	if (!count) return record.decisions.call === "accepted" || record.decisions.call === "rejected";
-	for (let idx = 0; idx < count; idx++) {
-		const precise = preciseHunk(record, idx);
-		const value = perHunk[idx] ?? record.decisions.call;
-		if (isNoopHunk(precise) && value === "pending") return false;
-		if (value !== "accepted" && value !== "rejected") return false;
+function encodeSegment(raw) {
+	if (raw.length === 0) throw new Error("cannot encode an empty path segment");
+	if (raw === ".") return "~002E";
+	if (raw === "..") return "~002E~002E";
+	let out = "";
+	for (let i = 0; i < raw.length; i++) {
+		const code = raw.charCodeAt(i);
+		const ch = String.fromCharCode(code);
+		if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) out += ch;
+		else out += "~" + code.toString(16).toUpperCase().padStart(4, "0");
 	}
-	return true;
+	return out;
 }
 /**
-* 记录决策摘要（采纳/拒绝/待处理计数，superseded 标记）。
-* @author ddj 2026年08月20号
-* @param record 记录
-* @returns 摘要
+* DSH 工作区目录键：cwd → `--<可读键>--`。分隔符（/ \ :）折叠为单个 `-`，
+* 其余非安全码位转 ~XXXX，`--` 包裹、251 截断。与引擎 projectKey 一致。
+* @author ddj 2026年09月02号
+* @param cwd 会话工作区绝对路径（非空）
+* @returns `~/.dsh/sessions` 下的工作区目录名
 */
-function recSummary(record) {
-	const hunks = Array.isArray(record.hunks) ? record.hunks : [];
-	const perHunk = Array.isArray(record.decisions.perHunk) ? record.decisions.perHunk : [];
-	const n = Math.max(1, hunks.length, perHunk.length);
-	let accepted = 0;
-	let rejected = 0;
-	let pending = 0;
-	for (let i = 0; i < n; i++) {
-		const hunk = preciseHunk(record, i);
-		const value = perHunk[i] ?? record.decisions.call;
-		if (i < hunks.length && isNoopHunk(hunk) && value === "pending") continue;
-		if (value === "accepted") accepted++;
-		else if (value === "rejected") rejected++;
-		else pending++;
+function sessionWorkspaceKey(cwd) {
+	if (cwd.length === 0) throw new Error("cannot encode an empty project path");
+	let readable = "";
+	let separatorRun = false;
+	for (let i = 0; i < cwd.length; i++) {
+		const code = cwd.charCodeAt(i);
+		const ch = String.fromCharCode(code);
+		if (ch === "/" || ch === "\\" || ch === ":") {
+			if (!separatorRun) readable += "-";
+			separatorRun = true;
+		} else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) {
+			readable += ch;
+			separatorRun = false;
+		} else {
+			readable += "~" + code.toString(16).toUpperCase().padStart(4, "0");
+			separatorRun = false;
+		}
 	}
-	return {
-		accepted,
-		rejected,
-		pending,
-		superseded: record.superseded === true
-	};
+	return `--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--`;
+}
+/** DSH 会话目录段：id → 路径安全段（与引擎 encodeSegment 一致）。 */
+function sessionIdSegment(id) {
+	return encodeSegment(id);
+}
+/** DSH 会话根目录（~/.dsh/sessions；引擎 dsh-base 默认 root）。 */
+function sessionsRoot(home = dshHome()) {
+	return join(home, "sessions");
 }
 /**
-* 重建"本批次修改前"内容：把仍待处理（pending）的差异块按 新→旧 顺序从当前内容反解
-* （newText → oldText）。已采纳/已拒绝的块跳过。反解失败的块标记为 stale。
-* @author ddj 2026年08月20号
-* @param records 该文件的活动记录
-* @param content 当前磁盘内容
-* @returns 重建内容与 stale 定位
+* 解析 DSH home：空白环境值视为未设置，展开 ~ 并解析绝对路径。
+* @public
+* @author ddj 2026年09月28号
+* @param env 环境映射（缺省 process.env；测试可注入）
+* @returns 归一化的 DSH home 绝对路径
 */
-function reconstructOriginal(records, content) {
-	const pending = [];
-	for (const rec of records) for (let i = 0; i < rec.hunks.length; i++) {
-		const st = rec.decisions.perHunk[i] ?? rec.decisions.call;
-		const hunk = preciseHunk(rec, i);
-		if (st === "pending" && hunk && !isNoopHunk(hunk)) pending.push({
-			rec,
-			idx: i,
-			hunk
-		});
-	}
-	pending.sort((a, b) => a.rec.at < b.rec.at ? 1 : a.rec.at > b.rec.at ? -1 : 0);
-	const rebuilt = applyLocations(content, locateHunks(content, pending.map((item) => item.hunk)), true);
-	return {
-		content: rebuilt.content,
-		stale: rebuilt.stale.map((idx) => ({
-			callId: pending[idx].rec.callId,
-			idx: pending[idx].idx
-		}))
-	};
+function dshHome(env = process.env) {
+	const value = env[DSH_HOME_ENV];
+	const path = value && value.trim() ? value : join(homedir(), DSH_DIR_NAME);
+	if (path === "~") return resolve(homedir());
+	if (path.startsWith("~/") || path.startsWith("~\\")) return resolve(join(homedir(), path.slice(2)));
+	return resolve(path);
+}
+/** 插件缓存根（~/.dsh/dsh-vscode-mode/cache，下分 workspace/ 与 user/ 两级）。 */
+function pluginCacheRoot(home = dshHome()) {
+	return join(home, PLUGIN_ID, "cache");
+}
+/** 工作区级缓存目录：按工作区 id（cwd hash）隔离，换工作区即失效。 */
+function workspaceCacheDir(workspaceId, home = dshHome()) {
+	return join(pluginCacheRoot(home), "workspace", workspaceId);
+}
+/** 用户级缓存目录（跨工作区共享；当前无实例，预留供全局偏好类缓存使用）。 */
+function userCacheDir(home = dshHome()) {
+	return join(pluginCacheRoot(home), "user");
+}
+/** LSP provider 发现结果缓存文件（用户级：user/lsp-specs.v<schema>.json，跨会话/跨重启共享）。 */
+function lspSpecCacheFile(home = dshHome(), schema = 4) {
+	return join(userCacheDir(home), "lsp-specs.v" + schema + ".json");
+}
+/** 插件日志根（~/.dsh/dsh-vscode-mode/logs，用户级）。 */
+function pluginLogRoot(home = dshHome()) {
+	return join(home, PLUGIN_ID, "logs");
+}
+/** 每工作区树缓存文件（工作区级：workspace/<id>/tree.v<schema>.json，文件名含版本便于 sweep）。 */
+function treeCacheFile(cwd, home = dshHome(), schema = 1) {
+	return join(workspaceCacheDir(hashOf(cwd), home), "tree.v" + schema + ".json");
 }
 /**
-* @public
-* @author ddj 2026年10月10号
-* 判断记录是否完全未决策；缺少逐块状态时沿用 pending 的 call 状态。
-* @param record 审查记录
-* @returns 未归档、未覆盖且没有用户决策时为 true
+* 每工作区 UI 状态镜像文件（工作区级：workspace/<id>/ui.v<schema>.json）。
+* 存编辑器页签/侧栏/预览态等界面状态的 localStorage 原值副本，供换 origin 后回填。
+* @author ddj 2026年09月28号
+* @param cwd 工作区绝对路径
+* @param home DSH home（测试可注入）
+* @param schema schema 版本（缺省 UI_STATE_SCHEMA）
+* @returns UI 状态镜像文件绝对路径
 */
-function fullyPending(record) {
-	return !record.archived && !record.superseded && record.decisions.call === "pending" && record.decisions.perHunk.every((value) => value === "pending");
+function uiStateFile(cwd, home = dshHome(), schema = 1) {
+	return join(workspaceCacheDir(hashOf(cwd), home), "ui.v" + schema + ".json");
 }
 /**
-* @public
-* @author ddj 2026年10月10号
-* 比较整组 hunk 是否逐块精确逆反；不把新建或纯 no-op 当作抵消。
-* @param prior 先前修改的差异块
-* @param later 后续修改的差异块
-* @returns 文本归一化后整组逆反且包含真实修改时为 true
+* 用户级 UI 状态镜像文件（跨工作区共享：user/ui-globals.v<schema>.json）。
+* 存与工作区无关的全局键（侧栏提示已忽略、工作区折叠态等）。
+* @author ddj 2026年09月28号
+* @param home DSH home（测试可注入）
+* @param schema schema 版本（缺省 UI_STATE_SCHEMA）
+* @returns 全局 UI 状态镜像文件绝对路径
 */
-function hunksInverse(prior, later) {
-	if (!prior.length || prior.length !== later.length) return false;
-	let changed = false;
-	for (let idx = 0; idx < prior.length; idx++) {
-		const a = normalizeHunk(prior[idx]);
-		const b = normalizeHunk(later[idx]);
-		if (a.oldText !== b.newText || a.newText !== b.oldText) return false;
-		if (!isNoopHunk(a)) changed = true;
-	}
-	return changed;
+function uiGlobalsFile(home = dshHome(), schema = 1) {
+	return join(userCacheDir(home), "ui-globals.v" + schema + ".json");
+}
+/** 每工作区 debug 日志文件（用户级日志根下，按 cwd hash 隔离）。 */
+function debugLogFile(cwd, home = dshHome()) {
+	return join(pluginLogRoot(home), "debug." + hashOf(cwd) + ".log");
 }
 /**
-* @private
-* @author ddj 2026年10月10号
-* 同路径优先按捕获批次排序；旧记录仅使用有效时间，不拿 callId 伪造先后证据。
-* @param a 第一条记录
-* @param b 第二条记录
-* @returns 负数表示 a 更早，零表示先后无法区分
+* 每工作区归档数据库（用户数据，不受缓存清理预算约束）。
+* @author ddj 2026年09月30号
+* @param cwd 工作区绝对路径
+* @param home DSH home
+* @returns 归档数据库绝对路径
 */
-function recordOrder(a, b) {
-	if (a.path !== b.path) return a.path.localeCompare(b.path);
-	if (Number.isInteger(a.batch) && Number.isInteger(b.batch) && a.batch > 0 && b.batch > 0 && a.batch !== b.batch) return a.batch - b.batch;
-	const delta = Date.parse(a.at) - Date.parse(b.at);
-	return Number.isFinite(delta) ? delta : 0;
+function archiveDbFile(cwd, home = dshHome()) {
+	return join(home, PLUGIN_ID, "data", "archive", hashOf(cwd) + ".sqlite");
+}
+/** 插件包 assets 目录（import.meta.url 派生；config.imageDir 可覆盖，见 imageDirOf）。 */
+function assetsDirOf(moduleUrl) {
+	return join(dirname(fileURLToPath(moduleUrl)), "..", "assets");
+}
+/** Monaco AMD 静态目录（随包发布）。 */
+function vendorDirOf(moduleUrl) {
+	return join(assetsDirOf(moduleUrl), "vendor");
 }
 /**
-* @private
-* @author ddj 2026年10月10号
-* 确认完整文件快照往返，防止相同文本在不同位置的反向修改被误隐藏。
-* @param prior 先前记录
-* @param later 后续记录
-* @returns 两端快照互换且文件存在性未变化时为 true；缺少证据时保留审查
+* 插件自带技能组根目录（包根 skills/，与 assets/ 同级；随包发布）。
+* 布局：<根>/<技能名>/SKILL.md（目录式）或 <根>/<技能名>.md（扁平式）。
+* @author ddj 2026年09月11号
+* @param moduleUrl 模块 URL（缺省 import.meta.url；测试注入）
+* @returns 技能组根目录绝对路径
 */
-function snapshotsRestore(prior, later) {
-	if (prior.create || later.create) return false;
-	if (typeof prior.before !== "string" || typeof prior.after !== "string" || typeof later.before !== "string" || typeof later.after !== "string") return false;
-	return normalizeForCompare(prior.before) === normalizeForCompare(later.after) && normalizeForCompare(prior.after) === normalizeForCompare(later.before);
+function skillsDirOf(moduleUrl) {
+	return join(dirname(fileURLToPath(moduleUrl)), "..", "skills");
+}
+/** 图标目录：config.imageDir 覆盖优先，否则插件包 assets/。 */
+function imageDirOf(config, moduleUrl) {
+	const cfg = config;
+	if (cfg && typeof cfg.imageDir === "string" && cfg.imageDir) return cfg.imageDir.replace(/\\/g, "/");
+	return assetsDirOf(moduleUrl);
 }
 /**
-* @public
-* @author ddj 2026年10月10号
-* 查找最近一条未决的整记录逆反；必须有文件快照证明原内容确实恢复。
-* @param records 工作区记录（不修改输入）
-* @param record 新记录
-* @returns 可安全配对的先前记录，证据不足或部分撤销时为 null
+* 已知缓存文件种类 → 当前 schema 版本（sweep 判旧依据）。
+* 新增缓存文件必须登记在此，否则被当作未知残留清理。
 */
-function findInversePrior(records, record) {
-	if (!fullyPending(record)) return null;
-	let found = null;
-	for (const prior of records) {
-		if (prior.callId === record.callId || prior.path !== record.path || !fullyPending(prior)) continue;
-		if (recordOrder(prior, record) >= 0 || !hunksInverse(prior.hunks, record.hunks)) continue;
-		if (!snapshotsRestore(prior, record)) continue;
-		if (!found || recordOrder(found, prior) < 0) found = prior;
-	}
-	return found;
+const CACHE_SCHEMAS = {
+	tree: 1,
+	"lsp-specs": 4,
+	ui: 1,
+	"ui-globals": 1
+};
+/** 缓存文件名 → 种类与 schema 版本（`<kind>.v<schema>.json`；未登记种类/命名不合规 → null）。 */
+function parseCacheName(filename) {
+	const m = /^([a-z-]+)\.v(\d+)\.json$/.exec(filename);
+	if (!m) return null;
+	const kind = m[1];
+	if (CACHE_SCHEMAS[kind] === void 0) return null;
+	return {
+		kind,
+		schema: Number(m[2])
+	};
 }
 /**
-* @public
-* @author ddj 2026年10月10号
-* 按捕获顺序贪心配对历史抵消记录，每条最多使用一次；桶上限为 200。
-* @param records 工作区记录（不修改输入或记录状态）
-* @returns 可以整对归档的记录对
+* 该缓存文件名是否为已登记种类的当前 schema 版本（sweep 判旧/判残留依据）。
+* @author ddj 2026年09月28号
+* @param filename 缓存文件名（不含目录）
+* @returns 已登记种类且版本为当前版本
 */
-function findCanceledPairs(records) {
-	const available = [];
-	const pairs = [];
-	const ordered = [...records].sort(recordOrder);
-	for (const record of ordered) {
-		const prior = findInversePrior(available, record);
-		if (!prior) {
-			if (fullyPending(record)) available.push(record);
-			continue;
+function isCurrentCacheFile(filename) {
+	const parsed = parseCacheName(filename);
+	return parsed !== null && parsed.schema === CACHE_SCHEMAS[parsed.kind];
+}
+/** 按「schema 版本 + 保留期」清扫某目录内文件（目录级，返回相对路径清单）。 */
+async function sweepDirFiles(dir, removed, now, dropAll) {
+	const names = await readdir(dir).catch(() => []);
+	for (const name of names) {
+		const full = join(dir, name);
+		let drop = dropAll;
+		if (!drop) {
+			if (!isCurrentCacheFile(name)) drop = true;
+			else try {
+				if (now - (await stat(full)).mtimeMs > 2592e6) drop = true;
+			} catch (error) {
+				drop = true;
+			}
 		}
-		pairs.push([prior, record]);
-		available.splice(available.indexOf(prior), 1);
+		if (!drop) continue;
+		try {
+			await rm(full, { force: true });
+			removed.push(name);
+		} catch (error) {}
 	}
-	return pairs;
 }
-/** 文件当前最大批次号（无记录为 0）。 */
-function fileMaxBatch(records, path) {
-	let m = 0;
-	for (const r of records.values()) if (r.path === path && Number.isInteger(r.batch) && r.batch > m) m = r.batch;
-	return m;
+/** 清扫工作区级缓存：逐工作区目录按版本/TTL 清文件，空目录删除。 */
+async function sweepWorkspaceTier(dir, removed, now) {
+	const ids = await readdir(dir).catch(() => []);
+	for (const id of ids) {
+		const wsDir = join(dir, id);
+		await sweepDirFiles(wsDir, removed, now, false);
+		if (!(await readdir(wsDir).catch(() => [])).length) await rm(wsDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
 }
-/** @public @author ddj 2026年10月26号 @param map Legacy records. @param max Cache target, never a pending retention limit. */
-function prune(map, max = 200) {
-	if (map.size <= max) return;
-	const sorted = [...map.values()].filter((record) => record.archived && recordResolved(record)).sort((a, b) => a.at < b.at ? -1 : 1);
-	for (const record of sorted) {
-		if (map.size <= max) break;
-		map.delete(record.callId);
+/** 总预算兜底：递归收集全部缓存文件，按 mtime 从旧到新删，直到总大小 ≤ 预算。 */
+async function sweepByTotalCap(root, removed, cap) {
+	const files = [];
+	const walk = async (dir) => {
+		const names = await readdir(dir).catch(() => []);
+		for (const name of names) {
+			const full = join(dir, name);
+			try {
+				const info = await stat(full);
+				if (info.isDirectory()) await walk(full);
+				else files.push({
+					path: full,
+					mtime: info.mtimeMs,
+					size: info.size
+				});
+			} catch (error) {}
+		}
+	};
+	await walk(root);
+	let total = files.reduce((sum, f) => sum + f.size, 0);
+	files.sort((a, b) => a.mtime - b.mtime);
+	for (const f of files) {
+		if (total <= cap) break;
+		try {
+			await rm(f.path, { force: true });
+			total -= f.size;
+			removed.push(f.path.slice(root.length + 1));
+		} catch (error) {}
 	}
 }
 /**
-* 归档条目构造（一条批次一条）。
-* @author ddj 2026年08月20号
-* @param recs 同批次记录（非空）
-* @param cwd 工作区
-* @param reason 归档原因
+* 清理插件缓存根（分级 + 总预算兜底）：
+* - 根级残留文件（旧扁平格式/未知）→ 删
+* - workspace/ 工作区级 → 按「schema 版本 + 保留期」清文件，空目录删除
+* - user/ 用户级 → 按「schema 版本 + 保留期」清文件
+* - 总大小超预算 → 按最旧先删（最后防线，防任意增长撑爆磁盘）
+* best-effort 静默。
+* @author ddj 2026年09月01号
+* @param home DSH home（测试可注入）
+* @param cap 总预算字节数（缺省 CACHE_TOTAL_CAP；测试可注入小预算）
+* @returns 删除的文件相对路径清单
 */
-function archiveEntryFor(recs, cwd, reason) {
-	const first = recs[0];
-	return {
-		at: (/* @__PURE__ */ new Date()).toISOString(),
-		cwd,
-		path: first.path,
-		batch: Number.isInteger(first.batch) ? first.batch : null,
-		reason,
-		records: recs.map((r) => ({
-			callId: r.callId,
-			toolName: r.toolName,
-			path: r.path,
-			create: r.create === true,
-			callHunk: r.callHunk,
-			hunks: r.hunks,
-			decisions: r.decisions,
-			note: r.note ?? null,
-			before: typeof r.before === "string" ? r.before : null,
-			after: typeof r.after === "string" ? r.after : null,
-			baseFingerprint: r.baseFingerprint ?? null,
-			afterFingerprint: r.afterFingerprint ?? null,
-			conflict: r.conflict === true,
-			legacy: r.legacy === true,
-			superseded: r.superseded === true,
-			batch: Number.isInteger(r.batch) ? r.batch : null,
-			at: r.at,
-			summary: recSummary(r)
-		}))
-	};
+async function sweepTreeCache(home = dshHome(), cap = CACHE_TOTAL_CAP) {
+	const dir = pluginCacheRoot(home);
+	const names = await readdir(dir).catch(() => []);
+	if (!names.length) return [];
+	const removed = [];
+	const now = Date.now();
+	await Promise.all(names.map(async (name) => {
+		const full = join(dir, name);
+		try {
+			if ((await stat(full)).isDirectory()) {
+				if (name === "workspace") await sweepWorkspaceTier(full, removed, now);
+				else if (name === "user") await sweepDirFiles(full, removed, now, false);
+				else {
+					await rm(full, {
+						recursive: true,
+						force: true
+					});
+					removed.push(name);
+				}
+			} else {
+				await rm(full, { force: true });
+				removed.push(name);
+			}
+		} catch (error) {}
+	}));
+	await sweepByTotalCap(dir, removed, cap);
+	return removed;
 }
 //#endregion
-//#region src/shared/rpc.ts
-/** webServer 精确路由。 */
-const RPC_PATH = "/edrv/rpc";
+//#region src/shared/logger.ts
 /**
-* 图片扩展名（小写、无点）→ MIME。edrv.read base64 响应与 client 图片预览共用，
-* 收敛在此避免 host/client 两处漂移。
-* @author ddj 2026年09月08号
+* dsh-vscode-mode — 统一日志核心（双面共享，平台中立）。
+* 输出规范：
+* - 格式：`[dsh-vscode-mode][:scope] 消息`；前缀只在模块内部拼接，业务代码禁止手写前缀
+* - 级别语义：debug=诊断明细 / info=装配与路由里程碑 / warn=降级与兼容回退 / error=失败
+* - 出口：host 面经 bindHostLog(ctx) 绑定 ctx.logger（缺失回退 console）；client 面固定 console
+* - 诊断文件通道（edrv.debug → ~/.dsh/dsh-vscode-mode/logs/）见 debugLog.ts，与本模块前缀共用
+* 新增日志一律 `import { log } from '../log.js'`（client 为 './log.js'）后调 log.debug/info/warn/error；
+* 子域日志用 log.child('scope')，禁止另起 console。
+* 作者 ddj 2026-09-08
 */
-const IMAGE_MIME = {
-	png: "image/png",
-	jpg: "image/jpeg",
-	jpeg: "image/jpeg",
-	gif: "image/gif",
-	webp: "image/webp",
-	bmp: "image/bmp",
-	ico: "image/x-icon",
-	avif: "image/avif",
-	svg: "image/svg+xml"
+/** 插件统一日志前缀（与包安装名一致）。 */
+const LOG_PREFIX = "[dsh-vscode-mode]";
+/** 默认级别到 console 方法名的映射。 */
+const CONSOLE_METHODS = {
+	debug: "debug",
+	info: "info",
+	warn: "warn",
+	error: "error"
 };
 /**
-* 路径 → 图片 MIME：按 basename 扩展名小写查 {@link IMAGE_MIME}，未命中回退 application/octet-stream。
+* 默认出口：console（级别直映方法；方法缺失时静默丢弃，不抛错）。
+* @author ddj 2026年09月08号
+* @returns console 出口
+*/
+function consoleSink() {
+	return (level, line) => {
+		const emit = console[CONSOLE_METHODS[level]];
+		if (typeof emit === "function") emit.call(console, line);
+	};
+}
+/**
+* DSH host 出口工厂：转接 ctx.logger（方法级可选调用，缺服务/缺方法回退 console）。
+* @author ddj 2026年09月08号
+* @param ctx DSH host 上下文
+* @returns 日志出口
+*/
+function ctxLogSink(ctx) {
+	const base = consoleSink();
+	return (level, line) => {
+		const logger = ctx?.logger;
+		const emit = logger?.[level];
+		if (typeof emit === "function") emit.call(logger, line);
+		else base(level, line);
+	};
+}
+/**
+* 拼一行日志：`[dsh-vscode-mode][:scope] 消息`（scope 为空省略冒号段）。
 * @author ddj 2026年09月08号
-* @param path 文件路径（`/` 或 `\` 分隔均可）
-* @returns MIME 字符串
+* @param scope 子域（可空）
+* @param message 消息文本
+* @returns 整行文本
 */
-function imageMimeOf(path) {
-	const base = String(path || "").split(/[\\/]/).pop() || "";
-	const dot = base.lastIndexOf(".");
-	const ext = dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
-	return IMAGE_MIME[ext] ?? "application/octet-stream";
+function formatLine(scope, message) {
+	const text = String(message);
+	return scope ? LOG_PREFIX + ":" + scope + " " + text : LOG_PREFIX + " " + text;
 }
-/** PDF 统一 MIME（host base64 响应与 client PDF 面板同源，避免两处漂移）。 */
-const PDF_MIME = "application/pdf";
 /**
-* 会话级前置错误的规范文案：host requireSession 系与 client 错误识别共用同一常量，
-* 避免文案漂移导致 client 端分类失效。跨端场景（桌面端/Web 端各自运行独立 DSH 实例、
-* 会话列表互通但会话仅在一端激活）下，本端 host 取不到会话即返回「会话不存在」。
-* @author ddj 2026年10月16号
+* 日志器工厂（内部）：emit 时读共享出口状态，保证父 bind 后子实例跟随。
+* @author ddj 2026年09月08号
+* @param state 共享出口状态
+* @param scope 子域文本（可空）
+* @returns 日志器
 */
-const SESSION_MISSING_ERROR = "会话不存在";
-/** 会话存在但无工作区 cwd 时的规范文案（与 SESSION_MISSING_ERROR 同源共用）。 */
-const SESSION_NO_WORKSPACE_ERROR = "会话无工作区";
+function makeLogger(state, scope) {
+	const emit = (level, message) => state.sink(level, formatLine(scope, message));
+	return {
+		debug: (message) => emit("debug", message),
+		info: (message) => emit("info", message),
+		warn: (message) => emit("warn", message),
+		error: (message) => emit("error", message),
+		bind(next) {
+			state.sink = next;
+		},
+		child(next) {
+			return makeLogger(state, scope ? scope + "." + next : next);
+		}
+	};
+}
 /**
-* 路径 → 二进制预览 MIME：PDF 特判 {@link PDF_MIME}，其余走图片表回退 octet-stream。
-* @author ddj 2026年09月22号
-* @param path 文件路径（`/` 或 `\` 分隔均可）
-* @returns MIME 字符串
+* 创建插件日志器（默认 console 出口；host 面单例由 bindHostLog 换到 ctx.logger）。
+* @author ddj 2026年09月08号
+* @param sink 初始出口（缺省 console）
+* @param scope 初始子域（业务方一般经 child 派生，不直接传）
+* @returns 日志器
 */
-function binaryMimeOf(path) {
-	const base = String(path || "").split(/[\\/]/).pop() || "";
-	const dot = base.lastIndexOf(".");
-	if (dot > 0 && base.slice(dot + 1).toLowerCase() === "pdf") return PDF_MIME;
-	return imageMimeOf(path);
+function createLogger(sink = consoleSink(), scope = "") {
+	return makeLogger({ sink }, scope);
 }
 //#endregion
-//#region src/paths.ts
+//#region src/log.ts
 /**
-* dsh-vscode-mode host — 路径常量与动态路径统一出口（PathConst）。
-* 所有 host 侧文件路径/缓存键/路由前缀从这里取，避免散落内联：
-* - 静态：插件缓存根（~/.dsh/dsh-vscode-mode/cache，下分 workspace/ 工作区级与
-*   user/ 用户级）、日志根、工作区侧车名、路由前缀、静态资源目录（import.meta.url 派生）
-* - 动态：每工作区树缓存文件（workspace/<id>/tree.v<schema>.json）、home 解析
-*   （DSH_HOME → ~/.dsh）
-* - 清理：缓存 sweep（分级：工作区级按版本/TTL/空目录、用户级按版本/保留期、根级残留）
-* 纯函数可单测；raw fs 写入与引擎自身插件（settings-file 用 node:fs + DSH_HOME）一致。
-* 作者 ddj 2026-09-01
+* dsh-vscode-mode host — 日志单例（全 host 面唯一日志入口）。
+* 默认 console 出口；apply() 首行调 bindHostLog(ctx) 切到 ctx.logger（缺失回退 console）。
+* 用法：`import { log } from './log.js'` → `log.debug/info/warn/error(msg)`；子域用 `log.child('scope')`。
+* 作者 ddj 2026-09-08
 */
-/** 插件 id（也是 .dsh 下插件工作区目录名）。 */
-const PLUGIN_ID = "dsh-vscode-mode";
-/** DSH 工作区目录名（默认 home 下）。 */
-const DSH_DIR_NAME = ".dsh";
-/** home 覆盖环境变量（与引擎 resolveDshHome 一致）。 */
-const DSH_HOME_ENV = "DSH_HOME";
-/** 插件缓存目录总预算：超限按 mtime 从旧到新删文件，防任意增长撑爆磁盘（最后兜底）。 */
-const CACHE_TOTAL_CAP = 209715200;
-/** 工作区根侧车：审查记录（用户数据，随项目走，不迁移）。 */
-const SIDECAR = ".dsh-edit-review.json";
-/** 旧 debug 日志文件名（工作区，迁移后由插件清理）。 */
-const DEBUG_LOG = ".dsh-edit-review-debug.log";
-/** 旧树缓存 sidecar 名（工作区，迁移后由插件清理；缓存可重建，删除无损）。 */
-const LEGACY_TREE_SIDECARS = [".dsh-edit-review-tree.json", ".dsh-vscode-mode-tree.json"];
-/** 路由前缀（兼容性检查用）。 */
-const ROUTE_PREFIX = "/edrv";
-/** Monaco 静态资源前缀。 */
-const VENDOR_PREFIX = "/edrv/vendor";
-/** 稳定短哈希（cwd → 缓存文件名段；sha1 截断，跨运行稳定）。 */
-function hashOf(text) {
-	return createHash("sha1").update(String(text)).digest("hex").slice(0, 16);
-}
+/** host 面插件日志单例（格式/级别语义见 shared/logger.ts 头注释）。 */
+const log = createLogger();
 /**
-* 可读安全路径段编码：非安全码位 → ~XXXX 大写十六进制（`~` 本身也转义）。
-* 与 DSH 引擎 dsh-session-persistence-jsonl 的 encodeSegment 逐字节一致，
-* 用于从 cwd/id 反推 `~/.dsh/sessions` 下的会话目录，纯函数可单测。
-* @author ddj 2026年09月02号
-* @param raw 原始路径段（非空）
-* @returns 路径安全段（`.`/`..` 特判为 ~002E / ~002E~002E）
+* 装配期绑定 host 日志出口：ctx.logger 可用时全部日志转经 DSH 日志系统。
+* @author ddj 2026年09月08号
+* @param ctx DSH host 上下文（logger 服务缺失时保持 console 出口）
 */
-function encodeSegment(raw) {
-	if (raw.length === 0) throw new Error("cannot encode an empty path segment");
-	if (raw === ".") return "~002E";
-	if (raw === "..") return "~002E~002E";
-	let out = "";
-	for (let i = 0; i < raw.length; i++) {
-		const code = raw.charCodeAt(i);
-		const ch = String.fromCharCode(code);
-		if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) out += ch;
-		else out += "~" + code.toString(16).toUpperCase().padStart(4, "0");
-	}
-	return out;
+function bindHostLog(ctx) {
+	log.bind(ctxLogSink(ctx));
 }
+//#endregion
+//#region src/debugLog.ts
 /**
-* DSH 工作区目录键：cwd → `--<可读键>--`。分隔符（/ \ :）折叠为单个 `-`，
-* 其余非安全码位转 ~XXXX，`--` 包裹、251 截断。与引擎 projectKey 一致。
-* @author ddj 2026年09月02号
-* @param cwd 会话工作区绝对路径（非空）
-* @returns `~/.dsh/sessions` 下的工作区目录名
+* dsh-vscode-mode host — 诊断文件通道（client 上报 → 缓冲批量落盘）+ 日志文件管理。
+* 通道：edrv.debug RPC → 内存缓冲（满/空闲触发）→ 串行读改写
+*       `~/.dsh/dsh-vscode-mode/logs/debug.<cwdHash>.log`（512KB 上限截断保留尾部）。
+* 设计：console 不一定落盘，文件可靠；写失败静默忽略（调试日志不阻塞业务）。
+* 管理：edrv.dlog.* RPC 用的清单/尾部读取/清空三能力；file 参数一律先过
+*       isDebugLogName 白名单（纯文件名、无路径分隔），杜绝穿越出日志根。
+* 作者 ddj 2026-09-08 / 2026-09-17
 */
-function sessionWorkspaceKey(cwd) {
-	if (cwd.length === 0) throw new Error("cannot encode an empty project path");
-	let readable = "";
-	let separatorRun = false;
-	for (let i = 0; i < cwd.length; i++) {
-		const code = cwd.charCodeAt(i);
-		const ch = String.fromCharCode(code);
-		if (ch === "/" || ch === "\\" || ch === ":") {
-			if (!separatorRun) readable += "-";
-			separatorRun = true;
-		} else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) {
-			readable += ch;
-			separatorRun = false;
-		} else {
-			readable += "~" + code.toString(16).toUpperCase().padStart(4, "0");
-			separatorRun = false;
-		}
-	}
-	return `--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--`;
-}
-/** DSH 会话目录段：id → 路径安全段（与引擎 encodeSegment 一致）。 */
-function sessionIdSegment(id) {
-	return encodeSegment(id);
-}
-/** DSH 会话根目录（~/.dsh/sessions；引擎 dsh-base 默认 root）。 */
-function sessionsRoot(home = dshHome()) {
-	return join(home, "sessions");
-}
+/** cwd → 内存缓冲：行数组 + 累计字节数 + 待触发 flush 定时器（攒批落盘，避免每条日志全文件读改写）。 */
+const debugBuffers = /* @__PURE__ */ new Map();
+/** cwd → Promise 链：串行化 debug 日志落盘（fs read+write 非原子，避免并发丢行）。 */
+const debugWriteQueues = /* @__PURE__ */ new Map();
+/** debug 日志单文件上限：超限截断保留尾部，防文件无限增长拖慢每次追加。 */
+const DEBUG_LOG_CAP = 524288;
+/** debug 日志批量缓冲上限：攒满即落盘（一次读改写），上限内不逐条写文件。 */
+const DEBUG_BUF_CAP = 32768;
+/** debug 日志空闲 flush 延迟：缓冲未满时，静默一段时间后落盘一次。 */
+const DEBUG_FLUSH_IDLE_MS = 1e3;
+/** cwd → 已清理旧工作区 debug 日志标记（一次性）。 */
+const debugLegacyCleaned = /* @__PURE__ */ new Set();
+/** 诊断回显日志器（终端回显统一带 `[dsh-vscode-mode:debug]` 前缀，级别跟随上报级别）。 */
+const debugLog = log.child("debug");
+/** 诊断日志文件名白名单（cwd hash 命名；请求回传的 file 参数必须整名匹配，防路径穿越）。 */
+const DEBUG_LOG_NAME = /^debug\.[0-9a-f]{16}\.log$/;
 /**
-* 解析 DSH home：空白环境值视为未设置，展开 ~ 并解析绝对路径。
-* @public
-* @author ddj 2026年09月28号
-* @param env 环境映射（缺省 process.env；测试可注入）
-* @returns 归一化的 DSH home 绝对路径
+* 文件名是否为合法诊断日志名（白名单整名匹配，杜绝路径穿越）。
+* @author ddj 2026年09月17号
+* @param name 请求回传的文件名（可为空）
+* @returns 是否合法
 */
-function dshHome(env = process.env) {
-	const value = env[DSH_HOME_ENV];
-	const path = value && value.trim() ? value : join(homedir(), DSH_DIR_NAME);
-	if (path === "~") return resolve(homedir());
-	if (path.startsWith("~/") || path.startsWith("~\\")) return resolve(join(homedir(), path.slice(2)));
-	return resolve(path);
-}
-/** 插件缓存根（~/.dsh/dsh-vscode-mode/cache，下分 workspace/ 与 user/ 两级）。 */
-function pluginCacheRoot(home = dshHome()) {
-	return join(home, PLUGIN_ID, "cache");
-}
-/** 工作区级缓存目录：按工作区 id（cwd hash）隔离，换工作区即失效。 */
-function workspaceCacheDir(workspaceId, home = dshHome()) {
-	return join(pluginCacheRoot(home), "workspace", workspaceId);
-}
-/** 用户级缓存目录（跨工作区共享；当前无实例，预留供全局偏好类缓存使用）。 */
-function userCacheDir(home = dshHome()) {
-	return join(pluginCacheRoot(home), "user");
-}
-/** LSP provider 发现结果缓存文件（用户级：user/lsp-specs.v<schema>.json，跨会话/跨重启共享）。 */
-function lspSpecCacheFile(home = dshHome(), schema = 4) {
-	return join(userCacheDir(home), "lsp-specs.v" + schema + ".json");
-}
-/** 插件日志根（~/.dsh/dsh-vscode-mode/logs，用户级）。 */
-function pluginLogRoot(home = dshHome()) {
-	return join(home, PLUGIN_ID, "logs");
-}
-/** 每工作区树缓存文件（工作区级：workspace/<id>/tree.v<schema>.json，文件名含版本便于 sweep）。 */
-function treeCacheFile(cwd, home = dshHome(), schema = 1) {
-	return join(workspaceCacheDir(hashOf(cwd), home), "tree.v" + schema + ".json");
+function isDebugLogName(name) {
+	return typeof name === "string" && DEBUG_LOG_NAME.test(name);
 }
 /**
-* 每工作区 UI 状态镜像文件（工作区级：workspace/<id>/ui.v<schema>.json）。
-* 存编辑器页签/侧栏/预览态等界面状态的 localStorage 原值副本，供换 origin 后回填。
-* @author ddj 2026年09月28号
-* @param cwd 工作区绝对路径
-* @param home DSH home（测试可注入）
-* @param schema schema 版本（缺省 UI_STATE_SCHEMA）
-* @returns UI 状态镜像文件绝对路径
+* 批量落盘一条 debug 日志缓冲：读旧文件 → 追加 → 超上限截断保留尾部 → 一次写回。
+* 串行链保证同一 cwd 的读改写不交错丢行；写失败静默忽略（调试日志不阻塞业务）。
+* @author ddj 2026年09月08号
+* @param cwd 工作区（日志落 ~/.dsh/dsh-vscode-mode/logs/debug.<cwdHash>.log）
+* @param batch 本批日志行
 */
-function uiStateFile(cwd, home = dshHome(), schema = 1) {
-	return join(workspaceCacheDir(hashOf(cwd), home), "ui.v" + schema + ".json");
+function flushDebug(cwd, batch) {
+	const task = (debugWriteQueues.get(cwd) ?? Promise.resolve()).then(async () => {
+		try {
+			await mkdir(pluginLogRoot(), { recursive: true });
+			const target = debugLogFile(cwd);
+			const appended = await readFile(target, "utf8").catch(() => "") + batch.map((l) => (/* @__PURE__ */ new Date()).toISOString() + " " + l + "\n").join("");
+			const next = appended.length > DEBUG_LOG_CAP ? appended.slice(-Math.floor(DEBUG_LOG_CAP / 2)) : appended;
+			await writeFile(target, next, "utf8");
+			if (!debugLegacyCleaned.has(cwd)) {
+				debugLegacyCleaned.add(cwd);
+				await rm(join(cwd, DEBUG_LOG), { force: true }).catch(() => {});
+			}
+		} catch (e) {}
+	});
+	debugWriteQueues.set(cwd, task);
+	return task;
 }
 /**
-* 用户级 UI 状态镜像文件（跨工作区共享：user/ui-globals.v<schema>.json）。
-* 存与工作区无关的全局键（侧栏提示已忽略、工作区折叠态等）。
-* @author ddj 2026年09月28号
-* @param home DSH home（测试可注入）
-* @param schema schema 版本（缺省 UI_STATE_SCHEMA）
-* @returns 全局 UI 状态镜像文件绝对路径
+* 记录一条 client 上报的诊断日志：入队缓冲批量落盘 + 终端回显（级别跟随，缺省 debug）。
+* 落盘行格式 `<iso> [level] text`；级别标记在入队时补齐，flush 侧无感。
+* @author ddj 2026年09月08号 / 2026年09月17号
+* @param _ctx DSH 上下文（入参保留：诊断通道按 cwd 隔离，当前不需要 ctx，未来过滤用）
+* @param cwd 工作区（日志文件按 cwd hash 隔离）
+* @param text 单条日志文本（不含换行）
+* @param level 日志级别（缺省 debug；落盘行与终端回显均带此级别）
 */
-function uiGlobalsFile(home = dshHome(), schema = 1) {
-	return join(userCacheDir(home), "ui-globals.v" + schema + ".json");
-}
-/** 每工作区 debug 日志文件（用户级日志根下，按 cwd hash 隔离）。 */
-function debugLogFile(cwd, home = dshHome()) {
-	return join(pluginLogRoot(home), "debug." + hashOf(cwd) + ".log");
+function debugRecord(_ctx, cwd, text, level = "debug") {
+	const tagged = "[" + level + "] " + text;
+	const st = debugBuffers.get(cwd) ?? {
+		lines: [],
+		len: 0,
+		timer: null
+	};
+	st.lines.push(tagged);
+	st.len += tagged.length;
+	const flush = () => {
+		st.timer = null;
+		const batch = st.lines;
+		st.lines = [];
+		st.len = 0;
+		flushDebug(cwd, batch);
+	};
+	if (st.len >= DEBUG_BUF_CAP) {
+		if (st.timer) clearTimeout(st.timer);
+		flush();
+	} else if (!st.timer) st.timer = setTimeout(flush, DEBUG_FLUSH_IDLE_MS);
+	debugBuffers.set(cwd, st);
+	debugLog[level](text);
 }
 /**
-* 每工作区归档数据库（用户数据，不受缓存清理预算约束）。
-* @author ddj 2026年09月30号
-* @param cwd 工作区绝对路径
-* @param home DSH home
-* @returns 归档数据库绝对路径
+* 清单：日志根下全部诊断日志文件（名字/字节/mtime；非法名跳过），mtime 新的在前。
+* @author ddj 2026年09月17号
+* @param home DSH home（测试可注入；缺省按环境解析）
+* @returns 清单项数组
 */
-function archiveDbFile(cwd, home = dshHome()) {
-	return join(home, PLUGIN_ID, "data", "archive", hashOf(cwd) + ".sqlite");
-}
-/** 插件包 assets 目录（import.meta.url 派生；config.imageDir 可覆盖，见 imageDirOf）。 */
-function assetsDirOf(moduleUrl) {
-	return join(dirname(fileURLToPath(moduleUrl)), "..", "assets");
-}
-/** Monaco AMD 静态目录（随包发布）。 */
-function vendorDirOf(moduleUrl) {
-	return join(assetsDirOf(moduleUrl), "vendor");
+async function listDebugLogs(home = dshHome()) {
+	const names = await readdir(pluginLogRoot(home)).catch(() => []);
+	const items = [];
+	for (const name of names) {
+		if (!isDebugLogName(name)) continue;
+		const info = await stat(join(pluginLogRoot(home), name)).catch(() => null);
+		if (!info?.isFile()) continue;
+		items.push({
+			name,
+			bytes: info.size,
+			mtimeMs: info.mtimeMs
+		});
+	}
+	items.sort((a, b) => b.mtimeMs - a.mtimeMs);
+	return items;
 }
 /**
-* 插件自带技能组根目录（包根 skills/，与 assets/ 同级；随包发布）。
-* 布局：<根>/<技能名>/SKILL.md（目录式）或 <根>/<技能名>.md（扁平式）。
-* @author ddj 2026年09月11号
-* @param moduleUrl 模块 URL（缺省 import.meta.url；测试注入）
-* @returns 技能组根目录绝对路径
+* 尾部读取一份诊断日志：保留文件尾 maxBytes 字节（缺省 256KB），truncated 标记截头。
+* 单文件本体受 DEBUG_LOG_CAP=512KB 约束，整读为字符串的成本可接受。
+* @author ddj 2026年09月17号
+* @param name 日志文件名（isDebugLogName 白名单校验，非法直接 null）
+* @param maxBytes 尾部保留字节数（缺省 256KB）
+* @param home DSH home（测试可注入）
+* @returns 读取结果；文件不存在或名字非法返回 null
 */
-function skillsDirOf(moduleUrl) {
-	return join(dirname(fileURLToPath(moduleUrl)), "..", "skills");
-}
-/** 图标目录：config.imageDir 覆盖优先，否则插件包 assets/。 */
-function imageDirOf(config, moduleUrl) {
-	const cfg = config;
-	if (cfg && typeof cfg.imageDir === "string" && cfg.imageDir) return cfg.imageDir.replace(/\\/g, "/");
-	return assetsDirOf(moduleUrl);
+async function readDebugLog(name, maxBytes = 262144, home = dshHome()) {
+	if (!isDebugLogName(name)) return null;
+	const target = join(pluginLogRoot(home), name);
+	const info = await stat(target).catch(() => null);
+	if (!info?.isFile()) return null;
+	const text = await readFile(target, "utf8").catch(() => null);
+	if (text === null) return null;
+	const cut = Math.max(0, text.length - maxBytes);
+	return {
+		name,
+		path: target,
+		content: cut > 0 ? text.slice(cut) : text,
+		size: info.size,
+		truncated: cut > 0
+	};
 }
 /**
-* 已知缓存文件种类 → 当前 schema 版本（sweep 判旧依据）。
-* 新增缓存文件必须登记在此，否则被当作未知残留清理。
+* 清空一份诊断日志（truncate 到 0，保留文件本身）。
+* @author ddj 2026年09月17号
+* @param name 日志文件名（isDebugLogName 白名单校验）
+* @param home DSH home（测试可注入）
+* @returns 是否清空成功（文件不存在视为未成功，文案由调用方给）
 */
-const CACHE_SCHEMAS = {
-	tree: 1,
-	"lsp-specs": 4,
-	ui: 1,
-	"ui-globals": 1
-};
-/** 缓存文件名 → 种类与 schema 版本（`<kind>.v<schema>.json`；未登记种类/命名不合规 → null）。 */
-function parseCacheName(filename) {
-	const m = /^([a-z-]+)\.v(\d+)\.json$/.exec(filename);
-	if (!m) return null;
-	const kind = m[1];
-	if (CACHE_SCHEMAS[kind] === void 0) return null;
-	return {
-		kind,
-		schema: Number(m[2])
-	};
+async function clearDebugLog(name, home = dshHome()) {
+	if (!isDebugLogName(name)) return false;
+	return await truncate(join(pluginLogRoot(home), name)).then(() => true).catch(() => false);
 }
+//#endregion
+//#region src/mcpDiagnostic.ts
 /**
-* 该缓存文件名是否为已登记种类的当前 schema 版本（sweep 判旧/判残留依据）。
-* @author ddj 2026年09月28号
-* @param filename 缓存文件名（不含目录）
-* @returns 已登记种类且版本为当前版本
+* Format an initialization failure without serializing the MCP configuration.
+* @public @author ddj 2026年10月28号
+* @param error Original failure and optional cause chain.
+* @param config Effective configuration, used only to remove known secret values.
+* @returns Bounded single-line diagnostic; URLs and explicit credentials are removed.
 */
-function isCurrentCacheFile(filename) {
-	const parsed = parseCacheName(filename);
-	return parsed !== null && parsed.schema === CACHE_SCHEMAS[parsed.kind];
+function mcpErrorText(error, config) {
+	const messages = [];
+	const seen = /* @__PURE__ */ new Set();
+	let cause = error;
+	while (cause !== void 0 && !seen.has(cause) && messages.length < 4) {
+		seen.add(cause);
+		if (cause instanceof Error) {
+			const code = cause.code;
+			messages.push(cause.name + ": " + cause.message + (typeof code === "string" ? " [" + code + "]" : ""));
+			cause = cause.cause;
+		} else {
+			messages.push(typeof cause === "string" ? cause : "Unknown MCP failure");
+			break;
+		}
+	}
+	let text = messages.join(" <- ");
+	const secrets = [...Object.values(config.env ?? {}), ...Object.values(config.headers ?? {})];
+	for (const argument of config.args ?? []) if (!argument.startsWith("-")) secrets.push(argument);
+	secrets.sort((left, right) => right.length - left.length);
+	for (const secret of secrets) if (secret) text = text.split(secret).join("[REDACTED]");
+	text = text.replace(/https?:\/\/[^\s"'<>]+/gi, "[URL]").replace(/\b(authorization|api[-_]?key|token|password|secret)\s*[:=]\s*[^\s,;]+/gi, "$1=[REDACTED]").replace(/[\r\n\x00-\x1f\x7f]+/g, " ");
+	return text.slice(0, 2048);
 }
-/** 按「schema 版本 + 保留期」清扫某目录内文件（目录级，返回相对路径清单）。 */
-async function sweepDirFiles(dir, removed, now, dropAll) {
-	const names = await readdir(dir).catch(() => []);
-	for (const name of names) {
-		const full = join(dir, name);
-		let drop = dropAll;
-		if (!drop) {
-			if (!isCurrentCacheFile(name)) drop = true;
-			else try {
-				if (now - (await stat(full)).mtimeMs > 2592e6) drop = true;
-			} catch (error) {
-				drop = true;
+//#endregion
+//#region src/mcpPool.ts
+/** Connection ownership, bounded cold starts and workspace leases. @author ddj 2026年10月20号 */
+/** @private @author ddj 2026年10月20号 @param input Plain effective configuration. @returns Stable secret-bearing identity used only as digest input. */
+function stableConfig(input) {
+	if (Array.isArray(input)) return "[" + input.map(stableConfig).join(",") + "]";
+	if (input && typeof input === "object") {
+		const config = input;
+		return "{" + Object.keys(config).sort().map((key) => JSON.stringify(key) + ":" + stableConfig(config[key])).join(",") + "}";
+	}
+	return JSON.stringify(input) ?? "null";
+}
+/** @public @author ddj 2026年10月20号 @param task Shared work that must remain alive for other waiters. @param signal One waiter's cancellation. @returns Caller-local wait without abandoning owned pool work. */
+function waitMcp(task, signal) {
+	if (!signal) return task;
+	return new Promise((resolve, reject) => {
+		/** @author ddj 2026年10月20号 Rejects only this waiter. */
+		const abort = () => {
+			reject(/* @__PURE__ */ new Error("MCP 等待已取消"));
+		};
+		if (signal.aborted) {
+			abort();
+			return;
+		}
+		signal.addEventListener("abort", abort, { once: true });
+		task.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+/** The pool owns private scopes independently from any first subscriber. */
+var McpPool = class {
+	ctx;
+	load;
+	make;
+	entries = /* @__PURE__ */ new Map();
+	owners = /* @__PURE__ */ new WeakMap();
+	ownerSeq = 0;
+	running = 0;
+	queue = [];
+	jobs = /* @__PURE__ */ new Set();
+	stopped = false;
+	/** @public @author ddj 2026年10月20号 @param ctx Host lifecycle owner. @param load Official plugin loader. @param make Private scope factory. */
+	constructor(ctx, load, make = () => McpBridge.create(ctx)) {
+		this.ctx = ctx;
+		this.load = load;
+		this.make = make;
+	}
+	/** @private @author ddj 2026年10月20号 @param spec Effective request. @returns Private digest; never emit configuration or secrets. */
+	keyOf(spec) {
+		let owner = 0;
+		if (spec.policy.sharing === "agent") {
+			if (!this.owners.has(spec.owner)) this.owners.set(spec.owner, ++this.ownerSeq);
+			owner = this.owners.get(spec.owner);
+		}
+		const workspace = process.platform === "win32" ? spec.workspace.replace(/\\/g, "/").toLowerCase() : spec.workspace;
+		return createHash("sha256").update(stableConfig([
+			workspace,
+			owner,
+			spec.config,
+			spec.policy
+		])).digest("hex");
+	}
+	/** @public @author ddj 2026年10月20号 @param spec Authorized connection request. @returns Reference-counted single-flight lease. */
+	acquire(spec) {
+		if (this.stopped) throw new Error("MCP runtime is disposed");
+		const key = this.keyOf(spec);
+		let entry = this.entries.get(key);
+		if (entry?.phase === "error" && entry.retryAt !== void 0 && Date.now() >= entry.retryAt && !entry.close) {
+			this.entries.delete(key);
+			entry = void 0;
+		}
+		if (entry && !entry.live) throw new Error(entry.error ?? "MCP 旧连接仍在释放，暂不能创建替代实例");
+		if (!entry) {
+			entry = {
+				key,
+				spec,
+				refs: 0,
+				phase: "queued",
+				queuedAt: Date.now(),
+				phaseAt: Date.now(),
+				ready: Promise.resolve(),
+				live: true,
+				calls: Promise.resolve()
+			};
+			this.entries.set(key, entry);
+			entry.ready = this.schedule(entry);
+			entry.ready.catch(() => void 0);
+		}
+		if (entry.idle) clearTimeout(entry.idle);
+		entry.idle = void 0;
+		entry.refs += 1;
+		let released = false;
+		return {
+			entry,
+			release: () => {
+				if (released) return;
+				released = true;
+				this.release(entry);
 			}
+		};
+	}
+	/** @private @author ddj 2026年10月20号 @param entry New entry. @returns Queued initialization, bounded to two concurrent starts. */
+	schedule(entry) {
+		return new Promise((resolve, reject) => {
+			/** @author ddj 2026年10月20号 Initializes a still-owned queue item. */
+			const run = async () => {
+				try {
+					await this.start(entry);
+					resolve();
+				} catch (error) {
+					reject(error);
+				}
+			};
+			this.queue.push(run);
+			this.pump();
+		});
+	}
+	/** @private @author ddj 2026年10月20号 Advances FIFO work; each task holds its slot until startup or cleanup quiesces. */
+	pump() {
+		while (this.running < 2 && this.queue.length) {
+			const run = this.queue.shift();
+			this.running += 1;
+			const job = run().finally(() => {
+				this.running -= 1;
+				this.jobs.delete(job);
+				this.pump();
+			});
+			this.jobs.add(job);
 		}
-		if (!drop) continue;
+	}
+	/** @private @author ddj 2026年10月20号 @param entry Connection to initialize. @returns Initialization completion, or failure after owned cleanup. */
+	async start(entry) {
+		if (!entry.live || this.stopped) throw new Error("MCP 启动已取消");
+		entry.phase = "loading";
+		entry.phaseAt = Date.now();
+		entry.startAt = entry.phaseAt;
+		let timer;
+		const work = this.mount(entry);
+		const deadline = new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error("MCP 初始化超时")), entry.spec.policy.startupTimeoutMs);
+			timer.unref?.();
+		});
 		try {
-			await rm(full, { force: true });
-			removed.push(name);
-		} catch (error) {}
+			await Promise.race([work, deadline]);
+			if (!entry.live) throw new Error("MCP 启动已取消");
+			entry.phase = "ready";
+			entry.finishedAt = Date.now();
+			entry.connectedAt = entry.finishedAt;
+		} catch (error) {
+			entry.error = "MCP 初始化失败或超时，请查看 Host 日志";
+			const diagnostic = "MCP initialization failed; phase=" + entry.phase + "; transport=" + entry.spec.config.transport + "; elapsedMs=" + (Date.now() - entry.startAt) + "; " + mcpErrorText(error, entry.spec.config);
+			debugRecord(this.ctx, entry.spec.workspace, diagnostic, "warn");
+			entry.live = false;
+			entry.phase = "stopping";
+			const closing = this.closeBridge(entry);
+			await Promise.allSettled([closing, work]);
+			entry.phase = "error";
+			entry.finishedAt = Date.now();
+			entry.retryAt = Date.now() + 5e3;
+			throw new Error(entry.error);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
 	}
-}
-/** 清扫工作区级缓存：逐工作区目录按版本/TTL 清文件，空目录删除。 */
-async function sweepWorkspaceTier(dir, removed, now) {
-	const ids = await readdir(dir).catch(() => []);
-	for (const id of ids) {
-		const wsDir = join(dir, id);
-		await sweepDirFiles(wsDir, removed, now, false);
-		if (!(await readdir(wsDir).catch(() => [])).length) await rm(wsDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+	/** @private @author ddj 2026年10月20号 @param entry Owned generation. @returns Official initial sync; never publishes after invalidation. */
+	async mount(entry) {
+		const official = await this.load();
+		if (!entry.live || this.stopped) return;
+		const bridge = await this.make();
+		if (!entry.live || this.stopped) {
+			await bridge.dispose();
+			return;
+		}
+		entry.bridge = bridge;
+		entry.phase = "starting";
+		entry.phaseAt = Date.now();
+		entry.fiber = bridge.scope.ctx.plugin(official, entry.spec.config);
+		await entry.fiber;
+		if (entry.fiber?.state !== void 0 && entry.fiber.state !== 2) throw new Error("MCP 插件未完成激活");
 	}
-}
-/** 总预算兜底：递归收集全部缓存文件，按 mtime 从旧到新删，直到总大小 ≤ 预算。 */
-async function sweepByTotalCap(root, removed, cap) {
-	const files = [];
-	const walk = async (dir) => {
-		const names = await readdir(dir).catch(() => []);
-		for (const name of names) {
-			const full = join(dir, name);
-			try {
-				const info = await stat(full);
-				if (info.isDirectory()) await walk(full);
-				else files.push({
-					path: full,
-					mtime: info.mtimeMs,
-					size: info.size
-				});
-			} catch (error) {}
+	/** @private @author ddj 2026年10月20号 @param entry Connection to close. @returns Shared closure barrier; rejection retains a fenced entry. */
+	async closeBridge(entry) {
+		if (entry.close) return entry.close;
+		const close = entry.bridge?.dispose() ?? Promise.resolve();
+		entry.close = close;
+		try {
+			await close;
+			entry.bridge = void 0;
+			entry.fiber = void 0;
+			entry.close = void 0;
+		} catch (error) {
+			entry.error = "MCP 释放未确认，禁止重建，请查看 Host 日志";
+			this.ctx.logger?.warn?.("MCP cleanup failed: " + String(error));
+			throw error;
+		}
+	}
+	/** @private @author ddj 2026年10月20号 @param entry One lease's owner. Arms workspace-only warm retention. */
+	release(entry) {
+		entry.refs = Math.max(0, entry.refs - 1);
+		if (entry.refs || !entry.live) return;
+		if (entry.spec.policy.sharing === "agent") {
+			this.retire(entry).catch(() => void 0);
+			return;
 		}
+		entry.idle = setTimeout(() => {
+			this.retire(entry).catch(() => void 0);
+		}, 6e4);
+		entry.idle.unref?.();
+	}
+	/** @public @author ddj 2026年10月20号 @param entry Invalid generation. @returns Quiescent close; callers may await before starting a replacement. */
+	async retire(entry) {
+		entry.live = false;
+		entry.phase = "stopping";
+		if (entry.idle) clearTimeout(entry.idle);
+		await this.closeBridge(entry);
+		await entry.ready.catch(() => void 0);
+		await entry.calls.catch(() => void 0);
+		if (this.entries.get(entry.key) === entry) this.entries.delete(entry.key);
+	}
+	/** @public @author ddj 2026年10月20号 @param entry Authorized connection. @param action Per-call work retaining original execution identity. @param signal Caller cancellation. @returns Serialized shared result; no direct registry bypass is introduced here. */
+	run(entry, action, signal) {
+		/** @author ddj 2026年10月20号 Checks cancellation and generation again at actual dispatch. */
+		const invoke = async () => {
+			await waitMcp(entry.ready, signal);
+			if (signal?.aborted || !entry.live || entry.phase !== "ready") throw new Error("MCP 连接不可用或调用已取消");
+			return action();
+		};
+		const result = entry.calls.then(invoke);
+		entry.calls = result.catch(() => void 0);
+		return result;
+	}
+	/** @public @author ddj 2026年10月20号 @returns Full disposal of entries, queue, timers and owned work. */
+	async dispose() {
+		this.stopped = true;
+		await Promise.all([...this.entries.values()].map((entry) => this.retire(entry)));
+		await Promise.all([...this.jobs]);
+	}
+};
+//#endregion
+//#region src/mcpDiscover.ts
+/** @public @author ddj 2026年10月20号 @param runtime Authorized runtime. @param ctx Host registration context. @returns Global discovery cleanup; normal capability filters remain authoritative. */
+function installDiscover(runtime, ctx) {
+	const tools = ctx.get("tools");
+	/** @author ddj 2026年10月20号 @param args Validated operation. @param execution Registry-owned caller identity. @returns Safe capability catalogue or real connected schemas. */
+	const execute = async (args, execution) => {
+		const agent = execution.agent;
+		if (!agent || !runtime.agents.has(agent)) throw new Error("会话未激活，不能使用项目 MCP 发现入口");
+		if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some((key) => !["action", "serverName"].includes(key))) throw new Error("发现入口仅接受 action 和 serverName");
+		if (!["list", "connect"].includes(args.action)) throw new Error("action 必须为 list 或 connect");
+		if (args.action === "list") return runtime.catalogue(agent);
+		if (typeof args.serverName !== "string") throw new Error("请指定已配置的 serverName");
+		return runtime.connect(agent, args.serverName, execution.signal);
 	};
-	await walk(root);
-	let total = files.reduce((sum, f) => sum + f.size, 0);
-	files.sort((a, b) => a.mtime - b.mtime);
-	for (const f of files) {
-		if (total <= cap) break;
-		try {
-			await rm(f.path, { force: true });
-			total -= f.size;
-			removed.push(f.path.slice(root.length + 1));
-		} catch (error) {}
+	/** @author ddj 2026年10月20号 @param _args Unused. @param result Safe canonical JSON. @returns Native content without bypassing output validation. */
+	const render = (_args, result) => [{
+		type: "text",
+		text: JSON.stringify(result)
+	}];
+	return tools.register({
+		name: "discover_project_mcp",
+		description: "List this workspace’s configured project MCP services without starting them, or connect one to discover its real tools. After connecting, call discovered tools in the NEXT request/program; never guess schemas. Global/preset MCPs are not included.",
+		parameters: {
+			type: "object",
+			properties: {
+				action: {
+					type: "string",
+					enum: ["list", "connect"]
+				},
+				serverName: { type: "string" }
+			},
+			required: ["action"],
+			additionalProperties: false
+		},
+		output: {
+			schema: {},
+			render
+		},
+		execute
+	});
+}
+/** @public @author ddj 2026年10月20号 @param runtime Active owners. @param agent Scoped catalogue owner. @returns Scoped instruction cleanup; does not register a tool override. */
+function discoverPrompt(runtime, agent) {
+	const prompt = agent.ctx.get("systemPrompt");
+	/** @author ddj 2026年10月20号 @returns Current enabled names only; no credential-bearing configuration. */
+	const text = () => {
+		const names = runtime.catalogue(agent).map((server) => server.serverName);
+		if (!names.length) return "";
+		return "Project MCP capabilities (may not be started): " + JSON.stringify(names) + ". Use discover_project_mcp action=list, then action=connect with serverName when needed. Only use returned real tool schemas. Native tools appear on the next model request; PTC must finish the current program and start a new program to refresh its SDK. Do not eval or bypass tool approval.";
+	};
+	return prompt.section({
+		name: "vscode-mode:project-mcp",
+		order: 3090,
+		text,
+		interpolate: false
+	});
+}
+//#endregion
+//#region src/shared/diff.ts
+/** 统一取对应 hunk；callHunk 只用于旧记录缺失 hunks 时兼容。 */
+function preciseHunk(record, idx) {
+	return hunkOf(record, idx);
+}
+/** 轻量、确定性的字符串指纹；不引入 Node crypto。 */
+function fingerprint(text) {
+	if (typeof text !== "string") return null;
+	let hash = 2166136261;
+	for (let i = 0; i < text.length; i++) {
+		hash ^= text.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
 	}
+	return "fnv1a:" + (hash >>> 0).toString(16) + ":" + text.length;
+}
+/** 取记录第 idx 个有效 hunk；只有记录缺 hunk 时才回退 callHunk。 */
+function hunkOf(record, idx) {
+	const hunk = Array.isArray(record.hunks) ? record.hunks[idx] : void 0;
+	if (hunk && typeof hunk.newText === "string") return hunk;
+	if (idx === 0 && record.callHunk && typeof record.callHunk.newText === "string") return record.callHunk;
+	return null;
+}
+/** hunk 是否表示没有实际内容变化。 */
+function isNoopHunk(hunk) {
+	return !!hunk && hunk.oldText !== null && hunk.oldText === hunk.newText;
 }
 /**
-* 清理插件缓存根（分级 + 总预算兜底）：
-* - 根级残留文件（旧扁平格式/未知）→ 删
-* - workspace/ 工作区级 → 按「schema 版本 + 保留期」清文件，空目录删除
-* - user/ 用户级 → 按「schema 版本 + 保留期」清文件
-* - 总大小超预算 → 按最旧先删（最后防线，防任意增长撑爆磁盘）
-* best-effort 静默。
-* @author ddj 2026年09月01号
-* @param home DSH home（测试可注入）
-* @param cap 总预算字节数（缺省 CACHE_TOTAL_CAP；测试可注入小预算）
-* @returns 删除的文件相对路径清单
+* 差异比较口径归一化：剥离 UTF-8 BOM、统一 CRLF 为 LF。
+* 背景：外部工具（pwsh/编辑器）可能改变 BOM/行尾，导致 after 指纹与 hunk
+* 定位在内容语义未变的情况下误报 conflict，把待确认修改从 UI 排除。
+* @author ddj 2026年09月09号
 */
-async function sweepTreeCache(home = dshHome(), cap = CACHE_TOTAL_CAP) {
-	const dir = pluginCacheRoot(home);
-	const names = await readdir(dir).catch(() => []);
-	if (!names.length) return [];
-	const removed = [];
-	const now = Date.now();
-	await Promise.all(names.map(async (name) => {
-		const full = join(dir, name);
-		try {
-			if ((await stat(full)).isDirectory()) {
-				if (name === "workspace") await sweepWorkspaceTier(full, removed, now);
-				else if (name === "user") await sweepDirFiles(full, removed, now, false);
-				else {
-					await rm(full, {
-						recursive: true,
-						force: true
-					});
-					removed.push(name);
-				}
-			} else {
-				await rm(full, { force: true });
-				removed.push(name);
+function normalizeForCompare(text) {
+	return text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+}
+/** 归一化一个 hunk 的两侧文本（与 normalizeForCompare 同口径）。 */
+function normalizeHunk(hunk) {
+	return {
+		oldText: hunk.oldText === null ? null : normalizeForCompare(hunk.oldText),
+		newText: normalizeForCompare(hunk.newText)
+	};
+}
+/** 按文件顺序为多 hunk 写入不重复的 after 坐标。 */
+function annotateHunks(hunks, before, after) {
+	if (typeof after !== "string") return hunks;
+	let cursor = 0;
+	return hunks.map((hunk) => {
+		if (hunk.newText.length > 0) {
+			const start = after.indexOf(hunk.newText, cursor);
+			if (start >= 0) {
+				cursor = start + hunk.newText.length;
+				return {
+					...hunk,
+					afterStart: start,
+					afterEnd: cursor
+				};
 			}
-		} catch (error) {}
-	}));
-	await sweepByTotalCap(dir, removed, cap);
-	return removed;
+			return hunk;
+		}
+		if (hunks.length !== 1 || typeof before !== "string" || before === after || hunk.oldText === null) return hunk;
+		const prefix = commonPrefix(before, after);
+		const suffix = commonSuffix(before, after, prefix);
+		const removedStart = prefix;
+		const removedEnd = Math.max(removedStart, before.length - suffix);
+		return {
+			...hunk,
+			afterStart: removedStart,
+			afterEnd: removedStart,
+			beforeStart: removedStart,
+			beforeEnd: removedEnd
+		};
+	});
+}
+/** 计算两个文本的最长公共前缀长度。 */
+function commonPrefix(left, right) {
+	const limit = Math.min(left.length, right.length);
+	let i = 0;
+	while (i < limit && left.charCodeAt(i) === right.charCodeAt(i)) i++;
+	return i;
+}
+/** 计算不与 prefix 重叠的最长公共后缀长度。 */
+function commonSuffix(left, right, prefix) {
+	const limit = Math.min(left.length, right.length) - prefix;
+	let i = 0;
+	while (i < limit && left.charCodeAt(left.length - 1 - i) === right.charCodeAt(right.length - 1 - i)) i++;
+	return i;
 }
-//#endregion
-//#region src/shared/logger.ts
-/**
-* dsh-vscode-mode — 统一日志核心（双面共享，平台中立）。
-* 输出规范：
-* - 格式：`[dsh-vscode-mode][:scope] 消息`；前缀只在模块内部拼接，业务代码禁止手写前缀
-* - 级别语义：debug=诊断明细 / info=装配与路由里程碑 / warn=降级与兼容回退 / error=失败
-* - 出口：host 面经 bindHostLog(ctx) 绑定 ctx.logger（缺失回退 console）；client 面固定 console
-* - 诊断文件通道（edrv.debug → ~/.dsh/dsh-vscode-mode/logs/）见 debugLog.ts，与本模块前缀共用
-* 新增日志一律 `import { log } from '../log.js'`（client 为 './log.js'）后调 log.debug/info/warn/error；
-* 子域日志用 log.child('scope')，禁止另起 console。
-* 作者 ddj 2026-09-08
-*/
-/** 插件统一日志前缀（与包安装名一致）。 */
-const LOG_PREFIX = "[dsh-vscode-mode]";
-/** 默认级别到 console 方法名的映射。 */
-const CONSOLE_METHODS = {
-	debug: "debug",
-	info: "info",
-	warn: "warn",
-	error: "error"
-};
 /**
-* 默认出口：console（级别直映方法；方法缺失时静默丢弃，不抛错）。
-* @author ddj 2026年09月08号
-* @returns console 出口
+* 懒扫描候选：先找 cursor 后未占用项，找不到再回退至首个未占用项。
+* @author ddj 2026年09月29号
+* @param content 当前内容
+* @param needle 搜索串
+* @param cursor 前一块的结束位置
+* @param occupied 已选区间
+* @param state 此搜索串已扫描的候选
+* @returns 与完整候选列表双轮查找相同的匹配
 */
-function consoleSink() {
-	return (level, line) => {
-		const emit = console[CONSOLE_METHODS[level]];
-		if (typeof emit === "function") emit.call(console, line);
-	};
+function findCandidate(content, needle, cursor, occupied, state) {
+	if (!needle.length) return void 0;
+	let fallback;
+	for (let i = 0; i < state.ranges.length; i++) {
+		const range = state.ranges[i];
+		if (occupied.some((used) => overlaps(range, used))) continue;
+		if (range.start >= cursor) return range;
+		if (!fallback) fallback = range;
+	}
+	while (!state.done) {
+		const at = content.indexOf(needle, state.next);
+		if (at < 0) {
+			state.done = true;
+			break;
+		}
+		const range = {
+			start: at,
+			end: at + needle.length
+		};
+		state.ranges.push(range);
+		state.next = range.end;
+		if (occupied.some((used) => overlaps(range, used))) continue;
+		if (range.start >= cursor) return range;
+		if (!fallback) fallback = range;
+	}
+	return fallback;
 }
 /**
-* DSH host 出口工厂：转接 ctx.logger（方法级可选调用，缺服务/缺方法回退 console）。
-* @author ddj 2026年09月08号
-* @param ctx DSH host 上下文
-* @returns 日志出口
+* 从 after 快照定位所有 hunk，按 hunk 顺序优先选未占用且靠近前一块的候选。
+* 若 hunk 带 afterStart/afterEnd，则优先验证快照坐标，避免重复文本错配。
+* @author ddj 2026年08月24号
+* @param content 当前文件内容
+* @param hunks 待定位 hunk
+* @returns 每个 hunk 一个结果，matched=false 表示冲突/stale
 */
-function ctxLogSink(ctx) {
-	const base = consoleSink();
-	return (level, line) => {
-		const logger = ctx?.logger;
-		const emit = logger?.[level];
-		if (typeof emit === "function") emit.call(logger, line);
-		else base(level, line);
-	};
+function locateHunks(content, hunks) {
+	const locations = [];
+	let cursor = 0;
+	const occupied = [];
+	const matches = /* @__PURE__ */ new Map();
+	for (let idx = 0; idx < hunks.length; idx++) {
+		const hunk = hunks[idx];
+		const newText = hunk.newText;
+		const snapshot = Number.isInteger(hunk.afterStart) && Number.isInteger(hunk.afterEnd) ? {
+			start: hunk.afterStart,
+			end: hunk.afterEnd
+		} : null;
+		const snapshotMatches = snapshot && snapshot.start >= 0 && snapshot.end >= snapshot.start && (newText.length === 0 || content.slice(snapshot.start, snapshot.end) === newText) ? snapshot : null;
+		let candidate;
+		if (snapshotMatches) {
+			if (!occupied.some((used) => overlaps(snapshotMatches, used))) candidate = snapshotMatches;
+		} else if (newText.length) {
+			let state = matches.get(newText);
+			if (!state) {
+				state = {
+					ranges: [],
+					next: 0,
+					done: false
+				};
+				matches.set(newText, state);
+			}
+			candidate = findCandidate(content, newText, cursor, occupied, state);
+		}
+		if (candidate) {
+			locations.push({
+				idx,
+				hunk,
+				...candidate,
+				matched: true
+			});
+			occupied.push(candidate);
+			cursor = Math.max(cursor, candidate.end);
+			continue;
+		}
+		if (newText.length === 0 && hunk.afterStart === void 0 && hunk.afterEnd === void 0 && content.length === 0) {
+			locations.push({
+				idx,
+				hunk,
+				start: 0,
+				end: 0,
+				matched: true
+			});
+			continue;
+		}
+		if (newText.length === 0 && hunk.afterStart !== void 0 && hunk.afterEnd !== void 0 && hunk.afterStart === hunk.afterEnd && hunk.afterStart >= 0 && hunk.afterStart <= content.length) {
+			const point = {
+				start: hunk.afterStart,
+				end: hunk.afterEnd
+			};
+			if (!occupied.some((used) => overlaps(point, used))) {
+				locations.push({
+					idx,
+					hunk,
+					...point,
+					matched: true
+				});
+				occupied.push(point);
+				cursor = Math.max(cursor, point.end);
+				continue;
+			}
+		}
+		locations.push({
+			idx,
+			hunk,
+			start: -1,
+			end: -1,
+			matched: false
+		});
+	}
+	return locations;
+}
+/** 判断两个半开区间是否重叠。零长度区间只与同一位置的零长度区间重叠。 */
+function overlaps(left, right) {
+	if (left.start === left.end || right.start === right.end) return left.start === right.start && left.end === right.end;
+	return left.start < right.end && right.start < left.end;
 }
-/**
-* 拼一行日志：`[dsh-vscode-mode][:scope] 消息`（scope 为空省略冒号段）。
-* @author ddj 2026年09月08号
-* @param scope 子域（可空）
-* @param message 消息文本
-* @returns 整行文本
-*/
-function formatLine(scope, message) {
-	const text = String(message);
-	return scope ? LOG_PREFIX + ":" + scope + " " + text : LOG_PREFIX + " " + text;
+/** 在可定位区间上执行一次 hunk 反向替换。 */
+function replaceRange(content, location, reverse = false) {
+	if (!location.matched || location.start < 0) return null;
+	const replacement = reverse ? location.hunk.oldText ?? "" : location.hunk.newText;
+	return content.slice(0, location.start) + replacement + content.slice(location.end);
 }
 /**
-* 日志器工厂（内部）：emit 时读共享出口状态，保证父 bind 后子实例跟随。
-* @author ddj 2026年09月08号
-* @param state 共享出口状态
-* @param scope 子域文本（可空）
-* @returns 日志器
+* 按位置倒序收集片段，最后一次拼接；非互斥区间退回原替换语义。
+* @author ddj 2026年09月29号
+* @param content 当前文件内容
+* @param locations 已定位区间
+* @param reverse 是否反向应用
+* @returns 合成内容及失效块索引
 */
-function makeLogger(state, scope) {
-	const emit = (level, message) => state.sink(level, formatLine(scope, message));
-	return {
-		debug: (message) => emit("debug", message),
-		info: (message) => emit("info", message),
-		warn: (message) => emit("warn", message),
-		error: (message) => emit("error", message),
-		bind(next) {
-			state.sink = next;
-		},
-		child(next) {
-			return makeLogger(state, scope ? scope + "." + next : next);
+function applyLocations(content, locations, reverse = false) {
+	const stale = locations.filter((location) => !location.matched).map((location) => location.idx);
+	const matched = locations.filter((location) => location.matched).sort((a, b) => b.start - a.start);
+	const parts = [];
+	let end = content.length;
+	for (const location of matched) {
+		if (location.start < 0 || location.end > end) {
+			let out = content;
+			for (const item of matched) {
+				const next = replaceRange(out, item, reverse);
+				if (next === null) stale.push(item.idx);
+				else out = next;
+			}
+			return {
+				content: out,
+				stale: stale.sort((a, b) => a - b)
+			};
 		}
+		parts.push(content.slice(location.end, end), reverse ? location.hunk.oldText ?? "" : location.hunk.newText);
+		end = location.start;
+	}
+	parts.push(content.slice(0, end));
+	parts.reverse();
+	return {
+		content: parts.join(""),
+		stale: stale.sort((a, b) => a - b)
 	};
 }
 /**
-* 创建插件日志器（默认 console 出口；host 面单例由 bindHostLog 换到 ctx.logger）。
-* @author ddj 2026年09月08号
-* @param sink 初始出口（缺省 console）
-* @param scope 初始子域（业务方一般经 child 派生，不直接传）
-* @returns 日志器
+* 写决策到记录（scope=call 整体 / hunk 单个块）。
+* @author ddj 2026年08月20号
+* @param record 记录
+* @param scope 作用域
+* @param idx hunk 下标（仅 scope=hunk 时生效）
+* @param value 决策值
+* @returns 更新后的记录（原对象就地修改）
 */
-function createLogger(sink = consoleSink(), scope = "") {
-	return makeLogger({ sink }, scope);
+function markDecision(record, scope, idx, value) {
+	const dec = record.decisions;
+	if (scope === "hunk" && Array.isArray(dec.perHunk) && Number.isInteger(idx)) {
+		const i = idx;
+		if (i >= 0 && i < dec.perHunk.length) dec.perHunk[i] = value;
+	} else {
+		dec.call = value;
+		if (Array.isArray(dec.perHunk)) dec.perHunk = dec.perHunk.map(() => value);
+	}
+	record.at = (/* @__PURE__ */ new Date()).toISOString();
+	return record;
+}
+/** 记录是否已无任何待决策差异（superseded 或全部已决策）。 */
+function recordResolved(record) {
+	if (record.superseded === true) return true;
+	const hunks = Array.isArray(record.hunks) ? record.hunks : [];
+	const perHunk = Array.isArray(record.decisions.perHunk) ? record.decisions.perHunk : [];
+	const count = Math.max(hunks.length, perHunk.length);
+	if (!count) return record.decisions.call === "accepted" || record.decisions.call === "rejected";
+	for (let idx = 0; idx < count; idx++) {
+		const precise = preciseHunk(record, idx);
+		const value = perHunk[idx] ?? record.decisions.call;
+		if (isNoopHunk(precise) && value === "pending") return false;
+		if (value !== "accepted" && value !== "rejected") return false;
+	}
+	return true;
 }
-//#endregion
-//#region src/log.ts
 /**
-* dsh-vscode-mode host — 日志单例（全 host 面唯一日志入口）。
-* 默认 console 出口；apply() 首行调 bindHostLog(ctx) 切到 ctx.logger（缺失回退 console）。
-* 用法：`import { log } from './log.js'` → `log.debug/info/warn/error(msg)`；子域用 `log.child('scope')`。
-* 作者 ddj 2026-09-08
+* 记录决策摘要（采纳/拒绝/待处理计数，superseded 标记）。
+* @author ddj 2026年08月20号
+* @param record 记录
+* @returns 摘要
 */
-/** host 面插件日志单例（格式/级别语义见 shared/logger.ts 头注释）。 */
-const log = createLogger();
+function recSummary(record) {
+	const hunks = Array.isArray(record.hunks) ? record.hunks : [];
+	const perHunk = Array.isArray(record.decisions.perHunk) ? record.decisions.perHunk : [];
+	const n = Math.max(1, hunks.length, perHunk.length);
+	let accepted = 0;
+	let rejected = 0;
+	let pending = 0;
+	for (let i = 0; i < n; i++) {
+		const hunk = preciseHunk(record, i);
+		const value = perHunk[i] ?? record.decisions.call;
+		if (i < hunks.length && isNoopHunk(hunk) && value === "pending") continue;
+		if (value === "accepted") accepted++;
+		else if (value === "rejected") rejected++;
+		else pending++;
+	}
+	return {
+		accepted,
+		rejected,
+		pending,
+		superseded: record.superseded === true
+	};
+}
 /**
-* 装配期绑定 host 日志出口：ctx.logger 可用时全部日志转经 DSH 日志系统。
-* @author ddj 2026年09月08号
-* @param ctx DSH host 上下文（logger 服务缺失时保持 console 出口）
+* 重建"本批次修改前"内容：把仍待处理（pending）的差异块按 新→旧 顺序从当前内容反解
+* （newText → oldText）。已采纳/已拒绝的块跳过。反解失败的块标记为 stale。
+* @author ddj 2026年08月20号
+* @param records 该文件的活动记录
+* @param content 当前磁盘内容
+* @returns 重建内容与 stale 定位
 */
-function bindHostLog(ctx) {
-	log.bind(ctxLogSink(ctx));
+function reconstructOriginal(records, content) {
+	const pending = [];
+	for (const rec of records) for (let i = 0; i < rec.hunks.length; i++) {
+		const st = rec.decisions.perHunk[i] ?? rec.decisions.call;
+		const hunk = preciseHunk(rec, i);
+		if (st === "pending" && hunk && !isNoopHunk(hunk)) pending.push({
+			rec,
+			idx: i,
+			hunk
+		});
+	}
+	pending.sort((a, b) => a.rec.at < b.rec.at ? 1 : a.rec.at > b.rec.at ? -1 : 0);
+	const rebuilt = applyLocations(content, locateHunks(content, pending.map((item) => item.hunk)), true);
+	return {
+		content: rebuilt.content,
+		stale: rebuilt.stale.map((idx) => ({
+			callId: pending[idx].rec.callId,
+			idx: pending[idx].idx
+		}))
+	};
 }
-//#endregion
-//#region src/debugLog.ts
 /**
-* dsh-vscode-mode host — 诊断文件通道（client 上报 → 缓冲批量落盘）+ 日志文件管理。
-* 通道：edrv.debug RPC → 内存缓冲（满/空闲触发）→ 串行读改写
-*       `~/.dsh/dsh-vscode-mode/logs/debug.<cwdHash>.log`（512KB 上限截断保留尾部）。
-* 设计：console 不一定落盘，文件可靠；写失败静默忽略（调试日志不阻塞业务）。
-* 管理：edrv.dlog.* RPC 用的清单/尾部读取/清空三能力；file 参数一律先过
-*       isDebugLogName 白名单（纯文件名、无路径分隔），杜绝穿越出日志根。
-* 作者 ddj 2026-09-08 / 2026-09-17
+* @public
+* @author ddj 2026年10月10号
+* 判断记录是否完全未决策；缺少逐块状态时沿用 pending 的 call 状态。
+* @param record 审查记录
+* @returns 未归档、未覆盖且没有用户决策时为 true
 */
-/** cwd → 内存缓冲：行数组 + 累计字节数 + 待触发 flush 定时器（攒批落盘，避免每条日志全文件读改写）。 */
-const debugBuffers = /* @__PURE__ */ new Map();
-/** cwd → Promise 链：串行化 debug 日志落盘（fs read+write 非原子，避免并发丢行）。 */
-const debugWriteQueues = /* @__PURE__ */ new Map();
-/** debug 日志单文件上限：超限截断保留尾部，防文件无限增长拖慢每次追加。 */
-const DEBUG_LOG_CAP = 524288;
-/** debug 日志批量缓冲上限：攒满即落盘（一次读改写），上限内不逐条写文件。 */
-const DEBUG_BUF_CAP = 32768;
-/** debug 日志空闲 flush 延迟：缓冲未满时，静默一段时间后落盘一次。 */
-const DEBUG_FLUSH_IDLE_MS = 1e3;
-/** cwd → 已清理旧工作区 debug 日志标记（一次性）。 */
-const debugLegacyCleaned = /* @__PURE__ */ new Set();
-/** 诊断回显日志器（终端回显统一带 `[dsh-vscode-mode:debug]` 前缀，级别跟随上报级别）。 */
-const debugLog = log.child("debug");
-/** 诊断日志文件名白名单（cwd hash 命名；请求回传的 file 参数必须整名匹配，防路径穿越）。 */
-const DEBUG_LOG_NAME = /^debug\.[0-9a-f]{16}\.log$/;
+function fullyPending(record) {
+	return !record.archived && !record.superseded && record.decisions.call === "pending" && record.decisions.perHunk.every((value) => value === "pending");
+}
 /**
-* 文件名是否为合法诊断日志名（白名单整名匹配，杜绝路径穿越）。
-* @author ddj 2026年09月17号
-* @param name 请求回传的文件名（可为空）
-* @returns 是否合法
+* @public
+* @author ddj 2026年10月10号
+* 比较整组 hunk 是否逐块精确逆反；不把新建或纯 no-op 当作抵消。
+* @param prior 先前修改的差异块
+* @param later 后续修改的差异块
+* @returns 文本归一化后整组逆反且包含真实修改时为 true
 */
-function isDebugLogName(name) {
-	return typeof name === "string" && DEBUG_LOG_NAME.test(name);
+function hunksInverse(prior, later) {
+	if (!prior.length || prior.length !== later.length) return false;
+	let changed = false;
+	for (let idx = 0; idx < prior.length; idx++) {
+		const a = normalizeHunk(prior[idx]);
+		const b = normalizeHunk(later[idx]);
+		if (a.oldText !== b.newText || a.newText !== b.oldText) return false;
+		if (!isNoopHunk(a)) changed = true;
+	}
+	return changed;
 }
 /**
-* 批量落盘一条 debug 日志缓冲：读旧文件 → 追加 → 超上限截断保留尾部 → 一次写回。
-* 串行链保证同一 cwd 的读改写不交错丢行；写失败静默忽略（调试日志不阻塞业务）。
-* @author ddj 2026年09月08号
-* @param cwd 工作区（日志落 ~/.dsh/dsh-vscode-mode/logs/debug.<cwdHash>.log）
-* @param batch 本批日志行
+* @private
+* @author ddj 2026年10月10号
+* 同路径优先按捕获批次排序；旧记录仅使用有效时间，不拿 callId 伪造先后证据。
+* @param a 第一条记录
+* @param b 第二条记录
+* @returns 负数表示 a 更早，零表示先后无法区分
 */
-function flushDebug(cwd, batch) {
-	const task = (debugWriteQueues.get(cwd) ?? Promise.resolve()).then(async () => {
-		try {
-			await mkdir(pluginLogRoot(), { recursive: true });
-			const target = debugLogFile(cwd);
-			const appended = await readFile(target, "utf8").catch(() => "") + batch.map((l) => (/* @__PURE__ */ new Date()).toISOString() + " " + l + "\n").join("");
-			const next = appended.length > DEBUG_LOG_CAP ? appended.slice(-Math.floor(DEBUG_LOG_CAP / 2)) : appended;
-			await writeFile(target, next, "utf8");
-			if (!debugLegacyCleaned.has(cwd)) {
-				debugLegacyCleaned.add(cwd);
-				await rm(join(cwd, DEBUG_LOG), { force: true }).catch(() => {});
-			}
-		} catch (e) {}
-	});
-	debugWriteQueues.set(cwd, task);
-	return task;
+function recordOrder(a, b) {
+	if (a.path !== b.path) return a.path.localeCompare(b.path);
+	if (Number.isInteger(a.batch) && Number.isInteger(b.batch) && a.batch > 0 && b.batch > 0 && a.batch !== b.batch) return a.batch - b.batch;
+	const delta = Date.parse(a.at) - Date.parse(b.at);
+	return Number.isFinite(delta) ? delta : 0;
 }
 /**
-* 记录一条 client 上报的诊断日志：入队缓冲批量落盘 + 终端回显（级别跟随，缺省 debug）。
-* 落盘行格式 `<iso> [level] text`；级别标记在入队时补齐，flush 侧无感。
-* @author ddj 2026年09月08号 / 2026年09月17号
-* @param _ctx DSH 上下文（入参保留：诊断通道按 cwd 隔离，当前不需要 ctx，未来过滤用）
-* @param cwd 工作区（日志文件按 cwd hash 隔离）
-* @param text 单条日志文本（不含换行）
-* @param level 日志级别（缺省 debug；落盘行与终端回显均带此级别）
+* @private
+* @author ddj 2026年10月10号
+* 确认完整文件快照往返，防止相同文本在不同位置的反向修改被误隐藏。
+* @param prior 先前记录
+* @param later 后续记录
+* @returns 两端快照互换且文件存在性未变化时为 true；缺少证据时保留审查
 */
-function debugRecord(_ctx, cwd, text, level = "debug") {
-	const tagged = "[" + level + "] " + text;
-	const st = debugBuffers.get(cwd) ?? {
-		lines: [],
-		len: 0,
-		timer: null
-	};
-	st.lines.push(tagged);
-	st.len += tagged.length;
-	const flush = () => {
-		st.timer = null;
-		const batch = st.lines;
-		st.lines = [];
-		st.len = 0;
-		flushDebug(cwd, batch);
-	};
-	if (st.len >= DEBUG_BUF_CAP) {
-		if (st.timer) clearTimeout(st.timer);
-		flush();
-	} else if (!st.timer) st.timer = setTimeout(flush, DEBUG_FLUSH_IDLE_MS);
-	debugBuffers.set(cwd, st);
-	debugLog[level](text);
+function snapshotsRestore(prior, later) {
+	if (prior.create || later.create) return false;
+	if (typeof prior.before !== "string" || typeof prior.after !== "string" || typeof later.before !== "string" || typeof later.after !== "string") return false;
+	return normalizeForCompare(prior.before) === normalizeForCompare(later.after) && normalizeForCompare(prior.after) === normalizeForCompare(later.before);
 }
 /**
-* 清单：日志根下全部诊断日志文件（名字/字节/mtime；非法名跳过），mtime 新的在前。
-* @author ddj 2026年09月17号
-* @param home DSH home（测试可注入；缺省按环境解析）
-* @returns 清单项数组
+* @public
+* @author ddj 2026年10月10号
+* 查找最近一条未决的整记录逆反；必须有文件快照证明原内容确实恢复。
+* @param records 工作区记录（不修改输入）
+* @param record 新记录
+* @returns 可安全配对的先前记录，证据不足或部分撤销时为 null
 */
-async function listDebugLogs(home = dshHome()) {
-	const names = await readdir(pluginLogRoot(home)).catch(() => []);
-	const items = [];
-	for (const name of names) {
-		if (!isDebugLogName(name)) continue;
-		const info = await stat(join(pluginLogRoot(home), name)).catch(() => null);
-		if (!info?.isFile()) continue;
-		items.push({
-			name,
-			bytes: info.size,
-			mtimeMs: info.mtimeMs
-		});
+function findInversePrior(records, record) {
+	if (!fullyPending(record)) return null;
+	let found = null;
+	for (const prior of records) {
+		if (prior.callId === record.callId || prior.path !== record.path || !fullyPending(prior)) continue;
+		if (recordOrder(prior, record) >= 0 || !hunksInverse(prior.hunks, record.hunks)) continue;
+		if (!snapshotsRestore(prior, record)) continue;
+		if (!found || recordOrder(found, prior) < 0) found = prior;
 	}
-	items.sort((a, b) => b.mtimeMs - a.mtimeMs);
-	return items;
+	return found;
 }
 /**
-* 尾部读取一份诊断日志：保留文件尾 maxBytes 字节（缺省 256KB），truncated 标记截头。
-* 单文件本体受 DEBUG_LOG_CAP=512KB 约束，整读为字符串的成本可接受。
-* @author ddj 2026年09月17号
-* @param name 日志文件名（isDebugLogName 白名单校验，非法直接 null）
-* @param maxBytes 尾部保留字节数（缺省 256KB）
-* @param home DSH home（测试可注入）
-* @returns 读取结果；文件不存在或名字非法返回 null
+* @public
+* @author ddj 2026年10月10号
+* 按捕获顺序贪心配对历史抵消记录，每条最多使用一次；桶上限为 200。
+* @param records 工作区记录（不修改输入或记录状态）
+* @returns 可以整对归档的记录对
 */
-async function readDebugLog(name, maxBytes = 262144, home = dshHome()) {
-	if (!isDebugLogName(name)) return null;
-	const target = join(pluginLogRoot(home), name);
-	const info = await stat(target).catch(() => null);
-	if (!info?.isFile()) return null;
-	const text = await readFile(target, "utf8").catch(() => null);
-	if (text === null) return null;
-	const cut = Math.max(0, text.length - maxBytes);
-	return {
-		name,
-		path: target,
-		content: cut > 0 ? text.slice(cut) : text,
-		size: info.size,
-		truncated: cut > 0
-	};
+function findCanceledPairs(records) {
+	const available = [];
+	const pairs = [];
+	const ordered = [...records].sort(recordOrder);
+	for (const record of ordered) {
+		const prior = findInversePrior(available, record);
+		if (!prior) {
+			if (fullyPending(record)) available.push(record);
+			continue;
+		}
+		pairs.push([prior, record]);
+		available.splice(available.indexOf(prior), 1);
+	}
+	return pairs;
+}
+/** 文件当前最大批次号（无记录为 0）。 */
+function fileMaxBatch(records, path) {
+	let m = 0;
+	for (const r of records.values()) if (r.path === path && Number.isInteger(r.batch) && r.batch > m) m = r.batch;
+	return m;
+}
+/** @public @author ddj 2026年10月26号 @param map Legacy records. @param max Cache target, never a pending retention limit. */
+function prune(map, max = 200) {
+	if (map.size <= max) return;
+	const sorted = [...map.values()].filter((record) => record.archived && recordResolved(record)).sort((a, b) => a.at < b.at ? -1 : 1);
+	for (const record of sorted) {
+		if (map.size <= max) break;
+		map.delete(record.callId);
+	}
 }
 /**
-* 清空一份诊断日志（truncate 到 0，保留文件本身）。
-* @author ddj 2026年09月17号
-* @param name 日志文件名（isDebugLogName 白名单校验）
-* @param home DSH home（测试可注入）
-* @returns 是否清空成功（文件不存在视为未成功，文案由调用方给）
+* 归档条目构造（一条批次一条）。
+* @author ddj 2026年08月20号
+* @param recs 同批次记录（非空）
+* @param cwd 工作区
+* @param reason 归档原因
 */
-async function clearDebugLog(name, home = dshHome()) {
-	if (!isDebugLogName(name)) return false;
-	return await truncate(join(pluginLogRoot(home), name)).then(() => true).catch(() => false);
+function archiveEntryFor(recs, cwd, reason) {
+	const first = recs[0];
+	return {
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		cwd,
+		path: first.path,
+		batch: Number.isInteger(first.batch) ? first.batch : null,
+		reason,
+		records: recs.map((r) => ({
+			callId: r.callId,
+			toolName: r.toolName,
+			path: r.path,
+			create: r.create === true,
+			callHunk: r.callHunk,
+			hunks: r.hunks,
+			decisions: r.decisions,
+			note: r.note ?? null,
+			before: typeof r.before === "string" ? r.before : null,
+			after: typeof r.after === "string" ? r.after : null,
+			baseFingerprint: r.baseFingerprint ?? null,
+			afterFingerprint: r.afterFingerprint ?? null,
+			conflict: r.conflict === true,
+			legacy: r.legacy === true,
+			superseded: r.superseded === true,
+			batch: Number.isInteger(r.batch) ? r.batch : null,
+			at: r.at,
+			summary: recSummary(r)
+		}))
+	};
 }
 //#endregion
 //#region src/archiveDb.ts
@@ -2986,10 +3019,14 @@ var McpRuntime = class {
 		instance ??= this.reserve(agent, record, path, name, def);
 		await waitMcp(instance.ready, signal);
 		if (!this.valid(agent, record, name, instance)) throw new Error("项目 MCP 配置已失效");
-		const visible = agent.ctx.get("tools")?.view?.(agent)?.visible;
+		const registry = agent.ctx.get("tools");
+		let visible;
+		if (typeof registry?.definitions === "function") visible = new Set(registry.definitions(agent).map((tool) => tool.name));
+		else if (typeof registry?.view === "function") visible = new Set(registry.view(agent).visible.keys());
+		else throw new Error("项目 MCP 工具目录不可用：缺少公开 definitions 或旧版 view 接口");
 		return {
 			serverName: name,
-			tools: [...instance.lease.entry.bridge.tools.values()].filter((tool) => visible?.has(tool.name)).map((tool) => ({
+			tools: [...instance.lease.entry.bridge.tools.values()].filter((tool) => visible.has(tool.name)).map((tool) => ({
 				name: tool.name,
 				description: tool.description,
 				parameters: tool.parameters
@@ -13114,6 +13151,147 @@ function reviewHandlers(ctx, registry) {
 	};
 }
 //#endregion
+//#region src/missingReview.ts
+/** Missing historical files: frozen, whole-file deletion reviews. */
+const frozen = /* @__PURE__ */ new Map();
+const locks = /* @__PURE__ */ new Set();
+/** @private @author ddj 2026年10月28号 @param target Resolved absolute path. @returns Platform file identity. */
+function fileKey(target) {
+	const normalized = resolve(target).replace(/\\/g, "/");
+	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+/** @private @author ddj 2026年10月28号 @param records Ordered records. @returns Full evidence and decision revision, excluding transient conflict flags. */
+function revisionOf(records) {
+	const evidence = records.map(({ callId, path, at, after, hunks, decisions, archived, superseded }) => ({
+		callId,
+		path,
+		at,
+		after,
+		hunks,
+		decisions,
+		archived,
+		superseded
+	}));
+	return createHash("sha256").update(JSON.stringify(evidence)).digest("hex");
+}
+/** @private @author ddj 2026年10月28号 @param ctx Host capability. @param cwd Workspace. @param bucket Records. @param target Resolved file. @returns Records for the same physical path spelling, oldest first. */
+async function fileRecords(ctx, cwd, bucket, target) {
+	const matches = [];
+	const identity = fileKey(target);
+	for (const record of bucket.values()) {
+		if (record.superseded) continue;
+		if (fileKey(await resolveTargetIn(ctx, cwd, record.path)) === identity) matches.push(record);
+	}
+	return matches.sort((left, right) => left.at.localeCompare(right.at));
+}
+/** @public @author ddj 2026年10月28号 @param ctx Host. @param cwd Workspace. @param path Requested file. @returns True only for confirmed absence; directories and IO failures are not missing files. */
+async function fileAbsent(ctx, cwd, path) {
+	const fs = ctx.get("fs");
+	if (!fs) throw new Error("缺少 fs");
+	const target = await resolveTargetIn(ctx, cwd, path);
+	try {
+		return !await fs.stat(target);
+	} catch (error) {
+		if (["ENOENT", "FS_NOT_FOUND"].includes(String(error.code))) return true;
+		throw error;
+	}
+}
+/** @public @author ddj 2026年10月28号 @param ctx Host. @param session Live session. @param cwd Workspace. @param bucket Records. @param path Requested file. @returns Frozen complete snapshot; never constructs text from hunks or writes files. @throws Missing evidence or nonmissing target. */
+async function missingReview(ctx, session, cwd, bucket, path) {
+	const target = await resolveTargetIn(ctx, cwd, path);
+	if (hasOfficial(cwd, path) || hasOfficial(cwd, target)) throw new Error("该文件已有官方审查记录，请使用官方审查入口");
+	if (!await fileAbsent(ctx, cwd, target)) throw new Error("文件已重新出现，请刷新");
+	const records = await fileRecords(ctx, cwd, bucket, target);
+	const latest = records.at(-1);
+	if (!records.some((record) => !record.archived && !recordResolved(record))) throw new Error("没有待审历史记录");
+	if (!latest || typeof latest.after !== "string") throw new Error("缺少可靠的完整历史快照，无法展示或恢复；不会用局部差异拼接文件");
+	if (Buffer.byteLength(latest.after, "utf8") > 8388608) throw new Error("历史快照过大，无法整文件预览");
+	for (const [token, item] of frozen) if (item.expires < Date.now()) frozen.delete(token);
+	if (frozen.size >= 256) throw new Error("缺失文件预览过多，请稍后重试");
+	const view = {
+		token: randomUUID(),
+		path,
+		content: latest.after,
+		callIds: records.filter((record) => !record.archived && !recordResolved(record)).map((record) => record.callId),
+		at: latest.at
+	};
+	frozen.set(view.token, {
+		view,
+		cwd,
+		session,
+		revision: revisionOf(records),
+		expires: Date.now() + 18e5
+	});
+	return view;
+}
+/** @private @author ddj 2026年10月28号 @param ctx Host. @param item Frozen evidence. @param target Resolved path. @param undo Restore instead of keeping absence. @sideEffects Atomically creates absent file, verifies exact bytes; retries never overwrite an existing file. */
+async function applyDisk(ctx, item, target, undo) {
+	const fs = ctx.get("fs");
+	const absent = await fileAbsent(ctx, item.cwd, target);
+	if (!undo) {
+		if (!absent) throw new Error("文件已重新出现，未执行 Keep");
+		return;
+	}
+	const operation = item.operation;
+	if (!absent && !operation.restored) throw new Error("文件已重新出现，未执行 Undo");
+	if (absent && !operation.restored) {
+		await fs.writeText(target, item.view.content, { kind: "createIfAbsent" }, void 0, policyOf(ctx, item.session));
+		operation.restored = true;
+	}
+	if (absent && operation.restored && !await fs.stat(target)) throw new Error("恢复后的文件再次缺失，未结清记录");
+	if (await fs.readText(target) !== item.view.content) throw new Error("恢复内容校验失败，未结清记录");
+}
+/** @public @author ddj 2026年10月28号 @param ctx Host. @param session Requesting session. @param cwd Workspace. @param bucket Records. @param token Frozen preview token. @param operationId Stable retry ID. @param undo True restores shown snapshot; false keeps deletion. @returns Covered call IDs. @throws Changed evidence, concurrent action or sandbox/IO failure. */
+async function missingDecide(ctx, session, cwd, bucket, token, operationId, undo) {
+	const item = frozen.get(token);
+	if (!item || item.expires < Date.now() || item.cwd !== cwd || item.session.id !== session.id) throw new Error("删除预览已过期，请刷新后重试");
+	if (!operationId || operationId.length > 128) throw new Error("缺少有效操作 ID");
+	const target = await resolveTargetIn(ctx, cwd, item.view.path);
+	const key = JSON.stringify([cwd, fileKey(target)]);
+	if (locks.has(key)) throw new Error("该文件正在处理，请稍后重试");
+	locks.add(key);
+	item.session = session;
+	try {
+		return await commitMissing(ctx, item, bucket, target, operationId, undo);
+	} finally {
+		locks.delete(key);
+	}
+}
+/** @private @author ddj 2026年10月28号 @param ctx Host. @param item Frozen preview. @param bucket Live records. @param target Resolved target. @param operationId Retry identity. @param undo Restore action. @returns Archived pending call IDs; disk success survives bookkeeping failure in the same Host lifetime. */
+async function commitMissing(ctx, item, bucket, target, operationId, undo) {
+	const previous = item.operation;
+	if (previous && (previous.id !== operationId || previous.undo !== undo)) throw new Error("已有不同操作，请刷新后重试");
+	if (previous?.done) return item.view.callIds;
+	if (hasOfficial(item.cwd, target) || hasOfficial(item.cwd, item.view.path)) throw new Error("该文件已有官方审查记录，请刷新");
+	if (revisionOf(await fileRecords(ctx, item.cwd, bucket, target)) !== item.revision) throw new Error("历史记录已变化，请刷新删除预览");
+	item.operation ??= {
+		id: operationId,
+		undo,
+		restored: false,
+		done: false
+	};
+	await applyDisk(ctx, item, target, undo);
+	const current = await fileRecords(ctx, item.cwd, bucket, target);
+	if (revisionOf(current) !== item.revision) throw new Error("历史记录已变化，未结清记录，请刷新");
+	const pending = current.filter((record) => item.view.callIds.includes(record.callId));
+	const decisions = pending.map((record) => record.decisions);
+	const decision = undo ? "rejected" : "accepted";
+	for (const record of pending) record.decisions = {
+		call: decision,
+		perHunk: record.hunks.map(() => decision)
+	};
+	try {
+		await archiveRecords(ctx, item.session, item.cwd, bucket, pending, undo ? "已恢复删除文件快照" : "已保留文件删除");
+	} catch (error) {
+		pending.forEach((record, index) => {
+			record.decisions = decisions[index];
+		});
+		throw error;
+	}
+	item.operation.done = true;
+	return item.view.callIds;
+}
+//#endregion
 //#region src/rpc.ts
 /** Process-local cursor signer; reads must stay on the Host filesystem capability. */
 const readTextPage = createTextPages();
@@ -13202,8 +13380,13 @@ async function readTargetOf(ctx, sc, path) {
 		const target = await resolveTargetIn(ctx, sc.cwd, path);
 		debugRecord(ctx, sc.cwd, "[DEBUG path.resolve] input=" + String(path ?? "") + " resolved=" + fs.processPath(target), "debug");
 		const info = await fs.stat(target);
-		if (!info || info.type !== "file") return {
+		if (!info) return {
 			err: "文件不存在",
+			resolvedPath: fs.processPath(target),
+			code: "file-missing"
+		};
+		if (info.type !== "file") return {
+			err: "目标不是文件",
 			resolvedPath: fs.processPath(target)
 		};
 		if ((info.size ?? 0) > 33554432) return {
@@ -13216,6 +13399,10 @@ async function readTargetOf(ctx, sc, path) {
 			info
 		};
 	} catch (error) {
+		if (["ENOENT", "FS_NOT_FOUND"].includes(String(error.code))) return {
+			err: "文件不存在",
+			code: "file-missing"
+		};
 		return { err: "读取失败：" + String(error) };
 	}
 }
@@ -13316,6 +13503,23 @@ async function applyDecisions(ctx, session, cwd, bucket, items) {
 			});
 			continue;
 		}
+		try {
+			if (await fileAbsent(ctx, cwd, record.path)) {
+				results.push({
+					callId: item.callId,
+					ok: false,
+					error: "文件已删除，请刷新后按整文件删除预览执行 Keep / Undo"
+				});
+				continue;
+			}
+		} catch (error) {
+			results.push({
+				callId: item.callId,
+				ok: false,
+				error: "无法确认文件状态：" + String(error)
+			});
+			continue;
+		}
 		const alreadyDone = (item.scope === "hunk" ? record.decisions.perHunk[item.hunkIndex ?? -1] : record.decisions.call) === item.decision;
 		if (alreadyDone) {
 			if (recordResolved(record) && !record.archived) resolved.push(record);
@@ -13735,6 +13939,48 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				record: item.record
 			};
 		},
+		"edrv.missingReview": async (args) => {
+			const sc = await requireSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			try {
+				const bucket = await bucketOf(registry, ctx, sc.cwd);
+				if (!await fileAbsent(ctx, sc.cwd, args.path)) return {
+					ok: true,
+					review: null
+				};
+				return {
+					ok: true,
+					review: await missingReview(ctx, sc.session, sc.cwd, bucket, args.path)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
+		"edrv.missingDecide": async (args) => {
+			const sc = await requireSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			try {
+				const bucket = await bucketOf(registry, ctx, sc.cwd);
+				return {
+					ok: true,
+					callIds: await missingDecide(ctx, sc.session, sc.cwd, bucket, args.token, args.operationId, args.undo === true)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error)
+				};
+			}
+		},
 		"edrv.decideBatch": async (args) => {
 			const sc = await requireSession(ctx, args.sessionId);
 			if ("err" in sc) return {