跳转到主要内容

​
平台集成指南

​
8.1 平台的角色

在UCP架构中，平台（Platform）是代表商家托管UCP能力的中间层。平台的职责：
  • 为旗下商家统一部署和维护 /.well-known/ucp Profile
  • 实现能力协商算法，与AI代理自动协商
  • 管理商家的签名密钥和OAuth配置
  • 处理支付令牌交换中的平台侧逻辑

​
8.2 能力协商算法实现

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

​
步骤1：计算交集

获取AI代理和平台双方Profile中名称相同的能力： 
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：选择版本

对每个共同能力，选择双方都支持的最高版本号（基于日期比较）： 
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：修剪孤立扩展

移除依赖于不在交集中的能力的扩展： 
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：重复修剪直到稳定

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.*）来提供特有能力： 
{
  "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适配层: 
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等官方插件 或 自建proxy0.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路由: 每个商家有独立的子域名或路径前缀 
https://store-a.platform.com/.well-known/ucp  → 商家A的Profile
https://store-b.platform.com/.well-known/ucp  → 商家B的Profile
密钥隔离: 每个商家应有独立的签名密钥对，避免密钥泄露影响所有商家。 能力定制: 不同商家可能支持不同的能力组合（有的商家支持退货，有的不支持），Profile应准确反映每个商家的实际能力。
下一章: 测试与验证 — Profile验证、结账流程测试和安全合规检查