arc afs 是 AFS 檔案系統操作的命令組。每個子命令操作的都是一個 AFS 路徑，比如 /src、/data 這類掛載出來的位置，不是你機器上的原始檔案系統路徑。
對照版本：arc 2.0.0-beta.50（commit a99fb2c37，main，2026-09-11）。複製 dump 前先跑 arc --version；釘住命令面的是 commit。
arc afs <subcommand> [options]跑 arc afs --help 看完整子命令列表。每個子命令都接受 概覽 裡說的全域 --json、--view <default|llm|human|json>、--instance / -i、--home <dir> 選項。--yaml 已刪除（從未真正實現）；改用 --json 或 --view json。
未識別的選項現在會被拒絕（Unknown argument: <name>，退出碼 5），不會靜默忽略——比如 arc afs ls --bogus-flag foo 會直接失敗，而不是丟掉 --bogus-flag 繼續跑。
命令作用在哪個例項上
arc afs 需要一個活著的例項才能跑。不帶任何選項時,它連的是預設後臺例項(用一條裸 arc service start 起的);如果沒有例項在跑,每個 arc afs 子命令都會以非零退出,不會靜默退回一個臨時的 ad-hoc AFS:
$ arc afs ls /
ERROR: No AFS daemon is running for instance "default".
Start it with: arc service start
Or use --standalone for ad-hoc mode (no runtime state)--instance <name>/-i：全域選項。連到一個具名例項,而不是預設例項(用arc service list看你有哪些例項在跑)。省略即default--home <dir>：全域選項。例項根。用於arc service start（建立）、--standalone（ad-hoc）、arc did init。要指定作用在哪個例項，用--instance。兩個都傳且指向不同例項時命令失敗--standalone：強制 ad-hoc 模式——直接從當前目錄的.afs-config/config.toml載入 AFS,不連線任何正在執行的 daemon。沒有執行時狀態(你在別處加的掛載、活躍訂閱等都看不到);會在 stderr 列印一行[standalone] not attached to any instance提醒你
arc service start --instance docs-demo --home ~/docs-demo # start a named instance once
arc afs ls / --instance docs-demo # every later afs call names it explicitly讀取與列目錄
arc afs ls
列出目錄內容。
用法
arc afs ls [path] [options][path](可選，預設/)：要列出的 AFS 路徑--depth <n>：最大列出深度（預設1）-l：詳細列表格式，顯示型別和大小-R：遞迴列出--limit <n>：返回條目數上限--max-children <n>：每個目錄最多顯示的子項數--pattern <glob>：用 glob 模式過濾條目
別名是 arc afs list。
-R 和顯式給出的 --depth 互斥——-R 總是按深度 10 列出，同時給 --depth 會產生歧義，不知道該聽誰的：
$ arc afs ls /demo -R --depth 2
ERROR: ls: --depth conflicts with -R (recursive always lists at depth 10) — choose one: drop --depth to use -R's depth of 10, or drop -R and pass --depth explicitly路徑不存在時退出碼是 1（不是 0 加空列表，也不是 5）：
$ arc afs ls /demo/does-not-exist
ERROR: No data found for path: /demo/does-not-exist示例：遞迴、詳細列表
arc afs ls /demo -l -R└── 📁 demo
├── 📄 notes.txt (fs:file) 15B
└── 📁 reports (fs:directory)
└── 📄 q1.txt (fs:file) 15Barc afs read
讀檔案內容。
用法
arc afs read [path] [options][path]（位置引數，或用--path <path>，兩者給一個即可，必須有一個）：要讀的路徑--start-line <n>：起始行，1 起始，含邊界--end-line <n>：結束行，1 起始，含邊界；-1表示到檔案末尾
別名是 arc afs cat。
示例
$ arc afs read /demo/notes.txt
Hello from AFS路徑不存在時退出碼是 1：
$ arc afs read /demo/does-not-exist.txt
ERROR: No data found for path: /demo/does-not-exist.txtarc afs stat
獲取檔案或目錄資訊。
用法
arc afs stat [path][path]（位置引數，或用--path <path>，兩者給一個即可，必須有一個）：要檢視的路徑
示例
$ arc afs stat /demo/notes.txt
PATH=/demo/notes.txt
KIND=fs:file
SIZE=15
MODIFIED=2026-08-01T04:00:51.508Z路徑不存在時退出碼是 1，報錯文本和退出碼和 arc afs read 一樣：
$ arc afs stat /demo/does-not-exist.txt
ERROR: No data found for path: /demo/does-not-exist.txtarc afs search
在一個 AFS 路徑內搜尋內容。
用法
arc afs search [path] [query][path]（位置引數，或用--path <path>，兩者給一個即可，必須有一個）：搜尋的路徑[query]（位置引數，或用--query <text>，兩者給一個即可，必須有一個）：搜尋關鍵詞
別名是 arc afs grep。不再別名 find——find 已刪除（它搜的是內容，不是名字；要按名字過濾條目，改用 arc afs ls --pattern）。
示例
$ arc afs search /demo revenue
/demo/reports/q1.txtarc afs explain
解釋 AFS 概念或某個路徑。不帶引數時列印總覽（mount / path / uri 這幾個概念）；帶上一個 topic 或一個真實的 AFS 路徑時，就針對那個具體物件解釋。
用法
arc afs explain [topic][topic]：概念名（mount、path、uri）或一個 AFS 路徑，比如/src。也可以不用位置引數，改用--topic <value>傳
示例
$ arc afs explain
AFS Overview
============
AFS (Agentic File System) is a virtual filesystem that unifies different data sources into a single namespace.
Core Concepts:
- mount: Mount a data source to a virtual path
- path: Virtual path, e.g., /src, /data
- uri: Data source address, e.g., fs://, git://, sqlite://
Data Flow:
User Path -> AFS -> /{mount} -> Provider -> Actual Data
Examples:
$ arc afs mount add /src fs:///path/to/source
$ arc afs ls /src
$ arc afs read /src/file.txtarc afs subscribe
訂閱某個路徑下的 AFS 事件;按 Ctrl-C 停止前,每行列印一條 JSON 事件。適合盯著一個掛載點看別的處理程序(構建工具、另一個 arc afs write、一個正在跑的 blocklet)改了什麼。
用法
arc afs subscribe [path] [options][path](可選,預設/),比如/demo或/dev/code-agents。也可以不用位置引數,改用--path <value>傳--type <pattern>,比如afs:write、afs:*(預設afs:write,支援萬用字元)
示例(一個終端裡跑這條,另一個終端裡跑 arc afs write /demo/hello.txt ...)
$ arc afs subscribe /demo
Subscribed to /demo (type=afs:write) — Ctrl-C to stop
{"type":"afs:write","path":"/demo/hello.txt","source":"fs","timestamp":1787870798884}寫入與刪除
arc afs write
往檔案寫內容。
用法
arc afs write [path] [content] [options][path]（位置引數，或用--path <path>，兩者給一個即可，必須有一個）：要寫的路徑--content <text>：要寫的內容--mode <mode>：replace（預設）、append、prepend、patch、create、update之一--patch <json>：patch 操作的 JSON 陣列，配合--mode patch用--meta <key=value>：設定一個後設資料欄位，可重複--if-match <version>：樂觀併發控制 token，來自之前一次stat/read/write的結果。當前版本和這個 token 不一致時，寫入會被AFS_CONFLICT拒絕；不支援這個機制的 provider 會忽略這個引數（誰後寫誰贏）
示例：先寫後追加
$ arc afs write /demo/draft.txt --content 'first draft'
OK /demo/draft.txt
$ arc afs write /demo/draft.txt --content ' plus more' --mode append
OK /demo/draft.txt
$ arc afs read /demo/draft.txt
first draft plus morearc afs delete
刪除檔案或目錄。
用法
arc afs delete [path] [options][path]（位置引數，或用--path <path>，兩者給一個即可，必須有一個）：要刪除的路徑-r, --recursive：遞迴刪除目錄（預設false）--dry-run：只列印會刪掉什麼，不真的刪--yes：跳過 TTY 確認提示（這個提示只在 stdin 是真實 TTY 時才出現；非互動場景——指令碼、CI、本文件自己的這些示例——不管有沒有--yes都不會卡在那裡等）
別名是 arc afs rm。
示例：先預覽，再刪除
$ arc afs delete /demo/draft.txt --dry-run
Would delete /demo/draft.txt (dry-run)
$ arc afs stat /demo/draft.txt
PATH=/demo/draft.txt
KIND=fs:file
SIZE=21
$ arc afs delete /demo/draft.txt --yes
OK /demo/draft.txt執行 Action
arc afs exec
執行某個 provider 在指定路徑上暴露的 action，比如 provider 自己定義的操作，不是單純的檔案讀寫。
用法
arc afs exec <executable_path> [options]executable_path（必填）：要執行的 action 路徑--args <json>：JSON 格式的引數，比如--args '{"key": "value"}'
不是每個掛載點都暴露 action。對一個連著正在跑的例項的純 fs:// 掛載點調 action 路徑，目前會得到一個通用的伺服器錯誤，不是一條具體的資訊——daemon 的 HTTP 層沒有把這種情況下 AFS 底層的報錯文本傳上來：
$ arc afs exec /demo/.actions/foo
ERROR: Internal server error在 --standalone 模式下（沒有 daemon 參與）同一條呼叫會得到那條具體的資訊：
$ arc afs exec /demo/.actions/foo --standalone
ERROR: No actions available for path: /.actions/foo掛載管理
arc afs mount 是獨立的子命令組，管理掛載了什麼、掛在哪。
arc afs mount <subcommand> [options]arc afs mount add 寫的是從當前目錄往上找到的那個 .afs-config/config.toml——不管你有沒有連著某個 --instance/--home。--home 會被直接拒掉（退出碼 5），因為這個選項暗示改動會送到例項的 daemon，而它從來不會。--instance / -i 是全域的例項選擇器：那個例項沒在跑時，命令在 mount add 之前就失敗。去掉 --home、換到正確的目錄跑。要改一個正在跑的例項掛了什麼 cd 進那個例項的 home 目錄(就是你起它時 arc service start --home 傳的那個),再跑 arc afs mount add,這樣立刻對那個例項生效,不用重啟。（AFS runtime boundaries 頁裡「mount add 不天然是一條 acceptance path」這條提醒背後的機制就是這個——從錯誤的目錄跑 mount add，會讓這個掛載出現在 mount list 裡，卻不出現在 ls 裡。）
$ arc afs mount add /demo fs:///path/to/a/local/directory --instance docs-demo
ERROR: no instance named "docs-demo". `arc service list` shows 0
$ arc afs mount add /demo fs:///path/to/a/local/directory --home /Users/you
ERROR: --home is not supported by `arc afs mount add`. `arc afs mount` only reads and writes the `.afs-config/config.toml` found by walking up from the current directory; it never reaches an instance's daemon, so the selected instance would silently not see the change. Drop the flag to edit the cwd config, or mount into a running instance at runtime with `arc attach --to <daemon-url> --namespace <ns> --source <dir>`.cd ~/docs-demo # the instance's --home directory
arc afs mount add /demo fs:///path/to/a/local/directory
arc afs ls /demo --instance docs-demo # visible right awayarc afs mount add
新增一個掛載。
用法
arc afs mount add <path> <uri> [options]path（必填）：掛載路徑，比如/srcuri（必填）：provider URI，比如fs://./src--namespace <name>：掛載的 namespace--description <text>：掛載描述--sensitive-args <names>：要當作敏感憑證處理的欄位名-s, --set <key=value>：直接設定一個憑證，可重複，跳過互動式輸入--terminal：用終端 readline 收集憑證，而不是瀏覽器-f, --force：強制重新收集憑證，忽略快取值
示例
$ arc afs mount add /demo fs:///path/to/a/local/directory
Mounted fs:///path/to/a/local/directory at /demoarc afs mount list
列出全部掛載。
用法
arc afs mount list [options]別名是 arc afs mount ls。沒有 --namespace 過濾——當前目錄的 .afs-config/config.toml 是一張表，沒有按 namespace 分片這回事，所以傳 --namespace 會被拒絕：
$ arc afs mount list --namespace anything
ERROR: --namespace is not supported by `arc afs mount list`. `arc afs mount` reads and writes the cwd `.afs-config/config.toml` as one table; there is no per-namespace slice. Drop --namespace.示例（只展示一條；你實際的列表會包含你加過的每一個掛載）
$ arc afs mount list
/demo -> fs:///path/to/a/local/directoryarc afs mount remove
取消一個掛載。
用法
arc afs mount remove <path> [options]path（必填，只能是位置引數）：要移除的掛載路徑。--help裡也列了一個標[required]的--path選項，但把它當 flag 傳、不按位置傳，並不滿足這個必填要求——照樣報Not enough non-option arguments: got 0, need at least 1。永遠按位置傳這個路徑--namespace <name>：不支援——arc afs mount把當前目錄的.afs-config/config.toml當成一張表，沒有按 namespace 分片這回事，所以remove --namespace foo會被拒絕（ERROR: --namespace is not supported by 'arc afs mount remove'），和mount list一樣
別名是 arc afs mount rm。
示例
$ arc afs mount remove /demo
Unmounted /demo把路徑當 --path 傳、不按位置傳是不行的，即便 --help 把它列成必填選項：
$ arc afs mount remove --path /demo
ERROR: Not enough non-option arguments: got 0, need at least 1arc afs mount validate
校驗當前的掛載配置。
用法
arc afs mount validate示例
$ arc afs mount validate
Configuration is valid關於輸出的說明
afs 命令連著一個正在跑的例項時——這是預設情況——完全不往 stderr 寫東西 上的結果就是全部輸出。啟動日誌屬於 daemon,不屬於你的 shell。
例外是 --standalone,因為那種模式下命令會在你自己的處理程序裡把 AFS 啟起來,這份啟動日誌就打到你的終端上。其中三行是不變的——一行說明當前是臨時模式;一行回顯它讀到的是哪個/哪些 .afs-config/config.toml;再一行是來自 node:boot 的 warn 記錄,只要 AFS_DID_SPACE_SCOPE_SECRET 沒設定就會出現,說 DID Space 的 scope 脫敏是關的、目錄名以明文存放:
[standalone] not attached to any instance — ad-hoc mode (no runtime state)
[standalone] config: /path/to/.afs-config/config.toml
{"ts":"…","level":"warn","service":"arc-node","ns":"node:boot","message":"[afs-loader] AFS_DID_SPACE_SCOPE_SECRET unset — DID Space scope de-identification is OFF (plaintext directories). Set the secret to enable; set AFS_DID_SPACE_REQUIRE_DEID=true to enforce."}把這個變數設上,第三行就沒有了;把 AFS_DID_SPACE_REQUIRE_DEID=true 設上,則會把"沒設定"變成直接報錯。stderr 上再多出來的內容,是 node:boot 在彙報你這臺機器自己的狀況——比如某個掛載沒能建立,或者排程器自己啟動時打的一行 [code-agents] recover ok: ...——所以總行數因機器而異。認這三行,別去數行數。這些都不是命令結果本身的一部分,上面的示例裡也都略掉了。