#Provider 自有 API

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

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

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 设计示意，不是主包自带端点：

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

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

#Provider 必须负责

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

#Core 不负责

Core 不监听端口、不启动业务服务、不执行能力，也不保证 Agent 采纳规范。可运行参考见 Seed 端到端示例。

#后续路径

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