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（调用客户端）

负责远程调用已发现的技能：

构造标准化的调用请求
处理认证流程
管理执行状态查询
处理超时和错误响应