尧图网站建设 
Tolaria 路径感知的外部 Vault 刷新机制焦点编辑器保持与共享 reconcile 管线【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria导读本文深入解析 Tolaria一个以文件系统为唯一事实来源的 Markdown 知识库桌面应用如何应对外部 Vault 变更——包括git pull、AI Agent 写盘以及原生文件系统 watcher 事件——并在此基础上演进出一套路径感知刷新 焦点编辑器保持path-aware refresh with focused-editor preservation的协调策略。读者将掌握refreshPulledVaultState()这一共享 reconcile 管线的完整执行规则、底层路径身份匹配实现、焦点检测逻辑以及主窗口、二级笔记窗口与 AI 桥接层的调用方式可直接对照仓库源码理解其设计取舍。该策略由 ADR-0111Path-aware external vault refresh with focused-editor preservation 定义取代了此前的 ADR-0071External vault updates reload derived state and reopen the clean active note并与 ADR-0089Active vault filesystem watcher 配合构成 Tolaria 外部变更处理的第一等公民机制。一、问题背景为什么干净笔记一律重开不再成立1.1 外部变更的三类来源Tolaria 的 ADR-0002 确立了文件系统为事实来源ADR-0043 保证本地编辑的 frontmatter 在 UI 内实时响应。但外部进程对磁盘的修改依然存在空白窗口git pull/git checkout等仓库操作批量改写磁盘文件AI Agent如 Claude Code 等 CLI Agent在 Tolaria 之外直接编辑笔记原生文件系统 watcherADR-0089检测到的来自其他编辑器、终端命令或另一个 Tolaria 窗口的改动。这些变更可能让笔记列表、派生关系、backlinks 以及编辑器内的 BlockNote 文档停留在刷新前的旧状态。1.2 ADR-0071 的贡献与缺陷ADR-0071 首次把外部变更统一收敛到共享的refreshPulledVaultState()reconcile 路径确立了三个原则整体刷新 vault 派生状态、保护未保存的本地编辑、在安全时从磁盘重开干净的活动笔记。其方向正确但重开干净活动笔记的规则过于宽泛暴露出两个问题无关外部更新也可能重挂活动编辑器——即使活动文件本身没变只要其它文件被外部改动旧策略仍可能为了收敛派生状态而重开活动标签页焦点丢失——当光标位于富文本编辑器BlockNote或 raw 编辑器CodeMirror内部时重挂会丢弃光标/焦点状态打断原生输入流如中文输入法、原生 undo/redo即便这次刷新本身是安全的。因此 ADR-0111 的诉求是派生状态必须刷新但只有变更路径批次确实命中活动文件、且编辑器当前干净且未聚焦时才付出活动编辑器重挂的代价。二、决策核心七条执行规则ADR-0111 给出的最终决策是外部 Vault 刷新现在急切地重载共享的 vault 派生状态但只有当活动文件本身发生变更、且编辑器处于干净且未聚焦状态时才重挂活动编辑器。共享的refreshPulledVaultState()路径按以下七条规则执行每次外部变更批次同时重载 vault entries、folders 和 saved views若没有活动笔记共享重载后即停止若异步重载期间活动笔记发生了切换停止而不是重开过期上下文若活动笔记存在未保存的本地编辑保持当前编辑器 buffer 挂载若焦点当前位于富文本或 raw 编辑器表面内即使是干净笔记也保持该编辑器挂载若活动文件消失关闭标签页而不是留下陈旧编辑器仅当变更路径批次包含该活动文件、且上述守卫均未生效时才关闭并重开活动标签页。Git pull、AI Agent 刷新回调、文件系统 watcher 批次都必须收敛到这一个 reconcile helper而不是各自发明独立的 reload 策略。三、源码级解析refreshPulledVaultState()的执行管线核心实现在 src/utils/pulledVaultRefresh.ts函数签名通过PulledVaultRefreshOptions注入所有依赖以便测试与各调用方复用interface PulledVaultRefreshOptions { activeTabPath: string | null getActiveTabPath?: () string | null // 异步重载期间可重新读取真实活动路径 closeAllTabs: () void hasUnsavedChanges: (path: string) boolean isActiveTabContentCurrent?: (path: string) Promiseboolean | boolean reloadFolders: () Promiseunknown | unknown reloadVault: () PromiseVaultEntry[] reloadViews: () Promiseunknown | unknown replaceActiveTab: (entry: VaultEntry) Promisevoid refocusActiveEditor?: (path: string) void shouldRefocusActiveEditor?: () boolean updatedFiles: string[] // 本次外部变更的路径批次 vaultPath: string }3.1 第一步并行重载共享派生状态const [entries] await Promise.all([ reloadVault(), Promise.resolve(reloadFolders()), Promise.resolve(reloadViews()), ])三个重载并行执行对应规则 1。entries是刷新后的VaultEntry[]后续所有活动标签页决策都以它为基础。3.2 第二步活动路径守卫链const latestActiveTabPath getActiveTabPath?.() ?? activeTabPath if (isActivePathBlocked({ activeTabPath, latestActiveTabPath, hasUnsavedChanges })) return entriesgetActiveTabPath允许在异步重载完成后重新读取真正的活动标签页路径在 src/App.tsx 中传入() noteActiveTabPathRef.current以此检测异步期间的标签切换。isActivePathBlocked的判定条件覆盖规则 2、3、4function isActivePathBlocked(options) { if (!activeTabPath) return true // 规则 2无活动笔记 if (!latestActiveTabPath) return true if (didActivePathChange({ initialPath: activeTabPath, latestPath: latestActiveTabPath })) return true // 规则 3 return hasUnsavedChanges(latestActiveTabPath) // 规则 4 }路径比较统一走notePathsMatch见下文路径身份小节而不是字符串全等。3.3 第三步在刷新结果中定位活动条目const refreshedEntry findByNotePath(entries, activePath) ?? null const movedEntry refreshedEntry ? null : findExternallyMovedActiveEntry({ activeTabPath: activePath, entries, updatedFiles, vaultPath, }) const replacementEntry refreshedEntry ?? movedEntry当活动笔记在刷新后不存在时Tolaria 会尝试外部移动重定位findExternallyMovedActiveEntry在updatedFiles批次中查找与活动文件名相同、且路径确实出现在更新列表中的唯一候选条目。这是对重命名/移动笔记后标签页跟随新路径场景的支持测试用例retargets a focused active tab when the active note was moved externally验证了这一点。3.4 第四步变更批次是否命中活动文件function didPullUpdateActiveNote({ updatedFiles, vaultPath, activeTabPath }) { return updatedFiles.some((path) notePathsMatch(resolveUpdatedFilePath({ path, vaultPath }), activeTabPath)) }resolveUpdatedFilePath把相对路径拼上vaultPath绝对路径直接规范化——这就是路径感知path-aware的落点只有批次确实包含活动文件时才考虑替换规则 7 的前半段。shouldReplaceActiveEntry综合判断if (movedEntry) return true // 移动重定位必然替换 if (!refreshedEntry) return false return didPullUpdateActiveNote({ updatedFiles, vaultPath, activeTabPath: activePath })注意当updatedFiles为空数组如 AI Agent 的整个 vault 变了回调、watcher 全量刷新时didPullUpdateActiveNote返回 false活动标签页保持挂载——这正是测试用例keeps the active tab mounted for full watcher refreshes with unknown changed files所验证的行为。3.5 第五步内容新鲜度检查避免无谓重挂async function shouldKeepCurrentActiveEntryMounted(options) { if (!shouldReplace || movedEntry || !isActiveTabContentCurrent) return false return await isActiveTabContentCurrent(activePath) true }即便批次命中了活动文件如果当前编辑器 buffer 的内容与磁盘一致isActiveTabContentCurrent返回 true也跳过重挂。在 src/App.tsx 中该函数通过invoke(get_note_content)读取磁盘内容并与标签页缓存的content比对——这是对内容已经是最新的就无须重挂这一细节的优化。3.6 第六步执行替换或关闭async function applyActiveEntryReplacement(options) { if (!replacementEntry || !shouldReplace) return false const shouldRefocus shouldRefocusActiveEditor?.() true if (!notePathsMatch(activePath, replacementEntry.path)) closeAllTabs() await replaceActiveTab(replacementEntry) if (shouldRefocus) refocusActiveEditor?.(replacementEntry.path) return true }若新条目路径与旧活动路径不同外部移动先closeAllTabs()关闭旧标签再replaceActiveTab挂载新条目若焦点确实在编辑器内且需要保持shouldRefocusActiveEditor为真替换完成后通过refocusActiveEditor恢复焦点到新挂载的编辑器若没有任何 replacement 条目活动文件消失走closeAllTabs()收尾对应规则 6。四、路径身份匹配notePathIdentity.ts的底层支持路径感知刷新依赖可靠的路径身份判定实现在 src/utils/notePathIdentity.tsnormalizeNotePathForIdentity统一分隔符为/剥离 Windows 扩展路径前缀\\?\、\\?\UNC\并把 macOS 的/private/tmp归一为/tmp——测试用例matches macOS /tmp and /private/tmp aliases when reloading the active tab entry专门验证了这种别名匹配notePathsMatch两条路径经normalizeNotePathForIdentity后全等比较pulledVaultRefresh.ts中所有路径判断didPullUpdateActiveNote、didActivePathChange、findExternallyMovedActiveEntry都基于它findByNotePath/findByCollidingNotePath在条目数组中按身份/碰撞规则查找notePathsCollide则提供大小写不敏感的碰撞检测对应同目录大小写不同文件名的边界场景。这套规范化是跨平台Windows/macOS/Linux下 watcher 事件路径与标签页路径可靠比对的基石。五、焦点检测如何判断光标在编辑器内规则 5 的实现在 src/utils/appOrchestration.tsexport const ACTIVE_EDITOR_SURFACE_SELECTOR .editor__blocknote-container, .raw-editor-codemirror export function isActiveElementInsideEditorSurface(): boolean { const activeElement document.activeElement if (!(activeElement instanceof HTMLElement)) return false return Boolean(activeElement.closest(ACTIVE_EDITOR_SURFACE_SELECTOR)) }它通过document.activeElement沿 DOM 向上查找判断焦点是否落在富文本容器.editor__blocknote-container或 raw 编辑器.raw-editor-codemirror之内。该函数在 src/App.tsx 中被作为shouldRefocusActiveEditor传给refreshPulledVaultState刷新前判断焦点在编辑器内 → 保持挂载不重挂替换后恢复替换发生且焦点仍应在编辑器内 →refocusActiveEditor重新聚焦。同一文件中还有isTextEditingElementFocused()INPUT/TEXTAREA/contenteditable 判定与runNativeTextHistoryCommand()说明 Tolaria 将编辑器内焦点视为需要统一维护的原生输入流边界。六、调用方集成三类外部变更如何汇入共享管线6.1 主窗口统一入口src/App.tsx 中的handleVaultUpdate是主窗口的唯一 reconcile 入口组装了完整依赖后调用refreshPulledVaultState随后执行refreshGitModifiedFiles()同步 Git 修改列表。其上层两个薄封装handlePulledVaultUpdate(updatedFiles, vaultPath)接收带 vault 路径的 pull/watcher 事件handleFocusedVaultUpdate(updatedFiles)聚焦窗口的 watcher 回调见 src/App.tsx 附近无noteWindowParams时走主窗口管线否则委托给二级窗口的refreshNoteWindowVaultChanges。6.2 AI Agent 桥接层src/hooks/useVaultBridge.ts 为 AI 集成提供四个回调全部收敛到refreshAgentChangedFiles→refreshPulledVaultStatehandleAgentFileModified(relativePath)单个文件被 Agent 修改时以[relativePath]作为updatedFiles批次handleAgentVaultChanged()Agent 声明整个 vault 变化时传入空批次[]此时仅做共享重载不重挂活动标签页handleAgentFileCreated(path)新建文件后reloadAndOpen直接重载并选中handlePulseOpenNote/openNoteByPath按路径打开笔记未命中时先重载再打开。这正是 ADR-0111 所要求的AI-agent refresh callbacks 与 pull/watcher 共用同一策略。6.3 文件系统 watcher 的批处理与防抖src/hooks/useVaultWatcher.ts 实现原生事件到刷新批次的转换对应 ADR-0089handleWatcherEvent把后端vault-changed事件携带vaultPath与paths按根目录入队usePendingVaultRefresh维护queuedPathsRef与fullRefreshPendingRef以debounceMs默认VAULT_WATCHER_DEBOUNCE_MS合并短时间内的多个事件flushQueuedRefresh时经filterChangedPaths过滤后一次性调用onVaultChanged(filteredPaths)全量刷新fullRefresh时直接透传队列否则过滤后的空批次会跳过刷新if (!fullRefresh filteredPaths.length 0) return。由此watcher 的每一次刷新都携带尽可能完整的变更路径列表满足 ADR-0111 对调用方应传递最佳可用文件列表的契约要求。6.4 二级笔记窗口src/utils/noteWindowVaultRefresh.ts 的refreshNoteWindowVaultChanges是二级窗口entry-scoped note window见 ADR-0118的适配层它先尝试按路径批量reloadEntry增量刷新任一条目失败则回退refreshFullVault随后仍调用refreshPulledVaultState完成活动标签页的守卫与替换决策——把增量加载与活动编辑器策略解耦。七、测试验证十一类场景覆盖src/utils/pulledVaultRefresh.test.ts 使用 vitest 对共享管线做了场景化验证是理解七条规则的最佳可执行文档测试用例验证的规则reloads vault-derived data and refreshes the active note when pull updated it规则 1 规则 7 的正常路径updatedFiles含活动文件 → 替换keeps the active tab mounted when updates do not include the active note路径感知批次不含活动文件 → 不重挂keeps the active tab mounted for full watcher refreshes with unknown changed files空批次全量刷新→ 仅共享重载matches macOS /tmp and /private/tmp aliases路径规范化身份匹配skips tab replacement when the active note has unsaved edits规则 4未保存编辑保护keeps the active tab mounted when its current content already matches disk内容新鲜度优化isActiveTabContentCurrentrefocuses the editor after refreshing a focused clean active tab替换后焦点恢复keeps the active tab mounted when the active note was not changed规则 7批次未命中活动文件retargets a focused active tab when the active note was moved externally外部移动重定位skips stale tab replacement when the active note changes during reload规则 3异步重载期间标签切换closes the tab when the pulled note disappeared from the reloaded vault规则 6文件消失关闭标签页测试还验证了closeAllTabs与replaceActiveTab的调用次数/参数确保共享管线不会被无关批次误触发。八、与 ADR-0071 的演进对比与后续约束8.1 演进对比维度ADR-0071已废弃ADR-0111现行活动标签页重开条件活动笔记干净即重开批次包含活动文件 且 编辑器干净 且 未聚焦焦点保护无isActiveElementInsideEditorSurface守卫 refocusActiveEditor恢复变更批次未纳入契约updatedFiles成为外部刷新契约的一部分全量刷新空批次可能误重挂仅共享重载活动标签页保持8.2 备选方案与取舍ADR-0111 记录了两个被否决的方案每次外部刷新后一律重开干净活动笔记收敛最快但无关变更也会引起可见抖动并丢失焦点编辑器聚焦时跳过共享重载保住焦点但 folders、views、backlinks 等派生状态会滞留过期数据。最终选择的路径感知 焦点保持方案代价是聚焦且干净的编辑器可能暂时停留在刷新前的内容直到后续某次安全重挂才收敛——这是用活动笔记即时收敛换取编辑连续性的明确权衡。8.3 演进约束ADR-0111 强调refreshPulledVaultState()是外部刷新策略的唯一演化点未来特性应扩展该 helper而不是在各处叠加 ad hoc 的编辑器重载逻辑。与之衔接的后续决策还包括 ADR-0135Clean active note refresh after external edit后者进一步约束了外部编辑后干净活动笔记的刷新时机。需要扩展阅读的读者可对照 docs/ARCHITECTURE.md 与 docs/ABSTRACTIONS.md 中的抽象边界说明。九、结语Tolaria 的 ADR-0111 展示了同步与编辑体验如何在同一 reconcile 管线内达成平衡共享派生状态始终急切刷新而活动编辑器的重挂被严格限定在批次命中活动文件 编辑器干净 未聚焦这一最小集合内。refreshPulledVaultState()配合notePathIdentity的跨平台路径规范化、appOrchestration的焦点检测、以及 watcher/Agent 桥接层的批处理输入构成了一个可测试、可扩展的外部变更处理中枢——这也是理解 Tolaria 文件系统即事实来源架构的关键入口之一。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Tolaria 路径感知的外部 Vault 刷新机制：焦点编辑器保持与共享 reconcile 管线
Tolaria 路径感知的外部 Vault 刷新机制焦点编辑器保持与共享 reconcile 管线【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria导读本文深入解析 Tolaria一个以文件系统为唯一事实来源的 Markdown 知识库桌面应用如何应对外部 Vault 变更——包括git pull、AI Agent 写盘以及原生文件系统 watcher 事件——并在此基础上演进出一套路径感知刷新 焦点编辑器保持path-aware refresh with focused-editor preservation的协调策略。读者将掌握refreshPulledVaultState()这一共享 reconcile 管线的完整执行规则、底层路径身份匹配实现、焦点检测逻辑以及主窗口、二级笔记窗口与 AI 桥接层的调用方式可直接对照仓库源码理解其设计取舍。该策略由 ADR-0111Path-aware external vault refresh with focused-editor preservation 定义取代了此前的 ADR-0071External vault updates reload derived state and reopen the clean active note并与 ADR-0089Active vault filesystem watcher 配合构成 Tolaria 外部变更处理的第一等公民机制。一、问题背景为什么干净笔记一律重开不再成立1.1 外部变更的三类来源Tolaria 的 ADR-0002 确立了文件系统为事实来源ADR-0043 保证本地编辑的 frontmatter 在 UI 内实时响应。但外部进程对磁盘的修改依然存在空白窗口git pull/git checkout等仓库操作批量改写磁盘文件AI Agent如 Claude Code 等 CLI Agent在 Tolaria 之外直接编辑笔记原生文件系统 watcherADR-0089检测到的来自其他编辑器、终端命令或另一个 Tolaria 窗口的改动。这些变更可能让笔记列表、派生关系、backlinks 以及编辑器内的 BlockNote 文档停留在刷新前的旧状态。1.2 ADR-0071 的贡献与缺陷ADR-0071 首次把外部变更统一收敛到共享的refreshPulledVaultState()reconcile 路径确立了三个原则整体刷新 vault 派生状态、保护未保存的本地编辑、在安全时从磁盘重开干净的活动笔记。其方向正确但重开干净活动笔记的规则过于宽泛暴露出两个问题无关外部更新也可能重挂活动编辑器——即使活动文件本身没变只要其它文件被外部改动旧策略仍可能为了收敛派生状态而重开活动标签页焦点丢失——当光标位于富文本编辑器BlockNote或 raw 编辑器CodeMirror内部时重挂会丢弃光标/焦点状态打断原生输入流如中文输入法、原生 undo/redo即便这次刷新本身是安全的。因此 ADR-0111 的诉求是派生状态必须刷新但只有变更路径批次确实命中活动文件、且编辑器当前干净且未聚焦时才付出活动编辑器重挂的代价。二、决策核心七条执行规则ADR-0111 给出的最终决策是外部 Vault 刷新现在急切地重载共享的 vault 派生状态但只有当活动文件本身发生变更、且编辑器处于干净且未聚焦状态时才重挂活动编辑器。共享的refreshPulledVaultState()路径按以下七条规则执行每次外部变更批次同时重载 vault entries、folders 和 saved views若没有活动笔记共享重载后即停止若异步重载期间活动笔记发生了切换停止而不是重开过期上下文若活动笔记存在未保存的本地编辑保持当前编辑器 buffer 挂载若焦点当前位于富文本或 raw 编辑器表面内即使是干净笔记也保持该编辑器挂载若活动文件消失关闭标签页而不是留下陈旧编辑器仅当变更路径批次包含该活动文件、且上述守卫均未生效时才关闭并重开活动标签页。Git pull、AI Agent 刷新回调、文件系统 watcher 批次都必须收敛到这一个 reconcile helper而不是各自发明独立的 reload 策略。三、源码级解析refreshPulledVaultState()的执行管线核心实现在 src/utils/pulledVaultRefresh.ts函数签名通过PulledVaultRefreshOptions注入所有依赖以便测试与各调用方复用interface PulledVaultRefreshOptions { activeTabPath: string | null getActiveTabPath?: () string | null // 异步重载期间可重新读取真实活动路径 closeAllTabs: () void hasUnsavedChanges: (path: string) boolean isActiveTabContentCurrent?: (path: string) Promiseboolean | boolean reloadFolders: () Promiseunknown | unknown reloadVault: () PromiseVaultEntry[] reloadViews: () Promiseunknown | unknown replaceActiveTab: (entry: VaultEntry) Promisevoid refocusActiveEditor?: (path: string) void shouldRefocusActiveEditor?: () boolean updatedFiles: string[] // 本次外部变更的路径批次 vaultPath: string }3.1 第一步并行重载共享派生状态const [entries] await Promise.all([ reloadVault(), Promise.resolve(reloadFolders()), Promise.resolve(reloadViews()), ])三个重载并行执行对应规则 1。entries是刷新后的VaultEntry[]后续所有活动标签页决策都以它为基础。3.2 第二步活动路径守卫链const latestActiveTabPath getActiveTabPath?.() ?? activeTabPath if (isActivePathBlocked({ activeTabPath, latestActiveTabPath, hasUnsavedChanges })) return entriesgetActiveTabPath允许在异步重载完成后重新读取真正的活动标签页路径在 src/App.tsx 中传入() noteActiveTabPathRef.current以此检测异步期间的标签切换。isActivePathBlocked的判定条件覆盖规则 2、3、4function isActivePathBlocked(options) { if (!activeTabPath) return true // 规则 2无活动笔记 if (!latestActiveTabPath) return true if (didActivePathChange({ initialPath: activeTabPath, latestPath: latestActiveTabPath })) return true // 规则 3 return hasUnsavedChanges(latestActiveTabPath) // 规则 4 }路径比较统一走notePathsMatch见下文路径身份小节而不是字符串全等。3.3 第三步在刷新结果中定位活动条目const refreshedEntry findByNotePath(entries, activePath) ?? null const movedEntry refreshedEntry ? null : findExternallyMovedActiveEntry({ activeTabPath: activePath, entries, updatedFiles, vaultPath, }) const replacementEntry refreshedEntry ?? movedEntry当活动笔记在刷新后不存在时Tolaria 会尝试外部移动重定位findExternallyMovedActiveEntry在updatedFiles批次中查找与活动文件名相同、且路径确实出现在更新列表中的唯一候选条目。这是对重命名/移动笔记后标签页跟随新路径场景的支持测试用例retargets a focused active tab when the active note was moved externally验证了这一点。3.4 第四步变更批次是否命中活动文件function didPullUpdateActiveNote({ updatedFiles, vaultPath, activeTabPath }) { return updatedFiles.some((path) notePathsMatch(resolveUpdatedFilePath({ path, vaultPath }), activeTabPath)) }resolveUpdatedFilePath把相对路径拼上vaultPath绝对路径直接规范化——这就是路径感知path-aware的落点只有批次确实包含活动文件时才考虑替换规则 7 的前半段。shouldReplaceActiveEntry综合判断if (movedEntry) return true // 移动重定位必然替换 if (!refreshedEntry) return false return didPullUpdateActiveNote({ updatedFiles, vaultPath, activeTabPath: activePath })注意当updatedFiles为空数组如 AI Agent 的整个 vault 变了回调、watcher 全量刷新时didPullUpdateActiveNote返回 false活动标签页保持挂载——这正是测试用例keeps the active tab mounted for full watcher refreshes with unknown changed files所验证的行为。3.5 第五步内容新鲜度检查避免无谓重挂async function shouldKeepCurrentActiveEntryMounted(options) { if (!shouldReplace || movedEntry || !isActiveTabContentCurrent) return false return await isActiveTabContentCurrent(activePath) true }即便批次命中了活动文件如果当前编辑器 buffer 的内容与磁盘一致isActiveTabContentCurrent返回 true也跳过重挂。在 src/App.tsx 中该函数通过invoke(get_note_content)读取磁盘内容并与标签页缓存的content比对——这是对内容已经是最新的就无须重挂这一细节的优化。3.6 第六步执行替换或关闭async function applyActiveEntryReplacement(options) { if (!replacementEntry || !shouldReplace) return false const shouldRefocus shouldRefocusActiveEditor?.() true if (!notePathsMatch(activePath, replacementEntry.path)) closeAllTabs() await replaceActiveTab(replacementEntry) if (shouldRefocus) refocusActiveEditor?.(replacementEntry.path) return true }若新条目路径与旧活动路径不同外部移动先closeAllTabs()关闭旧标签再replaceActiveTab挂载新条目若焦点确实在编辑器内且需要保持shouldRefocusActiveEditor为真替换完成后通过refocusActiveEditor恢复焦点到新挂载的编辑器若没有任何 replacement 条目活动文件消失走closeAllTabs()收尾对应规则 6。四、路径身份匹配notePathIdentity.ts的底层支持路径感知刷新依赖可靠的路径身份判定实现在 src/utils/notePathIdentity.tsnormalizeNotePathForIdentity统一分隔符为/剥离 Windows 扩展路径前缀\\?\、\\?\UNC\并把 macOS 的/private/tmp归一为/tmp——测试用例matches macOS /tmp and /private/tmp aliases when reloading the active tab entry专门验证了这种别名匹配notePathsMatch两条路径经normalizeNotePathForIdentity后全等比较pulledVaultRefresh.ts中所有路径判断didPullUpdateActiveNote、didActivePathChange、findExternallyMovedActiveEntry都基于它findByNotePath/findByCollidingNotePath在条目数组中按身份/碰撞规则查找notePathsCollide则提供大小写不敏感的碰撞检测对应同目录大小写不同文件名的边界场景。这套规范化是跨平台Windows/macOS/Linux下 watcher 事件路径与标签页路径可靠比对的基石。五、焦点检测如何判断光标在编辑器内规则 5 的实现在 src/utils/appOrchestration.tsexport const ACTIVE_EDITOR_SURFACE_SELECTOR .editor__blocknote-container, .raw-editor-codemirror export function isActiveElementInsideEditorSurface(): boolean { const activeElement document.activeElement if (!(activeElement instanceof HTMLElement)) return false return Boolean(activeElement.closest(ACTIVE_EDITOR_SURFACE_SELECTOR)) }它通过document.activeElement沿 DOM 向上查找判断焦点是否落在富文本容器.editor__blocknote-container或 raw 编辑器.raw-editor-codemirror之内。该函数在 src/App.tsx 中被作为shouldRefocusActiveEditor传给refreshPulledVaultState刷新前判断焦点在编辑器内 → 保持挂载不重挂替换后恢复替换发生且焦点仍应在编辑器内 →refocusActiveEditor重新聚焦。同一文件中还有isTextEditingElementFocused()INPUT/TEXTAREA/contenteditable 判定与runNativeTextHistoryCommand()说明 Tolaria 将编辑器内焦点视为需要统一维护的原生输入流边界。六、调用方集成三类外部变更如何汇入共享管线6.1 主窗口统一入口src/App.tsx 中的handleVaultUpdate是主窗口的唯一 reconcile 入口组装了完整依赖后调用refreshPulledVaultState随后执行refreshGitModifiedFiles()同步 Git 修改列表。其上层两个薄封装handlePulledVaultUpdate(updatedFiles, vaultPath)接收带 vault 路径的 pull/watcher 事件handleFocusedVaultUpdate(updatedFiles)聚焦窗口的 watcher 回调见 src/App.tsx 附近无noteWindowParams时走主窗口管线否则委托给二级窗口的refreshNoteWindowVaultChanges。6.2 AI Agent 桥接层src/hooks/useVaultBridge.ts 为 AI 集成提供四个回调全部收敛到refreshAgentChangedFiles→refreshPulledVaultStatehandleAgentFileModified(relativePath)单个文件被 Agent 修改时以[relativePath]作为updatedFiles批次handleAgentVaultChanged()Agent 声明整个 vault 变化时传入空批次[]此时仅做共享重载不重挂活动标签页handleAgentFileCreated(path)新建文件后reloadAndOpen直接重载并选中handlePulseOpenNote/openNoteByPath按路径打开笔记未命中时先重载再打开。这正是 ADR-0111 所要求的AI-agent refresh callbacks 与 pull/watcher 共用同一策略。6.3 文件系统 watcher 的批处理与防抖src/hooks/useVaultWatcher.ts 实现原生事件到刷新批次的转换对应 ADR-0089handleWatcherEvent把后端vault-changed事件携带vaultPath与paths按根目录入队usePendingVaultRefresh维护queuedPathsRef与fullRefreshPendingRef以debounceMs默认VAULT_WATCHER_DEBOUNCE_MS合并短时间内的多个事件flushQueuedRefresh时经filterChangedPaths过滤后一次性调用onVaultChanged(filteredPaths)全量刷新fullRefresh时直接透传队列否则过滤后的空批次会跳过刷新if (!fullRefresh filteredPaths.length 0) return。由此watcher 的每一次刷新都携带尽可能完整的变更路径列表满足 ADR-0111 对调用方应传递最佳可用文件列表的契约要求。6.4 二级笔记窗口src/utils/noteWindowVaultRefresh.ts 的refreshNoteWindowVaultChanges是二级窗口entry-scoped note window见 ADR-0118的适配层它先尝试按路径批量reloadEntry增量刷新任一条目失败则回退refreshFullVault随后仍调用refreshPulledVaultState完成活动标签页的守卫与替换决策——把增量加载与活动编辑器策略解耦。七、测试验证十一类场景覆盖src/utils/pulledVaultRefresh.test.ts 使用 vitest 对共享管线做了场景化验证是理解七条规则的最佳可执行文档测试用例验证的规则reloads vault-derived data and refreshes the active note when pull updated it规则 1 规则 7 的正常路径updatedFiles含活动文件 → 替换keeps the active tab mounted when updates do not include the active note路径感知批次不含活动文件 → 不重挂keeps the active tab mounted for full watcher refreshes with unknown changed files空批次全量刷新→ 仅共享重载matches macOS /tmp and /private/tmp aliases路径规范化身份匹配skips tab replacement when the active note has unsaved edits规则 4未保存编辑保护keeps the active tab mounted when its current content already matches disk内容新鲜度优化isActiveTabContentCurrentrefocuses the editor after refreshing a focused clean active tab替换后焦点恢复keeps the active tab mounted when the active note was not changed规则 7批次未命中活动文件retargets a focused active tab when the active note was moved externally外部移动重定位skips stale tab replacement when the active note changes during reload规则 3异步重载期间标签切换closes the tab when the pulled note disappeared from the reloaded vault规则 6文件消失关闭标签页测试还验证了closeAllTabs与replaceActiveTab的调用次数/参数确保共享管线不会被无关批次误触发。八、与 ADR-0071 的演进对比与后续约束8.1 演进对比维度ADR-0071已废弃ADR-0111现行活动标签页重开条件活动笔记干净即重开批次包含活动文件 且 编辑器干净 且 未聚焦焦点保护无isActiveElementInsideEditorSurface守卫 refocusActiveEditor恢复变更批次未纳入契约updatedFiles成为外部刷新契约的一部分全量刷新空批次可能误重挂仅共享重载活动标签页保持8.2 备选方案与取舍ADR-0111 记录了两个被否决的方案每次外部刷新后一律重开干净活动笔记收敛最快但无关变更也会引起可见抖动并丢失焦点编辑器聚焦时跳过共享重载保住焦点但 folders、views、backlinks 等派生状态会滞留过期数据。最终选择的路径感知 焦点保持方案代价是聚焦且干净的编辑器可能暂时停留在刷新前的内容直到后续某次安全重挂才收敛——这是用活动笔记即时收敛换取编辑连续性的明确权衡。8.3 演进约束ADR-0111 强调refreshPulledVaultState()是外部刷新策略的唯一演化点未来特性应扩展该 helper而不是在各处叠加 ad hoc 的编辑器重载逻辑。与之衔接的后续决策还包括 ADR-0135Clean active note refresh after external edit后者进一步约束了外部编辑后干净活动笔记的刷新时机。需要扩展阅读的读者可对照 docs/ARCHITECTURE.md 与 docs/ABSTRACTIONS.md 中的抽象边界说明。九、结语Tolaria 的 ADR-0111 展示了同步与编辑体验如何在同一 reconcile 管线内达成平衡共享派生状态始终急切刷新而活动编辑器的重挂被严格限定在批次命中活动文件 编辑器干净 未聚焦这一最小集合内。refreshPulledVaultState()配合notePathIdentity的跨平台路径规范化、appOrchestration的焦点检测、以及 watcher/Agent 桥接层的批处理输入构成了一个可测试、可扩展的外部变更处理中枢——这也是理解 Tolaria 文件系统即事实来源架构的关键入口之一。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考