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

# Capability Graph

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

**下一步：** [运行第一个示例](https://devcodex-labs.github.io/capability-graph/getting-started/first-provider.md) · [判断是否适合](#何时使用)

## 它解决什么问题

例如用户要求“给现有 `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 发起，方向如下：


**Agent
**
根据任务选择下一次查询

**Provider-owned API / MCP
**
认证、绑定项目和范围，再调用 Core

**Capability Graph Core
**
校验来源并执行有界查询

**Provider 权威来源
**
提供静态定义；按需读取知识或调用 Adapter

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

## 何时使用

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

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

## 从这里开始

- [快速开始](https://devcodex-labs.github.io/capability-graph/getting-started/index.md)：从安装到第一个 Provider 和第一次查询。
- [核心概念](https://devcodex-labs.github.io/capability-graph/concepts/index.md)：理解身份、关系、范围、修订、知识和 Runtime。
- [GitHub](https://github.com/devcodex-labs/capability-graph)：查看源码、测试和真实 Seed。

## 文档目录

- [快速开始](https://devcodex-labs.github.io/capability-graph/getting-started/index.md)
- [核心概念](https://devcodex-labs.github.io/capability-graph/concepts/index.md)
- [使用指南](https://devcodex-labs.github.io/capability-graph/guides/index.md)
- [集成](https://devcodex-labs.github.io/capability-graph/integrations/index.md)
- [示例](https://devcodex-labs.github.io/capability-graph/examples/index.md)
- [API 参考](https://devcodex-labs.github.io/capability-graph/reference/index.md)
- [故障排查](https://devcodex-labs.github.io/capability-graph/troubleshooting/index.md)

## 最小能力发现

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

```ts
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();
}
```

这段代码的职责分工：

| 调用或配置                         | 含义                                         |
| ----------------------------- | ------------------------------------------ |
| `open()`                      | 加载有效启用的 Provider，并完整校验静态定义                 |
| `hostAllowedProviders`        | 宿主允许访问的 Provider 上限                        |
| `integrationEnabledProviders` | 本次集成启用的 Provider；与宿主允许集合取交集                |
| `providers`                   | 每个有效启用 Provider 的唯一权威来源配置                  |
| `authority.kind` / `rootDir`  | 本例从指定文件根读取 `provider.json` 和能力文件           |
| `forProvider()`               | 将查询绑定到 `acme.http`，后续可以使用 Provider 内的能力 ID |
| `listCatalog()`               | 返回平坦能力摘要，不是根节点专用接口，也不展开详情、知识和 Runtime      |
| `close()`                     | 释放 Core 持有的权威视图句柄                          |

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

```json
{
  "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、目录和定义必填字段。

下一步进入[快速开始](https://devcodex-labs.github.io/capability-graph/getting-started/index.md)，创建真实定义并把主能力、意图收窄和子能力逐层暴露给 Agent。