Глава 4: Дескриптор Навыка

4.1 Обзор

Skill Descriptor — это центральная структура данных протокола, существующая как JSON-документ, полностью описывающий метаданные навыка. Он служит контрактом между провайдерами и потребителями навыков.

4.2 Полные Определения Полей

Обязательные Поля

Поле	Тип	Описание
protocol	ProtocolVersion	Информация о версии протокола
id	string	Уникальный идентификатор навыка
name	string	Название навыка
version	string	Версия навыка (формат SemVer)
capability_type	CapabilityType	Тип возможности
description	string	Описание навыка
provider	object	Информация о провайдере
endpoint	InvocationEndpoint	Конфигурация точки вызова
inputs	ParameterDefinition[]	Определения входных параметров
output	OutputDefinition	Определение формата вывода
auth	AuthConfig	Конфигурация аутентификации
access	AccessPolicy	Политика контроля доступа

Необязательные Поля

Поле	Тип	Описание
tags	string[]	Теги (для поиска и классификации)
documentation_url	string	URL документации навыка
created_at	string	Время создания (ISO 8601)
updated_at	string	Время обновления (ISO 8601)

4.3 Перечислимые Типы

CapabilityType

["plugin", "api", "knowledge", "task"]

AccessPolicy

["public", "restricted", "private"]

AuthType

["api_key", "oauth2", "custom", "none"]

4.4 Определения Подструктур

InvocationEndpoint

{
  "url": "https://example.com/skills/translate/invoke",
  "method": "POST",
  "content_type": "application/json",
  "status_url": "https://example.com/skills/translate/status/{execution_id}",
  "result_url": "https://example.com/skills/translate/result/{execution_id}",
  "timeout_ms": 30000,
  "retry": { "max_attempts": 3, "backoff_ms": 1000 }
}

AuthConfig

Пример API Key:

{ "type": "api_key", "description": "Передать API Key через HTTP Header", "header": "X-API-Key" }

Пример OAuth 2.0:

{
  "type": "oauth2",
  "oauth2": {
    "authorization_url": "https://example.com/oauth/authorize",
    "token_url": "https://example.com/oauth/token",
    "scopes": { "skill:invoke": "Вызов навыка", "skill:read": "Чтение информации о навыке" }
  }
}

4.5 Полный Пример

{
  "protocol": { "version": "1.0.0", "changelog_url": "https://skill-sharing.org/changelog" },
  "id": "com.example.translate-v1",
  "name": "Universal Translator",
  "version": "2.1.0",
  "capability_type": "api",
  "description": "Высококачественный сервис перевода текста с поддержкой 100+ языков",
  "provider": { "name": "Example Corp", "url": "https://example.com", "contact": "skills@example.com" },
  "endpoint": {
    "url": "https://api.example.com/skills/translate/invoke",
    "method": "POST",
    "content_type": "application/json",
    "status_url": "https://api.example.com/skills/translate/status/{execution_id}",
    "result_url": "https://api.example.com/skills/translate/result/{execution_id}",
    "timeout_ms": 30000,
    "retry": { "max_attempts": 3, "backoff_ms": 1000 }
  },
  "inputs": [
    { "name": "text", "type": "string", "description": "Текст для перевода", "required": true, "schema": { "minLength": 1, "maxLength": 10000 } },
    { "name": "target_language", "type": "string", "description": "Код целевого языка (ISO 639-1)", "required": true },
    { "name": "source_language", "type": "string", "description": "Код исходного языка (пусто для автоопределения)", "required": false, "default": "auto" }
  ],
  "output": {
    "content_type": "application/json",
    "schema": { "type": "object", "properties": { "translated_text": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "confidence": { "type": "number" } } },
    "description": "Результат перевода"
  },
  "auth": { "type": "api_key", "description": "Передать ключ через header X-API-Key", "header": "X-API-Key" },
  "access": "restricted",
  "tags": ["translation", "nlp", "multilingual"],
  "documentation_url": "https://docs.example.com/skills/translate",
  "created_at": "2025-01-15T08:00:00Z",
  "updated_at": "2025-03-20T14:30:00Z"
}