通用商务协议(Universal Commerce Protocol, UCP)

UCP 是一个开放标准,允许 AI 智能体发现、搜索并购买你的产品和服务——通过一个标准 JSON 文件和一组结构化端点实现。 本页是实现 UCP 的完整参考。

UCP 简介

UCP 扮演着你企业"机器可读菜单"的角色。正如 robots.txt 告诉搜索引擎爬虫应该抓取哪些部分一样, UCP 文件告诉 AI 智能体你的企业拥有哪些能力,以及每项能力应从何处调用。该文件必须始终能在固定地址 https://yoursite.com/.well-known/ucp 访问,并以 Content-Type: application/json 响应。

快速上手

最快的方式是使用免费的 UCP 生成器:输入你的企业信息和所需能力,即可生成一份完整、可直接部署的 ucp.json 文件。如需手动编写,请参考下面的字段和能力参考。

ucp.json 参考

{
  "protocol": "ucp/v1",
  "merchant_name": "示例商店",
  "description": "一家在线数码产品商店",
  "website": "https://example.com",
  "capabilities": [
    {
      "name": "search_offers",
      "description": "搜索产品",
      "endpoint": "https://api.example.com/v1/ucp/search",
      "method": "GET"
    }
  ],
  "payment_methods": ["alipay"],
  "supported_languages": ["zh", "en"],
  "currency": "CNY"
}

能力参考(Capabilities)

capabilities 数组中的每个成员都包含 name、description、endpoint 和 method。八项标准能力如下:

请求与响应示例:search_offers

GET /v1/ucp/search?query=耳机&limit=5

200 OK
{
  "results": [
    { "id": "sku_123", "name": "Model X 无线耳机", "price": 129.00, "currency": "CNY", "in_stock": true }
  ]
}

请求与响应示例:initiate_checkout

POST /v1/ucp/checkout
{ "cart_id": "cart_789", "customer": { "name": "...", "phone": "..." } }

200 OK
{ "order_id": "order_456", "status": "pending_payment", "payment_url": "https://..." }

身份验证

UCP 让清单文件本身保持公开(读取无需身份验证),但操作性端点必须是安全的:

• 所有端点仅通过 HTTPS 提供访问
• 对于敏感端点(结账、钱包),使用 API 令牌或 Bearer Token
• 使用请求签名或一次性 nonce 保护会产生变更的请求(POST)

支付

initiate_checkout 能力通常会向你现有的支付网关发起一笔交易,并返回支付链接或交易 ID—— UCP 并不会取代你的支付网关,而是构建在其之上的标准层。对任何商店来说,这都意味着从同一个端点背后连接到你已经在使用的 同一个网关(支付宝、微信支付,或任何其他支付服务商)。

错误处理

错误响应必须始终是有效的 JSON,而不是 HTML 页面或自由文本:

404 Not Found
{ "error": { "code": "product_not_found", "message": "未找到该产品" } }

测试与验证

• curl -i https://yoursite.com/.well-known/ucp — 检查是否返回 200 且 JSON 有效
• 在在线 JSON 验证工具中检查输出
• 使用 Postman 单独测试每一项能力
• 确保在错误状态下也能返回结构化的 JSON 响应

版本管理

protocol 字段携带当前版本(例如 ucp/v1)。不兼容的更改必须通过提升版本号来宣布, 以免仍在实现旧版本的智能体遇到意外错误。

常见问题