规范

5. 发现机制

5.1 概述

发现机制定义了技能消费者如何在去中心化网络中定位和获取 Skill Descriptor。本协议定义三种互补的发现路径：Well-Known URI、直接 URL 和注册表查询。

5.2 Well-Known URI 发现

5.2.1 路径规范

技能提供者 MUST 在其域名根路径下暴露以下路径：

/.well-known/skill-sharing

该路径遵循 RFC 8615 Well-Known URI 规范。

5.2.2 请求格式

GET /.well-known/skill-sharing HTTP/1.1
Host: example.com
Accept: application/json

5.2.3 响应格式：Skill Index

成功响应 MUST 返回 HTTP 200 状态码，并包含一个 Skill Index JSON 文档。

interface SkillIndex {
  protocol: ProtocolVersion;        // 必需
  provider: ProviderInfo;           // 必需
  skills: SkillIndexEntry[];        // 必需，可为空数组
}

interface SkillIndexEntry {
  id: string;                       // 必需
  name: string;                     // 必需
  capability_type: CapabilityType;  // 必需
  description: string;              // 必需
  descriptor_url: string;           // 必需，完整描述符 URL
  access: AccessPolicy;             // 必需
  version: string;                  // 必需，技能版本
}

5.2.4 索引示例

{
  "protocol": {
    "version": "1.0.0"
  },
  "provider": {
    "name": "Example Corp",
    "url": "https://example.com"
  },
  "skills": [
    {
      "id": "com.example.translate-v1",
      "name": "Universal Translator",
      "capability_type": "api",
      "description": "高质量文本翻译服务",
      "descriptor_url": "https://example.com/skills/translate/descriptor.json",
      "access": "restricted",
      "version": "2.1.0"
    }
  ]
}

5.3 直接 URL 发现

当消费者已知 Skill Descriptor 的完整 URL 时 MAY 直接获取：

GET https://example.com/skills/translate/descriptor.json HTTP/1.1
Accept: application/json

响应 MUST 是一个完整的 Skill Descriptor JSON 文档。

5.4 注册表发现（可选）

注册表 MAY 提供按能力类型筛选的查询接口：

GET {registry_url}/skills?type={capability_type}

响应格式与 Skill Index 中的 skills 数组一致。

5.5 能力类型筛选

Well-Known URI 端点 SHOULD 支持通过查询参数 type 筛选：

GET /.well-known/skill-sharing?type=api

筛选规则：

结果集中每个条目的 capability_type MUST 等于查询值
原始集合中所有匹配该类型且对当前请求可见的技能 MUST 出现在结果中
筛选 MUST NOT 影响访问控制规则

5.6 标识符唯一性

在同一个 Skill Index 中，所有 id 字段值 MUST 互不相同。如果存在重复，提供者 MUST 视为配置错误并修复。