BLUEPRINT

第六章：调用协议

6.1 概述

调用协议（Invocation Protocol）定义了技能消费者如何远程调用已发现的技能。协议采用异步调用模型，支持状态查询和结果获取。

6.2 调用流程

三步调用模型

步骤	HTTP 方法	端点	说明
1. 发起调用	POST	`{invocation_endpoint}`	提交调用请求，返回执行 ID
2. 查询状态	GET	`{status_url}/{execution_id}`	查询执行状态
3. 获取结果	GET	`{result_url}/{execution_id}`	获取执行结果

调用时序

消费者                              提供者
  │                                  │
  │── POST /invoke ──────────────────→│
  │   {caller, skill_id, inputs}     │
  │                                  │
  │←── 202 Accepted ─────────────────│
  │   {execution_id, status: "accepted"}
  │                                  │
  │── GET /status/{execution_id} ───→│
  │                                  │
  │←── {status: "running"} ──────────│
  │                                  │
  │── GET /status/{execution_id} ───→│
  │                                  │
  │←── {status: "completed"} ────────│
  │                                  │
  │── GET /result/{execution_id} ───→│
  │                                  │
  │←── {output: {...}} ──────────────│
  │                                  │

6.3 调用请求格式

{
  "caller": {
    "id": "ifay-instance-001",
    "type": "ifay",
    "credentials": {
      "api_key": "sk-xxxxx"
    }
  },
  "skill_id": "com.example.translate-v1",
  "inputs": {
    "text": "Hello, world!",
    "target_language": "zh-CN"
  },
  "context": {
    "trace_id": "trace-abc-123",
    "priority": "normal",
    "timeout_ms": 30000
  }
}

请求字段

字段	类型	必需	说明
`caller`	object	是	调用者身份信息
`caller.id`	string	是	调用者唯一标识
`caller.type`	string	是	调用者类型（ifay/service/user）
`caller.credentials`	object	否	认证凭据
`skill_id`	string	是	目标技能 ID
`inputs`	object	是	输入参数（键值对）
`context`	object	否	调用上下文
`context.trace_id`	string	否	追踪 ID
`context.priority`	string	否	优先级（low/normal/high）
`context.timeout_ms`	number	否	超时时间（毫秒）

6.4 调用响应格式

{
  "execution_id": "exec-789-xyz",
  "status": "completed",
  "skill_id": "com.example.translate-v1",
  "output": {
    "translated_text": "你好，世界！",
    "source_language": "en",
    "target_language": "zh-CN",
    "confidence": 0.98
  },
  "timestamps": {
    "created_at": "2025-03-20T14:30:00Z",
    "updated_at": "2025-03-20T14:30:02Z",
    "completed_at": "2025-03-20T14:30:02Z"
  }
}

响应字段

字段	类型	必需	说明
`execution_id`	string	是	执行唯一标识
`status`	ExecutionStatus	是	执行状态
`skill_id`	string	是	目标技能 ID
`output`	any	否	输出数据（completed 时）
`error`	object	否	错误信息（failed/timeout 时）
`timestamps`	object	是	时间戳信息

执行状态枚举

状态	说明
`accepted`	请求已接收，等待执行
`running`	正在执行中
`completed`	执行成功完成
`failed`	执行失败
`timeout`	执行超时

6.5 认证流程

调用前，消费者需检查技能描述符中的 auth 字段：

消费者                              提供者
  │                                  │
  │── 读取 descriptor.auth ──→       │
  │                                  │
  │   auth.type == "api_key"?        │
  │   → 在 Header 中附加 API Key     │
  │                                  │
  │   auth.type == "oauth2"?         │
  │   → 执行 OAuth 2.0 流程获取 Token │
  │                                  │
  │   auth.type == "none"?           │
  │   → 直接调用，无需凭据            │
  │                                  │
  │── POST /invoke (附带凭据) ───────→│
  │                                  │

认证失败响应

未提供有效凭据时，返回 401 错误：

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication is required to invoke this skill",
    "details": {
      "required_auth_type": "oauth2",
      "authorization_url": "https://example.com/oauth/authorize"
    }
  }
}

6.6 超时与重试

超时处理

当技能执行超过配置的 timeout_ms 时：

{
  "execution_id": "exec-789-xyz",
  "status": "timeout",
  "skill_id": "com.example.translate-v1",
  "error": {
    "code": "EXECUTION_TIMEOUT",
    "message": "Skill execution exceeded the configured timeout of 30000ms",
    "retry": {
      "suggested_delay_ms": 5000,
      "max_attempts": 3
    }
  },
  "timestamps": {
    "created_at": "2025-03-20T14:30:00Z",
    "updated_at": "2025-03-20T14:30:30Z"
  }
}

重试策略

超时响应中包含建议的重试延迟和最大重试次数
消费者应实现指数退避重试策略
端点不可达时，建议使用指数退避（初始延迟 × 2^n）