> 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

可用

## 1. 冻结 Provider 边界

先写清 Provider 拥有哪些能力、由哪个权威来源维护，以及哪些执行、认证和规范职责留在接入层。不要用一个 Provider 混合没有共同版本和所有权的系统。

## 2. 选择稳定身份

为 Provider 和能力选择稳定、Provider 内唯一的 ID。概念替换使用新 ID，不用改描述掩盖不兼容语义。

## 3. 建立平坦目录

先为每个可独立选择的能力填写 `description`、`whenToUse` 和 `distinction`。用真实用户意图验证第一轮目录是否足以区分主能力。

### 选择能力粒度

把候选概念建模为独立能力前，回答四个问题：

1. Agent 是否会在真实任务中单独选择它？
2. 它是否有不同于相邻能力的 `whenToUse` 或限制？
3. 它能否在不改变身份语义的情况下独立演进？
4. 详情、关系或知识是否能帮助后续选择？

如果答案多数为否，它更可能是字段、参数或实现细节。不要把每个函数、HTTP 路由实例或配置键建成 Static Capability。反过来，一个节点若同时包含多个互斥意图，目录会失去判别力。拆分时保留主能力，再用 `parents` 或 `specializes` 表达真实结构。

用至少三个相邻能力做首轮目录评审：只看 `name`、`description`、`whenToUse` 和 `distinction`，评审者应能稳定选中目标。不能靠读详情猜出区别时，先修正文案或粒度。

## 4. 添加显式关系

只声明能解释的 `parents`、`specializes`、`related` 和 `requires`。端点必须存在于同一 Provider；不要从名称或文件夹推导边。`requires` 表达任务必需的上下文，会进入 Selection 闭包，不要用它泛化弱关联。

## 5. 关联知识和 Runtime

本地文档使用 `relative-file`；需要检索或远程读取时配置相应 Adapter。Runtime 由独立 Adapter 观察，不把实例写成静态节点。

## 6. 从公共入口验证

使用 `CapabilityGraph.open()` 加载真实目录，执行目录、详情、关系、知识和负向 Fixture。直接调用内部校验函数不足以证明接入可用。

参考可运行定义：[Seed 端到端示例](https://devcodex-labs.github.io/capability-graph/examples/seed-provider.md)。

## 用一个任务验证模型

对“给现有 `POST /users` 增加请求校验”，先仅展示候选摘要，检查能否区分以下概念：

| 候选             | 是否建成静态能力             | 原因                 |
| -------------- | -------------------- | ------------------ |
| HTTP 路由注册      | 是，`route.http`       | 可独立选择，有自己的步骤和限制    |
| 路由请求校验         | 是，`route.validation` | 意图不同，不能只靠路由注册详情猜测  |
| 请求 Schema      | 是，`schema.request`   | 声明结构与执行校验职责不同      |
| `POST /users`  | 否，作为 Runtime 实例      | 随项目和环境变化，不是框架的稳定能力 |
| 配置中的一个 boolean | 通常否                  | 多数只是某能力的参数，无独立发现价值 |

预期调用方先选验证，再根据显式关系决定是否需要 Schema，最后读取已选知识。若必须读完所有正文才知道选哪个，先修改 `whenToUse`/`distinction`；若 `open()` 成功但业务分类错误，Core 校验不会代替这一轮语义评审。确认粒度后进入[设计关系](https://devcodex-labs.github.io/capability-graph/guides/design-relations.md)。