# @desplega\.ai/agent-fs 中文文档 规范地址：https://npmcn.com/package/%40desplega.ai/agent-fs/ 版本：0\.18\.25 npm 元数据更新时间：2026-11-12T00:31:06.543Z 中文译文更新时间：2026-11-12T01:43:45.681Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40desplega.ai/agent-fs 原文对照：https://npmcn.com/package/%40desplega.ai/agent-fs/?lang=original 项目主页：https://github.com/desplega-ai/agent-fs#readme 源码仓库：https://github.com/desplega-ai/agent-fs ## 关键信息（来自 npm 元数据） - 包体积（解压后）：666 kB，4 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：15 个 - 首次发布：2026-03-16T19:02:09.857Z - 最新版本发布：2026-11-12T00:31:06.176Z - 近 30 天下载量：9817（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：83（近 12 个月 83 个） ## 中文简介 S3 支持的代理首个文件系统 ## 安装 ```sh npm install @desplega.ai/agent-fs ``` 也可以使用：`pnpm add @desplega.ai/agent-fs`、`yarn add @desplega.ai/agent-fs`、`bun add @desplega.ai/agent-fs` ## README [![GitHub Stars](https://img.shields.io/github/stars/desplega-ai/agent-fs?style=flat-square&color=yellow)](https://github.com/desplega-ai/agent-fs/stargazers) [![MIT License](https://img.shields.io/github/license/desplega-ai/agent-fs?style=flat-square)](https://github.com/desplega-ai/agent-fs/blob/main/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](https://github.com/desplega-ai/agent-fs/pulls) [![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/KZgfyyDVZa) **一个持续,可搜索的AI代理文件系统.** 由 [破伤风](https://desplega.sh/) ——由建设者,为建设者. * * * Agent FS给予AI代理一个结构化的文件系统,内置语义搜索,版本化,以及身份管理. 它作为具有集成MCP支持的CLI和HTTP服务器运行——因此任何AI编码助理都可以将其作为长期内存和文件存储. 用于为共享文件系统提供动力的代理- fs 构建于 [间谍群](https://github.com/desplega-ai/agent-swarm) ——多代理协调框架. 虽然它的设计是供swarm代理共享文件,搜索内容,以及合作,但它作为任何AI代理的独立文件系统发挥作用. ## 关键特性 - **语义搜索**: 使用向量嵌入(OpenAI,Google GenAI,OpenRouter,Cheaper推论,或本地)索引和搜索文件. 本地运行于 lama.cpp 上或 EmbeddingGemma 2 在变压器.js上. - **SQL 查询** ——在所储存的文件(CSV,TSV,Parquet,Excel,JSON,NDJSON,SQLite,DuckDB)上运行沙箱DuckDB SQL——参见 [文件/平方米](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/sql.md) - **结构化存储** ——SQLite后置文件操作并带有元数据和版本 - **S3 兼容同步** —— 同步代理工作空间到任何 S3 兼容对象存储 - **身份管理** ——长期性剂身份文件随时间演变 - **MCP一体化** ——作为Claude Code, Codex 和其他助手的 MCP 工具的 Expose 文件系统操作 - **HTTP API 密码** ——由Hono为程序访问提供动力的RESTful服务器 - **国 际** 单二进制( )`agent-fs`供本地使用和脚本 ## 快速启动 ### 安装 要求数 [阿宝](https://bun.sh/) >= 1.4.0. ```bash bun add -g @desplega.ai/agent-fs ``` 或者从源头构建: ```bash git clone https://github.com/desplega-ai/agent-fs.git cd agent-fs bun install bun run build ``` ### 使用量 ```bash # 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 文件系统, 这样代理可以使用平面外壳动词( Name`cat`, (中文(简体) ), `grep`, (中文(简体) ), `mv`, (中文(简体) ), `rm`)针对代理-fs内容. ```bash # 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 指向您的本地二进制 : ```bash 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 套接字 : ```bash 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`数字 : ```bash # 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 bash packages/fuse-helper/docker/run-mount-test.sh ``` **环境指南** 见 [`docs/mounting/`](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/mounting/README.md) 总体概况加分步骤指南 [丝绸](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/mounting/sprite.md), (中文(简体) ), [E2B 软件](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/mounting/e2b.md),以及 [赫兹纳云](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/mounting/hetzner.md). 现有联邦经济调查参考文献 -- -- [`fuse-mount.md`](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/fuse-mount.md), (中文(简体) ), [`fuse-compat.md`](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/fuse-compat.md), (中文(简体) ), [`fuse-troubleshooting.md`](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/fuse-troubleshooting.md) ——封装语义,沙盒相容性,以及完整的出错目录. ## 文档 - [挂载指南](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/mounting/README.md) 概况+每本指南(Sprite、E2B、Hetzner) - [MCP 设置指南](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/mcp-setup.md) – 连接代理- fs 到 Claude 代码, cursor, 或任何 MCP 客户端 - [部署指南](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/deployment.md) ——地方,远程S3,团队,多代理部署 - [API 参考](https://npmcn.com/package/%40desplega.ai/agent-fs/docs/api-reference.md) —— HTTP API 和 OpenAPI spec ## 发展 ```bash bun install # Install dependencies bun run typecheck # Type checking bun run test # Run tests bun run build # Bundle CLI for npm ``` 见 [捐款额](https://npmcn.com/package/%40desplega.ai/agent-fs/CONTRIBUTING.md) 为完整的发展指南. ## 释放 发布是自动的——版本更改登陆 `main` 标记和出版. ```bash ./scripts/release.sh 0.13.0 ``` 见 [相关内容](https://npmcn.com/package/%40desplega.ai/agent-fs/RELEASING.md) 用于整个过程、版本同步规则和回收步骤. ## 部署到Fly.io 部署一个持续的代理实例 [飞.io](https://fly.io/) 带有底格里斯S3存储器 : ```bash git clone https://github.com/desplega-ai/agent-fs && cd agent-fs bun run scripts/fly-deploy.ts ``` 见 [解雇.md](https://npmcn.com/package/%40desplega.ai/agent-fs/DEPLOYMENT.md) 用于 Docker, BYOK 存储和手动设置选项. ## 现场查看器 **[现场直播. agent -fs.dev](https://live.agent-fs.dev/)** ——用于检查任何代理-fs部署的无国籍浏览器UI(仅本地存储). 指向您的服务器 URL 浏览文件和搜索内容 – 没有存储在服务器侧. 搜索覆盖所选驱动器 。 文件匹配所有目录的文件名模式 . 全文将输入作为文字术语,所以 `ai-tinkerers` 在用户界面中不需要引用查询语言. 混合了关键词和意义. 语义需要嵌入提供者. UI 区分请求错误, 提供者提示, 以及没有匹配的成功搜索 . 结果外的开放文件带有单独的标签. CLI和MCP `fts` 操作保留了原始的FTS5语法. 使用 `agent-fs fts '"ai-tinkerers"'` 是一个含点的术语. ## 捐款 我们欢迎捐款! 无论是错误报告,特性请求,docs改进,还是代码——都是受欢迎的. 1. 叉出还原 2. 创建分支( E)`git checkout -b my-feature`(中文(简体) ) 3. 做你的改变 4. 打开 PR 加入我们 [解析器](https://discord.gg/KZgfyyDVZa) 如果你有问题或想讨论想法. ## 许可证 [麻省理工学院](https://npmcn.com/package/%40desplega.ai/agent-fs/LICENSE) - 2025-2026年),字相会 [(原始内容存档于2018-09-21). desplega.ai](https://desplega.ai/) ## 常见问题 ### @desplega\.ai/agent-fs 是什么？ S3 支持的代理首个文件系统 ### 如何安装 @desplega\.ai/agent-fs？ 在项目目录运行 npm install @desplega\.ai/agent-fs，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agent-fs，可以用 npx agent-fs 直接运行。 ### @desplega\.ai/agent-fs 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/desplega\.ai\_\_agent-fs 是否存在。 ### @desplega\.ai/agent-fs 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @desplega\.ai/agent-fs 可以商用吗？ @desplega\.ai/agent-fs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @desplega\.ai/agent-fs 的下载量有多少？ 根据 npm 官方下载统计，@desplega\.ai/agent-fs 在 2026/10/12 – 2026/11/10 这 30 天内被下载 9,817 次，日均约 327 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @desplega\.ai/agent-fs 还在维护吗？ 最新版本 0\.18\.25 发布于 2026/11/12（今天）；至今共发布 83 个版本，其中过去 12 个月发布了 83 个；首次发布于 2026/03/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。