架构设计
架构设计
概述
UCP 架构围绕四个核心问题展开：
- 如何发现能力？ — Profile 机制
- 如何协商版本和能力？ — 能力交集算法
- 如何传输数据？ — 多传输协议支持
- 如何安全支付？ — 解耦的支付架构
发现机制
Profile 端点
每个参与者在 /.well-known/ucp 发布配置文件：
| 参与者 | Profile URI |
|---|---|
| 商家 | https://business.example.com/.well-known/ucp |
| 平台 | https://platform.example.com/profiles/shopping-agent.json |
Profile 内容结构
{
"ucp": {
"version": "2026-01-11",
"services": { ... },
"capabilities": [ ... ]
},
"payment": {
"handlers": [ ... ]
},
"signing_keys": [ ... ]
}平台声明
平台在每个请求中声明 Profile URI：
HTTP Transport:
UCP-Agent: profile="https://agent.example/profiles/shopping-agent.json"MCP Transport:
{
"_meta": {
"ucp": {
"profile": "https://agent.example/profiles/shopping-agent.json"
}
}
}协商机制
能力交集算法
输入：平台能力列表、商家能力列表
输出：活跃能力列表
步骤：
1. 计算交集：保留名称相同的能力
2. 剪枝孤立扩展：移除 extends 父能力不在交集中的扩展
3. 重复步骤 2，直到没有能力被移除示例
| 平台能力 | 商家能力 | 交集结果 |
|---|---|---|
| Checkout | Checkout, Order | Checkout |
| Fulfillment (extends Checkout) | Fulfillment (extends Checkout) | Fulfillment |
| Discount | - | - （商家不支持） |
命名空间治理
| 命名空间模式 | 权威方 | 治理方式 |
|---|---|---|
dev.ucp.* | ucp.dev | UCP 管理机构 |
com.{vendor}.* | {vendor}.com | 供应商组织 |
org.{org}.* | {org}.org | 组织 |
Spec URL 绑定验证
| 命名空间 | 要求的来源 |
|---|---|
dev.ucp.* | https://ucp.dev/... |
com.example.* | https://example.com/... |
平台必须验证 spec URL 的来源与命名空间权威方匹配。
传输架构
传输绑定
UCP 将传输定义为薄层，仅声明方法名和引用基础 Schema：
{
"rest": {
"schema": "https://ucp.dev/services/shopping/rest.openapi.json",
"endpoint": "https://business.example.com/ucp/v1"
}
}端点解析
OpenAPI 路径直接追加到 endpoint：
endpoint: https://business.example.com/ucp/v1
path: /checkout-sessions
结果: POST https://business.example.com/ucp/v1/checkout-sessions传输能力矩阵
| 传输 | 主要用途 | 规范 | 能力映射 |
|---|---|---|---|
| REST | 标准应用集成 | OpenAPI 3.x | 端点 |
| MCP | LLM 智能体 | OpenRPC | 工具 |
| A2A | 智能体间协作 | Agent Card | 扩展 |
| Embedded | 嵌入商家 UI | OpenRPC | 事件 |
支付架构
设计目标
解决"平台—商家—支付凭证提供方"之间的 N×N 复杂度：
- 支付凭证与支付处理器分离
- 平台不接触原始支付数据
- 支持多种支付令牌类型
信任模型
┌─────────────────┐
│ 平台 │
│ (不接触原始数据) │
└────────┬─────────┘
│ 令牌/证明
↓
┌─────────────────┐
│ 商家 │
│ (Merchant of │
│ Record) │
└────────┬─────────┘
│
┌───────────┴───────────┐
↓ ↓
┌─────────┐ ┌──────────────┐
│ PSP │ │ 凭证提供方 │
└─────────┘ └──────────────┘支付生命周期
1. 协商 → 商家广告 handlers
2. 获取 → 平台执行 handler 逻辑
3. 完成 → 平台提交不透明凭证Payment Handler 定义
| 字段 | 说明 |
|---|---|
id | 唯一标识符 |
name | Handler 名称（反向域名） |
version | 版本（YYYY-MM-DD） |
spec | 规范文档 URL |
config_schema | 配置 Schema URL |
instrument_schemas | 支持的支付凭证类型 |
config | 商家特定配置 |
PCI-DSS 范围管理
| 角色 | PCI 范围 | 最小化策略 |
|---|---|---|
| 平台 | 可避免 | 使用不透明凭证、不接触原始数据 |
| 商家 | 可最小化 | 使用令牌化、委托给 PCI 认证的支付凭证提供方 |
| 凭证提供方 | 必需 | 通常为 PCI-DSS Level 1 认证 |
版本控制
版本格式
使用日期版本：YYYY-MM-DD
版本协商规则
IF 平台版本 ≤ 商家版本:
商家必须处理请求
ELSE:
商家必须返回 version_unsupported 错误向后兼容
兼容变更（无需新版本）：
- 添加非必需字段
- 添加非必需参数
- 添加新端点
破坏性变更（需要新版本）：
- 删除或重命名字段
- 修改字段类型
- 使非必需字段变为必需
安全架构
传输安全
- 所有通信必须使用 HTTPS
- 请求使用标准认证（如
Authorization: Bearer <token>） - Webhook 必须签名验证
数据隐私
敏感数据必须符合 PCI-DSS 和 GDPR 要求，鼓励使用令牌化支付数据。
交易完整性（可选）
对于需要加密证明的场景（如自主智能体），UCP 支持 AP2 Mandates Extension：
- 商家提供结账条款的加密签名
- 平台提供用户授权的加密证明