跳到主要内容

AFS

本地巡检 AFS

在指定 arc 版本上，对 mount 与路径做以只读为主、可复跑的本地巡检，不编造存储神话。

用本页检查你已经拥有的本地 AFS 面。下文粘贴的输出均来自 arc 2.0.0-beta.28 对本地 daemon 的实测。你的 mount、路径与子项会不同。不要把样例路径当成产品默认。

本巡检的安全规则

规则原因
优先 explain、ls、stat、read、search只检视，不虚构结构
只用实例上已暴露的路径未知路径不是通用 demo 树
对 mount list 脱敏Provider URI 可能含 token
在确认 mount 的 access mode 前不做 write/delete/exec变更取决于 mount 与权限
不要假定刚执行的 mount add 立即可用实测缺口：CLI 可能报成功，操作仍失败

1. 确认版本与帮助

bash
arc --version
arc afs --help
text
2.0.0-beta.28

帮助列出 ls、read、write、delete、stat、exec、explain、search、mount。完整旗标见 arc afs。

2. 先 explain 概念，再看 mount

bash
arc afs explain
text
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
bash
arc afs explain mount

explain mount 列出本实例的 mount，输出随环境而变。形状示例（敏感处已脱敏）：

text
Mounts
======

Current mount configuration:

  /dev/ai/hub
  /dev/web - Web Device — Site Host
  /ash - ASH pipeline DSL
  /modules/vault
  /modules/project
  /modules/memory
  …
bash
arc afs mount list

示例（凭证已脱敏）：

text
/dev/ai/hub -> aignehub://hub.aigne.io
/dev/web -> web-device:// (Web Device — Site Host)
/ash -> ash:// (ASH pipeline DSL)
/modules/vault -> vault://…[redacted]
/modules/project -> fs:///…/project
/modules/memory -> fs:///…/test-mem
/telegram -> telegram://[REDACTED]
…
bash
arc afs mount validate
text
Configuration is valid

validate 检查配置形态，不证明每个 mount 都能提供数据。

3. 列出根命名空间

bash
arc afs ls / -l

样例（截断；你的根条目会不同）：

text
├── 📁 blocklet-manager — Local blocklet workspace manager: …
├── 📁 spaces — Local DID Space logical roots
├── 📁 web — Web Device — renders .web/ + pages/ into static HTML. …
├── 📁 registry
├── 📁 modules
├── 📁 .knowledge (afs:system) — Provider capability index
├── 📁 .meta (afs:system) — Root metadata and mount info
└── 📁 .actions (afs:system) — Root-level executable actions
bash
arc afs stat /
text
PATH=/
CHILDREN=108
ACTIONS=mount,unmount,read,list,write,query,aggregate,delete

根上的 ACTIONS 是根级 action 通告。出现在列表里不等于每个 mount 都支持同名动词。

4. 巡检已知 mount 路径

选择已在根或 mount list 中出现的路径。核验主机上 /modules/project 是本地 fs:// mount。

bash
arc afs ls /modules
arc afs stat /modules/project
arc afs explain /modules/project
text
PATH=/modules/project
KIND=fs:directory
CHILDREN=185
MODIFIED=2026-07-30T21:14:23.150Z
bash
arc afs read /modules/project/package.json --start-line 1 --end-line 12
text
{
  "name": "afs",
  "description": "Explore and manage AFS file systems",
  "version": "2.0.0-beta.15",
  …
}

5. 读路径上的能力声明

若 provider 暴露，能力在相对 mount 的 /.meta/.capabilities（或聚合视图）下。

bash
arc afs read /modules/project/.meta/.capabilities

本地 fs mount 上实测到的形状（截断）：

json
{
  "schemaVersion": 1,
  "provider": "fs",
  "description": "Local filesystem provider",
  "operations": {
    "read": true,
    "list": { "supported": true, "features": { "orderBy": true } },
    "write": {
      "supported": true,
      "features": { "ifMatch": true, "treeMerge": true, "treeToggle": true, "treeIncrement": true }
    },
    "delete": { "supported": true, "features": { "where": true } },
    "search": true,
    "exec": true,
    "stat": true,
    "explain": true,
    "batchWrite": true,
    "batchDelete": true
  }
}

用这份声明——而不是靠路径形状猜——判断 search、write 或 batch 是否在合同内。

6. Search（provider 定义的自由文本）

bash
arc afs search /modules/project RELEASING

样例命中（截断）：

text
/modules/project/CLAUDE.md
/modules/project/README.md
/modules/project/RELEASING.md
…

搜索质量、覆盖与排序由 provider 定义。见 Search and query。

7. 预期失败

命令beta.28 实测含义
arc afs read /this-path-does-not-exist-xyzERROR: Path not found: …（exit 5）路径不存在
arc afs ls /modules/project/definitely-missing-xyzERROR: Path not found: …（exit 5）mount 下子路径不存在
arc afs exec /.actions/query --args '{"path":"/modules/project","limit":2}'ERROR: Collection query is not available on this surface（exit 5）此处未声明/不可用 query——不是静默降级成 list
arc afs mount add /modules/… fs:///tmp/… 后 ls/read显示 Mounted；explain 可能 TYPE unknown；ls 空或报错；read not found未再次核验前，不要把 add 成功当成可用

8. 可选：仅在已知可写 mount 上变更

当且仅当你有自己控制的可写 mount（例如已挂好的可丢弃 fs:// 目录）时，才做 write/read/delete。不要虚构通用可写路径。

在预挂载的可写 fs:// 路径上实测（核验主机为 /modules/memory——你的路径会不同）：

bash
arc afs write /modules/memory/afs-doc-recipe.txt --content 'Hello from AFS recipe' --mode create
arc afs read /modules/memory/afs-doc-recipe.txt
arc afs stat /modules/memory/afs-doc-recipe.txt
arc afs delete /modules/memory/afs-doc-recipe.txt
text
OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe
PATH=/modules/memory/afs-doc-recipe.txt
KIND=fs:file
SIZE=21
…
delete

删除后 read 为 not-found。完整任务形态见 Recipes。

本页不做什么

  • 不替你启动或重配 daemon。
  • 不声称每个安装都自带同一棵 demo 树。
  • 不把源码仓库里的 package 名当成已挂载产品。
  • 不替代正式发布或 DID Space 部署验收。本地巡检是另一条验证面；见 Runtime boundaries。