omnifs

<div align="center"> # 🗄️ 全息文件系统 **给予你的AI代理记忆、时间旅行和意义搜索的文件系统。** NTFS和ext4保存*字节*。全息文件系统保存**字节 + 历史 + 意义 + 作者** — 按操作版本控制、语义搜索和来源，**离线且仅在一个二进制文件中**。       </div> --- ## 📑 目录 - [30秒了解](#-30秒了解) - [问题](#-问题) - [全息文件系统 vs git vs 普通文件系统](#-全息文件系统-vs-git-vs-普通文件系统) - [架构](#-架构) - [工作原理](#-工作原理) - [安装](#-安装) - [使用](#-使用) - [克劳德代码（MCP）](#-克劳德代码-mcp) - [已证明的结果](#-已证明的结果) - [实证测量](#-实证测量-为什么我们构建它) - [平台](#-平台) - [路线图](#-路线图) - [诚实的局限性](#-诚实的局限性) - [常见问题](#-常见问题) - [开发](#-开发) --- ## ⚡ 30秒了解 ```console $ omnifs init ~/磁盘/.omnifs-drive $ omnifs mount ~/磁盘/.omnifs-drive ~/OmniDrive # 变成一个普通驱动 $ echo "验证登录和密码的函数" > ~/OmniDrive/auth.rs # 保存 → 自动提交 $ omnifs index ~/磁盘/.omnifs-drive 索引 1 个文件 $ omnifs search ~/磁盘/.omnifs-drive "在哪里检查用户访问" 0.638 auth.rs — 验证登录和密码的函数 # 通过意义找到，无需grep $ omnifs snapshot ~/磁盘/.omnifs-drive "修改前" snapshot: b4b7f7cb8ffe... # ...代理做错事... $ omnifs rollback ~/磁盘/.omnifs-drive b4b7f7cb8ffe... # 整个树恢复，字节忠实 ``` 你在一个普通驱动上工作。在底层：**每次保存都版本化**，**所有内容都可按意义搜索**，并且**可以穿越时间** — 无需你（或代理）配置任何内容。 ## 🎯 问题 一个AI代理（克劳德代码）有I/O配置文件，而NTFS/ext4从来不是为此设计的： | 代理… | …但普通文件系统提供 | |---|---| | 编辑并**出错** | "保存，没事"（撤销 = 你祈祷已经提交） | | 按**意义**搜索（“身份验证逻辑”） | 字面`grep`（找到`*.py`，不是概念） | | **并行**工作（N个工作线程） | 行冲突，覆盖 | | 有**有限的上下文窗口** | 要么读取整个5000行的文件，要么什么都没有 | | 每次写入都有**作者和意图** | 匿名字节；`git blame`手动 | 全息文件系统在**现有文件系统之上运行**（FUSE层，非块）。`cat`/`Edit`/`cp`/`grep`**与现有文件系统完全相同** — 在底层，每次写入都变成版本 + 索引。 ## 🆚 全息文件系统 vs git vs 普通文件系统 | | 普通文件系统 | git | **全息文件系统** | |---|:---:|:---:|:---:| | 保存字节 | ✅ | ✅ | ✅ | | **自动**版本控制（无需手动提交） | ❌ | ❌ | ✅ （在`release`时） | | 整个树 rollback | ❌ | ✅ | ✅ | | 按**意义**搜索 | ❌ | ❌ | ✅ （MiniLM） | | 内容重复数据删除 | ❌ | ✅ | ✅ （BLAKE3） | | 作为**透明驱动**可用 | ✅ | ❌ | ✅ （FUSE） | | 在上面运行**git / 符号链接 / 设备** | ✅ | — | ✅ （完整POSIX） | | 快速写入 | ✅ | ✅ | ✅ （**284 MB/s**，异步提交） | | 代理**原生工具**（MCP） | ❌ | ❌ | ✅ | | 离线 / 零运行时依赖 | ✅ | ✅ | ✅ | ## 🧱 架构 ``` ┌─ omnifs-cli ──── init · put · get · mount · snapshot · log · rollback · index · search ├─ omnifs-mcp ──── MCP服务器（stdio JSON-RPC）；统一FUSE+MCP守护进程，位于同一存储 ├─ omnifs-fuse ──── POSIX投影（fuser 0.14）+ 释放时的自动提交；通过Arc存储 ├─ omnifs-index ── 语义搜索（fastembed MiniLM 384d + 余弦）；~/.cache/omnifs缓存 ├─ omnifs-txn ──── CoW版本控制：内容寻址提交（树 + 父节点 + 时间戳 + 消息） └─ omnifs-store ── 内容寻址对象存储（BLAKE3 + redb），重复数据删除，引用（HEAD/分支） ``` > **核心 ≠ 智能**。核心（存储 + 版本 + POSIX）始终是快速的，零依赖的。语义搜索是一个在上面加载的模块 — 文件系统在没有它的情况下仍然可以完美运行。 ## 🔬 工作原理 1. **你保存**一个文件到挂载点（`~/OmniDrive`）。 2. **FUSE**拦截`release`（文件关闭）并**异步**排队一个自动提交（不阻塞写入 — 因此达到284 MB/s）：一个工作线程进行BLAKE3哈希 → 将其存储在**对象存储**（`redb`）。相同内容 = 相同哈希 = 只存储一次（重复数据删除）。`.git`/`node_modules`/build被忽略，因此存储不会随着依赖项膨胀。 3. **快照**将整个树捕获为一个提交（路径映射 → 哈希）+ 父节点 + 消息，序列化并存储在同一存储中。`rollback`将树重写为提交状态。 4. **索引**读取文本文件，生成嵌入（MiniLM，384维，离线）并存储向量。`search`嵌入查询并按**余弦**排名 — 按意义查找。 5. **MCP**将所有内容公开为工具，克劳德调用它们。统一守护进程在**同一对象存储**上运行FUSE和MCP（通过`Arc`），因此挂载和搜索在同一进程中协同工作，无需锁冲突。 ## 📦 安装 ```bash sudo apt install fuse3 libfuse3-dev # 唯一的系统前提要求 git clone <仓库> && cd omnifs cargo build --release cp target/release/{omnifs,omnifs-mcp} ~/.cargo/bin/ ``` ## 🚀 使用 ### 版本控制驱动（隐藏内部） ```bash omnifs init ~/磁盘/.omnifs-drive # 点目录 = 隐藏；保存存储 + 后备 omnifs mount ~/磁盘/.omnifs-drive ~/OmniDrive # 在~/OmniDrive上像普通驱动一样工作 — 每次保存都自动提交 ``` ### 开发仓库（git和符号链接在挂载内工作） ```console $ cd ~/OmniDrive $ git init && git add -A && git commit -m "v1" # 提交有效（处理表用于松散对象 0444） $ ln -s src/main.rs shortcut.rs # 保存符号链接（node_modules/venv） $ df -h ~/OmniDrive # df报告磁盘实际大小 ``` ### 时间旅行 ```console $ omnifs snapshot ~/磁盘/.omnifs-drive "v1" b565dc5ccce7... $ omnifs log ~/磁盘/.omnifs-drive 57d928c098d4 v2 b565dc5ccce7 v1 $ omnifs rollback ~/磁盘/.omnifs-drive b565dc5ccce7 # 回滚到v1（字节忠实，删除孤儿） ``` ### 语义搜索 ```console $ omnifs index ~/磁盘/.omnifs-drive 索引 5 个文件 $ omnifs search ~/磁盘/.omnifs-drive "在用户空间中挂载posix文件系统" 0.392 fuse.rs — 通过FUSE进行POSIX投影... ``` ## 🤖 克劳德代码（MCP） 语义搜索**不是透明的** — 文件系统不能将`grep`转换为语义（意图在系统调用中丢失）。代理通过MCP**调用工具**: ```bash claude mcp add omnifs --scope user -- ~/.cargo/bin/omnifs-mcp ~/磁盘/.omnifs-drive ~/OmniDrive ``` 在每个会话中，克劳德获得`omnifs_snapshot · log · rollback · index · search`，驱动器挂载，意义搜索在**单个进程中**可用，无需锁冲突。 ## ✅ 已证明的结果 | 验证 | 结果 | |---|---| | 字节忠实的自动提交 | ✅ 二进制文件 `\x00`/`\xff` 与挂载↔存储相同 | | 回滚 | ✅ 恢复树 + 从最新快照中删除孤儿 | | 跨语言**语义** | `auth`（EN，代码）× `login/senha`（PT）= **0.419** · vs `cart` = **-0.043** | | 真实代码中的语义 | **4/4 top-1** （中性名称，查询无文件名） | | 统一守护进程 | FUSE + MCP同时在同一存储上运行，**无“数据库已打开”错误** | | **真实git** 在挂载上 | `init`+`add`+`commit`×2，工作树干净，`cat-file`读取对象返回 | | **符号链接 · df** | `ln -s`保存链接（node_modules/venv）；`df`报告磁盘实际大小 | | **吞吐量** | 1.1秒内300 MB带fsync = **284 MB/s** （之前~0.65 MB/s — ~437×） | | **索引 + 存储过滤** | `.git`/`node_modules`/build被忽略 — 搜索中**0命中**，存储中**0 KB** | | 套件 | **8个绿色测试** （6个存储 + 1个事务 + 1个索引） | ## 📊 实证测量（为什么我们构建它） 在编写一行代码之前，我们挖掘了**666个真实克劳德代码转录本（46,290次工具调用）**来验证前提 — 而不是依赖猜测： | 支柱 | 测量的信号 | 结论 | |---|---|---| | 语义搜索 | **~10%**的操作是定位代码（从22.9%原始数据精炼） | 🟢 #1 — 值得 | | 线性时间旅行 | **0.32%**的操作使用`git reset` | 🔴 在本地较弱（在基础设施上较强） | | 远程操作 | **~50%**的搜索是ssh/docker/VPS | ⚠️ 超出本地文件系统的范围 | 实际的主要成本：**387亿缓存读取令牌**（重新处理的上下文）。测量者在[`docs/measurement/`](docs/measurement/)，决策在[ADR 0001](docs/adr/0001-omnifs-architecture-and-measurement.md)。 ## 💻 平台 | | 核心 + 搜索 + MCP | 透明挂载 | |---|:---:|:---:| | **Linux** | ✅ | ✅ 原生 | | **Windows（WSL2）** | ✅ | ✅ （真实Linux内核 + `/dev/fuse`） | | **macOS** | ✅ | ✅ 使用macFUSE | | Windows原生（Win32） | ✅ | ❌ （需要后端WinFSP） | 核心是纯Rust + ONNX Runtime（每个操作系统二进制文件）。只有透明挂载是操作系统特定的。 ## 🗺️ 路线图 - [x] 内容寻址对象存储（BLAKE3 + redb） - [x] 时间旅行（快照/日志/回滚） - [x] 语义搜索（MiniLM + 余弦） - [x] POSIX投影（FUSE）+ 自动提交 — **完整POSIX**：重命名 · 符号链接 · readlink · statfs · 链接 · fsync - [x] **真实开发文件系统** — `git commit`，符号链接和`df`在挂载内工作 - [x] **吞吐量** — 异步自动提交 + 1 MB缓冲区 → **284 MB/s** （之前0.65） - [x] **索引 + 存储过滤** — 跳过`.git`/`node_modules`/build和>512 KB文件 - [x] MCP（5个工具）+ 统一守护进程 - [ ] **套接字守护进程** — 始终连接的挂载 + 搜索，独立于克劳德 - [ ] **FUSE存储支持** — 单个不透明文件，零可见备份（完全隐藏） - [ ] **命名分支 + 按提示来源** - [ ] **PDF/图像提取器** （pdftotext/OCR）— 索引媒体 - [ ] **HNSW** — 亚线性搜索（> 10k文件；当前线性扫描） - [ ] **AST摘要** （tree-sitter）— 提取摘要，无需LLM ## ⚠️ 诚实的局限性 - **`redb` 是单写入器** → FUSE + MCP通过**统一守护进程**共存（解决）；**守护进程外部**的进程无法同时写入同一个存储。 - **按文件搜索**（非按功能）和**线性扫描** — 适用于~10k文件。 - **无媒体提取器** — PDF/图像保存字节忠实，但不索引。 - **大规模迁移源慢** （例如HDD失败）受源限制，不受全息文件系统限制 — 对于损坏的磁盘，请先复制到ext4。 ## ❓ 常见问题 **卸载时文件会与我一起消失吗？** 不。它们存在于隐藏存储（内容寻址）；挂载只是**投影**。卸载 = 文件夹变空，重新挂载 = 一切恢复。 **我需要互联网 / GPU / Ollama吗？** 不。所有操作离线，CPU。嵌入模型（~90 MB）**一次下载**并存储在`~/.cache/omnifs`。 **支持媒体（PDF，照片）吗？** 字节忠实保存。是的。索引（按内容搜索）还不支持 — 正在开发中。 **安全吗？可以删除我的磁盘吗？** 不格式化任何内容。存在于**现有文件系统内的目录**中。 ## 🛠️ 开发 ```bash cargo build # 工作区（拉取fuser、redb、fastembed/ort、blake3） cargo test # 8个测试（索引测试是#[ignore] — 下载模型） cargo build --release # 优化二进制文件 ``` 结构：`crates/`中的6个crate，规范在[`docs/superpowers/specs/`](docs/superpowers/specs/)中，决策在[`docs/adr/`](docs/adr/)中。 ## 📄 许可证 MIT. --- <div align="center">_{使用<b>代码前测量</b>构建。18次提交 · 8个绿色测试 · 100%离线 · 284 MB/s写入速度。}</div>