vfs (Virtual Function Signatures)

AST 级代码签名提取工具与 MCP Server，为 AI 编码代理削减约 98.6% token 消耗，支持 17 种语言。

核心定位#

vfs 是一个本地优先的 CLI 工具与 MCP Server，通过 AST 级解析从源代码中提取导出函数、类、接口和类型的签名，去除函数体、import、注释等噪声，为 AI 编码代理提供极度精简的代码结构摘要。自基准测试显示 token 节省率达 98.6%（26,079 → 373），相比 grep 节省 89.5%（3,537 → 373）。

签名提取与降噪#

基于 go/ast（Go 语言）和 tree-sitter（其余语言）进行 AST 级解析，仅输出导出符号签名
彻底去除函数体、import 语句、注释等噪声
对 Dockerfile / Protobuf / SQL / YAML 采用基于行的简单解析器
不包含函数实现逻辑；不支持非导出（私有）符号的提取（除非语言本身无 export 语义）

多语言覆盖#

支持 17 种语言：Go、JavaScript、TypeScript、Python、Rust、Java、C#、Dart、Kotlin、Swift、Ruby、Solidity、HCL/Terraform、Dockerfile、Protobuf、SQL、YAML。单次命令可跨前端与后端语言检索。

MCP Server 集成#

支持 stdio 和 HTTP 两种传输方式
暴露三个 MCP 工具：search、extract、list_languages
可被 Cursor、Claude Code、Claude Desktop、Windsurf、Cline、Continue、Aider 等 MCP 兼容客户端直接调用

stdio 模式配置：

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

HTTP 模式配置（适用于 Docker / 远程场景）：

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

项目要求在目标仓库中创建规则文件（如 .cursor/rules/vfs-agent-search.mdc），指示 AI 代理优先使用 vfs 而非 grep。

安全与隐私#

本地优先，完全离线运行
零网络访问、零遥测、零代码存储
源码仅在内存中解析后立即丢弃
持久化仅写入 ~/.vfs/history.jsonl，记录扫描统计

可观测性#

内建 Web Dashboard（默认端口 3000），展示使用统计与 token 节省趋势
vfs stats 命令提供 lifetime 累计统计（调用次数、节省 token 量、平均缩减率）

CLI 命令#

命令	说明
`vfs [paths...] -f <pattern>`	扫描路径并按名称过滤签名（不区分大小写）
`vfs bench`	对比 token 用量（全文件 vs grep vs vfs）
`vfs stats`	查看 lifetime token 节省统计
`vfs mcp`	启动 MCP Server（stdio 或 HTTP）
`vfs serve`	前台运行 MCP Server + Dashboard
`vfs up / down / status`	后台管理 MCP Server
`vfs dashboard`	单独运行 Dashboard UI

安装部署#

预编译二进制（Linux）：

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

从源码构建：

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

Docker：

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

依赖要求：Go 1.24+、C 编译器（tree-sitter 编译需要）、Docker（可选）。macOS 和 Windows 需从源码构建或使用 Docker。

架构要点#

入口层：cmd/vfs/ — CLI 入口点
核心引擎：internal/ — 签名提取引擎，包含各语言 parser 实现
解析策略分层：Go 用 go/ast；其余主流语言用 tree-sitter；Dockerfile/Protobuf/SQL/YAML 用行解析器
基准测试模块：pkg/bench/
容器化：根目录 Dockerfile + entrypoint.sh，通过 VFS_PORT 和 VFS_DASHBOARD_PORT 环境变量自定义端口

适用场景#

AI 代理的代码发现与定位
大型代码库结构导航
多语言单体仓库的跨语言签名检索
CI/脚本中的文件路径与行号提取

待确认信息#

首次发布时间：仓库有 VERSION 文件和 41 次 commits，但 README 未标注首次发布日期
作者背景：仅有 GitHub 用户名 TrNgTien，未发现个人主页或组织信息
tree-sitter 具体版本未列出
独立官网：仓库中未发现独立网站链接