# UCP 技能 — 通用商务协议实施 ## 核心原则 1. **不使用 Edge 运行时** — 仅使用 Node.js（默认）或 Bun（选择加入）运行时 2. **交互式错误处理** - 当不明确时，询问用户如何继续 3. **配置驱动** — 所有决策都保留在 `ucp.config.json` 中 4. **基于规范** — 所有实现均参考规范的 UCP 规范 5. **Next.js 约定** — 遵循 App Router 模式进行代码组织 6. **深度分析** — 使用 AST 解析和数据流追踪进行间隙检测 ** ** ## 规范存储库处理 ### 位置优先按此顺序检查： 1. `./ucp/` — 用户的本地副本（按原样使用） 2. `./.ucp-spec/` — 之前克隆的规范（更新它） 3. 两者都不存在——克隆新鲜 ### 克隆过程当需要克隆时： git clone --深度 1 https://github.com/Universal-Commerce-Protocol/ucp.git .ucp-spec 如果 HTTPS 失败，请尝试 SSH： git clone --深度 1 git@github.com:Universal-Commerce-Protocol/ucp.git .ucp-spec ### 更新程序当 `./.ucp-spec/` 存在时： cd .ucp-spec && git pull && cd .. ### Gitignore 管理克隆后，确保“.ucp-spec/”位于“.gitignore”中： * 读取`.gitignore`（如果存在） * 检查 `.ucp-spec/` 或 `.ucp-spec` 是否已列出 * 如果没有，则在新行上附加 `.ucp-spec/` ### 规范文件位置（按需阅读）文档/规范/概述.md 文档/规范/checkout.md 文档/规范/checkout-rest.md 文档/规范/checkout-mcp.md 文档/规范/checkout-a2a.md 文档/规范/embedded-checkout.md 文档/规范/order.md 文档/规范/fulfillment.md 文档/规范/discount.md 文档/规范/买方同意.md 文档/规范/identity-linking.md 文档/规范/ap2-mandates.md 文档/规范/ payment-handler-guide.md 文档/规范/tokenization-guide.md 规格/服务/购物/rest.openapi.json 规范/服务/购物/mcp.openrpc.json 规格/服务/购物/embedded.openrpc.json 规范/处理程序/标记化/openapi.json 规格/模式/购物/* 规范/发现/profile_schema.json ** ** ## 配置文件 ### 地点项目根目录下的`./ucp.config.json` ### 架构 { "$schema": "./ucp.config.schema.json", “ucp_版本”：“2026-01-11”， “角色”：[“业务”]， “运行时”：“nodejs”， “能力”：{ "核心": ["dev.ucp.shopping.checkout"], “扩展”：[] }, “交通”：[“休息”]， “transport_priority”：[“休息”，“mcp”，“a2a”，“嵌入”]， “付款处理程序”：[]， “特点”：{ “ap2_mandates”：假， “identity_linking”：假， “multi_destination_fulfillment”：假 }, “域”：“”， “现有的_api”：{}， “policy_urls”：{ “隐私”：“”， “条款”：“”， “退款”：“”， “运输”：“” }, "scaffold_depth": "完整", “生成的文件”：[]， “答案”：{}， “部署”：{ “平台”：“维塞尔”， “区域”：“iad1”， “MCP”：{ “启用”：假， “最大持续时间”：60 } } } ### 字段说明领域|类型 |描述 ---|---|--- `ucp_版本` |字符串| UCP 规范版本（基于日期） `角色` |字符串[] |以下一项或多项：`business`、`platform`、` payment_provider`、`host_embedded` `运行时` |字符串| `nodejs` （默认）或 `bun` `能力.核心` |字符串[] |实施所需的能力 `功能.扩展` |字符串[] |要实施的可选扩展 `交通` |字符串[] |启用的传输：`rest`、`mcp`、`a2a`、`embedded` `传输优先级` |字符串[] |实施运输的命令 `付款处理程序` |字符串[] |支持的支付处理程序 ID `features.ap2_mandates` |布尔 |启用 AP2 授权签名 `features.identity_linking` |布尔 |启用 OAuth 身份链接 `features.multi_destination_fulfillment` |布尔 |启用多目的地运输 `域` |字符串| `/.wellknown/ucp` 的业务域 `现有的_api` |对象|要分析的现有 API 端点图 `policy_urls` |对象|隐私、条款、退款、运输政策的 URL `脚手架深度` |字符串| `类型` | `脚手架` | ‘满’ `生成的文件` |字符串[] |脚手架创建的文件（用于跟踪） `答案` |对象|合格问题的原始答案 ** ** ## 子命令：（无参数） ### 触发器用户运行“/ucp”，不带子命令 ### 行为显示列出所有可用子命令的帮助： UCP 技能 — 通用商务协议实施可用命令： /ucp init — 在此项目中初始化 UCP（克隆规范，创建配置） /ucp Consult — 全面咨询：回答合格问题，构建路线图 /ucp plan — 生成详细的实施计划 /ucp gaps — 根据 UCP 要求分析现有代码 /ucp 脚手架 — 生成完整的 UCP 实现 /ucp validate — 根据 UCP 模式验证实施 /ucp profile — 生成 /.well-known/ucp 发现配置文件 /ucp test — 为 UCP 处理程序生成单元测试 /ucp docs — 生成内部文档典型工作流程： /ucp init → /ucp 咨询 → /ucp 计划 → /ucp 脚手架 → /ucp 配置文件 → /ucp 测试 → /ucp 验证配置：./ucp.config.json 规范位置：./ucp/ 或 ./.ucp-spec/ ** ** ## 子命令：init ### 触发器用户运行“/ucp init” ### 目的在项目中引导 UCP：克隆规范、创建配置、提出基本问题。 ### 程序 #### 第 1 步：检查/克隆规范存储库 1.检查`./ucp/`是否存在 * 如果是：“在 ./ucp/ 找到本地 UCP 规范” 2.如果不存在，检查`./.ucp-spec/`是否存在 * 如果是：运行 `git pull` 进行更新 * 如果不是：克隆存储库（请参阅规范存储库处理） 3.克隆后，将`.ucp-spec/`添加到`.gitignore` #### 步骤 2：检查现有配置 1.检查`./ucp.config.json`是否存在 2. 如果是，询问：“配置文件存在。覆盖、合并还是中止？” * 覆盖：删除并创建新的 * 合并：保留现有值作为默认值 * 中止：停止初始化 #### 第 3 步：提出基本问题（4 个问题） **问题1：您正在扮演什么角色？** * 商业（记录商人） * 平台（消费者应用程序或代理） * 支付凭证提供商 * 主机嵌入结账 * 多个（指定）如果用户选择多个角色，则警告： > “实施多个角色是不寻常的。这通常适用于市场/聚合器场景。您确定吗？” **问题2：您将使用什么运行时？** * Node.js（推荐，稳定） * Bun（选择加入，实验性）注意：如果用户提到 Edge，请回复： > “UCP 实现不支持 Edge 运行时。请选择 Node.js 或 Bun。” **问题3：您的业务领域是什么？** * 将托管 `/.well-known/ucp` 的域 * 示例：`shop.example.com` **问题 4：发布时您需要哪些交通工具？** * REST（推荐基线） * MCP（模型上下文协议） * A2A（代理对代理） * 嵌入（iframe结帐） #### 步骤 4：创建配置文件使用以下命令创建 `./ucp.config.json`： * 基本问题的答案 * 其他字段的合理默认值 * `ucp_version` 设置为规范中的最新版本 #### 步骤 5：输出就绪消息 UCP初始化成功！配置：./ucp.config.json 规格：./.ucp-spec/（或./ucp/）角色：{角色} 域：{域} 后续步骤： /ucp Consult — 完成全面咨询（推荐） /ucp plan — 跳至实施计划 /ucp差距——首先分析现有代码 ** ** ## 子命令：咨询 ### 触发器用户运行“/ucp Consult” ### 目的完成所有 12 个资格问题、更新配置、生成实施路线图。 ### 先决条件 * 配置文件必须存在（首先运行`/ucp init`） * 规格必须可用 ### 程序 #### 第 1 步：加载现有配置阅读 `./ucp.config.json` 并使用现有答案作为默认值。 #### 第 2 步：完成 12 个合格问题问每个问题。如果已在配置中回答，则显示当前值并要求确认或更改。 **问题1：我们是在实施业务端、平台端还是两者？** * 映射到配置中的“角色” * 如果两个/多个，警告异常情况 **问题 2：哪个 UCP 版本以及哪些功能/扩展在范围内？** * 从规范中读取可用版本 * 现有功能选项： * 核心：`dev.ucp.shopping.checkout`（必填） * 扩展： * `dev.ucp.shopping.fulfillment` * `dev.ucp.shopping.discount` * `dev.ucp.shopping.buyer_consent` * `dev.ucp.shopping.ap2_mandate` * `dev.ucp.shopping.order` * `dev.ucp.common.identity_linking` **问题 3：我们需要哪些支付处理程序？** * 钱包（Apple Pay、Google Pay） * PSP 代币化（Stripe、Adyen 等） * 自定义处理程序 * 还没有（稍后决定） **问题 4：我们需要 AP2 授权并签署关键基础设施吗？** * 是 → 设置 `features.ap2_mandates: true` * 否 → 设置 `features.ap2_mandates: false` * 如果是，请解释：“您需要提供 JWS 签名密钥（推荐 ES256）” **问题 5：我们需要履行选项和多组/多目的地支持吗？** * 无需履行 * 仅限单一目的地 * 多目的地支持 → 设置 `features.multi_destination_fulfillment: true` **问题 6：我们需要折扣、买家同意获取或身份链接吗？** * 折扣 → 将 `dev.ucp.shopping.discount` 添加到扩展中 * 买家同意 → 将 `dev.ucp.shopping.buyer_consent` 添加到扩展中 * 身份链接 → 添加 `dev.ucp.common.identity_linking`，设置 `features.identity_linking: true` **问题7：我们应该将哪些现有结账和订单 API 映射到 UCP？** * 询问现有的端点路径 * 存储在`existing_apis`对象中 * 示例：`/api/checkout`、`/api/cart`、`/api/orders` **问题 8：所需的策略 URL 是什么？** * 隐私政策网址 * 服务条款网址 * 退款政策网址 * 运输政策 URL * 存储在`policy_urls`对象中 **问题9：结帐端点需要什么身份验证模型？** * 无（匿名结帐） * API密钥 * OAuth 2.0 * 基于会话 * 存储在 `answers.authentication_model` 中 **问题 10：谁将收到订单 Webhooks 以及需要什么事件节奏？** * 订单事件的 Webhook URL * 需要的事件类型：`order.created`、`order.updated`、`order.fulfilled`、`order.canceled` * 存储在 `answers.webhook_config` 中 **问题 11：我们需要在发布时支持 MCP、A2A 或嵌入式结帐吗？** * 确认/更新`transports`数组 * 设置`transport_priority`顺序 **问题 12：将托管 /.well-known/ucp 的业务域是什么？** * 确认/更新`domain`字段 #### 步骤 3：更新配置将所有答案写入“./ucp.config.json” #### 步骤 4：生成实施路线图根据答案，制定路线图： UCP 实施路线图 ========================= 角色：商业（商人）版本：2026-01-11 域名：shop.example.com 实施能力： ✓ dev.ucp.shopping.checkout（核心） ✓ dev.ucp.shopping.fulfillment ✓ dev.ucp.shopping.discount ○ dev.ucp.shopping.order 交通（按顺序）： 1. 休息 2、MCP 付款处理程序： - 条纹标记化重点实施任务： 1. 创建/.well-known/ucp 发现配置文件 2. 实现结帐会话端点（创建、获取、更新、完成） 3. 实施履行选项逻辑 4. 实施折扣码申请 5. 设置支付处理程序集成 6. 实施订单 webhook 7.添加MCP传输层估计要创建/修改的文件：~15-20 运行 /ucp plan 获取详细的逐个文件计划。 ** ** ## 子命令：计划 ### 触发器用户运行“/ucp plan” ### 目的生成包含特定文件和操作顺序的详细实施计划。 ### 先决条件 * 配置文件必须存在且已完成咨询 * 规格必须可用 ### 程序 #### 第 1 步：加载配置和规格 * 读取`./ucp.config.json` * 根据功能/传输读取相关规格文件 #### 步骤 2：分析现有代码库结构 * 检测 Next.js 版本（App Router 与 Pages Router） * 查找已有的API路由 * 查找现有的lib/utils结构 * 查找现有类型/模式 * 识别包管理器（npm、yarn、pnpm、bun） #### 步骤 3：生成归档计划对于每个功能/传输，列出要创建/修改的文件。 **输出示例：** UCP实施计划 ======================= 第一阶段：核心类型和模式 ------------------------------------------- 创建 lib/ucp/types/checkout.ts - CheckoutSession接口 - 行项目、总计、付款类型 - 状态枚举创建 lib/ucp/types/index.ts - 重新导出所有类型创建 lib/ucp/schemas/checkout.ts - 用于验证的 Zod 模式第 2 阶段：发现概况 -------------------------- 创建 app/.wellknown/ucp/route.ts - GET 处理程序返回配置文件 JSON - 从配置中读取功能创建 lib/ucp/profile.ts - 配置文件生成逻辑第 3 阶段：结帐端点 (REST) ---------------------------------- 创建 app/api/ucp/checkout/route.ts - POST：创建结帐会话 - 能力协商逻辑创建 app/api/ucp/checkout/[id]/route.ts - GET：检索结帐 - 补丁：更新结帐 - POST：完成结账（操作=完成）创建 lib/ucp/handlers/checkout.ts - 结帐操作的业务逻辑 - 状态机实现第四阶段：履行扩展 ------------------------------------------ 创建 lib/ucp/handlers/fulfillment.ts - 履行选项计算 - 目的地验证修改 lib/ucp/handlers/checkout.ts - 将履行集成到结帐响应中第五阶段：折扣延期 ---------------------------- 创建 lib/ucp/handlers/discount.ts - 折扣代码验证 - 应用折扣计算修改 lib/ucp/handlers/checkout.ts - 将折扣整合到结帐中第六阶段：支付整合 ---------------------------- 创建 lib/ucp/handlers/ payment.ts - 支付处理程序注册表 - 支付数据处理创建 lib/ucp/handlers/stripe.ts - 特定于条带的标记化第 7 阶段：订购 Webhook ----------------------- 创建 lib/ucp/handlers/order.ts - 订单事件发射 - Webhook 签名 (JWS) 创建 lib/ucp/webhooks/sender.ts - 带重试的 Webhook 交付第 8 阶段：MCP 传输（如果启用） ----------------------------------- 创建 lib/ucp/transports/mcp.ts - MCP工具定义 - JSON-RPC 处理程序要安装的依赖项： ------------------------ zod — 模式验证 jose — JWS 签名（如果启用了 AP2/webhooks）运行 /ucpscaffold 来生成这些文件。 #### 步骤 4：将计划保存到配置将计划存储在“answers.implementation_plan”中以供脚手架参考。 ** ** ## 子命令：间隙 ### 触发器用户运行“/ucp间隙” ### 目的根据 UCP 要求深入分析现有代码库。使用 AST 解析和数据流跟踪。 ### 先决条件 * 配置文件应该存在（用于角色/能力上下文） * 规格必须可用 ### 程序 #### 第 1 步：加载上下文 * 读取配置以获取声明的功能 * 阅读相关规格文件 #### 第 2 步：发现现有代码扫描： * API 路由（`app/api/**`、`pages/api/**`） * 结帐相关文件（搜索“结帐”、“购物车”、“订单”） * 支付处理代码 * 网络钩子的实现 #### 步骤 3：深度分析（基于 AST）对于每个相关文件： * 解析AST * 跟踪结帐对象的数据流 * 识别现有模式 **根据 UCP 要求进行分析：** 要求 |状态 |寻找 ---|---|--- 发现简介位于 /.wellknown/ucp |失踪|没有找到路线结帐会话创建 |部分|找到 /api/checkout 但缺少 UCP 字段状态生命周期 |失踪|无状态状态机能力洽谈|失踪|无 UCP-Agent 标头处理付款处理程序支持 |部分| Stripe 存在但不符合 UCP 响应元数据（ucp 对象）|失踪|响应不包含 ucp 字段 #### 步骤 4：生成差距报告 UCP 差距分析报告 ======================= 现有代码库：Next.js 14（应用程序路由器）目标角色：商业目标功能：结账、履行、折扣关键差距（必须修复） ------------------------ [GAP-001] 缺少发现配置文件 - 必需：/.wellknown/ucp 端点 - 状态：未找到 - 修复：创建 app/.well-known/ucp/route.ts [GAP-002] 缺少 UCP 响应信封 - 必需：所有响应必须包含具有版本/功能的“ucp”对象 - 发现：app/api/checkout/route.ts 返回原始结账数据 - 修复：使用 UCP 元数据包装响应 [GAP-003] 缺少能力协商 - 必需：读取 UCP-Agent 标头，计算交集 - 发现：结账路线中没有标头处理 - 修复：添加中间件或处理程序逻辑部分实现 ----------------------- [PARTIAL-001] 结账会话存在但不合规 - 文件：app/api/checkout/route.ts - 缺少：id、状态、货币、totals.grand_total、链接、付款字段 - 具有：line_items（需要架构调整） [PARTIAL-002] 存在支付集成 - 文件：lib/stripe.ts - 问题：直接 Stripe API，而不是 UCP payment_data 流 - 修复：使用 UCP 支付处理程序抽象进行包装合规领域 ---------------- [确定] 在现有结帐中配置的策略 URL [确定] 强制执行 HTTPS [确定] POST 处理程序中的幂等性密钥支持建议 ---------------- 1.从/ucp脚手架开始生成合规结构 2. 将现有结账逻辑迁移到新的处理程序中 3. 迁移后运行 /ucp validate 总计：3 个关键差距、2 个部分差距、3 个合规差距 ** ** ## 子命令：脚手架 ### 触发器用户运行“/ucpscaffold” ### 目的根据配置和计划生成完整的 UCP 实施。 ### 先决条件 * 配置文件必须存在 * 计划应该存在（首先运行`/ucp plan`，否则脚手架会生成一个） ### 程序 #### 第 1 步：确认脚手架深度询问用户： >“您想要什么级别的代码生成？” > > * **类型** ：仅限 TypeScript 接口和 Zod 模式 > * **脚手架** ：带有用于业务逻辑的 TODO 标记的结构 > * **完整** ：完整的工作实施（推荐） > 将选择存储在“config.scaffold_depth”中 #### 第 2 步：检查依赖关系根据配置确定所需的包： * `zod` — 总是需要的 * `jose` — 如果 AP2 强制要求或启用了 Webhook 签名 * `uuid` — 用于生成会话 ID 安装前询问： > “需要以下软件包：zod、jose、uuid” “现在安装吗？（npm install / Bun add）” 如果是，请运行适当的安装命令。 #### 步骤 3：生成代码根据计划生成文件。对于每个文件： 1. 如果需要创建父目录 2.写入文件内容 3. 跟踪`config. generated_files` ### 代码生成模板 #### lib/ucp/types/checkout.ts /** * UCP 结帐类型 * 由 /ucp 脚手架生成 * 规格：{spec_version} */ 导出类型 CheckoutStatus = | “不完整” | '需要升级' | '准备完成' | '完成中' | ‘完成’ | '取消'; 导出类型消息严重性= | “可恢复” | '需要买家输入' | '需要买家评论'；导出接口 UCPMetadata { 版本：字符串；功能：字符串[]； } 导出接口 LineItem { id：字符串；名称：字符串；数量：数量；单价：数量；总价：数量；货币：字符串； // 根据配置添加扩展字段 } 导出接口总计{ 小计：数量；税：数量；运输：数量；折扣：数量； grand_total：数量；货币：字符串； } 导出接口PaymentInfo { 状态：'待定' | '授权' | '捕获' | '失败的'; 处理程序：PaymentHandler[]； amount_due：数量；货币：字符串； } 导出接口PaymentHandler { id：字符串；类型：字符串；配置？：记录<字符串，未知>； } 导出接口 CheckoutMessage { 代码：字符串；严重性：消息严重性；消息：字符串；字段？：字符串； } 导出接口 CheckoutLinks { 自我：字符串； continue_url?: 字符串；隐私政策：字符串；服务条款：字符串；退款政策？：字符串； Shipping_policy？：字符串； } 导出接口 CheckoutSession { ucp：UCP元数据； id：字符串；状态：结帐状态；货币：字符串； line_items: LineItem[]; 总计：总计；付款：付款信息；链接：结账链接；消息：CheckoutMessage[]；过期时间：字符串；创建于：字符串； update_at：字符串； // 根据协商的功能填充扩展字段买家？：买家信息；履行？：履行信息；折扣？：折扣信息； } 导出接口BuyerInfo { 电子邮件？：字符串；电话？：字符串；名称？：字符串； // 如果 Buyer_consent 扩展已启用，则同意字段 } // 基于扩展的条件类型... #### lib/ucp/schemas/checkout.ts /** * UCP Checkout Zod 模式 * 由 /ucp 脚手架生成 */ 从 'zod' 导入 { z }；导出 const LineItemSchema = z.object({ id: z.string(), 名称： z.string(), 数量：z.number().int().positive(), unit_price: z.number().int(), // 小单位（美分）总价格： z.number().int(), 货币：z.string().length(3), }); 导出 const TotalsSchema = z.object({ 小计：z.number().int(), 税：z.number().int(), 运输： z.number().int(), 折扣：z.number().int(), grand_total: z.number().int(), 货币：z.string().length(3), }); 导出 const CreateCheckoutRequestSchema = z.object({ line_items: z.array(LineItemSchema).min(1), 货币：z.string().length(3), 买家：z.object({ 电子邮件：z.string().email().可选()，电话：z.string().可选()， }).可选(), // 扩展字段... }); 导出 const UpdateCheckoutRequestSchema = z.object({ line_items: z.array(LineItemSchema).可选(), 买家：z.object({ 电子邮件：z.string().email().可选()，电话：z.string().可选()， }).可选(), // 扩展字段... }); 导出 const CompleteCheckoutRequestSchema = z.object({ 动作：z.literal('完整'), payment_data: z.record(z.unknown()), }); 导出类型 CreateCheckoutRequest = z.infer; 导出类型 UpdateCheckoutRequest = z.infer; 导出类型 CompleteCheckoutRequest = z.infer; #### 应用程序/.wellknown/ucp/route.ts /** * UCP 发现配置文件端点 * GET /.wellknown/ucp * 由 /ucp 脚手架生成 */ 从'next/server'导入{NextResponse}；从'@/lib/ucp/profile'导入{generateProfile}；导出常量运行时='nodejs'; // 不支持边缘运行时导出异步函数 GET() { const 配置文件=generateProfile(); 返回 NextResponse.json(个人资料, { 标题：{ '缓存控制'：'公共，最大年龄= 3600'， '内容类型'：'应用程序/json'， }, }); } #### lib/ucp/profile.ts /** * UCP 发现配置文件生成器 * 由 /ucp 脚手架生成 */ 从'@/../ucp.config.json'导入配置；导出接口 UCPProfile { UCP：{ 版本：字符串；服务：记录<字符串，服务定义>；能力：CapabilityDefinition[]； }; 付款？：{ 处理程序：PaymentHandlerDefinition[]； }; 签名密钥？：JsonWebKey[]； } 接口服务定义{ 版本：字符串；规格：字符串；休息？：{ 模式：字符串；端点：字符串}； mcp？：{ 模式：字符串；端点：字符串}； a2a?: { 端点: 字符串 }; 嵌入？：{模式：字符串}； } 接口能力定义{ 名称：字符串；版本：字符串；规格：字符串；模式：字符串；延伸？：字符串；配置？：记录<字符串，未知>； } 接口 PaymentHandlerDefinition { id：字符串；类型：字符串；规格：字符串；配置模式：字符串； } 导出函数generateProfile(): UCPProfile { const baseUrl = `https://${config.domain}`; 常量配置文件：UCPProfile = { UCP：{ 版本：config.ucp_version，服务：{ 'dev.ucp.shopping': { 版本：config.ucp_version，规格：'https://ucp.dev/spec/services/shopping', ...(config.transports.includes('rest') && { 休息：{ 模式：'https://ucp.dev/spec/services/shopping/rest.openapi.json'，端点：`${baseUrl}/api/ucp`， }, }), ...(config.transports.includes('mcp') && { MCP：{ 架构：'https://ucp.dev/spec/services/shopping/mcp.openrpc.json'，端点：`${baseUrl}/api/ucp/mcp`， }, }), ...(config.transports.includes('a2a') && { a2a：{ 端点：`${baseUrl}/api/ucp/a2a`， }, }), ...(config.transports.includes('嵌入') && { 嵌入：{ 模式：'https://ucp.dev/spec/services/shopping/embedded.openrpc.json'， }, }), }, }, 功能：构建功能（配置）， }, }; if (config. payment_handlers.length > 0) { 个人资料.付款= { 处理程序：config. payment_handlers.map(buildHandlerDefinition), }; } 返回个人资料； } 函数 buildCapability(config: typeof import('@/../ucp.config.json')): CapabilityDefinition[] { const 能力：CapabilityDefinition[] = []； // 核心结帐功能（始终存在）功能.push({ 名称: 'dev.ucp.shopping.checkout', 版本：config.ucp_version，规范：'https://ucp.dev/spec/capability/checkout'，架构：'https://ucp.dev/spec/schemas/shopping/checkout.json'， }); // 根据配置添加扩展 for (config.capability.extensions 的 const ext) { 功能.push(buildExtensionCapability(ext, config)); } 返回能力； } 函数构建扩展能力（扩展名：字符串，配置： typeof import('@/../ucp.config.json') ): 能力定义 { // 将扩展名称映射到规范 URL const extMap: Record = { 'dev.ucp.shopping.fulfillment': { 规格：'https://ucp.dev/spec/capability/fulfillment'，架构：'https://ucp.dev/spec/schemas/shopping/fulfillment.json'，扩展：'dev.ucp.shopping.checkout'， }, 'dev.ucp.shopping.discount': { 规格：'https://ucp.dev/spec/capability/discount'，模式：'https://ucp.dev/spec/schemas/shopping/discount.json'，扩展：'dev.ucp.shopping.checkout'， }, 'dev.ucp.shopping.buyer_consent': { 规格：'https://ucp.dev/spec/capability/buyer-consent'，模式：'https://ucp.dev/spec/schemas/shopping/buyer-consent.json'，扩展：'dev.ucp.shopping.checkout'， }, 'dev.ucp.shopping.order': { 规范：'https://ucp.dev/spec/capability/order'，架构：'https://ucp.dev/spec/schemas/shopping/order.json'，配置：{ webhook_url: config.answers?.webhook_config?.url, }, }, 'dev.ucp.common.identity_linking': { 规范：'https://ucp.dev/spec/capability/identity-linking'，架构：'https://ucp.dev/spec/schemas/common/identity-linking.json'， }, }; const def = extMap[扩展名]; 返回{ 名称：扩展名，版本：config.ucp_version，规格：def?.规格|| '', 架构：def?.schema || '', ...(def?.extends && { 扩展: def.extends }), ...(def?.config && { 配置: def.config }), }; } 函数 buildHandlerDefinition(handlerId: string): PaymentHandlerDefinition { // 映射已知处理程序 const handlerMap: Record> = { 条纹：{ 类型：'标记化'，规格：'https://ucp.dev/spec/handlers/stripe', config_schema: 'https://ucp.dev/spec/handlers/stripe/config.json', }, // 根据需要添加更多处理程序 }; const def = handlerMap[handlerId] || { 类型：'自定义'，规格：''，配置模式：''， }; 返回 { id: handlerId, ...def }; } #### 应用程序/api/ucp/checkout/route.ts /** * UCP 结账会话端点 * POST /api/ucp/checkout - 创建结帐会话 * 由 /ucp 脚手架生成 */ 从 'next/server' 导入 { NextRequest, NextResponse }; 从'@/lib/ucp/handlers/checkout'导入{createCheckout}；从 '@/lib/ucp/schemas/checkout' 导入 { CreateCheckoutRequestSchema }；从 '@/lib/ucp/negotiation' 导入 { negotiation, parseUCPAgent }; 从'@/lib/ucp/response'导入{wrapResponse，errorResponse}；导出常量运行时='nodejs'; // 不支持边缘运行时导出异步函数 POST(request: NextRequest) { 尝试{ // 解析 UCP-Agent 标头以进行能力协商 const ucpAgent = parseUCPAgent(request.headers.get('UCP-Agent')); // 协商能力 const 协商 = 等待协商能力(ucpAgent?.profile); // 解析并验证请求体 const body =等待request.json(); const parsed = CreateCheckoutRequestSchema.safeParse(body); if (!parsed.success) { 返回 errorResponse(400, 'invalid_request', parsed.error.message); } // 获取幂等密钥 const idempotencyKey = request.headers.get('幂等性密钥'); // 创建结账会话 const checkout = 等待 createCheckout(parsed.data, { 能力：谈判能力，幂等性密钥， }); 返回wrapResponse（结账，协商，201）； } 捕获（错误）{ console.error('结账创建失败:', error); return errorResponse(500, 'internal_error', '创建结帐会话失败'); } } #### lib/ucp/handlers/checkout.ts /** * UCP 结账处理程序 * 结帐操作的核心业务逻辑 * 由 /ucp 脚手架生成 */ 从 'crypto' 导入 { randomUUID }; 导入类型{ 结账会话，结账状态，创建结账请求，更新结账请求，来自“@/lib/ucp/types/checkout”；从'@/../ucp.config.json'导入配置； // 用于演示的内存存储 - 替换为您的数据库 const checkoutStore = new Map<字符串, CheckoutSession>(); 接口CreateCheckoutOptions { 功能：字符串[]；幂等性密钥？：字符串 |无效的; } 导出异步函数createCheckout( 请求：创建结账请求，选项：CreateCheckoutOptions ): Promise { const id = randomUUID(); const now = new Date().toISOString(); const expiresAt = new Date(Date.now() + 30 * 60 * 1000).toISOString(); // 30 分钟 // 计算总数 const subtotal = request.line_items.reduce((sum, item) => sum + item.total_price, 0); 常量税=计算税（小计）； // 实现你的税务逻辑常量运费= 0； // 通过履行扩展设置常量折扣= 0； // 通过折扣扩展设置常量结账：CheckoutSession = { UCP：{ 版本：config.ucp_version，功能：选项.功能， }, 身份证号，状态：“不完整”，货币：请求.货币， line_items: request.line_items.map((item, index) => ({ ...项目， id: 项目.id || `行_${索引}`, }）），总计：{ 小计，税，运输，折扣， grand_total：小计+税+运费-折扣，货币：请求.货币， }, 付款方式：{ 状态：'待定'，处理程序：getPaymentHandlers（选项.功能）， amount_due：小计+税+运费-折扣，货币：请求.货币， }, 链接：{ self: `https://${config.domain}/api/ucp/checkout/${id}`, continue_url: `https://${config.domain}/checkout/${id}`, 隐私策略：config.policy_urls.privacy，服务条款：config.policy_urls.terms， ...(config.policy_urls.refunds && {refund_policy: config.policy_urls.refunds }), ...(config.policy_urls.shipping && {shipping_policy: config.policy_urls.shipping }), }, 消息：[]，过期时间：过期时间，创建时间：现在，更新时间：现在， }; // 添加买家信息（如果提供） if (请求.买家) { 结账.买家 = 请求.买家; } // 验证结帐状态并设置适当的状态 checkout.status = 确定状态(checkout); checkout.messages =generateMessages(checkout); // 商店结账 checkoutStore.set(id, 结帐); 返回结账； } 导出异步函数 getCheckout(id: string): Promise { 返回 checkoutStore.get(id) ||无效的; } 导出异步函数 updateCheckout( id：字符串，请求：更新结账请求，功能：字符串[] ): Promise { const checkout = checkoutStore.get(id); if (!checkout) 返回 null； // 检查结帐是否可以修改 if (['已完成', '已取消'].includes(checkout.status)) { throw new Error('当前状态下无法修改结账'); } // 应用更新 if (request.line_items) { checkout.line_items = request.line_items; 重新计算总计（结账）； } if (请求.买家) { checkout.buyer = { ...checkout.buyer, ...request.buyer }; } // 更新元数据 checkout.updated_at = new Date().toISOString(); checkout.ucp.capability = 功能； checkout.status = 确定状态(checkout); checkout.messages =generateMessages(checkout); checkoutStore.set(id, 结帐); 返回结账； } 导出异步函数completeCheckout( id：字符串， paymentData：记录<字符串，未知>，功能：字符串[] ): Promise { const checkout = checkoutStore.get(id); if (!checkout) 返回 null； if (checkout.status !== 'ready_for_complete') { throw new Error('结帐尚未准备好完成'); } checkout.status = 'complete_in_progress'; checkout.updated_at = new Date().toISOString(); checkoutStore.set(id, 结帐); 尝试{ // 处理付款等待流程付款（结帐，付款数据）； checkout.status = '已完成'; checkout. payment.status = '已捕获'; checkout.updated_at = new Date().toISOString(); checkoutStore.set(id, 结帐); // 如果订单功能启用，则发出订单事件 if (capability.includes('dev.ucp.shopping.order')) { 等待emitOrderCreated（结帐）； } 返回结账； } 捕获（错误）{ checkout.status = '不完整'; checkout. payment.status = '失败'; 结帐.messages.push({ 代码：'付款失败'，严重性：“可恢复”，消息：错误实例错误？ error.message : '付款处理失败', }); checkout.updated_at = new Date().toISOString(); checkoutStore.set(id, 结帐); 返回结账； } } 函数确定状态（结账：CheckoutSession）：CheckoutStatus { // 检查是否缺少必填字段 const MissingFields: string[] = []; if (!checkout.buyer?.email) { MissingFields.push('买家.email'); } // 如果启用了扩展，则检查履行情况 if (checkout.fulfillment && !checkout.fulfillment.selected_option) { MissingFields.push('fulfillment.selected_option'); } if (missingFields.length > 0) { 返回“不完整”； } // 检查是否需要买家输入 if (checkout.messages.some(m => m.severity === 'requires_buyer_input')) { 返回“需要升级”； } 返回“准备完成”； } 函数generateMessages(checkout: CheckoutSession): CheckoutSession['messages'] { const messages: CheckoutSession['messages'] = []; if (!checkout.buyer?.email) { 消息.push({ 代码： 'missing_email', 严重性：“可恢复”， message: '需要买家电子邮件', 字段: '买家.电子邮件', }); } 返回消息； } 函数重新计算Totals（结账：CheckoutSession）：无效{ const subtotal = checkout.line_items.reduce((sum, item) => sum + item.total_price, 0); checkout.totals.subtotal = 小计； checkout.totals.tax =calculateTax(小计); checkout.totals.grand_total = 小计 + checkout.totals.tax + checkout.totals.shipping - checkout.totals.discount; checkout. payment.amount_due = checkout.totals.grand_total; } 函数calculateTax（小计：数字）：数字{ // 实现你的税收计算逻辑 return Math.round(小计 * 0.08); // 示例：8% 税 } 函数 getPaymentHandlers(功能：字符串[]): CheckoutSession['付款']['处理程序'] { // 返回配置的支付处理程序返回 config. payment_handlers.map(id => ({ 身份证号，类型：'标记化'， })); } 异步函数 processPayment( 结账：结账会话， paymentData：记录<字符串，未知> ): 承诺 { // 根据广告处理程序验证 handler_id const handlerId = paymentData.handler_id 作为字符串； if (!config. payment_handlers.includes(handlerId)) { throw new Error(`未知的支付处理程序：${handlerId}`); } // 基于handler实现支付处理 // 这是与 Stripe 等集成的地方。 } 异步函数 emitOrderCreated(checkout: CheckoutSession): Promise { // 实现订单 webhook 发射 // 参见 lib/ucp/webhooks/sender.ts } #### lib/ucp/negotiation.ts /** * UCP能力协商 * 由 /ucp 脚手架生成 */ 从'@/../ucp.config.json'导入配置；接口 UCPAgentInfo { 配置文件：字符串； } 接口协商结果{ 功能：字符串[]；版本：字符串； } /** * 解析 UCP-Agent 标头（RFC 8941 字典语法） * 示例：profile="https://platform.example.com/.well-known/ucp" */ 导出函数 parseUCPAgent(header: string | null): UCPAgentInfo |空{ if (!header) 返回 null； const profileMatch = header.match(/profile="([^"]+)"/); if (!profileMatch) 返回 null；返回 { 个人资料：profileMatch[1] }; } /** * 业务和平台之间协商能力 */ 导出异步函数协商能力（ platformProfileUrl？：字符串 ): Promise<协商结果> { // 业务能力 const 业务能力 = new Set([ ...config.capability.core, ...config.capability.extensions， ]); if (!platformProfileUrl) { // 无平台简介-返回所有业务能力返回{ 能力：Array.from(businessCapability), 版本：config.ucp_version， }; } 尝试{ // 获取平台配置文件 const 响应 = 等待 fetch(platformProfileUrl, { headers: { 接受: 'application/json' }, }); 如果（！response.ok）{ console.warn(`无法获取平台配置文件：${response.status}`); 返回{ 能力：Array.from(businessCapability), 版本：config.ucp_version， }; } const platformProfile = 等待response.json(); // 验证命名空间权限 const profileUrl = 新 URL(platformProfileUrl); // 平台控制自己的域 - 信任它 // 计算交集 const 平台功能 = new Set( platformProfile.ucp?.capability?.map((c: { name: string }) => c.name) || [] ）； const 交集 = [...businessCapability].filter(c => 平台功能.has(c) ）； // 版本协商-接受平台版本 <= 商业版本 const platformVersion = platformProfile.ucp?.version; if (platformVersion && platformVersion > config.ucp_version) { 抛出新错误（'version_unsupported'）； } 返回{ 能力：交叉点，版本：config.ucp_version， }; } 捕获（错误）{ console.error('能力协商失败:', error); // 回到业务能力返回{ 能力：Array.from(businessCapability), 版本：config.ucp_version， }; } } #### lib/ucp/response.ts /** * UCP 响应助手 * 由 /ucp 脚手架生成 */ 从'next/server'导入{NextResponse}；从 './negotiation' 导入类型 { NegotiationResult }； /** * 使用 UCP 元数据包装响应 */ 导出函数wrapResponse （数据：T，协商：协商结果，状态：数量 = 200 ): 下一个响应 { // 确保 ucp 元数据存在常量响应 = { ...数据， UCP：{ 版本：协商版本，能力：谈判能力， }, }; 返回 NextResponse.json(response, { status }); } /** * 创建错误响应 */ 导出函数错误响应（状态：数量，代码：字符串，消息：字符串，详细信息？：记录<字符串，未知> ): 下一个响应 { 返回 NextResponse.json( { 错误：{ 代码，留言， ...（详细信息&&{详细信息}）， }, }, { 状态 } ）； } ### MCP 传输代码模板（使用 mcp-handler）当在配置中启用 MCP 传输时，生成这些附加文件。 #### MCP 传输的依赖关系 npm 安装 mcp-handler @modelcontextprotocol/sdk@1.25.2 zod **重要：** 使用 `@modelcontextprotocol/sdk@1.25.2` 或更高版本 - 早期版本存在安全漏洞。 #### 应用程序/api/mcp/[传输]/route.ts /** * UCP MCP 传输端点 * 用于 UCP 结帐操作的模型上下文协议服务器 * 由 /ucp 脚手架生成 * * 支持： * - 可流式 HTTP 传输（直接客户端连接） * - SSE 传输（通过 mcp-remote 桥） * * @参见 https://github.com/vercel/mcp-handler */ 从“mcp-handler”导入{createMcpHandler}；从 'zod' 导入 { z }；导入{ 创建结账，结账，更新结账，完成结账，来自“@/lib/ucp/handlers/checkout”；从 '@/lib/ucp/negotiation' 导入 { negotiation } ；从'@/lib/ucp/profile'导入{generateProfile}；从'@/../ucp.config.json'导入配置；导出常量运行时='nodejs'; // 不支持边缘运行时常量处理程序 = createMcpHandler( （服务器）=> { // ============================================================================= // UCP 发现 // ============================================================================= 服务器.注册工具( 'ucp_get_profile', { title: '获取 UCP 配置文件', 描述：'检索该业务的 UCP 发现配置文件。返回支持的功能、传输和支付处理程序。', 输入架构：{}， }, 异步（）=> { const 配置文件=generateProfile(); 返回{ 内容：[ { 类型：'文本'，文本： JSON.stringify(profile, null, 2), }, ], }; } ）； // ============================================================================= // 结帐会话管理 // ============================================================================= 服务器.注册工具( 'ucp_create_checkout', { title: '创建结帐会话', 描述：'使用订单项创建新的 UCP 结账会话。返回一个结帐会话，其中包含 ID、状态、总计和可用的付款处理程序。', 输入架构：{ line_items: z.array( z. 对象({ id: z.string().optional().describe('订单项的唯一标识符'), name: z.string().describe('产品名称'), 数量： z.number().int().positive().describe('订购数量'), unit_price: z.number().int().describe('以小单位表示的每单位价格（美分）'), total_price: z.number().int().describe('该行总价(数量*unit_price)'), 货币: z.string().length(3).describe('ISO 4217 货币代码'), }) ).min(1).describe('结帐中的商品数组'), 货币： z.string().length(3).describe('结帐的 ISO 4217 货币代码'), 买家：z.object({ email: z.string().email().optional().describe('买家邮箱地址'), 电话：z.string().可选().describe('买家电话号码'), name: z.string().optional().describe('买家全名'), }).可选().describe('买家信息'), platform_profile_url: z.string().url().optional().describe('用于能力协商的平台 UCP 配置文件的 URL'), }, }, 异步 ({ line_items, 货币, 买家, platform_profile_url }) => { 尝试{ // 协商能力 const 协商 = 等待协商能力(platform_profile_url); const checkout = 等待 createCheckout( { line_items, 货币, 买家 }, { 能力：谈判.能力 } ）；返回{ 内容：[ { 类型：'文本'，文本： JSON.stringify(checkout, null, 2), }, ], }; } 捕获（错误）{ 返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 错误：{ 代码：'checkout_creation_failed'，消息：错误实例错误？ error.message : '未知错误', }, }), }, ], 错误：正确， }; } } ）；服务器.注册工具( 'ucp_get_checkout', { title: '获取结帐会话', 描述：'通过 ID 检索现有的结账会话。返回当前状态，包括状态、行项目、总计和消息。', 输入架构：{ checkout_id: z.string().describe('结帐会话 ID'), }, }, 异步 ({ checkout_id }) => { const checkout = 等待 getCheckout(checkout_id); 如果（！结帐）{ 返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 错误：{ 代码：'checkout_not_found'，消息：“未找到结帐会话 ${checkout_id}”， }, }), }, ], 错误：正确， }; } 返回{ 内容：[ { 类型：'文本'，文本： JSON.stringify(checkout, null, 2), }, ], }; } ）；服务器.注册工具( 'ucp_update_checkout', { title: '更新结帐会话', 描述：'更新现有的结帐会话。可以修改订单项、买家信息、履行选择或折扣代码。', 输入架构：{ checkout_id: z.string().describe('结帐会话 ID'), line_items: z.array( z. 对象({ id: z.string(), 名称： z.string(), 数量：z.number().int().positive(), 单位价格：z.number().int(), 总价格： z.number().int(), 货币：z.string().length(3), }) ).可选().describe('更新的订单项(替换现有的)'), 买家：z.object({ 电子邮件：z.string().email().可选()，电话：z.string().可选()，名称：z.string().可选()， }).可选().describe('更新的买家信息(与现有的合并)'), 履行： z.object({ selected_option_id: z.string().Optional().describe('所选履行选项的 ID'), 目的地： z.object({ 地址行1: z.string(), 地址行2：z.string().可选()，城市: z.string(), 状态：z.string().可选()，邮政编码: z.string(), 国家: z.string().length(2), }).可选().describe('送货目的地地址'), }).可选().describe('配送选择（如果启用了配送扩展）'), discount_codes: z.array(z.string()).optional().describe('要应用的折扣代码（如果启用折扣扩展）'), platform_profile_url: z.string().url().Optional().describe('用于能力协商的平台配置文件 URL'), }, }, 异步（{ checkout_id，line_items，买家，履行，discount_codes，platform_profile_url }）=> { 尝试{ const 协商 = 等待协商能力(platform_profile_url); const checkout = 等待 updateCheckout( 结帐_id， { line_items, 买家 }, 谈判能力）；如果（！结帐）{ 返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 错误：{ 代码：'checkout_not_found'，消息：“未找到结帐会话 ${checkout_id}”， }, }), }, ], 错误：正确， }; } 返回{ 内容：[ { 类型：'文本'，文本： JSON.stringify(checkout, null, 2), }, ], }; } 捕获（错误）{ 返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 错误：{ 代码：'checkout_update_failed'，消息：错误实例错误？ error.message : '未知错误', }, }), }, ], 错误：正确， }; } } ）；服务器.注册工具( 'ucp_complete_checkout', { title: '完成结账', 描述：'通过付款完成结帐会话。结账必须处于ready_for_complete状态。返回已完成的结帐或错误消息。', 输入架构：{ checkout_id: z.string().describe('结帐会话 ID'), payment_data: z.object({ handler_id: z.string().describe('付款处理程序 ID（必须与 checkout. payment.handlers 中的一个匹配）'), token: z.string().optional().describe('来自标记化处理程序的支付令牌'), 工具：z.record(z.unknown()).可选().describe('支付工具数据'), }).describe('来自所选付款处理程序的付款数据'), platform_profile_url: z.string().url().optional().describe('平台配置文件 URL'), }, }, 异步 ({ checkout_id, payment_data, platform_profile_url }) => { 尝试{ const 协商 = 等待协商能力(platform_profile_url); const checkout = 等待完成Checkout( 结帐_id，付款数据，谈判能力）；如果（！结帐）{ 返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 错误：{ 代码：'checkout_not_found'，消息：“未找到结帐会话 ${checkout_id}”， }, }), }, ], 错误：正确， }; } 返回{ 内容：[ { 类型：'文本'，文本： JSON.stringify(checkout, null, 2), }, ], }; } 捕获（错误）{ 返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 错误：{ 代码：'checkout_completion_failed'，消息：错误实例错误？ error.message : '未知错误', }, }), }, ], 错误：正确， }; } } ）； // ============================================================================= // 履行扩展工具（如果启用） // ============================================================================= if (config.capability.extensions.includes('dev.ucp.shopping.fulfillment')) { 服务器.注册工具( 'ucp_get_fulfillment_options', { 标题：“获取履行选项”，描述：“获取可用的结帐履行/运输选项。需要目标地址。', 输入架构：{ checkout_id: z.string().describe('结帐会话 ID'), 目的地： z.object({ 地址行1: z.string(), 地址行2：z.string().可选()，城市: z.string(), 状态：z.string().可选()，邮政编码: z.string(), 国家： z.string().length(2).describe('ISO 3166-1 alpha-2 国家代码'), }).describe('运送目的地'), }, }, 异步 ({ checkout_id, 目的地 }) => { // 实现将调用履行处理程序返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 结帐_id，目的地, 选项：[ { id: '标准', 名称：“标准运输”，描述：“5-7 个工作日”，价格：599，货币：'美元'， }, { id: '快递', name: '快递', 描述：“2-3 个工作日”，价格：1299，货币：'美元'， }, ], }, 空, 2), }, ], }; } ）； } // ============================================================================= // 折扣扩展工具（如果启用） // ============================================================================= if (config.capability.extensions.includes('dev.ucp.shopping.discount')) { 服务器.注册工具( 'ucp_validate_discount', { title: '验证折扣代码', 描述：'在申请结帐之前验证折扣代码。返回折扣详情或拒绝原因。', 输入架构：{ checkout_id: z.string().describe('结帐会话 ID'), code: z.string().describe('要验证的折扣代码'), }, }, 异步 ({ checkout_id, 代码 }) => { // 实现将调用折扣处理程序返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 有效：真实，代码，折扣：{ 类型：'百分比'，值：10，描述：“订单 10% 折扣”， }, }, 空, 2), }, ], }; } ）； } // ============================================================================= // 支付处理工具 // ============================================================================= 服务器.注册工具( 'ucp_get_ payment_handlers', { 标题：“获取付款处理程序”，描述：'获取结帐会话可用的付款处理程序。用它来确定如何收集付款信息。', 输入架构：{ checkout_id: z.string().describe('结帐会话 ID'), }, }, 异步 ({ checkout_id }) => { const checkout = 等待 getCheckout(checkout_id); 如果（！结帐）{ 返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 错误：{ 代码：'checkout_not_found'，消息：“未找到结帐会话 ${checkout_id}”， }, }), }, ], 错误：正确， }; } 返回{ 内容：[ { 类型：'文本'，文本：JSON.stringify({ 结帐_id，应付金额：结帐.付款.应付金额，货币：结帐.付款.货币，处理程序：checkout. payment.handlers， }, 空, 2), }, ], }; } ）； }, { // 服务器元数据 name: 'ucp-购物', 版本：config.ucp_version， }, { // 处理程序选项基本路径: '/api/mcp', 最大持续时间：60， verboseLogs: process.env.NODE_ENV === '开发', } ）；导出 { 处理程序为 GET，处理程序为 POST }; #### lib/ucp/transports/mcp-tools.ts /** * UCP MCP 工具定义 * MCP传输的可重用工具模式 * 由 /ucp 脚手架生成 */ 从 'zod' 导入 { z }； // 常用模式导出 const LineItemSchema = z.object({ id: z.string().可选(), 名称： z.string(), 数量：z.number().int().positive(), 单位价格：z.number().int(), 总价格： z.number().int(), 货币：z.string().length(3), }); 导出 const BuyerSchema = z.object({ 电子邮件：z.string().email().可选()，电话：z.string().可选()，名称：z.string().可选()， }); 导出 const AddressSchema = z.object({ 地址行1: z.string(), 地址行2：z.string().可选()，城市: z.string(), 状态：z.string().可选()，邮政编码: z.string(), 国家: z.string().length(2), }); 导出 const PaymentDataSchema = z.object({ handler_id: z.string(), 令牌：z.string().可选()，仪器：z.record(z.unknown()).可选()， }); // 文档的工具定义导出常量 UCP_MCP_TOOLS = { ucp_get_profile: { 描述：“获取 UCP 发现配置文件”，输入：{}， }, ucp_create_checkout：{ 描述: '创建一个新的结账会话', 输入：{ line_items: '行项目数组（必需）', 货币：'ISO 4217 货币代码（必需）'， Buyer: '买家信息（可选）', platform_profile_url: '平台 UCP 配置文件 URL（可选）', }, }, ucp_get_checkout：{ 描述: '通过 ID 获取结帐会话', 输入：{ checkout_id: '结账会话 ID（必填）', }, }, ucp_update_checkout：{ 描述：“更新结帐会话”，输入：{ checkout_id: '结账会话 ID（必填）', line_items: '更新的订单项（可选）', 买家：'更新的买家信息（可选）'，履行：“履行选择（可选）”， discount_codes: '要应用的折扣代码（可选）', }, }, ucp_complete_checkout：{ 描述：“付款完成结账”，输入：{ checkout_id: '结账会话 ID（必填）', payment_data: '付款处理程序数据（必需）', }, }, ucp_get_fulfillment_options：{ 描述：“获取运输选项（履行延期）”，输入：{ checkout_id: '结账会话 ID（必填）', 目的地：'送货地址（必填）'， }, }, ucp_validate_discount：{ 描述：“验证折扣代码（折扣扩展）”，输入：{ checkout_id: '结账会话 ID（必填）', code: '折扣码（必填）', }, }, ucp_get_ payment_handlers：{ 描述：“获取可用的付款处理程序”，输入：{ checkout_id: '结账会话 ID（必填）', }, }, 作为常量； ** ** ## Vercel 部署 ### 部署配置 #### vercel.json { “框架”：“nextjs”， “地区”：[“iad1”]， “功能”：{ “应用程序/api/mcp/[传输]/route.ts”：{ “最大持续时间”：60 }, “应用程序/api/ucp/**/*.ts”：{ “最大持续时间”：30 } }, “标题”：[ { "来源": "/.well-known/ucp", “标题”：[ { "key": "缓存控制", "value": "公开，最大年龄=3600" }, { "key": "内容类型", “值”：“应用程序/json” } ] } ] } #### 环境变量在 Vercel 仪表板 → 设置 → 环境变量中设置这些：变量|必填|描述 ---|---|--- `UCP_DOMAIN` |是的 |生产域（例如“shop.example.com”） `UCP_SIGNING_KEY` |如果 AP2 | JWS 签名密钥（PEM 或 JWK） `STRIPE_SECRET_KEY` |如果条纹| Stripe API 密钥 #### next.config.js（MCP 优化） /** @type {import('next').NextConfig} */ 常量 nextConfig = { // mcp-handler 流需要实验：{ 服务器操作：{ bodySizeLimit: '2mb', }, }, // 确保 MCP 的标头正确异步标头() { 返回[ { 来源：'/api/mcp/:路径*'，标题：[ { key: 'Access-Control-Allow-Origin', value: '*' }, { key: 'Access-Control-Allow-Methods', value: 'GET、POST、OPTIONS' }, { key: 'Access-Control-Allow-Headers', value: '内容类型，授权' }, ], }, ]; }, // MCP 流响应所需异步重写() { 返回[]； }, }; module.exports = nextConfig; ### MCP 客户端配置 #### 对于 Claude 桌面/光标/风帆 **选项 1：直接 HTTP（如果客户端支持流 HTTP）** 添加到 MCP 客户端配置： { “mcp服务器”：{ “ucp 购物”：{ “url”：“https://your-domain.vercel.app/api/mcp” } } } **选项 2：通过 mcp-remote 网桥（仅适用于 stdio 客户端）** { “mcp服务器”：{ “ucp 购物”：{ “命令”：“npx”， “args”：[“-y”，“mcp-remote”，“https://your-domain.vercel.app/api/mcp”] } } } ### 测试 MCP 部署 #### 脚本/test-mcp.mjs #!/usr/bin/env 节点 /** * MCP服务器测试脚本 * 用法：节点脚本/test-mcp.mjs [部署-url] */ constdeploymentUrl = process.argv[2] || 'http://localhost:3000'; 异步函数 testMcpServer() { console.log(`正在 ${deploymentUrl}/api/mcp\n 处测试 MCP 服务器`); // 测试 1：获取个人资料 console.log('1.测试 ucp_get_profile...'); const profileResponse = wait fetch(`${deploymentUrl}/api/mcp`, { 方法：'POST'， headers: { 'Content-Type': 'application/json' }, 正文：JSON.stringify({ jsonrpc: '2.0', 编号: 1, 方法：'工具/调用'，参数：{ 名称：'ucp_get_profile'，参数：{}， }, }), }); const profileResult = 等待 profileResponse.json(); console.log('个人资料：', profileResult.result ? '确定' : '失败'); // 测试 2：创建结账 console.log('2.测试 ucp_create_checkout...'); const createResponse = wait fetch(`${deploymentUrl}/api/mcp`, { 方法：'POST'， headers: { 'Content-Type': 'application/json' }, 正文：JSON.stringify({ jsonrpc: '2.0', 编号: 2, 方法：'工具/调用'，参数：{ 名称：'ucp_create_checkout'，参数：{ 行项目：[ { name: '测试产品', 数量: 1, 单价：1000，总价：1000，货币：'美元'， }, ], 货币：'美元'， }, }, }), }); const createResult =等待createResponse.json(); console.log('创建：', createResult.result ? '确定' : '失败'); // 解析结帐ID以供后续测试 if (createResult.result?.content?.[0]?.text) { const checkout = JSON.parse(createResult.result.content[0].text); console.log(` 结账 ID：${checkout.id}`); console.log(` 状态：${checkout.status}`); // 测试 3：获取结账 console.log('3.测试 ucp_get_checkout...'); const getResponse = wait fetch(`${deploymentUrl}/api/mcp`, { 方法：'POST'， headers: { 'Content-Type': 'application/json' }, 正文：JSON.stringify({ jsonrpc: '2.0', 编号: 3, 方法：'工具/调用'，参数：{ 名称：'ucp_get_checkout'，参数：{ checkout_id: checkout.id }, }, }), }); const getResult = 等待 getResponse.json(); console.log('获取：', getResult.result ? '确定' : '失败'); } console.log('\nMCP 服务器测试已完成。'); } testMcpServer().catch(console.error); ### Vercel 部署清单在使用 Vercel 部署运行“/ucpscaffold”时，验证： * 使用函数超时创建的 `vercel.json` * 记录环境变量 * 针对 MCP 流式传输更新了“next.config.js” * MCP 路由位于 `app/api/mcp/[transport]/route.ts` * 测试脚本位于 `scripts/test-mcp.mjs` * `.env.example` 更新了所需的变量 ### 部署后验证部署到 Vercel 后： 1. **检查发现配置文件：** 卷曲 https://your-domain.vercel.app/.well-known/ucp | jq . 2. **测试MCP端点：** 节点脚本/test-mcp.mjs https://your-domain.vercel.app 3. **配置 MCP 客户端：** 将服务器添加到 Claude Desktop、Cursor 或您首选的 MCP 客户端。 4. **在客户端中验证：** 要求 AI“列出可用的 UCP 工具”——它应该显示结帐工具。 ** ** ### 后一代的步骤 #### 步骤 4：更新配置生成后，更新`ucp.config.json`： * 将所有创建的文件添加到 ` generated_files` 数组中 * 更新 `scaffold_depth` 以反映生成的内容 #### 步骤 5：输出摘要 UCP 支架完整 ===================== 生成的文件：创建 lib/ucp/types/checkout.ts 创建 lib/ucp/types/index.ts 创建 lib/ucp/schemas/checkout.ts 创建 lib/ucp/profile.ts 创建 lib/ucp/negotiation.ts 创建 lib/ucp/response.ts 创建 lib/ucp/handlers/checkout.ts 创建 app/.wellknown/ucp/route.ts 创建 app/api/ucp/checkout/route.ts 创建 app/api/ucp/checkout/[id]/route.ts MCP 传输（如果启用）：创建 app/api/mcp/[transport]/route.ts 创建 lib/ucp/transports/mcp-tools.ts 维塞尔部署：创建 vercel.json 创建脚本/test-mcp.mjs 修改next.config.js 安装的依赖项：佐德、何塞、uuid mcp-handler、@modelcontextprotocol/sdk（如果启用了 MCP）后续步骤： 1.审查生成的代码并定制业务逻辑 2.在Vercel仪表板中设置环境变量 3. 部署：vercel --prod 4. 运行 /ucp profile 以验证发现配置文件 5. 运行 /ucp test 生成单元测试 6. 运行 /ucp validate 检查合规性 7. 使用部署 URL 配置 MCP 客户端 ** ** ## 子命令：验证 ### 触发器用户运行“/ucp validate” ### 目的根据 UCP JSON 架构验证实施。 ### 先决条件 * 实现必须存在（首先运行`/ucpscaffold`） * 规格必须可用 ### 程序 #### 第 1 步：加载架构从规范中读取 JSON 模式： * `spec/schemas/shopping/checkout.json` * `spec/schemas/shopping/fulfillment.json` * `spec/schemas/shopping/discount.json` * `spec/discovery/profile_schema.json` #### 步骤 2：验证发现配置文件 * 向 `/.wellknown/ucp` 路由发出请求（或直接读取文件） * 根据 `profile_schema.json` 进行验证 #### 步骤 3：验证响应形状对于每个已实现的端点： * 生成样品请求 * 执行处理程序（模拟模式） * 根据模式验证响应 #### 步骤 4：检查协议要求验证： * 所有响应都包含 `ucp` 对象 * 状态值是有效的枚举值 * 金额为整数（小单位） * 日期采用 RFC 3339 格式 * 链接是绝对 HTTPS URL * 功能名称遵循反向 DNS 格式 #### 步骤 5：输出报告 UCP验证报告 ===================== 发现简介：通过 ✓ 架构有效 ✓ 存在必填字段 ✓ 服务定义有效 ✓ 可访问的功能规格结帐端点： POST /api/ucp/结账 ✓ 响应模式有效 ✓ UCP 元数据存在 ✓ 状态枚举有效获取 /api/ucp/checkout/[id] ✓ 响应模式有效 ✓ 幂等补丁 /api/ucp/checkout/[id] ✓ 响应模式有效 ✓ 部分更新有效 POST /api/ucp/checkout/[id]（完整） ✓ 响应模式有效 ✓ 状态转换正确协议要求： ✓ 小单位的金额 ✓ RFC 3339 中的日期 ✓ HTTPS 链接 ✓ 反向 DNS 功能名称总体：通过（24/24 检查） ** ** ## 子命令：profile ### 触发器用户运行“/ucp profile” ### 目的生成并显示“/.wellknown/ucp”发现配置文件 JSON。 ### 先决条件 * 配置必须存在 ### 程序 #### 第 1 步：生成配置文件使用“lib/ucp/profile.ts”中的“generateProfile()”函数（如果尚未搭建，则生成内联）。 #### 第 2 步：显示个人资料输出格式化的 JSON： { “ucp”：{ “版本”：“2026-01-11”， “服务”：{ “dev.ucp.shopping”：{ “版本”：“2026-01-11”， “规格”：“https://ucp.dev/spec/services/shopping”， “休息”：{ “模式”：“https://ucp.dev/spec/services/shopping/rest.openapi.json”， “端点”：“https://shop.example.com/api/ucp” } } }, “能力”：[ { "名称": "dev.ucp.shopping.checkout", “版本”：“2026-01-11”， “规格”：“https://ucp.dev/spec/capability/checkout”， “模式”：“https://ucp.dev/spec/schemas/shopping/checkout.json” } ] } } #### 步骤 3：提供写入文件问：“将其写入`public/.well-known/ucp`以进行静态服务，还是保留为动态路由？” 如果静态： * 创建`public/.wellknown/ucp`（无扩展名，JSON内容） * 注意：无扩展名文件可能需要 Next.js 配置 ** ** ## 子命令：测试 ### 触发器用户运行“/ucp test” ### 目的为 UCP 处理程序生成单元测试。 ### 先决条件 * 实现必须存在 * 检测到测试框架（Jest、Vitest 等） ### 程序 #### 步骤 1：检测测试框架寻找： * `jest.config.js` / `jest.config.ts` → 玩笑 * `vitest.config.js` / `vitest.config.ts` → Vitest * `package.json`测试脚本提示 #### 步骤 2：生成测试文件对于每个处理程序，生成相应的测试文件。 #### 示例：lib/ucp/handlers/**tests** /checkout.test.ts /** * UCP 结账处理程序测试 * 由/ucp测试生成 */ 导入 { 描述，它，期望，beforeEach } from 'vitest'; // 或者开玩笑导入{ 创建结账，结账，更新结账，完成结账， } 来自 '../checkout'; 描述（'UCP结帐处理程序'，（）=> { 常量有效请求 = { 行项目：[ { id: 'item_1', name: '测试产品', 数量: 1, 单价：1000，总价：1000，货币：'美元'， }, ], 货币：'美元'， }; 描述('createCheckout', () => { it('使用有效请求创建结账', async () => { const checkout = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); 期望（checkout.id）.toBeDefined（）； Expect(checkout.status).toBe('不完整'); Expect(checkout.currency).toBe('美元'); 期望(checkout.line_items).toHaveLength(1); 期望(checkout.ucp.version).toBeDefined(); 期望（checkout.ucp.capability）.toContain（'dev.ucp.shopping.checkout'）; }); it('正确计算总数', async () => { const checkout = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); 期望(checkout.totals.subtotal).toBe(1000); 期望(checkout.totals.grand_total).toBeGreaterThanOrEqual(checkout.totals.subtotal); }); it('设置过期时间', async () => { const checkout = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); 期望(checkout.expires_at).toBeDefined(); const expiresAt = new Date(checkout.expires_at); Expect(expiresAt.getTime()).toBeGreaterThan(Date.now()); }); it('包含必需的链接', async () => { const checkout = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); 期望(checkout.links.self).toContain(checkout.id); 期望（checkout.links.privacy_policy）.toBeDefined（）；期望（checkout.links.terms_of_service）.toBeDefined（）； }); }); 描述('getCheckout', () => { it('检索现有结账', async () => { const 创建 = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); const 检索 = 等待 getCheckout(created.id); 期望（检索）.toEqual（创建）； }); it('对于不存在的结帐返回 null', async () => { const 检索=等待 getCheckout('不存在的 id'); 期望（检索）.toBeNull（）； }); }); 描述（'updateCheckout'，（）=> { it('更新订单项', async () => { const 创建 = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); 常量更新 = 等待 updateCheckout( 创建.id, { 行项目：[ { ...validRequest.line_items[0]，数量：2，total_price：2000 }， ], }, ['dev.ucp.shopping.checkout'] ）；期望（更新？.totals.subtotal）.toBe（2000）; }); it('更新买家信息', async () => { const 创建 = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); 常量更新 = 等待 updateCheckout( 创建.id, { 买家：{ 电子邮件：'test@example.com' } }, ['dev.ucp.shopping.checkout'] ）； Expect(更新?.买家?.email).toBe('test@example.com'); }); it('满足要求时转换到ready_for_complete', async () => { const 创建 = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); 常量更新 = 等待 updateCheckout( 创建.id, { 买家：{ 电子邮件：'test@example.com' } }, ['dev.ucp.shopping.checkout'] ）；期望（更新？.status）.toBe（'ready_for_complete'）; }); }); 描述('状态生命周期', () => { it('遵循正确的状态转换', async () => { // 未完成->ready_for_complete->complete_in_progress->完成 const checkout = 等待 createCheckout(validRequest, { 功能：['dev.ucp.shopping.checkout']， }); Expect(checkout.status).toBe('不完整'); 常量更新 = 等待 updateCheckout( 结账.id, { 买家：{ 电子邮件：'test@example.com' } }, ['dev.ucp.shopping.checkout'] ）；期望（更新？.status）.toBe（'ready_for_complete'）; }); }); }); #### 步骤 3：输出摘要生成的测试文件：创建 lib/ucp/handlers/__tests__/checkout.test.ts 创建 lib/ucp/handlers/__tests__/fulfillment.test.ts 创建 lib/ucp/__tests__/negotiation.test.ts 创建 lib/ucp/__tests__/profile.test.ts 创建应用程序/api/ucp/__tests__/checkout.route.test.ts 使用以下命令运行测试：npm test（或bun test） ** ** ## 子命令：docs ### 触发器用户运行“/ucp docs” ### 目的生成 UCP 集成的内部文档。 ### 先决条件 * 配置必须存在 * 理想情况下存在实施 ### 程序 #### 第 1 步：收集信息 * 读取功能、传输、处理程序的配置 * 扫描生成的文件 * 阅读规格文件以获得准确的描述 #### 第 2 步：生成文档创建“docs/ucp-integration.md”： # UCP 集成文档 ## 概述此代码库实现通用商务协议 (UCP) 版本 {version}。 **角色：** {角色} **域名：** {域名} **交通：** {交通} ## 能力 ### 核心 - `dev.ucp.shopping.checkout` - 结账会话管理 ### 扩展 {列出带有描述的扩展} ## API 端点 ### 发现 - `GET /.well-known/ucp` - UCP 发现配置文件 ### 结账（休息） - `POST /api/ucp/checkout` - 创建结帐会话 - `GET /api/ucp/checkout/:id` - 获取结账会话 - `PATCH /api/ucp/checkout/:id` - 更新结帐会话 - `POST /api/ucp/checkout/:id` (action=complete) - 完成结帐 ## 结账状态生命周期不完整 → 需要升级 → 准备完成 → 完成中 → 已完成 ↘ 已取消 ## 支付处理程序 {列出已配置的处理程序以及集成说明} ## 能力协商平台通过“UCP-Agent”标头发送他们的个人资料 URL： UCP-Agent：配置文件=“” 业务获取平台配置文件，计算能力交集，并在每个响应中包含协商的功能。 ## 配置配置存储在项目根目录的“ucp.config.json”中。 ## 文件 {列出生成的文件及其描述} ## 测试运行单元测试： ````bash npm测试 ## 验证根据 UCP 模式验证实施： # 使用技能 /ucp 验证 #### 第三步：输出生成的文档：CREATE docs/ucp-integration.md 文档包括： * 能力概述 * API端点参考 * 状态生命周期图 * 配置指南 * 文件清单 --- ## 错误处理 ### 交互式错误解决当遇到不明确的情况时，总是询问用户： 1. **Missing config:** “未找到配置文件。先运行 /ucp init，还是手动创建？” 2. **规范获取失败：**“无法克隆 UCP 规范。检查网络/身份验证。重试、使用本地路径还是中止？” 3. **冲突文件：**“文件 {path} 已存在。覆盖、合并、跳过或中止？” 4. **未知角色：**“角色‘{role}’无法识别。您的意思是：业务、平台、 payment_provider 或 host_embedded？” 5. **验证失败：**“{file} 的架构验证失败。显示详细信息、尝试修复还是跳过？” ### 错误代码 |代码|意义|分辨率| |------|---------|------------| | `CONFIG_NOT_FOUND` | ucp.config.json 丢失 |运行 /ucp init | | `SPEC_NOT_FOUND` |规格存储库不可用 |检查网络，手动克隆 | | `INVALID_ROLE` |配置中的未知角色 |修复配置 | | `SCHEMA_INVALID` |响应与架构不匹配 |查看生成的代码 | | `EDGE_RUNTIME_DETECTED` |使用的边缘运行时 |更改为nodejs/bun | --- ## Next.js 约定 ### 文件结构 project/ ├── app/ │ ├── .well-known/ │ │ └── ucp/ │ │ └──route.ts # 发现配置文件 │ └── api/ │ └── ucp/ │ ├── checkout/ │ │ ├──route.ts # POST create │ │ └── [id]/ │ │ └──route.ts # GET、PATCH、POST 完成 │ ├── mcp/ │ │ └──route.ts # MCP 传输（如果启用） │ └── a2a/ │ └──route.ts # A2A 传输（如果启用） ├── lib/ │ └── ucp/ │ ├── types/ │ │ ├── checkout.ts │ │ └──index.ts │ ├── schemas/ │ │ └── checkout.ts │ ├── handlers/ │ │ ├── checkout.ts │ │ ├──fulfillment.ts │ │ ├──discount.ts │ │ └── payment.ts │ ├── 运输/ │ │ └── mcp.ts │ ├── profile.ts │ ├── negotiation.ts │ └── response.ts ├── docs/ │ └── ucp-integration.md ├── ucp.config.json └── .ucp-spec/ # 克隆规范（gitignored） ### 运行时声明每个路由文件必须包括： ``打字稿导出常量运行时='nodejs'; // 不支持边缘运行时或者对于面包：导出常量运行时='nodejs'; // Bun 兼容的 Node.js 运行时 ### 应用程序路由器模式 * 使用路由处理程序（`route.ts`）而不是 API 路由（`pages/api`） * 使用“next/server”中的“NextRequest”和“NextResponse” * 等待 `request.json()` 进行正文解析 * 使用“request.headers.get()”进行标头访问 ** ** ## 凭证处理 ### 所需的密钥 * **AP2 授权：** JWS 签名密钥 (ES256) * **Webhook 签名：** JWS 签名密钥 (ES256) * **身份链接：** OAuth 客户端凭据 ### 提示输入凭据当某项功能需要凭据时，请询问： > “AP2 强制要求需要 JWS 签名密钥（建议使用 ES256）。您是否有现有的密钥对，或者我应该解释一下如何生成密钥对？” 如果用户需要生成指令： # 生成ES256密钥对 openssl ecparam -genkey -name prime256v1 -noout -out private.pem openssl ec -in private.pem -pubout -out public.pem # 转换为JWK格式（使用jose库或在线工具） ### 存储凭据应存储在环境变量中，而不是配置中： * `UCP_SIGNING_KEY` \- 私钥（PEM 或 JWK） * `UCP_OAUTH_CLIENT_ID` \- OAuth 客户端 ID * `UCP_OAUTH_CLIENT_SECRET` \- OAuth 客户端密钥 ** ** ## 版本历史 * **2026-01-11**：初始 UCP 规范版本 * **技能 v1.0** ：初始技能发布 ** ** ## 参考文献 * UCP 规范存储库： * UCP 文档：请参阅“./ucp/docs/”或“./.ucp-spec/docs/” * JSON 架构草案 2020-12 * RFC 8941（结构化字段值） * RFC 3339（日期/时间格式） * RFC 8785（JSON 规范化方案）

UCP

包含技能