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

# 定义与身份

可用

| 字段              | 必填 | 说明                                    |
| --------------- | -: | ------------------------------------- |
| `providerId`    |  是 | 稳定 Provider 身份，必须符合 ID 规则             |
| `name`          |  是 | 人类可读名称                                |
| `version`       |  是 | Provider 定义版本，不属于能力身份                 |
| `specification` |  否 | Provider-owned Specification metadata |

`specification` 可整体省略；提供时必须包含非空 `specificationId`、`version` 和非空 `documents`。每篇 Document 的 `role` 固定为 `specification`；`appliesTo` 及其 `software`、`versionRange`、`conditions` 均可选。Core 仅在显式 `readSpecification()` 时读取正文，不把正文当作执行规则，也不判断当前项目版本。

文件 Authority 的 `provider.json` 必须与配置中的 `providerId` 一致。每个有效启用 Provider 必须恰有一个 Authority。

## 可执行验证用例

| Case ID           | 字段/场景                  | 预期   |
| ----------------- | ---------------------- | ---- |
| `DEF-PROVIDER-01` | 最小完整记录                 | 打开成功 |
| `DEF-PROVIDER-02` | 缺少 `providerId`        | 拒绝   |
| `DEF-PROVIDER-03` | 非法 `providerId`        | 拒绝   |
| `DEF-PROVIDER-04` | 空 `name`               | 拒绝   |
| `DEF-PROVIDER-05` | 空 `version`            | 拒绝   |
| `DEF-PROVIDER-06` | 不完整 `specification`    | 拒绝   |
| `DEF-PROVIDER-07` | 定义与配置的 Provider ID 不一致 | 拒绝   |
| `DEF-PROVIDER-08` | 有效多文档 Specification 映射 | 打开成功 |

这些用例由 Reference 校验器通过公开 `CapabilityGraph.open()` 执行，不依赖内部校验函数。

## Capability 定义

| 字段             | 必填 | 默认   | 说明                                             |
| -------------- | -: | ---- | ---------------------------------------------- |
| `capabilityId` |  是 | -    | Provider 内稳定唯一 ID                              |
| `name`         |  是 | -    | 人类可读名称                                         |
| `description`  |  是 | -    | 能力解决的问题                                        |
| `whenToUse`    |  是 | -    | 适用意图或条件                                        |
| `distinction`  |  否 | 省略   | 与相邻能力的关键区别                                     |
| `examples`     |  否 | `[]` | 简短用例                                           |
| `parents`      |  否 | `[]` | 同 Provider 直接父节点                               |
| `specializes`  |  否 | `[]` | 同 Provider 特化目标                                |
| `related`      |  否 | `[]` | 有方向的显式关联                                       |
| `requires`     |  否 | `[]` | 必要上下文，参与 Selection 闭包；`requiredBy` 只派生，不可写在定义中 |
| `knowledge`    |  否 | `[]` | Document 或 Collection 引用                       |

跨字段约束：关系端点必须存在于同一 Provider，重复端点拒绝；完整收集全部能力后，分别检查 `parents`、`specializes` 和 `requires` 无环；同一 Provider 的 `knowledgeId` 映射身份必须完全一致，Collection 内重复成员拒绝，合法成员排序后判等；单个定义文件最大 262,144 UTF-8 字节。

### Capability 可执行验证用例

| Case ID      | 字段/场景                   | 预期       |
| ------------ | ----------------------- | -------- |
| `DEF-CAP-01` | 最小完整记录                  | 打开成功     |
| `DEF-CAP-02` | 缺少 `capabilityId`       | 拒绝       |
| `DEF-CAP-03` | 非法 `capabilityId`       | 拒绝       |
| `DEF-CAP-04` | Provider 内重复 ID         | 拒绝       |
| `DEF-CAP-05` | 缺少 `name`               | 拒绝       |
| `DEF-CAP-06` | 缺少 `description`        | 拒绝       |
| `DEF-CAP-07` | 缺少 `whenToUse`          | 拒绝       |
| `DEF-CAP-08` | 省略可选集合                  | 使用空集合默认值 |
| `DEF-CAP-09` | 关系端点不存在                 | 拒绝       |
| `DEF-CAP-10` | `parents` 成环            | 拒绝       |
| `DEF-CAP-11` | `specializes` 成环        | 拒绝       |
| `DEF-CAP-12` | 跨 Provider 关系表示         | 拒绝       |
| `DEF-CAP-13` | 不完整知识引用                 | 拒绝       |
| `DEF-CAP-14` | 重复 `knowledgeId`        | 拒绝       |
| `DEF-CAP-15` | 相对路径越出 Provider 根目录     | 拒绝       |
| `DEF-CAP-16` | 定义文件超过 262,144 UTF-8 字节 | 拒绝       |

这些用例同样通过公开 `CapabilityGraph.open()` 执行。

## 身份模型

```ts
interface CanonicalCapabilityId {
  providerId: string;
  capabilityId: string;
}
```

`QualifiedCapabilityId` 是显示字符串，正式分隔符 `QUALIFIED_SEPARATOR` 为 `::`。导出的身份辅助函数包括 `isId()`、`isKnowledgeId()`、`formatQualifiedId()`、`parseQualifiedId()`、`equalId()` 和 `idKey()`。

不绑定 Provider 的查询必须使用完整二元身份。`{ capabilityId }` 短形式只在 `BoundProviderGraph` 中合法。Provider 版本不是身份的一部分。