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, and this page is available as Markdown at https://devcodex-labs.github.io/capability-graph/concepts/capability-identity.md.

身份与关系

可用

规范身份是:

{ 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 有三种作者声明的正向关系和三种查询时生成的反向投影:

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

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

关系端点必须属于同一 Provider。跨 Provider 组合发生在 Agent 任务层,而不是写入 V1 正式图。实践见 设计关系

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