UCP Skill 是用于实现 Universal Commerce Protocol（UCP）的专家级实现助手，面向希望在 Next.js 电商项目中加入 UCP 支持的开发者。
核心原则
- 不使用 Edge runtime，仅使用 Node.js（默认）或 Bun（可选）运行时。
- 交互式错误处理：遇到歧义时询问用户如何继续。
- 配置驱动：所有决策持久化在 ucp.config.json 中。
- 以规范为依据：所有实现参考权威 UCP 规范。
- 遵循 Next.js 约定：代码组织使用 App Router 模式。
- 深度分析：使用 AST 解析和数据流追踪进行缺口检测。
规范仓库处理
查找位置优先级：先检查 ./ucp/（用户本地副本，按原样使用）；再检查 ./.ucp-spec/（此前克隆的规范，进行更新）；两者都不存在则全新克隆。
克隆命令： git clone --depth 1 https://github.com/Universal-Commerce-Protocol/ucp.git .ucp-spec
如果 HTTPS 失败，尝试 SSH： git clone --depth 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/。
规范文件按需读取，包括 docs/specification/ 下的 overview、checkout、checkout-rest、checkout-mcp、checkout-a2a、embedded-checkout、order、fulfillment、discount、buyer-consent、identity-linking、ap2-mandates、payment-handler-guide、tokenization-guide 等文档，以及 spec/services/、spec/handlers/、spec/schemas/、spec/discovery/ 下的 OpenAPI、OpenRPC 与 JSON Schema 文件。
配置文件
位置为项目根目录 ./ucp.config.json。主要字段包括 ucp_version（基于日期的规范版本）、roles（business、platform、payment_provider、host_embedded 中的一个或多个）、runtime（nodejs 或 bun）、capabilities.core 与 capabilities.extensions、transports（rest、mcp、a2a、embedded）与 transport_priority、payment_handlers、features（ap2_mandates、identity_linking、multi_destination_fulfillment）、domain（承载 /.well-known/ucp 的业务域名）、existing_apis、policy_urls（privacy、terms、refunds、shipping）、scaffold_depth（types、scaffolding、full）、generated_files、answers、deployment（platform、region、mcp.enabled、mcp.max_duration）等。
子命令
无参数 /ucp：显示帮助并列出全部可用子命令与典型工作流：/ucp init → /ucp consult → /ucp plan → /ucp scaffold → /ucp profile → /ucp test → /ucp validate。
/ucp init：在项目中引导 UCP——检查或克隆规范仓库并加入 .gitignore；检查现有配置并询问覆盖、合并或中止；询问四个基本问题（实现哪些角色、运行时、业务域名、启动时需要哪些传输）；创建 ./ucp.config.json；输出就绪信息与后续建议。若用户提到 Edge，会提示 UCP 实现不支持 Edge runtime。若选择多个角色会给出不常见场景的警告。
/ucp consult：完整咨询，依次走完 12 个资格问题（角色、版本与能力/扩展、支付处理器、AP2 委托与签名密钥、履约与多目的地、折扣/买家同意/身份关联、现有结账与订单 API、必需政策 URL、结账端点的认证模型、订单 webhook 接收方与事件节奏、启动时是否需要 MCP/A2A/嵌入式结账、承载 /.well-known/ucp 的业务域名），更新配置并生成实现路线图。涉及能力包括核心 dev.ucp.shopping.checkout，以及 fulfillment、discount、buyer_consent、ap2_mandate、order、identity_linking 等扩展。
/ucp plan：生成详细的逐文件实现计划。检测现有代码结构（Next.js 版本、API 路由、lib/utils、类型与 schema、包管理器），按阶段列出创建与修改的文件，例如核心类型与 Zod schema、发现档案、REST 结账端点、履约扩展、折扣扩展、支付集成、订单 webhook、MCP 传输层，并列出需要安装的依赖（如 zod、jose）。计划保存在 answers.implementation_plan 中供脚手架参考。
/ucp gaps：基于 AST 解析与数据流追踪，对现有代码库与 UCP 要求进行深度差距分析，扫描 API 路由、结账相关文件、支付处理代码与 webhook 实现，输出差距报告，区分关键差距（如缺少发现档案、缺少 UCP 响应封装、缺少能力协商）与部分实现（如已有结账会话但不符合规范）。
其余子命令包括：/ucp scaffold 生成完整可运行的 UCP 实现；/ucp validate 依据 UCP schema 校验实现；/ucp profile 生成 /.well-known/ucp 发现档案；/ucp test 为 UCP 处理器生成单元测试；/ucp docs 生成内部文档。
适用场景为需要在 Next.js（App Router）电商项目中实现 UCP 的商家或平台侧开发者，可按角色实现结账、履约、折扣、订单、支付处理器与发现档案等能力，并从 REST 起步按优先级扩展到 MCP、A2A 或嵌入式结账。限制方面：不支持 Edge runtime，仅 Node.js 或 Bun；实现依赖规范仓库的可用性；多角色实现属于不常见场景会给出警告。其余更细的收费、平台、效果等信息暂未提供。