Timeline Diff — 版本一致性与脏文本保护

文档发表:2026-07-20 · 更新 4 次 · 最近更新:2026-10-29 · 阅读:173

基于原创 timeline diff 系统解决「文档在外部被更改」导致的版本不一致和脏文本问题

1. 要解决什么问题

一个文件被多处打开——同一个 IDE 的两个窗口、IDE 和外部编辑器、甚至同一个窗口的两个 tab——用户在 A 处编辑、切到 B 处看到的是旧内容,大脑瞬间分裂:我刚刚改的内容去哪了?是谁覆盖了谁?

传统 IDE(VS Code、JetBrains、Sublime)给出的答案是弹窗:「文件在外部被修改了——你要覆盖还是重载?」这个弹窗把文件系统的一致性仲裁推给了用户。用户不知道「外部」是谁,不知道选「是」会丢什么,不知道选「否」的后果。

本质问题是:用户在编辑器里的注意力应该放在「我要写什么」上,而不是「文件系统此刻是什么状态」。

2. 历史方案的失败点

VS Code 模式:「弹窗二选一」

  • 文件被外部改了 → 弹出 File has been modified externally. Reload?
  • 用户必须理解「覆盖」和「重载」的含义
  • 选错了就丢数据
  • 当有 3 个窗口同时打开同一文件,弹窗乱飞

JetBrains 模式:「底部通知 + 非阻塞」

  • 底部出现「File changed externally. Show Diff」
  • 比 VS Code 好——不打断,但用户仍需处理冲突
  • 本质上仍需要用户理解文件版本语义

Apple 版本系统

  • OS 级版本历史,每次保存是一个新版
  • 不存在「覆盖」——但需要整个 OS 栈支持,跨平台不可行

共同缺陷

所有方案都假设:用户应该关心文件系统状态。 这是一个错误的假设。用户只想编辑文本。文件系统是编辑器的领域,编辑器应该自己兜底。

3. 第一层:Timeline Diff — 永不丢失数据的安全网

我们的底层设施是自建的 timeline 版本系统(文件位于 _qqq/timeline/):

存储: blobs/{sha256}.gz  (内容不可变,SHA256 行尾归一化去重)
索引: timeline.db         (SQLite 全量快照)
增量: timeline.wal        (NDJSON ≤99 行)

工作方式

每次编辑器 blur 或 Ctrl+S,触发保存管线:

① _captureExternalBefore(filePath)
   → 读磁盘当前内容
   → 查 timeline 数据库中最新的 blob_hash
   → 解压对比
   → 如果不相等 → 外部修改发生
   → 捕获当前磁盘版本到 timeline(source=editx-before,不走 100s 冷却)

② 写入我们自己的编辑内容到磁盘

③ _xHookRecord / _maybeRecordTimeline
   → 正常保存快照(source=editx,走 100s 冷却 + SHA256 去重)

结果

场景磁盘timeline 里的记录
正常编辑我们的版本editx (单条)
外部先改了外部版本 → 我们的版本editx-before + editx (两条)
两个窗口先后保存后者覆盖前者editx-before(前者的内容) + editx(后者的内容)

任何版本都不会丢失。 任何时候打开 diff 窗口(独立 BrowserWindow,Monaco side-by-side),都能看到完整的版本链。外部修改被静默捕获为一个 before 快照,用户事后可以审查,但从不需要在编辑时做决策。文件系统的噪音被完全隔离在用户注意力之外。

3.5 文件身份:路径键为什么不能靠猜

一个看似简单的问题:/proj/README.md 和 /proj/readme.md 是不是同一个文件?

答案取决于文件系统。而文件系统的行为取决于:平台默认(Windows 不敏感 / Linux 敏感)、卷格式(APFS 可选敏感卷、exFAT 不敏感)、挂载方式(Linux 挂 SMB)、目录标志(Windows 逐目录大小写敏感)、以及 Unicode 归一策略(APFS 存 NFD、NTFS 不归一)。

我们的第一版实现是:按平台猜——只要平台不是 Linux 就折叠大小写。这在绝大多数机器上对,但它本质上是「用平台代理卷、用卷代理目录」。代理一旦错,错误就直接写进数据:两个真文件被并成一条历史,或同一个文件裂成两段。

