agent-fs

agent-fs CLI

agent-fs 是一个以 Agent 为先的文件系统，具备完整的版本管理、全文搜索（FTS5）和语义搜索功能。它提供可输出 JSON 的 CLI，非常适合 Agent 工作流。文件按组织中的云盘进行整理。

存储后端

agent-fs 将文件字节存储在可插拔的存储后端中。持久化数据——版本历史、评论和搜索数据——存储在 SQLite 中，并且在所有后端上的工作方式完全相同。

后端	设置	版本管理层级	signed-url
S3 / MinIO（默认）	agent-fs onboard -y（本地 MinIO，需要 Docker），或使用 --s3-* 标志连接任何兼容 S3 的存储（AWS、R2、Tigris 等）	完整——通过 S3 对象版本管理支持 revert 和历史 diff	真实的预签名 URL（公开、限时有效）
本地文件系统	agent-fs onboard --filesystem（无需 Docker 或 S3）	完整——通过磁盘上的内容寻址 Blob 支持 revert 和历史 diff	回退为需身份验证的应用内链接（需要登录；不会过期）

两个后端均为完整层级：所有操作——包括 revert 和历史 diff——都可用。未来的后端可能为基础层级（不支持对象版本管理）：在这些后端上，revert 和历史 diff 不可用，并会明确返回 UNSUPPORTED_OPERATION 错误（HTTP 422），而非原始存储错误；当前内容、列表、评论和搜索仍可正常使用。如果不确定某个云盘使用的是哪个后端，请先检查后端的功能，再依赖版本管理。

快速开始

# 1. Set up (local MinIO — requires Docker)
agent-fs onboard -y

#    ...or with no Docker/S3 at all — store bytes on the local filesystem:
agent-fs onboard --filesystem            # uses ~/.agent-fs/storage
agent-fs onboard --filesystem --storage-root /data/agent-fs   # custom dir

# 2. Optionally start the daemon (CLI auto-detects and works without it)
agent-fs daemon start

# 3. Start using it
echo "hello world" | agent-fs write docs/readme.txt -m "initial version"
agent-fs cat docs/readme.txt

对于自定义 S3（AWS、R2 等），请使用标志：agent-fs onboard --s3-endpoint <url> --s3-bucket <name> --s3-access-key <key> --s3-secret-key <key>。

本地文件系统后端（--filesystem，等同于 --storage local）无需 Docker 或 S3——文件字节存储在 --storage-root 下（默认为 ~/.agent-fs/storage），每个版本都按内容寻址，因此 revert 和历史 diff 的工作方式与 S3 上相同。

just-bash 适配器

当 just-bash 环境需要通过 agent-fs 读写文件，并将其用作 fs 实现时，请使用 @desplega.ai/agent-fs-just-bash。

import { Bash } from "just-bash";
import { AgentFsFileSystem } from "@desplega.ai/agent-fs-just-bash";

const fs = new AgentFsFileSystem({
  baseUrl: process.env.AGENT_FS_API_URL,
  apiKey: process.env.AGENT_FS_API_KEY,
  orgId: "org_...",
  driveId: "drive_...",
});

const bash = new Bash({ fs, cwd: "/" });

该适配器使用 /raw 进行字节安全的读写，使用 /ops 获取列表和元数据。空目录通过隐藏的 .agent-fs-dir 标记表示；不支持符号链接，遇到时会抛出 EPERM。

基本模式

1. 机器输出使用 JSON——解析 CLI 输出时传入 --json（download 未指定 -o 时除外，此时会将原始字节写入标准输出；daemon status 和 auth register 会输出人类可读的文本）。

2. 自动检测——CLI 会自动检测守护进程是否正在运行。如果正在运行，命令会通过 HTTP 执行；否则会直接使用嵌入模式。无需用户操作。

3. 默认组织/云盘解析——未指定 --org/--drive 标志时，CLI 会按以下顺序解析：标志本身、本地配置（org switch <id> / drive switch <id>，每台机器独立保存）、AGENT_FS_DEFAULT_ORG_ID / AGENT_FS_DEFAULT_DRIVE_ID 环境变量（部署级提示，例如 Agent swarm 工作容器获准写入的共享组织），然后是账户在 GET /me 中返回的默认组织/云盘（自动创建的个人组织，除非已更改）。如果写入位置不符合预期，请检查 agent-fs org current / agent-fs drive current（source 字段）——未指定任何标志时，写入总是会落在个人组织/云盘中，除非设置了优先级更高的选项。

4. 标准输入和文件上传——write 可通过标准输入或 --file 接收原始字节，也可通过 --content 接收文本；append 可通过标准输入或 --content 接收文本：

   # Preferred for multi-line text
   echo "content here" | agent-fs write path/to/file.txt
   
   # Inline for short content
   agent-fs write path/to/file.txt --content "short text"
   
   # Binary-safe upload
   agent-fs write assets/screenshot.png --file ./screenshot.png
   

5. 路径：使用正斜杠。开头的斜杠可省略。Agent FS 会返回并存储规范形式的路径，例如 /docs/notes/meeting.md。

6. 版本消息——可选，但建议填写以便审计：

   agent-fs write docs/spec.md --content "..." -m "added API section"
   

7. 乐观并发控制——在 write 中使用 --expected-version 以避免冲突：

   agent-fs write config.json --content '{}' --expected-version 3
   # Fails if file is not at version 3
   

命令速查

文件操作

