AFS 暴露的是路径操作。负责该路径的 provider 提供操作及其行为。不要把 API 建模成「每个动词都必须支持」的通用文件系统。
本页证据：packages/core/src/type.ts（AFSModule、AFSRoot）、packages/core/src/afs.ts、packages/core/src/capabilities/types.ts（OperationsDeclaration）、packages/core/src/error.ts，对照 ARC 源码 44fbd616f 与 CLI arc 2.0.0-beta.28。
操作族
| 操作 | 模块方法（core） | 用途 | 能力边界 |
|---|---|---|---|
list | list? | 枚举路径下条目 | 选项与列举语义由 provider 定义；不支持的 list 旗标可能是 best-effort |
read / batch read | read?，可选 batchRead? | 读一个或多个资源 | 取决于 provider 与路径；visibility: "meta" 只返回元数据 |
write / batch write | write?，可选 batchWrite? | 创建或修改内容 | 路径存在不蕴含可写；mode 含 replace/append/prepend/patch/create/update |
delete / batch delete | delete?，可选 batchDelete? | 删除资源 | 递归与谓词选项取决于 provider/feature |
rename | rename? | 在 provider 规则内移动/重命名 | 并非每个 CLI 面都暴露 rename；查 core/API 与 provider |
stat | stat? | 查看元数据 | 共享结果信封；字段内容由 provider 定义 |
search | search? | 自由文本检索 | 覆盖与排序由 provider 定义；见 Search and query |
exec | exec? | 在路径上调用 action | 需要明确的 action 路径、参数与权限/严重级别策略 |
explain | explain? | 报告路径如何解析 | 用于路由与归属巡检 |
query | query?（可选） | 经 /.actions/query 的类型化集合查询 | 可选且严格；要么完整声明执行，要么不声明 |
AFSModule 上的可选方法是真实的：省略某方法即未实现该操作。根 AFSRoot 在调度层要求常见 ops，但仍经 mount 能力路由。
能力声明
Provider 通过 OperationsDeclaration 声明操作（布尔或 { supported, features }）：
| 字段 | 说明 |
|---|---|
read、list、write、delete、search、exec、stat、explain | 核心 op 旗标 |
query? | 镜像标准 collection-query action，供工具使用 |
batchWrite?、batchDelete? | 常被派生；真正 pushdown 需要方法存在 + features.batchPushdown |
subscribe?、interact? | 可选事件 / 向人提问能力 |
子能力 feature 示例：
| Feature | 声明后的含义 |
|---|---|
write.features.ifMatch | 通过不透明 meta.version 做乐观并发；必须强制执行或拒绝，禁止静默降级 |
list.features.orderBy | 服务端 list 排序 |
delete.features.where | 谓词删除 |
有声明时读取：
arc afs read <mount>/.meta/.capabilitiesAccess mode 与 visibility
| 概念 | 取值 | 效果 |
|---|---|---|
accessMode | readonly · create · append · readwrite | 约束模块/mount 允许的变更 |
visibility | full · meta | meta：read 只返回元数据；search 被拒绝 |
不要因为路径能 list 子项就假定 readwrite。
错误码（节选）
来自 packages/core/src/error.ts。应用应按 code 分支，不要只依赖英文文案。
| Code | Class | 典型原因 |
|---|---|---|
AFS_NOT_FOUND | AFSNotFoundError | 路径不存在 |
AFS_UNSUPPORTED | AFSUnsupportedError | 操作不支持 |
AFS_VALIDATION_ERROR | AFSValidationError | 参数错误或严格 query/spec 失败 |
AFS_READONLY | AFSReadonlyError | 对只读面做变更 |
AFS_ACCESS_MODE | AFSAccessModeError | 违反 mount access mode |
AFS_ACCESS_DENIED | AFSAccessDeniedError | 底层访问拒绝 |
AFS_FORBIDDEN | AFSForbiddenError | 策略禁止 |
AFS_AUTH_REQUIRED | AFSAuthRequiredError | 变更 action 需要认证 |
AFS_CONFLICT | AFSConflictError | ifMatch 版本不匹配 |
AFS_ALREADY_EXISTS | AFSAlreadyExistsError | 创建冲突 |
AFS_MOUNT_FAILED | AFSMountError | Mount 检查失败 |
AFS_ACTION_NOT_FOUND | AFSActionNotFoundError | 未知 action |
CLI 在 beta.28 上的观察：arc afs read 对缺失路径打印 ERROR: Path not found: …，exit 5。
CLI 与 core 面
| 面 | 常见暴露的操作 |
|---|---|
arc afs（beta.28） | ls、read、write、delete、stat、exec、explain、search、mount |
Core AFSModule | 以上，外加 rename、可选 query、可选 batch pushdown、subscribe 等 |
若某操作在 core 类型中有、但 CLI 组没有，使用程序/RPC 面，或检查根 /.actions/* 是否覆盖。见 arc afs。
Provider 作者
实现 AFSModule（通常经 AFSBaseProvider 与操作装饰器），只暴露能强制执行的操作，并跑共享 conformance 测试。继续见 Author a provider。