Tolaria 编辑器正确性与响应性契约单一路径渲染、身份校验缓存与空闲期预热的实现机制【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本篇基于 Tolaria 的架构决策记录 0105-editor-correctness-and-responsiveness-contract.md系统梳理该项目围绕 BlockNote 富文本编辑器建立的正确性与响应性契约以单一直接编辑器表面替代先 Markdown 预览、后水合的双渲染器方案通过交换代际检查generation-checked swaps、磁盘身份校验modifiedAt fileSize的原文预取缓存、按源码内容精确键控的有界解析块缓存以及仅在前台空闲窗口执行的后台块预热保证大笔记场景下不崩溃、不丢失编辑、不出现过期内容竞争。读完后你将理解这套契约的每个约束在 Tolaria 前端源码中是如何落地为具体常量、缓存结构与调度逻辑的。背景持久化 Markdown 与 BlockNote 渲染之间的张力Tolaria 的笔记是磁盘上持久的 Markdown 文件但富文本编辑层通过 BlockNote 的块结构来渲染。ADR 的 Context 部分指出大笔记曾暴露出一个诱人但危险的优化先显示一个快速的 Markdown 预览再在后台水合出 BlockNote 编辑器。实践中该方案会带来同一份文档存在两个渲染器可见的闪烁flicker点击编辑时的延迟卡顿delayed click-time lag更多让过期异步工作与当前选中笔记发生竞争的位置。因此 ADR 明确了产品优先级的排序后续所有编辑器优化都必须服从这个顺序不崩溃no crashes不出现过期内容、竞争条件覆盖或丢失编辑no stale content, race-condition overwrites, or lost edits打字与光标移动的响应性responsive typing and cursor movement从笔记列表到编辑器的快速加载fast note-list-to-editor loading注意这个排序加载速度排在正确性之后。这决定了 Tolaria 允许预取 缓存 空闲预热来加速打开但禁止先画一个假的预览。核心决策单一直接编辑器表面 有界缓存ADR 的 Decision 部分给出的决策可以概括为一句话Tolaria 为 Markdown 笔记保留单一直接编辑器表面并把编辑器内容交换视为经过代际检查、经过源内容检查的操作。快速加载只能依靠原文文件内容预取和有界的解析块缓存而不能显示一个随后切换为编辑器的独立预览。解析后的 BlockNote 块只有在源 Markdown 与正在打开的内容完全一致时才可复用后台解析必须在前台打字/导航进入空闲状态之后运行。ADR 同时列出了四个被评估的方案及取舍方案结论理由单一直接编辑器表面 防护式交换 有界缓存选中保持文档的单一视觉表示拒绝过期的异步解析结果打开前校验或做身份比对打字相关的工作保持防抖。代价非常大的笔记若未被预热仍要等待 BlockNote 转换快速 Markdown 预览 隐藏 BlockNote 水合弃用改善首帧但引入闪烁、编辑期卡顿、重复的渲染语义无界/激进的后台 BlockNote 解析弃用会让某些打开变快但与打字/导航竞争且带来过期解析结果的风险除非被严格调度、限界、失效大笔记永远使用 raw 模式弃用对超大文件响应性最强但会突兀地改变编辑体验应作为显式回退而非默认实现证据一代际检查的内容交换swap token编辑器内容交换是代际检查操作这一约束在源码中对应useEditorTabSwap这套交换生命周期逻辑。src/hooks/useEditorTabSwap.ts 导入了用于令牌化的工具import { createSwapToken, invalidatePendingSwap, shouldAbortSwap, type SwapToken, } from ./editorSwapTokencreateSwapToken为每次笔记切换生成代际令牌shouldAbortSwap让任何在途的异步交换在令牌失效时自我中止避免为 A 笔记拉取的解析结果落到已经切走的编辑器上invalidatePendingSwap在状态变化时使未完成的交换作废。同一文件中还可以看到交换与防抖体系的协作flushBeforePathChange、flushBeforeRawMode保证在切笔记或切 raw 模式之前先把待写内容落盘useDebouncedEditorChange则把逐键的编辑器变更延迟处理见后文。src/components/Editor.tsx 中的useEditorTabSwap调用与tabsForEditorSwap说明交换逻辑与笔记/表格sheet切换状态机是分开建模的richEditorActiveTabPath等状态用于判定当前哪一条 tab 真正拥有编辑器表面——这正是单一直接编辑器表面在组件层的体现。实现证据二原文预取缓存与 modifiedAt/fileSize 身份校验ADR 要求缓存的原文笔记内容在显示前必须与磁盘校验除非它携带与当前 VaultEntry 相同的modifiedAt和fileSize身份或内容刚由 Tolaria 在当前进程中生成。这一条在 src/hooks/noteContentCache.ts 中得到了完整实现。缓存边界常量export const NOTE_CONTENT_CACHE_LIMIT 24 // 最多缓存 24 条笔记原文 export const NOTE_CONTENT_ENTRY_MAX_BYTES 1024 * 1024 // 单条上限 1 MB export const NOTE_CONTENT_CACHE_MAX_BYTES 8 * 1024 * 1024 // 总字节预算 8 MB export const NOTE_CONTENT_PREFETCH_CONCURRENCY 4 // 预取并发上限 const NOTE_CONTENT_LOAD_RETRY_DELAYS_MS [120, 320, 800] as const // 读盘重试退避缓存条目NoteContentCacheEntry除了 path、content 之外还携带identity: { modifiedAt, fileSize }、vaultPath、请求状态机queued / running / settled / canceled以及可取消的请求句柄startRequest/cancelRequest。超过 1 MB 的内容不会进入缓存retainResolvedNoteContent中直接delete超限缓存会按最旧条目淘汰trimPrefetchCache。身份比对与磁盘新鲜度校验打开一条笔记时loadContentForOpen的决策路径是若未强制刷新且已有解析完成的缓存内容走loadCachedContentIfFresh缓存条目与目标不属于同一个 vault → 直接丢弃matchesCachedContentVault检查cachedEntry.vaultPath targetVaultPath(entry)通过sameIdentity比对modifiedAt与fileSize两者都完整且相等才免校验直接复用——这正对应 ADR 中携带相同 modifiedAt 和 fileSize 身份的豁免条件身份不可信时调用 Tauri 命令validate_note_content拿磁盘上的内容做新鲜度校验markNoteOpenTrace(entry.path, freshnessCheckStart)埋点记录了这一步的耗时校验失败则删除缓存并回落到全量读取。缓存不可用或强制刷新时走loadNoteContent(entry, forceFresh)其中requestState与startRequest保证前台打开可以把尚在排队的预取请求提升为立即执行startNoteContentRequestNow而不是发起重复 IO。预取侧prefetchNoteContent会把请求放入长度受并发上限 4 约束的队列runQueuedPrefetches取消时通过cancelRequest把 Promise 以NOTE_CONTENT_REQUEST_CANCELED拒绝避免被取消的预取污染监听器。加载失败按NOTE_CONTENT_LOAD_RETRY_DELAYS_MS [120, 320, 800]退避重试但文件不存在与非 UTF-8等不可重试错误会直接抛出isMissingNoteContentError/isUnreadableNoteContentError。实现证据三按vault 路径 精确源内容键控的解析块缓存ADR 对解析块缓存的要求是以 vault、path、精确源内容为键读写时克隆且按条目数 源字节预算双重限界。src/hooks/editorParsedBlockCache.ts 是逐条落地的export const PARSED_NOTE_BLOCK_CACHE_LIMIT 6 // 条目数上限 export const PARSED_NOTE_BLOCK_ENTRY_MAX_BYTES 768 * 1024 // 单条源内容上限 768 KB export const PARSED_NOTE_BLOCK_CACHE_MAX_SOURCE_BYTES 3 * 1024 * 1024 // 源字节总预算 3 MB键控cacheKey(path, vaultPath)生成vaultPath \0 path条目里同时保存sourceContent实现vault path两级定位精确源内容检查readParsedNoteBlocks中if (!entry || entry.sourceContent ! options.content) return null——源 Markdown 与当前要打开的内容全字符串相等才允许复用解析结果否则返回 null 触发重新解析。这正是stale parse result被拒之门外的机制读写克隆cloneBlocks优先使用structuredClone回落到JSON.parse(JSON.stringify(...))写入cacheParsedNoteBlocks和读出readParsedNoteBlocks都克隆一份防止编辑器侧的块对象被缓存引用原地修改而互相污染双重限界淘汰trimParsedBlockCache在条目数超过 6 或累计源字节超过 3 MB 时按 Map 插入顺序删除最旧条目单条源内容超过 768 KB 的笔记直接不缓存cacheParsedNoteBlocks开头的早退分支。注意这里的源字节是源 Markdown 的 UTF-8 字节数sourceBytes用TextEncoder测量而不是解析后块结构的体积——预算控制的是为多大的一份文档保留了可复用解析结果。实现证据四空闲窗口内的后台块预热ADR 规定后台解析块预热只允许在前台空闲窗口之后针对可能打开的下一条大 Markdown 笔记进行正在打字、raw 模式、编辑器未挂载都必须推迟它。src/hooks/editorParsedBlockPreload.ts 把这些条件变成了显式常量与判定函数export const PARSED_BLOCK_PRELOAD_MIN_BYTES 32 * 1024 // 只预热 32 KB 的笔记 export const PARSED_BLOCK_PRELOAD_DELAY_MS 1800 // 事件入队后延迟 1.8 s export const PARSED_BLOCK_PRELOAD_FOREGROUND_IDLE_MS 1500 // 距上次前台工作需超过 1.5 s export const PARSED_BLOCK_PRELOAD_ENABLED true入队侧canPreloadParsedBlocks的过滤条件与 ADR 逐条对应事件必须标记parsedBlockPreload即该次内容请求本来就想预热解析块条目必须是 markdown 文件fileKind ! markdown直接跳过文件必须不小于 32 KB——小笔记解析很快不值得预热不能是当前激活 tabentry.path activeTabPath排除。执行侧shouldDeferParsedPreload实现了三类推迟条件并在性能跟踪logParsedBlockPreloadTrace中记录推迟原因推迟条件对应 ADR 条款trace 原因编辑器未挂载editorMountedRef.current falseeditor mount state must defer iteditor-unmountedraw 模式激活raw mode … must defer itraw-mode距上次前台工作打字/导航不足 1.5 sonly after recent typing/navigation has gone idleforeground-active调度本身是单飞 定时重排候选事件先进入queueRef按 path 去重1.8 s 后执行runNext若被推迟则记录 trace 并再次scheduleNext()重排一次执行只处理一个候选runningRef防止并发完成后若队列非空继续排程。每个状态转移queued / deferred / prepared都会写入 src/utils/editorPerformanceTrace.ts 的预热跟踪携带sourceBytes与耗时便于离线分析预热是否真正兑现了空闲期承诺。实现证据五逐键工作保持最小化ADR 最后一条约束每次击键的编辑器工作必须保持最小序列化、元数据推导、自动保存和缓存更新应当防抖、合并或调度到打字之外。源码侧可以看到两个落点src/hooks/useEditorTabSwap.ts 从editorChangeDebounce引入useDebouncedEditorChange并对外导出防抖常量export { RICH_EDITOR_CHANGE_DEBOUNCE_MS } from ./editorChangeDebounce——编辑变更回调本身是防抖的切换路径或切 raw 模式前再由flushBeforePathChange/flushBeforeRawMode做一次性同步落盘保证防抖不丢编辑。解析预热通过foregroundWorkAtRef最近一次前台工作时间戳感知打字活动见上节解析块解析路径自身还区分了快速解析与回退原因src/hooks/editorFastMarkdownBlocks.ts 的FastMarkdownParseMetrics.fallbackReason即解析器遇到它不认识的块结构时会带着明确原因降级而不是静默产出错误块。脏内容权威性本地未保存编辑优先ADR 的另一条后果是本地脏编辑器内容保持权威。外部文件系统刷新可以替换干净的笔记但不能覆盖未保存的本地编辑。在打开链路里这一点的体现是 src/components/editor-content/editorContentState.ts 的可见性推导deriveEditorContentState以当前激活 tab 的内容为主源contentHasTopLevelH1直接读activeTab.content再与来自磁盘扫描的freshEntry最新entries中同 path 的 VaultEntry交叉推导 H1、归档、sheet/HTML/纯文本等展示态isDeletedPreview条目已从 vault 消失这类异常态被显式建模而非覆盖 tab 内容。结合useEditorTabSwap中pendingLocalContentRef与suppressChangeRef的处理本地未保存内容在切换与外部刷新中不会被静默丢弃。这套契约给后续优化的边界ADR 的 Consequences 部分最后一条为未来的大笔记优化划了边界应瞄准真正的渐进式/分块转换或显式的 raw/只读回退状态而不是一个视觉上不同、随后变形为 BlockNote 的预览。结合本仓库现状可以印证这一方向已经部分成型raw 模式回退是显式的editorContentState.ts中effectiveRawMode rawMode || isNonMarkdownText非 Markdown 文本文件强制走 raw 路径showEditor: !effectiveRawMode解析降级是显式的editorFastMarkdownBlocks.ts的fallbackReason指标让快速解析不可用成为可观测事件而非视觉上的格式突变打开链路耗时是显式的noteContentCache.ts与noteOpenPerformance的 trace如freshnessCheckStart/End把校验缓存新鲜度这一步单独计点。换言之0105 号 ADR 不仅是否决了一个看起来更快的方案更是给 Tolaria 的编辑器性能工作立下了一条可审计的验收线任何加速手段都必须先证明它不破坏同一文档只有一个视觉表示、每次交换都经过代际与源内容双重检查这两条不变量。相关行为在 src/hooks/editorParsedBlockPreload.test.tsx 与 src/utils/noteOpenPerformance.extra.test.ts 中有对应测试覆盖可作为理解上述机制的回归依据。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Tolaria 编辑器正确性与响应性契约：单一路径渲染、身份校验缓存与空闲期预热的实现机制
Tolaria 编辑器正确性与响应性契约单一路径渲染、身份校验缓存与空闲期预热的实现机制【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本篇基于 Tolaria 的架构决策记录 0105-editor-correctness-and-responsiveness-contract.md系统梳理该项目围绕 BlockNote 富文本编辑器建立的正确性与响应性契约以单一直接编辑器表面替代先 Markdown 预览、后水合的双渲染器方案通过交换代际检查generation-checked swaps、磁盘身份校验modifiedAt fileSize的原文预取缓存、按源码内容精确键控的有界解析块缓存以及仅在前台空闲窗口执行的后台块预热保证大笔记场景下不崩溃、不丢失编辑、不出现过期内容竞争。读完后你将理解这套契约的每个约束在 Tolaria 前端源码中是如何落地为具体常量、缓存结构与调度逻辑的。背景持久化 Markdown 与 BlockNote 渲染之间的张力Tolaria 的笔记是磁盘上持久的 Markdown 文件但富文本编辑层通过 BlockNote 的块结构来渲染。ADR 的 Context 部分指出大笔记曾暴露出一个诱人但危险的优化先显示一个快速的 Markdown 预览再在后台水合出 BlockNote 编辑器。实践中该方案会带来同一份文档存在两个渲染器可见的闪烁flicker点击编辑时的延迟卡顿delayed click-time lag更多让过期异步工作与当前选中笔记发生竞争的位置。因此 ADR 明确了产品优先级的排序后续所有编辑器优化都必须服从这个顺序不崩溃no crashes不出现过期内容、竞争条件覆盖或丢失编辑no stale content, race-condition overwrites, or lost edits打字与光标移动的响应性responsive typing and cursor movement从笔记列表到编辑器的快速加载fast note-list-to-editor loading注意这个排序加载速度排在正确性之后。这决定了 Tolaria 允许预取 缓存 空闲预热来加速打开但禁止先画一个假的预览。核心决策单一直接编辑器表面 有界缓存ADR 的 Decision 部分给出的决策可以概括为一句话Tolaria 为 Markdown 笔记保留单一直接编辑器表面并把编辑器内容交换视为经过代际检查、经过源内容检查的操作。快速加载只能依靠原文文件内容预取和有界的解析块缓存而不能显示一个随后切换为编辑器的独立预览。解析后的 BlockNote 块只有在源 Markdown 与正在打开的内容完全一致时才可复用后台解析必须在前台打字/导航进入空闲状态之后运行。ADR 同时列出了四个被评估的方案及取舍方案结论理由单一直接编辑器表面 防护式交换 有界缓存选中保持文档的单一视觉表示拒绝过期的异步解析结果打开前校验或做身份比对打字相关的工作保持防抖。代价非常大的笔记若未被预热仍要等待 BlockNote 转换快速 Markdown 预览 隐藏 BlockNote 水合弃用改善首帧但引入闪烁、编辑期卡顿、重复的渲染语义无界/激进的后台 BlockNote 解析弃用会让某些打开变快但与打字/导航竞争且带来过期解析结果的风险除非被严格调度、限界、失效大笔记永远使用 raw 模式弃用对超大文件响应性最强但会突兀地改变编辑体验应作为显式回退而非默认实现证据一代际检查的内容交换swap token编辑器内容交换是代际检查操作这一约束在源码中对应useEditorTabSwap这套交换生命周期逻辑。src/hooks/useEditorTabSwap.ts 导入了用于令牌化的工具import { createSwapToken, invalidatePendingSwap, shouldAbortSwap, type SwapToken, } from ./editorSwapTokencreateSwapToken为每次笔记切换生成代际令牌shouldAbortSwap让任何在途的异步交换在令牌失效时自我中止避免为 A 笔记拉取的解析结果落到已经切走的编辑器上invalidatePendingSwap在状态变化时使未完成的交换作废。同一文件中还可以看到交换与防抖体系的协作flushBeforePathChange、flushBeforeRawMode保证在切笔记或切 raw 模式之前先把待写内容落盘useDebouncedEditorChange则把逐键的编辑器变更延迟处理见后文。src/components/Editor.tsx 中的useEditorTabSwap调用与tabsForEditorSwap说明交换逻辑与笔记/表格sheet切换状态机是分开建模的richEditorActiveTabPath等状态用于判定当前哪一条 tab 真正拥有编辑器表面——这正是单一直接编辑器表面在组件层的体现。实现证据二原文预取缓存与 modifiedAt/fileSize 身份校验ADR 要求缓存的原文笔记内容在显示前必须与磁盘校验除非它携带与当前 VaultEntry 相同的modifiedAt和fileSize身份或内容刚由 Tolaria 在当前进程中生成。这一条在 src/hooks/noteContentCache.ts 中得到了完整实现。缓存边界常量export const NOTE_CONTENT_CACHE_LIMIT 24 // 最多缓存 24 条笔记原文 export const NOTE_CONTENT_ENTRY_MAX_BYTES 1024 * 1024 // 单条上限 1 MB export const NOTE_CONTENT_CACHE_MAX_BYTES 8 * 1024 * 1024 // 总字节预算 8 MB export const NOTE_CONTENT_PREFETCH_CONCURRENCY 4 // 预取并发上限 const NOTE_CONTENT_LOAD_RETRY_DELAYS_MS [120, 320, 800] as const // 读盘重试退避缓存条目NoteContentCacheEntry除了 path、content 之外还携带identity: { modifiedAt, fileSize }、vaultPath、请求状态机queued / running / settled / canceled以及可取消的请求句柄startRequest/cancelRequest。超过 1 MB 的内容不会进入缓存retainResolvedNoteContent中直接delete超限缓存会按最旧条目淘汰trimPrefetchCache。身份比对与磁盘新鲜度校验打开一条笔记时loadContentForOpen的决策路径是若未强制刷新且已有解析完成的缓存内容走loadCachedContentIfFresh缓存条目与目标不属于同一个 vault → 直接丢弃matchesCachedContentVault检查cachedEntry.vaultPath targetVaultPath(entry)通过sameIdentity比对modifiedAt与fileSize两者都完整且相等才免校验直接复用——这正对应 ADR 中携带相同 modifiedAt 和 fileSize 身份的豁免条件身份不可信时调用 Tauri 命令validate_note_content拿磁盘上的内容做新鲜度校验markNoteOpenTrace(entry.path, freshnessCheckStart)埋点记录了这一步的耗时校验失败则删除缓存并回落到全量读取。缓存不可用或强制刷新时走loadNoteContent(entry, forceFresh)其中requestState与startRequest保证前台打开可以把尚在排队的预取请求提升为立即执行startNoteContentRequestNow而不是发起重复 IO。预取侧prefetchNoteContent会把请求放入长度受并发上限 4 约束的队列runQueuedPrefetches取消时通过cancelRequest把 Promise 以NOTE_CONTENT_REQUEST_CANCELED拒绝避免被取消的预取污染监听器。加载失败按NOTE_CONTENT_LOAD_RETRY_DELAYS_MS [120, 320, 800]退避重试但文件不存在与非 UTF-8等不可重试错误会直接抛出isMissingNoteContentError/isUnreadableNoteContentError。实现证据三按vault 路径 精确源内容键控的解析块缓存ADR 对解析块缓存的要求是以 vault、path、精确源内容为键读写时克隆且按条目数 源字节预算双重限界。src/hooks/editorParsedBlockCache.ts 是逐条落地的export const PARSED_NOTE_BLOCK_CACHE_LIMIT 6 // 条目数上限 export const PARSED_NOTE_BLOCK_ENTRY_MAX_BYTES 768 * 1024 // 单条源内容上限 768 KB export const PARSED_NOTE_BLOCK_CACHE_MAX_SOURCE_BYTES 3 * 1024 * 1024 // 源字节总预算 3 MB键控cacheKey(path, vaultPath)生成vaultPath \0 path条目里同时保存sourceContent实现vault path两级定位精确源内容检查readParsedNoteBlocks中if (!entry || entry.sourceContent ! options.content) return null——源 Markdown 与当前要打开的内容全字符串相等才允许复用解析结果否则返回 null 触发重新解析。这正是stale parse result被拒之门外的机制读写克隆cloneBlocks优先使用structuredClone回落到JSON.parse(JSON.stringify(...))写入cacheParsedNoteBlocks和读出readParsedNoteBlocks都克隆一份防止编辑器侧的块对象被缓存引用原地修改而互相污染双重限界淘汰trimParsedBlockCache在条目数超过 6 或累计源字节超过 3 MB 时按 Map 插入顺序删除最旧条目单条源内容超过 768 KB 的笔记直接不缓存cacheParsedNoteBlocks开头的早退分支。注意这里的源字节是源 Markdown 的 UTF-8 字节数sourceBytes用TextEncoder测量而不是解析后块结构的体积——预算控制的是为多大的一份文档保留了可复用解析结果。实现证据四空闲窗口内的后台块预热ADR 规定后台解析块预热只允许在前台空闲窗口之后针对可能打开的下一条大 Markdown 笔记进行正在打字、raw 模式、编辑器未挂载都必须推迟它。src/hooks/editorParsedBlockPreload.ts 把这些条件变成了显式常量与判定函数export const PARSED_BLOCK_PRELOAD_MIN_BYTES 32 * 1024 // 只预热 32 KB 的笔记 export const PARSED_BLOCK_PRELOAD_DELAY_MS 1800 // 事件入队后延迟 1.8 s export const PARSED_BLOCK_PRELOAD_FOREGROUND_IDLE_MS 1500 // 距上次前台工作需超过 1.5 s export const PARSED_BLOCK_PRELOAD_ENABLED true入队侧canPreloadParsedBlocks的过滤条件与 ADR 逐条对应事件必须标记parsedBlockPreload即该次内容请求本来就想预热解析块条目必须是 markdown 文件fileKind ! markdown直接跳过文件必须不小于 32 KB——小笔记解析很快不值得预热不能是当前激活 tabentry.path activeTabPath排除。执行侧shouldDeferParsedPreload实现了三类推迟条件并在性能跟踪logParsedBlockPreloadTrace中记录推迟原因推迟条件对应 ADR 条款trace 原因编辑器未挂载editorMountedRef.current falseeditor mount state must defer iteditor-unmountedraw 模式激活raw mode … must defer itraw-mode距上次前台工作打字/导航不足 1.5 sonly after recent typing/navigation has gone idleforeground-active调度本身是单飞 定时重排候选事件先进入queueRef按 path 去重1.8 s 后执行runNext若被推迟则记录 trace 并再次scheduleNext()重排一次执行只处理一个候选runningRef防止并发完成后若队列非空继续排程。每个状态转移queued / deferred / prepared都会写入 src/utils/editorPerformanceTrace.ts 的预热跟踪携带sourceBytes与耗时便于离线分析预热是否真正兑现了空闲期承诺。实现证据五逐键工作保持最小化ADR 最后一条约束每次击键的编辑器工作必须保持最小序列化、元数据推导、自动保存和缓存更新应当防抖、合并或调度到打字之外。源码侧可以看到两个落点src/hooks/useEditorTabSwap.ts 从editorChangeDebounce引入useDebouncedEditorChange并对外导出防抖常量export { RICH_EDITOR_CHANGE_DEBOUNCE_MS } from ./editorChangeDebounce——编辑变更回调本身是防抖的切换路径或切 raw 模式前再由flushBeforePathChange/flushBeforeRawMode做一次性同步落盘保证防抖不丢编辑。解析预热通过foregroundWorkAtRef最近一次前台工作时间戳感知打字活动见上节解析块解析路径自身还区分了快速解析与回退原因src/hooks/editorFastMarkdownBlocks.ts 的FastMarkdownParseMetrics.fallbackReason即解析器遇到它不认识的块结构时会带着明确原因降级而不是静默产出错误块。脏内容权威性本地未保存编辑优先ADR 的另一条后果是本地脏编辑器内容保持权威。外部文件系统刷新可以替换干净的笔记但不能覆盖未保存的本地编辑。在打开链路里这一点的体现是 src/components/editor-content/editorContentState.ts 的可见性推导deriveEditorContentState以当前激活 tab 的内容为主源contentHasTopLevelH1直接读activeTab.content再与来自磁盘扫描的freshEntry最新entries中同 path 的 VaultEntry交叉推导 H1、归档、sheet/HTML/纯文本等展示态isDeletedPreview条目已从 vault 消失这类异常态被显式建模而非覆盖 tab 内容。结合useEditorTabSwap中pendingLocalContentRef与suppressChangeRef的处理本地未保存内容在切换与外部刷新中不会被静默丢弃。这套契约给后续优化的边界ADR 的 Consequences 部分最后一条为未来的大笔记优化划了边界应瞄准真正的渐进式/分块转换或显式的 raw/只读回退状态而不是一个视觉上不同、随后变形为 BlockNote 的预览。结合本仓库现状可以印证这一方向已经部分成型raw 模式回退是显式的editorContentState.ts中effectiveRawMode rawMode || isNonMarkdownText非 Markdown 文本文件强制走 raw 路径showEditor: !effectiveRawMode解析降级是显式的editorFastMarkdownBlocks.ts的fallbackReason指标让快速解析不可用成为可观测事件而非视觉上的格式突变打开链路耗时是显式的noteContentCache.ts与noteOpenPerformance的 trace如freshnessCheckStart/End把校验缓存新鲜度这一步单独计点。换言之0105 号 ADR 不仅是否决了一个看起来更快的方案更是给 Tolaria 的编辑器性能工作立下了一条可审计的验收线任何加速手段都必须先证明它不破坏同一文档只有一个视觉表示、每次交换都经过代际与源内容双重检查这两条不变量。相关行为在 src/hooks/editorParsedBlockPreload.test.tsx 与 src/utils/noteOpenPerformance.extra.test.ts 中有对应测试覆盖可作为理解上述机制的回归依据。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考