三级 Fast Path：让 Git commit 跑得像内存操作

深度观点

三级 Fast Path：让 Git commit 跑得像内存操作

字节跳动 OpenViking 性能优化内幕

Git commit 每次都要重新读文件、算 SHA-1、写 blob——这对 AI 记忆系统是灾难。一个账号可能有上万个记忆片段，但每次 commit 通常只新增 1 个。OpenViking 用三级 Fast Path 把 commit 的 IO 复杂度从 O(n) 压到 O(1)。

1、朴素流程：O(n) 的浪费从哪来

每次 git commit，标准流程是：枚举所有文件 → 逐个读内容 → 计算 SHA-1 → zlib 压缩 → 写入 .git/objects/ → 构建 tree → 写入 commit。问题在于：大多数 commit 只改了少数文件，其他文件完全没变，但 Git 没有缓存机制，每次都重新来过。

对 AI 记忆系统，这是灾难性的：10000 个记忆片段，每次 commit 只新增 1 个，剩下的 9999 个每次都要读、算、写。这是 O(n) 的 IO 成本，n = 文件总数。

OpenViking 的三级 Fast Path，就是在三个不同层次把这笔浪费逐步消除：

2、Fast Path 1：stat cache 跳过 read + SHA-1

核心原理

核心观察：对未修改文件，stat.size 和 stat.mtime_ns 不变。如果 index 记录了上次 commit 时该文件的 (size, mtime_ns, oid)，且当前 stat 与之一致，直接复用 oid，跳过 read + SHA-1 计算。

IndexEntry 缓存结构

pub struct IndexEntry {
size:       u64,    // 文件字节数
mtime_ns:  i128,   // 纳秒级修改时间
oid:        ObjectId, // 上次计算的 blob OID
}

缓存命中判断

if entry.size  == cur_stat.size
    && entry.mtime_ns < saved_at_ns   // racy-clean 防护
    && entry.mtime_ns == cur_stat.mtime_ns
{
// ✅ Fast Path 1 命中：复用 cached oid，跳过 read+SHA1
} else {
// ❌ slow path：读文件 → 算 SHA-1 → 写对象
}

racy-clean 问题：mtime 骗你的情况

Git 经典问题：同一时钟刻度内文件被改了两次（大小相同但内容不同），mtime 相同但内容不同。只比较 mtime 会误判为"文件未变"，复用旧 oid 导致数据损坏。

OpenViking 解法：存 index 文件自身的 mtime 作为 saved_at_ns。只有当 mtime_ns < saved_at_ns 时才信任缓存——文件在 index 保存之后没有再修改过，mtime 不会撒谎。

为什么用纳秒？毫秒级 mtime 在 SSD 时代不够用——SSD 的文件修改时间分辨率远高于毫秒。纳秒级时间戳才能准确区分"文件真的没改"和"同一时钟刻度内改了两次"。

软失败设计

index 加载失败或解码错误时，返回 Ok(None)，commit 退化到 slow path。缓存失效是性能问题，不是正确性问题——不能让缓存问题导致 commit 失败。

3、Fast Path 2：惰性子树复用，最巧妙的优化

核心原理

从 root tree 创建 TreeEditor 时，只加载 root tree 本身，子树按需懒加载。修改某子目录时，只重建该子目录的 tree object，未触及的子树直接复用原有 OID——完全不需要读取 object store。

write_subtree 的三种分支

match self.subtrees.get(&child_prefix) {
Some(entries) if entries.is_empty() => {
continue;   // 空目录：直接剪枝
}
Some(_) => {
// 有修改：递归写子树（可能触发新的 FP2）
child_oid = self.write_subtree(...).await?;
}
None => {
// ✅ FP2：从未触及 → 直接复用原有 OID，零 IO
result_entries.push(entry);
}
}

None 分支是精华——该子树从未被加载或修改（不在 self.subtrees HashMap 中），说明它与上次 commit 完全一致，直接复用原有 OID，完全不读 object store。

SpyObjectStore：用测试保证"真的没读"

SpyObjectStore 包装真实的 ObjectStore，记录所有 get/put 操作。测试通过验证 Fast Path 2 是否真的避免了不必要的读取：

impl SpyObjectStore {
// 验证某个 OID 从未被读取
fn was_read(&self, oid: &ObjectId) -> bool {
self.gets.lock().unwrap()
.iter().any(|o| o == oid)
}
}// 测试用例：只修改 resources/，验证 agent/ 从未被读
let agent_oid = get_agent_subtree_oid();
store.reset();  // 重置 SpyObjectStore 记录
editor.edit_file("resources/new.txt").await;
editor.write(&store).await;
assert!(!store.was_read(&agent_oid));  // ✅ 从未读 agent/

这个测试的意义在于：Fast Path 2 不是"理论上应该不读"，而是"用 SpyObjectStore 实测证明没读"。有测试保证的优化才是可信的优化。

upsert_subtree：restore 的核心工具

restore 操作时，把一整棵历史 tree 的 OID 插入到当前编辑器的某个路径，直接丢弃该路径下所有内存状态。下次 write 直接引用这个 OID，不递归重建——把 O(n) 的 restore 变成 O(1) 的指针替换。

4、Fast Path 3：exists precheck 幂等写入

核心原理

blob 对象写入前，先用 exists(oid) 检查是否已存在。如果存在，直接跳过写入。注意：tree 对象每次 commit 都会重建（parent commit 不同），但 blob 内容（文件内容）本身是不变的——Fast Path 3 针对的是 blob 层。

if self.blob_exists_precheck {
if object_store.exists(account, &oid)
.await
.unwrap_or(false)
{
// ✅ FP3：已存在，跳过写入
return Ok(());
}
}
// ❌ 不存在：走正常写入路径
object_store.put(account, &oid, zlib_body).await;

收益场景

当多个并行 Agent 同时向同一账号提交记忆片段时，很可能写入相同内容的文件（相同文本的向量数据库条目）。Fast Path 3 确保只有第一个写入成功，后续的直接跳过，不浪费 IO 带宽。这是典型的空间换时间：用一次 exists() 查询省掉一次写入。

5、三级组合后的性能收益

假设 AI 记忆账号有 10000 个记忆片段，每次 commit 只新增 1 个片段：

IO 复杂度从 O(n)（n = 文件总数）降到 O(1)（只处理真正变化的文件）。这决定了 commit 是"毫秒级本地操作"还是"秒级磁盘密集型操作"。

6、设计哲学：缓存失效不影响正确性

三级 Fast Path 的设计哲学是：缓存一切可以缓存的，跳过一切可以跳过的，失败时优雅降级。

三个设计原则

FP1 软失败：index 失效 → slow path，不报错。缓存问题是性能问题，不是正确性问题。

FP2 懒加载：未触及的子树 → 永远不加载，不读。HashMap 里没有 = 真的没碰过。

FP3 幂等写入：对象已存在 → 跳过写入，不报错。exists() 查询比写入便宜得多。

整个系统追求的是：在最佳情况下跑得像内存操作，在最差情况下正确工作。这是工程实用主义的体现——不是教科书式的"缓存必须时刻一致"，而是"缓存失效不影响正确性，只影响性能"。

SpyObjectStore 测试也是这个哲学的一部分：不能只靠理论推断说"这个优化有效"，必须有实测数据证明。测试覆盖率是工程可信度的底线。