vfs (Tr Ng Tien)

虚拟文件系统

虚拟函数签名 --从源代码中提取导出的函数、类、接口和类型签名，并去掉正文。

目录

• 为什么选择vfs？
• 运作原理
• 基准
• 安全与隐私
• 支持的语言
• 安装

- 预构建二进制文件 - 从源代码构建 - 码头工人

• 快速开始
• CLI 参考
• AI工具设置

- 第一步：连接vfs - 步骤2：定义代理规则

• 贡献
• 被使用
• 许可证
• 明星历史

为什么选择vfs？

AI编码代理通过grepping或读取整个文件来寻找函数，从而浪费令牌。vfs通过AST和树形图解析源代码，只返回签名——任何代码库的一个紧凑的“目录”。

每次搜索的令牌减少60-70%。

它适用于任何AI编码工具——Cursor、Claude Code、Antigravity、Windsurf、Cline、Continue、Aider、Copilot、Zed或您自己的脚本。没有供应商锁定。

运作原理

flowchart TD
    A["Agent classifies intent"] --> B{"Intent?"}

    B -->|Locate| C["vfs search"]
    B -->|Understand| C
    B -->|Modify| C
    B -->|Debug| D["Grep / Read"]

    C --> E["file:line + signature\n~370 tokens"]
    E --> F{"Need behavior\nor just location?"}

    F -->|"Location only"| Done["Done"]
    F -->|"Need behavior"| G["Read exact lines\n(body + imports)"]

    G --> H{"Modifying?"}
    H -->|Yes| I["Grep for callers"]
    H -->|No| Done

    I --> Done
    D --> Done

代理人首先对其意图进行分类。对于 定位, 理解，以及 修改 实际上，vfs首先运行以获取签名（约370个令牌，而读取文件约26000个令牌）。只有这样，代理才能根据需要为呼叫者读取确切的行或Grep。对于 调试 意图，Grep是第一位的，因为你需要在函数体内搜索。

给定一个包含数千行的Go项目，询问“登录处理程序在哪里？”传统上意味着grepping或读取整个文件。vfs只给你签名：

$ vfs . -f login
internal/handlers/auth.go:23:   func HandleLogin(w http.ResponseWriter, r *http.Request)
internal/services/auth.go:10:   func ValidateToken(token string) (*Claims, error)
internal/middleware/jwt.go:45:  func RequireLogin(next http.Handler) http.Handler

每一行告诉你 文件, 行号，以及 完整签名 --无功能体，无进口，无噪音。然后，您（或您的AI代理）可以只读取所需的确切行。

这适用于17种语言：

$ vfs ./frontend -f auth
src/hooks/useAuth.ts:5:         export function useAuth(): AuthContext
src/components/LoginForm.tsx:12: export const LoginForm: React.FC
src/api/client.py:28:           def authenticate(username: str, password: str) -> Token

基准

此存储库上的自我基准测试（模式 "Extract"4178行源代码）：

• vfs节省了98.6%的代币 vs读取所有文件（26079->373）
• vfs节省89.5%的代币 vs grep（3537->373）

自己运行：

vfs bench --self                                   # self-test on vfs source
vfs bench -f HandleLogin /path/to/go-project       # benchmark on any project
vfs bench -f Login /path/to/project --show-output  # show actual output

安全与隐私

本地优先设计。 你的源代码永远不会离开你的机器。

• 零网络接入 --所有解析都是通过AST和树状图进行本地解析的。从来没有出站连接。
• 无秘密泄露 --不读取、访问或存储API密钥、凭据或环境变量。
• 无数据收集 --没有遥测，没有分析，没有跟踪。
• 无代码存储 --源代码在内存中被解析并丢弃。仅 ~/.vfs/history.jsonl （扫描统计）已写入。
• 完全离线 --安装一次，永远使用。

支持的语言

安装

预构建二进制文件

下载自 不需要Go，也不需要C编译器。每个版本都包含SHA-256校验和。

# Linux x86_64
curl -L https://github.com/TrNgTien/vfs/releases/latest/download/vfs-linux-amd64.tar.gz | tar xz
sudo mv vfs /usr/local/bin/

# Linux ARM64
curl -L https://github.com/TrNgTien/vfs/releases/latest/download/vfs-linux-arm64.tar.gz | tar xz
sudo mv vfs /usr/local/bin/

从源代码构建

需要 转到1.24+ 和一个 C编译器:

• macOS: xcode-select --install
• 一种计算机操作系统: sudo apt install build-essential （Debian/Ubuntu）或 sudo yum groupinstall "Development Tools" （Fedora/RHEL）

git clone https://github.com/TrNgTien/vfs.git && cd vfs
go install ./cmd/vfs

vfs: command not found? 将Go的bin添加到您的PATH中： export PATH="$PATH:$(go env GOPATH)/bin" （macOS/Linux）或添加 %USERPROFILE%\go\bin 到PATH（Windows）。

码头工人

