feat: 添加文件改动的防抖处理，优化同步逻辑以合并连续编辑

Author: ssbeatty

README.md

@@ -81,7 +81,7 @@ For easiest local development, keep this repository inside:
 1. Open **Settings → Obsidian RAG Integration → LightRAG**.
 2. Enable LightRAG and set the server URL, for example `http://192.168.50.209:9621`.
 3. Select **Test connection** to verify `/health`.
-4. Keep **Auto sync Markdown** enabled or select **Start sync** to sync immediately. Renames and deletions remove the corresponding LightRAG document, and a full **Start sync** also reconciles the server by removing orphaned documents whose vault files no longer exist (only documents previously created by this plugin are touched).
+4. Keep **Auto sync Markdown** enabled or select **Start sync** to sync immediately. Edits are debounced (continuous typing is coalesced into a single re-sync after you pause, with a hard cap so a long editing session still syncs periodically), and the periodic scan defers to files you are actively editing to avoid re-processing intermediate states. Renames and deletions remove the corresponding LightRAG document, and a full **Start sync** also reconciles the server by removing orphaned documents whose vault files no longer exist (only documents previously created by this plugin are touched).
 5. In **Vault chat** mode, the default answer mode calls LightRAG `/query/data` for retrieval, then uses the plugin's selected chat model to generate the final answer. You can switch to direct LightRAG `/query/stream` generation in the LightRAG query settings.
 
 LightRAG sync only sends Markdown files. New or changed files are submitted in batches of up to 3 texts per `/documents/texts` request. When a synced file changes, the plugin deletes the previously tracked LightRAG document and inserts the updated text because the current LightRAG API does not expose an in-place document update endpoint. The plugin listens for vault file events, scans once on startup, and can periodically rescan the vault by mtime to catch missed events. The LightRAG exclude list supports exact paths, folder prefixes such as `private/`, and simple glob rules such as `archive/**/*.md`; excluded files are not synced and previously synced excluded files are removed from LightRAG on the next scan. LightRAG chat defaults to `/query/data` retrieval plus plugin-model generation, strips generated inline References sections, and shows a limited de-duplicated source list based on retrieved chunks. The LightRAG settings tab refreshes pipeline and tracked document status automatically while it is open.

src/lightrag/LightRAGSyncService.ts

@@ -9,6 +9,10 @@ const STORE_PATH = `${STORE_DIR}/lightrag-sync.json`;
 const POLL_INTERVAL_MS = 1500;
 const PIPELINE_WAIT_MS = 5 * 60 * 1000;
 const INSERT_BATCH_SIZE = 3;
+// 文件改动后等待这么久(无新改动)才真正入队同步,合并连续编辑
+const DEBOUNCE_MS = 10000;
+// 连续编辑时的强制上限:即使一直在改,距首次改动超过此时长也会落一次同步
+const DEBOUNCE_MAX_WAIT_MS = 300 * 1000;
 
 type QueueItem =
 	| { type: 'sync'; filePath: string; force: boolean }
