> 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

- `CG_KNOWLEDGE_NOT_ASSOCIATED`：已选能力没有匹配的 knowledgeId；核对选择和过滤。
- `CG_KNOWLEDGE_TYPE_UNSUPPORTED`：将 Collection ID 当成单篇文档读取。可先用 `listKnowledgeMembers()` 发现成员，再按成员 ID 精确读取；需要全文检索时配置 Retriever 并使用 `queryKnowledge()`。
- `CG_READER_UNCONFIGURED`：远程引用存在，但没有 Reader；配置 Reader，不要写成“没有知识”。
- `CG_READER_UNAVAILABLE`：匹配 Reader 执行失败；检查外部来源和资源清理。
- `CG_SOURCE_UNREADABLE`：本地或远程来源当前不可读。
- `CG_PATH_TRAVERSAL`：相对路径或真实路径逃离 Provider 根；修正定义和符号链接。

批量读取逐项返回错误。保留成功文档，不要把混合结果统一改成 `not found`。知识正文不在 Static Revision 中，每次读取使用新的 contentId。

## 检索与 Adapter

`CG_RETRIEVER_UNCONFIGURED` 表示调用了可选召回或检索，但没有配置对应 Retriever。继续使用 Flat Catalog 或配置真实后端。

`CG_RETRIEVER_UNAVAILABLE` 表示后端执行失败。检查网络、索引和资源限制，不要返回成功空数组掩盖故障。

`CG_INDEX_STALE` 表示证据中的 Static Revision、mapping/config revision 或内容身份与当前 targets 不一致。重建受影响映射并重新查询；不要沿用旧向量或缓存。

`CG_ADAPTER_CONTRACT_INVALID` 表示 Adapter 返回的身份、范围、排序、证据、偏移、预算或状态违反合同。先记录原返回的有界摘要，再对照 [Adapter 接口](https://devcodex-labs.github.io/capability-graph/reference/runtime-adapter.md) 修复。