docker build -t vfs-mcp .
docker run --rm -v $(pwd):/workspace -p 8080:8080 -p 3000:3000 vfs-mcp

# Custom ports via environment variables
docker run --rm -v $(pwd):/workspace -e VFS_PORT=9090 -e VFS_DASHBOARD_PORT=4000 -p 9090:9090 -p 4000:4000 vfs-mcp

快速开始

# Find a function by name (case-insensitive)
vfs . -f HandleLogin

# Scan specific directories
vfs ./internal ./pkg

# List all signatures in a single file
vfs server.go

# Show token savings stats after output
vfs . -f auth --stats

# Start the MCP server + dashboard in the background
vfs up

# Start on a custom port (default: 8080)
vfs up --port 9090

# Check server status
vfs status

# Stop the server
vfs down

打开仪表板http://localhost:3000查看使用统计数据和代币随时间的节省情况。

跑 vfs --help 用于所有命令和标志。

CLI 参考

`vfs [paths...] -f

`

主要命令。扫描文件/目录并打印导出的签名。

vfs .                          # all signatures in current directory (recursive)
vfs ./src ./lib                # scan multiple directories
vfs handler.go                 # single file
vfs . -f auth                  # filter by pattern (case-insensitive)
vfs . -f auth --stats          # show token efficiency stats after output
vfs . -f auth --no-record      # skip logging to history

旗帜：

vfs bench

比较令牌使用情况：读取所有文件vs grep vs vfs。

vfs bench --self                              # benchmark on vfs's own source
vfs bench -f HandleLogin /path/to/project     # benchmark on any project
vfs bench -f Login /path/to/project --show-output  # also print actual output

vfs stats

显示所有记录的调用的生命周期令牌节省。

vfs stats            # show summary
vfs stats --reset    # clear all history

输出示例：

--- vfs lifetime stats ---
Invocations:         142
Total tokens saved:  ~52,300
Total raw scanned:   2.3 MB  (48,200 lines)
Total vfs output:    89.5 KB  (1,420 lines)
Avg reduction:       72.3%
First recorded:      2025-01-15 09:30
Last recorded:       2025-03-09 14:22

vfs mcp

启动MCP服务器以集成AI工具。

vfs mcp                  # stdio transport (default, for editor integration)
vfs mcp --http :8080     # HTTP transport (for Docker / remote setups)

vfs serve

在前台同时运行MCP服务器（HTTP）和仪表板。

vfs serve                                    # defaults: MCP on :8080, dashboard on :3000
vfs serve --port 9090                        # MCP on :9090
vfs serve --port 9090 --dashboard-port 4000  # both custom
vfs serve --mcp :9090 --dashboard-port 4000  # equivalent (full address form)

vfs up / vfs down / vfs status

将服务器作为后台进程进行管理。

vfs up                  # start MCP + dashboard in background (default port 8080)
vfs up --port 9090      # start on custom MCP port
vfs status              # check if running, show endpoints
vfs status --port 9090  # check custom port
vfs down                # stop the background server

vfs dashboard

只运行仪表板web UI（不含MCP服务器）。

vfs dashboard                # default port 3000
vfs dashboard --port 4000    # custom port

AI工具设置

设置vfs需要 两个步骤:

1. 连接vfs --配置MCP或使CLI可用，以便代理 *能* 呼叫vfs。
2. 添加代理规则 --告诉代理人 *应该* 在grep之前调用vfs。如果没有这个，即使vfs可用，代理仍将默认为grep/read。

第二步至关重要。 AI代理不会自动知道vfs的存在。您必须添加一个规则文件，指示代理使用vfs进行代码发现。每个工具都有自己的规则文件格式——请参阅 第二步：代理规则 在......下面

第一步：连接vfs

vfs可与任何支持以下功能的AI编码工具配合使用 MCP（模型上下文协议）。如果您的工具不支持MCP，您可以使用vfs作为代理通过shell调用的CLI命令。

方法1:MCP集成（推荐）

MCP允许AI代理调用vfs工具(search, extract, list_languages)直接无需shell访问。即使在代理无法运行任意二进制文件的沙盒环境中，这也适用。

MCP工具

大多数工具使用相同的stdio JSON配置。唯一的区别是文件所在的位置：

标准配置 （光标、克劳德代码、克劳德桌面、反重力、风帆、克莱恩）：

{
  "mcpServers": {
    "vfs": {
      "command": "vfs",
      "args": ["mcp"]
    }
  }
}

继续 使用不同的结构：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "vfs",
          "args": ["mcp"]
        }
      }
    ]
  }
}

泽德 使用不同的结构：

{
  "context_servers": {
    "vfs": {
      "command": {
        "path": "vfs",
        "args": ["mcp"]
      }
    }
  }
}

HTTP配置 （对于Docker、远程设置或任何支持基于HTTP的MCP的工具）：

vfs up                  # starts MCP on :8080 and dashboard on :3000
vfs up --port 9090      # starts MCP on :9090 and dashboard on :3000

