> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP协议架构与核心概念详解

> 深入解析UCP协议架构与核心概念设计，详细涵盖反向域名命名空间治理机制、结账与身份关联及订单与商品数据四大核心能力说明、UCP Profile配置与/.well-known端点部署方法、能力协商算法四步流程、REST及MCP传输机制选型对比和UCP-Agent头部规范，帮助开发者全面掌握AI代理商务协议的技术架构

# UCP 核心概念

## 1.1 UCP的定位

UCP是AI代理商务中的"商品发现+交易+支付"全链路协议。它解决的核心问题：**AI代理如何与商家安全地完成一笔完整的商务交易？**

传统电商中，消费者打开网站、浏览商品、加入购物车、结账。UCP把这整个流程标准化为协议能力（Capabilities），让AI代理能以编程方式完成整个购买生命周期——从商品发现到结账、从身份关联到订单追踪、从支付协商到令牌交换。

UCP由 **Google、Shopify、Etsy、Wayfair、Target、Walmart** 六家联合开发，拥有30+生态合作伙伴（包括Adyen、Affirm、American Express、Ant International、Best Buy、Block、Klarna、PayPal、Stripe、Visa等），在GitHub上以Apache 2.0许可证开源。

## 1.2 参与方角色

| 角色                          | 说明                       | 举例                      |
| --------------------------- | ------------------------ | ----------------------- |
| **商家 (Business)**           | 提供商品和服务的卖方，部署UCP Profile | 独立电商网站、品牌官网             |
| **平台 (Platform)**           | 承载商家的电商平台，为商家托管UCP能力     | Shopify, Etsy, Wayfair  |
| **AI代理 (Agent)**            | 代表消费者完成购买的AI系统           | ChatGPT, Claude, Gemini |
| **消费者 (Consumer)**          | 最终购买商品的人                 | AI代理的最终用户               |
| **支付处理器 (Payment Handler)** | 处理支付令牌交换的服务商             | Stripe, Adyen, PayPal   |

**商家中心原则**: UCP的设计确保商家始终保持控制权。商家是Merchant of Record（记录商户），负责商品定价、库存管理、订单履约。AI代理是代表消费者的代理人，不是交易的主体。平台代表商家托管UCP能力，但商家保留对业务规则的最终控制权。

## 1.3 四大核心能力 (Capabilities)

UCP使用反向域名命名空间标识每个能力，确保全球唯一且无命名冲突。

### 结账 (Checkout)

**命名空间**: `dev.ucp.shopping.checkout`

结账是UCP的核心交易能力。一个结账会话（Checkout Session）有明确的状态机：

| 状态                     | 含义                  |
| ---------------------- | ------------------- |
| `incomplete`           | 会话创建但信息不完整          |
| `requires_escalation`  | 需要人工介入（如年龄验证、高风险订单） |
| `ready_for_complete`   | 所有信息就绪，可以提交         |
| `complete_in_progress` | 正在处理完成请求            |
| `completed`            | 交易成功完成              |
| `canceled`             | 交易已取消               |

支持5种操作：**Create**（创建会话）、**Get**（查询会话）、**Update**（更新信息）、**Complete**（提交完成）、**Cancel**（取消会话）。

所有金额使用 **ISO 4217最小货币单位**（如人民币用分、美元用美分、日元直接用円）。

### 身份关联 (Identity Linking)

**命名空间**: `dev.ucp.common.identity_linking`

基于 **OAuth 2.0 Authorization Code** 流程。商家通过 `/.well-known/oauth-authorization-server` 发布授权服务器元数据。标准scope为 `ucp:scopes:checkout_session`。支持令牌撤销（RFC 7009），用户可随时取消AI代理的访问权限。

### 订单管理 (Order)

**命名空间**: `dev.ucp.shopping.order`

行项目状态追踪：`processing`（处理中）、`partial`（部分履约）、`fulfilled`（已履约）、`removed`（已移除）。

履约事件类型：`processing`、`shipped`、`in_transit`、`delivered`、`attempted_delivery`、`ready_for_pickup`、`picked_up` 等。

调整操作类型：`refund`（退款）、`return`（退货）、`credit`（信用额度）等。

Webhook通知使用 **RFC 9421 HTTP消息签名** 确保数据完整性。

### 支付令牌交换 (Payment Token Exchange)

支付处理器使用反向DNS命名（如 `com.stripe.payment`）。生命周期为三步：

1. **协商（Negotiation）**: 平台和商家确定共同支持的支付处理器
2. **获取（Acquisition）**: 平台获取支付凭证
3. **完成（Completion）**: 使用凭证完成支付

凭证流向是**单向的**：从平台到商家（Platform到Business），确保支付安全。

## 1.4 命名空间治理

UCP的命名空间采用反向域名格式，确保全球唯一性：

