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

# 知识模型

Document 可用；检索仅合同

能力可以声明 `KnowledgeRef`，但知识不自动随一般关系展开。调用方先选择非空能力集合；仅 `requires` 可通过 `resolveSelection()` 加入必要能力，随后再决定读取或检索哪些知识。

## Document

本地 `relative-file` Document 可由 Core 直接读取，不依赖模型、数据库或网络。每篇必须声明角色，可选语言和展示元数据；路径受 Provider 根、真实路径和字节预算约束，每次读取都会取得内容身份。

## Collection

Collection 表示知识集合，不能通过 `readDocuments()` 拼接整读。`listKnowledgeMembers()` 有界列出成员元数据；调用方知道成员 ID 后，可用 `readDocuments({ knowledgeIds: [...] })` 精确读取成员。按文字检索集合需要显式 `KnowledgeRetriever`，并返回与当前静态修订和知识映射一致的证据。

## 远程 Reader

HTTP/HTTPS 等引用已关联但没有 Reader 时，应返回 `CG_READER_UNCONFIGURED`。这表示后端未配置，不表示“没有知识”。

Core 校验证据和边界，不生成最终答案。实现步骤见[添加本地知识](https://devcodex-labs.github.io/capability-graph/guides/add-local-knowledge.md)。

## 在 Acme HTTP 中选择知识

扩展后的 `route.validation` 可以绑定验证指南，`schema.request` 绑定 Schema 指南。任务只选择前者时，读取范围只有验证指南；即使两者有 `related` 边，也不会自动读取后者。Agent 确认还需要 Schema 后，应把它加入 `selected` 再查询。

入门 Fixture 的 `route.http` 绑定单篇 `routing-guide`，直接读取即可。只有需要从多篇知识中按文字检索时才考虑 Collection/检索后端；远程单篇文档则是 Reader 问题，不等于必须建 RAG。