Ephemeral-AI-Lab/layerfs

LayerFS – 面向 AI 代理工作区的 SQLite 后端、内容寻址的“时间机器”

它是什么

• 一个库、CLI 和基于 FUSE 的文件系统，让 AI 代理（或任何接触文件系统的工具）在临时工作区内工作。
• 当代理完成一个步骤时，工作区可以被提交——将整个文件系统快照转换为不可变的提交。
• 提交存储在 LayerStack 中：使用三种经典技术构建的层历史：
  1. 内容寻址存储 (CAS) – 对象以其字节的哈希命名，因此相同的数据只存储一次。
  2. 内容定义分块 (CDC) – 文件被分割成稳定的块；微小的编辑只创建新块，而不是整个文件的新副本。
  3. 写时复制 (COW) – 发布新层时，只重写更改的目录和文件。
• 整个历史存储在一个单一的 SQLite 数据库（Store）中。该数据库对代理是只读的；只有 LayerFS 运行时在发布提交时写入它。

为什么对 AI 很重要

• 现代自主代理（LLM 驱动的规划器、基于人类反馈的强化学习循环、多代理模拟）需要尝试代码、数据或配置的许多假设变体。
• 为每次试验重新创建大型工作区的完整副本是浪费的。LayerFS 让代理可以分叉先前的层（零复制）并运行多个并行展开，然后提升最佳分支。
• 由于历史是不可变且内容寻址的，系统可以在数千次试验中消除大量重复数据，大幅减少存储和 I/O。

关键组件（截至 v0.1.6 开发者预览版）

组件	角色
存储引擎	管理 CAS、CDC、COW、对象验证和 SQLite Store。
SDK	Rust 库，暴露 Client、LayerStack、Branch、Workspace 等类型以及创建/提交/查询它们的函数。
CLI (layerfs-cli)	用于创建 Store、初始化 LayerStack、生成工作区、提交和检查历史的命令行界面。
文件系统投影	提供挂载点（通过主机物化或 FUSE 容器），对代理显示为普通目录。
容器运行时	使用 FUSE 启动轻量级 Linux 容器，将可变工作区保留在容器内，而持久 Store 保留在主机上。

典型工作流程

1. 创建 Store – layerfs db create store.sqlite。
2. 初始化 LayerStack – layerfs layerstack init --name demo --empty 创建创世层。
3. 启动工作区 – layerfs workspace exec <branch> 启动一个进程（或容器），具有文件系统的私有视图。
4. 执行工作 – 代理运行其工具、写入文件等。
5. 提交 – layerfs commit <workspace> 将可变状态转换为不可变提交，并将其附加到当前分支。
6. 分支 / 分叉 – 从任何先前的提交创建新分支，以探索替代方案而无需复制数据。

性能亮点 (v0.1.6)

• 向 32 MiB 文件添加 10 字节仅使逻辑存储大小增加 ≈ 0.026 MiB（得益于 CDC）。
• 跨工作区的六次确定性编辑使逻辑存储增长 ≈ 0.225 MiB。
• 所有测量来自真实 FUSE 基准测试套件；底层 SQLite 页面可能增长更多，但逻辑内容保持微小。

限制（重要须知）

• 仅限开发者预览版 – 无崩溃或断电持久性保证；请备份重要数据。
• 每个客户端一个 Store；尚无跨主机同步。
• 提交不自动 fsync；沙箱的可变状态在提交发布前仅存在于内存中。
• 只有单个构建工作者构建不可变对象，使大型批量导入比早期版本慢。
• 无显式压缩；旧存储保持可读，但系统不会自动回收空间。
• CLI JSON 输出是临时格式，不是稳定 API。

入门

# 克隆 v0.1.6 标签（预览代码位于 `crates/` 下）
git clone https://github.com/Ephemeral-AI-Lab/layerfs.git
cd layerfs && git checkout v0.1.6

# 构建 CLI（需要 Rust 1.85+，macOS/Linux）
cargo build --release -p layerfs-cli
export LAYERFS_BIN=$PWD/target/release/layerfs
export LAYERFS_CONTEXT=$PWD/.layerfs/context
mkdir -p $PWD/.layerfs

# 创建 SQLite 存储和演示 LayerStack
$LAYERFS_BIN db create $PWD/.layerfs/store.sqlite
$LAYERFS_BIN context use --store $PWD/.layerfs/store.sqlite
$LAYERFS_BIN layerstack init --name demo --empty
$LAYERFS_BIN query layerstacks

继续阅读版本特定的快速入门指南，了解分支创建、工作区执行和可选的 FUSE 容器使用。

路线图快照

• 0.2.0（计划） – 可移植投影层（reflink/clonefile，未来支持 OverlayFS）。
• 稍后 – 跨主机存储导出/导入、同步和更丰富的运行时集成。

社区与支持

• Discord: https://discord.gg/DrgJ4DX9E
• 微信群（仓库中有二维码）– 邀请定期过期。
• 在 X 上关注项目负责人: @yifanxu_ephai

许可证 – MIT。

---

LayerFS 是一个研究级工具，面向构建需要廉价、版本化文件系统状态的自主 AI 代理的开发者。它还不是生产级存储系统，但为实验“临时工作区 + 持久共享历史”模式提供了具体平台。