命令	用法	描述
write	agent-fs write <path> [--content <text>] [--file <local-path>] [-m <msg>] [--expected-version <n>]	写入文本或二进制字节
cat	agent-fs cat <path> [--offset <n>] [--limit <n>] [--raw]	读取文本文件内容
edit	agent-fs edit <path> --old <text> --new <text> [-m <msg>]	在文件中查找并替换
append	agent-fs append <path> [--content <text>] [-m <msg>]	追加到文件（通过 stdin 或 --content）
tail	agent-fs tail <path> [--lines <n>]	读取最后 N 行（默认值：20）
ls	agent-fs ls [path]	列出目录内容（默认为 /）
stat	agent-fs stat <path>	显示文件元数据（大小、版本、时间戳、嵌入状态：pending、indexed、failed 或 skipped，以及当前字节的 etag：比较是否相等即可判断内容是否已更改）
reveal	agent-fs reveal <path>	一次调用即可获取在树中显示一个文件所需的全部信息：每个祖先目录的 ls 列表（从根目录开始，格式为 listings: [{ path, entries }]）以及文件的 stat。权限与 ls 相同；文件不存在时返回 NOT_FOUND。普通读取请优先使用 ls/stat。
tree	agent-fs tree [path] [--depth <n>]	递归列出目录
glob	agent-fs glob <pattern> [--path <prefix>]	按模式查找文件（*.md、**/*.md），搜索所有存储页面。区分大小写
find	agent-fs find <query> [--path <prefix>] [--limit <n>]	按近似名称查找文件。忽略大小写和重音符号，且单词顺序不限。如果没有文件包含输入的所有单词，可以跳过部分字母（zphr 可找到 Zephyr.pdf）。按匹配度从高到低排序：文件名匹配优先于文件夹匹配。默认上限为 50。返回 { matches, total }
rm	agent-fs rm <path>	删除文件
mv	agent-fs mv <from> <to> [-m <msg>]	移动或重命名文件
cp	agent-fs cp <from> <to>	复制文件
signed-url	agent-fs signed-url <path> [--expires-in <seconds>] [--inline]	生成下载 URL。在 S3/MinIO 上：生成预签名 URL（默认 24h，最长 7 天，kind: "presigned"）。在 local-FS 上：生成经过身份验证的应用内链接（kind: "app"，需要登录，不会过期）。默认情况下，URL 会强制下载；--inline 会让浏览器直接呈现文件（PDF、图像）。
share-create	agent-fs share-create <path> [--expires-in <seconds>] [--max-views <n>] [--one-off]	为文件或文件夹创建公开链接。文件会在 API 主机上生成 /share/<token> 页面：提供只读预览（Markdown、文本/代码、图像、PDF、音频、视频，以及在沙箱中呈现的 HTML）和“下载”按钮。文件夹会变成位于 /site/<token>/ 的 HTML 站点（kind: "site"，无查看次数限制）。默认 24h，最长 7 天；--one-off（即 --max-views 1）会使文件链接仅可使用一次。返回 { id, kind, url, sharePath, expiresAt, maxViews }。
share-revoke	agent-fs share-revoke [<id>] [--token <token-or-url>] [--path <path>]	立即撤销共享链接。必须且只能指定一个选择器：share-create 返回的 id、令牌/URL，或文件或文件夹路径（撤销指向该路径的所有链接）。仅创建者或驱动器管理员可执行。
download	agent-fs download <path> [-o <local-path>]	下载原始字节
watch	agent-fs watch [--json]	持续流式传输活动驱动器的更改，直到按下 Ctrl+C。Bearer 端点：GET /orgs/:orgId/drives/:driveId/events 会发出 ready、file.changed 和 comment.changed。
cat 是分页查看器，而不是原始文件读取器：在 TTY 中，如果不使用 --limit，默认显示前 200 行；但如果 stdout 被管道传输或重定向，则会返回整个文件（管道或重定向几乎总是表示“给我全部内容”）。每当 cat 返回的行数少于请求的行数时，都会向stderr输出 truncated: showing N of M lines (use --limit) 提示 — 永远不会输出到 stdout，因此不会破坏管道或重定向的输出。默认视图（非 --raw、TTY）还会在每行前加上行号以便阅读；这些前缀不属于存储的字节内容。要完整、逐字节准确地读取文件 — 在解析为 CSV/JSON 之前，或任何行号或部分读取会破坏数据的情况下都必须这样做 — 请使用 agent-fs cat <path> --raw，或者更推荐使用 agent-fs download <path> -o <file>。

版本控制

命令	用法	说明
log	agent-fs log <path> [--limit <n>]	显示版本历史
diff	agent-fs diff <path> --v1 <n> --v2 <n>	比较不同版本
revert	agent-fs revert <path> --version <n>	恢复到之前的版本

log 适用于所有后端（版本元数据存储在 SQLite 中）。revert 和历史 diff（比较两个已存储的版本）需要完整级别后端 — S3/MinIO 和本地文件系统均符合要求。对于没有对象版本控制功能的基础级后端，revert 会干净地失败并返回 UNSUPPORTED_OPERATION（HTTP 422），而 diff 会降级处理，不比较内容。

每个 diff 结果都包含 source：content（已比较两个版本）、summary（未比较；changes 是存储的编辑片段）或 none（未比较且无摘要；write 不存储摘要）。只有当 source: "content" 且 changes 为空时，才表示两个版本相同。 对于另外两种情况，CLI 会向 stderr 输出“未比较版本”的警告。如果 source 不是 content，要验证原地编辑，请使用 cat 读取当前文件并直接检查编辑后的文本。

Markdown 写入时的失效链接警告。 当 write 存储 .md/.mdx 文件时，会检查每个链接和图像目标是否存在于同一网盘中。相对目标会从文件所在文件夹解析，方式与 GitHub 和实时查看器相同：在 /reports/a.md 中，img/x.png 表示 /reports/img/x.png，而 /img/x.png 表示网盘根目录。外部 URL（https:、mailto:、data:）和 #anchor 链接会被跳过。缺失目标会通过 warnings: [{ link, resolvedPath, message }] 返回；仅当存在缺失目标时才会包含此字段；CLI 会将警告输出到 stderr。写入仍会成功。警告仅表示“写入时未找到”，因此请先上传图像，或者如果稍后会上传相关文件，则可忽略警告。

搜索与发现

命令	用法	说明
grep	agent-fs grep <pattern> <path>	在文件内容中进行正则表达式搜索
fts	agent-fs fts <pattern> [--path <prefix>]	在当前网盘中使用 FTS5 查询语法进行全文搜索
search	agent-fs search <query> [--limit <n>]	混合搜索（语义 + 关键词，适用于一般查询）
vec-search	agent-fs vec-search <query> [--limit <n>]	在当前网盘的不同文件中进行语义搜索
recent	agent-fs recent [path] [--since <duration>] [--limit <n>]	最近活动（例如，--since 24h）
reindex	agent-fs reindex [path]	为嵌入失败或缺失的文件重新编制索引。跳过 indexed 和 skipped 文件

各命令的适用场景：

• find：大致知道文件名（agent-fs find "zephyr deck"）
• grep — 知道确切的模式和路径（正则表达式）
• fts — 跨所有文件进行关键词搜索（快速，基于 FTS5）
• search — 结合关键词和含义的通用搜索（建议默认使用）
• vec-search — 仅需概念匹配时使用纯语义搜索 搜索使用当前组织和云盘。检查 org current 和 drive current，或传入明确的 --org 和 --drive 标志。 glob、ls 和 tree 会读取 S3 列表的所有分页。对象超过 1,000 个的云盘仍可搜索。 search 和 vec-search 会在当前云盘中选取语义候选项，并按不同文件计入上限。 可搜索 PDF 文本。对于 PDF 文本命中，search 和 vec-search 结果会包含 page。 使用 EmbeddingGemma 2 时，语义搜索还能找到 PNG、JPEG、WebP、GIF 图像，以及 PDF 前 3 页的图像。 语义匹配结果会包含 kind: "text" 或 kind: "image"。 图像匹配使用 [image] 片段。PDF 页面图像使用 [PDF page N] 片段，并包含 page。 搜索仍会对每个文件只返回一个结果。最佳语义分块决定 kind 和 page。 仅当余弦相似度达到 0.69 且 FTS 未命中文件时，混合搜索才会将图像的向量贡献加倍。 相似度较低时，仍只计一次向量贡献。FTS 命中仍会增加关键词贡献。 图像索引在后台运行，因此新图像可能需要一段时间才会显示。 使用 agent-fs signed-url <path> --inline 查看文件，或省略 --inline 以下载文件。 在本地文件系统后端上，URL 需要经过身份验证的云盘成员才能访问。 在服务器上设置 AGENT_FS_EMBEDDING_MAX_BYTES，以 UTF-8 字节数限制去除 base64 后的文本嵌入。 请使用正整数。未设置或值无效时不设上限。 超过上限的文本仍可进行全文搜索，但会丢失文本分块和向量，并报告为 skipped。 去除 base64 后超过 2,000,000 个字符的文本也会报告为 skipped，即使未设置字节上限。 上限针对 PDF 提取出的文本进行计算。PDF 文本会保留 base64，以维持页面偏移量。图像和 PDF 页面嵌入不受影响。 更改上限后请重启。启动时，守护进程会将已跳过的文件和大于新上限的已索引文件加入队列。 设置上限后，还会将 FTS 文本字节数超过上限的旧版 NULL 状态文件加入队列。 这些检查使用原始 FTS 字节数，因此可能会将包含 base64 的额外文件加入队列。

将要排除其文本、图像和 PDF 页面嵌入的云盘 ID 以逗号分隔，设置到 AGENT_FS_EMBEDDING_EXCLUDE_DRIVES。 解析器会去除 ID 首尾的空格，并忽略空条目。未设置或值为空时，不排除任何云盘。 被排除的云盘仍保留 FTS，但会丢失向量，文本状态报告为 skipped。其图像状态仍为 NULL。 更改后请重启。守护进程会将新排除的文本文件加入队列，并删除其图像分块和向量。 云盘移出排除列表后，守护进程会将其已跳过的文本加入队列，并重新允许处理其图像。

语义搜索结果需要嵌入。没有可用提供方时，vec-search 会返回提示，search 会标明仅关键词匹配的结果。 若要进行本地语义搜索，请设置 EMBEDDING_PROVIDER=local 和 EMBEDDING_MODEL=embeddinggemma-2，以选择 EmbeddingGemma 2。 模型设置为空时，如果 transformers 4.3.1 能在本地加载，新建索引会使用 EmbeddingGemma 2；否则会使用 nomic。 已有的 nomic 索引会继续使用 nomic。设置 EMBEDDING_MODEL=nomic-embed-text-v1.5 可明确选择 nomic。

若要使用 OpenRouter 文本嵌入，请在服务器上设置 EMBEDDING_PROVIDER=openrouter 和 EMBEDDING_API_KEY（或 OPENROUTER_API_KEY）。 EMBEDDING_MODEL 默认为 openai/text-embedding-3-small；其他模型必须支持 768 维。 更改模型或提供方后请重启。预热后，现有文件会在后台重新生成嵌入，API 用量将计入已配置的密钥。在此过程完成之前，搜索可能会混用新旧向量。 vec-search 分数表示余弦相似度。分数范围取决于模型。使用 nomic 时，良好匹配的分数约为 0.6。排序比绝对分数更重要。每个查询都会返回最接近的文件，因此请先检查相关性，再相信结果。混合 search 分数表示排名，范围为 0 到 1：1 表示该文件在所有可能匹配的列表中都排在第一位。三种搜索操作都会返回 tookMs，即服务器处理查询所用的时间。如果嵌入提供方返回了不可用的向量，search 和 vec-search 会失败，并返回 EMBEDDING_PROVIDER_ERROR（HTTP 502）。检查提供方配置，然后重试。

fts 接受原始 FTS5 语法。对于包含标点的词项，请在 shell 单引号内使用 FTS 双引号括起来：

agent-fs glob '**/*ai-tinkerers*'
agent-fs glob '**/*ai-tinkerers*' --path thoughts/research
agent-fs find 'ai tinkerers'
agent-fs find 'ai tinkerers' --path thoughts/research
agent-fs fts '"ai-tinkerers"'
agent-fs fts 'ai AND tinkerers'