三条原则

  1. 无损写入——磁盘上只存 OS 给出的原始字节(path_raw)。所有美化(分隔符、盘符、Unicode 归一)都是派生列。判据:如果一条规则读起来像是在「修复」用户给的路径,它就是在销毁信息。
  2. 派生键只是提示——折叠键(fold_key)算错了,最坏后果是多做一次 stat,绝不可能是「已合并」或「无法区分」。判据:这条规则算错,会不会污染数据?
  3. 可重算 + 版本戳——一切派生列都是主键的纯函数,并带 norm_ver。纯函数可以安全地全量重跑;而一旦把判断写进数据,就再也改不回来。

机制:双键 + 撞名对账

record(p):
  key = K(p)                     // 无损:分隔符归一 + 折叠 . / .. / 重复斜杠
                                 //       不折叠大小写、不做 Unicode 归一
  if EXISTS(path_key = key):     // 快路径:这个文件有历史,成本 = 一次索引查询
      append(key)
  else:
      sibs = DISTINCT path_key WHERE fold_key = F(p)   // F = NFC + 小写,纯提示键
      if sibs 为空: insert(key)                        // 真新文件
      else:
          mine = stat(p)                               // ★ 唯一需要问文件系统的时刻
          for s in sibs:
              if stat(s.raw) 与 mine 同 (dev, ino): merge(s → key)   // 同一文件的不同写法
          insert(key)                                   // 否则:两个真文件,保持两条线

查询侧对称:先按 path_key 查(零 IO),查不到才做撞名对账,且无证据只认本键——不自作主张外扩。

三条关键性质:

  • 硬链接天然安全——两个名字不折叠、永不撞名、永不被问到,因此永远不会被误并。
  • 无证据永不合并——文件已删、stat 失败、ino=0(FAT / 部分网络盘)时宁可分裂。分裂可以自愈(下次写入撞上即归并),合并不可逆,这个不对称是刻意设计的。
  • 历史分裂自愈——任何曾裂成两段的历史,用户下次再写该文件时会被 stat 自动归并。不需要迁移、不需要扫描、不需要有人记得。

为什么不是 inode 主键

inode 是「物理对象」的身份,而我们要的是「用户视角的那个文件」。硬链接(两个名字一个 inode)会被误并,删除重建(inode 复用)也会。路径仍是主身份轴,inode 只用来回答一句话:「这两个名字此刻是不是同一个文件」。

四个方案,同一组场景

场景A 平台代理B 探针卷特性C 无损 + 对账D inode 主键
mac 可选敏感卷(两同名异大小写真文件)误并正解正解正解
linux 挂 exFAT(该折叠的不折叠)裂两段正解正解正解
Windows 逐目录大小写敏感误并误并正解正解
NFC/NFD(盘上 NFD、代码字面量 NFC)裂两段需另加归一正解正解
POSIX 上反斜杠文件名不可逆损毁不可逆损毁正解正解
.. / // 路径别名裂裂正解正解
硬链接正解正解正解误并
删除后重建正解正解正解误并
未来规则再错需数据迁移需数据迁移零代价零代价
核心代码量12 行~90 行~60 行~150 行

B 被否掉的理由:探针只能回答「这个卷敏不敏感」,回答不了「这两个路径是不是同一个文件」——而后者才是真问题;它还需要可写目录、需要失效管理,且覆盖不到软链 / .. / 硬链 / 混合归一。

存量与边界(如实)

在「该文件至少可被观测到一次」的前提下是正确的。残留约 0.x%,方向恒为「裂而不并」:

  • 文件已删且从未被观测 → 暂裂,下次写入该文件时自愈;
  • FAT / 部分网络盘 ino=0 → 退化为不合并(不误并);
  • 软链别名(/tmp → /private/tmp)折叠键不同 → 不撞名 → 裂;这类别名需要跨路径解析才能识别,我们不猜;
  • 存量里被旧规则误并的历史:迁移时对能 stat 的组按 inode 重新裁决(文件还在 → 纠正;已删 → 沿用旧结论,不回归)。

一句话:我们把「规则写错」的影响半径,从「数据」压缩到「一次系统调用」。

