> 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.

# 知识接口

可用

仅合同

## KnowledgeRef

`KnowledgeDocumentRef` 必填 `knowledgeId`、locator 和 `role`；可声明 `locale/title/summary/canonicalUrl`。`locale` 采用固定注册表校验的 BCP 47 规范值，过滤是精确匹配，没有父语言回退。`KnowledgeCollectionRef` 可有标题和摘要，members 是完整 Document 映射；Collection 没有聚合正文。locator 当前支持 `relative-file` 和 `http`。

## readDocuments

`ReadDocumentsQuery` 包含非空 `selected`、可选 `knowledgeIds/roles/locales`、范围和修订。同维取并、异维取交；先筛选再应用每次最多 8 篇的预算和 Reader。`DocumentReadBatch` 的 `knowledgeState` 区分无关联、筛选后为空和匹配，逐项结果保留错误槽。`DocumentRead` 携带能力身份、文档路由元数据、来源、内容类型、内容身份、正文和精确字节。

只有在 `knowledgeIds` 明确写出成员 ID 时才直接读取 Collection 成员；仅给 Collection ID 不会整读。远程 Document 需要 `KnowledgeReader`。

## readSpecification

`ReadSpecificationQuery` 限定一个 Provider，可按 `knowledgeIds/locales` 筛选；正文仅在该方法被显式调用时读取。`SpecificationReadBatch` 保留逐篇成功或错误，成功项 `SpecificationDocumentRead` 以 `providerId` 标识来源，不伪造 Capability ID。无规范、筛空和匹配可区分；单次仍受 8 篇预算。

## queryKnowledge

`KnowledgeSearchTarget` 只含最终过滤后的公开文档映射，不含绝对知识根或 `readContext`。原始数组、最终目标数与目标 JSON 字节数均有预算，超限时 Retriever 不会被调用。后端的 `KnowledgeHit` 使用 UTF-8 字节偏移，`endOffset` 为开区间；Core 核验后生成带正式路由元数据的 `KnowledgeResultHit`。`KnowledgeIndexEvidence` 必须证明映射、配置和内容身份与当前请求一致，即使零命中也不能省略。