在 FTS 引号括起来的词项中，嵌入的引号需加倍。反斜杠转义不会转义 FTS 引号。 Glob 模式区分大小写。全文搜索会匹配已索引的词元。两种模式都不会纠正拼写错误。 find 会忽略大小写和重音符号。只有在没有文件包含按原样输入的所有词语时，它才会匹配跳过字母的情况。它不会纠正字母顺序颠倒或错误。

SQL 查询（DuckDB）

命令	用法	说明
sql	agent-fs sql <query> [-t name=path[:format]]... [--max-rows <n>]	对存储的文档运行 DuckDB SQL

支持的格式：csv、tsv、parquet、xlsx、json、ndjson/jsonl（除 parquet/xlsx 外，每种格式也支持 .gz）、sqlite（.db/.sqlite/.sqlite3）和 .duckdb。在查询中直接通过带引号的驱动器路径引用文件格式文档，或使用 -t 将任意文档绑定到表名。SQLite/DuckDB 数据库需要使用 -t 绑定，其表会以 <name>.<table> 的形式公开。为绑定追加 :format，即可查询扩展名不标准的文档（例如 -t logs=/raw/data.txt:csv）。查询受到沙盒限制，无法访问主机文件系统或网络。结果最多返回 --max-rows 条（默认 1000，最大 10000）；JSON 输出中的 truncated: true 表示还有更多行。

