> 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 与能力

可用

Provider 是一组能力及其接入规则的所有者。每个 Provider 在有效启用范围内必须恰有一个权威来源，文件或数据库二选一。

Provider Specification 描述如何正确使用该 Provider；正文归 Provider 所有，Core 只提供显式读取。`provider.json` 声明：

- `specificationId` 和版本；
- 适用软件、版本范围和可选条件；
- 一篇或多篇 `role: specification` 的 Document 映射，可带语言、标题与来源。

接入方负责首次可发现入口、适用版本判断、是否调用 `readSpecification()` 以及如何向 Agent 投递。普通浏览、Selection 和 `readDocuments()` 都不自动读取规范。Specification 不能覆盖用户指令、宿主 Policy、权限或执行授权。

## 为什么分开

静态图需要确定、可哈希的数据合同；规范正文可能独立发布、按版本变化或由宿主选择投递。Core 校验身份和适用性元数据的格式；实际项目版本匹配仍归接入层，不由 Core 执行。

## 贯穿示例：Acme HTTP

入门中的 `acme.http` 定义 `route` 和 `route.http`。能力增长后可扩展为：

| 能力                 | 负责什么      | 何时选择               |
| ------------------ | --------- | ------------------ |
| `route`            | 路由能力族     | 先寻找请求入口相关能力        |
| `route.http`       | HTTP 路由注册 | 新增或调整 HTTP handler |
| `route.validation` | 路由请求校验    | 在 handler 前验证输入    |
| `schema.request`   | 请求结构声明    | 描述必填字段和输入类型        |

后两项是概念扩展示例，不会由两节点入门 Fixture 自动生成。`PROVIDER.md` 放跨能力规则，验证指南绑定 `route.validation`；具体 `POST /users` 留给 Runtime，避免把每个业务路由变成静态能力。

## 能力建模

Static Capability 描述“Provider 能做什么以及何时应考虑它”，不是方法清单、运行实例或执行指令。一个可用节点至少要让第一轮发现回答：

- `name`：人类可读名称；
- `description`：能力解决什么问题；
- `whenToUse`：什么意图或条件下应考虑它；
- `distinction`：它与相邻能力的关键区别；
- 关系、知识和示例：按需补充，不把所有细节塞进目录。

粒度应稳定到可以独立选择，又不能细碎到每个函数或配置字段都是一个能力。静态图描述作者声明的领域结构，不从代码命名、目录或 Runtime 自动生成关系。

Core 校验 Schema、值、关系端点和环，不判断业务语义是否优秀。概念质量由 Provider 作者和评审流程负责，实践步骤见 [建模 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/concepts/capability-identity.md)。