> ## 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多商家托管集成方案技术详解，完整讲解能力协商四步算法即交集计算、版本选择、操作合并与扩展修剪的JavaScript代码实现、反向域名命名空间管理策略、多商家统一Profile托管架构设计，以及Shopify和Etsy等主流电商平台的UCP对接实现路径与最佳实践

# 平台集成指南

## 8.1 平台的角色

在UCP架构中，平台（Platform）是代表商家托管UCP能力的中间层。平台的职责：

* 为旗下商家统一部署和维护 `/.well-known/ucp` Profile
* 实现能力协商算法，与AI代理自动协商
* 管理商家的签名密钥和OAuth配置
* 处理支付令牌交换中的平台侧逻辑

## 8.2 能力协商算法实现

当AI代理首次连接平台时，双方需要执行能力协商。平台必须实现这个四步算法：

### 步骤1：计算交集

获取AI代理和平台双方Profile中名称相同的能力：

```javascript theme={null}
function computeIntersection(agentProfile, platformProfile) {
  const agentCaps = Object.keys(agentProfile.capabilities);
  const platformCaps = Object.keys(platformProfile.capabilities);

  return agentCaps.filter(cap => platformCaps.includes(cap));
}

// Agent支持: checkout, identity_linking, buyer_consent
// Platform支持: checkout, order, buyer_consent
// 交集: checkout, buyer_consent
```

### 步骤2：选择版本

对每个共同能力，选择双方都支持的最高版本号（基于日期比较）：

```javascript theme={null}
function selectVersion(agentCap, platformCap) {
  const agentVersions = agentCap.supported_versions || [agentCap.version];
  const platformVersions = platformCap.supported_versions || [platformCap.version];

  const mutual = agentVersions.filter(v => platformVersions.includes(v));
  // 日期字符串可以直接字典序比较
  return mutual.sort().reverse()[0]; // 最高版本
}
```

### 步骤3：修剪孤立扩展

移除依赖于不在交集中的能力的扩展：

```javascript theme={null}
function pruneOrphans(negotiated, dependencyMap) {
  return negotiated.filter(cap => {
    const deps = dependencyMap[cap] || [];
    return deps.every(dep => negotiated.includes(dep));
  });
}

// buyer_consent 依赖 checkout (在交集中) -> 保留
// ap2_mandate 依赖 checkout + identity (identity不在交集中) -> 移除
```

### 步骤4：重复修剪直到稳定

```javascript theme={null}
function negotiate(agentProfile, platformProfile, dependencyMap) {
  let result = computeIntersection(agentProfile, platformProfile);

  // 为每个能力选择版本
  result = result.map(cap => ({
    name: cap,
    version: selectVersion(
      agentProfile.capabilities[cap],
      platformProfile.capabilities[cap]
    )
  })).filter(cap => cap.version); // 移除无共同版本的能力

  // 反复修剪直到稳定
  let prev;
  do {
    prev = result.map(c => c.name);
    result = result.filter(cap => {
      const deps = dependencyMap[cap.name] || [];
      return deps.every(dep => prev.includes(dep));
    });
  } while (result.length !== prev.length);

  return result;
}
```

## 8.3 命名空间管理

平台可以在UCP标准命名空间（`dev.ucp.*`）之外注册自己的供应商命名空间（`com.vendor.*`）来提供特有能力：

```json theme={null}
{
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-04-08"
    },
    "com.shopify.abandoned_cart_recovery": {
      "version": "2026-01-15"
    },
    "com.shopify.loyalty_points": {
      "version": "2026-03-01"
    }
  }
}
```

**治理规则**:

* `dev.ucp.*`: 只有 UCP官方（`https://ucp.dev/`）可以注册和管理
* `com.shopify.*`: 只有Shopify可以注册和管理
* AI代理如果不认识某个供应商命名空间，协商时会自动跳过

## 8.4 Shopify

Shopify是UCP的六大共同开发者之一，预计将原生支持UCP。

**现有的UCP兼容基础**:

* Storefront API已支持JSON格式商品查询和购物车管理
* Checkout API支持编程式结账
* Customer Access Token机制接近OAuth模式
* Agentic Storefronts功能是UCP的前身

**当前可以做的**:

1. 确保商品数据完整（标题、描述、价格、库存、图片、SKU）
2. 启用Storefront API
3. 创建 `/.well-known/ucp` Profile（通过Shopify App或自定义proxy）
4. 等待Shopify官方UCP插件发布后一键启用

## 8.5 WooCommerce

WooCommerce的REST API已经提供了很多UCP需要的数据能力：

**已有的**:

* `GET /wp-json/wc/v3/products` — 商品列表
* `GET /wp-json/wc/v3/products/{id}` — 商品详情
* `GET /wp-json/wc/v3/orders/{id}` — 订单查询

**需要开发的UCP适配层**:

```text theme={null}
AI代理 → UCP格式请求 → 适配层(CF Worker/Node.js) → WooCommerce API
                              │
                              ├─ 格式转换: WC格式 ↔ UCP格式
                              ├─ /.well-known/ucp Profile
                              ├─ OAuth 2.0代理（WC原生用API Key）
                              └─ 签名密钥管理
```

适配层部署选项:

* **Cloudflare Worker**: 轻量级、全球边缘部署、低延迟
* **独立Node.js服务**: 完全控制、适合复杂逻辑
* **WordPress插件**: 与WooCommerce深度集成

## 8.6 自建站

自建站有最大的灵活性，可以直接实现UCP全部端点：

1. 部署 `/.well-known/ucp` Profile（参考7.2节）
2. 实现商品目录API（REST和/或MCP传输）
3. 实现结账状态机（6个状态、5种操作）
4. 生成ES256签名密钥，配置Webhook
5. 按需实现OAuth 2.0和订单管理

## 8.7 各平台对比

| 平台              | UCP集成路径          | 预计工作量         | 关键依赖             |
| --------------- | ---------------- | ------------- | ---------------- |
| **Shopify**     | 等官方插件 或 自建proxy  | 0.5-1天（proxy） | Storefront API   |
| **WooCommerce** | 适配层（CF Worker推荐） | 2-3天          | WC REST API v3   |
| **自建站**         | 完整开发             | 5-8天（全能力）     | 自有数据库和支付         |
| **Magento**     | 适配层              | 3-4天          | Magento REST API |
| **BigCommerce** | 适配层              | 2-3天          | BC API v3        |

## 8.8 多商家托管

平台为多个商家托管UCP时，需要处理：

**Profile路由**: 每个商家有独立的子域名或路径前缀

```text theme={null}
https://store-a.platform.com/.well-known/ucp  → 商家A的Profile
https://store-b.platform.com/.well-known/ucp  → 商家B的Profile
```

**密钥隔离**: 每个商家应有独立的签名密钥对，避免密钥泄露影响所有商家。

**能力定制**: 不同商家可能支持不同的能力组合（有的商家支持退货，有的不支持），Profile应准确反映每个商家的实际能力。

***

**下一章**: [测试与验证](/zh/book-3/ch9-testing) — Profile验证、结账流程测试和安全合规检查