评论

命令	用法	说明
comment add	agent-fs comment add <path> --body <text> [--mention <user-id-or-email>]... [--line-start <n>] [--line-end <n>] [--quote <text> [--quote-prefix <text>] [--quote-suffix <text>]]	向文件添加评论。--quote 会将评论锚定到确切文本，网页应用会在编辑后重新查找该文本；如果文本重复出现，前缀/后缀可用于选定正确的位置。重复使用 --mention 可通知云盘成员。
comment reply	agent-fs comment reply <comment-id> --body <text> [--mention <user-id-or-email>]...	回复评论，并可选择提及云盘成员
comment list	agent-fs comment list [path] [--prefix <path>]	列出评论及其内联回复。使用 --prefix 可列出目录下的所有评论。不要将位置参数路径与 --prefix 组合使用。
comment get	agent-fs comment get <id>	获取评论及其回复
comment update	agent-fs comment update <id> --body <text> [--mention <user-id-or-email>]... [--clear-mentions]	更新评论，并可选择替换或清除提及对象（仅作者可操作）
comment delete	agent-fs comment delete <id>	软删除评论（仅作者可操作）
comment resolve	agent-fs comment resolve <id>	解决评论
comment notifications	agent-fs comment notifications [--kind <comment|mention>]... [--unread] [--limit <n>]	列出当前用户的通知。默认类型为 comment。
comment read	agent-fs comment read [ids...] [--all [--kind <comment|mention>]...]	将选定的通知事件 ID，或当前活动云盘中所有类型的通知，标记为已读。--all 默认处理 comment。

收藏

收藏按用户区分：每位用户都可以为云盘中的文件和文件夹加星标，并且只能看到自己的星标。服务器从 API 密钥中获取用户；没有命令接受用户 ID。Viewer 角色即可使用。

命令	用法	描述
favorite-add	agent-fs favorite-add <path>	为文件或文件夹加星标。重复加星标不会产生任何影响。返回 { path, kind, createdAt, favorited }。
favorite-remove	agent-fs favorite-remove <path>	移除自己的星标。即使路径已不存在也可使用。返回 { path, removed }。
favorite-list	agent-fs favorite-list	列出当前云盘中的收藏，并按路径排序。文件夹的路径末尾会显示 /。

星标会随文件变化：mv 会将文件上的所有用户星标移至新路径，rm 会移除星标；文件夹消失后（其最后一个文件被删除或移出），该文件夹的星标也会移除。

设置与身份验证

