规范总览

版本信息

关键词说明

规范中的关键词 MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、RECOMMENDED、MAY、OPTIONAL 按 RFC 2119 和 RFC 8174 解释。

命名空间治理

UCP 使用反向域名编码治理权威：

命名格式 

{reverse-domain}.{service}.{capability}
组件说明示例
{reverse-domain}权威标识符dev.ucp、com.example
{service}服务/垂直类别shopping、common
{capability}具体能力名称checkout、identity_linking

权威映射表

命名空间权威方Spec URL 要求
dev.ucp.*ucp.devhttps://ucp.dev/...
com.example.*example.comhttps://example.com/...

验证要求：平台 MUST 验证 capability spec URL 的来源与命名空间权威方匹配。

命名示例

名称权威方服务能力
dev.ucp.shopping.checkoutucp.devshoppingcheckout
dev.ucp.common.identity_linkingucp.devcommonidentity_linking
com.example.payments.installmentsexample.compaymentsinstallments

Service（服务）定义

Service 定义 API 表面和传输绑定：

字段必填说明
version是服务版本（YYYY-MM-DD 格式）
spec是服务文档 URL
rest.schemaREST 绑定时必填OpenAPI 3.x 规范 URL
rest.endpointREST 绑定时必填REST 端点 URL
mcp.schemaMCP 绑定时必填OpenRPC 规范 URL
mcp.endpointMCP 绑定时必填MCP 端点 URL
a2a.endpointA2A 绑定时必填Agent Card URL
embedded.schemaEmbedded 绑定时必填OpenRPC 规范 URL

端点解析规则

OpenAPI 路径直接追加到 endpoint：

endpoint: https://business.example.com/ucp/v1
path: /checkout-sessions
结果: POST https://business.example.com/ucp/v1/checkout-sessions

Capability（能力）定义

Capability 是 Service 内的功能特性：

字段必填说明
name是能力名称（反向域名格式）
version是能力版本（YYYY-MM-DD 格式）
spec是规范文档 URL
schema是JSON Schema URL
extends否父能力名称（用于扩展）

Extension（扩展）定义

Extension 是可选的能力增强模块：

{
  "name": "dev.ucp.shopping.fulfillment",
  "version": "2026-01-11",
  "spec": "https://ucp.dev/specification/fulfillment",
  "schema": "https://ucp.dev/schemas/shopping/fulfillment.json",
  "extends": "dev.ucp.shopping.checkout"
}

Profile（配置文件）结构

Business Profile

发布在 https://business.example.com/.well-known/ucp：

{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/overview",
        "rest": {
          "schema": "https://ucp.dev/services/shopping/rest.openapi.json",
          "endpoint": "https://business.example.com/ucp/v1"
        }
      }
    },
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/checkout",
        "schema": "https://ucp.dev/schemas/shopping/checkout.json"
      },
      {
        "name": "dev.ucp.shopping.fulfillment",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/fulfillment",
        "schema": "https://ucp.dev/schemas/shopping/fulfillment.json",
        "extends": "dev.ucp.shopping.checkout"
      }
    ]
  },
  "payment": {
    "handlers": [...]
  },
  "signing_keys": [...]
}

Platform Profile 

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [...]
  },
  "payment": {
    "handlers": [...]
  },
  "signing_keys": [...]
}

平台声明机制

HTTP Transport

使用 UCP-Agent header（Dictionary Structured Field 语法）：

UCP-Agent: profile="https://agent.example/profiles/shopping-agent.json"

MCP Transport

使用 _meta.ucp 字段：

{
  "jsonrpc": "2.0",
  "method": "create_checkout",
  "params": {
    "_meta": {
      "ucp": {
        "profile": "https://agent.example/profiles/shopping-agent.json"
      }
    },
    "line_items": [...]
  },
  "id": 1
}

能力协商协议

平台要求

  1. Profile 声明：每个请求包含 Profile URI
  2. 发现：可预先获取并缓存 Business Profile
  3. 命名空间验证：验证 spec URL 来源与命名空间权威方匹配
  4. Schema 解析：获取并组合协商能力的 Schema

商家要求

  1. Profile 解析：收到带平台 Profile URI 的请求时获取并验证
  2. 能力交集：计算平台和商家能力的交集
  3. 扩展验证：移除父能力不在交集中的扩展
  4. 响应要求：每个响应包含 ucp 字段（version 和 capabilities）

能力交集算法 

输入：平台能力列表、商家能力列表
输出：活跃能力列表

步骤：
1. 计算交集：保留名称相同的能力
2. 剪枝孤立扩展：移除 extends 父能力不在交集中的扩展
3. 重复步骤 2，直到没有能力被移除

响应中的能力声明 

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {"name": "dev.ucp.shopping.checkout", "version": "2026-01-11"},
      {"name": "dev.ucp.shopping.fulfillment", "version": "2026-01-11"}
    ]
  },
  "id": "checkout_123",
  "line_items": [...]
}

错误处理

协商失败时，商家 MUST 返回错误响应：

{
  "status": "requires_escalation",
  "messages": [{
    "type": "error",
    "code": "version_unsupported",
    "message": "Version 2026-01-11 is not supported.",
    "severity": "requires_buyer_input"
  }]
}

支付架构概述

信任模型

关系说明
商家 ↔ 凭证提供方预存在的法律和技术关系
平台 ↔ 凭证提供方平台与凭证提供方接口交互
平台 ↔ 商家平台传递令牌或指令给商家

支付生命周期 

1. 协商 → 商家广告 handlers
2. 获取 → 平台执行 handler 逻辑
3. 完成 → 平台提交不透明凭证

传输协议

UCP 支持以下传输协议：

传输规范格式说明
RESTOpenAPI 3.x主要传输，HTTP/1.1 或更高
MCPOpenRPCLLM 智能体直接调用
A2AAgent Card智能体间协作
EmbeddedOpenRPC内嵌商家 UI

REST 要求

  • Content-Type：application/json
  • Methods：标准 HTTP 动词（POST、GET 等）
  • Status Codes：标准 HTTP 状态码

标准能力

能力名称ID说明
Checkoutdev.ucp.shopping.checkout结账会话管理
Identity Linkingdev.ucp.common.identity_linkingOAuth 2.0 身份关联
Orderdev.ucp.shopping.order订单生命周期通知

安全与认证

传输安全

所有 UCP 通信 MUST 使用 HTTPS。

请求认证

  • 平台 → 商家：SHOULD 使用标准 header（如 Authorization: Bearer <token>）
  • 商家 → 平台（Webhook）：MUST 使用签名验证

数据隐私

敏感数据 MUST 符合 PCI-DSS 和 GDPR 要求。

交易完整性

对于需要加密证明的场景，UCP 支持 AP2 Mandates Extension，提供：

  • 商家对结账条款的加密签名
  • 平台对用户授权的加密证明

版本控制

版本格式

使用日期版本：YYYY-MM-DD

版本协商 

IF 平台版本 ≤ 商家版本:
    商家 MUST 处理请求
ELSE:
    商家 MUST 返回 version_unsupported 错误

向后兼容

兼容变更（无需新版本）：

  • 添加非必需字段
  • 添加非必需参数
  • 添加新端点

破坏性变更（需要新版本）：

  • 删除或重命名字段
  • 修改字段类型
  • 使非必需字段变为必需

独立组件版本

  • UCP 协议独立于能力版本
  • 每个能力独立版本控制
  • 传输协议可定义自己的版本处理

参考链接