From cfc09b9ec8ec0729c108b4a8bf736e5f823e9602 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 23 Apr 2026 20:43:56 +0800 Subject: [PATCH] docs: Rewrite the README to clarify the design Signed-off-by: Chojan Shang --- README.md | 72 +++++++++++++++++++++++++------------------- README.zh-CN.md | 79 ++++++++++++++++++++++++------------------------- 2 files changed, 80 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index d5c0474..1f1202a 100644 --- a/README.md +++ b/README.md @@ -2,58 +2,68 @@ English | [简体中文](README.zh-CN.md) -A **protocol-level** unified VFS for AI agents. Bind any URI prefix to any storage backend; get agent-ready tool specs for free. - -`seekvfs` is a thin contract, not a business framework, and not a storage engine. It defines how agents talk to storage — what shape to give the data (single blob, tiered summaries, embeddings, etc.) is up to the backend. Two built-in recipes ship alongside the core: **Minimal** (file-based, zero database) and **Maximal** (filesystem + OceanBase + vector search, the best-combination backend). - -## Why - -Agents need one mental model for "files": one URI scheme, one tool surface, one way to read / write / search. Underneath, different classes of data need different storage (in-memory, filesystem, Postgres, object store, vector DB). This library gives you the facade and the routing; you plug in the backend. +seekvfs is a virtual file system interface for AI agents. It lets you assign different URI prefixes to different storage backends and expose them through a single file interface. The core package only handles URI normalization, prefix-based routing, cross-backend search merging, and agent tool export. Storage layout, indexing, summaries, embeddings, and other implementation details are left to the backend. ## Install +Requires Python 3.11+. + ```bash -# Minimal — core only, no database required pip install seekvfs - -# Full — Maximal recipe + all LangChain providers + all integrations -pip install "seekvfs[full]" ``` -## Pick a recipe - -| Recipe | Use when | Docs | -|---|---|---| -| [`seekvfs_recipes.minimal`](docs/recipes/minimal.md) | **Minimal** — pure filesystem storage, no database needed | [minimal.md](docs/recipes/minimal.md) | -| [`seekvfs_recipes.maximal`](docs/recipes/maximal.md) | **Maximal** — best-combination: FS + OceanBase + vector search | [maximal.md](docs/recipes/maximal.md) | +For the full built-in integrations: -Recipes are NOT part of the protocol — they live under `seekvfs_recipes.*` so the `seekvfs` core package stays free of concrete backends. +```bash +pip install "seekvfs[full]" +``` -## 30-second quickstart +## Quickstart ```python from seekvfs import VFS from seekvfs_recipes.minimal import FileBackend -vfs = VFS(routes={ - "seekvfs://notes/": {"backend": FileBackend("/data/agent_notes")}, -}) +vfs = VFS( + routes={ + "seekvfs://notes/": { + "backend": FileBackend("/data/agent_notes"), + }, + } +) + vfs.write("seekvfs://notes/hello.md", "hello world") + fd = vfs.read("seekvfs://notes/hello.md") -print(fd.content) # b'hello world' +print(fd.content.decode()) + +for item in vfs.ls("seekvfs://notes/"): + print(item.path, item.size) ``` -> Prefix names are yours to choose — the protocol does not recommend any naming convention. +The route key can also be written as a bare prefix like `notes/`; SeekVFS will normalize it to `seekvfs://notes/`. + +More examples: [docs/quickstart.md](docs/quickstart.md) + +## Tools + +`vfs.tools` returns a neutral set of 8 agent tool specs: `search`, `read`, `read_full`, `write`, `edit`, `ls`, `grep`, and `delete`. You can export them to different agent runtimes, including OpenAI, Anthropic, LangGraph, and MCP. + +## Recipes + +| Recipe | Use when | Storage shape | Docs | +|---|---|---|---| +| `seekvfs_recipes.minimal` | You want the smallest persistent backend | One file per path on local disk | [docs/recipes/minimal.md](docs/recipes/minimal.md) | +| `seekvfs_recipes.maximal` | You want tiered reads and semantic search | L2 on filesystem, L0/L1 + embeddings in OceanBase | [docs/recipes/maximal.md](docs/recipes/maximal.md) | -Full walkthrough in [`docs/quickstart.md`](docs/quickstart.md). +You can mix recipes in one `VFS` by mounting them on different URI prefixes. -## Design +## Documentation -- **URI:** `seekvfs://{path}`. Case-preserving. Trailing `/` = directory. -- **Routes:** longest-prefix match from `{prefix: RouteConfig}`. `RouteConfig` only requires `backend`. -- **Protocol contract:** content written via `write` must be retrievable via `read_full`. Everything else — tiers, embeddings, summaries, generation lifecycle — is backend-defined. -- **Tools:** `vfs.tools` returns a neutral `ToolSpecSet` exportable to OpenAI / Anthropic / LangGraph / MCP. +- Quickstart: [docs/quickstart.md](docs/quickstart.md) +- Minimal recipe: [docs/recipes/minimal.md](docs/recipes/minimal.md) +- Maximal recipe: [docs/recipes/maximal.md](docs/recipes/maximal.md) ## License -Apache 2.0. See [`LICENSE`](LICENSE). +[Apache 2.0](LICENSE). diff --git a/README.zh-CN.md b/README.zh-CN.md index 67aabec..5a55d7b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,69 +2,68 @@ [English](README.md) | 简体中文 -面向 AI Agent 的**协议层**统一 VFS。任意 URI 前缀绑任意存储后端,开箱即得可直接给 agent 使用的工具定义。 - -`seekvfs` 是一份**轻薄契约**,不是业务框架,也不是存储引擎。它只规定 agent 如何和存储对话 —— 数据存成什么形状(单块 blob、分层摘要、向量等)由 backend 自己决定。两个内置 recipe 覆盖常见场景:**Minimal**（文件直存,零依赖）和 **Maximal**（文件系统 + OceanBase + 向量检索,最佳搭配组合）。 - -## 为什么要做这个 - -Agent 需要一套统一的"文件"心智模型:一个 URI scheme、一套工具接口、统一的 read / write / search 动作。而底层不同类型的数据需要不同的存储介质(内存、文件系统、Postgres、对象存储、向量库)。本库只提供门面和路由,你把后端插进来就行。 +seekvfs 是一个面向 AI Agent 的虚拟文件系统接口，允许你为不同的存储后端分配不同的 URI 前缀，再以一套统一的文件接口暴露给 agent。核心包只负责 URI 归一化、按前缀路由请求、合并跨后端搜索结果，以及导出 agent 工具。底层的实现细节，如何存储、索引、摘要或 embedding，都由 backend 自己决定。 ## 安装 +要求 Python 3.11+。 + ```bash -# 最小安装 —— 仅核心，无需数据库 pip install seekvfs - -# 全量安装 —— Maximal recipe + 全部 LangChain provider + 全部集成 -pip install "seekvfs[full]" ``` -## 挑一个 recipe +如果需要完整内置集成： -| Recipe | 什么时候用 | 文档 | -|---|---|---| -| [`seekvfs_recipes.minimal`](docs/recipes/minimal.md) | **Minimal** — 纯文件系统存储,无需数据库 | [minimal.md](docs/recipes/minimal.md) | -| [`seekvfs_recipes.maximal`](docs/recipes/maximal.md) | **Maximal** — 最佳搭配组合:FS + OceanBase + 向量搜索 | [maximal.md](docs/recipes/maximal.md) | - -Recipe **不属于协议**,放在 `seekvfs_recipes.*` 下,和 `seekvfs` 核心严格分离。 +```bash +pip install "seekvfs[full]" +``` -## 30 秒快速上手 +## 快速开始 ```python from seekvfs import VFS from seekvfs_recipes.minimal import FileBackend -vfs = VFS(routes={ - "seekvfs://notes/": {"backend": FileBackend("/data/agent_notes")}, -}) +vfs = VFS( + routes={ + "seekvfs://notes/": { + "backend": FileBackend("/data/agent_notes"), + }, + } +) + vfs.write("seekvfs://notes/hello.md", "hello world") + fd = vfs.read("seekvfs://notes/hello.md") -print(fd.content) # b'hello world' +print(fd.content.decode()) + +for item in vfs.ls("seekvfs://notes/"): + print(item.path, item.size) ``` -> 前缀命名由你决定 —— 协议不给出任何命名建议。 +路由前缀也可以写成 `notes/` 这种裸路径，SeekVFS 会自动归一化为 `seekvfs://notes/`。 + +更多示例见：[docs/quickstart.md](docs/quickstart.md) + +## Tools -完整教程见 [`docs/quickstart.md`](docs/quickstart.md)。 +`vfs.tools` 会返回一套中立的 8 个 agent 工具规范：`search`、`read`、`read_full`、`write`、`edit`、`ls`、`grep` 和 `delete`，你可以将其导出给不同的 Agent：比如 OpenAI、Anthropic、LangGraph 和 MCP 等。 -## 设计 +## Recipes -- **URI:** `seekvfs://{path}`,区分大小写,尾斜杠表示目录 -- **路由:** 从 `{前缀: RouteConfig}` 中按最长前缀匹配。`RouteConfig` 只要 `backend` 一个字段 -- **协议承诺:** 通过 `write` 写进去的 content 必须能从 `read_full` 原样取出。其它(分层、embedding、摘要、生成时机)全部由 backend 自定 -- **工具:** `vfs.tools` 返回中立的 `ToolSpecSet`,可导出到 OpenAI / Anthropic / LangGraph / MCP +| Recipe | 适合场景 | 存储形态 | 文档 | +|---|---|---|---| +| `seekvfs_recipes.minimal` | 需要一个最小可持久化 backend | 每个路径对应本地磁盘上的一个文件 | [docs/recipes/minimal.md](docs/recipes/minimal.md) | +| `seekvfs_recipes.maximal` | 需要分层读取和语义搜索 | L2 在文件系统，L0/L1 与 embedding 在 OceanBase | [docs/recipes/maximal.md](docs/recipes/maximal.md) | -## 协议 vs Recipe vs 业务 +同一个 `VFS` 里也可以混用不同 recipe，只要把它们挂到不同 URI 前缀下即可。 -| ✅ 协议层 | ⚙ Recipe 层(官方最佳实践) | ❌ 业务层(留给你) | -|---|---|---| -| `VFS` 门面 + `BackendProtocol` | `OceanbaseFsBackend` 三层 + 向量检索 | 具体对接某 DB 的细节 | -| `seekvfs://` URI 模型 | `Summarizer / Embedder` 协议 | URI 路径的业务含义 | -| 路径前缀路由机制 | `hint="l0"/"l1"/"l2"` 值域 | 具体摘要 prompt / 模型 | -| 工具 `ToolSpec` + 适配器 | `reconcile` 补缺作业 | 路径命名规范 | +## 文档 -一句话:**协议给能力;recipe 给推荐做法;业务给决定。** +- Quickstart: [docs/quickstart.md](docs/quickstart.md) +- Minimal recipe: [docs/recipes/minimal.md](docs/recipes/minimal.md) +- Maximal recipe: [docs/recipes/maximal.md](docs/recipes/maximal.md) -## 许可 +## 许可证 -Apache 2.0,详见 [`LICENSE`](LICENSE)。 +[Apache 2.0](LICENSE)。