BLUEPRINT
第三章：架構設計
3.1 整體架構
協定採用去中心化的 Provider-Consumer 架構，類似於 Web 的超連結發現模型和 P2P 網路的節點發現機制。
┌─────────────────────────────────────────────────────────┐
│ 技能提供者域 (Provider Domain) │
│ │
│ ┌──────────────────────────┐ │
│ │ /.well-known/skill-sharing│ │
│ └────────┬─────────────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ ▼ ▼ │
│ ┌──────┐ ┌──────┐ │
│ │描述符A│ │描述符B│ │
│ └──┬───┘ └──┬───┘ │
│ ▼ ▼ │
│ ┌──────┐ ┌──────┐ │
│ │端點 A │ │端點 B │ │
│ └──────┘ └──────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ 技能消費者 (iFay) │
│ │
│ ┌────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │Discovery │→ │Schema │→ │Invocation │ │
│ │Client │ │Validator │ │Client │ │
│ └────────────┘ └──────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ 可選：技能註冊表 (Skill Registry) │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Registry Index │ │
│ │ (索引參照 → 各提供者域的描述符) │ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
3.2 協定互動流程
階段一：技能發現
技能消費者 (iFay) 技能提供者
│ │
│── GET /.well-known/skill-sharing ─→│
│ │
│←── 技能描述符索引 (Skill Index) ───│
│ │
│── Schema Validator 解析驗證 ──→ │
│ │
階段二：技能呼叫
技能消費者 (iFay) 技能提供者
│ │
│── POST {invocation_endpoint} ────→│
│ (呼叫請求) │
│ │
│←── 202 Accepted ─────────────────│
│ (確認回應 + 執行ID) │
│ │
│── GET {status_endpoint}/{id} ────→│
│ │
│←── 執行狀態 ─────────────────────│
│ (進行中/已完成/失敗) │
│ │
│── GET {result_endpoint}/{id} ────→│
│ │
│←── 執行結果 ─────────────────────│
│ │
3.3 三種發現路徑
| 路徑 | 方式 | 說明 | 適用情境 |
|---|---|---|---|
| Well-Known URI | GET /.well-known/skill-sharing | 主要發現方式，回傳網域下所有技能的索引 | 探索某個提供者的全部技能 |
| 直接 URL | GET {skill_descriptor_url} | 已知技能描述符 URL 時直接取得 | 已知具體技能位址 |
| 註冊表查詢 | GET {registry_url}/skills?type={type} | 可選，透過註冊表批次檢索 | 按類型搜尋技能 |
3.4 檔案組織架構
project-root/
├── docs/
│ ├── en/ # 基準語言（英語）
│ │ ├── specification/
│ │ │ ├── 2025-11-25/ # 版本化文件
│ │ │ └── draft/ # 草稿文件
│ │ ├── blueprint/ # 藍圖文件
│ │ ├── community/ # 社群文件
│ │ ├── develop/ # 開發指南
│ │ └── sdk/ # SDK 文件
│ ├── zh-CN/ # 簡體中文（同上結構）
│ ├── zh-TW/ # 繁體中文
│ ├── ja/ # 日語
│ ├── ko/ # 韓語
│ ├── de/ # 德語
│ ├── fr/ # 法語
│ ├── es/ # 西班牙語
│ └── ru/ # 俄語
├── schema/
│ ├── draft/ # 草稿 Schema
│ │ ├── schema.json # JSON Schema (Draft 2020-12)
│ │ ├── schema.ts # TypeScript 型別定義
│ │ └── schema.mdx # MDX 互動式文件
│ └── 2025-10-25/ # 版本化 Schema
│ ├── schema.json
│ ├── schema.ts
│ └── schema.mdx
└── src/ # 工具原始碼
├── validator.ts # Schema 驗證器
├── discovery.ts # 發現機制邏輯
├── invocation.ts # 呼叫協定邏輯
└── version.ts # 版本管理邏輯
3.5 元件職責
Discovery Client（發現用戶端）
負責在去中心化網路中定位技能描述符：
- 向 Well-Known URI 發起請求取得技能索引
- 透過直接 URL 取得已知技能描述符
- 透過註冊表進行批次檢索
- 支援基於能力類型的篩選查詢
Schema Validator（Schema 驗證器）
負責驗證技能描述符的合規性：
- 使用 schema.json 驗證技能描述符文件
- 解析有效文件為結構化 Skill Descriptor 物件
- 對無效文件回傳具體違規欄位和原因
- 支援將 Skill Descriptor 物件序列化為 Pretty Print JSON
Invocation Client（呼叫用戶端）
負責遠端呼叫已發現的技能：
- 建構標準化的呼叫請求
- 處理認證流程
- 管理執行狀態查詢
- 處理逾時和錯誤回應