Search 与 query | ArcBlock

不要把 list、query、search 当成同一功能的不同名字。它们解决不同问题，做出不同承诺。

证据：packages/core/src/capabilities/collection-query.ts、docs/guides/collection-query.md、type.ts 中的 AFSModule.search / query，以及 arc 2.0.0-beta.28 实测。

三种合同

操作	用途	不要假定
`list`	枚举路径或子项	相关性排序结果集，或与 provider 无关的数据查询语言
`query`	标准 `/.actions/query` 上的类型化集合 spec	在未声明能力时有客户端回退
`search`	Provider 定义的自由文本检索，经共享结果信封返回	全局全文覆盖、语义检索、共享索引或统一排序算法

list — best-effort 枚举

list 是文件系统式的目录遍历。不支持的选项可能被忽略或标记。适合回答「这里有哪些子项？」

arc afs ls /modules/project

search — provider 定义的自由文本

arc afs search <path> <query>

在本地 fs:// mount 上实测（arc 2.0.0-beta.28）：

arc afs search /modules/project RELEASING

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

规则	细节
归属	Provider 拥有搜什么、如何索引、如何排序
信封	ARC 用 `AFSSearchResult` 返回匹配，并可合并请求路径下可搜索 provider 的结果
无全局承诺	合并结果 ≠ 全局 FTS 索引或语义搜索产品
Visibility	`visibility: "meta"` 的 mount 上 search 被拒绝

在 provider 自己的文档中写清 search 预期，不要抄另一个 provider 上观察到的行为。

query — 可选且严格

Collection query 是 /.actions/query 上的类型化 action（entries 模式与 aggregate 模式）。哲学是 声明 ⇒ 完整执行 spec。畸形 spec 与不支持的块是 AFS_VALIDATION_ERROR（或等价）。没有「用 list 假装 query」的静默客户端降级。

依赖之前先探测：读 <mount>/.meta/.capabilities（或根能力），找 name === "query" 且 pathTemplate === "/.actions/query" 的标准 action。Provider 本地方言（如表级 query 路径）不是本契约。

在 beta.28 上对未提供 collection query 的 fs:// 工程 mount 实测：

arc afs exec /.actions/query --args '{"path":"/modules/project","limit":2}'

ERROR: Collection query is not available on this surface

观察到的 exit code：5。这是正确信号——不是半份文件列表。

当 provider 确实声明了 query，消费者发送类型化 spec（如 path、doc、where、orderBy、limit/offset 或 cursor、count、groupBy、可选聚合）。完整字段词表与实现 checklist 见 ARC 内部指南 docs/guides/collection-query.md 与 packages/core/src/capabilities/collection-query.ts。

如何选择

目标	优先
浏览树	`list`
找 provider 会找的自由文本匹配	`search`（先查能力）
对记录集合做服务端类型化过滤/排序/计数/聚合	`query`（仅当已声明）
「像桌面 FTS 产品一样搜整机」	超出 AFS 整体合同

产品叙事注意

未来的文档库或 NAS 取向产品仍可能把目录、选定全文集合与更丰富索引做成独立产品选择。这些选择不是使用 AFS 路径的自动后果。