人机协同购物新范式｜Shopify 开源 UCP‑CLI，AI 智能体选品下单，人工接管支付

编者摘要：shopify/ucp‑cli是 Shopify 基于 UCP 通用商业协议打造、面向 AI Agent 的电商购物命令行工具，实现跨商户完整购物链路。它支持全局统一商品目录检索百万商户商品，也可限定单商户执行购物车创建更新、结账、订单查询，核心特性为运行时 Schema 动态内省，Agent 直接读取商户实时接口元数据组装请求，摆脱静态文档依赖。

工具内置 Agent 技能包 SKILL.md，兼容 agentskills.io，每条指令返回结构化 CTA 下一步指引，降低 Agent 业务逻辑负担。当 AI 无法处理登录、支付确认等场景，通过 escalation 移交钩子跳转浏览器交由人工完成。支持 dry‑run 预校验、JMESPath 结果投影、多维度请求头配置、多协议版本 Profile 管理。

目录查询无需鉴权，结账流程需要 Shopify Catalog JWT。支持环境变量配置、代理与 TLS 调试，可直接在终端使用，也可封装为 MCP 工具供大模型调用。其核心思想是 AI 负责检索加购，人工处理高敏感确认环节，实现人机协同电商。

10 个关键问题 Q&A

项目概述

@shopify/ucp‑cli是面向AI 智能体 (Agent)的购物能力命令行工具，基于 UCP（Universal‑Commerce‑Protocol，通用商业协议）构建，让 AI Agent 可以完成商品搜索、创建购物车、结账、订单查询整套电商购物链路。

核心定位：Agent‑first AI 购物技能，输出结构化 JSON，支持 Schema 动态内省，不需要依赖静态文档；支持多商户、全局商品目录，遇到 AI 无法处理的场景支持优雅移交浏览器给人工操作。

核心能力清单

1. 跨数百万商户全局商品目录搜索商品
2. 在任意支持 UCP 协议的商户创建购物车、修改购物车
3. 结账流程，AI 无法处理时触发移交（escalation）跳转浏览器
4. 购买完成后追踪查询订单
5. 实时 Schema 内省，Agent 根据商户实时暴露的 Schema 组装请求载荷，不用写死静态接口文档
6. 内置 Agent 技能包 SKILL.md，兼容 agentskills.io 规范

快速上手（60 秒入门）

# 全局安装
npm install -g @shopify/ucp-cli

# 注入Agent技能定义文件SKILL.md
ucp skills add

# 初始化一个购物者配置profile
ucp profile init --name shopper

1️⃣ 搜索商品

ucp catalog search \
  --set /query='keychron b1 pro' \
  --set /context/intent='looking for great mechanical keyboard' \
  --set /context/address_country=US \
  --view :compact \
  --format md

• 不加 --business：使用全局统一商品目录，跨海量商户搜索
• 增加 --business <商户URL>：限定只在单个指定商户内搜索
• --view
  ：JMESPath 投影表达式，裁剪返回数据；:compact是内置别名视图
• --format md
  ：输出 markdown 表格

返回包含：商品标题、价格、币种、变体 ID、直接加购链接。

2️⃣ 创建购物车

ucp cart create --business https://keytron.myshopify.com \
  --set /line_items/0/item/id='gid://shopify/ProductVariant/41293818167385' \
  --set /line_items/0/quantity=1 \
  --set /context/address_country=US \
  --view 'result.{id: id, items: length(line_items), currency: currency, continue_url: continue_url}'

• 返回 cart.id 购物车 ID，后续更新购物车复用该 ID
• 可以通过 ucp cart update --input‑schema查询商户 Schema，获取购物车阶段运费预估能力

注意：全新添加的购物车行没有 line id；只有已经存在的行才有 line id，不要自己编造 ID。

3️⃣ 创建结账、移交处理、完成下单

部分结账流程需要用户手动输入信息、登录、校验，AI Agent 不能代为完成，此时触发escalation 移交钩子打开浏览器。

# macOS 设置移交钩子：自动打开浏览器
export UCP_ON_ESCALATION='jq -r .url | xargs open'

# 将购物车转为结账
ucp checkout create --business https://keytron.myshopify.com \
  --input '{"cart_id":"<cart_id from step 2>","line_items":[]}' \
  --view 'result.{id: id, status: status}'

# 更新结账：填写收货地址、选择配送方式
ucp checkout update <checkout_id>

# 完成结账
ucp checkout complete <checkout_id>

权限说明：Shopify 商户商品目录公开可读；结账操作需要 Catalog JWT，在 Shopify 开发者后台获取。

AI Agent 如何调用该技能

执行完 ucp skills add，工具会加载内置 SKILL.md，教会 Agent 完整购物工作流：

关键设计：实时 Schema 内省，不是静态文档