命令	用法	描述
onboard	agent-fs onboard [--local] [--filesystem] [--storage <minio|local>] [--storage-root <dir>] [-y] [--embeddings <provider>]	设置 agent-fs（存储后端 + 数据库 + 用户）。--filesystem（或 --storage local）使用本地磁盘后端，无需 Docker/S3；--storage-root <dir> 用于设置其目录。
init	agent-fs init [--local] [-y]	onboard 的别名
auth register	agent-fs auth register <email>	注册新用户
auth whoami	agent-fs auth whoami	显示当前用户信息
auth reset-key	agent-fs auth reset-key	重置自己的 API 密钥。旧密钥会立即失效。

成员管理

命令	用法	说明
members	agent-fs members	列出当前云盘的活跃成员，包括用户 ID、电子邮件和显示名称。所有云盘成员均可使用。不显示角色。
member list	agent-fs member list	列出组织成员（使用 --drive <id> 列出云盘成员）
member invite	agent-fs member invite <email> --role <role> [--to <drive>[:<role>]]...	邀请他人加入组织。不带 --to：将其加入默认云盘，并设置 --role 指定的角色。带 --to：仅加入列出的云盘（ID 或名称），每个云盘可指定自己的角色（默认使用 --role）。如果该电子邮件对应的账户已存在，会立即添加；如果不存在，则会创建待处理邀请，并在命令输出中显示可发送给对方的接受链接。
member invites	agent-fs member invites	列出待处理邀请（ID、电子邮件、云盘、到期时间；仅限组织管理员）
member invite-revoke	agent-fs member invite-revoke <id>	撤销待处理邀请，使其链接失效（仅限组织管理员）
member add	agent-fs --drive <id-or-name> member add <email> --role <role>	授予现有组织成员访问云盘的权限，或更改其在该云盘中的角色
member update-role	agent-fs member update-role <email> --role <role>	更新组织角色（使用 --drive <id> 更新云盘角色）
member remove	agent-fs member remove <email>	将其从组织中移除（使用 --drive <id> 则仅从云盘中移除）
member reset-key	agent-fs member reset-key <email>	重置成员的 API 密钥（仅限组织管理员）。旧密钥会立即失效。
invite accept	agent-fs invite accept <link-or-token>	以已登录账户接受组织邀请（账户电子邮件必须与邀请匹配：完全一致，或是唯一一个仅字母大小写不同的账户）

--drive 标志是全局选项，必须放在子命令之前：agent-fs --drive <id> member list。

members 可供查看者使用，且不会返回角色。member 管理命令仍仅限管理员使用。组织级命令要求拥有组织 admin 角色。云盘级命令（--drive <id>）要求拥有云盘 admin 角色或所属组织的管理员权限，且该云盘必须属于当前组织。非管理员会收到权限错误。你不属于其成员的组织或云盘 ID 会返回“not found”。member add 仅适用于已在组织中的人员（否则返回“Not a member of this org”）；要邀请新人，请使用需要组织管理员权限的 member invite。

待处理邀请。 邀请没有账户的电子邮件地址时，会创建待处理邀请，而不是失败。命令会输出 Pending: <email> has no account yet. Send them: <link>；agent-fs 不会发送电子邮件，因此请自行转发链接。该链接只能使用一次，有效期为 7 天，且仅适用于使用受邀电子邮件的账户。再次邀请同一电子邮件地址会替换旧链接；如果对方注册后你再次邀请，则会直接将其添加，旧链接也会失效。受邀者使用该电子邮件注册（agent-fs auth register <email>），然后运行 agent-fs invite accept <link-or-token>，即可获得受邀的组织角色和云盘权限。期间已删除的云盘会被跳过。MCP：member-invite 返回 status: "pending" 以及 acceptUrl/token；member-invites 会列出邀请（或使用 revokeId 撤销邀请）；invite-accept 用于接受邀请。

云盘管理

命令	用法	说明
drive list	agent-fs drive list	列出当前组织中的云盘
drive create	agent-fs drive create <name>	创建新云盘（需要组织管理员权限）
drive current	agent-fs drive current	显示当前云盘上下文
drive invite	agent-fs drive invite <email> --role <role>	邀请用户加入组织，并仅授予其当前云盘上的 --role 权限

云盘成员身份需要明确授予：drive list 只显示你所属的云盘。创建云盘会自动授予你该云盘的管理员身份；其他用户则按云盘授予访问权限：使用 member invite --to、drive invite（当前云盘），或为现有组织成员使用 member add。直接使用 member invite 只会授予默认云盘的访问权限。

配置与守护进程

命令	用法	说明
config get	agent-fs config get <key>	获取配置值（点号表示法：s3.bucket）
config set	agent-fs config set <key> <value>	设置配置值。更改 embedding.provider 会移除旧模型和 API 密钥。
config list	agent-fs config list	显示所有配置
config validate	agent-fs config validate	检查 S3、数据库、身份验证和嵌入服务的运行状况
daemon start	agent-fs daemon start	启动后台守护进程
daemon stop	agent-fs daemon stop	停止守护进程
daemon status	agent-fs daemon status	检查守护进程是否正在运行

FUSE 挂载（仅限 Linux）

将所有组织云盘公开为 Linux FUSE 文件系统，让 Agent 可以使用普通 shell 命令（cat、grep、mv、rm）操作 agent-fs 内容。需要 /dev/fuse 和 SYS_ADMIN 能力；macOS 或基于 gVisor 的沙箱不支持。

支持两种拓扑：

