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

# Provider 自有 API

设计示例；Seed 参考可运行

Provider 自己决定 HTTP 路径、认证、请求范围和返回形状。先完成上一页并得到已打开的 `graph`。下面是供自有 handler 调用的 TypeScript 函数片段，不包含 HTTP 服务启动；完整普通 API 执行路径见下方 Seed 链接。

本例由 Provider 显式维护主入口 `route`。Core 的 `listCatalog()` 返回平坦目录，不会自动筛选根节点；固定入口可直接调用批量详情，再投影首轮需要的摘要。

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

export async function listMainCapabilities(graph: CapabilityGraph) {
  const provider = graph.forProvider('acme.http');
  const details = await provider.getCapabilities(['route']);

  return {
    capabilities: details.results.map((item) => item.ok
      ? { ok: true, id: item.value.id, name: item.value.name,
          description: item.value.description, whenToUse: item.value.whenToUse,
          distinction: item.value.distinction }
      : item),
    revision: details.meta.staticRevision,
    meta: details.meta
  };
}
```

`getCapabilities()` 返回逐项结果；缺失的主入口仍保留错误，不能过滤后伪装为空目录。成功时 `capabilities[0].id.capabilityId` 为 `route`，响应只包含首轮选择所需字段。`revision` 是实际返回的 Static Revision，`meta` 保留完整性和 warnings。

## 一次请求如何逐步展开

以下路径只是你的 API 设计示意，不是主包自带端点：

| 请求                                                | Handler 调用                                                                                   | 预期结果与下一步                                         |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `GET /capabilities/main`                          | 上面的 `listMainCapabilities(graph)`                                                            | 返回 `route` 摘要及修订，Agent 根据意图选路由能力                 |
| `POST /capabilities/children`，输入能力 `route` 与上一步修订 | `getNeighbors('route', { kinds: ['children'], requiredStaticRevision })`                     | `groups.children.items` 包含 `route.http`，有游标时继续该组 |
| `POST /capabilities/detail`，输入 `route.http` 与同一修订 | `getCapabilities(['route.http'], { requiredStaticRevision })`                                | `results[0]` 为能力详情，先检查 `ok`                      |
| `POST /capabilities/selection`，显式选择 `route.http`  | `resolveSelection({ selected: ['route.http'], requiredStaticRevision })`                     | 返回必要的 `requires` 闭包和每个加入项的原因                     |
| `POST /capabilities/documents`，传入 Selection 结果    | `readDocuments({ selected: resolved.map((id) => id.capabilityId), requiredStaticRevision })` | 返回已选能力知识的逐项内容/错误                                 |

请求体中的 `requiredStaticRevision` 取首个响应的真实值，不填写版本号。Handler 应验证输入，先按用户/租户解析允许的 Provider，再取得绑定对象；`forProvider()` 本身不做用户认证。服务关闭时等待在途请求完成，再关闭共享 `graph`，不要在每次 handler 结束时关闭它。

显式修订已退休时，向调用方返回 `CG_REVISION_MISMATCH` 并重新发现；不能静默换成当前修订。分页结果保留对应关系组的游标、完整性和 warnings。

## Provider 必须负责

- 身份认证和租户/项目绑定；
- 将宿主允许范围转换为 `requestProviderScope`；
- 工具或端点命名；
- Agent 意图判断和选择策略；
- Provider Specification 的发现与投递；
- 把 Core 错误映射为协议错误，但保留 `ErrorCode` 与 `NextAction`。

## Core 不负责

Core 不监听端口、不启动业务服务、不执行能力，也不保证 Agent 采纳规范。可运行参考见 [Seed 端到端示例](https://devcodex-labs.github.io/capability-graph/examples/seed-provider.md#provider-owned-api)。

## 后续路径

| 目标               | 下一步                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 调整能力粒度           | [建模 Provider](https://devcodex-labs.github.io/capability-graph/guides/model-a-provider.md#%E9%80%89%E6%8B%A9%E8%83%BD%E5%8A%9B%E7%B2%92%E5%BA%A6) |
| 设计父子、特化或相关关系     | [设计关系](https://devcodex-labs.github.io/capability-graph/guides/design-relations.md)                                                               |
| 让 Agent 按需读取本地文档 | [添加本地知识](https://devcodex-labs.github.io/capability-graph/guides/add-local-knowledge.md)                                                          |
| 暴露项目实际注册实例       | [使用运行时](https://devcodex-labs.github.io/capability-graph/guides/use-runtime.md)                                                                   |
| 使用 MCP 渐进发现      | [Provider 自有 MCP](https://devcodex-labs.github.io/capability-graph/integrations/provider-owned-mcp.md)                                            |
| 接入多个 Provider    | [使用多个 Provider](https://devcodex-labs.github.io/capability-graph/guides/multiple-providers.md)                                                    |
| 查字段、错误和预算        | [API 参考](https://devcodex-labs.github.io/capability-graph/reference/index.md)                                                                     |
| 诊断失败             | [故障排查](https://devcodex-labs.github.io/capability-graph/troubleshooting/index.md)                                                                 |

数据库权威、能力召回、知识检索和远程 Reader 提供公开合同，但不附带真实后端。只有 Provider 配置了对应 Adapter，相关原语才可用。