UCP (Universal Commerce Protocol) — 架构与原理
30 秒导读： UCP 是一个开放标准，让商家把自己的商务功能（结算、下单、支付方式…）用 JSON Schema 声明一次，任何兼容平台——尤其是 AI 购物 agent——就能自动发现并对接，不用为每家商家写一套定制集成。它解决的是“N 个平台 × M 个商家 = N×M 套对接”的爆炸问题。
本仓库是 UCP 的规范与文档源，不是某个可运行的服务端实现。真正的协商/签名/校验逻辑活在外部仓库（ucp-schema Rust crate、各语言 SDK、conformance 测试套件）里，不在本克隆内。所以下面 讲“算法”时，依据是规范散文 + 驱动这些算法的 JSON Schema 注解，外加本仓库自带的文档构建与示例校验工具链。
1. 这是什么（零基础也能懂）
一句话定义。 UCP 是一套“商务互操作”协议：商家在一个固定地址发布机器可读的能力清单，平台读清单后按标准接口跟它做生意。
它要解决的痛。 想象你做了一个 AI 购物助手，想让它能在 1000 家网店“帮用户下单”。今天你得为每家店读它们各自的 API 文档、写各自的对接代码——这就是碎片化。UCP 的思路是：让这 1000 家店都用同一种语言描述“我支持结算吗？支持配送选项吗？能用 Google Pay 吗？”，你的 agent 只要会读这一种语言，就能对接所有人。
给谁用。 协议定义了四类角色：
| 角色 | 中文 | 它干什么 | 例子 |
|---|---|---|---|
| Platform | 平台 | 消费能力的一方：发现商家能力并代表用户调用 | AI 购物 agent、超级 App、搜索引擎、B2B 采购系统 |
| Business | 商家 | 暴露能力的一方，通常是 Merchant of Record（记录商户，承担交易责任） | 零售商、航司、酒店、供应商 |
| Credential Provider (CP) | 凭证提供方 | 安全保管用户支付工具/地址，签发支付 token | Google Wallet、Apple Pay |
| Payment Service Provider (PSP) | 支付服务商 | 真正扣款、清结算、对接卡组织 | Stripe、Adyen、PayPal |
注意 Platform / Business 是按“能力流向”定义的角色，不绑定行业——所以 B2C、B2B、agent-to-agent 都适用。来源：
docs/documentation/core-concepts.md:28-35。
用起来什么样（最小直观示例）。 平台向商家发请求时，在 HTTP 头里报上自己的 profile 地址，商家据此协商：
POST /checkout-sessions HTTP/1.1
UCP-Agent: profile="https://agent.example/profiles/shopping-agent.json"
Content-Type: application/json
{"line_items": [{"id": "prod_123", "quantity": 2}]}
商家回的每个响应里都带一个 ucp 块，明确告诉平台“这次交互到底哪些能力生效、用的哪个版本”。来源：docs/specification/overview.md:609-624、docs/documentation/core-concepts.md:218-224。
一句话直觉/类比。 把 UCP 想成商务版的“浏览器 + 网站”约定：商家像网站一样在 /.well-known/ucp 挂一份“我支持什么” 的清单（类比 robots.txt / OpenAPI），平台像浏览器一样去读清单、按标准协议交互——没有中央注册中心，谁的域名谁说了算。
2. 顶层全景（它大概怎么转）
UCP 一笔交易的主线，是“发现 → 协商 → 调用 → 支付 → 订单”五步。下面这张图从上到下就是时间顺序（每一步配了它落在哪一章）：
平台 (AI agent / App) 商家 (Merchant of Record)
─────────────────────── ──────────────────────────
│ │
│ ① 发现：GET /.well-known/ucp │ 发布能力清单 + 公钥
│ ──────────────────────────────────────── ────────▶ │ (profile 文档)
│ ◀──────────── 能力 / 服务 / 支付方式 / signing_keys │
│ │
│ ② 协商：请求带 UCP-Agent: profile="…平台清单…" │ 服务端取交集
│ ────────────────────────────────────────────────▶ │ (server-selects)
│ ◀──── 响应的 ucp.capabilities = 双方都支持的最小集 │ + 剪掉孤儿扩展
│ │
│ ③ 调用 Checkout：create → update → … │ 状态机推进
│ ◀──────────── checkout{status, totals, messages…} │
│ │
│ ④ 支付：从 CP 取 token（商家不碰原始卡号） │ Handler 协商→获取→完成
│ ──── complete{payment.instruments[{token}]} ─────▶ │ 用 PSP 扣款
│ │
│ ⑤ 订单：商家 webhook 推送 shipped/delivered… │ 签名后推送
│ ◀──────────── order 事件（签名校验同 profile 公钥） │
部件一句话职责：
| 部件 | 干什么 | 在哪 |
|---|---|---|
Profile（/.well-known/ucp） | 商家/平台的“身份+能力”单一文档：声明 services/capabilities/payment_handlers + signing_keys | source/schemas/profile.json、source/schemas/ucp.json |
| Capability（能力） | 可独立版本化的“动词”，如 checkout/cart/order；反向域名命名 | source/schemas/capability.json |
| Extension（扩展） | 用 extends 挂到某能力上的可选增强（折扣、配送、AP2） | source/schemas/shopping/discount.json 等 |
| Service（服务） | 把一个垂直域的操作按传输绑定（REST/MCP/A2A/Embedded）暴露 | source/schemas/service.json |
| Payment Handler（支付处理器） | 规范（不是实体），描述某支付工具如何获取与处理 | source/schemas/payment_handler.json |
| 协商算法 | 取双方能力交集、选最高版本、剪孤儿扩展 | 规范散文 docs/specification/overview.md:679-703 |
| 签名 | RFC 9421 HTTP 消息签名，密钥从 profile 发现 | docs/specification/signatures.md |
| Schema 变体机制 | ucp_request 注解 → ucp-schema 解析出 create/update/response 三种形状 | source/schemas/shopping/checkout.json、main.py |
主线走一遍（高层）。 平台先（可选地）抓商家 profile；发请求时用 UCP-Agent 头报上自己的 profile URL；商家抓平台 profile，取双方能力交集得到本次生效能力集，写进响应的 ucp 块；随后双方按 checkout 能力的状态机推进，支付阶段平台直接找 CP 拿 token 交给商家扣款，下单后商家用签名 webhook 推订单事件。
3. 阅读地图（建议顺序）
按“先协议骨架、再业务流程、最后工程实现”的顺序读：
- 01-discovery-negotiation.md — 协议最核心的一招：能力取交集 + 剪枝。先读这章，它是 UCP “免对接接入”的发动机。
- 02-capabilities-extensions.md — 反向域名治理、capability/extension/service 三件套、
extends如何用allOf组合 schema。 - 03-payments.md — 支付信任三角、为什么说“Payment Handler 是规范不是实体”、三步支付 生命周期、PCI 边界。
- 04-checkout-lifecycle.md — checkout 状态机、
messages[]+severity错误处理栈、totals渲染契约、AP2 安全锁定。 - 05-signatures.md — RFC 9421 签名、用同一份 profile 既协商能力又发现公钥、幂等键做重放保护。
- 06-schema-variants-toolchain.md — 巧妙之处所在：一份 schema 靠
ucp_request注解派生出多种操作变体，以及文档构建宏 + 示例校验门禁。给要改 schema / 写文档的人。
4. 边界与局限（先知道它“不是什么”）
- 本仓库是规范，不是实现。 没有可运行的商家服务端或 SDK；协商、签名验证、schema 组合的真实代码在外部仓库（
ucp-schema、SDKs、conformance）。本克隆内能核对的是：JSON Schema 定义、规范散文、以及文档工具链（main.py、scripts/validate_examples.py）。 - 协议不规定的东西很多是故意的。 归因（attribution）模型、
maxProperties上限、版本弃用排期、信任策略，都明确交给实现者，UCP 只定“在线格式”。来源：docs/specification/overview.md:1812-1816、docs/documentation/schema-authoring.md:423-434。 - 协商是“服务端选择”（server-selects）。 是商家而非平台决定最终生效能力集——这把权威集中在 MoR 一侧。
5. 横向对比（同 shelf 兄弟）
UCP 属于 ai-protocol-reference 的 payments-commerce / protocols 区。它和兄弟协议的取舍差异：
- vs MCP（Model Context Protocol）： MCP 是“agent ↔ 工具”的通用 RPC；UCP 复用 MCP 作为它的一种传输绑定（
transport: "mcp"，OpenRPC 描述），但 UCP 关心的是商务语义（结算/支付/订单），是建在传输之上的领域协议。来源：docs/documentation/core-concepts.md:197-204。 - vs AP2（Agentic Payments Protocol）： AP2 是“可验证数字凭证 + mandate”的支付授权协议；UCP 把它做成一个可选扩展
dev.ucp.shopping.ap2_mandate，只有协商命中才激活并“锁死”会话。来源：docs/specification/ap2-mandates.md:17-38。 - 设计共性： 和多数 agent 协议一样，UCP 把“能力发现”做成核心一等公民（profile + 协商），区别在它额外背了支付与 PCI 合规这条重担，于是引入了信任三角和“凭证只能单向流动”的硬约束。
6. 代码地图（导航索引）
| 主题 | 文件路径 | 关键符号 / 锚点 |
|---|---|---|
协议元数据基座（profile 的 ucp 块） | source/schemas/ucp.json | $defs.base、$defs.platform_schema、$defs.business_schema、$defs.entity |
| 能力/扩展定义 | source/schemas/capability.json | $defs.base(含 extends)、platform_schema、response_schema |
| 结算能力基座 schema | source/schemas/shopping/checkout.json | name=dev.ucp.shopping.checkout、properties.status.enum、各属性的 ucp_request |
| 扩展组合范例 | source/schemas/shopping/discount.json | $defs["dev.ucp.shopping.checkout"](allOf)、$defs.discounts_object |
| 协商/支付/版本权威规范 | docs/specification/overview.md | Intersection Algorithm、Trust Triangle、Versioning |
| 结算状态机与错误处理 | docs/specification/checkout.md | Checkout Status Lifecycle、severity 表、Totals Rendering Contract |
| 签名机制 | docs/specification/signatures.md | verify_rest_request、Signed Components 表、Key Rotation |
| Schema 注解约定 | docs/documentation/schema-authoring.md | ucp_request、Schema Variants、Documenting JSON Examples |
| 文档构建宏 | main.py | define_env、schema_fields、method_fields、_load_schema_variant |
| 示例校验门禁 | scripts/validate_examples.py | reduce_to_canonical_json、check_coverage、process_block |