跳转到主要内容

​
实战案例与扩展

​
10.1 UCP扩展机制

UCP的核心能力之外，还定义了扩展（Extensions）机制。扩展通过命名空间关联到核心能力，在能力协商时作为依赖项参与修剪。 命名空间: dev.ucp.shopping.buyer_consent 该扩展让商家在结账流程中获取买家的隐私同意。遵循GDPR、CCPA等隐私法规要求： 
{
  "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），买家可以只披露完成交易所需的最少信息
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： 
{
  "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": []
}
  1. 商品目录适配（2小时）
将Shopify Storefront API的响应转换为UCP格式。
  1. 结账对接（1天）
将UCP结账操作映射到Shopify Checkout API。
  1. 测试验证（2小时）
使用第9章的验证清单测试所有端点。

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

背景: Node.js自建站，2000个SKU，PostgreSQL数据库，已有Stripe支付。 Phase 1 — Profile + 商品目录（1天） 
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种操作。结账会话存储在数据库中： 
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适配层。 
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 Profile1小时AI代理可以发现你
2商品目录API1天AI代理可以搜索和展示商品
3结账能力2-3天AI代理可以完成购买
4身份关联2-3天个性化购物体验
5订单管理 + Webhook2天完整售后支持
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密钥管理。 接下来推荐:
下一步推荐: ACP 代理商务协议 — 了解Stripe创建的AI代理结账和支付标准 其他实战案例: OTR案例 | ACP常见问题 | MCP案例