一个持续,可搜索的AI代理文件系统.
由 破伤风 ——由建设者,为建设者.
Agent FS给予AI代理一个结构化的文件系统,内置语义搜索,版本化,以及身份管理. 它作为具有集成MCP支持的CLI和HTTP服务器运行——因此任何AI编码助理都可以将其作为长期内存和文件存储.
用于为共享文件系统提供动力的代理- fs 构建于 间谍群 ——多代理协调框架. 虽然它的设计是供swarm代理共享文件,搜索内容,以及合作,但它作为任何AI代理的独立文件系统发挥作用.
关键特性
- 语义搜索: 使用向量嵌入(OpenAI,Google GenAI,OpenRouter,Cheaper推论,或本地)索引和搜索文件. 本地运行于 lama.cpp 上或 EmbeddingGemma 2 在变压器.js上.
- SQL 查询 ——在所储存的文件(CSV,TSV,Parquet,Excel,JSON,NDJSON,SQLite,DuckDB)上运行沙箱DuckDB SQL——参见 文件/平方米
- 结构化存储 ——SQLite后置文件操作并带有元数据和版本
- S3 兼容同步 —— 同步代理工作空间到任何 S3 兼容对象存储
- 身份管理 ——长期性剂身份文件随时间演变
- MCP一体化 ——作为Claude Code, Codex 和其他助手的 MCP 工具的 Expose 文件系统操作
- HTTP API 密码 ——由Hono为程序访问提供动力的RESTful服务器
- 国 际 单二进制( )
agent-fs供本地使用和脚本
快速启动
安装
要求数 阿宝 >= 1.4.0.
bun add -g @desplega.ai/agent-fs
或者从源头构建:
git clone https://github.com/desplega-ai/agent-fs.git
cd agent-fs
bun install
bun run build
使用量
# Show available commands
agent-fs --help
建筑
Agent FS是Bun monorepo的一款有四个包:
| 软件包 | 说明 |
|---|---|
@desplega.ai/agent-fs-core | 核心库-存储引擎,语义搜索,身份,S3同步 |
@desplega.ai/agent-fs | CLI 二进制( E)agent-fs(中文(简体) ) |
@desplega.ai/agent-fs-mcp | MCP stdio 代理 + HTTP 服务器的工具注册 |
@desplega.ai/agent-fs-server | HTTP 服务器 — 由 Hono 提供动力的 RESTful API |
FUSE 挂载 (Linux)
代理- fs 可以将您的驱动器曝光为 Linux FUSE 文件系统, 这样代理可以使用平面外壳动词( Namecat, (中文(简体) ), grep, (中文(简体) ), mv, (中文(简体) ), rm)针对代理-fs内容.
# Linux only — the FUSE helper sub-package auto-installs via optionalDependencies.
# Use Bun's installer; stock Ubuntu/Debian Node (18.x) chokes on a dep's
# postinstall and aborts the global install.
bun install -g @desplega.ai/agent-fs
agent-fs daemon start
agent-fs mount /mnt/agent-fs
所需资源
- Linux x86 64 或 arch64. macOS 和 Windows 不支持 (FUSE 在这里是一个 Linux 内核特性).
/dev/fuse必须无障碍。 在多克语中,运行--cap-add SYS_ADMIN --device /dev/fuse。 。 。 .- 使用gVisor(GKE Sandbox, Cloud Run gen1),GitHub Codespaces,Modal sandbox,或Fly.io Machines不能上架FUSE的沙盒-倒回CLI/MCP路径.
局部- Dev出逃舱口AGENT_FS_FUSE_BIN(中文(简体) )
如果您正在从源头构建帮助器( 例如 macOS dev 主机或自定义的 Linux 构建), 将 CLI 指向您的本地二进制 :
cd packages/fuse-helper && cargo build --release
export AGENT_FS_FUSE_BIN="$PWD/target/release/agent-fs-fuse"
agent-fs mount /tmp/m
AGENT_FS_FUSE_BIN 优先于自动解析子包二进制.
远程挂载( R)--remote(中文(简体) )
当您的代理员运行在一个无法托管本地守护进程( Sprite, E2B, ephemeral CI reserves) 的沙盒内时, 将挂载指向远程代理员- fs HTTP API 而不是本地的 Unix 套接字 :
agent-fs mount /mnt/agent-fs --remote \
--api-url https://my-agent-fs.example.com \
--api-key "$AGENT_FS_API_KEY"
帮助者直接与远程API交谈——没有本地守护进程,沙盒里没有S3的证书. 这种地形学的端到端覆盖 scripts/e2e-remote-mount.ts数字 :
# Spins up MinIO, a host-side daemon, and a Docker container with fuse3.
# Mounts via --remote against the daemon's HTTP API and exercises ~8 ops.
# Requires Docker Desktop / OrbStack on Mac.
bun run scripts/e2e-remote-mount.ts
macOS 测试带
macOS 可以建立帮助器但不能挂载它. 使用 Docker 吊带测试 Mac 主机的挂载行为 :
bash packages/fuse-helper/docker/run-mount-test.sh
环境指南
见 docs/mounting/ 总体概况加分步骤指南 丝绸, (中文(简体) ), E2B 软件,以及 赫兹纳云. 现有联邦经济调查参考文献 -- -- fuse-mount.md, (中文(简体) ), fuse-compat.md, (中文(简体) ), fuse-troubleshooting.md ——封装语义,沙盒相容性,以及完整的出错目录.
文档
- 挂载指南 概况+每本指南(Sprite、E2B、Hetzner)
- MCP 设置指南 – 连接代理- fs 到 Claude 代码, cursor, 或任何 MCP 客户端
- 部署指南 ——地方,远程S3,团队,多代理部署
- API 参考 —— HTTP API 和 OpenAPI spec
发展
bun install # Install dependencies
bun run typecheck # Type checking
bun run test # Run tests
bun run build # Bundle CLI for npm
见 捐款额 为完整的发展指南.
释放
发布是自动的——版本更改登陆 main 标记和出版.
./scripts/release.sh 0.13.0
见 相关内容 用于整个过程、版本同步规则和回收步骤.
部署到Fly.io
部署一个持续的代理实例 飞.io 带有底格里斯S3存储器 :
git clone https://github.com/desplega-ai/agent-fs && cd agent-fs
bun run scripts/fly-deploy.ts
见 解雇.md 用于 Docker, BYOK 存储和手动设置选项.
现场查看器
现场直播. agent -fs.dev ——用于检查任何代理-fs部署的无国籍浏览器UI(仅本地存储). 指向您的服务器 URL 浏览文件和搜索内容 – 没有存储在服务器侧.
搜索覆盖所选驱动器 。 文件匹配所有目录的文件名模式 .
全文将输入作为文字术语,所以 ai-tinkerers 在用户界面中不需要引用查询语言.
混合了关键词和意义. 语义需要嵌入提供者.
UI 区分请求错误, 提供者提示, 以及没有匹配的成功搜索 .
结果外的开放文件带有单独的标签.
CLI和MCP fts 操作保留了原始的FTS5语法. 使用 agent-fs fts '"ai-tinkerers"' 是一个含点的术语.
捐款
我们欢迎捐款! 无论是错误报告,特性请求,docs改进,还是代码——都是受欢迎的.
- 叉出还原
- 创建分支( E)
git checkout -b my-feature(中文(简体) ) - 做你的改变
- 打开 PR
加入我们 解析器 如果你有问题或想讨论想法.
许可证
麻省理工学院 - 2025-2026年),字相会 (原始内容存档于2018-09-21). desplega.ai