{
  "mcpServers": {
    "vfs": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

如果使用自定义端口，请相应地更新URL（例如。 http://localhost:9090/mcp).

方法2:CLI集成

对于不支持MCP的工具（Aider、自定义脚本、CI），请使用vfs作为shell命令：

vfs . -f CreateUser
# Output: internal/services/user.go:42: func CreateUser(name string, email string) (*User, error)

vfs . -f handler | head -20

LOCATION=$(vfs . -f CreateUser | head -1)
FILE=$(echo "$LOCATION" | cut -d: -f1)
LINE=$(echo "$LOCATION" | cut -d: -f2)
echo "Found at $FILE line $LINE"

步骤2：定义代理规则（必填）

安装vfs是不够的。 AI代理不会自动知道vfs的存在。如果没有明确的规则，代理仍将默认为grep并读取整个文件——浪费vfs旨在保存的令牌。 AGENTS.md 在这个repo中 文档 这就解释了vfs是如何工作的。它是 不 强制代理使用vfs的规则。您需要在自己的项目中创建一个规则文件。

您必须创建一个 规则文件 在您的项目中，指示代理：“在grep之前使用vfs进行代码发现。”此仓库在 .cursor/rules/vfs-agent-search.mdc --您可以直接重用它，也可以根据您的工具进行调整。

每个AI工具都有自己的规则系统：

在规则文件中放入什么

无论使用何种工具，核心指令都是相同的。为您的工具创建规则文件（见上表）并添加以下内容：

# vfs: Use AST-based search before grep

When looking for function definitions, method signatures, class names, or type
declarations, you MUST use vfs before grep or reading entire files.

## How to call vfs

MCP (preferred -- works in sandboxed editors):
  search(paths: ["."], pattern: "functionName")

CLI (fallback -- if MCP is not available):
  vfs . -f functionName

## Workflow

1. Call vfs search with the name you're looking for.
2. vfs returns file paths and line numbers.
3. Read ONLY the specific lines returned -- not the whole file.

## When to skip vfs and use grep directly

- Searching inside function bodies (string literals, error messages, config keys)
- Searching non-code files (JSON, CSS, .env, markdown)
- You already know the exact file and line number
- vfs returned no results for your query

## Why this matters

vfs parses source via AST and returns only signatures (bodies stripped).
This saves 60-70% tokens compared to grep. Do not skip this step.

示例：设置Cursor

mkdir -p .cursor/rules

然后创建 .cursor/rules/vfs.mdc 根据上述规则内容。此仓库包括一个完整的、可用于生产的游标规则，位于 .cursor/rules/vfs-agent-search.mdc 您可以直接复制：

cp /path/to/vfs/.cursor/rules/vfs-agent-search.mdc .cursor/rules/

示例：设置反重力

创建 GEMINI.md 在您的项目根目录中使用上述规则内容。反重力阅读 GEMINI.md 作为其原生配置。它还读到 AGENTS.md 对于一般代理指令，但应加入强制使用vfs的规则 GEMINI.md.

示例：为Claude Code设置

创建或附加到 CLAUDE.md 在您的项目根目录中使用上述规则内容。Claude Code在每个会话开始时读取此文件。

示例：设置Windsurf

mkdir -p .windsurf/rules

然后创建 .windsurf/rules/vfs.md 根据上述规则内容。

为什么这很重要

如果没有规则文件，会发生以下情况：

You: "Where is the login handler?"

❌ Without rule:  Agent runs `grep -r "HandleLogin" .` → reads 200 lines → 3,500 tokens
✅ With rule:     Agent calls vfs search("HandleLogin") → reads 23 lines → 370 tokens

规则文件将vfs从“已安装但被忽略”转变为“每次搜索时主动保存令牌”

这 VERSION repo根目录下的文件包含当前的semver。

贡献

贡献使开源社区成为一个学习、激励和创造的好地方。你所做的任何贡献都是 非常感谢.

请看 贡献.md 有关如何报告错误、建议功能和提交pull请求的指南。

有兴趣分享你的项目吗？ 在此处添加您的用例.

被使用

在你的项目或公司中使用vfs？ 提交PR 在这里列出。

如何添加用例

1. 分叉此仓库并创建一个分支： usecase/
2. 编辑上表——添加一行：

- 标志：指向您徽标的URL（例如。 https://.../logo.png) - 名字：您的公司或项目名称 - 网站：链接到您的官方网站 - 用例：对如何使用的简明描述 vfs - 博客：（可选）链接到任何博客文章或案例研究

1. 打开一个标题为的pull请求： usecase: add

指导方针：

• 保持描述简洁（一行）。
• 鼓励将公司/项目名称链接到公共URL，但这是可选的。
• 你不需要透露专有细节——高级描述是可以的。
• 只接触这张桌子的公关总是受欢迎的；不需要问题。

许可证

麻省理工学院

明星历史