> For AI agents: the complete documentation index is available at https://devcodex-labs.github.io/capability-graph/llms.txt, the full documentation bundle is available at https://devcodex-labs.github.io/capability-graph/llms-full.txt.

# Adapter 接口

可用

仅合同

## RuntimeAdapter

一个 Provider 最多配置一个 Runtime Adapter。`query()` 输入项目、环境、可选实例过滤、当前静态修订、limit 和 cursor；输出实例、观察和可选续页游标。

Core 验证：

- Provider、项目和环境匹配请求；
- `instanceOf` 是当前 Provider 的已有静态能力；
- facts、association 和游标满足预算；
- observation 的修订、兼容、availability 和 freshness 合法；
- `requiredRuntimeRevision` 不被静默切换。

Adapter 自己管理连接、取消、重试和清理。Core 的 5 秒默认超时只停止等待；迟到拒绝必须由 Adapter 消费，不能形成未处理 Promise rejection。

## CapabilityRetriever

仅合同

输入查询文本、允许的 Provider IDs、每个 Provider 的当前 Static Revision 和候选上限；输出候选身份、可选 score 与 `sourceStaticRevision`。

Core 按 Adapter 原始顺序生成一基 `rank`。候选被拒绝时保留排名间隙，合法项不重排。Core 拒绝范围外 Provider、不存在的能力、不可读来源修订、超预算候选和其他违反合同的返回。

未指定修订时，一个来源不可读不应清空其他 Provider 的合法候选；指定修订不可读时查询级失败。

## KnowledgeRetriever

仅合同

`retrieve(input, access)` 只处理 Core 展开的最终 targets。每个 target 含能力身份、`knowledgeId`、声明 locator 和经过的 Collection IDs，不含绝对知识根或 `readContext`。

命中必须提供能力身份、`knowledgeId`、`contentId`、source、UTF-8 `startOffset`/`endOffset`、snippet 和可选 score。索引证据必须精确覆盖最终 targets Provider，证明每个文档的 source/indexed contentId、mapping/config revision、观察时间和 freshness；零命中也必须返回证据和明确 `knowledgeState`。

Core 限制 hits 数量、snippet 字节、内容边界和访问范围。过期证据不会降级为成功空结果。

## KnowledgeReader

可用

仅合同

`canRead(ref)` 同步决定是否支持非本地来源。Core 选择第一个匹配的自定义 Reader；内置本地 Reader 优先处理 `relative-file`。

`read(ref, context, { maxBytes })` 返回精确 bytes、contentType、contentId 和 source。Reader 不得替换声明 locator，必须遵守最大字节并保证 `contentId` 对应真实 bytes；`sourceContext.knowledgeRootDir` 不能进入公共响应。无匹配 Reader 使用 `CG_READER_UNCONFIGURED`，执行失败使用 `CG_READER_UNAVAILABLE` 或 Core 投影的读取错误。

## DatabaseAuthorityAdapter

仅合同

`openView(providerId)` 返回稳定 `DatabaseReadView`，暴露 Provider metadata、sourceRevision、可选知识根，以及 `getCapability()`、`scanCapabilities()`、`neighbors()` 和 `close()`。

同一 view 的 Provider、知识根、sourceRevision 和记录必须稳定。扫描记录按 capabilityId 严格升序且恰好一次；之后点读必须重现同一记录。Core 先完整扫描和收集 ID，再进行端点检查和 `parents`/`specializes`/`requires` 三类无环检查，不能边扫边判不存在。随后交叉验证完整的 `requires`/`requiredBy` 流，缺失或伪造的反向依赖也必须使装载失败。Static Revision 使用与文件模式相同的规范序列化算法。

Core 拥有 `close()` 调用并在验证失败或视图退休时执行；仍有查询 pin 时延迟关闭。Adapter 不提供通用写入、CRUD 或迁移能力。