能力 Registry

统一目录，不强行统一所有能力形态

Model、Tool/MCP、Skill 与 Agent 可以共享身份、版本、Owner、风险和生命周期外壳，但消费契约不同。Model 关注模态、上下文、区域、价格和评测；Tool/MCP 关注输入输出 Schema、副作用、授权和幂等；Skill 关注触发、步骤、依赖和产物；Agent 关注任务能力、协议、异步状态与 SLO。统一目录不等于让四者共用一套稀疏字段。

MCP 2025-06-18 Tools 规范定义了工具发现、调用和列表变化通知；A2A 规范通过 Agent Card 描述 Agent 能力与安全方案。两者是互操作事实来源，但企业 Registry 还要叠加 Owner、租户准入、风险、成本和内部生命周期，不能直接把远端声明当批准记录。

Registry 保存控制面快照；实时延迟、错误率和熔断状态由运行系统产生，以引用或短 TTL 投影进入发现结果。Backstage 官方也明确提醒 Catalog 更适合作为汇聚和缓存层，而非所有动态关系的最终真源。这个边界能避免一次健康采集故障改写治理元数据。

每项能力的最小治理元数据

稳定 ID 不随名称、Owner 或部署地址变化；版本标识契约，而环境和 Endpoint 是部署实例。每项能力至少包含类型、语义描述、版本与兼容范围、环境和状态、Owner 与支持渠道、SLO 与成本、权限需求、数据分类、风险、地域、依赖、健康引用和替代能力。

// 教学用 TypeScript 契约，省略各类型的完整专有字段
interface CapabilityRecord {
  id: string;
  kind: 'model' | 'tool' | 'mcp-server' | 'skill' | 'agent';
  contractVersion: string;
  lifecycle: 'draft' | 'review' | 'approved' | 'limited' |
    'general' | 'deprecated' | 'retired';
  owner: { teamId: string; support: string };
  governance: {
    risk: 'low' | 'medium' | 'high';
    dataClasses: string[];
    regions: string[];
    requiredScopes: string[];
  };
  dependencies: Array<{ id: string; versionRange: string }>;
  healthRef: string;
  evidenceRefs: string[];
}

元数据字段必须标明权威来源和新鲜度。例如 Owner 来自组织目录，价格来自 Gateway/成本系统，SLO 来自服务契约，健康来自监控，评测来自发布流水线。允许 Owner 在 Git 流程中维护描述，不代表其可以自我批准高风险状态。

从申请到退役的状态机

生命周期既控制可发现范围，也控制谁可以调用。draft 仅 Owner 可见；review 进入契约、安全和评测检查；approved 表示治理准入通过但未承诺规模；limited 面向白名单和受限容量；general 面向目标用户群并承担 SLO；deprecated 只允许存量和迁移；retired 从发现结果移除并拒绝新调用。

状态变化由可验证条件驱动。Tool Schema 破坏性变化、权限扩大、数据分类提高、Owner 变化或供应链来源变化，都应回到相应审查。无人 Owner、长期不健康、依赖已退役或没有活跃消费方的能力进入治理队列，但自动化不应在没有影响分析时直接删除。

版本策略围绕契约兼容，而不是围绕部署次数。非破坏性元数据更新可以复用版本；输入输出、权限、副作用或完成语义变化需要新契约版本。运行 Trace 固定能力 ID 与版本，避免“同名最新版本”使历史不可复现。

发现到能力不等于可以信任

准入要验证来源与运行身份、代码或服务供应链、Schema、权限、副作用、数据边界、最低可靠性、Trace 和支持责任。第三方能力声明只能作为输入；平台需要验证签名、域名控制、发布者、依赖与实际 Endpoint 身份，并按租户、场景和权限限制。

A2A Agent Card 可以声明安全方案，MCP Tool 可以暴露注解，但声明不是执行授权。Registry 记录“该能力要求哪些凭据和范围”；运行时 Policy 根据当前用户、租户、资源、参数和环境作决定；Executor 在目标入口执行。三者分离后，即使目录缓存过期，也不会自动扩大权限。

同时服务人、Agent 与平台

发现分两步：先用租户、身份、环境、生命周期、数据地域和能力类型做确定性过滤，再在允许集合内做语义匹配与排序。这样能避免向模型泄露无权知道的能力描述，也避免向量检索把“近义但受限”的 Tool 排到前面。

列表接口返回稳定 ID、版本、短描述、风险摘要和获取完整契约的引用。只有进入候选集的少量能力才加载完整 Schema，减少 Context 成本。响应包含 Registry 修订号、能力版本、政策适用范围和过期时间；客户端缓存必须按租户与身份边界分区。

MCP 的列表变化通知提供了“能力集合已变化”的协议信号，但客户端仍需重新拉取并检查版本，不能把通知本身当完整变更。大规模目录采用修订号加增量变更流，同时保留周期性全量校准，以修复漏通知和消费者离线。

能力图支持变更影响分析

依赖边要说明来源能力、目标能力、版本范围、用途、是否运行时必需，以及最后一次观测。声明依赖用于发布前分析，运行 Trace 用于确认真实消费；两者不能互相替代。仅有 Trace 会漏掉低频和备用路径，仅有声明会保留已经消失的关系。

退役计划必须给出替代能力、兼容差异、迁移截止、支持 Owner 和阻断日期。到期前同时观察声明依赖、实际调用和未完成 Run；只有消费归零或例外获批，才进入 retired。事故中的紧急禁用要与正常退役分离，它优先止损，但仍需保留决定、影响面和恢复条件。

目录自身也需要运营指标

Registry 的产品目标是缩短可信能力的发现与变更时间，而不是最大化条目数。目录质量看无 Owner、重复/近义、过期健康、缺失风险、版本漂移和已退役仍被调用；发现质量看成功率、误选率、无结果率、完整契约加载量和从发现到首次成功调用的 Lead Time。

分类实践应选一个 Model、一个有副作用 Tool、一个 Skill 和一个远程 Agent，完成元数据登记、准入、发现、调用授权、破坏性变更和紧急禁用演练。证据包括 Schema、审查决定、发现响应、Trace、依赖影响清单、迁移记录和最终消费归零，而不是四张目录截图。