#建模 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 端到端示例。

#用一个任务验证模型

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

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