#Provider 与能力声明

你维护的是“已有能力的说明书”。先为每项真实能力分配稳定 ID，写清它适合什么任务，再按需要补使用说明、适用条件、关系和关联材料。Graph 校验这些声明，不扫描源码猜测功能，也不会执行能力。

#先让一项能力可被发现

例如给应用中的请求校验功能建立最小来源，保存为 provider.json：

{
  "providerId": "acme",
  "name": "Acme application",
  "version": "1",
  "capabilities": [
    { "id": "schema", "name": "Request validation", "description": "Validate a JSON request body before the handler runs." }
  ]
}

在已安装本包的项目目录运行 npx --no-install capability-graph validate --file provider.json。这检查声明是否合法，不证明外部框架已经安装或实际校验有效。首次打开和查询步骤见第一个图谱。

#按用户需要逐步补字段

usage 的每个字段都是可选的，消费时要处理缺省，见结果指南。描述“功能很强，支持各种场景”无法判断；“校验JSON请求体，非法输入在进入处理函数前拒绝；不负责身份认证”说明了对象、时机和限制。whenToUse 再补“需要拒绝不符合字段约束的请求时使用”。不要写入未由实际软件验证的承诺。

#目录和详情的可见范围

listCatalog/模型候选目录只包含 id/providerId/name/description 和可选 whenToUse/appliesTo。getCapabilities 或 resolve 的能力详情才包含 usage/relations/documents，且 documents 此时仍只是引用。readDocument 才读取正文；Graph不会在选能力前把usage和长文自动发给模型。

#字段规则

下表中 whenToUse 至 documents 均位于 capabilities[]，不是Provider顶层字段。

查询与返回使用完整身份 providerId::capabilityId。同 Provider 关系可写局部 ID；跨 Provider 关系必须完整 ID。

所有未知定义字段拒绝；AJV 不做强制转换、删除字段或填充数据。内联 JSON 拒绝函数、getter、Proxy、特殊原型、toJSON、循环、稀疏数组和非有限数，不执行输入上的用户函数。

文件组织可为 providers/acme/provider.json 与 providers/acme/knowledge/guide.md。配置显式指向 provider.json；当前不扫描目录、不合并 capabilities 分文件、不执行 JS 配置。

#用同一 Schema 描述不同来源

无需为框架、SDK、Tool、Skill、Workflow新增类型字段。包内 examples/scenarios/provider-patterns.json 给出四项声明模式教学样本，不代表已验证的软件兼容或生产调用代码：

按运行示例复制后，在项目根运行：

npx --no-install capability-graph validate --file examples/scenarios/provider-patterns.json

该命令应成功校验现有Schema。未知 kind/type/tags/callback 等字段拒绝；不要为描述模式伪造新字段。教学URN只用于说明合法引用格式，实际接入须替换为你的真实契约。

#新增与更新的维护步骤

1. 新来源创建独立Provider JSON和唯一providerId；新增能力保留已有ID含义，语义变更评估对调用方的影响。
2. 明确依据的软件/SDK版本、作者和覆盖范围；更新可见目录描述、usage、条件和文档引用，不把Provider.version当Graph版本。
3. 新关系先确认目标ID和授权：跨来源写完整ID，同类非法环或已加载来源中错误目标会在加载时拒绝。
4. 运行CLI validate，再以SDK打开全部相关来源，查询真实ID，检查完整结果；框架实际运行另做消费者验证。
5. 仅更改已配置文件可调用reload并检查ok；新增/删除来源或改变授权需重新open。内联对象按值加载，修改原对象后reload仍读旧副本。

一个Provider目前只有一份声明文件。作者可在自己的构建流程从已知元数据生成这份纯JSON，但Graph不扫描或合并分文件，也不推断源码行为。生命周期解释更新失败与跨请求版本变化。