by 运行时依赖
安装命令
点击复制技能文档
UCP Checkout — REST 绑定 编写代码前 获取实时规范：在 Web 上搜索 site:ucp.dev specification checkout-rest 并获取当前端点的确切形状、所需头部、请求/响应模式和状态代码的页面。同时，也获取 https://ucp.dev/specification/reference/ 中的所有数据类型定义（Buyer、LineItem、Total、Message 等）。
概念架构 五个 REST 操作
操作 | HTTP 路径 | 是否幂等 -----|----------|---------- 创建 Checkout | POST /checkout-sessions | 是（通过 Idempotency-Key） 获取 Checkout | GET /checkout-sessions/{id} | 自然幂等 更新 Checkout | PUT /checkout-sessions/{id} | 是（完全替换） 完成 Checkout | POST /checkout-sessions/{id}/complete | 是（通过 Idempotency-Key） 取消 Checkout | POST /checkout-sessions/{id}/cancel | 是（通过 Idempotency-Key）
所需头部（每个请求） UCP-Agent：平台的配置文件 URI，在 RFC 8941 结构化字段格式中 — profile="https://..." Idempotency-Key：用于变异操作的 UUID；业务缓存 24+ 小时 Request-Id：用于分布式跟踪的 UUID Request-Signature：用于请求完整性验证的加密签名 Content-Type：application/json
状态状态机 incomplete → requires_escalation → ready_for_complete → complete_in_progress → completed | | | | +---------------+--------------------+----------------------+--------→ canceled
已取消状态可以从任何非终止状态（incomplete、requires_escalation、ready_for_complete、complete_in_progress）到达。 代理的工作是将会话从 incomplete 驱动到 ready_for_complete，通过解决消息，然后调用 complete。
每个响应中的协商 每个响应都包含一个 ucp 对象，带有协商版本和功能。 业务计算其自身功能与平台配置文件的交集，修剪孤立的扩展，并仅返回双方支持的内容。
错误处理模式 响应包含一个 messages 数组。 每个消息都有： type：error / warning / info code：机器可读的错误代码 content：人类可读的描述 severity：recoverable / requires_buyer_input / requires_buyer_review（这些是 3 个正式枚举值；注意：escalation 出现在某些规范部分，但不是正式 severity 枚举的一部分 —— 这是一个规范不一致性） path：指向问题字段的 JSONPath
代理根据严重性行为： recoverable → 代理自动修复（例如，更新缺失的地址） requires_buyer_input → 向人类用户询问 requires_buyer_review → 显示总计/条款以供人类确认 escalation → 重定向到 continue_url
实施清单 业务（商家服务器）： 解析 UCP-Agent 头部并获取平台配置文件以进行协商 验证 Idempotency-Key —— 如果重复则返回缓存响应 创建带有行项的 checkout 会话，计算总计 返回协商的 ucp 对象 + 完整的会话状态 + 消息 处理更新通过重新计算总计、重新验证和更新消息 处理完成通过处理支付凭证并创建订单 处理取消通过清理会话 返回适当的 HTTP 状态代码（201 Created、200 OK、400/409/429 等）
平台（代理客户端）： 在 /.well-known/ucp 中发现业务配置文件 发送带有自身配置文件 URI 的 UCP-Agent 头部 创建 checkout、检查状态和消息 循环：解决消息 → 更新 checkout → 重新检查状态 当 ready_for_complete 时：获取支付凭证并调用 complete 处理 requires_escalation 通过向用户显示 continue_url
货币值 所有金额都是以次要货币单位表示的整数（例如，$29.99 = 2999）。 永远不要使用浮点数。
TLS 要求 所有 UCP REST 端点必须通过 HTTPS 服务，至少使用 TLS 1.3。