基于原创 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 就折叠大小写。这在绝大多数机器上对,但它本质上是「用平台代理卷、用卷代理目录」。代理一旦错,错误就直接写进数据:两个真文件被并成一条历史,或同一个文件裂成两段。
三条原则
- 无损写入——磁盘上只存 OS 给出的原始字节(
path_raw)。所有美化(分隔符、盘符、Unicode 归一)都是派生列。判据:如果一条规则读起来像是在「修复」用户给的路径,它就是在销毁信息。 - 派生键只是提示——折叠键(
fold_key)算错了,最坏后果是多做一次 stat,绝不可能是「已合并」或「无法区分」。判据:这条规则算错,会不会污染数据? - 可重算 + 版本戳——一切派生列都是主键的纯函数,并带
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 显示同一文件,用户看到的始终是同一个版本
两个层次共同实现了最终目标:用户永远不需要理解、参与或仲裁文件系统的版本冲突。 编辑器的唯一义务是让用户的每一次键盘敲击都安全、连贯、无感知。
而在两层之下还有一条更基本的设计约束:身份判定不能靠猜。 路径按原始字节落盘,判定权交给文件系统本身,任何猜测只作为「提示」并在撞名那一刻被证伪——这样即使判定规则本身写错了,代价也只是一次系统调用,而不是一段再也拼不回来的历史。
这就是我们对于「文件在外部被更改」弹窗问题的解决方案。