dsh-vscode-mode 0.4.3 → 0.4.5

package/lib/client.js

@@ -481,6 +481,16 @@ window.__ModuleLoader__.load({
 			window.dispatchEvent(new CustomEvent("edrv:refresh"));
 		}
 		/**
+		* 磁盘文件变化（外部写入/删除）：文件树按路径失效对应目录并强制重列。
+		* 与 edrv:refresh 分开：这里不触发差异记录重算与 stale 清理，只动目录缓存。
+		* @author ddj 2026年09月15号
+		* @param path 发生变化的文件路径
+		*/
+		function emitFileChanged(path) {
+			if (!path) return;
+			window.dispatchEvent(new CustomEvent("edrv:file-changed", { detail: { path } }));
+		}
+		/**
 		* 打开指定路径并定位到行列（LSP 跳转目标）。
 		* @author ddj 2026年08月27号
 		* @param path 目标路径
@@ -1519,7 +1529,7 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* 加载 Monaco Editor（AMD 构建，随插件包离线分发）：注入 loader.js → require.config → editor.main。
-		* @author ddj 2026年08月20号
+		* @author ddj 2026年08月20号 / 2026年09月22号
 		* @returns Promise<object> window.monaco
 		*/
 		function loadMonaco(onProgress) {
@@ -1527,13 +1537,58 @@ window.__ModuleLoader__.load({
 			if (!monacoPromise) {
 				publishStage("loader", MONACO_STAGES.loader.progress, MONACO_STAGES.loader.message);
 				monacoPromise = new Promise((resolve, reject) => {
+					const hasModule = Object.prototype.hasOwnProperty.call(globalThis, "module");
+					const hasExports = Object.prototype.hasOwnProperty.call(globalThis, "exports");
+					const savedModule = globalThis.module;
+					const savedExports = globalThis.exports;
+					const hideNodeGlobals = () => {
+						try {
+							delete globalThis.module;
+						} catch (error) {}
+						try {
+							delete globalThis.exports;
+						} catch (error) {}
+					};
+					const restoreNodeGlobals = () => {
+						if (hasModule) globalThis.module = savedModule;
+						else try {
+							delete globalThis.module;
+						} catch (error) {}
+						if (hasExports) globalThis.exports = savedExports;
+						else try {
+							delete globalThis.exports;
+						} catch (error) {}
+					};
+					const removeLoaderTag = () => {
+						const existing = document.querySelector("script[data-edrv-monaco-loader]");
+						if (existing?.parentNode) existing.parentNode.removeChild(existing);
+					};
 					const fail = (error) => {
 						monacoPromise = null;
+						removeLoaderTag();
+						restoreNodeGlobals();
 						publishStage("error", MONACO_STAGES.error.progress, MONACO_STAGES.error.message);
 						reject(error);
 					};
+					const inject = () => {
+						const s = document.createElement("script");
+						s.src = MONACO_BASE + "/loader.js";
+						s.dataset.edrvMonacoLoader = "1";
+						s.onload = boot;
+						s.onerror = (event) => {
+							const hint = event && event.type ? "（" + event.type + "）" : "";
+							fail(/* @__PURE__ */ new Error("Monaco loader 加载失败" + hint));
+						};
+						hideNodeGlobals();
+						document.head.appendChild(s);
+					};
 					const boot = () => {
+						restoreNodeGlobals();
 						try {
+							if (typeof window.require !== "function" || typeof window.require.config !== "function") {
+								fail(/* @__PURE__ */ new Error("Monaco loader 未挂载 window.require（可能被其他脚本注入的全局 module 干扰）"));
+								return;
+							}
 							window.require.config({ paths: { vs: MONACO_BASE } });
 							publishStage("core", MONACO_STAGES.core.progress, MONACO_STAGES.core.message);
 							window.require(["vs/editor/editor.main"], () => {
@@ -1548,15 +1603,12 @@ window.__ModuleLoader__.load({
 							fail(error);
 						}
 					};
-					if (document.querySelector("script[data-edrv-monaco-loader]")) boot();
-					else {
-						const s = document.createElement("script");
-						s.src = MONACO_BASE + "/loader.js";
-						s.dataset.edrvMonacoLoader = "1";
-						s.onload = boot;
-						s.onerror = () => fail(/* @__PURE__ */ new Error("Monaco loader 加载失败"));
-						document.head.appendChild(s);
-					}
+					const existing = document.querySelector("script[data-edrv-monaco-loader]");
+					if (existing && typeof window.require === "function" && typeof window.require.config === "function") boot();
+					else if (existing) {
+						removeLoaderTag();
+						inject();
+					} else inject();
 				});
 			}
 			return monacoPromise.finally(unsubscribe);
@@ -1640,6 +1692,348 @@ window.__ModuleLoader__.load({
 			for (let i = 0; i < bytes.length; i += chunk) bin += String.fromCharCode(...bytes.subarray(i, i + chunk));
 			return btoa(bin);
 		}
+		/** 作用域键 → 路径 → 磁盘版本令牌。 */
+		const baselines = /* @__PURE__ */ new Map();
+		/** 作用域键 → 路径 → 已读取过内容的磁盘版本（同版本不重复读盘；含当时的比对结果）。 */
+		const readVersions = /* @__PURE__ */ new Map();
+		/** 作用域键 → 路径 → 待处理同步标记。 */
+		const syncState = /* @__PURE__ */ new Map();
+		/**
+		* 判定一次观测的同步动作（纯函数，判定表见模块头注释）。
+		* @author ddj 2026年09月15号
+		* @param input 观测输入（基线有无/版本是否变化/是否缺失/缓冲是否脏/内容是否相同）
+		* @returns 同步动作
+		*/
+		function syncDecision(input) {
+			if (!input.hasBaseline) return "none";
+			if (input.missing) return input.clean ? "deleted" : "none";
+			if (!input.versionChanged) return "none";
+			if (input.clean) return "sync-silent";
+			return input.contentEqual ? "sync-silent" : "conflict";
+		}
+		/**
+		* 从 host 版本条目取可比较的版本令牌（缺失/空串 → null，表示该后端不提供版本）。
+		* @author ddj 2026年09月15号
+		* @param item 版本条目（可为 undefined）
+		* @returns 版本令牌或 null
+		*/
+		function versionOf(item) {
+			const version = item?.version;
+			return typeof version === "string" && version ? version : null;
+		}
+		/**
+		* 记入（或更新）某路径的磁盘版本基线；版本为空串时不记（后端不支持版本）。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		* @param version 磁盘版本令牌
+		*/
+		function recordBaseline(scope, path, version) {
+			if (!path || typeof version !== "string" || !version) return;
+			let map = baselines.get(scope);
+			if (!map) {
+				map = /* @__PURE__ */ new Map();
+				baselines.set(scope, map);
+			}
+			const key = String(path).replace(/\\/g, "/");
+			map.delete(key);
+			map.set(key, version);
+			while (map.size > 128) {
+				const oldest = map.keys().next().value;
+				if (oldest === void 0) break;
+				map.delete(oldest);
+			}
+		}
+		/**
+		* 读取某路径的磁盘版本基线。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		* @returns 版本令牌；无基线 → null
+		*/
+		function baselineOf(scope, path) {
+			return baselines.get(scope)?.get(String(path).replace(/\\/g, "/")) ?? null;
+		}
+		/**
+		* 清除某路径的基线（页签关闭、会话销毁时调用）。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		*/
+		function clearBaseline(scope, path) {
+			baselines.get(scope)?.delete(String(path).replace(/\\/g, "/"));
+		}
+		/**
+		* 记入「已读取过内容的磁盘版本」与比结果（同版本不再重复读盘）。
+		* 读盘成功、保存成功、覆盖成功、保留本地推进基线时都要记，避免下一轮白读一次。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		* @param version 版本令牌（空值忽略）
+		* @param equal 读到的磁盘内容是否与当时的缓冲内容相同
+		*/
+		function markReadVersion(scope, path, version, equal = false) {
+			if (!path || typeof version !== "string" || !version) return;
+			let map = readVersions.get(scope);
+			if (!map) {
+				map = /* @__PURE__ */ new Map();
+				readVersions.set(scope, map);
+			}
+			const key = String(path).replace(/\\/g, "/");
+			map.delete(key);
+			map.set(key, {
+				version,
+				equal: equal === true
+			});
+			while (map.size > 128) {
+				const oldest = map.keys().next().value;
+				if (oldest === void 0) break;
+				map.delete(oldest);
+			}
+		}
+		/**
+		* 该磁盘版本是否已读过内容；是则同时给出当时的比对结果（轮询跳过读盘）。
+		* 必须按版本号严格匹配：缓存里可能是更早版本的结果，版本不同一律视为未读。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		* @param version 当前磁盘版本令牌
+		* @returns 未读过该版本 → null；读过 → { equal: 内容是否与缓冲一致 }
+		*/
+		function readVersionOf(scope, path, version) {
+			if (!version) return null;
+			const memo = readVersions.get(scope)?.get(String(path).replace(/\\/g, "/"));
+			if (!memo || memo.version !== version) return null;
+			return { equal: memo.equal };
+		}
+		/**
+		* 清除某路径的已读版本（重载后必须清：下一轮需按新版本重新读盘比对）。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		*/
+		function clearReadVersion(scope, path) {
+			readVersions.get(scope)?.delete(String(path).replace(/\\/g, "/"));
+		}
+		/**
+		* 标记某路径需要用户介入（冲突/文件消失）。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		* @param kind 标记类型
+		*/
+		function markSync(scope, path, kind) {
+			let map = syncState.get(scope);
+			if (!map) {
+				map = /* @__PURE__ */ new Map();
+				syncState.set(scope, map);
+			}
+			const key = String(path).replace(/\\/g, "/");
+			map.delete(key);
+			map.set(key, {
+				path,
+				kind,
+				at: Date.now()
+			});
+			while (map.size > 64) {
+				const oldest = map.keys().next().value;
+				if (oldest === void 0) break;
+				map.delete(oldest);
+			}
+		}
+		/**
+		* 读取某路径的待处理同步标记。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		* @returns 标记；无 → null
+		*/
+		function readSync(scope, path) {
+			return syncState.get(scope)?.get(String(path).replace(/\\/g, "/")) ?? null;
+		}
+		/**
+		* 清除某路径的同步标记（重新加载/保留本地/保存成功后调用）。
+		* @author ddj 2026年09月15号
+		* @param scope 工作区作用域键
+		* @param path 文件路径
+		*/
+		function clearSync(scope, path) {
+			syncState.get(scope)?.delete(String(path).replace(/\\/g, "/"));
+		}
+		//#endregion
+		//#region src/client/ui/useFileWatch.ts
+		/**
+		* dsh-vscode-mode client — 已打开文件的外部改动轮询。
+		*
+		* 背景：RPC 只有客户端拉取通道（无服务端推送），编辑区因此无法感知外部写盘。
+		* 本 hook 以轻量接口补上感知：每 POLL_MS 一次把「全部已打开页签路径」批量交给
+		* host edrv.versions（单请求多条 stat），逐条与本地基线比对后按 watchDecision 的
+		* 判定表把动作回调给 EditorView 执行（IO 与 UI 都在那里）。
+		*
+		* 为何「版本变了还要读内容」：host 版本令牌含 ctime，同字节重写（格式化工具/同步盘/
+		* 编辑器保存策略）也会让它变化，只看版本会把无实质变化的文件反复重载（打断光标与
+		* 滚动）。故版本变化时读一次磁盘内容与缓冲比对，相同则只推进基线；读取结果按版本
+		* 记入 readVersions，同一版本只读一次（陈旧缓冲长期不处理也不会反复拉大文件）。
+		*
+		* 取舍：不使用 fs.watch（句柄/网络盘/长路径兼容性差），纯 stat+按需读轮询跨平台稳定
+		* 且可单测；1.5s 周期对「外部改文件 → 编辑区可见」足够及时，标签页隐藏时整轮跳过。
+		*
+		* 上报规则（避免每轮都弹提示）：
+		* - 首次观测某路径（无标记）：报 conflict/deleted，并落标记；
+		* - 已有标记且仍异常：不再重复回调（提示已在屏上），版本恢复一致时自动清标记；
+		* - 站点不可达（老 host 无此方法/离线）：整轮静默放弃，不清标记、不放大重试。
+		*
+		* 作者 ddj 2026-09-15
+		*/
+		/** 轮询周期：外部改动可见延迟上限（标签页隐藏时跳过整轮）。 */
+		const POLL_MS = 1500;
+		/**
+		* 装配外部改动轮询（挂载即开始，卸载/换会话即停）。
+		* @author ddj 2026年09月15号
+		* @param options 会话/作用域/ref 与回调
+		*/
+		function useFileWatch(options) {
+			const { sessionId, scope, tabsRef, dirtyRef, onReadDisk, onDiskChange } = options;
+			const cbRef = react.useRef(onDiskChange);
+			cbRef.current = onDiskChange;
+			const readRef = react.useRef(onReadDisk);
+			readRef.current = onReadDisk;
+			/** 在途守卫：上一轮未返回（host 卡住）时跳过本轮，避免请求堆积。 */
+			const busyRef = react.useRef(false);
+			react.useEffect(() => {
+				if (!sessionId) return;
+				const context = {
+					sessionId,
+					scope,
+					dirtyRef,
+					onReadDisk: (path) => readRef.current ? readRef.current(path) : Promise.resolve(null),
+					onChange: (change) => cbRef.current(change)
+				};
+				/**
+				* 一轮观测：批量取版本 → 逐条判定 → 回调。
+				* @author ddj 2026年09月15号
+				*/
+				const poll = async () => {
+					if (busyRef.current) return;
+					if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+					const paths = (tabsRef.current ?? []).filter((p) => typeof p === "string" && p);
+					if (!paths.length) return;
+					busyRef.current = true;
+					try {
+						const res = await rpc("edrv.versions", {
+							sessionId,
+							paths
+						});
+						if (!res || !res.ok || !Array.isArray(res.items)) return;
+						for (const item of res.items) {
+							if (!item || !item.path) continue;
+							await evaluate(item, context);
+						}
+					} catch (error) {} finally {
+						busyRef.current = false;
+					}
+				};
+				const timer = window.setInterval(() => {
+					poll();
+				}, POLL_MS);
+				poll();
+				return () => window.clearInterval(timer);
+			}, [sessionId, scope]);
+		}
+		/**
+		* 单条判定：按 watchDecision 的判定表决定动作，必要时清/落台账标记。
+		* 版本变化时先读磁盘内容（同版本只读一次）再定分支：内容相同只推进基线，
+		* 内容不同且缓冲脏才升级为冲突提示。
+		*
+		* 导出原因：这是「观测 → 动作派发」的关键落点（三条分支各自的副作用不轻），
+		* 用假 fetch + 假 context 可直接驱动它做端到端断言，无需渲染 React 树。
+		* 仅供测试与同模块内 poll 调用，不属于对外 API。
+		* @author ddj 2026年09月15号
+		* @param item host 版本条目
+		* @param context 轮询上下文（作用域/脏标记/读盘/回调）
+		*/
+		async function evaluate(item, context) {
+			const path = item.path;
+			const scope = context.scope;
+			const baseline = baselineOf(scope, path);
+			const version = versionOf(item);
+			const missing = item.type === "missing";
+			const dirty = context.dirtyRef.current?.[path] === true;
+			if (!baseline) {
+				recordBaseline(scope, path, version);
+				return;
+			}
+			const versionChanged = version !== baseline;
+			if (!versionChanged && !missing) {
+				clearSync(scope, path);
+				return;
+			}
+			const mode = await inspect(path, version, context);
+			if (mode.known && mode.equal) {
+				recordBaseline(scope, path, version);
+				markReadVersion(scope, path, version, true);
+				clearSync(scope, path);
+				return;
+			}
+			const action = syncDecision({
+				hasBaseline: true,
+				versionChanged,
+				missing,
+				clean: !dirty,
+				contentEqual: mode.equal
+			});
+			if (action === "sync-silent") {
+				clearSync(scope, path);
+				if (mode.known) {
+					recordBaseline(scope, path, version);
+					markReadVersion(scope, path, version, false);
+				} else clearReadVersion(scope, path);
+				context.onChange({
+					path,
+					kind: "modified"
+				});
+				return;
+			}
+			if (action === "none") return;
+			const kind = action === "deleted" ? "deleted" : "conflict";
+			const flagged = readSync(scope, path);
+			if (flagged && flagged.kind === kind) return;
+			markSync(scope, path, kind);
+			context.onChange({
+				path,
+				kind
+			});
+		}
+		/**
+		* 读盘并与调用方缓冲比对（脏缓冲也需要：内容相同就不该报冲突）。
+		* 同版本只读一次：已读过该版本的路径直接回放当时的比对结果（不重复拉取大文件）。
+		* @author ddj 2026年09月15号
+		* @param path 文件路径
+		* @param version 当前磁盘版本（可为 null）
+		* @param context 轮询上下文
+		* @returns { known: 是否拿到磁盘内容, equal: 内容是否与缓冲一致 }
+		*/
+		async function inspect(path, version, context) {
+			if (!version) return {
+				known: false,
+				equal: false
+			};
+			const cached = readVersionOf(context.scope, path, version);
+			if (cached) return {
+				known: true,
+				equal: cached.equal
+			};
+			const disk = await context.onReadDisk?.(path).catch(() => null);
+			if (!disk) return {
+				known: false,
+				equal: false
+			};
+			markReadVersion(context.scope, path, version, disk.equal);
+			return {
+				known: true,
+				equal: disk.equal
+			};
+		}
 		//#endregion
 		//#region src/client/pdf/pdfLoader.ts
 		/**
@@ -5368,7 +5762,7 @@ window.__ModuleLoader__.load({
 			if (!uri) return "";
 			if (uri.startsWith("edrv://")) return uri;
 			const path = relativeLspPath(uri, root);
-			return "edrv:///" + encodeURI(path);
+			return "edrv:///" + encodeURI(String(path ?? "").replace(/^\/+/, ""));
 		}
 		/**
 		* 归一化 Location 的 uri → 工作区路径（剥离 scheme，不补盘符）。
@@ -7188,6 +7582,8 @@ window.__ModuleLoader__.load({
 			activeRef.current = active;
 			const tabsRef = react.default.useRef([]);
 			tabsRef.current = tabs;
+			const tabPathsRef = react.default.useRef([]);
+			tabPathsRef.current = tabs.map((t) => t.path);
 			const dirtyRef = react.default.useRef({});
 			dirtyRef.current = dirtyMap;
 			const tabsHostRef = react.default.useRef(null);
@@ -7206,6 +7602,9 @@ window.__ModuleLoader__.load({
 			const doSaveRef = react.default.useRef(null);
 			const onEditRef = react.default.useRef(null);
 			const saveViewStateRef = react.default.useRef(null);
+			const revRef = react.default.useRef({});
+			const diskChangeRef = react.default.useRef(null);
+			const [diskFlag, setDiskFlag] = react.default.useState(null);
 			const diffRendererRef = react.default.useRef(null);
 			const layoutRef = react.default.useRef(layout);
 			layoutRef.current = layout;
@@ -7389,6 +7788,10 @@ window.__ModuleLoader__.load({
 					pdfCtlRef.current.delete(path);
 				}
 				pdfB64CacheRef.current.delete(path);
+				clearBaseline(scope, path);
+				clearReadVersion(scope, path);
+				clearSync(scope, path);
+				delete revRef.current[path];
 			};
 			/**
 			* 提交关闭结果：一次性更新页签与活动页签（补位规则见 tabActions.applyClose）。
@@ -7480,19 +7883,33 @@ window.__ModuleLoader__.load({
 			/**
 			* 加载文件内容（对齐 VSCode model 复用：会话内已打开的 model 直接秒显，
 			* 后台静默 RPC 校验防陈旧；首次打开走原读取流程）。
-			* @author ddj 2026年08月28号
+			* 每条成功分支都记下磁盘版本基线：外部改动轮询据此判断缓冲是否已陈旧，
+			* 保存时作为版本守卫令牌随 edrv.save 回传（读后被外部改过则拒绝写入）。
+			* @author ddj 2026年08月28号 / 2026年09月15号
 			* @param path 文件路径
 			* @param sid 会话 id
 			* @param force 强制走 RPC（reloadFile 用，跳过 model 复用）
+			* @param version 已知磁盘版本（缺省走 RPC 返回值）
 			*/
-			const loadContent = (path, sid, force) => {
+			const loadContent = (path, sid, force, version) => {
 				const seq = ++loadSeqRef.current;
+				/**
+				* 记下磁盘版本基线；markRead=true 表示本次真的从磁盘读了内容
+				* （已读版本台账随之失效，下一轮轮询按新版本重新比对）。
+				*/
+				const mark = (ver, markRead) => {
+					if (typeof ver !== "string" || !ver) return;
+					revRef.current[path] = ver;
+					recordBaseline(scope, path, ver);
+					clearSync(scope, path);
+					if (markRead === true) clearReadVersion(scope, path);
+				};
 				if (isImagePath(path) && !svgTextRef.current.has(path)) {
-					loadImage(path, sid, seq);
+					loadImage(path, sid, seq, version);
 					return;
 				}
 				if (isPdfPath(path)) {
-					loadPdf(path, sid, seq, force === true);
+					loadPdf(path, sid, seq, force === true, version);
 					return;
 				}
 				const cachedModel = force ? null : modelsRef.current.get(path);
@@ -7509,6 +7926,7 @@ window.__ModuleLoader__.load({
 						path
 					}).then((res) => {
 						if (seq !== loadSeqRef.current || path !== active) return;
+						if (res && res.ok) mark(res.version);
 						if (res && res.ok && res.content !== cachedModel.getValue()) {
 							saveViewState(path);
 							setContent(res.content);
@@ -7528,6 +7946,7 @@ window.__ModuleLoader__.load({
 				}).then((res) => {
 					if (seq !== loadSeqRef.current || path !== active) return;
 					if (res && res.ok) {
+						mark(res.version, true);
 						setContent(res.content);
 						setContentPath(path);
 						setLoadStage((prev) => ({
@@ -7552,12 +7971,13 @@ window.__ModuleLoader__.load({
 			};
 			/**
 			* 加载图片文件为 data URL（编辑区只读预览）；失败走 loadError 面板（重试经 loadContent 分派回此）。
-			* @author ddj 2026年09月08号
+			* @author ddj 2026年09月08号 / 2026年09月15号
 			* @param path 图片文件路径
 			* @param sid 会话 id
 			* @param seq 加载序号（过期响应丢弃）
+			* @param version 已知磁盘版本（图片同走外部改动轮询，读到新版本即重取）
 			*/
-			const loadImage = (path, sid, seq) => {
+			const loadImage = (path, sid, seq, version) => {
 				setImageSrc(null);
 				setImgSize(null);
 				setImgBroken(false);
@@ -7578,6 +7998,9 @@ window.__ModuleLoader__.load({
 							setStatus("读取失败");
 							return;
 						}
+						const imgVersion = res.version ?? version;
+						recordBaseline(scope, path, imgVersion);
+						clearReadVersion(scope, path);
 						setImageSrc(dataUrlOf(res.content, res.mime));
 						setLoadStage({
 							progress: 100,
@@ -7607,8 +8030,9 @@ window.__ModuleLoader__.load({
 			* @param sid 会话 id
 			* @param seq 加载序号（过期响应丢弃）
 			* @param force true=绕过缓存强制 RPC 重读（刷新按钮）
+			* @param version 已知磁盘版本（外部改动轮询触发时带入）
 			*/
-			const loadPdf = (path, sid, seq, force) => {
+			const loadPdf = (path, sid, seq, force, version) => {
 				setPdfBytes(null);
 				setLoadStage({
 					progress: monaco ? 72 : 12,
@@ -7634,6 +8058,9 @@ window.__ModuleLoader__.load({
 				}).then((res) => {
 					if (seq !== loadSeqRef.current || path !== active) return;
 					if (res && res.ok && res.encoding === "base64") {
+						const pdfVersion = res.version ?? version;
+						recordBaseline(scope, path, pdfVersion);
+						clearReadVersion(scope, path);
 						cache.set(path, res.content);
 						while (cache.size > 6) cache.delete(cache.keys().next().value);
 						setPdfBytes(base64ToBytes(res.content));
@@ -7668,6 +8095,66 @@ window.__ModuleLoader__.load({
 					window.removeEventListener("edrv:refresh", onRefresh);
 				};
 			}, [sessionId]);
+			/**
+			* 展示外部同步提示（按路径+类型去重：同一文件重复回调不重置已关闭的提示）。
+			* @author ddj 2026年09月15号
+			* @param flag 同步标记
+			*/
+			const markDiskFlag = (flag) => {
+				setDiskFlag((prev) => prev && prev.path === flag.path && prev.kind === flag.kind ? prev : flag);
+			};
+			/**
+			* 外部改动落地：干净缓冲直接刷入（含差异标记重算），脏缓冲只提示不覆盖。
+			* 经 ref 暴露给轮询 hook（hook 只负责观测，IO/UI 全在这里）。
+			* @author ddj 2026年09月15号
+			* @param change 轮询判定出的外部变更
+			*/
+			const onDiskChange = (change) => {
+				if (!change || !change.path) return;
+				emitFileChanged(change.path);
+				if (change.kind === "modified") {
+					loadContent(change.path, sessionId, true);
+					clearSync(scope, change.path);
+					setDiskFlag((prev) => prev && prev.path === change.path ? null : prev);
+					setStatus("已同步外部修改 " + (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8));
+					emitRefresh();
+					return;
+				}
+				const kind = change.kind === "deleted" ? "deleted" : "conflict";
+				markDiskFlag(readSync(scope, change.path) ?? {
+					path: change.path,
+					kind,
+					at: Date.now()
+				});
+				setStatus(kind === "deleted" ? "文件已被外部删除" : "外部已修改（未保存的编辑保留）");
+			};
+			diskChangeRef.current = onDiskChange;
+			/**
+			* 版本变化时读磁盘并与缓冲比对：内容相同 → 只推进基线（不做无意义重载）；
+			* 内容不同 → 由判定表决定自动刷入还是冲突提示。
+			* @author ddj 2026年09月15号
+			* @param path 文件路径
+			* @returns 比对结果；模型不可用/读失败 → null（按「需要重载」处理）
+			*/
+			const readDiskCompare = (path) => {
+				const model = modelsRef.current?.get(path);
+				if (!model || typeof model.getValue !== "function") return Promise.resolve(null);
+				return rpc("edrv.read", {
+					sessionId,
+					path
+				}).then((res) => {
+					if (!res || !res.ok) return null;
+					return { equal: res.content === model.getValue() };
+				}).catch(() => null);
+			};
+			useFileWatch({
+				sessionId,
+				scope,
+				tabsRef: tabPathsRef,
+				dirtyRef,
+				onReadDisk: readDiskCompare,
+				onDiskChange: (change) => diskChangeRef.current?.(change)
+			});
 			react.default.useEffect(() => {
 				const publishLsp = (servers) => setLspServers(Array.isArray(servers) ? servers : []);
 				const unsubscribe = onLspProgress(publishLsp);
@@ -8174,7 +8661,7 @@ window.__ModuleLoader__.load({
 				const cache = modelsRef.current;
 				let model = cache.get(path);
 				if (!model) {
-					const uri = window.monaco.Uri.parse("edrv:///" + encodeURI(path));
+					const uri = window.monaco.Uri.parse("edrv:///" + encodeURI(String(path ?? "").replace(/^\/+/, "")));
 					model = window.monaco.editor.getModel(uri) || window.monaco.editor.createModel(text ?? "", langOf(path), uri);
 					rememberModel(cache, path, model);
 				} else if (text !== void 0 && model.getValue() !== text) {
@@ -8188,13 +8675,24 @@ window.__ModuleLoader__.load({
 			* 提交待执行的防抖保存（**真正执行保存**，不是取消）。
 			* 语义与缺陷背景见 saveDebounce.ts：`schedule` 的返回值是只 clearTimeout 的 disposer，
 			* 旧实现把它当「立即保存」调用 → 防抖窗口内切页签/关闭文件会静默丢改动。
-			* @author ddj 2026年09月11号
+			* 外部改动待处理（冲突/文件被删）时跳过：切页签/卸载不得用陈旧缓冲覆盖磁盘，
+			* 缓冲内容仍在 model 里，用户处理完冲突后再保存。
+			* @author ddj 2026年09月11号 / 2026年09月15号
+			* @param path 目标路径（缺省 = 当前活动文件）
+			* @returns 是否执行了保存
 			*/
-			const flushSave = () => {
+			const flushSave = (path) => {
+				const target = path ?? active;
+				if (target && readSync(scope, target)) return false;
 				saveTimerRef.current?.flush();
+				return true;
 			};
 			const doSave = (silent) => {
 				if (!active) return;
+				if (silent && readSync(scope, active)) {
+					setStatus("外部已修改（未保存的编辑保留）");
+					return;
+				}
 				if (isPdfPath(active)) {
 					const ctl = pdfCtlRef.current.get(active);
 					if (!ctl) {
@@ -8215,30 +8713,49 @@ window.__ModuleLoader__.load({
 					return;
 				}
 				const text = ed.getValue();
+				const path = active;
 				if (!silent) setStatus("保存中…");
-				savingRef.current.add(active);
+				savingRef.current.add(path);
+				const rev = revRef.current[path];
 				rpc("edrv.save", {
 					sessionId,
-					path: active,
-					content: text
+					path,
+					content: text,
+					rev: typeof rev === "string" && rev ? rev : void 0
 				}).then((res) => {
 					if (res && res.ok) {
-						setStatus("已保存 " + (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8));
+						if (res.rev) revRef.current[path] = res.rev;
+						recordBaseline(scope, path, res.rev);
+						markReadVersion(scope, path, res.rev, true);
+						clearSync(scope, path);
 						setContent(text);
-						setContentPath(active);
-						setDirtyMap((d) => Object.assign({}, d, { [active]: false }));
+						setContentPath(path);
+						setDirtyMap((d) => Object.assign({}, d, { [path]: false }));
+						if (path === active) {
+							setStatus("已保存 " + (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8));
+							setDiskFlag((prev) => prev && prev.path === path ? null : prev);
+						}
 						refreshRecords();
 						emitRefresh();
-						if (/\.code-snippets$/i.test(active)) window.dispatchEvent(new CustomEvent("edrv:snippets-changed"));
-					} else {
-						setStatus("保存失败");
-						setError(res?.error ? String(res.error) : "保存失败");
+						if (/\.code-snippets$/i.test(path)) window.dispatchEvent(new CustomEvent("edrv:snippets-changed"));
+						return;
+					}
+					if (res && res.conflict) {
+						markDiskFlag({
+							path,
+							kind: "conflict",
+							at: Date.now()
+						});
+						setStatus("保存被拒：文件已被外部修改");
+						return;
 					}
+					setStatus("保存失败");
+					setError(res?.error ? String(res.error) : "保存失败");
 				}).catch((e) => {
 					setStatus("保存失败");
 					setError("保存异常:" + String(e));
 				}).finally(() => {
-					savingRef.current.delete(active);
+					savingRef.current.delete(path);
 				});
 			};
 			doSaveRef.current = doSave;
@@ -8249,12 +8766,17 @@ window.__ModuleLoader__.load({
 			* 这里再处理**仍标脏**的页签 —— 包括活动页签（其保存可能在途或失败），
 			* 用 model 里的当前文本补一次，保证关闭前内容一定写到磁盘。
 			* 保存失败只保留脏标记（不丢用户编辑），并在状态栏给出提示。
-			* @author ddj 2026年09月11号
+			* 外部改动待处理的页签跳过（版本守卫下必被拒绝；缓冲仍在 model 里，不丢内容）。
+			* @author ddj 2026年09月11号 / 2026年09月15号
 			* @param paths 即将关闭的页签路径
 			*/
 			const persistDirty = (paths) => {
 				for (const path of paths) {
 					if (!dirtyRef.current[path]) continue;
+					if (readSync(scope, path)) {
+						setStatus("未落盘（外部已修改）：" + baseNameOf(path));
+						continue;
+					}
 					if (savingRef.current.has(path)) continue;
 					const pdfCtl = pdfCtlRef.current.get(path);
 					if (pdfCtl) {
@@ -8268,12 +8790,19 @@ window.__ModuleLoader__.load({
 					}
 					const content = model.getValue();
 					savingRef.current.add(path);
+					const rev = revRef.current[path];
 					rpc("edrv.save", {
 						sessionId,
 						path,
-						content
+						content,
+						rev: typeof rev === "string" && rev ? rev : void 0
 					}).then((res) => {
-						if (res && res.ok) setDirtyMap((d) => Object.assign({}, d, { [path]: false }));
+						if (res && res.ok) {
+							if (res.rev) revRef.current[path] = res.rev;
+							recordBaseline(scope, path, res.rev);
+							markReadVersion(scope, path, res.rev, true);
+							setDirtyMap((d) => Object.assign({}, d, { [path]: false }));
+						}
 					}).catch((e) => dbg(sessionId, "关闭前落盘失败：" + path + " · " + String(e))).finally(() => {
 						savingRef.current.delete(path);
 					});
@@ -8283,6 +8812,10 @@ window.__ModuleLoader__.load({
 				if (!editorRef.current || !active) return;
 				setDirtyMap((d) => Object.assign({}, d, { [active]: true }));
 				setStatus("编辑中…");
+				if (readSync(scope, active)) {
+					setStatus("外部已修改（未保存的编辑保留）");
+					return;
+				}
 				saveTimerRef.current?.arm(schedule, 700, () => doSave(true));
 			};
 			onEditRef.current = onEdit;
@@ -8634,12 +9167,80 @@ window.__ModuleLoader__.load({
 				if (sum.pendingFiles.some((file) => sameFile(file.path, active))) gotoFile(1);
 				else openFile(sum.pendingFiles[0].path, true);
 			};
+			/**
+			* 重新从磁盘加载当前文件（工具栏 ⟳ / 冲突提示「重新加载」/ 差异决策后刷新）。
+			* 一律强制重读（跳过 model 复用）：这才是「用户要看到磁盘真实内容」的语义。
+			* @author ddj 2026年09月15号
+			* @param skipStale 差异记录刷新是否跳过 stale 清理
+			*/
 			const reloadFile = (skipStale) => {
 				if (!active) return;
-				loadContent(active, sessionId, true);
+				const path = active;
+				loadContent(path, sessionId, true);
+				clearSync(scope, path);
+				setDiskFlag((prev) => prev && prev.path === path ? null : prev);
 				refreshRecords(skipStale === true);
 			};
 			/**
+			* 冲突处理：用编辑器内容覆盖磁盘（在缓冲内容为权威时用户显式选择）。
+			* 覆盖不带版本令牌（host 无条件写入），成功后以返回的新版本重记基线。
+			* @author ddj 2026年09月15号
+			*/
+			const overwriteDisk = () => {
+				const path = diskFlag?.path;
+				const model = path ? modelsRef.current.get(path) : null;
+				if (!path || !model) {
+					setStatus("无法覆盖：文件未打开");
+					return;
+				}
+				rpc("edrv.save", {
+					sessionId,
+					path,
+					content: model.getValue()
+				}).then((res) => {
+					if (res && res.ok) {
+						if (res.rev) revRef.current[path] = res.rev;
+						recordBaseline(scope, path, res.rev);
+						markReadVersion(scope, path, res.rev, true);
+						clearSync(scope, path);
+						setDirtyMap((d) => Object.assign({}, d, { [path]: false }));
+						setDiskFlag((prev) => prev && prev.path === path ? null : prev);
+						setStatus("已覆盖磁盘");
+						emitRefresh();
+						return;
+					}
+					setStatus("覆盖失败");
+					setError(res?.error ? String(res.error) : "覆盖失败");
+				}).catch((e) => setError("覆盖异常:" + String(e)));
+			};
+			/**
+			* 冲突处理：保留本地编辑（关掉提示），磁盘内容不取用。
+			* 基线推进到磁盘当前版本，避免同一外部改动被反复提示；缓冲仍标脏，
+			* 之后的手工保存会被版本守卫拒绝并再次给出选择。
+			* @author ddj 2026年09月15号
+			*/
+			const keepLocal = () => {
+				const path = diskFlag?.path;
+				if (!path) return;
+				rpc("edrv.versions", {
+					sessionId,
+					paths: [path]
+				}).then((res) => {
+					const item = res && res.ok && Array.isArray(res.items) ? res.items[0] : null;
+					if (item && item.version) {
+						recordBaseline(scope, path, item.version);
+						markReadVersion(scope, path, item.version, false);
+						revRef.current[path] = item.version;
+					}
+					clearSync(scope, path);
+					setDiskFlag((prev) => prev && prev.path === path ? null : prev);
+					setStatus("已保留本地编辑（磁盘内容未取用）");
+				}).catch(() => {
+					clearSync(scope, path);
+					setDiskFlag(null);
+				});
+			};
+			/**
 			* SVG 在图片预览与文本编辑间切换（按路径记忆；重载分派随集合状态自动路由）。
 			* @author ddj 2026年09月08号
 			* @param path SVG 文件路径
@@ -9208,7 +9809,20 @@ window.__ModuleLoader__.load({
 				},
 				title: aiState === "error" && aiNote ? aiNote : "AI 自动补全（设置页「AI 补全」可配置）"
 			}, react.default.createElement("span", { className: "edrv-lsp-status-dot " + (!aiEnabled ? "idle" : aiDotCls) }), react.default.createElement("span", { className: "edrv-sp-lsp" }, aiLabel)) : null;
-			const statusBar = lspSeg || aiSeg ? react.default.createElement("div", { className: "edrv-statusbar" }, lspSeg, aiSeg) : null;
+			const diskSeg = active && diskFlag && sameFile(diskFlag.path, active) ? react.default.createElement("span", {
+				className: "edrv-status-seg",
+				style: {
+					display: "inline-flex",
+					alignItems: "center",
+					gap: "6px",
+					minWidth: 0,
+					flex: "0 0 auto",
+					cursor: "pointer"
+				},
+				title: "磁盘内容已被外部修改：重新加载 = 取磁盘版本；保留本地 = 继续编辑（保存时会被版本守卫拒绝）",
+				onClick: () => reloadFile()
+			}, react.default.createElement("span", { className: "edrv-sp-lsp" }, diskFlag.kind === "deleted" ? "⚠ 外部已删除" : "⚠ 外部已修改")) : null;
+			const statusBar = lspSeg || aiSeg || diskSeg ? react.default.createElement("div", { className: "edrv-statusbar" }, lspSeg, diskSeg, aiSeg) : null;
 			const navBackTarget = navRef.current.peekBack();
 			const navForwardTarget = navRef.current.peekForward();
 			const navNameOf = (entry) => entry && entry.path ? String(entry.path).split(/[\\/]/).pop() : "";
@@ -9245,6 +9859,43 @@ window.__ModuleLoader__.load({
 				sessionId,
 				onOpen: (p) => openFile(p, false)
 			}));
+			/**
+			* 外部同步提示条（冲突 / 文件被删）：仅在提示对象就是当前活动文件时显示。
+			* 不复用 error 面板：内容照常可编辑，提示条只是把「磁盘已变、怎么处理」摆在眼前。
+			* @author ddj 2026年09月15号
+			* @returns 提示条元素或 null
+			*/
+			const diskBanner = () => {
+				const flag = diskFlag && sameFile(diskFlag.path, active) ? diskFlag : null;
+				if (!flag) return null;
+				const deleted = flag.kind === "deleted";
+				const text = deleted ? "该文件已被外部删除（缓冲内容保留，保存会失败）" : "磁盘内容已被外部修改（当前有未保存编辑，未覆盖）";
+				return react.default.createElement("div", {
+					className: "edrv-diskbar",
+					style: {
+						display: "flex",
+						alignItems: "center",
+						gap: "8px",
+						flexShrink: 0,
+						padding: "4px 8px",
+						fontSize: "12px",
+						background: "var(--dsw-alias-bg-layer-1, rgba(255,193,7,.12))",
+						borderBottom: "1px solid var(--dsw-alias-border-l1, rgba(255,193,7,.35))"
+					}
+				}, react.default.createElement("span", { title: flag.path }, "⚠ " + text), react.default.createElement("span", { style: { flex: 1 } }), react.default.createElement("button", {
+					className: "edrv-pill edrv-pill-keep",
+					title: "放弃缓冲内容，重新加载磁盘版本",
+					onClick: () => reloadFile()
+				}, "重新加载"), deleted ? null : react.default.createElement("button", {
+					className: "edrv-pill edrv-pill-undo",
+					title: "用编辑器内容覆盖磁盘（放弃磁盘上的外部修改）",
+					onClick: overwriteDisk
+				}, "覆盖磁盘"), deleted ? null : react.default.createElement("button", {
+					className: "edrv-pill edrv-pill-ghost",
+					title: "保留编辑器内容，不取用磁盘版本",
+					onClick: keepLocal
+				}, "保留本地"));
+			};
 			const otherFiles = sum.pendingFiles.filter((f) => f.path !== active);
 			/**
 			* 渲染编辑器/文件加载进度面板。
@@ -9472,7 +10123,7 @@ window.__ModuleLoader__.load({
 					flexDirection: "column",
 					overflow: "hidden"
 				}
-			}, pathBar, tabRow, sideHintEl, editorArea, statusBar);
+			}, pathBar, tabRow, sideHintEl, diskBanner(), editorArea, statusBar);
 			const editorRow = react.default.createElement("div", { className: "edrv-editor-row" }, sidebarPanels ? react.default.createElement(SidebarView, {
 				registry: sidebarPanels,
 				ctx: sidebarCtx,
@@ -10269,14 +10920,14 @@ window.__ModuleLoader__.load({
 		*/
 		function markEditorMounted() {
 			mountEpoch += 1;
-			markEditorActive$1(true);
+			markEditorActive(true);
 		}
 		/**
 		* 直接设置激活标记（正文卸载延迟判定用；测试 also 用作状态编排入口）。
 		* @author ddj 2026年09月09号
 		* @param active 是否激活
 		*/
-		function markEditorActive$1(active) {
+		function markEditorActive(active) {
 			editorTabActive = active;
 		}
 		/**
@@ -13576,6 +14227,8 @@ window.__ModuleLoader__.load({
 		const REVEAL_HIGHLIGHT_MS = 2e3;
 		const REVEAL_RETRY_MAX = 6;
 		const REVEAL_RETRY_MS = 120;
+		/** 外部文件变化重列去抖：一轮外部批量写入（如 agent 连写多文件）合并为一次重列。 */
+		const FILE_CHANGE_DEBOUNCE_MS = 400;
 		/**
 		* 目录图标元素（官方 IconFolderOpen16/Close16）。
 		* @author ddj 2026年09月10号
@@ -13669,6 +14322,11 @@ window.__ModuleLoader__.load({
 			const revealTryRef = react.default.useRef(0);
 			const revealInTreeRef = react.default.useRef(null);
 			const treeRef = react.default.useRef(null);
+			const reloadDirRef = react.default.useRef(null);
+			const changedTimerRef = react.default.useRef(null);
+			const changedRelRef = react.default.useRef(/* @__PURE__ */ new Set());
+			const dirsMapRef = react.default.useRef(null);
+			dirsMapRef.current = loadDir;
 			/** 渲染取数：内存态 → 本地条目缓存 → null（显示加载态）。 */
 			const entriesOf = (rel) => dirsRef.current[rel] ?? entriesCacheGet(scope, rel) ?? null;
 			/** 预取子目录：≤4 个、排除重型目录、缓存新鲜跳过、已加载跳过、不级联。 */
@@ -13794,6 +14452,45 @@ window.__ModuleLoader__.load({
 				});
 			};
 			refreshRef.current = refresh;
+			reloadDirRef.current = loadDir;
+			/**
+			* 磁盘文件变化（外部写入/删除/改名）：把变化路径的父目录并入待重列集合，
+			* 去抖合并后对「已展开且存在」的目录强制重列（force 跳过 host 索引命中）。
+			* host 侧 fileVersions 已顺手失效目录树缓存，这里补上「已渲染行」的即时刷新。
+			* @author ddj 2026年09月15号
+			* @param path 发生变化的文件路径（工作区相对；绝对路径按最长已展开祖先匹配）
+			*/
+			const onFileChanged = (path) => {
+				if (typeof path !== "string" || !path) return;
+				const rel = path.replace(/\\/g, "/").replace(/^\.\//, "");
+				const parts = rel.split("/").filter(Boolean);
+				if (parts.length > 1) changedRelRef.current.add(parts.slice(0, -1).join("/"));
+				for (const dir of ancestorDirsOf(rel)) if (expandedRef.current[dir] === true) changedRelRef.current.add(dir);
+				if (changedTimerRef.current) return;
+				changedTimerRef.current = window.setTimeout(() => {
+					changedTimerRef.current = null;
+					const targets = [...changedRelRef.current];
+					changedRelRef.current.clear();
+					for (const dir of targets) {
+						if (dir !== "" && expandedRef.current[dir] !== true) continue;
+						reloadDirRef.current?.(dir, {
+							force: true,
+							prefetch: false
+						});
+					}
+				}, FILE_CHANGE_DEBOUNCE_MS);
+			};
+			react.default.useEffect(() => {
+				const handler = (event) => onFileChanged(event?.detail?.path);
+				window.addEventListener("edrv:file-changed", handler);
+				return () => {
+					window.removeEventListener("edrv:file-changed", handler);
+					if (changedTimerRef.current) {
+						clearTimeout(changedTimerRef.current);
+						changedTimerRef.current = null;
+					}
+				};
+			}, []);
 			react.default.useEffect(() => {
 				tokensRef.current = {};
 				setDirs({});