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