第五章：發現機制

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