4. 第二层:跨窗口脏文件追踪 — IDE 领域内视觉一致

Timeline diff 解决了保存后的数据安全。但还有另一个问题:保存前的脏文本不一致。

场景

窗口 A: 编辑 foo.py,内存中有 "abcXYZ"(未保存)
窗口 B: 也打开 foo.py,显示的是磁盘上的旧版本 "abc"

用户切换到窗口 B 的 foo.py tab,看到的是过时的 "abc",虽然窗口 A 里已经有最新的 "abcXYZ"。这是我们 IDE 自己领域内的不一致——磁盘上确实还是旧版本(A 还没保存),但用户期望在不同窗口/不同 tab 里看到同一个版本。

设计

维护一个跨窗口共享的脏文件快照(主进程内存 Map),键是文件路径,值是当前未保存的最新文本。

┌─────────────────────────────────────┐
│  Main Process (共享内存)            │
│  __dirtySnapshots: Map<path,text>   │
└──┬──────────────┬───────────────────┘
   │ IPC          │ IPC
   ▼              ▼
┌──────┐      ┌──────┐
│窗口 A │      │窗口 B │
│编辑中 │      │显示中 │
└──────┘      └──────┘

数据流

① 窗口 A 编辑 foo.py,内容变化
   → debounced (500ms) → bridge.dirty.set("foo.py", content)
   → 主进程存储最新脏文本

② 窗口 B 获得焦点 / 切换到 foo.py 的 tab
   → bridge.dirty.get("foo.py") → 有脏文本
   → 窗口 B 的 Monaco model 更新为脏文本
   → 用户看到的是窗口 A 正在编辑的最新版本

③ 窗口 A 保存(blur 或 Ctrl+S)
   → 写盘 → timeline 捕获 → bridge.dirty.remove("foo.py")
   → 此时磁盘已是最新版本,后续读取天然一致

触发时机(只需两个事件)

  • 窗口获得焦点 (window focus):遍历当前活跃窗口中所有打开的 file tab,逐一检查是否有脏快照
  • tab 切换 (activateTab):切换到的 tab 对应的文件检查是否有脏快照

性能

  • 键盘键入时:仅更新渲染层 DOM(零 IPC),500ms 后才推送一次脏快照到主进程
  • 脏快照存储:主进程内存 Map,零序列化开销
  • 窗口聚焦 / tab 切换:一次 IPC 调用取回文本,零额外开销

5. 两层协同:完整闭环

用户在 IDE 内编辑文件
      │
      ▼
[Layer 2: 脏文件追踪]
  编辑 → debounced push 到主进程
  切窗口/tab → pull 最新脏文本
  保存 → 从主进程删除
      │ (保存触发)
      ▼
[Layer 1: Timeline Diff]
  _captureExternalBefore → 外部修改?捕获 before 快照
  写盘
  _xHookRecord / _maybeRecordTimeline → 正常 after 快照

两层职责完全不同,互不耦合:

  • Layer 2 管未保存的脏文本在 IDE 内部的一致性(我编辑的同一个东西,到处看起来都一样)
  • Layer 1 管保存后的版本永久安全(任何版本都能在 diff 窗口里找回来,不用在弹窗中做决策)

6. 结论

我们给出的方案是一个有两个独立层次的架构:

  • 下层:Timeline diff 提供零数据损失的安全网——捕获所有变化,静默归档,事后可查
  • 上层:跨窗口脏文件追踪提供 IDE 领域内的视觉一致性——无论打开了多少个窗口、多少个 tab 显示同一文件,用户看到的始终是同一个版本

两个层次共同实现了最终目标:用户永远不需要理解、参与或仲裁文件系统的版本冲突。 编辑器的唯一义务是让用户的每一次键盘敲击都安全、连贯、无感知。

而在两层之下还有一条更基本的设计约束:身份判定不能靠猜。 路径按原始字节落盘,判定权交给文件系统本身,任何猜测只作为「提示」并在撞名那一刻被证伪——这样即使判定规则本身写错了,代价也只是一次系统调用,而不是一段再也拼不回来的历史。

这就是我们对于「文件在外部被更改」弹窗问题的解决方案。