AFS recipes | ArcBlock

每条 recipe 写明版本、变更风险与假设。/modules/project 一类路径是核验主机上的例子，不是通用默认。请用你自己的 arc afs mount list 替换。

版本： arc 2.0.0-beta.28

Recipe 1 — 只读根与 mount 普查

目标： 在不改数据的前提下了解本实例暴露了什么。
是否变更： 否
假设： 本地 CLI 能连上你的 AFS 面（通常是正在运行的 daemon）

arc --version
arc afs explain
arc afs mount list   # 分享前脱敏
arc afs mount validate
arc afs ls / -l
arc afs stat /
arc afs ls /.actions

观察（截断，随主机而变）：

2.0.0-beta.28

Configuration is valid

PATH=/
CHILDREN=108
ACTIONS=mount,unmount,read,list,write,query,aggregate,delete

/.actions/unmount
/.actions/read
/.actions/list
/.actions/write
/.actions/query
/.actions/aggregate
/.actions/delete
/.actions/mount

完成标准： 你能指出至少一个愿意继续巡检的 mount 路径。

Recipe 2 — 巡检已知 mount（list / stat / read / capabilities / search）

目标： 在一个已有 mount 上验证路由与能力。
是否变更： 否
假设： 已有 mount 在提供数据（核验主机使用 /modules/project → fs://…）

MOUNT=/modules/project   # 换成你的路径

arc afs ls "$MOUNT"
arc afs stat "$MOUNT"
arc afs explain "$MOUNT"
arc afs read "$MOUNT/.meta/.capabilities"
arc afs search "$MOUNT" RELEASING

观察（截断）：

PATH=/modules/project
KIND=fs:directory
CHILDREN=185
MODIFIED=2026-07-30T21:14:23.150Z

capabilities JSON 含 "provider": "fs"，以及 search: true 与含 ifMatch 的 write features（完整片段见本地巡检）。

search 返回 mount 下路径，例如 /modules/project/RELEASING.md。

失败检查：

arc afs read /this-path-does-not-exist-xyz
# ERROR: Path not found: /this-path-does-not-exist-xyz  (exit 5)

完成标准： 你知道该 mount 的 capabilities 是否含 search/write，并读过一个真实文件。

Recipe 3 — 在预挂载可写路径上做可丢弃 write / read / delete

目标： 只在你已有可写 mount 的地方练习变更。
是否变更： 是（创建并删除一个文件）
假设： 已有已挂载且你控制的可写路径。核验主机为 /modules/memory（fs://…/test-mem）。不要盲目复制该路径。
不假设： 刚执行的 arc afs mount add 一定可用——见 Runtime boundaries。

W=/modules/memory/afs-doc-recipe.txt   # 把前缀换成你的可写 mount

arc afs write "$W" --content 'Hello from AFS recipe' --mode create
arc afs read "$W"
arc afs stat "$W"
arc afs write "$W" --content ' — append' --mode append
arc afs read "$W"
arc afs delete "$W"
arc afs read "$W"   # 期望 not found

观察：

OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe
PATH=/modules/memory/afs-doc-recipe.txt
KIND=fs:file
SIZE=21
MODIFIED=2026-08-11T06:47:04.762Z
OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe — append
delete
ERROR: Path not found: …

可选负向检查（不要编造成功）：

MOUNT=/modules/project   # 换成你的路径（本 recipe 可独立运行，不依赖 Recipe 2）
arc afs exec /.actions/query --args "{\"path\":\"$MOUNT\",\"limit\":2}"
# 核验用的 fs mount：ERROR: Collection query is not available on this surface

完成标准： 在你的 mount 上 create/read/append/delete 行为符合预期，且可丢弃文件已删除。

Recipe 卫生

规则	原因
共享 runbook 时写明 `arc --version`	beta 之间命令会漂移
演示优先用已有 mount	避免未证明的 `mount add` 路径
对 `mount list` 脱敏	URI 中可能有凭证
分开 list / search / query	合同不同
清理可丢弃文件	让实例回到原状