@@ -57,6 +61,8 @@ export class LightRAGSyncService {
 	private queuedKeys = new Set<string>();
 	private processing = false;
 	private saveTimer: ReturnType<typeof setTimeout> | null = null;
+	private debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+	private debounceFirstSeen = new Map<string, number>();
 	private idleResolvers: Array<() => void> = [];
 	private lastError: string | null = null;
 	private pipelineStatus: LightRAGPipelineStatus | null = null;
@@ -78,6 +84,7 @@ export class LightRAGSyncService {
 		this.stopped = true;
 		this.queue = [];
 		this.queuedKeys.clear();
+		this.clearAllDebounce();
 		this.resolveIdle();
 	}
 
@@ -128,6 +135,12 @@ export class LightRAGSyncService {
 		if (!this.config.enabled) return;
 
 		const files = this.app.vault.getMarkdownFiles();
+		// 防御启动竞态:文件列表为空却已有同步记录,几乎一定是 vault 尚未就绪。
+		// 此时执行下面的孤儿清理会把所有已同步文档误删,跳过本轮,留待就绪后再同步。
+		if (files.length === 0 && Object.keys(this.records).length > 0) {
+			Logger.warn('[LightRAGSync] queueAll 跳过:文件列表为空但存在同步记录,疑似 vault 未就绪');
+			return;
+		}
 		const livePaths = new Set(files.map(file => normalizePath(file.path)));
 
 		for (const record of Object.values(this.records)) {
@@ -174,19 +187,21 @@ export class LightRAGSyncService {
 	handleCreateOrModify(file: TFile): void {
 		if (!this.config.enabled || !this.config.autoSync || !this.isMarkdown(file)) return;
 		if (this.isExcludedPath(file.path)) return;
-		this.enqueue({ type: 'sync', filePath: file.path, force: false });
-		this.processQueue();
+		this.scheduleDebouncedSync(file.path);
 	}
 
 	handleDelete(filePath: string): void {
 		if (!this.config.enabled || !this.config.autoSync) return;
+		this.cancelDebounce(filePath);
 		if (!this.records[filePath]) return;
 		this.enqueue({ type: 'delete', filePath });
 		this.processQueue();
 	}
 
 	handleRename(file: TFile, oldPath: string): void {
 		if (!this.config.enabled || !this.config.autoSync) return;
+		this.cancelDebounce(oldPath);
+		this.cancelDebounce(file.path);
 		if (this.records[oldPath]) {
 			this.enqueue({ type: 'delete', filePath: oldPath });
 		}
@@ -196,6 +211,47 @@ export class LightRAGSyncService {
 		this.processQueue();
 	}
 
+	/**
+	 * 将文件改动延迟入队,合并连续编辑。带 maxWait 上限:即使一直在改,
+	 * 距首次改动超过 DEBOUNCE_MAX_WAIT_MS 也会强制落一次同步。
+	 * 处于 debounce 窗口内的文件由 shouldSync 跳过,避免定时扫盘抢先同步中间态。
+	 */
+	private scheduleDebouncedSync(filePath: string): void {
+		if (this.stopped) return;
+		const now = Date.now();
+		const firstSeen = this.debounceFirstSeen.get(filePath) ?? now;
+		if (!this.debounceFirstSeen.has(filePath)) {
+			this.debounceFirstSeen.set(filePath, now);
+		}
+		const existing = this.debounceTimers.get(filePath);
+		if (existing) clearTimeout(existing);
+		const delay = Math.min(DEBOUNCE_MS, Math.max(0, DEBOUNCE_MAX_WAIT_MS - (now - firstSeen)));
+		this.debounceTimers.set(filePath, setTimeout(() => this.flushDebouncedSync(filePath), delay));
+	}
+
+	private flushDebouncedSync(filePath: string): void {
+		this.debounceTimers.delete(filePath);
+		this.debounceFirstSeen.delete(filePath);
+		if (this.stopped || !this.config.enabled || !this.config.autoSync) return;
+		const file = this.app.vault.getAbstractFileByPath(filePath);
+		if (!(file instanceof TFile) || !this.isMarkdown(file) || this.isExcludedPath(filePath)) return;
+		this.enqueue({ type: 'sync', filePath, force: false });
+		this.processQueue();
+	}
+
+	private cancelDebounce(filePath: string): void {
+		const timer = this.debounceTimers.get(filePath);
+		if (timer) clearTimeout(timer);
+		this.debounceTimers.delete(filePath);
+		this.debounceFirstSeen.delete(filePath);
+	}
+
+	private clearAllDebounce(): void {
+		for (const timer of this.debounceTimers.values()) clearTimeout(timer);
+		this.debounceTimers.clear();
+		this.debounceFirstSeen.clear();
+	}
+
 	getSnapshot(): LightRAGSyncSnapshot {
 		const records = Object.values(this.records).sort((a, b) => b.updatedAt - a.updatedAt);
 		return {
@@ -220,6 +276,8 @@ export class LightRAGSyncService {
 
 	private shouldSync(file: TFile): boolean {
 		if (this.isExcludedPath(file.path)) return false;
+		// 正处于编辑 debounce 窗口内的文件交给 debounce 处理,定时扫盘不抢先同步中间态
+		if (this.debounceTimers.has(file.path)) return false;
 		const record = this.records[file.path];
 		if (!record) return true;
 		if (record.mtime < file.stat.mtime) return true;

src/main.ts

@@ -56,9 +56,6 @@ export default class CopilotPlugin extends Plugin {
 		await this.loadConversations();
 		await this.localStore.load();
 		await this.lightRAGSync.load();
-		if (this.settings.lightRAG.enabled && this.settings.lightRAG.autoSync) {
-			this.lightRAGSync.queueAll(false);
-		}
 		this.configureLightRAGPeriodicScan();
 		this.registerViews();
 		this.addCommands();
@@ -79,39 +76,48 @@ export default class CopilotPlugin extends Plugin {
 			)
 		);
 
-		// Watch for file deletions to keep index in sync
-		this.registerEvent(
-			this.app.vault.on('delete', file => {
-				void this.indexer.deleteFileIndex(file.path);
-				this.lightRAGSync.handleDelete(file.path);
-			})
-		);
+		// Vault 文件事件需等布局就绪后再注册:
+		// 1) onload 阶段 getMarkdownFiles() 可能为空/不全,此时 queueAll 的孤儿清理会把已同步文档误删;
+		// 2) 过早注册 'create' 会在启动时对每个已存在文件各触发一次,造成全量误同步。
+		this.app.workspace.onLayoutReady(() => {
+			if (this.settings.lightRAG.enabled && this.settings.lightRAG.autoSync) {
+				this.lightRAGSync.queueAll(false);
+			}
 
-		this.registerEvent(
-			this.app.vault.on('create', file => {
-				if (file instanceof TFile) {
-					this.lightRAGSync.handleCreateOrModify(file);
-				}
-			})
-		);
+			// Watch for file deletions to keep index in sync
+			this.registerEvent(
+				this.app.vault.on('delete', file => {
+					void this.indexer.deleteFileIndex(file.path);
+					this.lightRAGSync.handleDelete(file.path);
+				})
+			);
 
-		this.registerEvent(
-			this.app.vault.on('modify', file => {
-				if (file instanceof TFile) {
-					this.lightRAGSync.handleCreateOrModify(file);
-				}
-			})
-		);
+			this.registerEvent(
+				this.app.vault.on('create', file => {
+					if (file instanceof TFile) {
+						this.lightRAGSync.handleCreateOrModify(file);
+					}
+				})
+			);
 
-		this.registerEvent(
-			this.app.vault.on('rename', (file, oldPath) => {
-				if (file instanceof TFile) {
-					this.lightRAGSync.handleRename(file, oldPath);
-				} else {
-					this.lightRAGSync.handleDelete(oldPath);
-				}
-			})
-		);
+			this.registerEvent(
+				this.app.vault.on('modify', file => {
+					if (file instanceof TFile) {
+						this.lightRAGSync.handleCreateOrModify(file);
+					}
+				})
+			);
+
+			this.registerEvent(
+				this.app.vault.on('rename', (file, oldPath) => {
+					if (file instanceof TFile) {
+						this.lightRAGSync.handleRename(file, oldPath);
+					} else {
+						this.lightRAGSync.handleDelete(oldPath);
+					}
+				})
+			);
+		});
 
 		Logger.info('Copilot plugin loaded');
 	}