• 本地模式（默认）：辅助程序通过 Unix 套接字与本地守护进程通信。守护进程必须正在运行，并且已配置 S3 后端。
• 远程模式（--remote）：辅助程序直接与远程 agent-fs HTTP API 通信。无需本地守护进程，适用于能够访问托管版 agent-fs、但无法运行完整守护进程栈的沙箱（sprite、E2B、Hetzner VM、GitHub Actions 运行器）。

在云盘上进行 FUSE 写入需要 editor 或更高角色；如果你在某个云盘上是 viewer，挂载将禁止文件写入（写入会因 EACCES 失败；请检查 <mount>/.agent-fs/errors.ndjson 中的 PERMISSION_DENIED 记录）。

命令	用法	说明
mount	agent-fs mount <path> [--allow-other] [--foreground]	通过本地守护进程将云盘挂载到 <path>（例如 /mnt/agent-fs/<drive>/）。
mount --remote	agent-fs mount <path> --remote [--api-url <url>] [--api-key <key>]	针对远程 agent-fs HTTP API 挂载。若未提供标志，则从 ~/.agent-fs/config.json 中读取 apiUrl/apiKey，或从 AGENT_FS_API_URL/AGENT_FS_API_KEY 环境变量中读取。优先使用环境变量，而不是 --api-key（后者会在 ps 中暴露密钥）。
umount	agent-fs umount <path>	卸载 FUSE 挂载点。
mount status	agent-fs mount status	显示挂载是否处于活动状态及其位置。

常见工作流

存储和检索文档

# Write a document (multi-line via stdin)
cat <<'EOF' | agent-fs write reports/q1-summary.md -m "Q1 summary draft"
# Q1 Summary
Revenue grew 15% quarter over quarter.
EOF

# Read it back
agent-fs cat reports/q1-summary.md

# Check metadata
agent-fs stat reports/q1-summary.md

跨文件搜索

# Regex search within a specific path
agent-fs grep "revenue|growth" reports/

# Full-text search across all files (FTS5 — fast keyword matching)
agent-fs fts "quarterly revenue"

# Hybrid search (combines keyword + semantic matching — recommended default)
agent-fs search "financial performance metrics" --limit 5

# Vector-only semantic search (conceptual matches only)
agent-fs vec-search "financial performance metrics" --limit 5

不使用 --json 时，PDF 搜索结果会在相关度分数后打印 [page N]。图片搜索结果会打印其标记片段：

$ agent-fs search "revenue chart" --limit 3
/reports/q1.pdf (score: 1.000) [page 2]  by [email protected]
  Quarterly <b>revenue</b> grew 12% over Q4...

/charts/revenue.png (score: 0.492)  by [email protected]
  [image]

/decks/board.pdf (score: 0.484) [page 1]  by [email protected]
  [PDF page 1]

使用 SQL 查询数据文件

# Query a CSV directly by path
agent-fs sql "SELECT category, sum(amount) AS total FROM '/finance/2026.csv' GROUP BY category" --json

# Join documents of different formats
agent-fs sql "SELECT s.name, t.tag FROM sales s JOIN tags t ON s.id = t.id" \
  -t sales=/data/sales.csv -t tags=/data/tags.parquet

# Query a stored SQLite database (tables exposed as app.<table>)
agent-fs sql "SELECT count(*) FROM app.users" -t app=/backups/app.db

# Pipe a query via stdin
echo "SELECT count(*) FROM '/data/events.ndjson'" | agent-fs sql

审查并撤销更改

# View version history
agent-fs log docs/spec.md --limit 10

# Compare two versions
agent-fs diff docs/spec.md --v1 2 --v2 5

# Revert to version 2
agent-fs revert docs/spec.md --version 2

评论与协作

# Add a comment to a file
agent-fs comment add docs/spec.md --body "Needs more detail on auth"

# Ask a human for a decision and send a targeted mention notification
agent-fs comment add docs/spec.md --body "Which option should we use?" --mention [email protected]

# Anchor a comment to exact text (survives edits above it; the MCP/API param is quote: { exact, prefix, suffix })
agent-fs comment add docs/spec.md --body "Which provider?" --quote "OAuth login" --quote-suffix " flow"

# Reply to a comment
agent-fs comment reply <comment-id> --body "Added in v3"

# List comments
agent-fs comment list docs/spec.md

# List unresolved comments below a directory
agent-fs comment list --prefix docs/

# Check unread notifications (the returned IDs are notification event IDs)
agent-fs comment notifications --unread --limit 20

# Check targeted mention notifications
agent-fs comment notifications --kind mention --unread

# Mark selected notifications as read
agent-fs comment read <notification-id> [<notification-id>...]

# Or acknowledge every notification in the active drive
agent-fs comment read --all

# Acknowledge every targeted mention notification in the active drive
agent-fs comment read --all --kind mention

# Resolve a comment
agent-fs comment resolve <comment-id>

设置新云盘并邀请用户

# Create a shared drive
agent-fs drive create "team-docs"

# Invite a teammate to that drive only
agent-fs --drive team-docs drive invite [email protected] --role editor

# Check current drive context
agent-fs drive current

管理成员

# List active-drive members without exposing roles
agent-fs members

# List org members
agent-fs member list

# List drive members
agent-fs --drive <driveId> member list

# Invite a user (default drive only)
agent-fs member invite [email protected] --role editor

# Invite a user to chosen drives, with a role per drive
agent-fs member invite [email protected] --role viewer --to context:editor --to ledger

# Invite someone without an account: prints an accept link to send them
agent-fs member invite [email protected] --role viewer --to context:editor
agent-fs member invites
agent-fs member invite-revoke <invite-id>

