BLUEPRINT

第四章：技能描述符

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"]

plugin：可嵌入的功能模組
api：遠端服務介面
knowledge：結構化知識資源
task：人類或 iFay 可執行的任務

AccessPolicy（存取控制策略）

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

public：公開，任何人可發現和呼叫
restricted：受限，可被發現但呼叫需認證
private：私有，未認證時不可被發現

AuthType（認證方式）

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

4.4 子結構定義

ProtocolVersion（協定版本）

{
  "version": "1.0.0",
  "changelog_url": "https://example.com/changelog"
}

version（必要）：SemVer 格式的協定版本號
changelog_url（選用）：版本變更日誌 URL

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
  }
}

ParameterDefinition（參數定義）

{
  "name": "text",
  "type": "string",
  "description": "要翻譯的文字",
  "required": true,
  "default": null,
  "schema": { "minLength": 1, "maxLength": 10000 }
}

AuthConfig（認證設定）

API Key 認證範例：

{
  "type": "api_key",
  "description": "透過 HTTP Header 傳遞 API Key",
  "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": "讀取技能資訊"
    }
  }
}

OutputDefinition（輸出格式）

{
  "content_type": "application/json",
  "schema": {
    "type": "object",
    "properties": {
      "translated_text": { "type": "string" },
      "source_language": { "type": "string" },
      "target_language": { "type": "string" }
    }
  },
  "description": "翻譯結果，包含譯文和語言資訊"
}

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": "透過 X-API-Key header 傳遞金鑰",
    "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"
}