#Capability Graph

Capability Graph 帮助框架、SDK 或平台把能力整理成 Agent 可以逐步查询的目录。维护这组定义和接入规则的一方称为 Provider；它使用 Core 加载和查询定义，通过自己的 API 或 MCP 提供发现入口。

下一步： 运行第一个示例 · 判断是否适合

#它解决什么问题

例如用户要求“给现有 POST /users 增加请求校验”。只有工具名称或一整本文档时，Agent 仍需判断哪些能力有关、项目是否已有这条路由，以及该读哪段说明。使用 Capability Graph 后，接入层可以让 Agent：

1. 从路由目录发现 route.validation，按任务意图选择它。
2. 查看它与 schema.request 的关系，决定是否还需要请求 Schema。
3. 通过已配置的 Runtime Adapter 确认项目中的 POST /users 实例。
4. 读取已选能力关联的知识，再由宿主完成代码修改和验证。

Core 提供发现和查询结果，不执行能力，也不代替 Agent 判断意图。这个完整场景见示例分区；下方最小代码只演示静态目录。

#定义来源与查询方向

定义来源：Provider 提供能力文件、知识引用和可选 Adapter，Core 按配置加载并校验。查询则由 Agent 发起，方向如下：

结构化结果沿调用链返回。目录不携带知识正文或 Runtime 实例；需要这些信息时再发起对应查询。

#何时使用

适合能力较多、需要区分静态定义与项目实际实例、希望按所选能力读取知识的框架或平台。多个 Provider 也可以联合发现，但仍保留各自的身份和修订。

如果只有几个固定工具，Agent 不需要发现、选择或查询能力关系，直接提供 API/MCP 通常就够了。

#从这里开始

• 快速开始：从安装到第一个 Provider 和第一次查询。
• 核心概念：理解身份、关系、范围、修订、知识和 Runtime。
• GitHub：查看源码、测试和真实 Seed。

#文档目录

• 快速开始
• 核心概念
• 使用指南
• 集成
• 示例
• API 参考
• 故障排查

#最小能力发现

前置条件：已安装包，并按快速开始创建 acme.http Provider。下面是接入片段，需将 rootDir 替换为该 Provider 的真实目录；它不会生成定义文件。

import { CapabilityGraph } from '@devcodex/capability-graph';

const graph = await CapabilityGraph.open({
  hostAllowedProviders: ['acme.http'],
  integrationEnabledProviders: ['acme.http'],
  providers: [{
    providerId: 'acme.http',
    authority: { kind: 'file', rootDir: '/absolute/path/to/provider' }
  }]
});

try {
  const catalog = await graph.forProvider('acme.http').listCatalog();
  console.log(catalog.items);
} finally {
  await graph.close();
}

这段代码的职责分工：

使用快速开始的两个能力时，catalog.items 中会同时有 route 和 route.http。其中一项的精简投影如下，省略修订等字段：

{
  "id": { "providerId": "acme.http", "capabilityId": "route" },
  "name": "Routing",
  "description": "Define how requests reach application handlers.",
  "whenToUse": "Choose a routing capability before changing an entrypoint.",
  "distinction": "A static capability family, not registered runtime routes."
}

meta.completeness 为 complete 且没有 nextCursor 才表示本次目录已返回完整。要先只暴露主能力，由 Provider 接入层维护入口选择；不能把不带过滤的 listCatalog() 当作“只返回主能力”。加载失败时先检查 Provider ID、目录和定义必填字段。

下一步进入快速开始，创建真实定义并把主能力、意图收窄和子能力逐层暴露给 Agent。