# As the invitee (after `agent-fs auth register [email protected]`)
agent-fs invite accept <accept-link-or-token>

# Give an existing org member access to another drive
agent-fs --drive ledger member add [email protected] --role viewer

# Change role
agent-fs member update-role [email protected] --role admin

# Remove from org (cascades to all drives)
agent-fs member remove [email protected]

# Remove from a specific drive only (keeps org membership)
agent-fs --drive <driveId> member remove [email protected]

查看近期活动

# What changed in the last hour?
agent-fs recent --since 1h

# Recent changes under a specific path
agent-fs recent docs/ --since 24h --limit 20

生成可分享的下载链接

# Default expiry (24 hours)
agent-fs signed-url docs/report.pdf

# Custom expiry (1 hour)
agent-fs signed-url docs/report.pdf --expires-in 3600

# Render in the browser instead of downloading (PDF viewer, image tab)
agent-fs signed-url docs/report.pdf --inline

# JSON output (useful for agents)
agent-fs signed-url docs/report.pdf --json
# → { "url": "https://...", "path": "/docs/report.pdf", "expiresIn": 86400, "expiresAt": "2026-03-20T..." }

在 S3/MinIO 后端（kind: "presigned"）上，URL 无需身份验证——任何拥有链接的人都可以在链接过期前下载文件。访问权限只在生成链接时进行 RBAC 检查（对该云盘具有查看者或更高权限）；此后，URL 就是一个持有即有权限的秘密。不要记录该 URL，也不要将它粘贴到任何你不会粘贴凭据的地方，并尽量使用可行的最短 --expires-in。签名 URL 会根据文件扩展名提供正确的 Content-Type 标头（例如，.pdf 对应 application/pdf，.png 对应 image/png）。默认情况下，签名 URL 还会带有 Content-Disposition: attachment，因此打开链接会以文件的真实名称保存文件。如果链接将嵌入页面或用于查看文件（例如，在 <iframe> 中打开 PDF），请传入 --inline（API："disposition": "inline"）；无论哪种情况，<img> 标签都会忽略 disposition。

对于不支持预签名 URL 的后端（本地文件系统后端），signed-url 不会失败——它会回退到经过身份验证的应用内链接（kind: "app"、expiresIn: 0），格式为 <appUrl>/file/~/<org>/<drive>/<path>。与预签名 URL 不同，此链接不是公开的持有即有权限的秘密：守护进程的 /raw 路由和 Web 查看器都要求登录，因此接收者必须是该云盘的已认证成员。请设置 AGENT_FS_APP_URL（或在配置中设置 appUrl），以便链接指向你的部署。

与没有账号的人分享文件

# 24h link, opens as many times as needed
agent-fs share-create docs/report.md

# Single-use link: the page opens once, then shows "link expired"
agent-fs share-create docs/report.pdf --one-off

# At most 5 views, valid for 1 hour
agent-fs share-create docs/report.pdf --max-views 5 --expires-in 3600

# Kill a link (id from share-create), or every link to a file
agent-fs share-revoke <id>
agent-fs share-revoke --path docs/report.pdf

share-create 返回的是 API 主机上的 URL（https://<server>/share/<token>），而不是 Web 应用上的 URL，因此任何人无需登录即可访问。与 signed-url 不同，收件人会看到渲染后的页面：Markdown 会转换为经过净化的 HTML（frontmatter 卡片、目录、提示框、任务列表、脚注、数学公式、mermaid 图表、高亮代码、浅色／深色／系统主题、查看源代码和复制功能）；文本和代码会以转义形式显示；图片、PDF、音频和视频会嵌入页面；HTML 页面会在沙箱框架中渲染（并提供“打开完整页面”链接）；其他所有类型都会显示无预览卡片。每个页面都会显示文件名、大小、过期时间和“下载”按钮。SVG 文件不会渲染，只能下载。

分享前需要了解以下事项：

• 此链接是持有者凭据。 任何持有链接的人都可以访问，直到链接过期、被撤销或达到查看次数上限。链接只显示一次，系统只存储其 SHA-256 值，因此无法恢复；如果之后可能需要撤销，请保留 id。
• 链接显示的是文件当前内容，而非快照。如果文件被编辑，链接会显示新版本；如果文件被删除或移动，链接会显示“文件不可用”。
• --one-off / --max-views 统计的是页面访问次数，文件内容也随访问一并提供。 限制访问次数的链接不会仅凭 URL 提供文件：消耗了一次访问次数的页面会获得一个私有的短时凭据（有效期最长为一小时，且不会超过链接的过期时间），页面中的嵌入内容和“下载”按钮会使用该凭据。访问次数用尽后，仅持有链接的人将无法获取文件；撤销或使链接过期会立即使所有凭据失效。不限次数的链接无需凭据。链接预览爬虫（Slack、WhatsApp 等）和 HEAD 请求不会消耗访问次数。
• 共享 HTML 文件只包含该文件本身。 文件会在具有不透明源的沙箱中运行，其旁边的相对资源（chart.png、app.js）会返回 404。页面需要这些资源时，请改为共享整个文件夹（见下文）。
• 路径必须位于云盘内。 如果路径包含 . 或 .. 段（任一斜杠方向均适用），share-create 会拒绝该路径，而不会对其进行解析。
• 查看者角色足以创建链接，创建者（或云盘管理员）可以撤销链接。每次计入的访问都会记录为 share_viewed 事件。
• 如果服务器位于不会转发 Host / X-Forwarded-* 的代理之后，请设置 AGENT_FS_PUBLIC_URL，确保返回的链接指向正确地址。

