BLUEPRINT
제3장: 아키텍처 설계
3.1 전체 아키텍처
프로토콜은 탈중앙화된 Provider-Consumer 아키텍처를 채택하며, 웹의 하이퍼링크 발견 모델과 P2P 네트워크의 노드 발견 메커니즘과 유사합니다.
┌─────────────────────────────────────────────────────────┐
│ 스킬 제공자 도메인 (Provider Domain) │
│ │
│ ┌──────────────────────────┐ │
│ │ /.well-known/skill-sharing│ │
│ └────────┬─────────────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ ▼ ▼ │
│ ┌──────┐ ┌──────┐ │
│ │디스크A│ │디스크B│ │
│ └──┬───┘ └──┬───┘ │
│ ▼ ▼ │
│ ┌──────┐ ┌──────┐ │
│ │엔드 A │ │엔드 B │ │
│ └──────┘ └──────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ 스킬 소비자 (iFay) │
│ │
│ ┌────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │Discovery │→ │Schema │→ │Invocation │ │
│ │Client │ │Validator │ │Client │ │
│ └────────────┘ └──────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ 선택사항: 스킬 레지스트리 (Skill Registry) │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Registry Index │ │
│ │ (인덱스 참조 → 각 제공자 도메인의 디스크립터)│ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
3.2 프로토콜 상호작용 흐름
단계 1: 스킬 발견
스킬 소비자 (iFay) 스킬 제공자
│ │
│── GET /.well-known/skill-sharing ─→│
│ │
│←── 스킬 인덱스 (Skill Index) ─────│
│ │
│── Schema Validator 파싱·검증 ──→ │
│ │
단계 2: 스킬 호출
스킬 소비자 (iFay) 스킬 제공자
│ │
│── POST {invocation_endpoint} ────→│
│ (호출 요청) │
│ │
│←── 202 Accepted ─────────────────│
│ (확인 응답 + 실행 ID) │
│ │
│── GET {status_endpoint}/{id} ────→│
│ │
│←── 실행 상태 ────────────────────│
│ (진행 중/완료/실패) │
│ │
│── GET {result_endpoint}/{id} ────→│
│ │
│←── 실행 결과 ────────────────────│
│ │
3.3 3가지 발견 경로
| 경로 | 방식 | 설명 | 적용 시나리오 |
|---|---|---|---|
| Well-Known URI | GET /.well-known/skill-sharing | 주요 발견 방식. 도메인 하위의 모든 스킬 인덱스를 반환 | 제공자의 전체 스킬 탐색 |
| 직접 URL | GET {skill_descriptor_url} | Skill Descriptor 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 Validator
├── discovery.ts # 디스커버리 메커니즘 로직
├── invocation.ts # 호출 프로토콜 로직
└── version.ts # 버전 관리 로직
3.5 컴포넌트 책임
Discovery Client(발견 클라이언트)
탈중앙화 네트워크에서 Skill Descriptor를 위치 확인하는 책임:
- Well-Known URI에 요청을 보내 스킬 인덱스 획득
- 직접 URL로 알려진 Skill Descriptor 획득
- 레지스트리를 통한 일괄 검색
- 능력 유형 기반 필터링 쿼리 지원
Schema Validator
Skill Descriptor의 준수성을 검증하는 책임:
- schema.json을 사용하여 Skill Descriptor 문서 검증
- 유효한 문서를 구조화된 Skill Descriptor 객체로 파싱
- 무효한 문서에 대해 구체적인 위반 필드와 이유 반환
- Skill Descriptor 객체의 Pretty Print JSON 직렬화 지원
Invocation Client(호출 클라이언트)
발견된 스킬의 원격 호출 담당:
- 표준화된 호출 요청 구성
- 인증 흐름 처리
- 실행 상태 쿼리 관리
- 타임아웃 및 오류 응답 처리