> ## 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实战案例分析与协议扩展机制详解，深入讲解Buyer Consent隐私同意即GDPR和CCPA合规扩展以及AP2 Mandate支付授权绑定两大扩展的技术实现与依赖关系，规划分阶段集成实战路径，并提供小型独立站、中型品牌电商和大型零售商等不同规模商家的UCP接入案例

# 实战案例与扩展

## 10.1 UCP扩展机制

UCP的核心能力之外，还定义了扩展（Extensions）机制。扩展通过命名空间关联到核心能力，在能力协商时作为依赖项参与修剪。

### Buyer Consent 扩展

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

该扩展让商家在结账流程中获取买家的隐私同意。遵循GDPR、CCPA等隐私法规要求：

```json theme={null}
{
  "buyer_consent": {
    "analytics": true,
    "preferences": true,
    "marketing": false,
    "sale_of_data": false
  }
}
```

**四个同意维度**:

| 维度             | 含义         | 默认     |
| -------------- | ---------- | ------ |
| `analytics`    | 允许使用数据进行分析 | 需要明确同意 |
| `preferences`  | 允许保存用户偏好设置 | 需要明确同意 |
| `marketing`    | 允许发送营销信息   | 需要明确同意 |
| `sale_of_data` | 允许出售个人数据   | 需要明确同意 |

AI代理在创建结账会话时，如果商家支持 `buyer_consent` 扩展，必须向消费者展示同意选项并收集明确的同意/拒绝。布尔值 `true` 表示同意，`false` 表示拒绝。

**依赖关系**: `buyer_consent` 依赖 `checkout` 能力。如果能力协商结果中不包含 `checkout`，`buyer_consent` 会在修剪步骤中被自动移除。

### AP2 Mandate 扩展

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

该扩展为支付流程添加密码学绑定，确保支付授权的不可否认性：

**核心机制**:

* **JWS Detached Signatures**: 使用JSON Web Signature的分离签名模式，签名与支付请求体分离传输
* **SD-JWT+kb Credentials**: 选择性披露的JWT凭证（Selective Disclosure JWT with Key Binding），买家可以只披露完成交易所需的最少信息

```text theme={null}
AP2 Mandate流程:

1. 商家声明需要AP2 Mandate
2. AI代理请求用户授权支付
3. 用户的支付代理创建JWS分离签名
4. 签名绑定到特定交易（金额、商家、时间）
5. 商家验证签名后完成扣款
6. 签名作为不可否认的支付凭证存档
```

**依赖关系**: `ap2_mandate` 依赖 `checkout` 和 `identity_linking`。如果能力协商结果中缺少任何一个，`ap2_mandate` 会被修剪。

## 10.2 案例1：Shopify商家的快速接入

**背景**: Shopify商家，500个SKU，想让AI代理推荐商品并完成结账。

**策略**: 利用Shopify现有API基础，通过proxy部署UCP Profile。

**步骤**:

1. **部署UCP Profile**（30分钟）

通过Shopify App Proxy或独立服务部署 `/.well-known/ucp`：

```json theme={null}
{
  "supported_versions": ["2026-04-08"],
  "services": {
    "dev.ucp.shopping": {
      "base_url": "https://myshop.myshopify.com/apps/ucp-proxy"
    }
  },
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-04-08",
      "supported_operations": ["create", "get", "update", "complete", "cancel"]
    }
  },
  "payment_handlers": ["com.shopify.payments"],
  "signing_keys": []
}
```

2. **商品目录适配**（2小时）

将Shopify Storefront API的响应转换为UCP格式。

3. **结账对接**（1天）

将UCP结账操作映射到Shopify Checkout API。

4. **测试验证**（2小时）

使用第9章的验证清单测试所有端点。

## 10.3 案例2：自建站的完整接入

**背景**: Node.js自建站，2000个SKU，PostgreSQL数据库，已有Stripe支付。

**Phase 1 — Profile + 商品目录（1天）**

```javascript theme={null}
const express = require("express");
const app = express();

// UCP Profile
app.get("/.well-known/ucp", (req, res) => {
  res.set("Cache-Control", "public, max-age=3600");
  res.set("Content-Type", "application/json");
  res.json({
    supported_versions: ["2026-04-08"],
    services: {
      "dev.ucp.shopping": { base_url: "https://mystore.com/ucp" }
    },
    capabilities: {
      "dev.ucp.shopping.checkout": {
        version: "2026-04-08",
        supported_operations: ["create", "get", "update", "complete", "cancel"]
      }
    },
    payment_handlers: ["com.stripe.payment"],
    signing_keys: []
  });
});

// 商品搜索
app.get("/ucp/catalog/products", async (req, res) => {
  const { query, category, limit = 10, offset = 0 } = req.query;
  const products = await db.query(`
    SELECT id, name, description, price_amount, stock, image_url, category
    FROM products
    WHERE ($1::text IS NULL OR name ILIKE '%' || $1 || '%')
    AND ($2::text IS NULL OR category = $2)
    ORDER BY name LIMIT $3 OFFSET $4
  `, [query || null, category || null, Math.min(+limit, 50), +offset]);

  res.json({
    products: products.rows.map(p => ({
      id: p.id,
      name: p.name,
      description: p.description,
      price: { amount: p.price_amount, currency_code: "CNY" },
      availability: p.stock > 0 ? "in_stock" : "out_of_stock",
      images: [{ url: p.image_url, alt: p.name }]
    })),
    total: products.rowCount,
    limit: +limit,
    offset: +offset
  });
});
```