上传时的 MIME 类型： write、edit、append 和 revert 会根据文件扩展名自动检测并为 S3 对象设置正确的 Content-Type。内容类型也会存储在数据库中，并通过 stat 输出中的 contentType 字段显示。原始 stdin 和 --file 上传会完全保留字节内容。搜索会为有效且可索引的 UTF-8 文本建立索引，并提取 PDF 文本。

从文件夹发布 HTML 网站

# index.html is the site's front page (without one, a lone .html page opens, or else a list of the HTML pages)
agent-fs write report-site/index.html --content '<!doctype html><link rel="stylesheet" href="style.css"><img src="chart.png"><script src="app.js"></script>'
agent-fs share-create report-site --expires-in 86400
# Site: https://<server>/site/<token>/

# Take the site down
agent-fs share-revoke --path report-site

对文件夹执行 share-create 会返回 kind: "site"，以及 API 主机上的 /site/<token>/ URL。任何人都可以通过链接打开网站，无需登录。

• index.html 是入口文件。 /site/<token>/ 会提供文件夹中的 index.html，而 sub/ 会提供 sub/index.html。如果文件夹中没有 index.html，则会打开其中唯一的 .html 文件（例如 radar.html），否则会列出其中的 HTML 页面（绝不会列出其他文件或子文件夹）。如果文件夹中没有 HTML 页面，则返回 404。
• 相对路径有效。 <img src="chart.png">、<link href="style.css">、<script src="app.js">、模块脚本、fetch("data.json") 和 CSS url() 都会在文件夹内解析。外部 CDN 和字体也能加载。
• 页面在具有不透明来源的沙盒中运行。 脚本、表单、弹出窗口和警报均可正常使用，但没有 localStorage、sessionStorage 或 Cookie。
• 没有查看次数限制。 加载一个页面会获取多个文件，因此文件夹不支持 --max-views 和 --one-off，网站访问也不会记录 share_viewed 事件。请改用 --expires-in（最长 7 天）和 share-revoke --path <folder>。
• 链接有效期间，页面可以读取文件夹下的所有文件。 请勿将机密内容与要发布的 HTML 放在一起，也不要发布包含非你编写的 HTML 的文件夹。实时 UI 以相同方式呈现 .html 文件，并为该文件所在的文件夹提供有效期为 15 分钟的网站链接。
• 每个文件最多可提供 25 MB。更大的文件会返回 413。

响应中的应用 URL

设置 AGENT_FS_APP_URL 后（例如 https://live.agent-fs.dev），与文件相关的操作会自动包含 appUrl 字段，指向实时 Web 应用中的文件：

AGENT_FS_APP_URL=https://live.agent-fs.dev agent-fs stat docs/report.pdf --json
# → { ..., "appUrl": "https://live.agent-fs.dev/file/~/org-id/drive-id/docs/report.pdf" }

这适用于任何返回 path 或 to 字段的操作（write、stat、edit、append、rm、cp、mv、signed-url 等）。

验证设置

agent-fs config validate

从沙盒挂载远程驱动器

当 Agent 在 Linux 沙盒中运行（sprite、E2B、Hetzner VM、GitHub Actions runner 等），且能够连接托管的 agent-fs HTTP API，但无法在本地运行完整的守护进程和 S3 堆栈时，请使用 --remote。

# Linux prereqs (run once per sandbox)
sudo apt-get install -y fuse3
sudo chmod 666 /dev/fuse
sudo ln -sf /proc/mounts /etc/mtab
echo user_allow_other | sudo tee -a /etc/fuse.conf

# Auth — either env vars or ~/.agent-fs/config.json
export AGENT_FS_API_URL=https://agent-fs.example.com
export AGENT_FS_API_KEY=<key>

# Mount — no local daemon needed
mkdir -p ~/mnt
agent-fs mount ~/mnt --remote

# Use plain shell verbs against remote content
ls ~/mnt
cat ~/mnt/current/docs/spec.md
echo "edit from sandbox $(date)" > ~/mnt/current/notes.txt

# Unmount
fusermount3 -u ~/mnt

请参阅 docs/mounting/ 中按环境分类的指南（sprite、E2B、Hetzner）。

上传限制配置

原始 HTTP 上传的默认限制为 50 MiB。在服务器上设置 AGENT_FS_MAX_UPLOAD_BYTES （例如，设置为 104857600 即为 100 MiB），然后重启守护进程以更改限制。无效 值会回退到 50 MiB。Web UI 会从 /health 获取限制。 JSON/MCP write 的限制仍为 10 MiB。FUSE 仍保留 64 MiB 的编码 IPC 帧上限， 其中包含协议开销；较大的文件请使用 HTTP 原始上传。

个人资料

agent-fs profile get 会读取你的个人资料。agent-fs profile set --name "Taras" 会设置你的显示名称。名称会去除首尾空格，长度为 1–100 个字符，所有 能够读取你评论的人都能看到。只有你经过身份验证的个人资料可以编辑。 HTTP：GET /auth/profile，以及使用 { "displayName": "Taras" } 的 PATCH /auth/profile （或使用 null 清除）。MCP：profile-get、使用 displayName 的 profile-set。 Web 账户菜单中有 编辑个人资料。设置显示名称后，评论响应会包含 authorDisplayName，通知响应会包含 actorDisplayName。每位云盘成员都可以通过 agent-fs members 列出成员邮箱和显示名称。成员角色仍仅限管理员查看。