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

# 身份与关系

可用

规范身份是：

```ts
{ providerId: 'acme.http', capabilityId: 'route.validation' }
```

可逆显示形式为 `acme.http::route.validation`。`::` 是正式分隔符；不能按点号猜 Provider 和 Capability 的边界。

`capabilityId` 只在所属 Provider 内唯一。查询必须已经绑定 Provider，或传入完整二元身份。正式关系边只能连接同一 Provider 内的节点。

## 演进规则

身份表达概念连续性。如果能力语义发生不兼容替换，Provider 作者必须使用新 ID。Core 不会识别“保留旧 ID 但暗中变义”，也不会把旧候选、向量、缓存、Runtime `instanceOf` 或知识映射自动绑定到新身份。

辅助函数 `formatQualifiedId()` 和 `parseQualifiedId()` 用于可逆显示，不要自行拼接或拆分。

## 关系模型

能力关系用于表达静态能力之间的明确语义。Capability Graph 有三种作者声明的正向关系和三种查询时生成的反向投影：

| 正向            | 反向              | 含义       | 环规则                |
| ------------- | --------------- | -------- | ------------------ |
| `parents`     | `children`      | 分类或组成层级  | `parents` 图必须是 DAG |
| `specializes` | `specializedBy` | 更具体的语义变体 | `specializes` 图无环  |
| `related`     | `relatedBy`     | 有方向的显式关联 | 允许循环和双向声明          |

`related` 不自动补反向边；`relatedBy` 只是查询投影。命名层级、共同前缀和 Runtime `instanceOf` 都不会生成静态边。

关系端点必须属于同一 Provider。跨 Provider 组合发生在 Agent 任务层，而不是写入 V1 正式图。实践见 [设计关系](https://devcodex-labs.github.io/capability-graph/guides/design-relations.md)。

例如 Acme 扩展示例中，`route.validation.parents = ['route']` 表示验证归属路由族，`related = ['schema.request']` 提示可以配合请求 Schema。查询 `route` 的 `children` 可发现验证能力，但不会自动选择它的知识。另一个 Provider 即使也叫 `route.validation`，仍是不同身份，不能用本 Provider 的边指向它。