第五章：发现机制

5.1 概述

发现机制（Discovery Mechanism）定义了技能消费者如何在去中心化网络中定位和获取技能描述符。协议提供三种互补的发现路径，确保灵活性和可扩展性。

5.2 Well-Known URI 发现

路径规范

技能提供者在其域名下暴露标准化路径：

GET https://{domain}/.well-known/skill-sharing

响应格式：技能索引（Skill Index）

{
  "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": "支持 100+ 语言的高质量文本翻译服务",
      "descriptor_url": "https://example.com/skills/translate/descriptor.json",
      "access": "restricted",
      "version": "2.1.0"
    },
    {
      "id": "com.example.sentiment-v1",
      "name": "Sentiment Analyzer",
      "capability_type": "api",
      "description": "文本情感分析服务",
      "descriptor_url": "https://example.com/skills/sentiment/descriptor.json",
      "access": "public",
      "version": "1.0.0"
    }
  ]
}

技能索引字段

字段	类型	必需	说明
protocol	ProtocolVersion	是	协议版本
provider	object	是	提供者信息
provider.name	string	是	提供者名称
provider.url	string	否	提供者网站
skills	SkillIndexEntry[]	是	技能列表

技能索引条目字段

字段	类型	必需	说明
id	string	是	技能唯一标识符
name	string	是	技能名称
capability_type	CapabilityType	是	能力类型
description	string	是	简短描述
descriptor_url	string	是	完整描述符 URL
access	AccessPolicy	是	访问控制策略
version	string	是	技能版本

5.3 直接 URL 发现

当消费者已知技能描述符的完整 URL 时，可直接获取：

GET https://example.com/skills/translate/descriptor.json

响应为完整的 Skill Descriptor JSON 文档。

5.4 注册表发现（可选）

技能注册表是可选的索引服务，用于加速跨域技能发现。注册表不是协议运行的必要条件。

查询接口

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

响应格式

返回匹配的技能描述符引用列表，格式与技能索引条目一致。

5.5 访问控制与发现

发现机制与访问控制策略紧密关联：

访问策略	未认证发现	认证后发现	调用
public	✓ 可见	✓ 可见	无需认证
restricted	✓ 可见	✓ 可见	需要认证
private	✗ 不可见	✓ 可见	需要认证

关键规则：

• 当未认证请求访问 Well-Known URI 时，返回的技能索引不包含任何 access 为 private 的技能
• 认证后的请求可以看到所有技能（包括 private）

5.6 能力类型过滤

消费者可以按能力类型过滤技能：

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

过滤规则：

• 结果集中每个技能的 capability_type 等于过滤值
• 原始集合中所有匹配该类型的技能都出现在结果中
• 过滤不影响访问控制规则（private 技能仍然对未认证请求不可见）

5.7 技能标识符唯一性

在同一个技能索引中，所有技能的 id 字段值必须互不相同。推荐的 ID 格式：

{reverse_domain}.{skill_name}-v{major_version}

示例：

• com.example.translate-v1
• org.openai.gpt4-v1
• io.github.user.code-review-v2