Skip to content

docs: Rewrite the README to clarify the design #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Evenss merged 1 commit into from
Apr 23, 2026
Merged

docs: Rewrite the README to clarify the design #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 41 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
79 changes: 39 additions & 40 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)。
Loading