ucp discover --business <商户域名>                     # 查询商户支持哪些操作
ucp catalog search --input-schema --business <xxx>    # 查询catalog search入参schema
ucp cart update --input-schema --business <xxx>       # 查询购物车更新schema
ucp checkout update --input-schema --business <xxx>   # 查询结账更新schema

Agent 运行时动态拉取商户最新 Schema 组装请求，商户接口迭代升级，不需要同步更新 Agent 代码。

每个命令返回结果自带 cta（下一步行动建议）结构化字段，告诉 Agent 后续可以执行哪些命令，Agent 不需要记忆全部业务流程。

示例 CTA 片段：

{
  "description": "Cart saved. Ready to buy? ...",
  "commands": [
    {"command":"ucp checkout create ...","description":"convert this cart to a checkout"},
    {"command":"ucp cart update --input-schema ...","description":"inspect cart schema before requesting shipping estimates"}
  ]
}

核心概念详解

1. Profile（配置档案）

profile 存放 UCP 协议版本、Agent 身份配置文件。UCP 协议带时间版本号，商户每次请求校验协议版本。

# 创建绑定旧协议版本的profile
ucp profile init --name legacy --version 2026-04-08

# 使用指定profile执行命令
ucp discover shop.example.com --profile legacy

本地路径：~/.ucp/profiles/<name>/profile.json

• 可以把 agent profile 托管到公网 URL，商户会拉取该 URL 识别 Agent 身份；
• ucp doctor
  ：诊断本地配置与远端是否一致，检查 profile‑drift 配置漂移。

2. 三种入参方式，可以混合使用

1. 位置参数 <id>
   ：cart/get/update，checkout，order 等针对已有资源操作；创建类命令无位置参数。
2. --input '<json>|@file|-'
   ：完整请求体 JSON，可以读取文件 /stdin。
3. --set JSONPointer=value
   ：RFC6901 JSON 指针，增量修改字段；--set-string防止数字字符串被强制转数字；/-用于数组追加。

# 混合用法
ucp cart create --input '{"line_items":[]}' --set /context/address_country=US

3. 响应投影 --view

基于 JMESPath，对返回结果做数据裁剪过滤，不会重复请求网络。

• :alias
  加载工具内置视图；
• @file
  加载自定义本地 jmespath 文件；
• 内联表达式。 --view先执行，之后--format md/json渲染。

4. Escalation 移交钩子机制

触发条件：result.status === "requires_escalation"

鉴权类错误 (AUTH_REQUIRED 等) 不会触发钩子，返回结构化 CTA 交给 Agent 处理。

钩子接收 JSON 输入到 stdin，配置优先级：

1. 单次命令参数：--on‑escalation "shell cmd"
2. 环境变量：UCP_ON_ESCALATION（最常用）
3. 配置文件 ~/.ucp/config.yaml

示例：

# Linux：浏览器打开
export UCP_ON_ESCALATION='jq -r .url | xargs xdg-open'

# webhook推送通知
export UCP_ON_ESCALATION='curl -sX POST -H "Content‑Type: application/json" --data @- "$WEBHOOK_URL"'

5. Dry‑Run 预演

--dry‑run：组装、校验请求载荷，打印出要发送的报文，不发起真实网络请求，用于调试 cart/checkout 修改：

ucp cart update <id> --business https://xxx \
  --input '{...}' \
  --dry-run

6. 请求头自定义

优先级（低→高）：内置 UA → profile headers.json default → profile headers.json businesses [origin] → --header命令行参数 支持环境变量插值 ${ENV_VAR}，敏感密钥不会明文写配置文件。

ucp catalog search --header "Authorization: Bearer $TOKEN" --header "Trace‑Id: req‑123"

7. 环境变量总览

8. 代理与 TLS

兼容标准 curl 风格代理环境变量；TLS 检测代理（Zscaler 等）通过 Node CA 配置信任根证书。ucp doctor可以诊断代理配置。

本地开发

pnpm install
pnpm build
pnpm test          #单元测试
pnpm test:full     #单元+集成
pnpm lint
pnpm typecheck

# 开发模式全局软链接
pnpm build && pnpm link --global

调试：UCP_VERBOSE=1输出网络、缓存、discover 日志；--verbose参数。

关键架构要点总结

1. 商户（business）就是 URL
   工具自动拉取商户 UCP 元数据缓存，协商协议版本，屏蔽底层传输、能力协商、错误处理。
2. 两套工作域
• 全局目录：无--business，多商户商品检索；
• 指定商户：--business，购物车 / 结账 / 订单操作。
3. Agent 优先设计
   JSON IO、动态 schema 内省、CTA 下一步建议、移交钩子，把电商业务逻辑下沉 CLI，Agent 只做决策调用。
4. Schema 由商户全权控制
   商户自主演进接口，不需要同步升级 Agent/ucp‑cli 版本。
5. 移交机制是核心
   AI 做商品检索加购，人负责登录、支付确认，人机协同购物。