BLUEPRINT

第九章：错误处理

9.1 概述

协议定义了统一的错误处理机制，确保技能消费者能够准确理解错误原因并采取适当的恢复措施。

9.2 错误分类

错误类别	错误码	HTTP 状态码	场景
验证错误	VALIDATION_ERROR	N/A（本地）	Schema Validator 检测到无效的技能描述符
认证失败	AUTH_REQUIRED	401	未提供有效凭据调用受保护技能
权限不足	PERMISSION_DENIED	403	凭据有效但无权访问该技能
技能未找到	SKILL_NOT_FOUND	404	请求的技能 ID 或描述符 URL 不存在
调用超时	EXECUTION_TIMEOUT	408 / 504	技能执行超过配置的超时时间
端点不可达	ENDPOINT_UNREACHABLE	502 / 503	调用端点无法连接
版本不兼容	VERSION_INCOMPATIBLE	422	技能描述符的协议版本与消费者不兼容

9.3 统一错误响应格式

所有错误响应遵循统一结构：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "人类可读的错误描述",
    "details": {},
    "retry": {
      "suggested_delay_ms": 0,
      "max_attempts": 0
    }
  }
}

字段说明

字段	类型	必需	说明
`error.code`	string	是	机器可读的错误码
`error.message`	string	是	人类可读的错误描述
`error.details`	object	否	错误的详细上下文信息
`error.retry`	object	否	重试建议
`error.retry.suggested_delay_ms`	number	否	建议的重试延迟（毫秒）
`error.retry.max_attempts`	number	否	建议的最大重试次数

9.4 各类错误详细说明

验证错误

Schema Validator 检测到无效文档时返回：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Skill descriptor validation failed",
    "details": {
      "violations": [
        {
          "field": "/capability_type",
          "expected": "one of: plugin, api, knowledge, task",
          "actual": "unknown_type",
          "message": "Invalid enum value"
        },
        {
          "field": "/endpoint/url",
          "expected": "string (URI format)",
          "actual": null,
          "message": "Required field is missing"
        }
      ]
    }
  }
}

特点：

返回所有违规字段的列表（非仅第一个错误）
每个条目包含字段路径（JSON Pointer 格式）、期望值和实际值

认证失败

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

特点：

包含所需的认证方式说明
帮助消费者自动完成认证流程

调用超时

{
  "error": {
    "code": "EXECUTION_TIMEOUT",
    "message": "Skill execution exceeded the configured timeout of 30000ms",
    "details": {
      "timeout_ms": 30000,
      "elapsed_ms": 30001
    },
    "retry": {
      "suggested_delay_ms": 5000,
      "max_attempts": 3
    }
  }
}

特点：

包含建议的重试延迟和最大重试次数
消费者可据此实现自动重试

端点不可达

{
  "error": {
    "code": "ENDPOINT_UNREACHABLE",
    "message": "Failed to connect to skill endpoint",
    "details": {
      "endpoint_url": "https://api.example.com/skills/translate/invoke",
      "reason": "Connection refused"
    },
    "retry": {
      "suggested_delay_ms": 2000,
      "max_attempts": 5
    }
  }
}

版本不兼容

{
  "error": {
    "code": "VERSION_INCOMPATIBLE",
    "message": "Protocol version 2.0.0 is not compatible with consumer version 1.x",
    "details": {
      "descriptor_version": "2.0.0",
      "consumer_supported_range": "1.x.x",
      "upgrade_url": "https://skill-sharing.org/upgrade-guide"
    }
  }
}

9.5 重试策略

指数退避

对于可重试的错误（超时、端点不可达），推荐使用指数退避策略：

延迟 = initial_delay × 2^(attempt - 1)

示例（initial_delay = 1000ms）：

第 1 次重试：1000ms
第 2 次重试：2000ms
第 3 次重试：4000ms
第 4 次重试：8000ms

不可重试的错误

以下错误不应重试：

VALIDATION_ERROR：需修复描述符
AUTH_REQUIRED：需提供凭据
PERMISSION_DENIED：需获取权限
VERSION_INCOMPATIBLE：需升级消费者