```text theme={null}
格式: [reverse-domain].[service].[capability]

UCP官方命名空间:
  dev.ucp.shopping.checkout        # 结账能力
  dev.ucp.common.identity_linking  # 身份关联
  dev.ucp.shopping.order           # 订单管理
  dev.ucp.shopping.buyer_consent   # 买家同意（扩展）
  dev.ucp.shopping.ap2_mandate     # AP2授权（扩展）

供应商命名空间:
  com.shopify.custom_checkout      # Shopify自定义
  com.stripe.payment               # Stripe支付处理器
```

**治理规则**:

* `dev.ucp.*` 命名空间由UCP官方管理，必须源自 `https://ucp.dev/`
* `com.vendor.*` 命名空间由各供应商自行管理
* 命名空间确保不同供应商的扩展不会互相冲突

## 1.5 UCP Profile (/.well-known/ucp)

每个支持UCP的商家或平台必须在 `/.well-known/ucp` 路径发布一个JSON Profile文件，这是AI代理发现和对接的入口。

**关键要求**:

* 必须通过 **HTTPS** 提供服务（不允许HTTP）
* **不允许重定向**（3xx响应会被拒绝）
* 必须设置 `Cache-Control` 头：`public, max-age` 至少60秒

Profile文件包含以下核心字段：

```json theme={null}
{
  "supported_versions": ["2026-04-08"],
  "services": {
    "dev.ucp.shopping": {
      "base_url": "https://store.example.com/ucp"
    }
  },
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-04-08",
      "supported_operations": ["create", "get", "update", "complete", "cancel"]
    },
    "dev.ucp.common.identity_linking": {
      "version": "2026-04-08"
    },
    "dev.ucp.shopping.order": {
      "version": "2026-04-08"
    }
  },
  "payment_handlers": [
    "com.stripe.payment",
    "com.adyen.payment"
  ],
  "signing_keys": [
    {
      "kid": "key-2026-04",
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}
```

## 1.6 UCP-Agent HTTP头

AI代理在与商家通信时，使用 `UCP-Agent` HTTP头声明自身身份。该头遵循 **RFC 8941 Dictionary Structured Field** 格式：

```http theme={null}
UCP-Agent: profile="https://agent.example/profiles/shopping-agent.json"
```

这让商家可以识别哪个AI代理在发起请求，便于日志记录、限速控制和信任管理。

## 1.7 能力协商算法

当AI代理和商家初次建立连接时，需要通过能力协商确定双方共同支持的功能。算法分为四步：

1. **计算交集**: 找出双方Profile中名称相同的能力
2. **选择版本**: 对每个共同能力，选择双方都支持的最高版本号
3. **修剪孤立扩展**: 移除依赖于不在交集中的能力的扩展
4. **重复修剪**: 反复执行步骤3，直到没有更多扩展被移除（达到稳定状态）

```text theme={null}
示例:

Agent支持: checkout v2026-04-08, identity v2026-04-08, buyer_consent v2026-04-08
商家支持: checkout v2026-04-08, order v2026-04-08, buyer_consent v2026-04-08

步骤1 - 交集: checkout, buyer_consent
步骤2 - 版本: checkout v2026-04-08, buyer_consent v2026-04-08
步骤3 - 修剪: buyer_consent依赖checkout(已在交集中), 保留
步骤4 - 稳定: 无更多变化

最终结果: checkout v2026-04-08, buyer_consent v2026-04-08
```

## 1.8 传输机制

UCP不绑定单一传输协议，支持四种传输方式：

| 传输方式         | Schema                   | 通信模式      | 典型场景                                                      |
| ------------ | ------------------------ | --------- | --------------------------------------------------------- |
| **REST**     | OpenAPI 3.x              | HTTP请求/响应 | 服务端集成、平台对接                                                |
| **MCP**      | OpenRPC (JSON-RPC 2.0)   | 工具调用      | AI应用直接对接（`search_catalog`、`lookup_catalog`、`get_product`） |
| **A2A**      | Agent Card Specification | 代理间消息     | 多代理协作（购物代理+支付代理）                                          |
| **Embedded** | OpenRPC schema           | 嵌入式调用     | 商家页面内嵌AI能力                                                |

## 1.9 版本策略

UCP使用**基于日期的版本号**（如 `2026-04-08`），而非传统的语义化版本号。这种策略的优势：

* 版本号直接反映规范发布日期，便于理解时间线
* 每个能力可以独立版本化
* 能力协商时通过日期比较即可确定最新版本

## 1.10 一个完整的交易流程

```text theme={null}
1. AI代理获取商家的 /.well-known/ucp Profile
2. 执行能力协商算法，确定双方共同支持的能力
3. 如果支持identity_linking，通过OAuth 2.0关联用户身份
4. 通过MCP或REST搜索商品目录
5. 创建checkout session (状态: incomplete)
6. 更新买家信息、配送方式、支付信息
7. 会话状态变为 ready_for_complete
8. 调用Complete操作，状态变为 complete_in_progress
9. 交易完成，状态变为 completed
10. 通过order能力追踪履约状态，接收Webhook通知
```

***

**下一章**: [结账API](/zh/book-3/ch2-checkout) — 6个状态、5种操作、嵌入式UI和ISO 4217金额处理