跳到主要内容

AFS

编写 provider

从当前 JSON provider 与其 conformance 套件起步，只声明能强制执行的能力。

从当前测试覆盖的 provider 起步，不要从旧规划文档起步。在 ARC 源码树中：

产物作用
providers/core/json/src/index.ts紧凑实现基线（AFSJSON 继承 AFSBaseProvider）
providers/core/json/test/conformance.test.ts经 runProviderTests 的 conformance fixture
packages/testing（@aigne/afs-testing）共享套件与「声明即配套」fixture
docs/guides/provider-authoring.md编写纪律（标准 ops vs 语义 action、ifMatch、query）

最小公开合同

部分要实现什么
模块身份name、可选 description、uri / load 参数
路径归属稳定路径布局；不滥用保留虚拟前缀（.actions、.meta、.as …）
操作只实现能强制执行的方法：list / read / write / delete / stat / search / exec / explain / rename / 可选 query / 可选 batch
能力声明OperationsDeclaration（+ features）。声明 ⇒ 执行；未强制执行就不要宣传 ifMatch/query
错误使用共享 AFS*Error 码（AFS_NOT_FOUND、AFS_VALIDATION_ERROR、AFS_CONFLICT …）
Conformancetest/conformance.test.ts 调用 runProviderTests

JSON provider 的典型模式：

  1. 继承 AFSBaseProvider。
  2. 提供 static manifest() / load() 供 registry/URI 加载。
  3. 用 @List、@Read、@Write、@Delete、@Search、@Stat、@Explain … 装饰处理器。
  4. 需要 ifMatch 等 feature 时覆盖 getOperationsDeclaration()。
  5. 暴露 /.meta/.capabilities 供运行时发现。

跑 JSON 基线 conformance

在当前 ARC monorepo（package @aigne/afs-json）中：

bash
pnpm --filter @aigne/afs-json test -- test/conformance.test.ts

在 ARC 源码 44fbd616f 上实测（2026-08-10）：

text
372 pass
6 skip
0 fail
Ran 378 tests across 1 file.

该结果只证明这一基线与这一 commit，不证明每个 provider 或每个发行版。未声明可选能力时跳过套件（如 subscribe）是预期行为。

建议实现顺序

  1. 先画 FS 布局（目录 vs 叶子 vs action 路径）。
  2. 先实现检视：list + read（+ stat/explain）。存了什么就应能枚举——不要只把数据藏在自定义 action 后。
  3. 仅在存储能强制执行时再加路径变更（write/delete/rename）。
  4. 仅当操作需要超出路径 CRUD 的语义时，再加语义 @Actions。
  5. 用匹配真实数据的 structure fixture 接入 runProviderTests。
  6. 若声明 query，必须配套 collectionQuery fixture（声明即测试）。
  7. 若声明 write.features.ifMatch，必须配套 ifMatch 与指向同一后端的 peerProvider。
  8. 把数据、认证、search、失败边界写在通用 AFS 合同之外的 provider 文档里。

不要因为能 list 就声称 query，也不要因为暴露了 search 就声称某种搜索质量。

保留验收记录

在把 provider 当作公开 catalog 候选之前，使用下表。这是检查清单，不是「每个 provider 都已通过」的声明。

记录要捕获什么
合同拥有的路径、操作、声明的能力；不要互相推断
数据与访问边界后端系统、凭证或调用方边界、读写的数据、可观察失败
Conformance 证据精确测试命令、ARC/源码版本、pass/skip/fail
本地验收隔离的本地演练：ARC 版本、命令、非密钥环境选择、观察结果。不要用 DID Space 部署替代本地证据
兼容性观察所依赖的 ARC/runtime 与 provider 后端版本
支持归属维护者、生命周期状态、用户应依赖的文档位置

任一行未知，就不要进公开 catalog。源码树中的 package 是实现证据，不是支持承诺。见 Provider catalog。