#添加本地知识

当一个能力需要长说明、操作步骤或限制时，把正文单独放入 Knowledge，避免目录每次携带全文。短用途和选择条件仍写在 Capability 的摘要字段。本页假设你已有包含 route.validation 的 Provider；从空目录操作请先完成第一个 Provider。

#1. 放置文档

将 Markdown 或文本放在 Provider 权威根内，例如 knowledge/route-validation.md。

#2. 关联能力

以下是配置片段，合并进已有能力文件，保留其必填名称、描述、使用时机和已有关系；不要用片段覆盖整个文件。

{
  "capabilityId": "route.validation",
  "knowledge": [{
    "kind": "document",
    "knowledgeId": "route-validation-guide",
    "role": "guide",
    "locale": "zh-CN",
    "locator": {
      "type": "relative-file",
      "path": "knowledge/route-validation.md"
    }
  }]
}

#3. 只读取已选能力

查询片段：provider 是已打开图的 Provider 绑定对象。修订从此次目录结果取得：

const catalog = await provider.listCatalog();
const requiredStaticRevision = catalog.meta.staticRevision;
const result = await provider.readDocuments({
  selected: ['route.validation'],
  requiredStaticRevision
});
for (const item of result.results) {
  if (item.ok) console.log(item.value.knowledgeId, item.value.text);
  else console.error(item.error.code, item.error.nextAction);
}

Core 会校验相对路径仍位于 Provider 根的真实路径中，并按条目返回内容或错误。符号链接不能绕过根边界。role 用于按用途过滤，locale 用于精确语言匹配，不做自动语言回退。

knowledgeId 用于在已选能力的知识集合中继续收窄；locator.path 相对 Authority 根，不相对脚本位置。kind: document 允许精确读取；没有知识需求时不必配置该数组。

#预期结果

成功项的 value.knowledgeId 为 route-validation-guide，value.text 为文件正文，contentId 标识实际读取的字节。空的 selected 无效；拼错知识 ID、文件不存在或越出根边界应检查逐项错误，不能解释成“能力没有知识”。仅改正文无需重建能力身份；改关联需要重新加载静态定义。

下一步需要全文检索时再考虑检索 Adapter，不要把 Collection 当作可直接拼接的文档。

#当前边界

• Collection 不能整读；可以先列成员再按成员 ID 精确读取，全文检索需要 KnowledgeRetriever。
• HTTP/HTTPS 引用需要 KnowledgeReader；没有 Reader 会返回明确未配置错误。
• 知识只从非空已选能力集合展开；需要依赖闭包时先调用 resolveSelection()，仅 requires 被展开。