Skip to main content

平台集成指南

8.1 平台的角色

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

8.2 能力协商算法实现

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

步骤1:计算交集

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

步骤2:选择版本

对每个共同能力,选择双方都支持的最高版本号(基于日期比较):

步骤3:修剪孤立扩展

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

步骤4:重复修剪直到稳定

8.3 命名空间管理

平台可以在UCP标准命名空间(dev.ucp.*)之外注册自己的供应商命名空间(com.vendor.*)来提供特有能力:
治理规则:
  • 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适配层:
适配层部署选项:
  • 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 各平台对比

8.8 多商家托管

平台为多个商家托管UCP时,需要处理: Profile路由: 每个商家有独立的子域名或路径前缀
密钥隔离: 每个商家应有独立的签名密钥对,避免密钥泄露影响所有商家。 能力定制: 不同商家可能支持不同的能力组合(有的商家支持退货,有的不支持),Profile应准确反映每个商家的实际能力。
下一章: 测试与验证 — Profile验证、结账流程测试和安全合规检查