**Phase 2 — 结账能力（2-3天）**

实现6个状态的状态机和5种操作。结账会话存储在数据库中：

```sql theme={null}
CREATE TABLE ucp_checkout_sessions (
  id TEXT PRIMARY KEY,
  status TEXT NOT NULL DEFAULT 'incomplete',
  buyer JSONB,
  line_items JSONB NOT NULL DEFAULT '[]',
  pricing JSONB,
  fulfillment JSONB,
  payment JSONB,
  order_id TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
```

**Phase 3 — 身份关联 + 签名密钥（2-3天）**

* 部署OAuth 2.0授权服务器（推荐使用现有库如 `oidc-provider` 或 `oauth2-server`）
* 发布 `/.well-known/oauth-authorization-server`
* 生成ES256密钥对，在Profile的 `signing_keys` 中发布公钥

**Phase 4 — 订单管理 + Webhook（2天）**

* 订单查询API
* RFC 9421签名的Webhook通知
* 退货/退款调整API

## 10.4 案例3：WooCommerce Cloudflare Worker适配层

**背景**: WooCommerce网店，800个SKU，想用最少的工作量接入UCP。

**方案**: 部署一个Cloudflare Worker作为UCP适配层。

```text theme={null}
AI代理
  │
  ▼
Cloudflare Worker (UCP适配层)
  ├─ /.well-known/ucp → 返回Profile JSON
  ├─ /ucp/catalog/* → 转换为WC API调用，响应转换为UCP格式
  ├─ /ucp/checkout/* → 转换为WC Checkout调用
  └─ 签名密钥管理（密钥存储在CF Secrets中）
  │
  ▼
WooCommerce REST API (wp-json/wc/v3/*)
```

**优势**:

* 不修改WooCommerce本身，Worker独立部署
* 全球边缘节点，低延迟
* 可随时开关，不影响现有网站
* CF Worker的Secrets可以安全存储签名私钥

## 10.5 接入优先级建议

不管你用什么平台，按这个顺序来：

| 阶段 | 工作                         | 耗时   | 效果            |
| -- | -------------------------- | ---- | ------------- |
| 1  | `/.well-known/ucp` Profile | 1小时  | AI代理可以发现你     |
| 2  | 商品目录API                    | 1天   | AI代理可以搜索和展示商品 |
| 3  | 结账能力                       | 2-3天 | AI代理可以完成购买    |
| 4  | 身份关联                       | 2-3天 | 个性化购物体验       |
| 5  | 订单管理 + Webhook             | 2天   | 完整售后支持        |
| 6  | 扩展（Consent/AP2）            | 1-2天 | 合规和高级支付       |

第1阶段零成本就能做，让AI代理知道你存在。后续阶段逐步增加能力，每个阶段都独立可用。

## 10.6 生态系统协作

UCP的30+生态合作伙伴意味着：

* **支付**: 通过 `payment_handlers` 声明支持的处理器（Stripe, Adyen, PayPal, Klarna等），AI代理自动协商最优支付方式
* **先买后付**: Affirm和Klarna作为UCP合作伙伴，预计将提供标准化的分期支付处理器
* **零售商**: Best Buy、Target、Walmart等大型零售商的支持意味着AI代理可以跨商家比价和购买
* **卡组织**: Visa和American Express的参与确保支付令牌交换的金融合规性

***

恭喜你读完了Book 3。现在你理解了UCP协议的完整技术架构——从 `/.well-known/ucp` Profile发现、能力协商、四大核心能力（结账/身份/订单/支付令牌）、四种传输机制（REST/MCP/A2A/Embedded），到RFC 9421签名和JWK密钥管理。

**接下来推荐**:

* 了解AI代理下单协议 -- [Book 4: ACP协议](/zh/book-4/index)
* 构建MCP Server -- [Book 5: MCP协议](/zh/book-5/index)
* 先优化AI可见性 -- [Book 6: SEO for AI](/zh/book-6/index)
* 直接用模板 -- [模板与提示词](/zh/templates/index)

***

**下一步推荐**: [ACP 代理商务协议](/zh/book-4/index) — 了解Stripe创建的AI代理结账和支付标准

**其他实战案例**: [OTR案例](/zh/book-2/ch12-case-studies) | [ACP常见问题](/zh/book-4/ch8-faq) | [MCP案例](/zh/book-5/ch10-case-studies)